chanora/docs/offline-knowledge/external/respeak-overview.md

ReSpeak Project Knowledge Base

Source: https://github.com/ReSpeak/tsclientlib Last synced: 2026-06-13 License: MIT OR Apache-2.0

Overview

ReSpeak is an open-source project that provides a Rust implementation of the TeamSpeak 3 protocol. The primary goal is to enable building TeamSpeak clients and bots in Rust. The project is not an official TeamSpeak product — it was created for fun and to gain features/bugfixes not available in the official client.

The organization maintains a single monorepo (ReSpeak/tsclientlib) containing multiple crates that layer from low-level protocol handling up to a high-level client library.

Key principle: ReSpeak does not publish server-side code. They earn revenue by selling servers and ReSpeak respects that business model.

Repository Map

Crate	Path	Purpose	Version
tsclientlib	tsclientlib/	High-level client/bot library	0.2.0
tsproto	tsproto/	Low-level TeamSpeak 3 protocol implementation	0.2.0
ts-bookkeeping	utils/ts-bookkeeping/	Server state tracking (clients, channels)	0.1.x
tsproto-packets	utils/tsproto-packets/	Packet and command parsing/serialization	0.1.x
tsproto-types	utils/tsproto-types/	Core types, enums, crypto primitives	0.1.x
tsproto-structs	utils/tsproto-structs/	Generated structs from tsdeclarations	0.1.x

External dependency: tsdeclarations — machine-readable TeamSpeak protocol declarations (embedded as git submodule).

tsclientlib

Architecture

tsclientlib is the top-level crate — the one consumers use. It provides:

• Connection struct: manages a single connection to a TeamSpeak server
• Async API built on tokio + futures
• DNS SRV resolution for server discovery (resolver.rs)
• Audio handling via audiopus (Opus codec) behind the audio feature flag
• Sync wrapper (sync.rs) for non-async contexts
• Prelude module for convenient imports

Features

Feature	Default	Description
audio	yes	Opus encode/decode, AudioHandler for jitter buffer + mixing
unstable	no	Expose internal protocol API (may break on minor releases)
default-tls	yes	reqwest with default TLS for HTTP/HTTPS
bundled	no	Bundle SDL2
static-link	no	Statically link SDL2
audiopus-unstable	no	Extended audiopus API from Flakebi's fork

Key Dependencies

• tsproto — protocol layer
• ts-bookkeeping — state management
• tsproto-packets — packet parsing
• tsproto-types — types + crypto
• tokio — async runtime
• hickory-proto / hickory-resolver — DNS resolution
• reqwest — HTTP client
• audiopus — Opus codec (optional)

Source Files

File	Purpose
lib.rs	Core types, re-exports, Connection entry point
audio.rs	Audio subsystem — Opus encode/decode, AudioHandler
resolver.rs	DNS SRV resolution for TeamSpeak servers
sync.rs	Synchronous wrapper API
prelude.rs	Convenience re-exports
tests.rs	Integration tests

Examples

• simple.rs — minimal async client
• simple-sync.rs — minimal sync client
• audio.rs — audio streaming client
• audio-latency.rs — latency measurement
• channeltree.rs — channel navigation
• many.rs / sync.rs — stress tests

tsproto

Architecture

tsproto implements the low-level TeamSpeak 3 protocol:

• Connection establishment and handshake
• UDP packet delivery with reliability (resend logic)
• Packet encryption and compression
• Command parsing

Source Files

File	Purpose
algorithms.rs	Packet splitting, encryption/decryption, compression, hash cash
client.rs	Client-side connection logic
connection.rs	Connection state machine, packet queuing
packet_codec.rs	Packet encoding/decoding codec
resend.rs	Reliable packet delivery with retransmission
license.rs	License system implementation
log.rs	Logging utilities
utils.rs	Helper functions

Protocol Details

Packet Types

Type	Description
Command	High-priority commands
CommandLow	Low-priority commands
Voice	Voice data
VoiceWhisper	Whisper voice data
Ack / AckLow	Acknowledgments
Ping / Pong	Keepalive
Init	Connection initialization

Packet Limits

• Max UDP packet size: 1500 bytes (ethernet MTU)
• Max command packet size: 500 bytes (including header)
• Max fragments length: 40960 bytes
• Max decompressed size: 2 MiB (for large servers with 2000+ channels)
• Max out-of-order queue: 200 packets

Compression

• Uses QuickLZ level 1 for command packets
• Compression only applied if result is smaller than original
• Fragmentation occurs when compressed data exceeds 500 bytes

Cryptography

Key Types

Type	Curve	Usage
EccKeyPubP256	P-256 (secp256r1)	Public identity key
EccKeyPrivP256	P-256	Private identity key
EccKeyPubEd25519	Ed25519	Public ephemeral key (handshake)
EccKeyPrivEd25519	Ed25519	Private ephemeral key (handshake)

Encryption Algorithm

1. Key derivation: SHA-256(packet_type || generation_id || shared_iv) → 16-byte key + 16-byte nonce
2. Cipher: AES-128 in EAX mode with 8-byte MAC
3. Key caching: Derived keys are cached per generation to avoid recomputation
4. Packet ID mixing: key[0] ^= (packet_id >> 8), key[1] ^= (packet_id & 0xff)

Shared IV Computation (compute_iv_mac)

1. ECDH shared secret via Ed25519
2. shared_iv = SHA-512(shared_secret)
3. XOR with alpha (10 bytes) and beta (54 bytes) from handshake
4. shared_mac = SHA-1(shared_iv)[..8]

Hash Cash (Identity Proof-of-Work)

• Identity level = number of leading zero bits in SHA-1(public_key_string || counter)
• upgrade_level(target) iterates counter until desired level is reached
• Default target level: 8

Identity Format

Format: counter || 'V' || base64(private_key)
Example: "2792354VMG8DAgeAAgEgAiEA..."

Fake Encryption

• Used for unencrypted packet types (voice, ack, ping, etc.)
• Fixed key: c:\windows\syste (16 bytes)
• Fixed nonce: m\firewall32.cpl (16 bytes)

ts-bookkeeping

Tracks the server state by processing incoming commands:

• Maintains client list, channel tree, server info
• Generates events from state changes
• Provides methods to create outgoing command packets
• Main struct: data::Connection

tsproto-packets

Handles packet serialization/deserialization:

• packets.rs — packet structures (InPacket, OutPacket, OutAck, etc.)
• commands.rs — TeamSpeak command parsing
• Header constants: C2S_HEADER_LEN, S2C_HEADER_LEN

tsproto-types

Core types and primitives:

• crypto.rs — ECC key types (P-256, Ed25519), ECDH, signatures, identity obfuscation
• versions.rs — TeamSpeak version strings
• errors.rs — Protocol error codes

Key Crypto Functions

Function	Description
EccKeyPrivP256::create()	Generate new P-256 keypair
EccKeyPrivP256::import_str()	Import from base64/tomcrypt/obfuscated formats
EccKeyPrivP256::create_shared_secret()	ECDH with P-256
EccKeyPrivP256::sign()	ECDSA signature
EccKeyPubP256::verify()	ECDSA verification
EccKeyPubP256::get_uid()	base64(SHA-1(ts_encoded_key))
encode_password()	base64(SHA-1(password))
EccKeyPrivEd25519::create_shared_secret()	ECDH with Ed25519

Identity Obfuscation

TeamSpeak stores identities XOR'd with a static 128-byte pattern + SHA-1 hash of trailing data. ReSpeak implements both obfuscation and deobfuscation.

How Chanora Uses ReSpeak

Chanora depends on four crates from the ReSpeak monorepo, all pinned to revision 04aa2491:

Dependency Chain

chanora_protocol/
  ├── tsclientlib (rev 04aa2491, features=["audio"])
  ├── tsproto-packets (rev 04aa2491)
  ├── tsproto-types (rev 04aa2491)
  └── ts-bookkeeping (rev 04aa2491)

chanora_audio/
  └── tsclientlib (rev 04aa2491, features=["audio"])

Architectural Constraint (SAD-067 / SysDes-011 / SysDes-029)

Chanora's chanora_protocol crate acts as an isolation boundary:

No tsclientlib types may cross out of this crate.

This prevents ReSpeak API changes from cascading through Chanora's codebase.

Patched Fork

Chanora patches tsproto-types to fix P-256 short coordinate padding:

[patch."https://github.com/ReSpeak/tsclientlib.git"]
tsproto-types = { git = "https://github.com/EdisonJwa/tsclientlib.git", branch = "fix/p256-short-coordinate-pad" }

This handles cases where P-256 coordinates are shorter than 32 bytes and need left-padding.

Key Usage Points

1. Protocol connection: tsclientlib::Connection for TeamSpeak server connections
2. Audio handling: AudioHandler from tsclientlib for decode, jitter buffer, mixing
3. Packet types: tsproto-packets for OutAudio, InAudioBuf, AudioData, CodecType, Direction
4. State tracking: ts-bookkeeping for server state management

External References

• Qint (https://github.com/ReSpeak/Qint) — Cross-platform TeamSpeak client built on tsclientlib (not yet ready)
• SimpleBot (https://github.com/ReSpeak/SimpleBot) — Example chat bot
• tsdeclarations (https://github.com/ReSpeak/tsdeclarations) — Machine-readable protocol declarations
• TSIdentityTool (https://github.com/landave/TSIdentityTool) — Identity deobfuscation reference (MIT)

Performance Benchmarks

From i7-5280K @ 3.6 GHz (single-threaded):

Operation	Time	Throughput
Connection creation	199 ms	6.5 conn/sec
Message send	189 µs	5300 msg/sec

Bottleneck: RSA puzzle solving at connection time. Use --features rug for efficient big integer implementation.