whisper-transcribe

Audio Transcription Service with Whisper.cpp – local-first, chunked recording support.

Quick Start

1. Interactive Setup

# Clone the repo
git clone https://git.fuksa.de/Tasch/whisper-transcribe.git
cd whisper-transcribe

# Run setup (downloads whisper.cpp + model + configures everything)
bash scripts/setup.sh

2. Start Server

uv run uvicorn src.main:app --reload

3. Or use Docker

docker compose up --build

CLI Tool

# Interactive setup
python scripts/cli.py setup

# Download a model
python scripts/cli.py download base

# Start server
python scripts/cli.py serve --port 8000

Web UI

A simple recording UI is available at ui/index.html.

# Serve the UI (or open directly in browser)
# Just open ui/index.html in your browser

Features:

• One-click recording
• Visual timer
• Sends chunks automatically to server
• Shows transcription when done

API Endpoints

Method	Endpoint	Description
GET	/api/v1/health	Health check
POST	/api/v1/record/start	Start recording session
POST	/api/v1/record/chunk/{session_id}	Add audio chunk
POST	/api/v1/record/stop/{session_id}	Stop + transcribe
POST	/api/v1/transcribe	Direct file upload

Configuration

Edit settings.yaml:

whisper:
  model: base              # tiny, base, small, medium, large
  language: null           # auto-detect, or: "de", "en", etc.
  model_path: models/ggml-base.bin

recording:
  chunk_duration_sec: 30   # Chunk size for recording sessions

routing:
  to_tasch:
    enabled: true          # Send transcripts to Tasch
  to_repo:
    enabled: false
    repo_url: "https://git.fuksa.de/..."

Development

# Install dependencies
uv sync

# Run tests
uv run pytest -m "not integration"

# Lint
uv run ruff check src/ tests/

Architecture

src/
├── audio/           # Recording sessions, file handling
├── transcription/   # Whisper.cpp wrapper
├── routing/         # Output dispatcher
├── api/             # FastAPI routes
└── main.py          # App entry point