Open Automations beneath Tracking in the left navigation column of the Control Panel. An automation coordinates a timed sequence of actions executed against the active scene. Automations can be initiated by keyboard hotkeys, game controller inputs, runtime events (such as scene switches, facial tracking dropouts, or signal threshold crossings), or invoked manually. A single trigger can execute multiple stage commands simultaneously or sequentially — activating post-processing effects, interpolating camera positions, toggling layer visibility, or choreographing camera moves to an audio soundtrack.
The automations panel first lists all application-wide automation routines. When avatars or props are present on stage, a collapsible Avatar Shortcuts section appears below, grouping model-specific shortcuts by asset; this section starts expanded and remembers its collapsed state across sessions.
Global application hotkeys and scene-specific shortcuts from legacy versions are not migrated automatically and must be recreated as automations. Avatar-specific shortcuts remain stored alongside model assets and are unaffected.
Creating an Automation
Click Add Automation above the list. Choose an action type from the dropdown, then select its target in the adjacent picker (actions requiring no target display an Add button directly; actions under the Avatar category require selecting the destination avatar). A new automation containing the specified action will appear, expanding automatically with focus set on the name input field.
Each automation is presented as an independent card. The header displays the automation title above a summary of active triggers, followed by bound shortcut badges, an Enable Automation switch, and the Automation Options menu; during playback, Pause Automation and Stop Automation transport controls appear on the card. Turning off the switch disables the automation: the status summary prefixes with Paused, incoming triggers (including external API calls) are ignored, and any active timeline playback halts immediately.
Click the title bar to expand the card details. Enter a custom label in the Name field; leaving it empty automatically generates a descriptive title combining action names separated by ·. The card body contains the Triggers block, a Timeline Editor button to summon the docked timeline, and the list of scheduled Actions.
The card options menu provides Run Automation, Duplicate Automation, Export Automation, Run in Background (see Background and Focused Shortcuts), and Delete Automation. Choosing Duplicate Automation clones the entry directly below: the duplicate inherits all actions, timing offsets, triggers, cooldown values, and enabled state, appending “Copy” to its name, while clearing shortcut assignments for safety. Export Automation writes the routine to disk as an exchangeable JSON file (see Import and Export).
Triggers
The Triggers section specifies the criteria that initiate automation playback. Fulfilling any single active trigger executes the sequence; automations can also be run manually. The card header summarizes configured trigger categories, displaying Manual Only when no automated triggers exist.
Keyboard or Controller
The Keyboard or Controller trigger resides at the top of the trigger block. Expand the entry and click Set Shortcut… to open the input capture modal, press the desired key combination, and confirm with Save or Enter; click Clear to unbind. Input handling mirrors avatar shortcuts: combinations containing Ctrl, Alt, or Cmd modifiers function globally while other desktop applications have focus; bare keys or combinations lacking those modifiers respond only when Persona is focused. The recorder also binds up to three inputs from a game controller, which operate globally in the background without modifier keys (see Controller Shortcuts).
| Marker | Description |
|---|---|
| Red triangle | Another shortcut entry in the list uses the identical combination |
| Amber triangle | The key combination is claimed exclusively by another application |
Shortcut bindings are optional. Automations lacking hotkeys remain operable via event triggers, manual execution, and external API integrations.
Event Triggers
Click Add Trigger to append event listeners from the following options. Each trigger appears as a collapsible row summarizing its parameters; click Remove Trigger to delete an entry:
| Trigger | Trigger Condition |
|---|---|
| Microphone Level | Input audio amplitude crosses a decibel threshold |
| Parameter Value | A specific tracking input on the chosen Model Layer crosses a threshold |
| Model Loaded | Any Model or a specific model finishes loading and asset initialization |
| Motion Playback | An animation starts or finishes on the chosen Model Layer (Started, Ended, or both) |
| Scene Changed | The stage enters or exits Any Scene or a specific scene (Entered, Exited, or both) |
| Face Tracking | The selected Tracking Source detects or loses a face (Face Found, Face Lost, or both) |
If the layer assigned to Parameter Value or Motion Playback is swapped to another model asset, the trigger stops evaluating until updated. If no avatar layer exists on stage, these options appear disabled in the Add Trigger menu; similarly, Face Tracking requires an active tracking source.
Parameter Value intercepts raw input channels delivered to the layer (defaulting to MouthOpen, reassignable to any face or controller axis via the Parameter dropdown). Signals are sampled before parameter mapping, reflecting raw capture data independent of model deformation curves. Microphone Level taps the physical input selected under Lip Sync, inheriting its gain, noise gate, and smoothing filters; it functions even when lip sync deformation is disabled.
A face counts as lost when the tracking provider explicitly reports no face or transmits no data frames for 1.5 seconds. Actions triggered by Scene Changed always target the destination scene being entered, even when configured for Exited; editing scene properties in the inspector does not register as a scene change.
Threshold triggers employ directional logic: configure the signal to trigger when it Rises Above or Falls Below the Threshold, holding that state For at Least a specified duration (0 – 60 seconds). To trigger again, the signal must retreat beyond the Reset Margin deadband; expanding the row reveals the necessary reset value and displays a real-time VU meter comparing current input against the threshold. Microphone level normalizes across 0 – 1 (initial threshold 0.65); parameters use their native source ranges.
Microphone, parameter, and tracking triggers do not fire on static initialization states, reacting only to subsequent dynamic changes. When interrupted signals reconnect, edge detection reinitializes cleanly. All event triggers remain active when the Control Panel is dismissed.
Cooldown
Cooldown enforces a minimum duration between consecutive executions, adjustable from 0 to 3600 seconds, measured from the start of the previous run. Triggers received while an automation is active or cooling down are discarded rather than queued. Cooldown timers do not delay subsequent actions within an ongoing run.
Actions
The Actions block lists the scheduled operations in the automation, with Add Action providing the same types available in Add Automation. Actions occupy the timeline in one of three timing modes:
| Action | Description | Timing |
|---|---|---|
| Toggle Effect | Enables, disables, or inverts the state of a post-processing effect | Cue |
| Apply Effect Settings | Writes preconfigured effect parameters and toggle states directly to the active scene | Cue |
| Temporary Effect | Overrides effect parameters for a bounded duration before reverting to scene defaults | Clip |
| Camera Position | Smoothly eases the 3D camera to a stored viewpoint | Cue |
| Reset Camera | Smoothly eases the 3D camera back to the scene's default framing | Cue |
| Play Camera Motion | Drives the 3D camera using a .vmd motion trajectory | Clip |
| Stop Camera Motion | Halts automated camera motion playback, returning control to the scene camera | Cue |
| Camera Follow | Directs the camera to follow a layer or the primary model, or stops following | Cue |
| Camera Aim | Rotates the camera to keep a layer or the primary model in frame, or stops aiming | Cue |
| Camera Focus | Locks Depth of Field focus onto a layer or the primary model, or resets to look-at point | Cue |
| Handheld Movement | Enables, disables, or toggles procedural handheld camera sway | Cue |
| Layer Visibility | Shows, hides, or toggles the visibility of a layer | Cue |
| Apply Preset | Moves layers to a saved scene preset using the preset's own transition | Cue |
| Stream Mode | Enables, disables, or toggles Stream Mode | Cue |
| Switch Scene | Transitions to a saved scene before timeline playback begins | Setup |
| Play Audio | Plays an audio file from the Inventory | Clip |
| Control Audio | Pauses, resumes, or stops active playback instances of an audio file | Cue |
| Set Text | Temporarily displays text on a text layer | Cue |
| Lyrics | Sings an .lrc lyrics file on a text layer with karaoke playback | Clip |
| Toggle Expression | Applies an avatar expression, or removes it if already active | Cue |
| Play Motion | Plays a specific animation clip, overriding current motion channels | Clip |
| Clear All Expressions | Clears all active facial expressions simultaneously | Cue |
| Swap Model | Replaces the avatar layer with another model asset prior to timeline playback | Setup |
| Model Position | Smoothly glides the avatar to stored spatial coordinates | Cue |
Setup actions execute first in sequential list order. Timeline playback begins only after the destination scene is active and swapped model assets have loaded completely. Setup rows feature dashed borders labelled Setup before playback.
A cue executes instantaneously at its assigned timestamp (labelled Runs at X s). Its state modifications persist indefinitely; stopping automation playback does not roll back cues. Simultaneous cues sharing an identical timestamp execute in list order.
A clip spans a continuous duration (labelled 2–7 s · 5 s) and releases its targeted channels upon expiration: temporary effects revert to scene baselines, while camera motion, audio, and avatar animations cease playback. Untrimmed Play Camera Motion, Play Audio, Lyrics, and Play Motion clips adopt native file durations, displaying Starts at X s · automatic duration. Viewport camera movement, avatar animation channels, specific effects, and text layers can each be driven by only one active clip at a time; audio clips may overlap freely.
Each action row collapses to a header summarizing its parameters. Only one row expands at a time, and selecting a clip on the timeline highlights and opens its inspector row. Dragging an action's row handle adjusts vertical track ordering without altering execution timestamps. Automations require at least one action; the final remaining action cannot be deleted.
During playback, each row header displays real-time execution status — Pending, Running…, Completed, Skipped, Failed, or Cancelled, along with elapsed runtime; audio and camera motion clips display percentage progress indicators. Hovering over a status badge reveals diagnostic failure reasons.
Action targets reflect pre-run setup state: adding Switch Scene updates layer pickers to reference destination scene assets; adding Swap Model updates pickers to reference the replacement model. If a targeted asset is deleted, the row displays a missing asset warning: Missing Scene, Missing Layer, Missing Preset, Missing Avatar, Missing Model, Missing Expression, Missing Motion, Missing Audio, or Missing Camera Motion. At runtime, Layer Visibility actions with missing layers and Apply Preset actions with missing presets are skipped silently, whereas other missing targets cause the run to fail.
Layer Visibility rows provide a Layer picker (targeting specific layers or dynamically referencing the Primary Model) and a Toggle / Show / Hide selector. Stream Mode and Handheld Movement rows provide Toggle / On / Off. Both default to Toggle. Because Stream Mode modifies global preferences rather than scene state, its value persists across scene transitions like the switch under Stage. Reset Camera requires no stored snapshot: regardless of current camera offset, it smoothly eases back to the scene's authored framing.
Apply Effect Settings
Creating an Apply Effect Settings action captures a snapshot of current live parameters for that post-processing effect; subsequent edits alter only this automation. The row includes the effect's native adjustment controls and an Enabled When Triggered toggle. Copy from Current Stage overwrites stored values with current live parameters; Reset to Defaults restores factory defaults while preserving the trigger toggle state.
When executed, numerical properties and color values interpolate smoothly over 0.4 seconds, while discrete modes and switches toggle instantaneously.
Temporary Effect
Temporary Effect provides the same controls as Apply Effect Settings, accompanied by Fade In (Seconds) and Fade Out (Seconds) fields (up to 10 seconds each). New clips default to a 5-second duration with 0.4-second fades; total fade durations cannot exceed clip length. Stored parameters override the effect during playback, fading in at the start and fading out before the end, after which the effect returns seamlessly to its scene configuration. Temporary parameters are not persisted to scene files; manually adjusting the effect during a run releases automation control until the sequence restarts.
Switch Scene
Adding this action captures the active scene as the initial target; select an alternate destination under Scene. Transitions leverage the destination scene's configured scene transition. As a setup task, this executes before timeline playback commences; the timeline clock starts once the destination scene is active, even if transitional animations are still concluding.
Selecting an already active scene cancels pending switches without reloading assets. A newer scene switch request — from another action, the Control Panel, or a plugin call to scene.activate — cancels a pending run without generating an error. If the destination scene has been deleted, the row displays Missing Scene and execution aborts.
To switch scenes via key presses or controllers, create an automation with a Switch Scene action and assign a shortcut combination.
Apply Preset
Apply Preset rows provide a Preset picker listing the saved scene presets of the target scene; if the sequence contains Switch Scene, it lists the destination scene's presets. When executed, layers move using the preset's own configured transition. If the preset no longer exists in the target scene, the row displays Missing Preset and the action is skipped at runtime. Like other cues, applying a preset from an automation records no undo step.
To apply a preset via keyboard shortcuts or controller buttons, create an automation with an Apply Preset action and assign a shortcut; the Stream Deck plugin also provides a dedicated Apply Preset key.
Camera Position
A new Camera Position action records the stage camera's active viewpoint, allowing direct parameter editing in the inspector:
| Control | Value and Description |
|---|---|
| Position | X · Y · Z coordinates with an interactive 3D position handle |
| Orbit Angle | Horizontal orbit angle, −180° – 180° |
| Tilt | Vertical tilt angle, −80° – 80° |
| Distance | Camera distance to focal target, 0.35 – 20 (auto-scaled to environment dimensions) |
| Field of View | Lens focal field of view (FOV), 10° – 90° |
| Look at Point | Focus point coordinates orbiting the camera target (Look at X, Look at Y, Look at Z) |
Click Copy from Current Stage to capture the camera's viewport framing; click Preview Position to align the viewport camera with stored coordinates; modifying fields updates only this action.
Actions saved while the camera retains its initial defaults display Default Framing, locking adjustments to Field of View until clicking Set Position.
To transition across multiple camera angles, assign staggered start times to separate camera actions. If the scene's Camera settings assign an active motion trajectory, it overrides static position actions, with the row displaying an active warning.
Play Camera Motion
Play Camera Motion selects a .vmd camera trajectory from the Inventory, driving the 3D camera for the duration of the clip before returning control to the scene camera; a Stop Camera Motion cue relinquishes control prematurely. This action supersedes camera motion assigned in scene Camera settings and synchronizes strictly with the automation timeline rather than avatar idle cycles. Pausing or scrubbing the timeline pauses or scrubs camera motion concurrently. Interactively adjusting the stage camera while paused establishes a new offset; resuming playback snaps back to the motion path.
Camera Follow
Camera Follow binds the camera to frame a specific layer or the Primary Model as it moves, or selects None to stop following. Settings include the Layer picker, Anchor point (bone or root), Binding mode (World, Yaw, Yaw and Pitch, Yaw, Pitch, and Roll, or Lazy), and Damping parameters, matching Camera: Follow. Click Copy from Current Stage to capture active follow settings from the viewport camera.
Camera Aim
Camera Aim rotates the camera in place to keep a layer or the primary model within a target region on screen, or selects None to return to the standard look-at point. Configurable fields include Layer, Anchor, Screen Position (Screen X and Y), Dead Zone, Soft Zone, Bias, Damping, and Lookahead settings, matching Camera: Aim. Click Copy from Current Stage to capture live aim settings.
Camera Focus
When the Depth of Field effect is active, Camera Focus locks the focal plane to a specific bone or root anchor on a chosen layer or the primary model with customizable Focus Damping; selecting None returns focus to the standard look-at point. See Camera: Focus. Click Copy from Current Stage to adopt active focus settings.
Handheld Movement
Handheld Movement toggles procedural camera sway during automation playback, offering Toggle, On, and Off modes (defaulting to Toggle). When active, the camera exhibits subtle breathing and hand-held motion; turning it off restores a completely rigid camera. See Camera: Handheld Movement.
Play Audio
Play Audio triggers audio playback from the Inventory's Audio repository:
| Control | Value and Description |
|---|---|
| Playback | Choose Once, Repeat, or Loop Until Stopped |
| Total Plays | Total iterations when set to Repeat (including first play), up to 999 |
| Volume (%) | Audio playback gain, 0 – 100 (default 50) |
| Fade In (Seconds) · Fade Out (Seconds) | Fade transitions, 0 – 60 seconds each (default 0) |
| When Triggered Again | Concurrency policy: Restart Playback, Overlap, or Keep Playing |
| Drive Lip Sync | Lip sync routing: Off, Primary Model, or an explicit avatar in the scene |
Fade-ins apply to the beginning of the initial playback; fade-outs apply to the conclusion of the final repetition. Looped audio fades out only when explicitly stopped. When Triggered Again controls behavior when invoked while a prior playback instance is active: Restart Playback restarts the track from the beginning, Overlap instantiates a concurrent audio instance, and Keep Playing ignores the trigger to allow uninterrupted playback. Distinct actions playing the same audio file operate independently.
Enabling Drive Lip Sync analyzes the audio waveform to animate the mouth shapes of the chosen avatar (see Lip Sync). Primary Model references whichever avatar holds primary status when audio begins.
The row header reflects playback progress and state (Loading…, Playing, Looping, Paused, Stopping…, Completed, Stopped, or Failed), displaying elapsed time and repetition counters (such as Play 2/3). Audio terminates when its timeline clip expires.
Control Audio applies transport commands (Pause, Resume, or Stop, defaulting to Stop) across all active playback instances of the specified audio file, whether triggered by automations or manual Inventory playback. Selecting Stop allows active instances to execute their configured fade-out before terminating.
Set Text
Set Text pushes dynamic text to a designated text layer at a specific timestamp. This action acts as a transient text override: it writes no changes to scenes.json and creates no undo step. The temporary text persists until the layer evaluates Show Saved Text, the saved text is edited in the inspector, or the layer is removed from the stage. If the target layer is missing or is not a text layer, the action skips silently at runtime.
Lyrics
Lyrics binds an .lrc file from the Inventory to a designated text layer, driving karaoke playback synchronized to the automation timeline:
- Audio Alignment: Adding a Lyrics action automatically copies the start timestamp, Source In offset, and duration of the first Play Audio clip in the same automation. If the audio runs at natural uncropped length, the lyrics clip also adopts natural duration (ending with its own file rather than forced to the song duration). The two clips remain independent afterwards.
- Duration Resolution: A lyrics file's natural duration is resolved from its
[length:]tag, falling back to the end of the final word, or to five seconds past the start of the final line. If a lyrics clip is trimmed or extended past the end of the file, the layer holds the final line in place until the clip ends. - Two Alternating Rows: To avoid vertical jumping while reading, the text layer displays the current and next line in two fixed alternating rows — even lines on top and odd lines below. Both rows appear in their unsung state before the first line begins.
- Word Wipe and Line Highlighting: Enhanced LRC files with
<mm:ss.xx>timestamps perform smooth word-by-word wipe coloring; standard LRC lines turn sung in full at line start. Sung text fill and 2D outline colors follow the layer's Sung Color and Sung Outline properties. - Time Tag Parsing: Supports
[offset:]tags to shift all timings (positive values display earlier). For duplicate timestamps, the first line containing text is retained. Empty timestamped lines act as end markers for preceding lines. Character encodings are detected via BOM as UTF-8 or UTF-16, falling back to UTF-8 and then GB18030. - State Restoration: When a lyrics clip reaches its right edge, or when playback stops or fails, the text layer immediately restores its underlying saved text (including any active transient text).
- Validation: If the referenced lyrics file is missing or unparseable, or if the target layer is missing or not a text layer, automation execution fails immediately prior to start.
Avatar Actions
Toggle Expression, Play Motion, Clear All Expressions, Swap Model, and Model Position target the avatar selected under Avatar: an explicit avatar layer or the dynamic Primary Model. The expression picker and Live2D motion selector parse model metadata directly without requiring assets on stage. VRM motions are selected via Choose Motion… from the Inventory, encompassing bundled motion libraries and custom clips imported via Open File….
Model Position records an avatar's spatial coordinates, offering standard 2D and 3D transform fields; editing these values does not move the live model. Click Copy from Current Stage to re-sample coordinates; executing the action smoothly glides the model to the stored placement. Swap Model pre-loads replacement assets before timeline playback while preserving existing layer transforms. Missing expressions, motions, or avatars cause execution to fail.
Live2D Play Motion clips require full playback from the initial frame; trimming start boundaries or mid-stream playback is rejected. VRM clips support trimming and playhead scrubbing, though secondary spring bone dynamics do not back-propagate physics prior to jump points.
Timeline Editor
Clicking Timeline Editor inside an expanded automation docks a multi-track sequencing panel along the bottom of the Control Panel. The editor remains bound to that automation while navigating other cards; selecting a clip in the timeline automatically scrolls to and expands its inspector row. Click Close Timeline Editor to dismiss the dock, or drag the top border to resize the workspace.
The header toolbar provides Undo Timeline Edit, Redo Timeline Edit, Split at Playhead, Duplicate Selected Actions, Delete Selected Actions, and Add Marker, alongside Play (toggling to Pause), Stop, and Close Timeline Editor controls on the right. The lower section pairs an action hierarchy on the left with horizontal sequencer tracks on the right beneath a timecode scrub bar.
| Gesture | Description |
|---|---|
| Click clip | Selects clip and opens its inspector row; hold Shift, ⌘, or Ctrl to add to selection |
| Drag across track canvas | Box-selects all intersected timeline clips |
| Drag clip | Moves clip across time alongside selected peers |
| Drag clip boundary | Trims duration. Trimming the start of audio, lyrics, motion, or camera clips adjusts Source In (playback media offset) |
| ← → | Steps selection by snap interval (10× with Shift; finest step with Alt) |
| ⌘/Ctrl + D | Duplicates selected clips in place |
| Delete | Deletes selected clips |
| Alt + scroll | Zooms the timeline centered on the pointer (up to 64×) |
| Hold Alt while dragging | Temporarily disables grid snapping |
| Esc | Cancels active drag operation |
The property strip below the tracks permits numerical time adjustments: Start, plus End and Duration for clips, and Source In for media tracks (all measured in seconds). Click Use Source Length to restore original media or lyrics durations. The Lock Timing toggle prevents accidental moves or trims; Add Marker creates snapping targets and navigation bookmarks without altering playback output. Dragging action handles reorders vertical track layers, and the divider adjusts inspector width.
Edits remain isolated: moving, trimming, or deleting clips leaves surrounding elements in place without collapsing empty gaps. Split at Playhead divides selected clips into two independent segments (forbidden within fade envelopes). Clips driving the camera, a specific avatar's motion channels, identical effects, or the same text layer cannot overlap; overlapping clips highlight red, and the automation is blocked from running until resolved. Every modification produces an undo step (⌘ + Z / ⌘ + Shift + Z on macOS; Ctrl + Z / Ctrl + Y on Windows and Linux). Active playbacks continue using the snapshot established at trigger time.
The Timeline Settings gear menu in the bottom-right corner configures:
| Setting | Description |
|---|---|
| Preview on Stage | Enabled by default. Scrubbing the position slider previews stage media and temporary effects (cues and setup actions omitted) |
| Timeline Snapping | Options: Snap Off, 0.1 s (default), 0.5 s, 1 s, or 30 FPS. Clips snap to neighboring clips, the playhead, and markers |
| Timeline Zoom | Preset: Fit, or zoom ratios from 2× to 64× |
| Automatic Duration | Enabled by default: aligns timeline ending with the final clip or cue once media durations resolve; defaults to 30 s otherwise |
| Sequence Duration (Seconds) | Explicitly defines total duration when Automatic Duration is disabled (up to 1 hour), allowing tail silence |
Clicking Play evaluates setup actions before executing from the playhead position, functioning even when automations are disabled or cooling down; clicking Pause allows resume from that point. Clicking Stop halts playback, mutes audio, fades out active animations, revokes temporary overrides, and resets the playhead to 0 seconds. Scrubbing the playhead does not evaluate cues or setup actions, and scrubbing backward does not roll back state.
Running an Automation
Automations can be executed manually via Run Automation in the card options menu, through the Automations surface in the Web Console, via the Run Automation key on Stream Deck, or triggered programmatically via automation.run in the Plugin API. None of these control paths consume keyboard hotkeys — ideal for populating hardware macro pads. Automations are authored strictly within the desktop application; disabled automations cannot be executed via external entry points.
Executing an automation evaluates setup actions prior to starting the timeline clock: cues fire and clips play at their precise timestamps, accounting for empty gaps, with remaining activity halting at sequence conclusion. Media assets are cached before playback begins; if an asset is buffering when its clip comes due, the sequence pauses temporarily to guarantee audio-visual synchronization.
During execution, card headers display a left-to-right accent fill tracking playback progress, while active media rows illuminate. If an action encounters an exception, the automation freezes, highlighting the error on the failing row; the automation cannot run again until manually cleared via Stop.
Switching scenes terminates active automations; disabling or deleting an automation halts its running instance immediately. Opening the shortcut recorder pauses active playback and inhibits new automations from starting. Automations can chain-trigger each other — such as Switch Scene activating an automation listening for scene changes, or Play Motion firing a Motion Playback trigger — but each automation evaluates at most once per execution chain, preventing infinite loops. Manual clicks, keys, API requests, and sensor inputs initiate distinct execution chains, whereas timeline scrubbing triggers no automations.
Import and Export
The Import and Export toolbar above the list provides Import Automations and Export All, while individual card menus offer Export Automation. The resulting JSON document serializes action sequences, timings, triggers, and cooldown values, referencing scenes, layers, models, and audio files by UUID without bundling binary media. Exported files declare the official JSON Schema for real-time validation in IDEs like VS Code.
Import Automations validates file structure prior to applying changes, rejecting invalid schemas or corrupted definitions. Imported automations append to the bottom of the list, disabled and stripped of key combinations. References to missing local scenes or files display warnings until reassigned, requiring verification before activation.
Avatar Shortcuts
Each avatar's shortcuts have a separate collapsible section below application automations, headed by its model name, format glyph, and primary indicator (Primary Model carries a star badge). Expansion is remembered per model; the keyboard switch and shortcut controls stay inside that avatar's section on desktop and in the Web Console. Inside, each section contains the Add Avatar Shortcut button and individual shortcut rows, with tooltips reading Saved with «model».
Shortcuts belong to model assets rather than global application preferences. Each model stores its own shortcut bindings — allowing control mappings to travel with the character across computers and between Persona and VTube Studio.
All active models on stage evaluate their respective shortcuts independently, regardless of primary status or format (matching VTube Studio conventions). The primary model group anchors the top of the list. Models assigned to multiple layers display once (sharing bindings stored within the asset file); removing a model from the stage removes its shortcut group.
Adding a Shortcut
Click Add Avatar Shortcut within a model group, select an action type (groups are named for their avatar, with each action using a distinctive icon matched across list rows), then select target parameters in the adjacent picker:
| Action | Description |
|---|---|
| Toggle Expression | Applies the selected expression, or removes it if already active — mirroring inspector toggle buttons |
| Play Motion | Plays a specific animation, taking over from active motions. Plays once, regardless of internal file loop flags |
| Clear All Expressions | Removes all active facial expressions simultaneously, including those suppressed by active motions |
| Swap Model | Replaces this layer with another model asset across any format (e.g. Live2D to VRM); pickers exclude the current model |
These actions apply directly to the owning model asset across any format — binding VRM blendshapes and animations with equal fidelity. Pickers disable when models lack compatible motions or expressions; Swap Model lists all registered models except the active asset, disabling when no alternates exist, and replaces the specific layer hosting the model.
New rows initialize unbound. Click Set Shortcut… to open the recorder modal, input the key combination, and confirm via Save or Enter. Click Clear to unbind.
Registered application hotkeys are released while the recorder is active, allowing bound combinations to reach the configuration dialog without triggering associated actions.
The recorder accepts game controllers — supporting up to three inputs from a single device, including analog sticks, D-pad directions, and triggers (see Controller Shortcuts).
Combinations allow up to two modifiers plus one standard key. This constraint reflects storage schemas rather than UI limitations — VTube Studio's hotkey specification allocates three trigger slots per entry, and Persona requires strict format interoperability. Modifier keys follow platform conventions, displaying as ⌥ and ⌘ on macOS rather than Alt and Win.
Row option menus provide Trigger to test shortcuts immediately. This option disables when Persona would reject execution: unsupported VTube Studio actions, entries disabled on the model, or groups whose master switch is toggled off.
Playback Options
Expression and motion shortcuts expose advanced playback parameters in their option menus, matching identical VTube Studio settings and maintaining configuration interoperability across both platforms:
| Option | Description |
|---|---|
| Hold to Activate | Expression remains active only while the combination is held, fading out on release (default off) |
| Fade Time | Transition duration in seconds; Default follows timings authored inside asset files |
| Turn Off After | Automatically deactivates the expression after this duration; Never maintains state |
| Stop After | Maximum animation runtime; Never plays the full duration of the motion |
| Stop on Last Frame | Holds the final animation frame until re-triggered (default off) |
Hold to Activate and Turn Off After appear on expressions only; Stop on Last Frame and Stop After apply exclusively to Live2D motions (VRM clips play as authored). Duration menus offer standard intervals alongside custom values stored in asset files.
Hold to Activate requires physical key release events. Global keyboard shortcuts executing in the background cannot intercept key-up events and revert to standard toggles; if any shortcut on a combination executes globally, all sharing entries fall back to toggle mode (annotated in the menu). Controller combinations are unaffected. Triggering via Trigger, Stream Deck, MCP, or the Plugin API lacks release events and behaves as a toggle.
Expressions activated by Hold to Activate or Turn Off After shortcuts are excluded from Remembering Expressions, preventing temporary states from restoring unexpectedly across model reloads.
Background and Focused Shortcuts
Each automation and avatar shortcut provides a Run in Background menu toggle, determining whether combinations fire while other applications have desktop focus. Globally active shortcuts display a globe icon.
Global registration requires Ctrl, Alt, or Cmd modifiers. Bare keys and Shift combinations are reserved for text entry — registering them globally would intercept keystrokes intended for other software — restricting them to focused execution with background toggles disabled. Controller combinations operate outside global OS hotkey tables, allowing Run in Background without modifier requirements.
Combinations claimed exclusively by other applications cannot be registered globally. Shortcuts revert gracefully to focused execution, with an amber warning triangle explaining the fallback.
When Two Shortcuts Share a Combination
When two avatar shortcuts share an identical key combination, both fire concurrently, with warning triangles annotating both rows. This mirrors VTube Studio behavior, allowing deliberate composite triggers (such as applying dual expressions) while signaling unintended overlap.
Shortcuts belonging to distinct models sharing a combination fire concurrently on their respective rigs — commonly used to synchronize avatar movement with independent hand props. VTube Studio provides no notification for cross-model conflicts; Persona flags them with warning triangles.
Automations maintain execution precedence: when a combination is assigned to an automation, only the automation runs, suppressing avatar shortcuts on that combination; when two automations share a combination, only the first entry in the list executes. Affected rows display warning triangles.
Shortcuts incorporate hardware-level de-bounce protection, firing once per press rather than repeating while held.
Where They Are Stored
| Model Storage | Written To |
|---|---|
Has .vtube.json | The asset's native hotkey array in VTube Studio format |
Lacks .vtube.json | A <model>.persona.json sidecar beside the model's entry file |
Persona updates these configuration files in place, preserving unrecognized fields. Hotkeys referencing unsupported VTube Studio actions display greyed out and marked unsupported, never execute, and remain untouched on disk — preserving existing VTube Studio setups.
The playback options map directly to VTube Studio fields supported by both formats; Persona writes only explicitly modified values, leaving untracked bytes intact. Note that .vtube.json hotkeys require numerical fade times (Default writes as 0.5 s), whereas .persona.json permits omitting the property to follow native file durations.
Read-only configuration files are never written to, silently discarding modifications.
Assigned shortcuts appear as badges on motion and expression buttons within model controls, serving as an interactive reference for active key mappings.
Last updated on October 15, 2026