How to use TS3AudioBot

The Claytonia Gaming Teamspeak server uses TS3AudioBot for music. Below are helpful notes that I have taken to aid in the administration and usage of the bot. I've gone through the GitHub issues and Swagger API docs to find this info, and I wrote it all down for easy reference next time.

These are my personal notes and I want to share them publicly in an effort to help people use TS3AudioBot in the future.

If you have any questions, I'd be happy to help you set up or use the bot. You can find me on the Claytonia Teamspeak and Discord servers.

User Commands and General Usage:

Command Description Example


Plays a new song !play


!pause Pauses music !pause
!play Continues paused music !play
!stop Stops playing music !stop
!add Adds song to the queue !add
!next Plays next song in queue !next
!next 4
You can skip multiple songs at a time.
!skip Skips ahead by seconds.

!skip 300
Skips ahead by 5 minutes.

!previous Plays previous song in queue !previous
!help Shows a (hopefully) helping message

!help command list
!help command skip
!help command settings

!list import

Import a playlist from another source.

!list import LIST123

!list import adamradio /home/tsaudio/bots/default/music/adamradio/

!list play Plays a predefined playlist. !list play LIST123

!list play adamradio

!list list Displays a list of playlits !list list
!bot come Brings the bot to your channel. !bot come

(With Claytonia bots, "!come" will also work.)
!bot move [channel] Moves the bot to a different channel. !bot move 1
!bot move 43
(On most Claytonia bots, "!goaway" works too)

!api token

Gets and API token for web interface

!api token

!yt [song name]

Searches YouTube for a song. Follow instructions in chat to play it.  *

!yt Arabian Nights
!yt I Love A Piano

!ytp [song name]

Searches YouTube for a song and plays the "best" result.   *

!ytp Arabian Nights
!ytp I Love A Piano

!yta [song name]

Searches YouTube for a song and plays it after the current song is over.   *

!yta Arabian Nights
!yta I Love A Piano

!ytpl [playlist URL]

Plays a YouTube playlist. *


TS3AudioBot Tips And Tricks


YouTube playlists

You cannot play a YouTube playlist without importing it to a local playlist first.
!list import MY-GOOD-MUSIC
!list play MY-GOOD-MUSIC

Alternatively, you could set up an alias to do this for you. **
alais add ytpl = "!x (!list clear YTPL1) (!list import YTPL1 (!param 0)) (!list play YTPL1)"
This strings together a few commands.  First we clear the playlist (just in case), then we import a new list from a YouTube URL, finally we play the newly imported list.
Example usage:

m3u8 Playlists

!list get 80s
!list play 80s

Local Media Playlist

!list import adamradio /home/tsaudio/bots/default/music/adamradio/
!list play adamradio


!help command list
!help command history

NOT !help list !help history

Custom Commands and Aliases

Aliases must be added to each bot individuality.
To add an alias, use these commands:

!alias add [new command] "![command]"
!alias add come "!bot come"

In this example, the new command is "!come" and it will call the bot to the channel of the user issuing the command.

!alias add hits "!play"

This example sets up an alias to play a radio station when the user sends the command: "!hits"

Admin and Config File Stuff


To log in to the web interface, you will need an API token. Send the bot a PM with this command. Note: The Claytonia Teamspeak's web interface is turned off.

!api token

Set default channel

!settings set "/34"

Boot Options

How to make the bot do things when it connects to a server.

onconnect options in /bots/default/bot.toml

#Called when the bot is connected.
onconnect = "!xecute (!bot commander on) (!play"

Alone mode

add to /bots/default/bot.toml


#Called when the last client leaves the channel of the bot. Delay can be specified
onalone = "!stop"
#Specifies how long the bot has to be alone until the 'onalone' event gets fired.
#You can specify the time in the ISO-8601 format with quotation marks "PT30S" or like: 15s, 1h, 3m30s
alone_delay = "30s"
#Called when the bot was alone and a client joins his channel. Delay can be specified.
onparty = "!play [Youtube URL]" #any command works. 
#Specifies how long the bot has to be alone until the 'onalone' event gets fired.
#You can specify the time in the ISO-8601 format with quotation marks "PT30S" or like: 15s, 1h, 3m30s
party_delay = "0s"

Auto Reconnect

add to /bots/default/bot.toml

ontimeout = ["1s", "2s", "5s", "10s", "30s", "1m", "5m", "repeat last"]
onkick = ["1s", "2s", "5s", "10s", "30s", "1m", "5m", "repeat last"]
onban = ["1s", "2s", "5s", "10s", "30s", "1m", "5m", "repeat last"]
onerror = ["30s", "repeat last"]
onshutdown = ["5m", "repeat last"]

Custom Commands and Aliases

Add alias

!alias add come "!bot come"
!alias add [new command] "![command]"


add to /bots/default/bot.toml

come = "!bot come"
goaway = "!bot move 439" #439 is a channel number
###Youtube search and play###
yt = "!search from youtube (!param 0)"
ytp = "!xecute (!search from youtube (!param 0)) (!search play 0)"
yta = "!xecute (!search from youtube (!param 0)) (!search add 0)"
ytpl = "!x (!list clear YTPL1) (!list import YTPL1 (!param 0)) (!list play YTPL1)" ###Stream Shortcuts### bbc = "!play" npr = "!play" 80s = "!play" hits = "!play" rock = "!play" kissfm = "!list play kissfm"


Youtube-dl is required if you want to play music (or playlists) from YouTube, but Youtube-dl is old and doesn't always work. I found that using yt-dlp works better.

Install as same user that runs the bot.

python3 -m pip install -U yt-dlp

After install, it will tell you where the binary was installed. Copy that path and put it in ts3audiobot.toml

#Path to the youtube-dl binary or local git repository.
youtube-dl = { path = "/home/tsaudio/.local/bin/yt-dlp" }

Run the same command to update

*Bot admin must have the correct command aliases set up for this to work.
** On some servers, adding aliases requires admin permissions.