A native TeamSpeak voice client for the terminal, written in C++20.
ts-cli is a terminal-first TeamSpeak client, built natively for Linux and cross-compiled to Windows. It connects directly using the TeamSpeak client protocol and implements the connection, session crypto, command transport, channel/client state, messaging, and voice path natively.
It does not use the proprietary TeamSpeak SDK, and it is not a ServerQuery wrapper.
Note
ts-cli is under active development. The goal is not to reproduce every feature of the desktop client, but to provide a small, capable, understandable terminal client for everyday TeamSpeak use.
Tip
Windows support is experimental: navigation, chat, configuration, and voice (via WASAPI) all work, but the Windows audio backend hasn't been exercised on real hardware yet — see BUILDING.md for the full picture and known limitations.
With ts-cli, you can:
- connect directly to TeamSpeak servers;
- browse channels and connected users, join and move between channels;
- talk and listen (PipeWire on Linux, WASAPI on Windows), with configurable voice activation and optional RNNoise filtering;
- send channel messages, private messages, and reply to the last PM;
- change your nickname at runtime, select input/output devices, mute/unmute;
- adjust or locally mute individual remote users without affecting anyone else;
- keep useful preferences across sessions in standard XDG locations.
The client starts every session with the microphone muted.
This assumes your build dependencies are already installed. First time here? Set up your environment with BUILDING.md — it covers both Linux and Windows.
make
build/linux/client/ts-cli voice.example.net:9987Once connected, type normally to send a message to the current channel, or use a command:
hello everyone
/list
/join Gaming
/unmute
/quit
$ build/linux/client/ts-cli voice.example.net:9987
Connected as frAgZ
Lobby
├── Alice
├── Bob
└── MusicBot
> hello everyone
[Lobby] frAgZ > hello everyone
> /join Gaming
Joined channel: Gaming
> anyone up for a game?
[Gaming] frAgZ > anyone up for a game?
> /unmute
microphone unmuted
For the full walkthrough — channels, messaging, voice activation, audio devices, per-user controls, and the complete command reference — see the Usage guide.
ts-cli supports both TeamSpeak Opus Voice and Opus Music channels over a native audio path:
capture -> optional filter -> voice-activity detection -> Opus encode -> network
network -> Opus decode -> per-user volume/mute -> mix -> playback
The microphone starts muted every session; unmute with /unmute, mute again with /mute. See Audio and voice for the full pipeline and Usage guide for tuning voice activation, RNNoise, and devices.
ts-cli stores its state in the standard XDG configuration directory:
$XDG_CONFIG_HOME/ts-cli/ (~/.config/ts-cli/ if unset)
├── config.conf # client-wide behavior and preferences
├── identity # local TeamSpeak identity
└── users/ # per-remote-user local settings, keyed by stable identity
See Configuration and identity for the full layout, file formats, and migration behavior.
ts-cli builds natively on Linux and cross-compiles to Windows via MinGW-w64 (tested under Wine); it can also be built natively on Windows via MSYS2. Full environment setup and dependency lists live in BUILDING.md.
Once dependencies are installed, a single Makefile drives all three targets — make linux (default), make windows-cross, and make windows-msys:
make linuxThe resulting binary is build/linux/client/ts-cli.
ts-cli on Linux links against its dependencies dynamically, so running a binary you didn't build yourself (e.g. downloaded from a release) needs these shared libraries installed: OpenSSL 3.x, libsodium, Opus, and RNNoise. You also need PipeWire actually running as your system's audio server, not just its library installed — see Audio and voice.
sudo pacman -S --needed openssl libsodium opus rnnoise pipewiresudo dnf install openssl-libs libsodium opus rnnoise pipewiresudo apt install libssl3 libsodium23 libopus0 librnnoise0 libpipewire-0.3-0Tip
Debian/Ubuntu package names occasionally change between releases (for example, a t64 suffix on newer releases from the 64-bit time_t transition — libssl3t64, libpipewire-0.3-0t64). If a package above isn't found, run ldd path/to/ts-cli to see exactly which .so is missing, then search for it with your package manager: pacman -F <name>.so on Arch, dnf provides '*/<name>.so' on Fedora, or apt search <library-name> on Debian/Ubuntu.
The project implements the TeamSpeak client path itself rather than delegating it to the proprietary SDK: native UDP connection and handshake, session encryption, packet sequencing and reliable command transport, QuickLZ decompression, identity handling, live channel/client state, Opus voice transmit/receive with jitter handling, native audio capture/playback and mixing, and persistent configuration.
For protocol and architecture details, see the documentation under docs/.
ts-cli/
├── audio/ # PipeWire/WASAPI, Opus, filters, jitter, mixing and audio worker
├── client/ # CLI, configuration, persistence and runtime integration
├── docs/ # architecture and protocol documentation
├── log/ # logging
├── net/ # networking
└── protocol/ # TeamSpeak protocol, crypto, session state and transport
The project keeps these boundaries intentionally strict: protocol code does not own UI or filesystem state, audio code does not need to understand TeamSpeak command parsing, and the CLI remains a relatively thin user-facing layer over the underlying runtime and state APIs.
- Documentation index
- Usage guide — everyday commands and full command reference
- Audio and voice
- Runtime model
- Configuration and identity
- Building ts-cli — environment setup for Linux and Windows
- Contributing — style, architecture and project conventions
- Protocol documentation — handshake, packet format, reliability, commands, crypto, state and voice
ts-cli is intended to be useful for normal voice and chat interaction, but it deliberately does not attempt complete desktop-client parity. Areas that remain smaller or incomplete include advanced administration/server-management workflows, desktop-style UI features and overlays, a fully adaptive heavyweight jitter engine, arbitrary microphone filter chains beyond the current optional RNNoise stage, and exclusive-mode audio / live device hot-plug notifications on Windows (see BUILDING.md).
Keeping the scope focused is intentional: the goal is a compact native terminal client that remains understandable, hackable, and pleasant to use.
Build environment setup is documented in BUILDING.md; development and contribution guidelines are documented in CONTRIBUTING.md. Protocol changes should remain focused, tested, and contained within the protocol layer where possible. Audio, client runtime, and persistence changes should preserve the existing ownership boundaries between components.
This project is not affiliated with or endorsed by TeamSpeak Systems GmbH. TeamSpeak and related trademarks belong to their respective owners.
AI assistance was used in this project to help with research, draft designs, and fill in documentation. The application itself is, and is intended to remain, handcrafted.