🎙️ Speech Transcriber

Local AI audio transcription with whisper.cpp — 100% offline, private, and hardware-accelerated.

---

📖 Table of Contents

• What is Speech Transcriber?
• Features
• Getting Started
  • Windows
  • Linux
  • macOS
• Supported Models
• Architecture
• Hardware Acceleration
• Project Structure
• License

---

What is Speech Transcriber?

Speech Transcriber is a fully offline, private audio transcription application powered by whisper.cpp. It runs entirely on your local hardware — no internet, no API keys, no tracking, no subscriptions.

Record audio directly from your microphone or upload audio files in common formats, then transcribe them to text using state-of-the-art Whisper models with optional GPU acceleration.

---

✨ Features

Transcription

• Microphone recording — capture audio directly in the browser
• File upload — supports WAV, MP3, M4A, OGG, FLAC, WebM, AAC, M4B, OPUS, WMA
• Multi-language support — auto-detect or specify from 10 languages (English, Spanish, French, German, Italian, Portuguese, Hindi, Japanese, Korean, Chinese)
• Timestamps — optionally display segment timestamps in transcripts
• Translation — translate foreign language speech to English during transcription

Export

• TXT — clean text file
• JSON — structured data with segments and metadata
• Markdown — formatted transcript with optional timestamps

Model Management

• One-click download — fetch Whisper models directly from Hugging Face
• Local import — drag-and-drop .bin model files
• Model catalog — curated selection of Tiny, Base, and Small models (English-only and Multilingual)

Hardware Acceleration

• Auto-detection — automatically uses GPU when available, falls back to CPU
• Vulkan — cross-platform GPU acceleration (NVIDIA, AMD, Intel)
• CUDA — NVIDIA GPU acceleration
• Metal — Apple Silicon / Intel Mac GPU acceleration
• CPU fallback — works on any hardware

Interface

• 8 color themes — Light Default, Nord Light, Sakura Blossom, Dark Default, Dracula, Cyberpunk, Emerald Forest, OLED Black
• Dark / Light mode — system preference detection with manual override
• Real-time telemetry — CPU, RAM, and GPU usage monitoring
• Hardware tier detection — automatic system classification (High-End / Balanced / Potato)

---

🚀 Getting Started

Windows

Double-click windows.bat or run from terminal:

windows.bat

On first run, the app will automatically set up the portable Node.js runtime and whisper.cpp backend. After setup, it opens http://localhost:1420 in your browser.

Linux

Run linux.sh:

./linux.sh

Optional flags:

• --max-perf — enable additional backend downloads for maximum performance
• --setup-openvino — configure Intel NPU acceleration

macOS

Run mac.sh:

./mac.sh

---

🤖 Supported Models

Model	Size	Language	Quality
Whisper Tiny English	75 MB	English only	Fastest
Whisper Tiny English Q5	31 MB	English only	Fast, quantized
Whisper Base English	142 MB	English only	Balanced
Whisper Base English Q5	57 MB	English only	Balanced, quantized
Whisper Small English	466 MB	English only	High quality
Whisper Tiny Multilingual	75 MB	All supported	Fastest, multi-lang
Whisper Base Multilingual	142 MB	All supported	Balanced, multi-lang
Whisper Base Multilingual Q5	57 MB	All supported	Balanced, quantized
Whisper Small Multilingual	466 MB	All supported	High quality, multi-lang

Recommendation: Start with Base English Q5 (57 MB) for a good speed/quality tradeoff on English audio. Use Base Multilingual for non-English content.

---

🏗️ Architecture

whisper/
├── app/
│   ├── frontend/              # React + Vite source
│   │   ├── src/
│   │   │   ├── components/    # SpeechTranscriber, ModelManager, Settings
│   │   │   ├── services/api.js # Backend API client
│   │   │   ├── themes.js      # Color theme definitions
│   │   │   ├── App.jsx        # Main app shell
│   │   │   └── App.css        # Material Design 3 styling
│   │   └── dist/              # Built frontend (served by Node)
│   ├── speech-models/         # Downloaded Whisper models (.bin)
│   ├── transcriptions/        # Saved transcription results
│   └── speech-backend/        # whisper.cpp binaries per platform
├── scripts/
│   ├── server/serve.cjs       # Node.js server + process manager
│   ├── setup/                 # Platform-specific setup scripts
│   └── workers/               # Background workers
├── linux.sh                   # Linux launcher
├── mac.sh                     # macOS launcher
└── windows.bat                # Windows launcher

Flow:

1. User records/uploads audio in the browser (React frontend)
2. Audio is resampled to 16 kHz mono PCM16 WAV in-browser
3. Audio is sent to the Node.js server via REST API
4. Server spawns whisper-cli with the selected model and parameters
5. Transcription result is returned and displayed in the UI

---

⚡ Hardware Acceleration

The server automatically detects your hardware and selects the best available backend:

Priority	Backend	Platform	Requirements
1	Vulkan	Windows, Linux	Vulkan-capable GPU (NVIDIA, AMD, Intel)
2	CUDA	Windows, Linux	NVIDIA GPU with CUDA support
3	Metal	macOS	Apple Silicon or Intel Mac
4	CPU	All	Works everywhere

You can override the backend selection in Settings → Speech Transcription → Default Backend.

---

📁 Project Structure

• app/frontend/ — React + Vite single-page application
• scripts/server/serve.cjs — HTTP server + whisper.cpp process manager
• scripts/setup/ — Automated setup and repair scripts
• linux.sh / mac.sh / windows.bat — One-click platform launchers
• app/speech-models/ — Whisper model storage directory
• app/transcriptions/ — Transcription history and saved results

---

📜 License

MIT License — see LICENSE for details.

---

🙏 Acknowledgments

• whisper.cpp — The core transcription engine
• OpenAI Whisper — The original model architecture
• Material Design 3 — Design system reference
• Lucide Icons — Beautiful icon set