# 🎙️ Speech Transcriber

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

100% Offline Platforms MIT License

--- ## 📖 Table of Contents - [What is Speech Transcriber?](#what-is-speech-transcriber) - [Features](#features) - [Getting Started](#getting-started) - [Windows](#windows) - [Linux](#linux) - [macOS](#macos) - [Supported Models](#supported-models) - [Architecture](#architecture) - [Hardware Acceleration](#hardware-acceleration) - [Project Structure](#project-structure) - [License](#license) --- ## What is Speech Transcriber? **Speech Transcriber** is a fully offline, private audio transcription application powered by [whisper.cpp](https://github.com/ggerganov/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: ```bash 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`**: ```bash ./linux.sh ``` Optional flags: - `--max-perf` — enable additional backend downloads for maximum performance - `--setup-openvino` — configure Intel NPU acceleration ### macOS Run **`mac.sh`**: ```bash ./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](./LICENSE) for details. --- ## 🙏 Acknowledgments - [whisper.cpp](https://github.com/ggerganov/whisper.cpp) — The core transcription engine - [OpenAI Whisper](https://github.com/openai/whisper) — The original model architecture - [Material Design 3](https://m3.material.io/) — Design system reference - [Lucide Icons](https://lucide.dev/) — Beautiful icon set