{"id":50564368,"url":"https://github.com/collabora/aavaaz","last_synced_at":"2026-06-04T13:30:24.416Z","repository":{"id":357257054,"uuid":"1236061502","full_name":"collabora/aavaaz","owner":"collabora","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-01T22:13:57.000Z","size":851,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-02T00:13:14.181Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/collabora.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-11T23:12:31.000Z","updated_at":"2026-06-01T22:14:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/collabora/aavaaz","commit_stats":null,"previous_names":["collabora/aavaaz"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/collabora/aavaaz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collabora%2Faavaaz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collabora%2Faavaaz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collabora%2Faavaaz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collabora%2Faavaaz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/collabora","download_url":"https://codeload.github.com/collabora/aavaaz/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/collabora%2Faavaaz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33907692,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-04T13:30:23.198Z","updated_at":"2026-06-04T13:30:24.405Z","avatar_url":"https://github.com/collabora.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aavaaz\n\n**Production-grade speech-to-text platform built on [WhisperLive](https://github.com/collabora/WhisperLive).**\n\nAavaaz (आवाज़, \"voice\" in Hindi) is an open source extension of WhisperLive\nwith enterprise features that compete with Deepgram, ElevenLabs, and AssemblyAI.\n\n## Features\n\n| Category | Capabilities |\n|----------|-------------|\n| **Transcription** | Real-time WebSocket streaming, REST API (OpenAI-compatible), batch inference, multichannel audio |\n| **Intelligence** | Speaker diarization, sentiment analysis, topic detection, entity extraction, summarization |\n| **Post-processing** | Smart formatting, PII redaction, profanity filtering, noise reduction, utterance/paragraph segmentation |\n| **Platform** | Webhook delivery, transcript search \u0026 tagging, storage backends (local/S3), ACL/auth, GDPR compliance, Prometheus metrics |\n| **Deployment** | Docker, Helm charts, Terraform (AWS), **serverless (Lambda)**, **Modal (GPU)**, GPU auto-detection, model caching, SSE streaming |\n\n## Quick Start\n\n### Option 1: Install from PyPI (Recommended)\n\n```bash\n# Create a virtualenv (Python 3.12 required)\npython3.12 -m venv .venv \u0026\u0026 source .venv/bin/activate\n\n# Install aavaaz with WhisperLive + ML stack\npip install \"aavaaz[whisper]\"\n\n# Start the server\naavaaz serve --model large-v3\n\n# Transcribe a file\naavaaz transcribe audio.wav\n```\n\n### Option 2: Using `uv` (Fast \u0026 Reproducible)\n\n```bash\n# Install uv: https://docs.astral.sh/uv/\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Create venv with Python 3.12 (required; 3.14 not yet supported by ML deps)\nuv venv .venv --python python3.12\nsource .venv/bin/activate\n\n# Install from PyPI\nuv pip install \"aavaaz[whisper]\"\n\n# Start the server\naavaaz serve --model large-v3\n\n# Transcribe a file\naavaaz transcribe audio.wav\n```\n\n\u003e **Fedora 43+ / Python 3.14 note:** The ML stack (PyTorch, faster-whisper) does\n\u003e not yet publish wheels for Python 3.14. Use `python3.12` explicitly when\n\u003e creating the virtualenv. On Fedora: `sudo dnf install python3.12`\n\n### Option 3: Local Development Install\n\n```bash\ngit clone git@github.com:collabora/aavaaz.git\ncd aavaaz\npython3.12 -m venv .venv \u0026\u0026 source .venv/bin/activate\n\n# Local editable install\npip install -e .\n\n# With WhisperLive + dev tooling\npip install -e \".[whisper,dev]\"\n```\n\n### Option 4: Using `pip` with Requirements Files\n\n```bash\n# Create a virtualenv (Python 3.12 required)\npython3.12 -m venv .venv \u0026\u0026 source .venv/bin/activate\n\n# Install base + ML stack (large ~20GB download for torch/onnx)\npip install -r requirements/whisper.txt\n\n# Or install just base (fast, no ML):\n# pip install -r requirements/base.txt\n\n# Start the server (requires ML stack)\naavaaz serve --model large-v3\n\n# Transcribe a file\naavaaz transcribe audio.wav\n\n# OpenAI-compatible REST endpoint\ncurl -X POST http://localhost:8000/v1/audio/transcriptions \\\n  -F file=@audio.wav -F model=large-v3\n```\n\n### Note on Storage\n\nThe full ML stack (torch, onnxruntime, torchaudio) requires **~20GB** disk space. \nIf you hit disk quota errors, consider:\n- Using `uv` which is faster and handles large downloads better\n- Installing on a machine with more space\n- Using serverless deployments (AWS Lambda / Modal) instead of local\n\n### Requirements Files\n\n- `requirements/base.txt` — Core dependencies only (fastapi, uvicorn, boto3)\n- `requirements/whisper.txt` — Full ML stack (torch, whisper-live\u003e=0.9.0, etc)\n- `requirements/dev.txt` — Development tools (pytest, ruff, etc)\n\n## Architecture\n\nAavaaz uses WhisperLive as its transcription engine and extends it via the\nplugin system:\n\n```\n┌─────────────────────────────────────────┐\n│              Aavaaz Server               │\n│  ┌─────────────────────────────────┐    │\n│  │  REST API / WebSocket / Web UI  │    │\n│  └──────────────┬──────────────────┘    │\n│  ┌──────────────┴──────────────────┐    │\n│  │        Plugin Pipeline          │    │\n│  │  diarization → formatting →     │    │\n│  │  PII redaction → intelligence   │    │\n│  └──────────────┬──────────────────┘    │\n│  ┌──────────────┴──────────────────┐    │\n│  │    WhisperLive Core Engine      │    │\n│  │  faster-whisper / TensorRT /    │    │\n│  │  OpenVINO                       │    │\n│  └─────────────────────────────────┘    │\n└─────────────────────────────────────────┘\n```\n\n## Advanced Features\n\n### Word-Level Timestamps\nEnable per-word timing and confidence scores in transcription segments:\n```python\nfrom aavaaz import AavaazServer\n\nserver = AavaazServer()\nserver.serve(word_timestamps=True)\n```\nWhen enabled, each segment includes a `words` array:\n```json\n{\n  \"segments\": [{\n    \"start\": \"0.000\", \"end\": \"2.500\", \"text\": \"Hello world\",\n    \"words\": [\n      {\"word\": \"Hello\", \"start\": \"0.000\", \"end\": \"0.800\", \"probability\": 0.95},\n      {\"word\": \" world\", \"start\": \"0.900\", \"end\": \"2.500\", \"probability\": 0.88}\n    ]\n  }]\n}\n```\n\n### Custom Vocabulary / Hotwords\nBoost recognition of specific terms (product names, acronyms, domain jargon):\n```python\nfrom aavaaz import AavaazServer\n\nserver = AavaazServer()\nserver.serve(hotwords=\"Aavaaz,TensorRT,OpenVINO\")\n```\nThe `hotwords` parameter is a comma-separated string passed directly to faster-whisper's keyword boosting. Also available in the REST API via the `hotwords` form field.\n\n### Speaker Diarization\nReal-time speaker identification using pyannote.audio embeddings:\n```bash\npip install pyannote.audio\n```\n```python\nfrom aavaaz import AavaazServer\n\nserver = AavaazServer()\nserver.serve(enable_diarization=True, max_speakers=4)\n```\nWhen enabled, completed segments include a `speaker` field:\n```json\n{\"start\": \"0.000\", \"end\": \"2.500\", \"text\": \"Hello\", \"speaker\": \"SPEAKER_00\", \"completed\": true}\n```\n\n### Authentication\nProtect both REST API and WebSocket connections with a shared API key:\n```bash\naavaaz serve --model large-v3 --api-key \"my-secret-key\"\n```\n- **REST API**: Requires `Authorization: Bearer my-secret-key` header\n- **WebSocket**: Requires either `Authorization: Bearer my-secret-key` header or `?token=my-secret-key` query parameter\n\nUnauthenticated connections receive HTTP 401 before any GPU resources are allocated.\n\n### Rate Limiting\nLimit REST API requests per client IP (sliding 60-second window):\n```bash\naavaaz serve --model large-v3 --rate-limit-rpm 60\n```\nClients exceeding the limit receive HTTP 429.\n\n### Auto-Reconnect\nAutomatically reconnect when the WebSocket connection drops unexpectedly:\n```python\nfrom whisper_live.client import TranscriptionClient\n\nclient = TranscriptionClient(\n  \"localhost\", 9090,\n  max_retries=5,\n  retry_delay=3,\n)\n```\n\n### Batch Inference\nBatch multiple client sessions into single GPU calls for higher throughput:\n```bash\naavaaz serve --model large-v3 --batch-inference --batch-max-size 8 --batch-window-ms 50\n```\n\n### Prometheus Metrics\nMonitor server health with a Prometheus `/metrics` endpoint:\n```bash\naavaaz serve --model large-v3 --metrics-port 9091\n```\nTracks active connections, transcription latency, segment counts, and error rates.\n\n### SSE Streaming\nStream transcription results via Server-Sent Events from the REST API:\n```bash\ncurl -X POST http://localhost:8000/v1/audio/transcriptions \\\n  -F file=@audio.wav -F stream=true\n```\nReturns real-time segment events as `text/event-stream`.\n\n### Plugin System\nExtend the transcription pipeline with custom post-processors:\n```python\nfrom aavaaz.plugins import PluginRegistry\n\nregistry = PluginRegistry()\nregistry.register(\"my_plugin\", my_post_processor_fn, priority=50)\n\nserver = AavaazServer(plugin_registry=registry)\nserver.serve()\n```\nPlugins receive each transcription segment and can modify, enrich, or filter it before delivery to the client.\n\n## Scaling Guide\n\n### Single GPU\n```bash\naavaaz serve --model large-v3 --batch-inference\n```\n\n### Multi-GPU (Docker Compose)\n```yaml\nservices:\n  aavaaz:\n    image: collabora/aavaaz:latest\n    deploy:\n      resources:\n        reservations:\n          devices:\n            - capabilities: [gpu]\n    ports:\n      - \"9090:9090\"\n      - \"8000:8000\"\n```\n\n### Kubernetes (Helm)\n```bash\nhelm install aavaaz deploy/helm/aavaaz \\\n  --set model=large-v3 \\\n  --set replicas=3 \\\n  --set gpu.enabled=true\n```\n\n### AWS (Terraform)\n```bash\ncd deploy/terraform\nterraform init\nterraform apply -var=\"model=large-v3\" -var=\"api_key=my-secret\"\n```\nProvisions VPC, ALB, ECS with GPU instances (g5.xlarge), ECR, and CloudWatch.\nSee [deploy/terraform/README.md](deploy/terraform/README.md) for full options.\n\n### AWS Lambda (Serverless)\n\nFor batch file transcription without managing servers:\n\nProduction role: Lambda is the batch transcription path.\n\n```bash\n# Build and push the Lambda container image\ndocker build -f Dockerfile.lambda --build-arg WHISPER_MODEL=small -t aavaaz-lambda .\n\n# Deploy infrastructure\ncd deploy/terraform-lambda\nterraform init\nterraform apply\n\n# Upload audio — transcript appears automatically in the output bucket\naws s3 cp recording.wav s3://$(terraform output -raw audio_input_bucket)/\n\n# Or use the REST API\ncurl -X POST $(terraform output -raw api_endpoint) \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"audio_url\": \"s3://my-bucket/recording.wav\"}'\n```\n\nSee [docs/SERVERLESS.md](docs/SERVERLESS.md) for full configuration, model\nselection, cost estimates, and limitations.\n\n### Modal (GPU Serverless)\n\nDeploy on Modal for on-demand GPU transcription with zero infrastructure:\n\nProduction role: Modal is used for live WebSocket transcription (`deploy/modal/app_live.py`).\nThe `deploy/modal/app.py` endpoint is an optional GPU batch API.\n\n```bash\ncd deploy/modal\npip install modal\nmodal setup\nmodal deploy app_live.py\n\n# Optional: deploy the GPU batch API endpoint\n# modal deploy app.py\n\n# Transcribe\n# Live websocket URL is exposed by app_live.py deployment output.\n```\n\nAuto-scales to zero when idle, GPU containers spin up in seconds.\nSee [docs/MODAL.md](docs/MODAL.md) for full configuration.\n\n## Development\n\n```bash\ngit clone git@github.com:collabora/aavaaz.git\ncd aavaaz\npip install -e \".[dev]\"\npytest\n```\n\n## License\n\n[MPL-2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcollabora%2Faavaaz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcollabora%2Faavaaz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcollabora%2Faavaaz/lists"}