Skip to content
mammuthPublic

About

Hörbert is a TeamSpeak music bot & soundboard

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Hörbert

A TeamSpeak music bot with a soundboard and text to speech. Control it from a shared web UI or with !commands in the chat.

Hörbert web UI

Features

  • 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 hello makes 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.

Quick start

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:8080

Or 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.

Usage

Web UI

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.

Chat commands

!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

Soundboard

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
  • url is anything ffmpeg can read; relative paths resolve against the file's directory.
  • volume (default 1.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.

Server view

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.

Text to speech

!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_COOLDOWN seconds between messages.
  • Voices are baked into the image. Pick others (or more languages) from the samples with a build arg, one language:voice each: --build-arg PIPER_VOICES="en:en_US-lessac-low de:de_DE-thorsten-medium". Languages without a voice are spoken with the TTS_VOICE one.
  • A small TTS server in the container keeps the voices in memory (~150 MB each), loading each on first use. After TTS_IDLE minutes without speech it frees them again; the next message then takes ~1 s longer. TTS=false turns it off.

Greetings

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.
  • lang is the voice's language like TTS_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.

Configuration

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

Troubleshooting

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:

  1. Keep yt-dlp current (the container updates it on every start).
  2. Run the PO-token provider sidecar: docker compose --profile pot up -d and set YTDLP_ARGS=--extractor-args "youtubepot-bgutilhttp:base_url=http://bgutil:4416".
  3. Export cookies from a browser to ./data/cookies.txt and set YTDLP_ARGS=--cookies /data/cookies.txt (yt-dlp wiki: Exporting YouTube cookies).

Development

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 dev

TTS 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-server

License

MIT


Disclaimer: this project is fully vibe coded. Use at your own risk.

About

Hörbert is a TeamSpeak music bot & soundboard

Resources

Stars

1 star

Watchers

0 watching

Forks

Packages

Contributors

Languages