Hotkeys Guide

This guide covers working with hotkeys in VTube Studio.

Getting Hotkeys

To get a list of hotkeys for the current model:

response = await vts.request_hotkeys_in_current_model()
hotkeys = response.data

for hotkey in hotkeys:
    print(f"Hotkey: {hotkey.name}")
    print(f"  ID: {hotkey.hotkeyID}")
    print(f"  File: {hotkey.file}")

Triggering Hotkeys

To trigger a hotkey:

from vtpy.data.requests import HotkeyTriggerRequestData

response = await vts.request_hotkey_trigger(
    HotkeyTriggerRequestData(hotkeyID="hotkey-id-here")
)

if response.data:
    print("Hotkey triggered successfully")

Listening to Hotkey Events

You can listen to hotkey trigger events:

from vtpy.data.events import EventType, HotkeyTriggeredEvent

async def on_hotkey_triggered(event: HotkeyTriggeredEvent) -> None:
    data = event.data
    print(f"Hotkey triggered: {data.hotkeyID}")
    print(f"  Name: {data.hotkeyName}")

vts.on_event(EventType.HotkeyTriggeredEvent, on_hotkey_triggered)

# Subscribe to events
from vtpy.data.events import (
    HotkeyTriggeredEventSubscriptionRequestData,
)

await vts.event_sub_hotkey_triggered(
    HotkeyTriggeredEventSubscriptionRequestData(subscribe=True)
)

Complete Example

import asyncio
from vtpy import VTS
from vtpy.data.requests import HotkeyTriggerRequestData
from vtpy.data.events import (
    EventType,
    HotkeyTriggeredEvent,
    HotkeyTriggeredEventSubscriptionRequestData,
)

async def on_hotkey_triggered(event: HotkeyTriggeredEvent) -> None:
    print(f"Hotkey triggered: {event.data.hotkeyName}")

async def main():
    vts = VTS(plugin_name="MyPlugin", plugin_developer="MyName")

    try:
        await vts.start(host="localhost", port=8001)

        # Get available hotkeys
        hotkeys_response = await vts.request_hotkeys_in_current_model()
        print("Available hotkeys:")
        for hotkey in hotkeys_response.data:
            print(f"  - {hotkey.name} (ID: {hotkey.hotkeyID})")

        # Listen to hotkey events
        vts.on_event(EventType.HotkeyTriggeredEvent, on_hotkey_triggered)
        await vts.event_sub_hotkey_triggered(
            HotkeyTriggeredEventSubscriptionRequestData(subscribe=True)
        )

        # Trigger a hotkey (if you know the ID)
        # await vts.request_hotkey_trigger(
        #     HotkeyTriggerRequestData(hotkeyID="some-hotkey-id")
        # )

        print("Listening for hotkey events. Press Ctrl+C to stop...")
        await asyncio.Event().wait()

    except KeyboardInterrupt:
        print("Stopping...")
    finally:
        if vts.connected:
            await vts.close()

asyncio.run(main())