GigaSTT Workbook
Scenario-driven recipes for gigastt, the local Russian speech-to-text server powered by GigaAM v3. Each chapter follows the same shape: scenario → prerequisites → recipe → verifying the result → common pitfalls → links.
This book is a cookbook, not a reference. The canonical references stay in
docs/ — the workbook links to them instead of duplicating them.
Documented against gigastt 2.14.x. Prefer resolving the latest release tag
in install scripts (gh api …/releases/latest) rather than hard-coding older
minors.
I want to…
| Goal | Time | Chapter |
|---|---|---|
| First transcript on this machine | ~5–15 min | Getting started |
| Batch a folder / watch a drop box / async jobs | ~15–30 min | CLI and batch processing |
| Transcribe PBX / Opus / raw telephony; stereo speakers | ~20 min | Telephony & VoIP |
| Live captions or a voice bot over WebSocket | ~30 min | Streaming over WebSocket |
| Ship a macOS / Electron / mobile app | ~30–60 min | Desktop & embedded |
| Run production with metrics, upgrades, model hot-reload | ~45 min | Deployment & ops |
| Pick head / INT8 / GPU / pool size / punct / hotwords | ~20 min | Models and backends |
| Label speakers on mono meetings | (in ch.3) | Telephony — diarization |
| Decode an HTTP/WS error code | ~2 min | Appendix A — Error codes |
| Ship air-gapped / offline | ~30 min | Appendix B — Offline checklist |
| Install on Windows | ~10 min | Getting started — Windows |
Chapters
- Getting started — install (macOS/Linux/Windows/Docker/air-gap), first transcription. Beginner · ~5–15 min
- CLI and batch processing — CLI, batch, and watch-mode recipes for audio files. Beginner · ~15–30 min
- Telephony & VoIP — G.711/G.722/Opus, PBX recordings, stereo split, and diarization. Intermediate · ~20 min
- Streaming over WebSocket — real-time transcription over WebSocket (partials, VAD endpointing, session caps). Intermediate · ~30 min
- Desktop & embedded — Swift/SPM, sidecar, Electron, UniFFI. Intermediate · ~30–60 min
- Deployment & ops — production deployment, monitoring, upgrades, admin reload. Ops · ~45 min
- Models and backends — model variants, quantization, execution providers, punctuation/ITN, hotwords. Intermediate · ~20 min
Appendices
- A — Error codes — REST/WS/close code jump table
- B — Offline checklist — air-gapped operator list
The Russian version mirrors this book chapter by chapter.
Documentation map
Full inventory of the documentation in this repository: what each file is and where it lives.
References (canonical — never duplicated in the workbook)
| File | Contents | Fate |
|---|---|---|
| docs/api.md | HTTP / WebSocket / SSE API reference | stays |
| docs/asyncapi.yaml | AsyncAPI schema for the WS protocol | stays |
| docs/openapi.yaml | OpenAPI schema for the REST API | stays |
| docs/cli.md | CLI reference (serve, download, transcribe, …) | stays |
| docs/architecture.md | Architecture overview | stays |
| docs/benchmarks.md | WER / RTF measurements | stays |
| docs/privacy.md | Privacy and data-flow statement | stays |
| docs/troubleshooting.md | Symptom → cause → fix table | stays |
| docs/observability/ | Prometheus alerts and Grafana dashboard assets | stays |
Guides (current)
| File | Contents | Fate |
|---|---|---|
| docs/deployment.md | Reverse proxy, TLS, systemd, Docker | stays |
| docs/quickstarts.md | In-process embedding quickstarts (FFI bindings) | stays |
| docs/runbook.md | Operator runbook for production | stays |
| docs/self-hosted-runner.md | Self-hosted CI runners for benchmarks | stays |
| docs/embedding-packaging.md | onnxruntime linking and packaging | stays |
| docs/verifying-releases.md | Verifying release artifacts | stays |
| docs/ane-backend.md | ANE (Core ML) backend note — live --features ane code | stays |
| docs/candle-backend.md | Candle/Metal backend note — live --features candle code | stays |
| sdks/go/README.md | Go WebSocket client SDK | stays |
| sdks/js/README.md | TypeScript WebSocket client SDK | stays |
Historical (archived)
Completed design/plan documents kept for archaeology in
docs/archive/:
| File | Contents | Fate |
|---|---|---|
| docs/archive/candle-metal-backend-plan.md | Candle/Metal backend implementation plan (completed) | archived |
| docs/archive/candle-metal-backend-design.md | Candle/Metal backend design (superseded by the shipped backend) | archived |
Rules for contributors
- The workbook holds recipes;
docs/api.md,docs/cli.md, and the AsyncAPI/OpenAPI schemas remain the canonical references. Link to them — do not copy their content. - Every command and example in a chapter must be verified before merge.
- Inside the book (chapter ↔ chapter, chapter ↔ intro) use relative
.mdlinks — they work both on GitHub and in the rendered book. Links from the book to repository files (docs/,crates/, …) must be absolute GitHub URLs — relative ones 404 on the published site. No mdBook-specific templating. - New chapters follow the
_template.mdstructure. - English is canonical. The Russian book (
docs/workbook/ru/) mirrors this one with identical file names; both versions are updated in the same PR. - When a feature changes the documented surface (CLI flags, error codes, audio
formats), update the chapter, the book
SUMMARY.md, and the canonical references in the same PR — and keep the docs-drift gate green:python3 scripts/check-docs-drift.py(advisory in CI; it compares CLI flags, WS error codes, audio formats, mdBook TOCs, EN/RU parity, relative links, OpenAPI/SECURITY/crate pins, and workbook version currency + required recipe tokens against the code).