/portrait          her animated portrait in a small window of its own (again closes it)
/portrait obs      the see-through URL for an OBS browser source

A window with her in it that follows what she's doing. She blinks and glances around, looks up and to the side while she thinks, and looks at you while you talk. Her ears twitch now and then and perk up when you start speaking. Her mouth moves with her actual voice: every sentence's loudness is sent to the page as it starts playing. Her mood shows as a smile, a blush or a frown. A failed tool gets a moment of spiral eyes, and a big jump in warmth gets a flustered ><.

It's served by the live monitor, so monitor.enabled has to be on. It opens as an app-style Chromium window (its own process, so /portrait can close it again), or in your normal browser if there's no Chromium. On Hyprland, float and pin it by title:

windowrulev2 = float, title:^(Luna)$
windowrulev2 = pin, title:^(Luna)$

She looks at the conversation. On Hyprland the live monitor checks twice a second where the portrait window and Luna's terminal are, and tells the page. She turns her head and eyes towards the terminal while you talk and while she answers, and drifts back to it when idle. Move either window and she follows. Anywhere that can't be worked out (another compositor, OBS, the terminal on another workspace) she looks straight ahead as before. If a model was rigged mirrored and looks the wrong way, set "flip_gaze": true in portrait.live2d.

Thinking is something you can watch. She looks up and away from you, to the side, then down for a moment as if weighing it, switches sides, and glances back at you now and then. Her eyes dart in small movements, her head follows further and wanders on its own, tilts towards the side she's looking, and her brow lifts a little. It's the same for the Live2D and the 3D portrait (portrait/viewer/look.js).

Page options: ?bg=transparent (OBS), ?frame=face (closer crop), ?frame=full (all of her, 3D models), ?debug=1 (test buttons for every reaction, including you: left / right / ahead to try the looking), ?demo=1 (acts out a conversation on its own).

./viewer.sh

It serves the portrait on its own (port 8793, so it works while Luna runs too) and opens the debug page. Everything is in the panel:

• model: everything in portrait/models
• view: bust, face or full body; hologram, see-through background, and a demo that acts out a conversation on a loop
• a button for every gesture, expression and reaction

h hides the panel. Picking a model there only previews it; Luna keeps the one she uses. With Luna running, http://127.0.0.1:8792/portrait/?debug=1 has the same panel.

Out of the box she's Luna's own model, the branded robot in portrait/models/luna/robot_default.vrm (made in VRoid Studio, ships with the repo). Drop a model into portrait/models/ (a Live2D model's folder, or a .vrm file) and switch to it from Luna:

/portrait models          list what's there, with the one in use marked
/portrait use 2           switch by number
/portrait use robot       or by any part of its name

The choice is saved to config.json, and an open portrait reloads with the new model straight away. A Live2D model straight out of its zip usually works as it is; add_live2d.py (below) tidies one up first if its file names are messy or its expressions aren't listed.

python portrait/add_live2d.py ~/Downloads/1_希格雯.rar --name sigewinne

That's the Sigewinne model from vtuber-nook, which is what the screenshot shows. On Fedora, opening the .rar needs sudo dnf install unrar (from RPM Fusion). 7z or bsdtar work too, or extract it in your file manager and pass the folder.

This copies the model into portrait/models/<name>/ with plain file names, registers any .exp3.json expressions the model3.json forgot to list, shrinks 8K textures to 4K (--texture 0 keeps them), and switches config.json to it. Restart Luna afterwards, then /portrait.

The standard Cubism parameters drive it: head angle, eyeballs, eye open/smile, mouth open and form, cheek, brows and breath. Ears are the model's own ear-physics parameters, nudged after physics runs, and they're found by name. Expressions are matched to roles by what they show (spiral eyes → confused, >< → flustered, tears → sad).

When a model needs any of that spelled out, put a luna.json in its folder. It travels with the model, so switching models switches the settings too:

{
    "credit": "Art: Koahri, Live2D: Medwok - https://booth.pm/en/items/4711410",
    "live2d": {
        "expressions": {"confused": "squeezed eyes", "flustered": "blush", "sad": "cry"},
        "ear_params": ["Param29", "Param31"],
        "crop": {"top": 0.04, "height": 0.78, "width": 0.8},
        "crop_face": {"top": 0.12, "height": 0.45, "width": 0.55}
    }
}

crop is the window's view of the model's canvas, as fractions: where it starts (top), how much of the height shows, and how much of the width has to fit across. The default suits a full-body model, cropped to the bust. A half-body model, whose canvas is already the bust, wants a bigger height and width. crop_face is the same for ?frame=face. credit is for you: free models usually ask to be credited, and this keeps the line with the model.

A model without a luna.json uses portrait.live2d from config.json, which is how older setups did it.

A model made in Cubism 5 (its .moc3 starts MOC3 then version 5) needs a recent Cubism Core. The CDN copy is always recent; a local copy from get_cubism_core.sh older than 2023 shows a blank page with "Unknown error" in the console. Run the script again to update it.

Most Live2D models hang their hair and ears off the head angles, and their clothes off the body angles, with breathing feeding both. So the portrait moves the body on its own instead of copying the head:

• Body: a slow sway of its own, a change of posture every half minute or so, leaning in while you talk, a little hop when she's pleased. The clothes physics swings with it.
• Breathing: a breath in that's quicker than the breath out, a little different each time, slower when it's late and quiet, and a top-up breath before she starts talking. Each breath also lifts the head and body slightly, so you can see it even on a model whose own breath parameter is subtle.
• Brows and eyes: worried when a reply came out unsure, one brow up when the grounding check flags a guess, furrowed when a tool fails, wide-eyed when you talk over her, softer when she's warm. One brow sits higher on the side she looks to while thinking. On Sigewinne the bangs hide much of the brows, so this mostly shows through the eyes.
• Talking and listening: small nods and brow lifts on her louder syllables, and an "mm-hm" nod every few seconds while you talk.
• Idle: after a quiet minute she looks around more, and now and then she stretches. Late at night her eyelids get heavier.

Two settings tune it, under portrait.live2d:

The ?debug=1 page has a button for every gesture and reaction, sliders for breath and motion (try values there, then put them in config.json), and a picker that holds any one of the model's parameters on a slider, named from its display file. That's the way to find out what an unlabelled parameter like Sigewinne's Param27 does.

Live2D's Cubism Core comes from Live2D's CDN. For offline use, run bash portrait/viewer/vendor/get_cubism_core.sh once. It's Live2D's code under their licence, so it's downloaded rather than shipped here. Models you add are gitignored. They're usually big and always someone else's: the Sigewinne model is marked personal use only, so check its Booth page before putting it on stream.

Any model, Live2D or VRM, can be shown as a hologram: tinted towards one colour, see-through, a glowing edge, scanlines rolling up, a faint flicker and a projector glow under her. Now and then the picture tears sideways for a moment, and it always does when a tool fails or you talk over her. She brightens a little while she talks.

It's a filter over the finished picture (portrait/viewer/hologram.js for Live2D, portrait/viewer/hologram3d.js for VRM), so blinking, talking, the hair and ear physics and everything else come through it unchanged.

Switch it with /holo (or /holo on, /holo off), or the hologram look row in the tools pane's Portrait group. Either one saves the choice and flips an open portrait straight away. ?holo=1 on the portrait address forces it for that page (the ?debug=1 page gets glitch and on/off buttons). The rest of the look is set in config.json:

"portrait": {
    "hologram": { "enabled": true, "tint": "#c37bff", "mix": 0.8,
                  "intensity": 1.0, "glitch": 1.0, "base": true }
}

It works in OBS too: with ?bg=transparent she floats over the stream as a projection. /holo and the tools pane switch it live there as well; &holo=1 or &holo=0 on the URL only sets how the page starts.

Point portrait.model at a .vrm and the same page renders it in 3D with three-vrm. Blink, the five mouth shapes, the mood expressions and look-at come from the VRM itself. Ears are nodes named like Ear_L, or listed in portrait.ear_bones. VRoid Studio exports VRM models that work as they are.

A 3D model moves more than her head. She waves, hugs, jumps, shrugs, and does small things on her own:

The full guide, with how it all works, is its own page: Gestures.

Each built-in gesture is a file in portrait/gestures/: wave.js, hug.js, and so on. A new file there is a new gesture, picked up on the next page load with nothing else to edit: it gets a button in the viewer, /portrait <name> plays it, and an about line offers it to her as a tag.

// portrait/gestures/hand_on_heart.js
import { fingers } from './_pose.js';

export default {
  about: "touched, grateful",      // offered to her as [hand_on_heart]
  dur: 3.0, fade: [0.5, 0.6],
  keys: [
    [0.0, { rightUpperArm: [0, 0.8, 1.15], rightLowerArm: [0, 2.15, -0.15], ...fingers('right', 0.2),
            '+head': [0.08, 0, 0.1] }],
    [3.0, { rightUpperArm: [0, 0.8, 1.15], rightLowerArm: [0, 2.15, -0.15], ...fingers('right', 0.2) }],
  ],
  expr: { blush: 0.5, happy: [[0, 0], [0.8, 0.5]] },
};

Rotations are [x, y, z] in radians on the standard VRM bone names (rightUpperArm z: 0 is straight out, 1.22 hanging down; rightLowerArm z negative bends the forearm up, a 4th number twists it; '+head' and '+spine' add on top of what she's doing). _pose.js has the helpers: both() mirrors a pose to both arms, fingers(side, curl), open(side). Other keys: idle: true (she does it on her own), left: true (also a left-handed <name>_left), private: true (never from stream chat), osc (a wobble), hips (lift her, metres). The header of portrait/viewer/gestures.js lists them all.

The built-in gestures are poses typed in as numbers. For real motion, record or keyframe a clip and drop it in portrait/animations/:

New clips show up within 20 seconds, no restart (reload the viewer to see them there). The viewer has a button per clip under clips, with 🔒 on private ones, and lists any file that wouldn't load.

Settings per clip go in portrait/animations/clips.json (or private/clips.json), keyed by file name without .vrma. clips.example.json shows them all:

Clips play on the standard VRM skeleton, so one recorded on any model plays on every VRM. Her breathing, blinking and lip-sync carry on underneath; a clip's own facial expressions are mixed in.

Making clips: XR Animator records one from your webcam and exports .vrma; Blender with the VRM add-on keyframes and exports them; VRoid publishes free samples. Check a clip's licence before it goes in a public repo.

How her replies set them off is up to you: the gestures row in the tools pane's Portrait group (space cycles it), or /portrait gestures <mode>.

The tag line only goes in her prompt while the portrait model is a 3D one. In meaning mode the log shows every score (gestures hug hug 0.61 none 0.55 ...), and /portrait meaning <some text> scores a line by hand. If she gestures too often, raise portrait.meaning_margin (default 0.04); too rarely, lower it.

The blush. VRoid paints the cheeks into the face texture, so there's no blush expression to turn up. The portrait lays a second copy of the face skin over it, sharing its skeleton and shape keys, with a pink glow in the cheek area of VRoid's face layout; it fades in and out and moves with every expression. A model with its own blush expression uses that instead. The viewer's tune section has a blush slider for trying it (left end is automatic). Per model, in its folder's luna.json:

{ "vrm": { "blush": { "left": [0.33, 0.61], "right": [0.67, 0.61], "size": 0.075,
                      "color": "#ff5f86", "strength": 0.65 } } }

left and right are where the cheeks sit in the face texture (0 to 1 from the top left); "enabled": false turns it off.

Chat can set them off too. Every message in stream chat (Twitch, YouTube, IRC, pomf) and Discord reaches the portrait, answered or not:

Chat triggers are rate-limited (five seconds between commands, twelve between the rest) so a busy chat doesn't keep her flailing. The chat gestures row in the tools pane turns them off, or "portrait": {"chat_gestures": false}.

/portrait wave (or hug, jump, bounce, shrug, stretch, kiss, shy, look_hand, tuck_hair) plays one by hand, good for a stream. The ?debug=1 page has a button for each.

They're built on the standard VRM skeleton (one file each in portrait/gestures/), so they work on any VRM model, including VRoid ones and outfits made from the same base. The tail wag looks for spring bones named like tail. Live2D models keep their own motions.

If portrait.model points at a file that isn't there, the portrait falls back to Luna's robot model (or Sigewinne if that's missing too) and says which file it couldn't find.

portrait/viewer/vendor/build.sh rebuilds the two bundled libraries (three.js + three-vrm, pixi.js + pixi-live2d-display) if you ever want newer ones.