Local Transcription Sidecar
Relevant source files
The following files were used as context for generating this wiki page:
The Local Transcription Sidecar is a dedicated native service within the mausVoice ecosystem designed to handle high-performance speech-to-text processing directly on the user's machine. By offloading heavy computational tasks like Whisper inference to a sidecar process, the main desktop application remains responsive while ensuring user privacy through zero-network local processing.
Sources: llms.txt, packages/rust_transcription/README.md:1-6
Architecture and Design
The sidecar is implemented in Rust and operates as a standalone binary communicating with the TypeScript-based "brain" via a REST API. It is decoupled from the main Tauri process to manage resource-intensive GPU and CPU tasks independently.
Component Overview
The sidecar supports two primary execution modes:
- CPU Binary (
rust-transcription-cpu): Optimized for standard processors usingwhisper.cppand ONNX Runtime. - GPU Binary (
rust-transcription-gpu): Leverages hardware acceleration through Metal (macOS) or Vulkan (Linux/Windows) via thegpufeature flag.
Sources: packages/rust_transcription/README.md:1-12, packages/rust_transcription/Cargo.toml:13-20
System Data Flow
The following diagram illustrates the interaction between the TypeScript frontend, the Tauri Rust bridge, and the local transcription sidecar.
The sidecar provides a bridge for native capabilities like audio capture and GPU enumeration while the business logic remains in TypeScript.
Sources: llms.txt, CLAUDE.md
Supported Models and Engines
The sidecar integrates multiple inference engines to provide flexibility between accuracy and speed.
| Engine | Supported Models | Format/Runtime |
|---|---|---|
| Whisper | tiny, base, small, medium, large, turbo | GGML (whisper.cpp) |
| NVIDIA ONNX | parakeet-ctc-0.6b, parakeet-tdt-0.6b, canary-1b | ONNX Runtime |
Sources: packages/rust_transcription/README.md:14-18
REST API Interface
The sidecar exposes a V1 API for model management and transcription execution.
Model Management
Endpoints for downloading and checking the status of local models.
POST /v1/models/{model}/download: Initiates a model download job.GET /v1/models/{model}/status: Validates if a model is loaded and functional.DELETE /v1/models/{model}: Removes model files from local storage.
Transcription Services
The sidecar supports both one-shot transcriptions and session-based chunked uploads.
The session-based approach allows for live-processing of audio streams by buffering little-endian Float32 samples before final inference.
Sources: packages/rust_transcription/README.md:37-142
Configuration and Environment
The sidecar is configured via environment variables that define network bindings and model storage paths.
| Variable | Default Value | Description |
|---|---|---|
RUST_TRANSCRIPTION_HOST | 127.0.0.1 | Binding address |
RUST_TRANSCRIPTION_PORT | 7771 (CPU) / 7772 (GPU) | Network port |
RUST_TRANSCRIPTION_MODELS_DIR | ./models | Storage path for GGML/ONNX files |
Sources: packages/rust_transcription/README.md:29-39
Technical Implementation Details
The sidecar relies on several key Rust crates for its functionality:
whisper-rs: Provides the bindings for GGML/Whisper.cpp inference.ort: Handles ONNX Runtime for Parakeet and Canary models.axum: Serves the REST API layer.tokio: Manages asynchronous I/O and multi-threaded runtime.
Sources: packages/rust_transcription/Cargo.toml:22-38
The local transcription sidecar ensures that mausVoice can operate in a fully offline mode, satisfying the "Personal local-first compute" requirement of the project. It provides a robust alternative to cloud providers like Deepgram when privacy or lack of connectivity is a priority.
Sources: apps/desktop/PRODUCT.md, README.md