{"id":34147960,"url":"https://github.com/namastexlabs/murmurai","last_synced_at":"2026-01-29T14:24:14.824Z","repository":{"id":191102054,"uuid":"683920121","full_name":"namastexlabs/murmurai","owner":"namastexlabs","description":"🎙️ Drop-in replacement for paid transcription APIs. Self-hosted, GPU-powered, speaker diarization. Free forever: uvx murmurai","archived":false,"fork":false,"pushed_at":"2025-12-17T14:14:07.000Z","size":18526,"stargazers_count":28,"open_issues_count":0,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-21T02:40:15.568Z","etag":null,"topics":["ai","api","asr","diarization","stt","text-to-speech","transcription","tts","whisper-ai","whisperx"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/murmurai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/namastexlabs.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2023-08-28T04:19:41.000Z","updated_at":"2025-12-17T14:14:11.000Z","dependencies_parsed_at":"2025-12-08T02:05:42.583Z","dependency_job_id":null,"html_url":"https://github.com/namastexlabs/murmurai","commit_stats":null,"previous_names":["namastexlabs/whisperex-api"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/namastexlabs/murmurai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namastexlabs%2Fmurmurai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namastexlabs%2Fmurmurai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namastexlabs%2Fmurmurai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namastexlabs%2Fmurmurai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/namastexlabs","download_url":"https://codeload.github.com/namastexlabs/murmurai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namastexlabs%2Fmurmurai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28879425,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T10:31:27.438Z","status":"ssl_error","status_checked_at":"2026-01-29T10:31:01.017Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai","api","asr","diarization","stt","text-to-speech","transcription","tts","whisper-ai","whisperx"],"created_at":"2025-12-15T04:35:31.109Z","updated_at":"2026-01-29T14:24:14.811Z","avatar_url":"https://github.com/namastexlabs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/images/murmur-200.png\" alt=\"MurmurAI Logo\" width=\"200\"\u003e\n\u003ch1 align=\"center\"\u003eMurmurAI\u003c/h1\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e🎙️ Drop-in replacement for paid transcription APIs. Self-hosted, GPU-powered, speaker diarization. Free forever.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/murmurai/\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/v/murmurai?style=flat-square\u0026color=00D9FF\" alt=\"PyPI\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/namastexlabs/murmurai/actions/workflows/ci.yml\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/namastexlabs/murmurai/ci.yml?style=flat-square\" alt=\"CI\"\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.12-blue?style=flat-square\" alt=\"Python 3.12\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-MIT-green?style=flat-square\" alt=\"MIT License\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#-quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#-api-reference\"\u003eAPI\u003c/a\u003e •\n  \u003ca href=\"#-configuration\"\u003eConfig\u003c/a\u003e •\n  \u003ca href=\"#-security\"\u003eSecurity\u003c/a\u003e •\n  \u003ca href=\"#-development\"\u003eDevelopment\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nTurn any audio into text with speaker labels. No cloud. No limits. Just run:\n\n```bash\nuvx murmurai\n```\n\nMurmurAI wraps [murmurai-core](https://pypi.org/project/murmurai-core/) (our WhisperX fork) in a REST API with speaker diarization, word-level timestamps, and multiple export formats. Self-hosted alternative to AssemblyAI, Deepgram, and Rev.ai.\n\n## Features\n\n- **Speaker Diarization** - Identify who said what with pyannote\n- **Word-Level Timestamps** - Precise alignment for every word\n- **Multiple Export Formats** - SRT, WebVTT, TXT, JSON\n- **Webhook Callbacks** - Get notified when transcription completes\n- **GPU Model Caching** - Fast subsequent transcriptions\n- **Background Processing** - Non-blocking async jobs\n- **Progress Tracking** - Poll for real-time status\n\n## 🔮 What's Next\n\nWe're a research lab. Stars tell us what the community wants — help us prioritize!\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/namastexlabs/murmurai\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/namastexlabs/murmurai?style=for-the-badge\u0026logo=github\u0026label=Star%20to%20Unlock\u0026color=f59e0b\" alt=\"Star to unlock\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  🔒 \u003cb\u003e250 ⭐\u003c/b\u003e Desktop App \u0026nbsp;\u0026nbsp;│\u0026nbsp;\u0026nbsp;\n  🔒 \u003cb\u003e500 ⭐\u003c/b\u003e MCP Server \u0026nbsp;\u0026nbsp;│\u0026nbsp;\u0026nbsp;\n  🔒 \u003cb\u003e750 ⭐\u003c/b\u003e Native Apple Silicon (MLX) \u0026nbsp;\u0026nbsp;│\u0026nbsp;\u0026nbsp;\n  🔒 \u003cb\u003e1000 ⭐\u003c/b\u003e Real-time Streaming\n\u003c/p\u003e\n\n## Quick Start\n\n### Prerequisites\n\n- **NVIDIA GPU** with 6GB+ VRAM (or CPU mode for testing)\n- **CUDA 12.x** drivers installed\n\n### Option A: One-Liner Install (Recommended)\n\n```bash\ncurl -fsSL https://install.namastex.ai/get-murmurai.sh | bash\n```\n\nThis installs Python 3.12, uv, checks CUDA, and sets up murmurai.\n\n### Option B: Direct Run (if dependencies met)\n\n```bash\nuvx murmurai\n```\n\n### Option C: pip install\n\n```bash\npip install murmurai\nmurmurai\n```\n\n### Option D: Docker (GPU required)\n\n```bash\n# Clone and run with docker compose\ngit clone https://github.com/namastexlabs/murmurai.git\ncd murmurai\ndocker compose up\n```\n\nRequires NVIDIA Container Toolkit. Set `MURMURAI_API_KEY` in environment for production.\n\n### Windows Install\n\nWindows requires PyTorch with CUDA from PyTorch's index (PyPI only has CPU wheels for Windows).\n\n```powershell\n# One command (auto-detects CUDA):\nuv pip install murmurai --torch-backend=auto\n\n# Or manually:\nuv pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu128\nuv pip install murmurai\n```\n\nIf you see \"PyTorch is CPU-only\", reinstall with `--torch-backend=auto` or use the manual method above.\n\nThe API starts at `http://localhost:8880`. Swagger docs at `/docs`.\n\n### First Transcription\n\n```bash\n# Default API key is \"namastex888\" - works out of the box\ncurl -X POST http://localhost:8880/v1/transcript \\\n  -H \"Authorization: namastex888\" \\\n  -F \"file=@audio.mp3\"\n\n# Check status (replace {id} with returned transcript ID)\ncurl http://localhost:8880/v1/transcript/{id} \\\n  -H \"Authorization: namastex888\"\n```\n\n## API Reference\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/v1/transcript` | Submit transcription job |\n| `GET` | `/v1/transcript/{id}` | Get transcript status/result |\n| `GET` | `/v1/transcript/{id}/srt` | Export as SRT subtitles |\n| `GET` | `/v1/transcript/{id}/vtt` | Export as WebVTT |\n| `GET` | `/v1/transcript/{id}/txt` | Export as plain text |\n| `GET` | `/v1/transcript/{id}/json` | Export as JSON |\n| `DELETE` | `/v1/transcript/{id}` | Delete transcript |\n| `GET` | `/health` | Health check (no auth) |\n\n### Submit Transcription\n\n**File upload:**\n```bash\ncurl -X POST http://localhost:8880/v1/transcript \\\n  -H \"Authorization: namastex888\" \\\n  -F \"file=@audio.mp3\"\n```\n\n**URL download:**\n```bash\ncurl -X POST http://localhost:8880/v1/transcript \\\n  -H \"Authorization: namastex888\" \\\n  -F \"audio_url=https://example.com/audio.mp3\"\n```\n\n**With speaker diarization:**\n```bash\ncurl -X POST http://localhost:8880/v1/transcript \\\n  -H \"Authorization: namastex888\" \\\n  -F \"file=@audio.mp3\" \\\n  -F \"speaker_labels=true\" \\\n  -F \"speakers_expected=2\"\n```\n\n### Response Format\n\n```json\n{\n  \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"status\": \"completed\",\n  \"text\": \"Hello world, this is a transcription.\",\n  \"words\": [\n    {\"text\": \"Hello\", \"start\": 0, \"end\": 500, \"confidence\": 0.98, \"speaker\": \"A\"}\n  ],\n  \"utterances\": [\n    {\"speaker\": \"A\", \"text\": \"Hello world...\", \"start\": 0, \"end\": 3000}\n  ],\n  \"language_code\": \"en\"\n}\n```\n\n**Status values:** `queued` → `processing` → `completed` (or `error`)\n\n## Configuration\n\nAll settings via environment variables with `MURMURAI_` prefix. Everything has sensible defaults - no `.env` file needed for local use.\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MURMURAI_API_KEY` | `namastex888` | API authentication key |\n| `MURMURAI_HOST` | `0.0.0.0` | Server bind address |\n| `MURMURAI_PORT` | `8880` | Server port |\n| `MURMURAI_MODEL` | `large-v3-turbo` | Whisper model |\n| `MURMURAI_DATA_DIR` | `./data` | SQLite database location |\n| `MURMURAI_HF_TOKEN` | - | HuggingFace token (for diarization) |\n| `MURMURAI_DEVICE` | `0` | GPU device index |\n| `MURMURAI_LOG_FORMAT` | `text` | Logging format (`text` or `json`) |\n| `MURMURAI_LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |\n\n### Speaker Diarization Setup\n\nTo enable `speaker_labels=true`:\n\n1. **Accept license** at [pyannote/speaker-diarization](https://hf.co/pyannote/speaker-diarization-community-1)\n2. **Get token** at [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)\n3. **Add to config:**\n   ```bash\n   echo \"MURMURAI_HF_TOKEN=hf_xxx\" \u003e\u003e ~/.config/murmurai/.env\n   ```\n\n## Security\n\n### Default API Key Warning\n\nMurmurAI ships with a default API key (`namastex888`) for zero-config local use. **This key is publicly known.**\n\n**For any network-exposed deployment, set a secure key:**\n\n```bash\n# Generate a secure random key\nexport MURMURAI_API_KEY=$(openssl rand -hex 32)\n\n# Or add to your .env file\necho \"MURMURAI_API_KEY=$(openssl rand -hex 32)\" \u003e\u003e .env\n```\n\nThe server will display a security warning at startup if using the default key.\n\n### Network Exposure\n\n- **Local-only (default):** Safe to use default key for `localhost` testing\n- **LAN/Docker:** Change the API key before exposing to your network\n- **Internet:** **Always** use a strong API key + consider a reverse proxy with HTTPS\n\n### SSRF Protection\n\nThe API validates all `audio_url` parameters to prevent Server-Side Request Forgery:\n\n- Blocks internal IPs (127.0.0.1, 10.x.x.x, 192.168.x.x, etc.)\n- Blocks cloud metadata endpoints (169.254.169.254)\n- Only allows HTTP/HTTPS schemes\n- Resolves DNS and validates the resolved IP\n\n## Troubleshooting\n\n**CUDA not available:**\n```bash\n# Check NVIDIA driver\nnvidia-smi\n\n# Check PyTorch CUDA\npython -c \"import torch; print(torch.cuda.is_available())\"\n```\n\n**Out of VRAM:**\n- Use smaller model: `MURMURAI_MODEL=medium`\n- Reduce batch size: `MURMURAI_BATCH_SIZE=8`\n\n**Diarization fails:**\n- Verify HF token: `echo $MURMURAI_HF_TOKEN`\n- Accept license at HuggingFace (link above)\n\n---\n\n## Built On\n\nThis project uses [murmurai-core](https://pypi.org/project/murmurai-core/) - our maintained fork of [WhisperX](https://github.com/m-bain/whisperX) with modern dependency support (PyTorch 2.6+, Pyannote 4.x, Python 3.10-3.13).\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch2\u003eDevelopment\u003c/h2\u003e\u003c/summary\u003e\n\n### Setup\n\n```bash\ngit clone https://github.com/namastexlabs/murmurai.git\ncd murmurai\nuv sync\n```\n\n### Run Tests\n\n```bash\nuv run pytest tests/ -v\n```\n\n### Code Quality\n\n```bash\nuv run ruff check .\nuv run ruff format .\nuv run mypy src/\n```\n\n### Project Structure\n\n```\nmurmurai/\n├── src/murmurai/\n│   ├── server.py          # FastAPI application\n│   ├── transcriber.py     # Transcription pipeline\n│   ├── model_manager.py   # GPU model caching\n│   ├── database.py        # SQLite persistence\n│   ├── config.py          # Settings management\n│   ├── auth.py            # API authentication\n│   ├── models.py          # Pydantic schemas\n│   ├── deps.py            # Dependency checks\n│   └── main.py            # CLI entry point\n├── tests/                 # Test suite\n├── get-murmurai.sh        # One-liner installer\n└── pyproject.toml         # Project config\n```\n\n### CI/CD\n\n- **CI:** Runs on every push (lint, typecheck, test)\n\n### Performance Notes\n\n- **First request:** ~60-90s (model loading)\n- **Subsequent:** ~same as audio duration\n- **VRAM usage:** ~5-6GB for large-v3-turbo\n\n\u003c/details\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ by \u003ca href=\"https://github.com/namastexlabs\"\u003eNamastex Labs\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/namastexlabs/murmurai\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/namastexlabs/murmurai?style=social\" alt=\"Star us on GitHub\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamastexlabs%2Fmurmurai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnamastexlabs%2Fmurmurai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamastexlabs%2Fmurmurai/lists"}