niram is a Blender 5.1 extension that receives iPhone ARKit facial capture over the network (from the Face Cap app, OSC/UDP) and writes the 52 ARKit blendshapes onto a character's facial shape keys in real time — live preview, recording, and punch-in retakes.
It is the face-mocap companion to
manekko (VIVE-tracker body mocap), and the
two share a 240-frame origin (a WAV cue fires at frame fps*10 = 240 @ 24 fps)
so body, face and audio line up.
Niramekko (にらめっこ) is a traditional Japanese children's game: two players stare at each other and pull funny faces, and the first one to laugh loses. The name fits a tool that is all about capturing faces and expressions. "niram" is just the short display name.
- Blender 5.1 or newer (developed and tested on Windows).
- An iPhone with the Face Cap app (by Bannaflak), on the same Wi-Fi / LAN as the PC.
- A character mesh whose shape keys are ARKit blendshapes — either a Character Creator 4 (CC4) export (auto-detected) or any mesh that carries ARKit-named / CC4-named facial morphs.
If you just want to use it:
- Download the latest
niramekko-x.y.z.zipfrom the Releases page. - In Blender 5.1+: Edit ▸ Preferences ▸ Add-ons ▸ Install from Disk… (the
dropdown at the top-right of the Add-ons list) and pick the
.zip. - Press N in the 3D Viewport to open the sidebar and select the niram tab.
(Building from source is only needed if you change the code — see Build below.)
- In the niram panel, pick the Face Mesh (the mesh whose shape keys should receive the capture). Leave it empty to auto-detect the CC4 body.
- In Face Cap on the iPhone, set Server IP & Port to this PC's LAN IP and
a port (default
9000). Face Cap's built-in default192.168.178.0is usually wrong for your network — use the PC's actual address. Allow inbound UDP through the firewall. - In niram, set the Port to match, optionally a Cue WAV, and the Smooth Frames count.
- Start / Stop — toggles the extension (opens/closes the UDP socket). While running and idle, your live face is mirrored onto the character so you can aim.
- Play — from the timeline cursor: advances frames (body + recorded face play from their baked actions) and fires the WAV cue at frame 240.
- Stop — stops playback/recording (the extension stays running).
- Rec — records the face onto the shape keys. Stopped → records from the cursor; playing → punch-in from the press frame. Press again to stop; the take's in/out boundaries are then batch-smoothed.
- Eyes only (gaze) — when ticked, Rec overwrites only the eye-gaze
blendshapes (
eyeLook*), leaving the rest of the take intact: re-do where the eyes look (e.g. a stray glance at the screen) without re-recording the whole face. Punch-in and the boundary crossfade still apply.
The capture/playback range follows the preview range when it is enabled, otherwise the scene frame range.
src/osc.py— stdlib UDP socket + tiny OSC parser, daemon thread keeps the latest 52/Wblendshape weights (latest-wins).src/facemap.py— ARKit → shape-key mapping (CC4 morph names by default); writes the chosen / body Key (secondary meshes follow via drivers), skipping driver-bound channels.src/ops.py— one modal operator owns the receiver + targets, one keyframe per scene frame; the panel buttons post requests it consumes.src/postproc.py— post-recording punch-in/out crossfade on the shape-key fcurves (scalar smoothstep blend).
See docs/face_cap_notes.md for the OSC protocol and mapping details.
Only needed if you modify the source:
blender --command extension build --source-dir . --output-dir dist
MIT — see LICENSE.
niram is an independent, unaffiliated project. Face Cap is by Bannaflak (Niels Jansson); ARKit is a trademark of Apple Inc.; Character Creator / CC4 are products of Reallusion. These names are used only to describe interoperability. No assets from those products are included.
Made with Claude Code.