subtitledss

Real-time subtitle overlay for Linux & macOS. 100% offline, powered by whisper.cpp.

Highlights

• Real-time transcription — speech-to-text as it happens, powered by whisper.cpp
• Offline translation — English ↔ Spanish via Marian MT (runs entirely on CPU)
• Transparent overlay — always-on-top subtitles with full appearance control
• Zero cloud — no data ever leaves your machine
• Multiple models — tiny (39 MB) to large-v3 (3.1 GB), GPU acceleration optional
• History & search — SQLite FTS5 full-text search across all transcriptions
• Export — SRT, VTT, TXT, JSON formats

---

Installation

Arch Linux (AUR)

yay -S subtitledss
# or
paru -S subtitledss

AppImage (any distro)

# Download from https://github.com/danieldussan/subtitledss/releases
chmod +x subtitledss-*.AppImage
./subtitledss-*.AppImage

Debian / Ubuntu

sudo dpkg -i subtitledss-*.deb
sudo apt-get install -f   # fix dependencies if needed

macOS

Download the .dmg file from Releases, open it, and drag subtitledss to your Applications folder.

System audio capture: macOS requires BlackHole to capture system audio. Install via Homebrew:

brew install blackhole-2ch

Then configure your audio MIDI setup to create a Multi-Output Device that includes both your speakers and BlackHole.

From Source

Prerequisites:

Build:

git clone https://github.com/danieldussan/subtitledss.git
cd subtitledss
bun install
bun run tauri build

Binary: src-tauri/target/release/subtitledss

GPU acceleration (optional):

# NVIDIA (requires CUDA toolkit)
cd src-tauri && cargo build --release --features cuda

# Vulkan
cd src-tauri && cargo build --release --features vulkan

# Metal (macOS / Apple Silicon — automatic with --features metal)
cd src-tauri && cargo build --release --features metal

---

Quick Start

1. Launch subtitledss
2. Go to Settings → download a Whisper model (start with Base — 142 MB)
3. Click Load on the downloaded model
4. Click the microphone button or press Ctrl+Shift+S (macOS: Cmd+Shift+S) to start capture
5. Subtitles appear in a transparent overlay on screen

---

Configuration

Config file: ~/.config/subtitledss/config.toml

[audio]

[whisper]

[overlay]

[translation]

[shortcuts]

Full example:

[audio]
source = "system"
device = "default"
sample_rate = 16000
vad_threshold = 0.005

[whisper]
model = "base"
language = "auto"
threads = 4
gpu = false

[overlay]
x = 100
y = 500
width = 600
height = 100
opacity = 0.9
always_on_top = true
click_through = false
font_size = 24
font_color = "#ffffff"
background_color = "#00000080"
auto_hide = true
auto_hide_delay = 5000
display_duration_ms = 10000
fade_duration_ms = 3000
max_visible_lines = 4
line_gap = 4
max_line_width = 80

[translation]
enabled = false
source_lang = "en"
target_lang = "es"
show_original = true

[shortcuts]
toggle_capture = "Ctrl+Shift+S"
toggle_overlay = "Ctrl+Shift+O"
toggle_translation = "Ctrl+Shift+T"
clear_history = "Ctrl+Shift+H"

---

Features

Real-time Transcription

Audio is captured via PipeWire/CPAL, processed through a VAD (Voice Activity Detector), and transcribed in chunks by whisper.cpp. The pipeline runs asynchronously — transcription never blocks audio capture.

Offline Translation

Built-in English ↔ Spanish translation using Marian MT via the candle ML framework. Models (~300 MB each) are downloaded from HuggingFace and run entirely on CPU. No internet required after download.

Transparent Overlay

A borderless, always-on-top window renders subtitles with configurable font, colors, opacity, and timing. Supports auto-hide with configurable delay, fade animations, and click-through mode for seamless integration.

Model Manager

Download, load, and delete Whisper models directly from the UI. Available models:

History & Search

All transcriptions are stored in a local SQLite database with FTS5 full-text search. Search across all past transcriptions instantly.

Export

Export transcription history to:

• SRT — SubRip (widely supported by video players)
• VTT — WebVTT (web standard)
• TXT — Plain text
• JSON — Structured data with timestamps

Keyboard Shortcuts & System Tray

System tray provides quick access to start/stop capture, toggle overlay, show window, and quit.

---

Development

Tech Stack

Project Structure

subtitledss/
├── src-tauri/                # Rust backend
│   ├── src/
│   │   ├── audio/            # CPAL capture, ring buffer
│   │   ├── whisper/          # whisper-rs engine, model downloader
│   │   ├── vad/              # Voice activity detector
│   │   ├── overlay/          # Overlay window manager
│   │   ├── translation/      # Marian MT engine + model manager
│   │   ├── settings/         # TOML config
│   │   ├── history/          # SQLite + FTS5
│   │   ├── models/           # Whisper model manager
│   │   ├── pipeline/         # Transcription pipeline
│   │   └── commands/         # Tauri IPC commands (21 total)
│   └── Cargo.toml
├── src/                      # React frontend
│   ├── components/
│   │   ├── Dashboard/        # Status cards, quick actions, live panel
│   │   ├── Settings/         # Audio, Whisper, Translation, Theme
│   │   ├── Overlay/          # Overlay settings + live preview
│   │   ├── History/          # History list with search
│   │   ├── ModelManager/     # Model download/load/delete
│   │   ├── Onboarding/       # First-run wizard
│   │   └── Layout/           # Sidebar, AppShell, routing
│   ├── hooks/                # useToast, useSettings, useOverlay
│   └── styles/               # Tailwind CSS theme
├── public/
│   └── overlay.html          # Overlay webview (vanilla JS)
├── ui-mockups/               # Design mockups
├── aur/                      # Arch Linux AUR packaging
└── .github/workflows/        # CI/CD

Commands

# Frontend
bun run dev          # Start dev server
bun run build        # Build frontend
bun run lint         # Run oxlint
bun run lint:fix     # Auto-fix lint issues
bun run fmt          # Format with oxfmt
bun run fmt:check    # Check formatting
bun run typecheck    # TypeScript check

# Tauri (Rust)
cd src-tauri
cargo check          # Check compilation
cargo test           # Run 93 unit tests
cargo build          # Build binary

---

CI/CD

GitHub Actions runs 7 checks on every push and PR to main:

---

License

MIT License — Copyright (c) 2026 danieldussan