A TeamSpeak music bot with a soundboard and text to speech.
Control it from a shared web UI or with !commands in the chat.
- Two ways to control it: a web UI for the whole channel (queue, search, soundboard, history) and chat commands in TeamSpeak. Both drive the same queue.
- Plays almost anything: every site yt-dlp supports (YouTube videos, playlists and search, SoundCloud, Bandcamp, …) plus direct audio and radio URLs.
- No ads, no sponsor reads: yt-dlp fetches the raw audio, and SponsorBlock segments on YouTube are skipped.
- Soundboard: your own clips as buttons and
!<name>commands, mixed over the music. - Server view: see who's online in every channel, live, with mute and away status.
- Text to speech:
!tts hellomakes the bot talk with natural English and German voices; the music ducks while it does. - Greetings: says hi when someone joins the channel, with lines you can add to.
- Good sound: 48 kHz stereo Opus at 128 kbit/s.
git clone https://github.com/mammuth/hoerbert && cd hoerbert
cp .env.example .env # set TS_ADDRESS (and TS_CHANNEL etc.)
docker compose up -d --build
open http://localhost:8080Or skip the build and use the prebuilt image: set
image: ghcr.io/mammuth/hoerbert:latest instead of build: . in docker-compose.yml.
The bot creates a TeamSpeak identity on first start and keeps it in
./data/identity.json, so you only have to grant it permissions (talk power!) once.
Add tracks by link or search, reorder the queue, skip, seek, play sounds and type text for the bot to say. Everyone sees the same state live.
The UI is locked behind a short key. !help posts a link with the key
(PUBLIC_URL/?key=…); opening it stores the key in a cookie. You can also type
the key into the page. Wrong guesses are throttled to one per second, which
keeps strangers out but is not strong security.
!play <link or search> add to queue (playlist links queue the whole list)
!next <link or search> play right after the current track
!skip !prev !pause
!now !queue !clear
!link link to the web UI
!soundboard list sounds, play one with !<slug>
!tts <text> say something (also !say)
!tts:de <text> …in another language
!help
List short clips in ./data/sounds.json. Each one becomes a !<slug> chat
command and a button in the web UI.
[
{ "slug": "airhorn", "name": "Airhorn", "emoji": "📯", "group": "Classics", "url": "sounds/airhorn.mp3", "volume": 0.8 },
{ "slug": "rimshot", "name": "Rimshot", "emoji": "🥁", "group": "Classics", "url": "https://example.com/rimshot.ogg" }
]Details
urlis anything ffmpeg can read; relative paths resolve against the file's directory.volume(default1.0) evens out loud and quiet clips.group(optional) puts buttons under a small heading in the web UI, in order of first appearance; ungrouped sounds come first.- Slugs are
[a-z0-9_-]; built-in commands win over a sound with the same slug. - The file is re-read on use, so edits apply without a restart.
The web UI lists every channel on the server and who is in it, the way the TeamSpeak client does: nested channels, spacers, muted mics and speakers, and away users. The bot's own channel is highlighted. It updates live as people join, leave and move around. "Hide empty" hides channels nobody is in. Hover someone in the bot's channel and hit 👋 Greet! to have Hörbert say a random greeting to them.
Anyone with the web key can see who is online server-wide.
SERVER_VIEW=false turns it off.
!tts and the Say box in the web UI read text out loud, offline, with natural
sounding English and German Piper voices
(run with sherpa-onnx, ~0.2 s per message
on one core).
Details
- Messages queue up instead of cutting each other off.
- The music gets quieter while the bot talks (
TTS_DUCK), and speech is compressed and limited so it stays clear over it without distorting. - Links are read as "link".
- Each user waits
TTS_COOLDOWNseconds between messages. - Voices are baked into the image. Pick others (or more languages) from the
samples with a build arg, one
language:voiceeach:--build-arg PIPER_VOICES="en:en_US-lessac-low de:de_DE-thorsten-medium". Languages without a voice are spoken with theTTS_VOICEone. - A small TTS server in the container keeps the voices in memory (~150 MB each),
loading each on first use. After
TTS_IDLEminutes without speech it frees them again; the next message then takes ~1 s longer.TTS=falseturns it off.
When someone joins the bot's channel, it says a random greeting from
./data/greetings.json, louder than other speech and with the music almost muted
(GREET_VOLUME, GREET_DUCK). The file is created with ten defaults on first start;
add your own. GREET=false turns greetings off.
[
{ "text": "Welcome back, {name}!", "lang": "en" },
{ "text": "Moin {name}!", "lang": "de" },
{ "text": "Psst. {name} ist da.", "lang": "de" }
]Details
{name}is the nickname of whoever joined.langis the voice's language likeTTS_VOICE(the default if left out).- At most one greeting every 10 s, so a crowd joining isn't greeted one by one.
- Each person is greeted at most once a minute, and nobody already in the channel is greeted when the bot (re)connects.
- The file is re-read on every join, so edits apply without a restart.
Everything is an environment variable, see .env.example.
Only TS_ADDRESS is required.
All variables
| Variable | Default | Meaning |
|---|---|---|
| TeamSpeak | ||
TS_ADDRESS |
— | host[:port] of the TeamSpeak server (required) |
TS_NAME |
Hörbert |
bot nickname |
TS_CHANNEL |
server default | channel path to join, e.g. Lounge/Music |
TS_CHANNEL_PASSWORD, TS_SERVER_PASSWORD |
— | passwords, if any |
COMMAND_PREFIX |
! |
chat command prefix |
HELP_SUFFIX |
— | extra text appended to !help (\n for line breaks) |
| Web UI | ||
WEB_BIND |
0.0.0.0:8080 |
where the web UI listens |
PUBLIC_URL |
— | URL shown by !link / !help (includes the key) |
WEB_KEY |
generated | web UI key; if unset, a 5-letter key is generated and saved in DATA_DIR/web_key |
SERVER_VIEW |
true |
list all channels and who is in them; shows everyone online to anyone with the key |
| Audio | ||
MUSIC_VOLUME |
0.06 |
music volume, 0.0 – 1.5; speech and sounds keep their level |
OPUS_BITRATE |
128000 |
Opus encoder bitrate |
SPONSORBLOCK |
true |
skip SponsorBlock segments on YouTube |
SPONSORBLOCK_CATEGORIES |
sponsor,selfpromo,interaction,music_offtopic |
which categories to skip |
| Soundboard | ||
SOUNDBOARD_FILE |
$DATA_DIR/sounds.json |
soundboard config |
SOUNDBOARD_VOLUME |
0.5 |
sound loudness, 0.0 – 1.5 |
| Text to speech | ||
TTS |
true |
enable TTS |
TTS_VOICE |
en |
default voice language, en or de |
TTS_SPEED |
de=1.2 |
talking speed per language, e.g. de=1.3,en=1.1 |
TTS_URL |
http://127.0.0.1:5002 in Docker |
TTS server; TTS is off without it |
TTS_IDLE |
30 |
minutes without speech before the voices are unloaded (0: never) |
TTS_MAX_CHARS |
200 |
longer messages are cut |
TTS_COOLDOWN |
1 |
seconds between two messages per user |
TTS_VOLUME |
1.0 |
speech loudness, 0.0 – 1.5 (above 1 it may distort; prefer GREET_VOLUME) |
TTS_DUCK |
0.15 |
music gain while speaking (1 = no ducking) |
GREET |
true |
greet people joining the channel (needs TTS) |
GREETINGS_FILE |
$DATA_DIR/greetings.json |
greetings |
GREET_VOLUME |
1.5 |
greeting loudness relative to other speech |
GREET_DUCK |
0.05 |
music gain while greeting |
| yt-dlp | ||
YTDLP_ARGS |
— | extra yt-dlp args (cookies, player clients, PO token provider) |
YTDLP_AUTO_UPDATE |
true |
pip install -U yt-dlp on container start |
| Other | ||
HISTORY_HOURS |
168 |
forget history (tracks and actions) older than this |
DATA_DIR |
data |
state + identity |
RUST_LOG |
info,hoerbert=debug |
log filter |
YouTube says “Sign in to confirm you’re not a bot”
YouTube is rate-limiting the IP. This mostly happens on datacenter IPs and rarely on home connections. Try these in order:
- Keep yt-dlp current (the container updates it on every start).
- Run the PO-token provider sidecar:
docker compose --profile pot up -dand setYTDLP_ARGS=--extractor-args "youtubepot-bgutilhttp:base_url=http://bgutil:4416". - Export cookies from a browser to
./data/cookies.txtand setYTDLP_ARGS=--cookies /data/cookies.txt(yt-dlp wiki: Exporting YouTube cookies).
How it works
web UI ──HTTP/WS──▶ axum ──▶ Player actor ──20 ms Opus frames──▶ TeamSpeak thread (tsclientlib)
│ ▲
yt-dlp -J ─┘ └─ ffmpeg → s16le PCM → gain → libopus
(stream URL, metadata, SponsorBlock segments)
- The bot connects with the TS3 full-client protocol via tsclientlib.
- The player resolves the stream URL right before playback (googlevideo URLs expire) and pre-resolves the next track while the current one plays.
- If ffmpeg gets a 403 or the stream dies, it re-resolves and resumes at the
same position; as a last resort it pipes
yt-dlp -o -into ffmpeg. - Pausing stops the Opus stream (and the TeamSpeak “talking” indicator); seeking
restarts ffmpeg with
-ss.
Running locally
# backend (needs ffmpeg, yt-dlp, libopus-dev, pkg-config, cmake on PATH)
TS_ADDRESS=127.0.0.1 cargo run
# frontend with hot reload, proxied to :8080
cd web && npm install && npm run devTTS needs the TTS server (tts/piper_server.py, see the Dockerfile for its voices);
point TTS_URL at it, otherwise TTS is off.
A local TeamSpeak server for testing:
docker run -d --name ts3 -e TS3SERVER_LICENSE=accept -p 9987:9987/udp teamspeak:latest
# or TS6
docker run -d --name ts6 -e TSSERVER_LICENSE_ACCEPTED=accept -p 9987:9987/udp teamspeaksystems/teamspeak6-serverMIT
Disclaimer: this project is fully vibe coded. Use at your own risk.
