Edison Jwa
dd6e80f72a
- function-inventory: complete public API for 10 Rust crates + 56 Dart files - coverage-analysis: 312 Rust tests, 221 Dart tests, doc coverage gaps - doc-quality-analysis: duplications, broken refs, useless content audit - link-coverage-report: all internal/external links validated - external/teaspeak: TeaSpeak voice server architecture & protocol - external/respeak: ReSpeak org, tsclientlib, tsproto, crypto docs - external/yatqa-en/de: yat.qa admin tool (English + German) - reviews/: cross-validation reports for all analyses All documentation only, no code changes.
393 lines
16 KiB
Markdown
393 lines
16 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
└── ...
|
|
```
|