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

TeaSpeak Project Knowledge Base

Overview

TeaSpeak is an open-source, TeamSpeak-compatible voice communication platform hosted at https://git.did.science/TeaSpeak. It consists of two main repositories:

• TeaSpeak-Client — An Electron-based desktop client (329 commits, created May 2020)
• TeaSpeakLibrary — A C++ shared library providing core protocol, channel, and database functionality (208 commits, created May 2020)

The project is developed by WolverinDEV / TeaSpeak and targets users who need a self-hosted, TeamSpeak-compatible voice chat solution.

Architecture

Two-Repository Design

TeaSpeak/
├── TeaSpeak-Client/        # Electron desktop application
│   ├── main.ts             # Entry point (Electron main process)
│   ├── modules/            # TypeScript modules (core, renderer, shared, crash_handler)
│   ├── native/             # C++ native addons (Node.js N-API)
│   │   ├── serverconnection/   # Server connection & audio engine
│   │   ├── codec/              # Opus codec bindings
│   │   ├── crash_handler/      # Native crash handling
│   │   ├── dns/                # DNS resolution
│   │   ├── ppt/                # Protocol handling
│   │   └── updater/            # Auto-updater
│   ├── imports/            # Shared TypeScript definitions & vendor libs
│   └── resources/          # Static assets
│
└── TeaSpeakLibrary/        # C++ static library
    ├── CMakeLists.txt      # CMake build system
    ├── src/
    │   ├── protocol/       # TeamSpeak protocol implementation
    │   ├── channel/        # Channel tree management
    │   ├── query/          # Server query protocol
    │   ├── sql/            # SQLite & MySQL database layer
    │   ├── ssl/            # SSL/TLS support
    │   ├── bbcode/         # BBCode parsing
    │   └── misc/           # Utilities (crypto, networking, etc.)
    └── test/               # Unit tests

Client Architecture (Electron)

The client uses a multi-process Electron architecture:

• Main Process (modules/core/main.ts) — App lifecycle, window management, crash handling
• Renderer Process (modules/renderer/) — UI rendering, audio controls, connection management
• Shared Module (modules/shared/) — IPC definitions, version info, proxy utilities
• Native Addons (native/) — C++ bindings for performance-critical operations

Key TypeScript path aliases:

• tc-shared/* → imports/shared-app/*
• tc-native/connection → native/serverconnection/exports/exports.d.ts

Features

Voice Communication

• Opus audio codec support (encoder/decoder)
• Audio input/output with gain control and level metering
• Audio mixing and interleaving
• Voice activity detection (VAD) via libfvad
• Audio filtering and processing pipeline
• Sound file playback capabilities

Server Protocol

• TeamSpeak protocol compatibility
• Custom protocol handler with crypto support (ProtocolHandlerCrypto)
• Packet acknowledgement and loss calculation
• Ring buffer for reliable packet delivery
• QuickLZ compression
• Hardware ID (HWID) generation for client identification

Channel System

• Tree-based channel hierarchy (TreeView)
• Channel properties and permissions
• BBCode formatting support

Data & Storage

• SQLite database support
• MySQL database support
• Client storage and profiles
• File transfer capabilities
• Connection logging

Client Features

• Auto-updater
• Crash handler with Sentry integration
• Window management and system tray
• Keyboard shortcuts
• Context menus
• i18n (internationalization)
• Music playback
• URL preview

Technology Stack

Client (TeaSpeak-Client)

Component	Technology
Runtime	Electron 8.5.5
Language	TypeScript 3.9, C++
UI	HTML/CSS, jQuery, EJS templates
Styling	SASS
Native addons	cmake-js, Node.js N-API
Build	electron-packager
Error tracking	Sentry

Library (TeaSpeakLibrary)

Component	Technology
Language	C++20
Build system	CMake 3.6+
Crypto	TomCrypt, TomMath, OpenSSL, Ed25519
Compression	QuickLZ
Database	SQLite3, MySQL Connector/C++
Logging	spdlog
Events	libevent
Audio	Opus
JSON	jsoncpp
Serialization	Protocol Buffers
Memory	jemalloc
Crash reporting	Breakpad
Terminal	CXXTerminal (server mode)
Threading	Custom ThreadPool
String templating	StringVariable
Networking	DataPipes (includes libnice for ICE)

External Dependencies (from libraries.txt)

• PortAudio — Cross-platform audio I/O
• libfvad — Voice activity detection
• SoXR — High-quality sample rate conversion

Protocol / API

TeamSpeak Protocol Implementation

The protocol layer (TeaSpeakLibrary/src/protocol/) implements:

• Packet — Core packet structure and serialization
• CryptHandler — Encryption/decryption for secure communication
• CompressionHandler — QuickLZ-based packet compression
• AcknowledgeManager — Reliable delivery with ACK tracking
• PacketLossCalculator — Network quality monitoring
• RingBuffer — Circular buffer for packet ordering
• Generation — Protocol version/generation handling

Server Connection (Client Side)

The native server connection module (native/serverconnection/) handles:

• ServerConnection — Main connection state machine
• ProtocolHandler — Full protocol implementation split across:
  • ProtocolHandlerCommands.cpp — Command processing
  • ProtocolHandlerCrypto.cpp — Crypto handshake
  • ProtocolHandlerPOW.cpp — Proof of work (anti-spam)
  • ProtocolHandlerPackets.cpp — Packet serialization
• Socket — TCP/UDP socket management
• Audio subsystem — Codec, drivers, filters, processing

Query Protocol

Server query support (src/query/) with:

• Command parsing (v2 and v3 formats)
• Escape sequence handling

Build & Configuration

Building TeaSpeakLibrary

# Prerequisites: CMake 3.6+, C++20 compiler, OpenSSL, MySQL, etc.
mkdir build && cd build
cmake .. -DTEASPEAK_SERVER=ON
make -j$(nproc)

# Build tests (optional)
cmake .. -DBUILD_TESTS=ON
make -j$(nproc)

Building TeaSpeak-Client

# Install dependencies
npm install

# Compile TypeScript
npm run compile-tsc

# Compile SASS
npm run compile-sass

# Generate JSON validators
npm run compile-json-validator

# Build for Linux
npm run build-linux-64
npm run package-linux-64

# Build for Windows
npm run build-windows-64
npm run package-windows-64

# Development mode
npm run start-s  # Connects to localhost:8080

Environment Variables

• teaclient_deploy_secret — Deployment signing key (in env.sh)

Platform-Specific Dependencies

• Linux: electron-installer-debian
• Windows: electron-installer-windows, electron-winstaller, electron-wix-msi, rcedit

Key Concepts

Protocol Concepts

• HWID (Hardware ID) — Unique machine identifier for client authentication
• POW (Proof of Work) — Anti-spam mechanism in connection handshake
• Ring Buffer — Circular buffer for managing packet ordering and retransmission
• Acknowledge Manager — Tracks packet delivery confirmation
• Packet Loss Calculator — Monitors network quality metrics

Audio Concepts

• Opus Converter — Handles Opus encoding/decoding
• Audio Gain — Volume amplification/attenuation
• Audio Level Meter — Real-time audio level monitoring
• Audio Merger — Combines multiple audio streams
• Audio Interleaved — Audio frame interleaving for transmission
• Audio Event Loop — Async audio processing pipeline
• VAD (Voice Activity Detection) — Detects speech vs silence

Channel Concepts

• TreeView — Hierarchical channel structure (parent/child relationships)
• BBCode — Text formatting markup (TeamSpeak standard)
• Permission Manager — Role-based access control

Connection Concepts

• ServerConnection — Full connection lifecycle management
• Command Handler — Processes server commands/responses
• Handshake Handler — Initial connection negotiation
• Voice Connection — Audio stream management
• Video Connection — Video stream support
• Dummy Voice Connection — Placeholder/mock for testing

Source Repository Structure

TeaSpeak-Client Root

.
├── .gitignore
├── .gitmodules
├── bugs                        # Bug tracking
├── build_declarations.sh       # Build script for type declarations
├── env.sh                      # Environment variables
├── generate-json-validators.sh # JSON schema validation generator
├── libraries.txt               # External library references
├── main.ts                     # Electron entry point
├── package.json                # Node.js dependencies & scripts
├── package-lock.json
├── restore.sh                  # Restore script
├── tsconfig.json               # TypeScript configuration
├── tsconfig_render_api.json    # Renderer API TypeScript config
├── imports/                    # Shared TypeScript types & vendor code
│   ├── shared-app/             # Application-level shared types
│   │   ├── audio/              # Audio type definitions
│   │   ├── backend/            # Backend interfaces
│   │   ├── clientservice/      # Client service definitions
│   │   ├── connection/         # Connection type definitions
│   │   │   └── rtc/            # WebRTC-related types
│   │   ├── connectionlog/      # Connection logging
│   │   ├── conversations/      # Chat/conversation types
│   │   ├── crypto/             # Crypto interfaces
│   │   ├── entry-points/       # Module entry points
│   │   ├── events/             # Event definitions
│   │   ├── file/               # File handling types
│   │   ├── i18n/               # Internationalization
│   │   ├── ipc/                # IPC message definitions
│   │   ├── media/              # Media handling
│   │   ├── music/              # Music playback
│   │   ├── permission/         # Permission types
│   │   ├── profiles/           # User profiles
│   │   ├── text/               # Text processing
│   │   ├── tree/               # Tree data structures
│   │   ├── ui/                 # UI component types
│   │   └── update/             # Update mechanism
│   ├── svg-sprites/            # SVG icon sprites
│   └── vendor/                 # Third-party libraries
│       ├── TeaEventBus/        # Event bus implementation
│       └── TeaClientServices/  # Client services
├── installer/                  # Build & packaging scripts
├── jenkins/                    # CI/CD pipeline
├── modules/                    # TypeScript source modules
│   ├── core/                   # Main process
│   │   ├── app-updater/        # Auto-update logic
│   │   ├── main-window/        # Main window management
│   │   ├── render-backend/     # Renderer backend
│   │   ├── ui-loader/          # UI loading
│   │   ├── url-preview/        # URL preview
│   │   └── windows/            # Window definitions
│   ├── crash_handler/          # Crash handling
│   ├── renderer/               # Renderer process
│   │   ├── audio/              # Audio controls UI
│   │   ├── connection/         # Connection UI
│   │   ├── dns/                # DNS resolution
│   │   └── hooks/              # React-like hooks
│   ├── renderer-manifest/      # Renderer configuration
│   └── shared/                 # Shared utilities
│       ├── ipc/                # IPC implementation
│       ├── process-arguments/  # CLI argument parsing
│       ├── proxy/              # Proxy utilities
│       └── version/            # Version management
├── native/                     # C++ native addons
│   ├── cmake/                  # CMake modules
│   ├── codec/                  # Audio codec (Opus)
│   │   └── codec/              # Codec implementation
│   ├── crash_handler/          # Native crash handler
│   ├── dist/                   # Distribution files
│   ├── dns/                    # DNS resolver
│   ├── ppt/                    # Protocol tools
│   ├── serverconnection/       # Server connection module
│   │   ├── exports/            # TypeScript declarations
│   │   ├── src/
│   │   │   ├── audio/          # Audio engine
│   │   │   │   ├── codec/      # Opus encoder/decoder
│   │   │   │   ├── driver/     # Audio drivers
│   │   │   │   ├── file/       # Audio file I/O
│   │   │   │   ├── filter/     # Audio filters
│   │   │   │   ├── js/         # JS audio bindings
│   │   │   │   ├── processing/ # Audio processing
│   │   │   │   └── sounds/     # Sound effects
│   │   │   └── connection/     # Protocol implementation
│   │   │       ├── audio/      # Audio connection
│   │   │       └── ft/         # File transfer
│   │   └── test/               # Connection tests
│   └── updater/                # Auto-updater native code
├── resources/                  # Static resources
└── scripts/                    # Build/utility scripts

TeaSpeakLibrary Root

.
├── CMakeLists.txt          # Build configuration
├── main.cpp                # Test entry point
├── src/
│   ├── bbcode/             # BBCode parser
│   ├── channel/            # Channel tree (TreeView)
│   ├── converters/         # Data converters
│   ├── lock/               # Read-write mutex
│   ├── log/                # Logging utilities
│   ├── misc/               # Utilities
│   │   ├── base64.*        # Base64 encoding
│   │   ├── digest.*        # Hash digests
│   │   ├── hex.*           # Hex encoding
│   │   ├── memtracker.*    # Memory tracking
│   │   ├── net.*           # Network utilities
│   │   └── rnd.*           # Random number generation
│   ├── protocol/           # TeamSpeak protocol
│   │   ├── AcknowledgeManager.*    # ACK tracking
│   │   ├── CompressionHandler.*    # QuickLZ compression
│   │   ├── CryptHandler.*          # Encryption
│   │   ├── Packet.*                # Packet structure
│   │   ├── PacketLossCalculator.*  # Loss monitoring
│   │   ├── buffers.*               # Buffer management
│   │   ├── generation.*            # Protocol generation
│   │   └── ringbuffer.*            # Circular buffer
│   ├── qlz/                # QuickLZ compression library
│   ├── query/              # Server query protocol
│   ├── sql/                # Database layer
│   │   ├── sqlite/         # SQLite implementation
│   │   └── mysql/          # MySQL implementation
│   ├── ssl/                # SSL/TLS management
│   ├── BasicChannel.*      # Base channel class
│   ├── Definitions.h       # Global definitions
│   ├── Error.*             # Error handling
│   ├── EventLoop.*         # Event loop
│   ├── License.*           # License management
│   ├── PermissionManager.* # Permission system
│   ├── Properties.*        # Property system
│   └── Variable.*          # Variable system
└── test/                   # Unit tests
    ├── RingTest.cpp
    ├── CommandTest.cpp
    ├── ChannelTest.cpp
    ├── PermissionTest.cpp
    └── ...