VTFTK

Types

SoundModel

Type Represents a sound within VTFTK

Property	Type	Description
id	string	ID of the sound
name	string	Name of the sound
src	string	URL for the sound file that can be played
volume	number	Volume the sound should be played at (0 - 1)
order	number	Order the sound is shown within the UI
created_at	string	ISO date time of when the sound was created

SoundSeq

Type Represents a sound in a sequence of sounds to play

Property	Type	Description
src	string	URL for the sound file that can be played
volume	number	Volume the sound should be played at (0 - 1)

ItemModel

Type Represents an item within VTFTK

Property	Type	Description
id	string	ID of the item
name	string	Name of the item
config	ItemConfig	Item configuration
order	number	Order the item is shown within the UI
created_at	string	ISO date time of when the sound was created
impact_sound_ids	string[]	List of IDs for the sounds that can play when this item impacts
windup_sounds_ids	string[]	List of IDs for the sounds that can play for this items windup

ItemConfig

Type Configuration for an item

Property	Type	Description
image	ItemImageConfig	Image config for the item
windup	ItemWindupConfig	Windup config for the item

ItemImageConfig

Type Image configuration for an item

Property	Type	Description
src	string	URL for the item image
weight	number	Weight of the item on impact
scale	number	Scale of the image
pixelate	boolean	Whether to pixelate when scaling

ItemWindupConfig

Type Windup configuration for an item

Property	Type	Description
enabled	boolean	Whether a windup is enabled
duration	number	Duration in milliseconds to windup for

ItemsWithSounds

Type Items with their loaded impact sounds

Property	Type	Description
items	ItemModel[]	List of items
sounds	SoundModel[]	List of impact sounds

BarrageConfig

Type Configuration for how a barrage is thrown

Property	Type	Description
totalAmount	number	Total number of items to throw for the barrage
amountPerThrow	number	Amount of items per throw of the barrage
frequency	number	The time between each barrage (ms)

Functions

playSound

Function (src: string, volume?: number) => Promise<void>

Tells the overlay to play a sound by URL

Argument	Type	Example	Description
src	string		URL of the sound to play
volume Optional	number	0.5	Optional volume to play the sound at (0 - 1) defaults to 1

// Use "await" to wait until the sound is queued (Almost immediate)
await api.vtftk.playSound("http://example.com/example.wav");

Tip

When playing multiple sounds that need to happen one after another ensure you use api.vtftk.playSoundSeq rather than api.vtftk.playSound as triggering api.vtftk.playSound with multiple sounds will cause them to all play at once

playSoundSeq

Function (sounds: SoundSeq[]) => Promise<void>

Tells the overlay to play a sequence of sounds one after another. Waits for the previous sound to complete before the next is started

Argument	Type	Example	Description
sounds	SoundSeq[]		List of sounds to play

// Use "await" to wait until the sound sequence is queued (Almost immediate)
await api.vtftk.playSoundSeq([
  {
    url: "http://example.com/example.wav",
    volume: 1,
  },
  {
    url: "http://example.com/example1.wav",
    volume: 1,
  },
  {
    url: "http://example.com/example2.wav",
    volume: 1,
  },
]);

playSoundByName

Function (name: string, ignoreCase?: boolean, volume?: number) => Promise<void>

Tells the overlay to play a sound by name (Sound must exist in VTFTK)

Argument	Type	Example	Description
name	string		Name of the sound to play
ignoreCase Optional	boolean		Whether to ignore case when matching the name (Default: false)
volume Optional	number	0.5	Optional volume to play the sound at (0 - 1) (Default: 1)

// Use "await" to wait until the sound is queued (Almost immediate)
await api.vtftk.playSoundByName("My Sound", true, 0.5);

playSoundByID

Function (id: string, volume?: number) => Promise<void>

Tells the overlay to play a sound by ID

Argument	Type	Example	Description
id	string		UUID of the sound to play
volume Optional	number	0.5	Optional volume to play the sound at (0 - 1) (Default: 1)

// Use "await" to wait until the sound is queued (Almost immediate)
await api.vtftk.playSoundByID(
  "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
  true,
  0.5
);

getSoundByName

Function (name: string, ignoreCase?: boolean) => Promise<SoundModel | null>

Get a sound by name(Sound must exist in VTFTK) returns a SoundModel or null if the sound does not exist

Argument	Type	Example	Description
name	string		Name of the sound to find
ignoreCase Optional	boolean		Whether to ignore case when matching the name (Default: false)

const sound = await api.vtftk.getSoundByName("My Sound", true);

if (sound === null) {
  // .. Sound doesn't exist
  return;
}

// .. inspect the sound src URL
console.log(sound.src);

// .. play the sound
await api.vtftk.playSound(sound.src, sound.volume);

getSoundsByName

Function (name: string, ignoreCase?: boolean) => Promise<SoundModel[]>

Gets multiple sounds by name (Sound must exist in VTFTK) returns a SoundModel list

Argument	Type	Example	Description
name	string		Name of the sound to find
ignoreCase Optional	boolean		Whether to ignore case when matching the name (Default: false)

const sounds = await api.vtftk.getSoundByName("My Sound", true);

if (sounds.length < 1) {
  // .. No sounds found
  return;
}

const firstSound = sounds[0];

// .. inspect the sound src URL
console.log(firstSound.src);

// .. play the sound
await api.vtftk.playSound(firstSound.src, firstSound.volume);

getSoundsByNames

Function (names: string, ignoreCase?: boolean) => Promise<SoundModel[]>

Gets multiple sounds from a collection of sound names (Sound must exist in VTFTK) returns a SoundModel list of all matching sounds

Argument	Type	Example	Description
names	string		Name of the sound to find
ignoreCase Optional	boolean		Whether to ignore case when matching the name (Default: false)

const sounds = await api.vtftk.getSoundsByNames(
  ["My Sound", "My Other Sound", "My Other Other Sound"],
  true
);

if (sounds.length < 1) {
  // .. No sounds found
  return;
}

const firstSound = sounds[0];

// .. inspect the sound src URL
console.log(firstSound.src);

// .. play the sound
await api.vtftk.playSound(firstSound.src, firstSound.volume);

getSoundByID

Function (id: string) => Promise<SoundModel | null>

Get a sound by ID (Sound must exist in VTFTK) returns a SoundModel or null if the sound does not exist

Argument	Type	Example	Description
id	string		ID of the sound to find

const sound = await api.vtftk.getSoundByID(
  "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
  true
);

if (sound === null) {
  // .. Sound doesn't exist
  return;
}

// .. inspect the sound src URL
console.log(sound.src);

// .. play the sound
await api.vtftk.playSound(sound.src, sound.volume);

getSoundsByIDs

Function (id: string) => Promise<SoundModel[]>

Gets multiple sounds by ID (Sound must exist in VTFTK) returns a SoundModel list

Argument	Type	Example	Description
id	string		ID of the sound to find

const sounds = await api.vtftk.getSoundsByIDs(
  [
    "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
    "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
    "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
  ],
  true
);

if (sounds.length < 1) {
  // .. No sounds found
  return;
}

const firstSound = sounds[0];

// .. inspect the sound src URL
console.log(firstSound.src);

// .. play the sound
await api.vtftk.playSound(firstSound.src, firstSound.volume);

getItemsWithSounds

Function (items: ItemModel[]) => Promise<ItemsWithSounds>

Loads the impact sounds for a collection of items returns a ItemsWithSounds list

This is only really intended to be used with throwBarrage, throwItems, and throwAll but using the ByNames (i.e throwAllByNames) and ByIds functions are preferred

Argument	Type	Example	Description
items	ItemModel[]		Item models to load the sounds for

const items = [
  /* ...The items here */
];

const itemsWithSounds = await api.vtftk.getItemsWithSounds(items);

// Throw the items
await api.vtftk.throwAll(itemsWithSounds, 10);

getItemByName

Function (name: string, ignoreCase?: boolean) => Promise<ItemModel | null>

Finds an ItemModel by name returning null if the model is not found

Argument	Type	Example	Description
name	string		Name of the item to find
ignoreCase Optional	boolean		Whether to ignore case when searching for the item (Default: false)

const item = await api.vtftk.getItemByName("My Item", true);

if (item === null) {
  // .. Item not found
  return;
}

// .. Work with the item

getItemsByName

Function (name: string, ignoreCase?: boolean) => Promise<ItemModel[]>

Finds any number of ItemModel by name

Argument	Type	Example	Description
name	string		Name of the item to find
ignoreCase Optional	boolean		Whether to ignore case when searching for the item (Default: false)

const items = await api.vtftk.getItemsByName("My Item", true);

if (item.length < 1>) {
  // .. No items found
  return;
}

// .. Work with the items

getItemsByNames

Function (names: string[], ignoreCase?: boolean) => Promise<ItemModel[]>

Finds any number of ItemModel from a collection of names

Argument	Type	Example	Description
names	string[]		List of item names to find
ignoreCase Optional	boolean		Whether to ignore case when searching for the item (Default: false)

const items = await api.vtftk.getItemsByNames(
    [
        "My Item",
        "My Item 1",
        "My Item 2"
    ],
    true
);

if (item.length < 1>) {
  // .. No items found
  return;
}

// .. Work with the items

getItemById

Function (id: string) => Promise<ItemModel | null>

Finds an ItemModel by ID returning null if the model is not found

Argument	Type	Example	Description
id	string		ID of the item to find

const item = await api.vtftk.getItemById(
  "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx"
);

if (item === null) {
  // .. Item not found
  return;
}

// .. Work with the item

getItemsByIds

Function (ids: string[]) => Promise<ItemModel[]>

Finds multiple ItemModels from a collection of IDs

Argument	Type	Example	Description
ids	string[]		IDs of the items to find

const items = await api.vtftk.getItemsByIds([
  "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
  "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
  "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
]);

if (items.length < 1) {
  // .. Items not found
  return;
}

// .. Work with the items

throwAllByIds

Function (ids: string[], amount?: number) => Promise<void>

Throws a bunch of items all at once from a collection of item IDs

Argument	Type	Example	Description
ids	string[]		IDs of the items to throw
amount Optional	number		Number of items to throw (Default: 10)

await api.vtftk.throwAllByIds(
  [
    "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
    "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
    "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
  ],
  10
);

throwAllByNames

Function (names: string[], ignoreCase?: number, amount?: number) => Promise<void>

Throws a bunch of items all at once from a collection of item names

Argument	Type	Example	Description
names	string[]		Names of the items to throw
ignoreCase Optional	number		Whether to ignore case when finding the items by name (Default: false)
amount Optional	number		Number of items to throw (Default: 10)

await api.vtftk.throwAllByNames(["My Item", "My Item 1", "My Item 2"], 10);

throwAll

Function (items: ItemsWithSounds, amount?: number) => Promise<void>

Throws a bunch of items all at once from a collection of item names

Argument	Type	Example	Description
items	ItemsWithSounds		Items to throw
amount Optional	number		Number of items to throw (Default: 10)

const items = [
  /* ...The items here */
];

const itemsWithSounds = await api.vtftk.getItemsWithSounds(items);

await api.vtftk.throwAll(itemsWithSounds, 10);

throwBarrage

Function (items: ItemsWithSounds, config?: BarrageConfig) => Promise<void>

Throws a barrage of items

Argument	Type	Example	Description
items	ItemsWithSounds		Items to throw
config Optional	BarrageConfig		Config for the barrage

const items = [
  /* ...The items here */
];

const itemsWithSounds = await api.vtftk.getItemsWithSounds(items);

await api.vtftk.throwBarrage(itemsWithSounds, {
  totalAmount: 15,
  amountPerThrow: 5,
  frequency: 100,
});

throwBarrageByIds

Function (ids: string[], config?: BarrageConfig) => Promise<void>

Throws a barrage of items by the IDs of the items to throw

Argument	Type	Example	Description
ids	string[]		IDs of the items to throw
config Optional	BarrageConfig		Config for the barrage

await api.vtftk.throwBarrageByIds(
  [
    "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
    "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
    "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
  ],
  {
    totalAmount: 15,
    amountPerThrow: 5,
    frequency: 100,
  }
);

throwBarrageByNames

Function (names: string[], ignoreCase?: boolean, config?: BarrageConfig) => Promise<void>

Throws a barrage of items by the names of the items to throw

Argument	Type	Example	Description
names	string[]		Names of the items to throw
ignoreCase	string[]		Whether to ignore case when finding items (Default: false)
config Optional	BarrageConfig		Config for the barrage

await api.vtftk.throwBarrageByNames(
  ["My Item", "My Item 1", "My Item 2"],
  true,
  {
    totalAmount: 15,
    amountPerThrow: 5,
    frequency: 100,
  }
);

throwItemsByIDs

Function (ids: string[], config: ThrowItemConfig) => Promise<void>

Throws items by IDs. Low level primitive for the throwBarrageByIds and throwAllByIds functions

Argument	Type	Example	Description
ids	string[]		IDs of the items to throw
config	ThrowItemConfig		Config for the throw

await api.vtftk.throwItemsByIDs(
  [
    "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
    "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
    "xxxxx-xxxxx-xxxxx-xxxxx-xxxxxxxxxxxx",
  ],
  {
    type: "Barrage",
    amount: 15,
    amount_per_throw: 5,
    frequency: 100,
  }
);

Tip

Its recommend to use throwBarrageByIds or throwAllByIds instead as this is a low level primitive for directly triggering a throw and is easy to do incorrectly.

throwItemsByNames

Function (names: string[], ignoreCase: boolean, config: ThrowItemConfig) => Promise<void>

Throws items by names. Low level primitive for the throwBarrageByNames and throwAllByNames functions

Argument	Type	Example	Description
names	string[]		Names of the items to throw
ignoreCase	boolean		Whether to ignore case when matching names
config	ThrowItemConfig		Config for the throw

await api.vtftk.throwItemsByNames(["My Item", "My Item 1", "My Item 2"], true, {
  type: "Barrage",
  amount: 15,
  amount_per_throw: 5,
  frequency: 100,
});

Tip

Its recommend to use throwBarrageByNames or throwAllByNames instead as this is a low level primitive for directly triggering a throw and is easy to do incorrectly.

throwItems

Function (items: ItemsWithSounds, config: ThrowItemConfig) => Promise<void>

Throws items. Low level primitive for the throwBarrage and throwAll functions

Argument	Type	Example	Description
items	ItemsWithSounds		Items to throw
config	ThrowItemConfig		Config for the throw

const items = [
  /* ...The items here */
];

const itemsWithSounds = await api.vtftk.getItemsWithSounds(items);

await api.vtftk.throwItems(itemsWithSounds, {
  type: "Barrage",
  amount: 15,
  amount_per_throw: 5,
  frequency: 100,
});

Tip

Its recommend to use throwBarrage or throwAll instead as this is a low level primitive for directly triggering a throw and is easy to do incorrectly.

triggerVTHotkey

Function (hotkeyID: string) => Promise<void>

Trigger a VTube Studio hotkey by ID.

Argument	Type	Description
hotkeyID	string	ID of the hotkey

// "await" to wait until the trigger is queued
await api.vtftk.triggerVTHotkey("HOTKEY ID");

Tip

See triggerVTHotkeyByName for triggering a hotkey by name rather than by ID if you don’t already know the ID in advance

triggerVTHotkeyByName

Function (hotkeyID: string, ignoreCase?: boolean) => Promise<void>

Trigger a VTube Studio hotkey by name.

Argument	Type	Description
hotkeyName	string	Name of the hotkey
ignoreCase Optional	boolean	Whether to ignore case when matching the hotkey name (Default: false)

// "await" to wait until the trigger is queued
await api.vtftk.triggerVTHotkeyByName("Bonk");