This is an extension/plugin for SAMMI that allows one to control Denchisoft's VTubeStudio using their API I slapped this together for a friend in like two days and, although it could be a lot better or improved, it seems to work.
The source code is available for viewing; feel free to look through it, get a third party consultation, or reach out to myself about any security or other concerns regarding this extension's operation. Furthermore, I am not responsible for any end-user's actions regarding the use of this extension.
Please feel free to submit a bug report or to DM me directly on Twitter if you need help or have questions. Twitter/@Hue_SwordDevil
- VtubeStudio - Request Token
- VtubeStudio - Authenticate
- VtubeStudio - Get VTS Info
- VtubeStudio - Load Model
- VtubeStudio - Pull Value
- VtubeStudio - Move Model
- VtubeStudio - Send Hotkey
- VtubeStudio - Send Hotkey (Item)
- VtubeStudio - Send Hotkey
- VtubeStudio - Get Items List
- VtubeStudio - Load Item
- VtubeStudio - Move Item
- VtubeStudio - Control Animation
- VtubeStudio - Remove Item
- VtubeStudio - Get Expression State
- VtubeStudio - Toggle Expression
- VtubeStudio - Listen to Event
- VtubeStudio - Unsubscribe from Event
This extension requires the following:
- VTube Studio 1.21.5
- SAMMI (any version) (We no longer support Lioranboard 2, please refer to version v1.1.0.0)
⚠️ UNINSTALL OLD VERSIONS OF THE EXTENSION. DO NOT SELECT [REINSTALL]- Download the sef file (SAMMI Extension File)
- In SAMMI's main UI, Click on [Bridge] and Select [Install an extension]
- Navigate to the downloaded sef file and select it
- The Bridge MUST be opened for the extension to even load commands, much less work at all.
- When the Bridge has connected to SAMMI, the extension will insert the VtubeStudio Extension commands
- You need to set up a button (or use one fromt he example deck) to trigger an authetication request between SAMMI and VtubeStudio
- You will see a prompt in VTubeStudio for SAMMIVtubeStudioExtension. Click [Allow].
- From here, you should see in the SAMMI alerts area that the extension successfully authenticated. Note* You do not need to request a new token each time you launch, but you need to re-authenticate. I suggest doing this with a saved token.
This guide assumes that you are familiar with SAMMI/LioranBoard 2's Deck, Button, and Commands system(s). We will not go into detail on basic setup.
| Param | Description |
|---|---|
| None | None |
Uses a token to authenticate with the VTS API Server.
If successful, sets global.SAMMIVtubeStudioExtension_IsAuthenticated to 1. Otherwise, 0.
| Param | Description |
|---|---|
| None | None |
Allows one to pull info about the connection to VtubeStudio and some stats/metrics
| Param | Description |
|---|---|
| Variable Name | Variable to save the response into |
| Pull Value | Response Property. Leave blank to save entire response or select a property from the dropdown |
| Delay (ms) | Native to SAMMI |
Loads a model specified by the user, from a select list. The extension must be authenticated in order for the command to load.
| Param | Description |
|---|---|
| Model to Load | Model to load, from a dropdown list |
| Delay (ms) | Native to SAMMI |
Pulls data about the currently loaded model.
| Param | Description |
|---|---|
| Variable | Variable to save the response into |
| Pull Value | Response Property. Leave blank to save entire response or select a property from the dropdown |
| Global | Checkbox. If true, variable will be inserted into the global object |
| Delay (ms) | Native to SAMMI |
This one is a little finicky and requires some trial and error. It works, but the numbers that you need to supply are a little particular. (Hint) You can actually use this in conjuction with [VtubeStudio - Pull Value] to move a model and then return the model to its original positon using [modelPosition].
| Param | Description |
|---|---|
| PositionX | Numerical value representing model's position on the X-axis. Try -1 to 1. |
| PositionY | Numerical value representing model's position on the Y-axis. Try -1 to 1. |
| Size | Numerical value representing model's scale. -50 seems like a normal value while -80 seems really small. |
| Rotation | Numerical value representing degrees of rotation. 0 - 360. I think 359 will cause a spin, but 360 does nothing if your model is alright upright? |
| Time (0-2) | Numerical value representing how long the transition should take to finish, in seconds. Only accepts 0 - 2 |
| Relative Values | If checked off, the values will be added to the model's current position. |
| Dev Note | Ignore. Just a comment. |
| Delay (ms) | Native to SAMMI |
Triggers a hotkey. Note that you will get an error if you attempt to trigger a hotkey on a model that is not currently loaded. However, SAMMI will not crash.
| Param | Description |
|---|---|
| Hotkey | Hotkey to trigger, from a select list. |
| Delay (ms) | Native to SAMMI |
This is the same as the Send Hotkey command, but allows one to include an instance ID. This is to allow you to trigger the hotkeys of items loaded into the scene. Note that you will get an error if you attempt to trigger a non-existent hotkey for a item.
| Param | Description |
|---|---|
| InstanceID | InstanceID of the item to be triggered (Note that this is not the name of the item. You can get the instanceID of an item using [VtubeStudio - Get Items List] and checking off [includeItemInstancesInScene]) |
| Hotkey | Hotkey to trigger. |
| Delay (ms) | Native to SAMMI |
This is the same as the Send Hotkey command, but you specify the hotkey by text without needing to specify the model. This is to allow you to trigger the hotkeys of the currently loaded model and is useful for simplifying your SAMMI commands, where you want a single command to trigger a common hotkey between many models. For instance, if you have seven models and they all have the hotkey "headpat", with this, you just need one command and it will work no matter which model is loaded. Note that you will get an error if you attempt to trigger a non-existent hotkey or a item.
- Note - this command does pre-request the hotkeys of the model that is loaded, so there is a brief delay between the SAMMI button trigger and the actual firing of the hotkey, compared to the normal send hotkey command.
| Param | Description |
|---|---|
| HotkeyName | Hotkey to trigger. Case is ignored. |
| Delay (ms) | Native to SAMMI |
| Param | Description |
|---|---|
| Variable | Variable to save the response into |
| includeAvailableSpots | Checkbox. If true, will return an array of numbers representing currently available order-spots, -30 to 30. |
| includeItemInstancesInScene | Checkbox. Returns an array of items are currently loaded in the scene. |
| includeAvailableItemFiles | Checkbox. Returns an array of item files that are available to be loaded. |
| onlyItemsWithFileName | Filter for only returning items with a specific file name. Case sensitive. |
| onlyItemsWithInstanceID | Filter for only returning items with a specific instance ID. Case sensitive. |
| Delay (ms) | Native to SAMMI |
Loads a specified item into the scene.
Moves an existing/already loaded scene item.
Controls the animation and other visual details of a loaded Scene Item.
Removes a loaded Scene Item.
Requests the state of all expressions for the currently loaded model. One may request a single expression if they include the name of a single expression file. You may check off Details to include more information per expression. You will want to provide a variable name that the command will save the response data into.
Toggles a single specific expression on the model. The command takes in a variable value for the On/Off state. So you may enter in "true" or "false" or, more useful in certain cases, a boolean variable.
| Param | Description |
|---|---|
| Event | Select. The event to subscribe to |
| Variable | Variable to save the response into |
| Delay (ms) | Native to SAMMI |
| Param | Description |
|---|---|
| Event | Select. The event to unsubscribe from |
| Variable | Variable to save the response into |
| Delay (ms) | Native to SAMMI |
These are valid events that the extension will fire. Enter one of these strings into the text box of the Extension Trigger type Trigger of a Button
- VTSEvent - TestEvent
- VTSEvent - ModelLoadedEvent
- VTSEvent - TrackingStatusChangedEvent
- VTSEvent - BackgroundChangedEvent
- VTSEvent - ModelConfigChangedEvent
- VTSEvent - ModelMovedEvent
- VTSEvent - ModelOutlineEvent
SAMMI Bridge needs to be open and connected to SAMMI Client.
WIP