AI-Institute-Africa/ZimVoice
Domain:
natural language processingRecord type:
software
Creator:
AI-
Host:
# 🎙️ ZimVoice — Speech-to-Text API (Phase 1)
A robust, asynchronous Speech-to-Text microservice built with **FastAPI** and **OpenAI Whisper**.
Designed to be **model-agnostic** — swap in custom fine-tuned weights (Shona, Ndebele, etc.) via a single `.env` change.
---
## 📁 Project Structure
```text
Zim-Voice/
├── main.py # FastAPI entry point — all endpoints
├── engine.py # ZimVoiceEngine — model loading, inference & intent layer
├── processor.py # AudioProcessor — FFmpeg, VAD (Silero) & noise reduction
├── vocabulary.json # Zimbabwean domain vocabulary & corrections
├── requirements.txt # Python dependencies
├── Dockerfile # Multi-stage container build
├── .env # Runtime config
└── tests/
├── test_api.py # Integration test suite
├── test_intent.py # Intent extraction validation
└── live_test.py # Manual system verification
```
---
## ⚡ Quick Start (Local)
### Prerequisites
- Python 3.11+
- FFmpeg installed and on `PATH`
```powershell
# 1. Clone / enter the project
cd Zim-Voice
# 2. Create virtual environment
python -m venv .venv
.venv\Scripts\Activate.ps1 # Windows
# source .venv/bin/activate # Linux/macOS
# 3. Install dependencies
pip install -r requirements.txt
# 4. Configure environment
# .env is already in the project — edit MODEL_NAME etc. as needed
# 5. Start the server
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```
Open localhost for the interactive Swagger UI.
---
## 🐳 Docker
```bash
# Build
docker build -t zimvoice:latest .
# Run (pass .env at runtime — never baked into image)
docker run -p 8000:8000 --env-file .env zimvoice:latest
# With persistent model cache (avoids re-downloading Whisper weights)
docker run -p 8000:8000 --env-file .env \
-v zimvoice-models:/app/model_cache \
zimvoice:latest
```
---
## 🔌 API Endpoints
| Method | Path | Description |
| :----- | :--------------- | :-------------------- …