AI Voice STT - Speech-to-Text Service

Local GPU-accelerated Speech-to-Text service with web interface. Runs completely offline using Docker containers.

• High Accuracy: Uses OpenAI's Whisper large-v3 model
• Multilingual: Supports 99+ languages with automatic detection
• GPU Acceleration: Optional CUDA support for 10-30x faster transcription
• Offline Operation: No cloud dependencies, runs entirely locally
• Web Interface: User-friendly browser-based UI with drag & drop
• OpenAI-Compatible API: Drop-in replacement for OpenAI's transcription API

• STT Engine: Faster-Whisper (optimized Whisper implementation)
• Model: Whisper large-v3 by default (configurable)
• Backend: Pre-built container (fedirz/faster-whisper-server)
• Web UI: Single-page HTML/JavaScript application
• Infrastructure: Docker Compose

make setup

This will:

1. Create .env file from template
2. Download Whisper models (~3GB on first use)
3. Start services

Access the web interface at: http://localhost:8080

Requirements: NVIDIA GPU with Docker GPU support

make setup-gpu

1. Open http://localhost:8080 in your browser
2. Drag and drop an audio/video file, or click to select
3. Wait for transcription to complete
4. View and copy the transcribed text

Supported formats: MP3, WAV, M4A, MP4, WEBM, OGG, FLAC, and more

The API is OpenAI-compatible:

curl -X POST http://localhost:10300/v1/audio/transcriptions \
  -H "Content-Type: multipart/form-data" \
  -F "file=@audio.mp3" \
  -F "model=large-v3"

Parameters:

• file (required): Audio/video file to transcribe
• model (optional): Model name (default: large-v3)
• language (optional): Two-letter language code for better accuracy

Response:

{
  "text": "Transcribed text appears here"
}

make up         # Start services (CPU mode)
make up-gpu     # Start services (GPU mode)
make down       # Stop services
make restart    # Restart services
make logs       # View service logs
make status     # Check container status
make test       # Test STT API health
make clean      # Remove containers
make clean-all  # Remove containers + downloaded models

Edit .env to change settings:

# Model selection
WHISPER_MODEL=large-v3  # Options: tiny, base, small, medium, large-v3

# Ports
STT_PORT=10300
WEB_PORT=8080

# GPU (for GPU mode only)
CUDA_VISIBLE_DEVICES=0

Recommendation: Use large-v3 for best accuracy. Use medium or small for faster processing on limited hardware.

The project consists of two Docker containers:

1. stt: Faster-Whisper server

   • Port: 10300 (configurable)
   • Models cached in ./models directory
   • OpenAI-compatible endpoint: /v1/audio/transcriptions
   • Health check: /health

2. web: Static file server

   • Port: 8080 (configurable)
   • Serves the web interface

• Docker images: ~3GB (CPU) or ~8GB (GPU with CUDA)
• Whisper models:
  • large-v3: ~3GB
  • medium: ~1.5GB
  • small: ~500MB
• Total (large-v3): ~6GB (CPU) or ~11GB (GPU)

• VRAM: ~3GB for large-v3 model
• CUDA: Compatible NVIDIA GPU with CUDA support
• Driver: Recent NVIDIA drivers with Docker GPU support

make logs  # Check logs for errors

# Test GPU access:
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

• Check internet connectivity
• Ensure sufficient disk space (~3GB for large-v3)
• Models download on first transcription (can take 5-10 minutes)
• Check logs: make logs

• Consider using GPU mode: make down && make up-gpu
• Or use a smaller model: Edit .env and set WHISPER_MODEL=medium or small
• Then restart: make restart

• Verify containers are running: make status
• Check browser console for errors
• Ensure STT_PORT matches in .env and web interface

Transcribe audio/video to text (OpenAI-compatible).

Request (multipart/form-data):

• file: Audio/video file
• model (optional): Model name
• language (optional): ISO 639-1 language code
• temperature (optional): Sampling temperature (0-1)
• response_format (optional): Response format (json, text, srt, vtt)

Response (JSON):

{
  "text": "Transcribed text"
}

Check service health.

Response:

{
  "status": "ok"
}

Whisper supports 99+ languages including: English, Spanish, French, German, Italian, Portuguese, Dutch, Russian, Chinese, Japanese, Korean, Arabic, Hindi, and many more.

Language detection is automatic, but specifying the language can improve accuracy.

1. Use GPU mode for 10-30x speedup
2. Choose the right model: Balance between speed and accuracy
3. Specify language when known for better accuracy
4. Split long audio: Process in chunks for faster results
5. Use appropriate format: WAV files are processed faster than compressed formats

• Faster-Whisper
• OpenAI Whisper
• Whisper large-v3 Model

This project is part of manzolo's Local AI Lab — a family of self-hosted AI projects (LLM, voice, vision & documents) that share the same conventions and can be wired together through the shared local-ai-net Docker network.

This repo ships a docker-compose.local-ai.yml override to join the shared network — see the conventions.

Explore the whole family: topic:local-ai