Persona

Open Automations below Tracking in the left column of the Control Panel. An automation plays a timeline of actions against the current scene, started by a key or controller combination, by an event such as a scene change or loss of face tracking, or manually. One key can turn on an effect, pull the camera back to a saved position, and hide a layer, all at once — or play a song while effects and camera moves come in on cue

The row lists the app's automations first. When the scene has a primary model, a collapsible Avatar Shortcuts section follows with the shortcuts that model carries; it starts open and remembers whether you collapsed it

Creating an Automation

Add Automation sits above the list. Pick an action kind in its dropdown, then choose the action's target in the picker beside it — actions that need no target have an Add button instead, and the avatar actions grouped under Avatar also ask which avatar they act on. The new automation contains that action and opens with the name field focused

Each automation is a card. Its header shows the name above a summary of the triggers, then the bound combination, an Enable Automation switch and the Automation Options menu, with Pause Automation and Stop Automation buttons in front while it plays. Switching it off disables the automation: the summary starts with Paused, every trigger is ignored — including requests from outside Persona — and a run in progress stops

Click the name to expand the card. Enter a Name, or leave it blank to generate a title from the action names, joined with ·. Below it come the When block with the triggers, Timeline Editor, which opens the timeline, and the Do block with the actions

The options menu holds Run Automation, Duplicate Automation, Export Automation, Run in Background — see Background and Focused Shortcuts — and Delete Automation. Duplicate Automation inserts a copy right below and opens it: the copy keeps the actions and their timing, triggers, cooldown and enabled state, adds “Copy” to the name, and has no key combination. Export Automation saves the automation to a file — see Import and Export

Triggers

The When block lists what starts the automation. Any one matching trigger runs it, and it can still be run manually; the summary under the name lists the trigger kinds, or reads Manual Only when there are none

Keyboard or Controller

Keyboard or Controller always comes first. Expand it and click Set Shortcut… to open the recorder, press the combination, and confirm with Save or Enter; Clear unbinds it. The rules match avatar shortcuts: a combination containing Ctrl, Alt or Cmd keeps working while another application is in front, anything else only fires while Persona is focused. The recorder also takes up to three controls from one controller, and controller combinations keep working in the background without a modifier — see Controller Shortcuts

A combination is optional. Without one, the automation still runs from its other triggers, manually, and from outside Persona

Event Triggers

Add Trigger adds any of these. Each one is a collapsible row whose header summarizes its settings — saved rows start collapsed, a new one opens — and Remove Trigger deletes it

Parameter Value and Motion Playback stop matching once their layer is swapped to another model, and stay greyed out in Add Trigger until the scene has an avatar — as Face Tracking does until there is a face tracking source

Parameter Value reads one input the layer receives — MouthOpen at first, or any face or controller input picked under Parameter — before parameter mapping, so it follows the tracking signal rather than the model's final parameters. Microphone Level listens to the microphone chosen under Lip Sync, with its gain, noise gate and smoothing; it keeps working with lip sync off, without moving the avatar's mouth

A face counts as lost once its source reports no face or sends nothing for 1.5 s. A Scene Changed trigger runs its actions on the scene being entered, even for Exited, and editing a scene does not count as entering it

The two threshold triggers fire when the signal Rises Above or Falls Below the Threshold and stays there For at Least the hold time, 0 – 60 s. To fire again, it has to come back past the Reset Margin first; the row shows the level required to reset the trigger, and a meter shows the live value against the threshold while the row is open. The microphone level runs 0 – 1 with the threshold starting at 0.65; a parameter uses its input's own range

Microphone, parameter and face triggers ignore the state they find when watching starts and react only to a change after that; a microphone or parameter signal that drops out starts over the same way when it comes back. All triggers keep working with the Control Panel closed

Cooldown

Cooldown is the minimum time between runs, 0 – 3600 s, counted from the start of the last run. A trigger that arrives while the automation is running or cooling down is ignored, not queued, and the cooldown never delays the actions inside a run

Actions

The Do block lists the actions, and Add Action below it offers the same kinds as Add Automation. Each takes its place on the automation's timeline in one of three ways:

Setup runs first, in list order, and the timeline's clock starts only once the destination scene is active and the swapped model has loaded. Setup rows have a dashed border and read Setup before playback

A cue happens once, at its start time — its row reads, say, Runs at 2 s — and what it changes stays changed: stopping the automation does not undo it. Cues that share a start time run in list order

A clip lasts from its start to its end — 2–7 s · 5 s — and lets go of what it controls there: a temporary effect returns to the scene's own settings, and camera motion, audio and motion stop. Until you trim them, Play Camera Motion, Play Audio and Play Motion clips run for their file's full length and read Starts at 2 s · automatic duration. Only one clip at a time can drive the camera, a given avatar's motion or a given effect; audio clips can overlap freely

Each action is a collapsible row whose header summarizes its settings. One row is open at a time, and selecting a clip on the timeline opens its row. Dragging a row's handle changes the order of the list and of the timeline's tracks, not when anything runs. An automation keeps at least one action, so the last cannot be removed

While the automation runs, each row header shows the action's status beside its name — Pending, Running…, Completed, Skipped, Failed or Cancelled, with the time it took — or, for audio and camera motion, its playback progress. Hover over the header to see why an action failed or was skipped

An action's targets follow the automation's setup: with a Switch Scene, the pickers offer the destination's layers, and after a Swap Model, the layer's new model — wherever those rows sit in the list. A target that is gone stays in its row as Missing Scene, Missing Layer, Missing Avatar, Missing Model, Missing Expression, Missing Motion, Missing Audio or Missing Camera Motion until you pick a replacement. When the automation runs, a Layer Visibility action whose layer is gone is skipped, while any other missing target fails the run

Layer Visibility rows carry a Layer picker — any layer, or Primary Model for whichever model is primary when the action runs — plus Toggle / Show / Hide, and Stream Mode rows Toggle / On / Off; both start at Toggle. Stream Mode is the one action that writes an application setting rather than scene state, so it survives a scene switch the way the switch under Stage does. Reset Camera stores nothing: it eases to the framing the scene starts from, wherever the camera has since been left

Apply Effect Settings

A new Apply Effect Settings action copies the effect's current values once; after that, editing them changes only the automation. The row carries the effect's own controls plus Enabled When Triggered, which sets whether the effect is enabled after the action runs. Copy from Current Stage replaces the saved values with the stage's current ones, and Reset to Defaults restores the effect's defaults but keeps Enabled When Triggered

When the action runs, numbers and colours ease over 0.4 s, while modes and switches change at once

Temporary Effect

A Temporary Effect row has the controls of Apply Effect Settings plus Fade In (Seconds) and Fade Out (Seconds), up to 10 s each. A new one lasts 5 s with 0.4 s fades, and the two fades together cannot outlast the clip. For the length of the clip its saved values take over that effect, fading in from the start and out before the end; at the end the effect is exactly as the scene has it — off, if it was off. Nothing is written to the scene, and editing the effect yourself during a run takes it back from the automation until the run is resumed or started again

Switch Scene

Add saves the active scene as the destination; pick another under Scene in the row. The switch uses the destination's own scene transition. As setup, it runs before the timeline starts, and the timeline begins once the destination is active, while its transition may still be revealing it

Choosing the scene that is already active only cancels a switch still pending, without reloading. A newer scene switch — another Switch Scene, a pick in the Control Panel, or a plugin's scene.activate — cancels a run still waiting on an earlier one, without an error. If the destination is deleted, the row shows Missing Scene and the run fails

To switch scenes from a key or a controller, give an automation a Switch Scene action and a combination

Camera Position

A new Camera Position action saves the current camera, and its row edits that shot directly:

Copy from Current Stage replaces the shot with the stage camera's current view, so a shot composed with the stage gestures can be captured. Preview Position moves the stage camera to the saved shot; editing the fields changes only the action

An action saved while the camera still had its default framing reads Default Framing and keeps using it, with only Field of View to edit, until you click Set Position

To visit several views in turn, give camera actions different start times. While the scene's Camera settings assign a camera motion, the motion overrides saved positions, and the row warns about it

Play Camera Motion

Play Camera Motion takes a camera motion — a .vmd camera move, chosen under Camera Motion from the Inventory — and drives the 3D camera with it for the length of its clip, then hands the view back to the scene's camera; a Stop Camera Motion cue hands it back sooner. It overrides a camera motion assigned in the scene's Camera settings, and it keeps time with the automation rather than with the avatar's idle clip, so pausing or scrubbing the automation pauses or scrubs the camera too. Dragging on the stage while the automation is paused moves the camera on from the paused view; resuming hands it back to the motion

Play Audio

Play Audio plays a file from the Inventory's Audio category, chosen under Audio File:

The fade-in plays at the start of the first play and the fade-out at the end of the last; a loop fades out only when stopped. When Triggered Again decides what happens when this action starts while its earlier playback is still going: Restart Playback ends it and starts over, Overlap plays another copy alongside it, and Keep Playing lets it carry on. Other actions playing the same file are unaffected

Drive Lip Sync moves the chosen avatar's mouth with the file while it plays — see Lip Sync. Primary Model means whichever model is primary when the audio starts

The row header shows the playback — Loading…, Playing, Looping, Paused, Stopping…, Completed, Stopped or Failed — with the time played, counting every repeat, and Play 2/3 while it repeats. The sound stops at the end of its clip, even when it is set to loop

Control Audio applies its Playback Control — Pause, Resume or Stop, starting at Stop — to every playback of its Audio File at once, whether an automation or the Inventory started it. Stop lets a playing file finish its fade-out first

Avatar Actions

Toggle Expression, Play Motion, Clear All Expressions, Swap Model and Model Position act on the avatar chosen under Avatar in the row: a specific avatar layer — the primary one to begin with — or Primary Model, which follows whichever model is primary when the automation runs. The expression picker, and the motion picker on a Live2D model, read what the model declares, without loading it on stage. A VRM's Motion is chosen from the Inventory instead, under Choose Motion…: the bundled motion pack plus your own clips, and Open File… there imports another

Model Position saves the avatar's current placement and edits it with the usual 2D or 3D placement controls; editing does not move the avatar, Copy from Current Stage recaptures it, and running the action glides the avatar there. Swap Model keeps the layer's placement, and as setup it has the new model loaded before the timeline starts. An expression, motion or avatar that is no longer there fails the run

A Play Motion clip on a Live2D model always plays the whole motion from its start: trimming it or starting it partway is refused. A VRM clip can be trimmed and scrubbed, but its spring bones do not replay what came before the point you jump to

Timeline Editor

Timeline Editor, in an expanded automation, opens a dock along the bottom of the Control Panel, under both columns. It stays with that automation while you visit other rows, and selecting a clip brings its row back into view. Close Timeline Editor puts it away, and the divider above it resizes it

The bar across the top holds Undo Timeline Edit, Redo Timeline Edit, Split at Playhead, Duplicate Selected Actions, Delete Selected Actions and Add Marker, then Play — Pause while it plays — Stop and Close Timeline Editor on the right. Below, the action list sits beside one track per action, under a position slider that shows the current and total time

The strip under the tracks edits the selected action in numbers: Start, plus End and Duration for clips and Source In for audio, motion and camera motion. Use Source Length gives such a clip its file's full length back. Lock Timing, beside an action in the list, keeps its clip from being moved or trimmed, and a marker from Add Marker is a point to snap to and jump back to — neither changes how the automation plays. Dragging an action's handle in the list reorders it as in the Do block, and the divider beside the list resizes it

Edits are independent: moving, trimming or deleting a clip leaves every other clip where it is, and nothing closes a gap. Split at Playhead cuts the selected clips in two at the playhead, though not inside an audio or effect fade. Clips on the camera, on one avatar's motion or on one effect cannot overlap: they turn red, and the automation will not run until they are apart. Each edit is one step of undo — also ⌘ + Z and ⌘ + Shift + Z, or Ctrl + Z and Ctrl + Y on Windows and Linux, while you are working in the timeline. A run already playing keeps the version it started with

Timeline Settings, the gear in the bottom-right corner, holds:

Play runs the automation from the playhead — its setup first — even while the automation is switched off or cooling down; after Pause, it carries on from where everything stopped. Stop ends the run, stops its sound, fades a running motion out, lifts its temporary effects and returns the playhead to 0 s. Moving the playhead never runs cues or setup, and moving it back does not undo them

Running an Automation

Besides its triggers, an automation runs from Run Automation in its options menu, from the web console's Automations page, from the Stream Deck Run Automation key, or from a plugin calling automation.run through the Plugin API. None of these needs a key combination — that is how you get a whole row of buttons without spending a whole row of combinations. Automations are edited only in the desktop app, and a paused one does not run from any of these

A run does its setup first, then starts the timeline's clock: cues fire and clips play at their times, gaps included, and at the end of the timeline whatever it still plays stops. Files are made ready before the clock starts, and when one is still loading as its clip comes due, the whole automation waits for it rather than falling out of step

While an automation plays, its header fills from left to right with a light accent in step with its timeline, and a row whose audio or camera motion is playing lights up too. A failure freezes the whole automation at that moment, with the error on the failed row, and it will not run again until you stop it

A scene change stops every other automation still playing, and switching an automation off or deleting it stops its own run. Opening the shortcut recorder stops a playing automation, and none starts while it is open. Automations can set each other off — a Switch Scene entering a scene another one watches, a Play Motion or Swap Model feeding a Motion Playback or Model Loaded trigger — but one chain visits each automation at most once, so two scenes can never switch back and forth forever. A key, a manual run, a plugin call or a sensor trigger starts a new chain, while previewing on the timeline starts none

Import and Export

The Import and Export row above the list holds Import Automations and Export All, and Export Automation in a card's options menu saves just that one. The file is JSON describing the automations — actions and their timing, triggers and cooldown — and naming the scenes, layers, models and files they use by ID, without containing any of them. It links its JSON Schema, so an editor such as VS Code can check it as you type

Import Automations reads the whole file before changing anything, and refuses a file from an unsupported version or with an invalid automation, action or trigger. What it imports is added below your automations, switched off and without key combinations. A scene, model or file this computer does not have shows as missing until you pick a replacement, so check each automation's targets before switching it on

Avatar Shortcuts

The shortcuts the current primary model carries follow the automations, in their own collapsible Avatar Shortcuts section. Enable Avatar Shortcuts comes first and turns the whole set on and off — it appears only when that avatar actually carries shortcuts — followed by Add Avatar Shortcut and the rows. Each row is marked with the model format's glyph, whose tooltip reads Saved with «model»

Shortcuts belong to the model rather than to the application. Each model carries its own set, and swapping the primary model swaps which set is live — so a rig's bindings travel with it between machines, and between Persona and VTube Studio

Only the primary model's set is listed. A model that is not primary contributes no rows, and its bindings do not fire

Adding a Shortcut

Pick an action in Add Avatar Shortcut — its group is named for the current avatar, and each action carries an icon that also marks its rows in the list — then choose what it acts on in the picker beside it:

These act on the current primary model whatever its format — a VRM's expressions and animations bind just as well. A picker is unavailable when the model has no motions or expressions to bind; Swap Model lists every registered model but the one already loaded, and is unavailable when there is none

The new row starts unbound. Click Set Shortcut… to open the recorder, press the combination you want, and confirm with Save or Enter. Clear unbinds it again

Every registered shortcut is released while the recorder is open, so a combination that is already bound reaches the dialog instead of firing its own shortcut

The recorder also accepts a controller — up to three controls from one device, stick and D-pad directions and triggers included. See Controller Shortcuts

A combination is at most two modifiers plus one key. That is not an interface limit but a storage one — VTube Studio's format keeps exactly three trigger slots per hotkey, and Persona refuses anything it could not write back. Modifier keys are named per platform, so a macOS binding reads ⌥ and ⌘ rather than Alt and Win

Each row's options menu holds Trigger, to test the shortcut immediately. It is unavailable for anything Persona would refuse to run anyway: an unsupported VTube Studio action, one the model has switched off, or any row at all while Enable Avatar Shortcuts is off

Background and Focused Shortcuts

The options menu of every automation and avatar shortcut holds Run in Background, which decides whether its combination works while another application is in front. A globe icon marks the ones that run in the background

It requires Ctrl, Alt or Cmd. A bare key, or Shift with a key, is how text is typed — claiming it system-wide could prevent other applications from receiving it — so those bindings stay focused-only and the option is disabled. Controller combinations are the exception: they never register with the operating system's global shortcuts, so Run in Background is always available for them and needs no modifier

A combination another application already owns cannot be claimed either. The shortcut is not lost: it falls back to working while Persona is focused, and an amber triangle beside the combination explains why

When Two Shortcuts Share a Combination

Two avatar shortcuts on one combination both fire, and a warning triangle marks the rows. This matches VTube Studio, where one combination can drive several hotkeys at once — useful for applying two expressions together, and worth noticing when it was not what you meant

An automation takes precedence: when it holds the combination, it runs and avatar shortcuts on the same combination do not, and of two automations sharing one, only the first in the list runs. The triangle marks those rows as well

Each shortcut has its own short re-fire guard, so holding a key down triggers it once rather than repeating for as long as it is held

Where They Are Stored

Persona edits these files in place and preserves unrecognized fields. A hotkey using a VTube Studio action Persona has no equivalent for is listed greyed out and marked unsupported, never runs, and survives untouched when the file is written back — so editing shortcuts in Persona preserves the rest of your VTube Studio configuration

A read-only configuration file is never written to, and changes are simply not saved