Song Requests

Song helpers let code show or manage Kicklet's song request queue. Use them for song request commands, queue management commands, or custom responses that mention the current song.

Request a Song

Adds a song request from a YouTube URL, video ID, or search term. maxSeconds is optional; use 0 or omit it when no duration limit should be applied.

Engine v2

Adds a song request from a YouTube URL, video ID, or search term.

API reference

songs.request

songs.request(username, query, maxSeconds?)

Input

username

string

Viewer username.

query

string

YouTube URL, video ID, or search term.

maxSecondsoptional

number

Maximum song duration in seconds. Use 0 or omit it for no duration limit.

Output

object

Song request result.

Request song resultAdvanced Script

const result = songs.request(sender.username, command.argsText(0), 300);
async.messages.send(`Added song at position ${result.position}.`);

Engine v1

Advanced Script:

const sender = $event.getSender();
Kicklet.songRequest(sender, "never gonna give you up", 300).then((resp) => resp.data.position);

Current Song

Reads the current song from Kicklet's song request system.

Engine v2

Reads the current song from Kicklet's song request system.

API reference

songs.current

songs.current()

Input

This helper does not take input parameters.

Output

object

Current song object.

Current song titleAdvanced Script

const song = songs.current();
async.messages.send(`Current song: ${song.title}`);

Engine v1

Current song: {{kicklet.CurrentSongTitle}}

Advanced Script:

Kicklet.getCurrentSong().then((resp) => resp.data.title);

Skip Current Song

Removes the current song from the queue.

Engine v2

Removes the current song from the queue.

API reference

songs.skip

songs.skip()

Input

This helper does not take input parameters.

Output

boolean

True when the skip request completed.

Skip songAdvanced Script

songs.skip();
async.messages.send("Skipped the current song.");

Engine v1

Advanced Script:

Kicklet.skipSong();

Clear Song Queue

Removes all song requests from the queue.

Engine v2

Removes all song requests from the queue.

API reference

songs.clear

songs.clear()

Input

This helper does not take input parameters.

Output

boolean

True when the clear request completed.

Clear song queueAdvanced Script

songs.clear();
async.messages.send("Song queue cleared.");

Engine v1

Advanced Script:

Kicklet.clearSongRequests();

Async song wrappers

Async wrapper for songs.request(username, query, maxSeconds?).

API reference

async.songs.request

async.songs.request(username, query, maxSeconds?)

Input

username

string

Viewer username.

query

string

YouTube URL, video ID, or search term.

maxSecondsoptional

number

Maximum song duration in seconds. Use 0 or omit it for no duration limit.

Output

object

Song request result.

Async wrapper for songs.current().

API reference

async.songs.current

async.songs.current()

Input

This helper does not take input parameters.

Output

object

Current song object.

Async wrapper for songs.skip().

API reference

async.songs.skip

async.songs.skip()

Input

This helper does not take input parameters.

Output

boolean

True when the skip request completed.

Async wrapper for songs.clear().

API reference

async.songs.clear

async.songs.clear()

Input

This helper does not take input parameters.

Output

boolean

True when the clear request completed.