Resonance

Unified Speech-to-Text (STT) and Text-to-Speech (TTS) API Server.

Features

• STT: GigaAM-v3 (RU), Distil-Whisper-v3 (EN), and IBM Granite (with speaker diarization) (EN)
• TTS: Russian Silero v5 voices and English Kokoro voices
• i18n: Interface available in English, Russian, Chinese

Demo

Configuration

Create .env before running:

cp .env.example .env

See .env.example for available options.

Before installing dependencies, configure .env:

• CUDA: set DEVICE=cuda, leave PYTORCH_BACKEND= for PyPI default or set a specific backend like cu128
• CPU: set DEVICE=cpu and PYTORCH_BACKEND=cpu
• macOS: use the setup script below
• Port: set RESONANCE_PORT (default 8000)
• CORS: set RESONANCE_CORS_ORIGINS only for custom origins; default follows RESONANCE_PORT

Docker

just build
just run

Local

Deps

• FFmpeg — audio decoding and streaming backend
• uv — fast Python package and project manager
• just — command runner

install it on your platform

macOS

./scripts/install-macos.sh

This creates .env if missing, configures the device, installs dev dependencies

Linux

manually choose your method

Windows

winget install "FFmpeg (Essentials Build)"
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install rust-just
winget install Microsoft.VCRedist.2015+.x64 -e

Run

just dev-deps
just dev

On macOS you can build Resonance.app menu bar app via:

just build-macos

and if you want to run from terminal with live logs:

./build/Resonance.app/Contents/MacOS/Resonance

Note

Open http://localhost:${RESONANCE_PORT} (default: http://localhost:8000)

Models are loaded lazily on first real STT/TTS use. Startup does not pre-download or pre-load model weights, so the first request to a specific backend may take noticeably longer.

API Endpoints

F5 Recovery Model

• Frontend stores only active job IDs in localStorage:
  • resonance_stt_active_job_id
  • resonance_tts_active_job_id
• Drawer jobs list is loaded from GET /api/jobs (paginated with offset / has_more) and contains only jobs for the current browser session.
• Backend assigns resonance_session_id cookie and enforces ownership on status/events/cancel endpoints.
• After page reload, UI restores state via GET /api/jobs/{job_id} and continues progress via /events.
• Job data is in-memory on server (JobRegistry), so after server restart unknown job_id is cleared on client and UI resets to neutral state.