docs: comprehensive codebase analysis and reference documentation

Add full codebase analysis report, issue history, test environment requirements, external research (TeaSpeak/ReSpeak/YaTQA), and offline protocol references (ReSpeak ts3protocol, TeaSpeak, YaTQA). Add master TODO list with 88 items across 11 categories. Add missing LICENSE files. Branch: docs/codebase-analysis-v2
2026-06-11 09:23:10 +09:00
parent 89bbfa1e18
commit 3b13a7edb4
10 changed files with 6173 additions and 0 deletions
@@ -0,0 +1,268 @@
+# External Research: TeaSpeak, ReSpeak, YaTQA
+
+**Date:** 2026-06-11  
+**Purpose:** Competitive analysis, dependency analysis, protocol documentation research
+
+---
+
+## 1. TeaSpeak
+
+### Overview
+
+| Attribute | Details |
+|---|---|
+| **Name** | TeaSpeak |
+| **Website** | teaspeak.de (currently down, archived) |
+| **Repository** | github.com/TeaSpeak/TeaSpeak (issue tracker only) |
+| **License** | Mixed: Web Client (MPL-2.0), Server (Proprietary), TeaMusic (Open Source C++) |
+| **Status** | **Effectively unmaintained** — TeaWeb archived July 2025, last server release ~2022 |
+| **Stars** | 120 (main repo), 49 (TeaWeb), 7 (TeaMusic) |
+| **Languages** | TypeScript (84%), SCSS, HTML, WebAssembly (web client); C++ (music bot) |
+
+### Architecture
+
+```
+TeaSpeak Server (closed-source binary, Linux x64 only)
+    │
+    ├── TeaSpeak Web Client (TypeScript, open source, MPL-2.0)
+    ├── TeaSpeak Native Client (closed-source binary, Win/Linux x64)
+    └── TeaMusic (C++ music bot, open source)
+```
+
+### Feature Comparison
+
+| Feature | TeaSpeak | Chanora |
+|---|---|---|
+| Voice (Opus) | ✅ | ✅ |
+| Text Chat | ✅ (markdown) | ✅ |
+| Video/Screen Sharing | ✅ (buggy, VP8) | Not planned |
+| Music Bot | ✅ (built-in) | Not in scope |
+| Channels | ✅ | ✅ |
+| Permissions | ✅ (advanced) | Partial |
+| File Transfer | ✅ | ✅ (v0.3.0) |
+| Web Client | ✅ | Not in scope |
+| Native Client | ✅ (closed source) | ✅ (Flutter + Rust) |
+| Cross-platform | Partial (Win/Linux) | ✅ (5 platforms) |
+| Push-to-Talk | Unknown | ✅ |
+| i18n | ✅ (8 languages) | ✅ |
+
+### Lessons for Chanora
+
+**What to learn:**
+- Web client as installation-less option is compelling
+- Built-in music bot is popular feature
+- Hidden/private channels valued by users
+- Markdown in chat is well-received
+- Multi-language support is expected
+
+**What to avoid:**
+- Closed-source server prevents community maintenance
+- Monolithic architecture limits extensibility
+- Poor maintenance (abandoned since ~2022)
+- Buggy video/screen sharing (multiple open issues)
+- No ARM support (frequently requested)
+- Mixed tech stack (React + jQuery) creates maintenance burden
+
+### Market Opportunity
+
+TeaSpeak's abandonment creates a clear opportunity for Chanora:
+- Users seeking open-source TeamSpeak-compatible clients
+- TeaSpeak's feature set validates market need
+- Chanora's formal engineering process prevents abandonment
+
+---
+
+## 2. ReSpeak Organization
+
+### Overview
+
+| Attribute | Details |
+|---|---|
+| **URL** | https://github.com/ReSpeak |
+| **Mission** | Reverse-engineering and reimplementing TS3 protocol in Rust |
+| **Activity** | 16 public repositories, 11 contributors |
+| **Language focus** | Rust (primary), C, C#, Python, Svelte/TypeScript |
+| **License** | Apache-2.0 / MIT dual-license |
+
+### Repository Inventory
+
+| Repository | Purpose | Stars | Status |
+|---|---|---|---|
+| **tsclientlib** | Core TS3 protocol library | 140 | Active |
+| **tsdeclarations** | Machine-readable protocol declarations | 94 | Active |
+| **TS3Hook** | DLL injection for packet decryption | 70 | Archived |
+| **rust-ts3plugin** | Rust bindings for TS3 plugin API | 14 | Active |
+| **SimpleBot** | Chat bot with custom reactions | 14 | Maintenance |
+| **quicklz** | QuickLZ compression for TS3 protocol | 7 | Stable |
+| **tomcrypt-rs** | Rust bindings for libtomcrypt | 6 | Dormant |
+| **ts3stats** | User statistics from server logs | 6 | Dormant |
+| **t4rust** | T4-like template engine for Rust | 5 | Active |
+| **Qint** | Full cross-platform TS3 client (Tauri) | 5 | Active |
+| **ts3tts** | Text-to-speech plugin | 3 | Maintenance |
+| **TsPressor** | Message compressor | 2 | Dormant |
+| **rust-ts3plugin-sys** | FFI bindings for TS3 plugin API | 0 | Active |
+| **MahTsIdentity** | Identity management | 0 | Dormant |
+| **pyTSon** | Python plugin interface | 0 | Dormant |
+| **TsVersionChecker** | Client version verification | 1 | Dormant |
+
+### Key Library: tsclientlib
+
+**Architecture (monorepo):**
+
+| Crate | Purpose |
+|---|---|
+| `tsclientlib` | High-level client API |
+| `tsproto` | Low-level protocol (UDP, encryption, fragmentation) |
+| `ts-bookkeeping` | State tracking |
+| `tsproto-packets` | Packet parsing |
+| `tsproto-structs` | Auto-generated structs |
+| `tsproto-types` | Basic types |
+
+**Key capabilities:**
+- Full TS3 protocol handshake (Init1 RSA puzzle, ECDH key exchange)
+- Encryption: EAX mode (AES-128-CTR + OMAC)
+- Compression: QuickLZ level 1
+- Packet fragmentation and reassembly
+- Voice/Opus audio handling
+
+**Performance:**
+- ~199ms connection time (RSA puzzle dominant)
+- ~189μs per message send
+
+### Chanora's Dependency on ReSpeak
+
+| Dependency | How Chanora Uses It |
+|---|---|
+| `tsclientlib` | Protocol adapter (`chanora_protocol`) |
+| `tsproto` | Network layer, encryption |
+| `tsproto-types` | Basic TS3 types |
+| `tsproto-packets` | Packet parsing |
+| `tsproto-structs` | Command/event structs |
+| `ts-bookkeeping` | Server state tracking |
+| `AudioHandler` | Voice decode, jitter buffer |
+
+**Note:** Chanora uses a **fork** (`EdisonJwa/tsclientlib`) for a p256 coordinate padding fix.
+
+### Protocol Documentation
+
+`tsdeclarations/ts3protocol.md` is the most comprehensive open TS3 protocol specification:
+
+1. **Low-level packets:** 9 packet types (Voice, VoiceWhisper, Command, CommandLow, Ping, Pong, Ack, AckLow, Init1)
+2. **Encryption:** EAX mode (AES-128-CTR + OMAC)
+3. **Compression:** QuickLZ level 1
+4. **Handshake:** 5-step Init1 (RSA puzzle), then ECDH key exchange
+5. **Voice:** Opus codec at 48kHz, whisper targeting modes
+6. **Identity:** EC key pairs (prime256v1), hashcash proof-of-work
+
+### Gaps in ReSpeak
+
+| Gap | Impact on Chanora |
+|---|---|
+| Server code | Not needed (client only) |
+| TS5 protocol | No full TS5 client protocol |
+| File transfer | No implementation |
+| Auto-reconnect | "Not yet there" in README |
+| IPv6 support | Not documented |
+| Documentation | Sparse code comments |
+
+### Recommendations
+
+**Continue using:**
+- `tsclientlib` as primary protocol dependency
+- `tsdeclarations` for protocol understanding
+
+**Consider contributing:**
+- p256 coordinate padding fix upstream
+- Auto-reconnect logic if implemented
+
+**Build internally:**
+- File transfer (no existing implementation)
+- Auto-reconnect logic
+- TS5 compatibility (monitor `tsdeclarations`)
+
+---
+
+## 3. YaTQA (yat.qa)
+
+### Overview
+
+| Attribute | Details |
+|---|---|
+| **Name** | YaTQA — Yet Another TeamSpeak³ Query App |
+| **URL** | https://yat.qa/ |
+| **Author** | Janni "Яedeemer" K. from northern Germany |
+| **First release** | June 29, 2011 |
+| **Latest version** | v3.9.9b (March 1, 2023) |
+| **Language** | Delphi 2009 (~50,000+ lines) |
+| **Purpose** | GUI alternative to raw ServerQuery telnet commands |
+
+**Note:** "qa" stands for **Query App**, not "Quality Assurance."
+
+### What It Is
+
+YaTQA is a Windows GUI tool for managing TeamSpeak 3 servers via the ServerQuery interface. It is NOT a testing framework.
+
+### Useful Resources
+
+The `/ressourcen/` section contains valuable unofficial documentation:
+
+| Resource | Value for Chanora |
+|---|---|
+| Server error codes | Comprehensive error handling reference |
+| Permission IDs | Permission feature implementation |
+| Client versions | Protocol compatibility reference |
+| DNS resolver behavior | Server resolution reference |
+| Anti-flood mechanics | Rate limiting design |
+| Codec configuration | Audio codec handling reference |
+| Snapshot format | Server migration features |
+| Voice client anti-flood | Rate limiting implementation |
+| Other protocols | File transfer, TSDNS, blacklist, weblist, badges |
+
+### Relevance to Chanora
+
+**Low direct relevance** — management tool, not testing framework.
+
+**What to extract:**
+1. Unofficial ServerQuery documentation (mostly German)
+2. Server error codes for comprehensive error handling
+3. Permission IDs for permission features
+4. Anti-flood mechanics for rate limiting design
+
+### Codec Reference
+
+YaTQA documents TeamSpeak's codec configuration:
+- Six codecs: Speex 8kHz, Speex 16kHz, Speex 32kHz, CELT 48kHz, Opus Voice, Opus Music
+- 11 quality levels per codec (0–10)
+- Latency settings for Speex/CELT (20–60ms)
+- Opus is VBR (variable bitrate)
+
+---
+
+## 4. Summary: What Chanora Can Learn
+
+### From TeaSpeak
+- ✅ Open-source client is the right approach
+- ✅ Cross-platform support is expected
+- ✅ i18n is important
+- ❌ Avoid closed-source components
+- ❌ Avoid monolithic architecture
+- ❌ Avoid mixed tech stacks
+
+### From ReSpeak
+- ✅ `tsclientlib` is the right protocol foundation
+- ✅ Protocol declarations are valuable reference
+- ⚠️ Keep fork in sync with upstream
+- ⚠️ Monitor for TS5 protocol updates
+- 🔨 Need to build file transfer internally
+- 🔨 Need to build auto-reconnect internally
+
+### From YaTQA
+- 📚 Unofficial protocol docs are valuable reference
+- 📚 Server error codes for error handling
+- 📚 Permission IDs for permission features
+- 📚 Anti-flood mechanics for rate limiting
+- ❌ Not a testing framework — don't try to use it as one
+
+---
+
+*Generated by external research agents on 2026-06-11*