# 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
    └── ...
```