How ahmetoner/whisper-asr-webservice works
Project Type and Purpose
• Type: A containerized RESTful microservice for Automatic Speech Recognition (ASR).
• Purpose: Expose multiple Whisper-based ASR engines (OpenAI Whisper, Faster-Whisper, WhisperX) over HTTP with configurable audio formats, output formats, and hardware acceleration (CPU/GPU).
File Structure to Extract Major Components
Top-level artifacts:
• Dockerfile / docker-compose.yml / GPU variant – packaging & orchestration
• app/webservice.py – entrypoint for the HTTP API (likely FastAPI or Flask + Swagger)
• app/config.py – environment-driven configuration
• app/factory/asr_model_factory.py – factory that selects and loads the appropriate ASR engine
• app/asr_models/*.py – concrete engine implementations (OpenAI, Faster Whisper, WhisperX)
• app/utils.py – helpers (e.g., audio pre-processing, VAD)
• cache persistence via host-volume for model downloads
• docs + mkdocs.yml – documentation site generation
Key Insights from README
• REST API with Swagger UI (http://host:9000)
• Supports multiple input formats (via FFmpeg) and multiple output formats (text, JSON, VTT, SRT, TSV)
• Environment variables control engine/model/device/timeout
• Docker images for CPU and GPU, Docker Compose examples
Main Components
A. Client Layer
– “API Consumer” (curl, browser, SDKs)
B. API Layer
– HTTP server (uvicorn/gunicorn + FastAPI or Flask)
– Swagger UI / OpenAPI docs
C. Configuration Module
– Reads ENV variables (ASR_ENGINE, ASR_MODEL, DEVICE, MODEL_IDLE_TIMEOUT, etc.)
D. ASR Model Factory
– Implements the factory pattern: inspects config, returns instance of the chosen engine
E. ASR Engine Implementations
– OpenAI Whisper Engine
– Faster-Whisper Engine
– WhisperX Engine (with optional speaker diarization)
F. Audio/Video Processing
– FFmpeg subprocess wrapper for format conversion
G. Model Storage & Cache
– Local cache directory (persisted via Docker volume)
– On-demand download from model repositories (Hugging Face / OpenAI)
H. Hardware Resources
– CPU and/or GPU
– CUDA runtime for GPU containers
I. Containerization & Orchestration
– Docker image (Dockerfile, GPU variant)
– docker-compose.yml (multi-service setup for future expansions, caching volume)
Relationships & Data Flow
1. Client → HTTP request (POST /transcribe)
2. API Layer parses request, handles authentication (if any)
3. API calls Configuration Module → ASR Model Factory
4. Factory checks cache → loads model into memory on CPU/GPU
5. API Layer streams audio to FFmpeg wrapper → normalized PCM data
6. Engine Implementation processes audio → emits transcription + timestamps
7. API Layer formats output (JSON/VTT/SRT/TSV/text)
8. Response returned to Client
9. Model may remain loaded until IDLE_TIMEOUT → then factory unloads
Architectural Patterns & Principles
• Factory Pattern for pluggable ASR engines
• Separation of concerns: API vs. model logic vs. utils vs. config
• Containerized infrastructure for portability (Docker, Compose)
• Use of environment variables for 12-factor compliance
• Extensibility: drop-in new ASR engines by adding to app/asr_models + factory