VTube Studio actions¶

CroStream can do nineteen things in VTube Studio: run a hotkey, put a clown nose on your model, tint it red, drop a viewer's emote into the scene, turn on a glitch effect and more. Each one is an action you add as a step in a macro; the Actions page lists them under VTube Studio in seven groups and lets you try each one with Run now.

New here? Set up the connection first. Props need anchors. For ready-made macros, see Recipes.

Before you start¶

• CroStream must be connected to VTube Studio, with a model loaded for anything that touches the model. Without a connection every action fails with CroStream isn't connected to VTube Studio. See Troubleshooting.
• Settings take {variables} in Text and Pick fields (not in the media library image field). A number field can be {amount} or a literal 0.5. A value that can't be checked until the macro runs (it holds a {variable}) is checked at that moment instead of when you save.
• Leave a number empty where the details say so, and that part is left as it is.
• Two permissions are separate from the connection: loading custom images (item drops and props that use your media library or an emote) and controlling NDI. You grant each once in VTube Studio; see Permissions.
• Timed changes: many actions can undo themselves after a while. See Undoing after a while.

All actions¶

How to read the tables: Type is the kind of field (Text takes {variables}, Pick is a list CroStream fills from VTube Studio, Choice is a fixed list, Duration is written like 10s or 2m, On/off is a switch, List takes one entry per line). Default is what the editor starts with. Outputs are variables later steps can use, such as {item_id}.

Hotkeys and expressions¶

Trigger a VTube Studio hotkey¶

ID vtubestudio.hotkey

Runs one of the hotkeys set up on your VTube Studio model: an animation, an expression, a background change, a screenshot and so on. This is the most direct way to reuse everything you already built in VTube Studio.

Limits. VTube Studio runs one specific hotkey at most once every five frames, and keeps a queue of 32 for different hotkeys sent in quick succession. If it answers wait or queue full, CroStream waits a moment and tries again, up to four more times, before it gives up with VTube Studio asked to wait a moment or VTube Studio's hotkey queue is full. A hotkey needs a loaded model.

Example: a channel point reward runs the hotkey Wave.

Turn a VTube Studio expression on or off¶

ID vtubestudio.expression

Switches one of your model's expressions on, off, or flips it, and can put it back after a while.

CroStream asks VTube Studio whether the expression is on right now, so toggle and Turn it back after act on the real state. If the expression is already how you asked, nothing is scheduled to undo. The model must have the expression; otherwise the step fails with No expression name on model.

Model¶

Move, turn or resize the model¶

ID vtubestudio.model_move

Moves, rotates or resizes your model on screen, either by an amount or to a place, and can put it back afterward.

At least one of Across, Up and down, Rotation or Size must be set. With Move back after, CroStream reads the model's position first and returns it to exactly that, taking the same move time. A move back is cancelled if you load a different model in the meantime.

Example: relative, Rotation 20, Move back after 3s tilts the model for three seconds.

Load a VTube Studio model¶

ID vtubestudio.model_load

Switches VTube Studio to another of your models, and can switch back after a while.

Limits. VTube Studio allows one model load every two seconds and refuses while a settings window is open or another load is running. CroStream spaces its own loads and, if VTube Studio still asks to wait, waits two seconds and tries once more. If the model is already loaded the step succeeds and does nothing, and no switch back is scheduled.

Physics gust¶

ID vtubestudio.physics

Turns the model's hair and clothing physics up (or down) for a while, like a gust of wind.

Set the strength, the wind, or both. VTube Studio lets one override last only 0.5 to 5 seconds, so for longer gusts CroStream sends it again every four seconds until the time is up. A newer gust ends an older one. Only one plugin can control physics at a time; if another one does, the step fails with Another plugin is controlling VTube Studio's physics (name). A model without physics fails with This model has no physics. When the time is up, VTube Studio returns to normal by itself.

Tint the model¶

ID vtubestudio.tint

Colors the whole model, or just some of its parts, and can undo it after a while.

Choose the whole model, or at least one ArtMesh, tag or group. Any part that matches any of the lists is tinted.

If no ArtMesh matches, the step fails with No ArtMesh matched. A running tint is reset when CroStream disconnects or when you use Reset everything CroStream changed on the VTube Studio page. When several plugins tint the same part, the most recent request wins.

Items¶

Items are the extra things in VTube Studio's scene: pictures, GIFs, Live2D items and props. These actions add, move, animate, pin, sort and remove them. Item actions take an item's instance ID, which the action that created it reports ({item_id}), so chain them in one macro.

Drop an item into VTube Studio¶

ID vtubestudio.item_drop

Adds an item to the VTube Studio scene: one from its Items folder, an image from your media library, or a Twitch emote.

random for a position picks a spot between -0.9 and 0.9 (for rotation, 0 to 360) so the item lands on screen.

Limits. VTube Studio's scene can hold only so many items; when it is full the step fails with VTube Studio's scene is full of items. Remove some first. If you turn off Remove when CroStream disconnects, the item stays after CroStream disconnects, and a Remove after timer is kept and carried out when CroStream reconnects.

Example: when a viewer redeems Confetti, drop confetti.png at Across random for 5s.

Remove items from VTube Studio¶

ID vtubestudio.item_remove

Takes items out of the VTube Studio scene: one you name, every copy of a file, everything CroStream added, or everything.

all removes items you added by hand in VTube Studio too. There is also a Remove CroStream's items button on the VTube Studio page.

Move an item¶

ID vtubestudio.item_move

Slides, resizes or turns items that are in the scene. Leave a field empty to leave that part as it is.

If some of several items can't be moved (gone from the scene), the step fails and lists which ones, noting how many did move.

Control an item's animation¶

ID vtubestudio.item_animate

Plays, stops or changes the speed, frame, brightness or opacity of an animated item (a GIF, for example). Leave a field empty to leave it.

Live2D items can't be animated this way (Use their hotkeys; see Trigger a hotkey). A still image fails with This image isn't animated if you set playback or frames; only brightness and opacity apply.

Pin or unpin an item on the model¶

ID vtubestudio.item_pin

Sticks an item to a part of your model so it moves with it, or lets it go.

Use it right after Drop an item, passing {item_id}, to put a viewer's emote on your head. For a quick temporary picture on a named part, Put on a prop does the drop, pin, sort and removal in one step. If the anchor's part is no longer on the model (you changed models or rigs), the step fails with a message naming the ArtMesh and the anchor, telling you to set that anchor again.

Put an item between the model's layers¶

ID vtubestudio.item_sort

Decides whether an item is drawn in front of or behind your model, or between two of its parts.

Props¶

Put on a prop¶

ID vtubestudio.prop

Puts an image on a part of your model for a while, like a clown nose on your nose or a hat on your head, then takes it off. This one step loads the image, pins it to a named anchor, draws it in front of the model and removes it after the time you set.

How it behaves.

• The anchor is looked up for the model that is loaded. An anchor named nose set for one model does not exist for another, and the step fails with No "nose" anchor for model Akari. On CroStream's VTube Studio page, add it and pick the part. This is checked before any image work.
• Replace is per anchor: a new prop on nose removes the old one on nose, but only after the new one loaded, so a failed load leaves the old prop on. Props on different anchors stay together.
• Props use Remove when CroStream disconnects, so VTube Studio clears them if the connection drops.
• If putting the prop in front fails, you get a note in the feed and the prop stays where VTube Studio placed it.

Example: Image from chat_emote, Anchor nose, For how long 8s, on a Chat command event, turns a viewer's emote into a nose for eight seconds.

Effects¶

Turn a visual effect on or off¶

ID vtubestudio.effect

Switches one of VTube Studio's visual effects (bloom, glitch, rain and so on) on, or off, optionally for a limited time.

If VTube Studio doesn't know the effect the step fails with No effect named name in VTube Studio. Restricted effects fail with That effect is restricted until you allow them in VTube Studio and turn on Restricted effect. With For how long, CroStream saves the current effects (including a loaded preset) and restores them afterward, not just this one effect.

Set VTube Studio's effects¶

ID vtubestudio.post_processing

Loads an effects preset, sets individual effect values, randomizes the effects, or turns them all on or off. VTube Studio calls this post-processing.

on and off switch effects as a whole without changing their settings. VTube Studio takes effect updates one at a time, so CroStream spaces them by a third of a second. An unknown preset fails with No effects preset named name, and a setting ID or value VTube Studio rejects with VTube Studio doesn't know one of those effect settings, or a value doesn't fit it.

Parameters¶

Tracking parameters are the numbers that drive your model: mouth open, eye smile, head angle, plus custom ones that models and other plugins define.

Set a tracking parameter for a while¶

ID vtubestudio.parameter

Holds one of VTube Studio's tracking parameters at a value for a while, overriding what the camera sees.

CroStream keeps sending the value until the time is up. When it ends, tracking takes over again. If another plugin already controls the parameter, the step fails with Another plugin is already setting name. Use mode add, or stop the other plugin. A name VTube Studio doesn't know fails with No parameter name in VTube Studio. Face found helps if you want a model to keep animating while your camera sees no face.

Create a custom parameter¶

ID vtubestudio.parameter_create

Adds a custom tracking parameter to VTube Studio that models and other plugins can use.

The parameter is yours until deleted. A name that another plugin owns, or that is one of VTube Studio's own, is refused with a message saying so.

Delete a custom parameter¶

ID vtubestudio.parameter_delete

Removes a custom parameter that CroStream created.

Deleting one that is already gone succeeds (already gone). One that belongs to another plugin fails with That parameter belongs to another plugin.

Advanced¶

Change VTube Studio's NDI output¶

ID vtubestudio.ndi

Turns VTube Studio's NDI video output on or off, switches NDI 5, or sets a custom output size. Needs the Control NDI permission.

Change at least one setting. VTube Studio only allows an NDI change every three seconds; if it says wait, CroStream waits and tries once more. A bad size fails with Width must be a multiple of 16 and height of 8, from 256 to 8192.

Image sources¶

Drop an item and Put on a prop show an image chosen by Image from:

Custom images (media, emote, chat_emote) are sent to VTube Studio as data. CroStream prepares them first:

• PNG, JPG, GIF and WebP (and BMP) are accepted. Anything else fails with This image type isn't supported; use PNG, JPG, GIF or WebP.
• Input up to 20 MB is read; VTube Studio accepts up to 5 MB, 64 to 2048 pixels on a side. CroStream resizes and re-encodes stills and GIFs as needed. An image that is still too big afterward fails with This image is too large for VTube Studio (5 MB max), and a GIF that is still too big, or has more than 1024 frames, with This GIF is too large for VTube Studio (5 MB max).
• A very thin image fails with This image is too thin to show. A huge one fails with has too many pixels to read.
• The same picture is only sent once per VTube Studio session.
• Ask in VTube Studio first makes VTube Studio show a window asking you to allow a custom image. It asks the first time only: VTube Studio remembers images you allowed (by their content), so the same picture is not asked about again. VTube Studio shows at most six such questions at once; more fail until you answer. Declining fails with The image was declined in VTube Studio. The question waits up to 30 seconds. If the macro step has less than about 8 seconds left, the step fails with There is not enough time left to ask in VTube Studio.

Permissions¶

Two things need a permission you grant once in VTube Studio:

On CroStream's VTube Studio page, click Ask in VTube Studio next to the permission, then Allow in VTube Studio. Until then those actions fail with a message naming the exact button. Everything else needs no extra permission.

Undoing after a while¶

Actions with a timer (Turn it back after, Move back after, Switch back after, Put back after, Remove after, Remove the tint after, For how long) put things back by themselves.

• Changes VTube Studio undoes itself when CroStream disconnects (items loaded with remove on disconnect, tints, held parameters, props) are simply dropped from CroStream's timers on disconnect.
• Changes VTube Studio would not undo (expression, model position, model load, effects, and items with remove on disconnect off) are kept. If the timer ends while you are disconnected, CroStream puts things back as soon as it reconnects, unless it was disconnected too long, in which case it skips the undo and tells you in the Activity feed. When CroStream quits, pending undos are run first.
• If you load a different model before the timer ends, undos tied to the old model (an expression, a model move, a tint) are dropped.
• Starting the same kind of change again (the same expression, a second move back) keeps the first undo with the new deadline.
• Reset everything CroStream changed on the VTube Studio page runs all pending undos now, stops held parameters, removes CroStream's items and clears tints.

Related¶

• Triggers: the events VTube Studio sends
• Props & anchors
• Recipes
• Troubleshooting
• Actions reference: all settings in the standard format