TS3AudioBot: a music bot that runs the whole TeamSpeak server

A bot for a voice server, not a client-side player

TS3AudioBot is an open-source TeamSpeak 3 bot that plays music and much more, and the feature list explains why it is built the way it is.

It can play YouTube and SoundCloud songs as well as stream Twitch, and it is extensible with plugins. There is song history. There are various voice subscription modes, including to clients, to channels and to whisper groups, which is the part that makes it more than a jukebox: the bot can deliver a track to one person, to a channel, or to a whisper conversation, rather than only to the room.

Playlist management works for all users, permission configuration is described as powerful, and the feature list rounds off with plugin support, a web API, multi-instance and localization.

The last item is the one that explains the resource profile. The documentation claims low CPU and memory use with a self-written headless ts3 client. A normal TeamSpeak client is a full application with a user interface; the bot does not need one, so it implements the protocol side directly. That is the difference between running a bot on a server and running a bot that also renders a window for nobody to look at.

Multi-instance means several bots can run side by side, which matters on a server with multiple channels or with a need for separate permission scopes. The language is C#, the licence is OSL-3.0 with both a LICENSE and a LICENSE_COMPLETE file in the repository, and the homepage is splamy.de/TSAudioBot/Home.

Everything is driven from chat commands

The bot is fully operable via chat, and the entry point for a new user is a single command: write !help to the bot.

That is the whole interface philosophy. There is no separate control panel to learn, no configuration file to write before you can try it, and the person running the server and the person using the music are in the same place, the channel. A user asks the bot to play something, and the permissions that decide whether they may do that are enforced at the point of the command.

The command set is documented in two places. For the full reference there is a live OpenApiV3 generator hosted on tab.splamy.de, which is an unusual choice and a useful one: the API description is generated from the implementation, so the reference cannot drift away from what the binary actually accepts. For an in-depth tutorial, the wiki carries a CommandSystem page.

The plugin support mentioned in the features list is the extension point for everything the command system does not cover. A plugin can add new commands and new behaviours to the same bot, which is what makes the project usable as a platform for a server owner rather than as a fixed application.

What the documentation does not describe, in the pages the project links from the README, is the full command list, the configuration file format beyond the rights file, or the plugin API. Those live in the wiki and in the plugin repositories, and they are the parts a serious evaluator has to read.

Rights and the privilege key are the security model

The first time setup instructions are short and they define the security model of the whole bot.

You run the bot for the first time and follow the setup instructions it gives you. Then, optionally, you close the bot and configure your rights.toml to your desires, either using the template rules as suggested in the automatically generated file or reading the rights syntax documentation, and you start the bot again.

Then comes the part marked optional but highly recommended for everything to work properly. You create a privilege key for the ServerAdmin group, or a group which has equivalent rights, and you send the bot a private message with !bot setup followed by that privilege key.

That last step is the interesting one. A privilege key in TeamSpeak 3 is a mechanism for granting administrative capabilities to a bot or a client without handing over the account password, and it is the only way the bot gets the level of access it needs to control voice subscriptions. Sending it in a private message keeps it out of the channel history.

The rights.toml file is where the fine-grained policy lives. Because the bot is fully operable by chat, the risk is not that someone breaks it but that someone uses it more than they should. The rules decide which commands a group may run, which is why the setup steps put rights.toml configuration before the bot is considered finished.

The ordering of the steps is deliberate: run once to generate the template, edit the rights, run again, and only then hand over the privilege key. Doing it the other way round gives the bot administrative capability before it has any restrictions.

ffmpeg and opus on three distributions

The bot needs two things to make sound: an Opus library and an ffmpeg binary. The documentation covers three Linux distributions and Windows separately.

On Ubuntu and Debian it is one command:

sudo apt-get install libopus-dev ffmpeg

On Arch Linux:

sudo pacman -S opus ffmpeg

On CentOS 7 the route is longer, because Opus comes from a third party repository: install the epel-release package, add the Nux desktop release RPM, and then install ffmpeg and opus-devel.

There is also a manual path for Linux that covers everything else. Make sure a C compiler is installed, make the Opus script runnable with chmod u+x InstallOpus.sh and run it with ./InstallOpus.sh, download a 32bit or 64bit static ffmpeg binary, extract the archive with tar -vxf ffmpeg-git-*XXbit*-static.tar.xz, and copy the ffmpeg binary from the extracted directory into your TS3AudioBot folder.

The Windows route is the same idea with a different name: download a 32bit or 64bit static ffmpeg build and copy ffmpeg.exe from the ffmpeg-latest-winXX-static/bin directory into the TS3AudioBot folder.

The manual path is the reason InstallOpus.sh sits at the root of the repository. The bot builds Opus from source when the system does not provide a usable one, and the script is the supported way to do that rather than a convenience.

Optional youtube-dl for the videos ffmpeg cannot fetch

The optional dependency section addresses a real and specific failure.

If the bot cannot play some YouTube videos, it might be due to embedding restrictions blocking it. The fix is to install the youtube-dl binary or its source folder, and to specify the path in the configuration.

That sentence describes a concrete failure mode worth understanding. The normal path for playing a YouTube track is that the bot asks the service for the audio stream and hands the URL to ffmpeg. Some videos are restricted so that a direct stream request is refused, and the bot then has nothing to play. Pointing it at a local youtube-dl installation gives it a second way to resolve the same video.

It is also a hint about the moving target this project lives in. The tooling for reading YouTube streams changes regularly, and a bot that relies on it inherits that churn. The project offers a dated youtube-dl link rather than a maintained fork, and the Docker image is described as coming with youtube-dl preconfigured, which tells you the maintainers treat it as a standard part of the stack.

Downloads are organised in two tracks. Stable builds correspond to the master branch and are described as mostly considered stable but not getting bigger features as fast, while experimental builds correspond to develop and will always have the latest and greatest but might not be fully stable or have broken features. Windows x64 and Linux x64 are listed for both, and a Docker image is offered in the stable column, noted as community maintained. More builds, including linux arm and arm64 and .NET framework dependent ones, live on the nightly server.

Building from source with the .NET toolchain

Building manually is documented for people who want to run something other than a nightly artefact.

The repository is cloned with its submodules, which matters because the project has several of them:

git clone --recurse-submodules https://github.com/Splamy/TS3AudioBot.git

The build instructions for Linux start by getting the latest dotnet core 3.1 version and choosing the platform, then changing into the repository directory with cd TS3AudioBot, and then executing a dotnet build against a netcoreapp3 target. The instruction is cut off in the documentation excerpt, but the shape of it is clear: this is a .NET Core project built with the dotnet CLI.

The repository layout backs that up. There is TS3AudioBot.sln at the root, the main TS3AudioBot project, a TSLib directory that holds the TeamSpeak library code, a WebInterface project that corresponds to the web API feature, a TS3ABotUnitTests project, and a Tools directory.

Two files in the root are worth a mention. GitVersion.yml is there because the release numbers are derived from the git history rather than typed by hand, which explains why the releases are named 0.12.0, 0.11.0 and 0.10.0. And appveyor.yml holds the continuous integration configuration, with build badges for both the master and develop branches in the documentation.

For an engineer evaluating this, the practical question is whether the .NET Core 3.1 target the instructions name still matches the runtime you intend to deploy, since that version is several years past its end of support and the documented build recipe has not been updated to say otherwise.

A busy backlog, an old release and a small community

The contribution guidance is candid about what to expect.

The backlog is described as large, and feature requests will probably take time. You can contribute code, and the project asks you to open an issue or contact a maintainer to discuss before you start. There is a wiki and an FAQ for questions, an issue tracker with templates that you should fill in unless they do not apply, and a request to keep issues in English so that everyone can participate and so links stay relevant.

There is also a Gitter chat and a Patreon and PayPal link for supporting the maintainer directly.

The release record is the thing that gives you pause. The tags are 0.12.0 from 2021-04-02, 0.11.0 from 2020-03-16 and 0.10.0, an alpha snapshot, from 2019-10-21. The last push to the repository was on 2026-08-24, so work is still landing in the tree, but there has been no tagged release since 2021.

That gap has a practical effect on how you would adopt it. If you install a build from the nightly server you get recent code with no version to pin and no changelog to diff, and the stable channel described in the download table points at the master branch rather than at a numbered release. The project is not abandoned, but the releases are not a reliable upgrade path either, and the documentation itself warns that the experimental track might not be fully stable or have broken features.

Editorial conclusion

TS3AudioBot suits the operator of a TeamSpeak 3 server who wants music, a playlist, per-group permissions and a query interface without writing any of it, and who is prepared to maintain ffmpeg and opus on the host. It is the wrong choice if you need a supported product with a release cadence, since the newest tagged release is 0.12.0 from April 2021, and it is the wrong choice if the audio must be delivered to a modern client through a channel you do not control. Verify three things before you deploy it: that the TeamSpeak 3 server version you run is one the bot supports, that your users can reach YouTube and SoundCloud from the host, since some streams are blocked at the network level, and that the rights file gives the right groups the right commands before you hand out the ServerAdmin privilege key.

Frequently asked questions

Official sources

1. License: OSL-3.0
2. Project website
3. README
4. Releases
5. Splamy/TS3AudioBot on GitHub