# Vocal10n — Developer Documentation

This documentation set captures the full design and implementation history of
**Vocal10n**, a real-time speech-to-speech translation system built on
FasterWhisper, Qwen3-4B, and GPT-SoVITS / Qwen3-TTS.

The chapters are organised so a new contributor can read them top-to-bottom
and build a complete mental model of the system, then dive into any module
for implementation details.

## Table of Contents

| # | Chapter | Description |
|---|---------|-------------|
| 01 | [Overview](01-overview.md) | What Vocal10n is, what it does, target users, hardware. |
| 02 | [Architecture](02-architecture.md) | Process model, threading, data flow, module map. |
| 03 | [Repository Layout](03-repository-layout.md) | Directory tree and where things live. |
| 04 | [Environments and Setup](04-environments-and-setup.md) | Python venvs, dependencies, model placement. |
| 05 | [Configuration](05-configuration.md) | `config/default.yaml` reference, every key explained. |
| 06 | [Pipeline and State](06-pipeline-and-state.md) | `SystemState`, event dispatcher, coordinator, latency tracker. |
| 07 | [STT Module](07-stt-module.md) | FasterWhisper engine, audio capture, hallucination filter, AEC. |
| 08 | [LLM Translation Module](08-llm-translation.md) | Qwen3-4B local + OpenAI-compatible backend, RAG, corrector. |
| 09 | [TTS Modules](09-tts-modules.md) | GPT-SoVITS client and Qwen3-TTS backend, queueing, playback. |
| 10 | [OBS Subtitle Overlay](10-obs-overlay.md) | HTTP server, HTML overlay, styling. |
| 11 | [User Interface](11-ui.md) | PySide6 main window, Section A/B, Pro mode tabs. |
| 12 | [Simple Mode](12-simple-mode.md) | One-click Start/Stop, staged startup, status pills. |
| 13 | [Output and Files](13-output-and-files.md) | SRT/TXT/WAV writers, knowledge base, training data. |
| 14 | [Knowledge Base and RAG](14-knowledge-base-rag.md) | Glossaries, STT term files, vector retrieval. |
| 15 | [Latency Budget and Tuning](15-latency-tuning.md) | Where time is spent and how to reduce it. |
| 16 | [Development Timeline](16-development-timeline.md) | Phase-by-phase history reconstructed from git. |
| 17 | [Troubleshooting](17-troubleshooting.md) | Common issues and fixes encountered during development. |
| 18 | [Roadmap and Open Items](18-roadmap.md) | Known gaps and planned work. |

## Conventions

- All paths are relative to the repository root unless stated otherwise.
- Code references use module dotted paths (e.g. `vocal10n.stt.engine`).
- "Prebuild" refers to the legacy `Vocal10n-prebuild/` tree which served as
  the reference implementation for the rewrite.
- Diagrams use [Mermaid](https://mermaid.js.org/) fenced code blocks.

## Building a PDF

These chapters are plain markdown with Mermaid diagrams. To produce a
single-PDF deliverable on Windows:

1. Install the VS Code extensions **`bierner.markdown-mermaid`** (so the
   preview can render Mermaid) and **`yzane.markdown-pdf`** (export to
   PDF using a headless Chromium that supports Mermaid).
2. Open any `doc/*.md` file, run the command
   `Markdown PDF: Export (pdf)`. Repeat per chapter, or use
   `Markdown PDF: Export (all: pdf, html, png, jpeg)` against the `doc/`
   folder.
3. To merge per-chapter PDFs into one, any PDF merger works (e.g.
   `pdftk *.pdf cat output Vocal10n-Docs.pdf` or the Edge / Acrobat
   "combine files" UI).

No Node, Pandoc, or wiki host is required — the same flow you used with
Wiki.js exports here too, but locally.
