truetype
a0bbd9a035
Remove references to removed features (image gen, LLM chat, TTS). Accurately describe current project state as a local whisper.cpp speech transcription tool with GPU acceleration.
197 lines
7.3 KiB
Markdown
197 lines
7.3 KiB
Markdown
# 🎙️ Speech Transcriber
|
|
|
|
<p align="center">
|
|
<strong>Local AI audio transcription with whisper.cpp — 100% offline, private, and hardware-accelerated.</strong>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<img src="https://img.shields.io/badge/Offline-100%25-green?style=for-the-badge&logo=offline" alt="100% Offline" />
|
|
<img src="https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-blue?style=for-the-badge" alt="Platforms" />
|
|
<img src="https://img.shields.io/badge/License-MIT-orange?style=for-the-badge" alt="MIT License" />
|
|
</p>
|
|
|
|
---
|
|
|
|
## 📖 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
|