Persona

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 run multiple stage actions at once or in sequence, such as activating post-processing effects, moving the camera, toggling layer visibility, or timing camera moves to an audio track.

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.

Creating an AutomationCopy Anchor Link

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 a card. Its header shows the title above a summary of its triggers, followed by its shortcut badges, an Enable Automation switch, and the Automation Options menu. While the automation plays, Pause Automation and Stop Automation buttons also appear on the card.

Turning the switch off disables the automation: the summary starts with Paused, all triggers are ignored (external API calls included), and a running timeline stops at once.

Click the title bar to expand the card. Type a name in the Name field; if you leave it empty, the title is the action names joined by ·. The card body holds the Triggers block, a Timeline Editor button that opens the docked timeline, and the list of Actions.

The card's options menu has Run Automation, Duplicate Automation, Export Automation, Run in Background, and Delete Automation.

• Duplicate Automation inserts an expanded copy directly below. The copy keeps all actions and their timing, the triggers, the cooldown, and the enabled state, with “Copy” added to its name. For safety, shortcuts are not copied.
• Export Automation saves the automation as a JSON file (see Import and Export).
• Run in Background decides whether its shortcut fires while another app is in focus (see Background and Focused Shortcuts).

TriggersCopy Anchor Link

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, Mouse or ControllerCopy Anchor Link

The Keyboard, Mouse or Controller trigger always comes first. Expand it and click Set Shortcut… to open the recorder, press up to three keys or mouse buttons together, then confirm with Save or Enter. Click Clear to remove the shortcut.

It follows the same rules as avatar shortcuts:

• With Run in Background on, any combination (including a bare key) triggers even while another app is in focus; with it off, it responds only while Persona is in focus.
• An automation requires the exact modifiers in its binding: one bound to W won't trigger while Shift is held.
• The recorder also accepts up to three inputs from a game controller. Controller shortcuts follow the same rules as keyboard ones (see Controller Shortcuts).

Shortcut bindings are optional. Automations lacking hotkeys remain operable via event triggers, manual execution, and external API integrations.

Event TriggersCopy Anchor Link

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:

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 watches a raw input that the layer receives: MouthOpen by default, or any face, controller, or random pulse input (RandomPulse1–RandomPulse8, whether or not it is bound to a parameter, to trigger the automation at random intervals) chosen under Parameter. It reads the input before parameter mapping, so the value is the raw capture data, unaffected by the model's deformation curves.
• Microphone Level listens to the microphone selected under Lip Sync and uses its gain, noise gate, and smoothing. It works even when lip sync isn't moving the mouth.
• Face Tracking counts a face as lost when the tracking source reports no face, or sends no data for 1.5 seconds.
• Scene Changed actions always target the scene being entered, even when the trigger is set to Exited. Editing scene properties in the inspector doesn't count as a scene change.

Microphone Level and Parameter Value fire when the signal crosses a threshold:

Expanding the row shows the value the signal must reach to reset, plus a live meter comparing the input with the threshold.

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.

CooldownCopy Anchor Link

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.

ActionsCopy Anchor Link

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:

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 covers a span of time (labelled 2–7 s · 5 s). When it ends, it releases what it was driving: temporary effects return to the scene's settings, and camera motion, audio, and avatar motion stop.

• Untrimmed Play Camera Motion, Play Audio, Lyrics, and Play Motion clips take their file's own length, labelled Starts at X s · automatic duration.
• Only one clip at a time can drive the camera, an avatar's motion channels, a given effect, or a text layer. Audio clips can 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.

While an automation runs, each row header shows the action's status and elapsed time: Pending, Running…, Completed, Skipped, Failed, or Canceled. Audio and camera motion clips also show their progress as a percentage. Hover over a status to see why the action failed or was skipped.

Pickers take the setup actions into account: with Switch Scene, layer pickers list the destination scene's layers; with Swap Model, pickers list the replacement model.

If a target is deleted, the row stays and shows a warning: Missing Scene, Missing Layer, Missing Preset, Missing Avatar, Missing Model, Missing Expression, Missing Motion, Missing Audio, Missing Camera Motion, or Missing Lyrics. At runtime:

• These actions are skipped silently:
  • Layer Visibility with a missing layer
  • Apply Preset with a missing preset
  • Set Text with a missing or non-text layer
  • Camera Follow, Camera Aim, and Camera Focus with a missing layer, or one that is neither a VRM model nor a 3D object (the camera stays as it was)
• Any other missing target makes the run fail.

The simpler actions have these options:

Stream Mode is the only action that changes a global preference rather than the scene, so it stays as set across scene switches, just like the switch under Stage.

Apply Effect SettingsCopy Anchor Link

A new Apply Effect Settings action starts from a snapshot of the effect's current live values; editing it afterwards changes only this automation. The row has the effect's own controls, plus:

• Enabled When Triggered sets whether the effect is on or off after the action runs.
• Copy from Current Stage replaces the stored values with the current live values.
• Reset to Defaults restores the factory defaults and keeps the Enabled When Triggered setting.

When executed, numerical properties and color values interpolate smoothly over 0.4 seconds, while discrete modes and switches toggle instantaneously.

Temporary EffectCopy Anchor Link

Temporary Effect has the same controls as Apply Effect Settings, plus Fade In (Seconds) and Fade Out (Seconds), up to 10 seconds each. A new clip lasts 5 seconds with 0.4-second fades, and the two fades together can't be longer than the clip.

While the clip plays, its stored values take over the effect, fading in at the start and out before the end. Then the effect returns to its scene settings.

• Temporary values are never saved to the scene file.
• If you adjust the effect manually during a run, the automation yields control of that effect until the next run.

Switch SceneCopy Anchor Link

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 raising 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 PresetCopy Anchor Link

Apply Preset has a Preset picker listing the target scene's saved scene presets; if the automation includes Switch Scene, it lists the destination scene's presets. When the action runs, layers move with the preset's own transition.

• If the preset no longer exists in the target scene, the row shows 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 PositionCopy Anchor Link

A new Camera Position action records the stage camera's active viewpoint, allowing direct parameter editing in the inspector:

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 MotionCopy Anchor Link

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 FollowCopy Anchor Link

Camera Follow makes the camera frame a layer or the Primary Model and follow it as it moves; choose None to stop following.

Its settings match Camera: Follow: Layer, Anchor (a bone or the root), Rotation (Ignore / Yaw / Yaw and Pitch / Yaw, Pitch, and Roll / Lazy Follow), and Damping. Copy from Current Stage copies the viewport camera's current follow settings.

Camera AimCopy Anchor Link

Camera Aim turns the camera in place to keep a layer or the primary model in a chosen region of the screen; choose None to return to the standard look-at point.

Its settings match Camera: Aim: Layer, Anchor, Screen Position (Screen X and Y), Dead Zone, Soft Zone, Bias, Damping, and Lookahead. Copy from Current Stage copies the current aim settings.

Camera FocusCopy Anchor Link

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 MovementCopy Anchor Link

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 AudioCopy Anchor Link

Play Audio triggers audio playback from the Inventory's Audio repository:

The fade-in applies to the start of the first play, and the fade-out to the end of the last repeat. Looped audio fades out only when it's stopped.

When Triggered Again sets what happens if the action fires while its earlier playback is still going:

• Restart Playback starts the track over from the beginning.
• Overlap plays another instance alongside the first.
• Keep Playing ignores the new trigger and lets the current playback continue.

Separate actions that play the same audio file don't affect each other.

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 shows the playback state and elapsed time, plus the current play when repeating (such as Play 2/3). The states are Loading…, Playing, Looping, Paused, Stopping…, Completed, Stopped, and Failed. Audio stops when its timeline clip ends.

Control Audio sends Pause, Resume, or Stop (the default) to every playing instance of an audio file, whether an automation or the Inventory started it. With Stop, each instance plays its fade-out before it ends.

Set TextCopy Anchor Link

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.

LyricsCopy Anchor Link

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, 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 before starting.

Avatar ActionsCopy Anchor Link

Toggle Expression, Play Motion, Clear All Expressions, Swap Model, and Model Position act on the avatar chosen under Avatar: a specific avatar layer, or Primary Model for whichever avatar is primary.

The expression picker and the Live2D motion picker read the model's metadata directly, so the model doesn't need to be on stage. For VRM, click Choose Motion… to pick a motion from the Inventory: the bundled motions, or your own clips imported with 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 simulate physics before the jump point.

Timeline EditorCopy Anchor Link

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 has:

• On the left: Undo Timeline Edit, Redo Timeline Edit, Split at Playhead, Duplicate Selected Actions, Delete Selected Actions, and Add Marker
• On the right: Play (which turns into Pause while playing), Stop, and Close Timeline Editor

Below the toolbar, the action list sits on the left and the tracks on the right, under a timecode scrub bar.

The property strip below the tracks sets times in seconds: Start, plus End and Duration for clips, and Source In for media. Use Source Length resets a media or lyrics clip to its source's full length.

Neither of the following changes playback:

• Lock Timing protects an action from accidental moves or trims.
• Add Marker places markers to snap to and jump between.

Drag an action's handle to reorder the tracks, and drag the divider to resize the list.

Timeline edits follow these rules:

• Moving, trimming, or deleting a clip leaves the other clips in place, and gaps are not closed up.
• Split at Playhead cuts the selected clips in two at the playhead. Clips can't be split inside a fade.
• Clips that drive the camera, the same avatar's motion channels, the same effect, or the same text layer can't overlap. Overlapping clips turn red, and the automation can't run until you fix them.
• Every edit adds an undo step. Undo and redo with ⌘ + Z / ⌘ + Shift + Z on macOS, or Ctrl + Z / Ctrl + Y on Windows and Linux.
• A run that is already playing keeps using the snapshot taken when it was triggered.

The Timeline Settings gear menu in the bottom-right corner configures:

With Preview on Stage enabled, Layer Visibility rows (as well as layer visibility changes inside Apply Preset) chase the playhead position: scrubbing previews each targeted layer's visibility on stage at that timestamp without saving it to the scene, while the eye icon in the Layers list keeps showing its saved state until playback actually writes it. If you manually change a layer's saved visibility during playback or preview (via the eye icon, a scene preset, or the Plugin API), the automation yields control of that layer back to the scene until Stop, Play, or an edit to the automation.

Clicking Play runs setup actions first (when starting from a stopped state or after setup edits), commits any chased layer visibility that differs from the scene, and plays through to the end of the sequence from the playhead position, even when the automation is disabled or cooling down; clicking Pause lets you resume from that point. Clicking Stop halts playback, mutes audio, fades out active animations, revokes temporary effects and previewed layer visibility, and resets the playhead to 0 seconds. Scrubbing the playhead does not evaluate setup actions or cues other than layer visibility.

Running an AutomationCopy Anchor Link

Besides its triggers, an automation can be run from:

• The card's options menu: Run Automation
• Studio Mode: select an automation in Camera Settings to record it into a video from its first frame to its last
• The Web Console: the Automations page
• Stream Deck: the Run Automation key
• The Plugin API and MCP Server: automation.run (plus automation.control for timeline transport)

None of these uses a keyboard shortcut, which makes them a good fit for hardware macro pads. Besides editing in the desktop app, clients on hosts with the automation-editing and automation-transport capabilities can also read, create, update, delete, and transport-control automations over the Plugin API (automations created via the API start disabled with no shortcut). A disabled automation cannot be triggered via automation.run or external hotkeys, but can still be auditioned from the desktop timeline editor or via automation.control.

Executing an automation runs setup actions before 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 (for example, Switch Scene activating an automation listening for scene changes, or Play Motion and Swap Model triggering Motion Playback and Model Loaded), but each automation runs at most once per execution chain to prevent infinite loops. Manual clicks, keys, API requests, and sensor inputs initiate distinct execution chains, whereas timeline scrubbing triggers no automations.

Import and ExportCopy Anchor Link

The Import and Export toolbar above the list has Import Automations and Export All; to export a single automation, use Export Automation in its card menu.

The exported JSON holds the actions, their timing, the triggers, and the cooldown. It refers to scenes, layers, models, and audio files by UUID and doesn't include the media itself. Exported files declare the official JSON Schema, so editors such as VS Code can validate them as you type.

Import Automations validates the file structure before 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 scenes, models, or media missing on this computer show warnings until you reassign them; check the targets before enabling the automation.

Avatar ShortcutsCopy Anchor Link

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, so your mappings 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 ShortcutCopy Anchor Link

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:

These actions apply directly to the model regardless of format, including VRM blendshapes and animations. For Toggle Expression and Play Motion, you can also bind or edit the primary shortcut directly from any expression or motion button's dropdown menu in the model panel via Set Shortcut… (or the Set Shortcut submenu on multi-file motion groups), or inside the Live2D Expression Editor and Motion Recorder/Editor. 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.

No shortcut fires while the recorder is open, so pressing an already bound combination records it in the dialog instead of triggering its action.

The recorder also accepts game controllers, supporting up to three inputs from a single device, including analog sticks, D-pad directions, and triggers (see Controller Shortcuts).

A combination holds up to three keys and mouse buttons, mixing modifiers, regular keys, and the left, middle, and right mouse buttons freely: two regular keys such as E + 1, a lone modifier, or a single mouse button all work. The limit matches the three trigger slots VTube Studio gives each hotkey, so such combinations shipped with VTube Studio models work once imported. A combination is matched as the set of inputs held, whatever the order: E + 1 and 1 + E are the same combination, and the duplicate warning treats them that way. Modifiers display first and the rest keep the order they were recorded or written in the file; modifier keys follow platform conventions, displaying as ⌥ and ⌘ on macOS rather than Alt and Win.

The recorder captures everything held at each press, in press order; click inside the dialog (anywhere but its buttons and footer row) to record a mouse button. A modifier records on its own only when pressed and released untouched, so pressing a chord such as ⌘/Ctrl + Enter never leaves a bare modifier bound. Controller buttons combine only with buttons on the same controller, never with keys or mouse buttons.

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 OptionsCopy Anchor Link

Expression and motion shortcuts expose advanced playback parameters in their option menus, matching identical VTube Studio settings and maintaining configuration interoperability across both platforms:

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: the expression fades out as soon as any key in the combination comes up. Keyboard, mouse, and controller shortcuts all see the release, whether or not they run in the background. 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 ShortcutsCopy Anchor Link

Each automation and avatar shortcut provides a Run in Background menu toggle, determining whether combinations fire while other applications have desktop focus. Shortcuts that currently fire in the background display a globe icon.

Persona never registers global hotkeys with the operating system; it reads key state instead, so any combination (including a bare key) can run in the background. The focused app still receives every keystroke, nothing is intercepted, and no other app can hold a combination away from Persona. macOS requires no Input Monitoring permission. Mouse buttons and controller combinations follow the same rules.

• A bare key running in the background also fires while you type in other apps. If that's unwanted, turn off Run in Background for it or bind a combination with a modifier. A lone mouse button bound this way fires on every click in any app.
• Shortcuts with Run in Background off respond only while Persona's stage or Control Panel window is in focus.
• Typing into a Persona text field fires no shortcut.
• Wayland offers no way to read key state, so every shortcut works only while the stage window is in focus, and combinations with a mouse button never fire.
• Mouse buttons are polled, so a press shorter than one poll (about 16 ms), such as a trackpad tap, may go unseen, as in VTube Studio.
• On a Mac with a non-QWERTY layout, a letter key fires at that letter's position on the US layout, which may differ from the label on the keycap.

When Two Shortcuts Share a CombinationCopy Anchor Link

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 on different models that share a combination run together on their respective models, which is useful for synchronizing an avatar with an independent hand prop. 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.

A combination fires when its last key goes down. Like VTube Studio, avatar shortcuts ignore other keys held at the same time (for example, holding Shift and pressing W still triggers an avatar shortcut bound to W, which keyboard- and WASD-controlled models rely on). An automation instead requires the exact modifiers in its binding, and only takes precedence over avatar shortcuts when those modifiers match.

Shortcuts incorporate hardware-level de-bounce protection, firing once per press rather than repeating while held.

Where They Are StoredCopy Anchor Link

Persona updates these configuration files in place, preserving unrecognized fields. Hotkeys referencing unsupported VTube Studio actions appear greyed out as unsupported, never run, and remain untouched on disk so existing VTube Studio setups stay intact.

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.