{
  "markdown": "# crispasr-agent-transcriber\n\n<!-- mcp-name: io.github.EmiyaKatuz/crispasr-agent-transcriber -->\n\nLocal-only transcription for Codex and MCP-based AI agents, powered by\n[CrispASR](https://github.com/CrispStrobe/CrispASR). No cloud uploads,\nno API keys required for transcription.\n\n[GitHub Release](https://github.com/EmiyaKatuz/crispasr-agent-transcriber/releases/latest)\n| [npm installer](https://www.npmjs.com/package/@emiyakatuz/crispasr-agent-transcriber)\n| [PyPI package](https://pypi.org/project/crispasr-agent-transcriber/)\n| [MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.EmiyaKatuz%2Fcrispasr-agent-transcriber)\n\n## What it does\n\nGive it a local audio or video file. It:\n\n1. Probes the spoken language (English or Chinese) using CrispASR's FireRed LID.\n2. Starts a local CrispASR server with the right backend -- Cohere Transcribe\n   for English, Qwen3-ASR for Chinese.\n3. Extracts audio from video with ffmpeg when needed.\n4. Calls CrispASR's `/v1/audio/transcriptions` endpoint.\n5. Writes the transcript and metadata to disk.\n6. For video understanding, captures synchronized keyframes and writes an\n   agent-readable manifest.\n\nEverything runs on your machine. Media never leaves it.\n\n## Quick install for Codex\n\nThe plugin includes the Codex Skill, command-line tool, and MCP server. Media\nstays on your computer. Model files are never downloaded during install/update;\nuse the explicit `models` command when you want the installer to fetch them.\n\n### 1. Install prerequisites\n\nInstall Node.js 20 or newer, [uv](https://docs.astral.sh/uv/), and\n[ffmpeg](https://ffmpeg.org/). The installer uses `uv` to provide Python.\n\n```powershell\nnode --version\nuv --version\nffmpeg -version\n```\n\n### 2. Run the installer\n\n```powershell\nnpx @emiyakatuz/crispasr-agent-transcriber@latest install\n```\n\nThe installer:\n\n- downloads the matching GitHub Release and verifies its SHA-256 checksum;\n- installs the plugin under `~/plugins/crispasr-agent-transcriber`;\n- installs the Python and MCP dependencies;\n- detects CUDA, Vulkan, or CPU and installs the best CrispASR build;\n- registers the plugin in the Codex Personal marketplace;\n- preserves existing models, binaries, and outputs during updates.\n\n### 3. Add the local models\n\nDownload the recommended local English, Chinese, and language-detection bundle:\n\n```powershell\nnpx @emiyakatuz/crispasr-agent-transcriber@latest models\n```\n\nThe command downloads only approved GGUF files into:\n\n```text\n~/plugins/crispasr-agent-transcriber/models/\n```\n\nThen verify the installation:\n\n```powershell\nnpx @emiyakatuz/crispasr-agent-transcriber@latest doctor\n```\n\n### 4. Enable the plugin\n\nWith a Codex build that supports plugin commands, run:\n\n```powershell\ncodex plugin add crispasr-agent-transcriber@personal\n```\n\nIf the CLI has no `codex plugin` command, open the Codex desktop Plugins view\nand install **CrispASR Transcriber** from the Personal marketplace. Start a new\nconversation, then ask:\n\n```text\nTranscribe C:\\path\\to\\sample.mp4 with CrispASR using auto language detection.\nSave a verbose JSON transcript and an SRT subtitle file.\n```\n\n### Update or uninstall\n\n```powershell\nnpx @emiyakatuz/crispasr-agent-transcriber@latest update\nnpx @emiyakatuz/crispasr-agent-transcriber@latest uninstall\n```\n\nUninstall preserves local models, CrispASR binaries, and outputs. Use\n`uninstall --purge-data` only when those files should also be deleted. See\n[Plugin installation](docs/plugin_install.md) for manual installation and\ntroubleshooting.\n\n## Direct command-line use\n\nAfter installation, you can run the transcription script without Codex:\n\n```powershell\nSet-Location (Join-Path $HOME \"plugins\\crispasr-agent-transcriber\")\nuv run python scripts/transcribe.py sample.mp4 --profile auto `\n  --manage-server `\n  --models-dir models `\n  --format verbose_json\n```\n\n## Use with other AI agents\n\nThe MCP server is the cross-agent interface. Any agent that supports MCP stdio\ncan run the released package directly from GitHub:\n\n```powershell\nuvx --from \"crispasr-agent-transcriber[mcp] @ git+https://github.com/EmiyaKatuz/crispasr-agent-transcriber.git@v0.4.0\" crispasr-agent-mcp\n```\n\nUse the same command and arguments in Claude Desktop, Cursor, or another MCP\nclient. See [AI agent integrations](docs/agent_integrations.md) for a generic\nMCP configuration and Codex CLI command.\n\n## Maintainer publishing\n\nEnd users do not need the release steps. Maintainers should follow the\n[publishing guide](docs/publishing.md) for Codex Marketplace, PyPI, MCP\nRegistry, and cross-agent distribution.\n\n## Required models\n\nInstall/update never downloads models. Use the explicit `models` command or\ndownload these three recommended GGUF files into a local directory such as\n`models/`:\n\n| Purpose | Local file | Variant / size | Model page | File page |\n|---|---|---|---|---|\n| English ASR | `cohere-transcribe-q4_k.gguf` | Q4_K, smaller default | [Cohere Transcribe 03-2026 GGUF](https://huggingface.co/cstr/cohere-transcribe-03-2026-GGUF) | [Download](https://huggingface.co/cstr/cohere-transcribe-03-2026-GGUF/blob/main/cohere-transcribe-q4_k.gguf) |\n| Chinese ASR | `qwen3-asr-1.7b-q4_k.gguf` | Q4_K, smaller default | [Qwen3-ASR 1.7B GGUF](https://huggingface.co/cstr/qwen3-asr-1.7b-GGUF) | [Download](https://huggingface.co/cstr/qwen3-asr-1.7b-GGUF/blob/main/qwen3-asr-1.7b-q4_k.gguf) |\n| Language detection | `firered-lid-q4_k.gguf` | Q4_K default | [FireRed LID GGUF](https://huggingface.co/cstr/firered-lid-GGUF) | [Download](https://huggingface.co/cstr/firered-lid-GGUF/blob/main/firered-lid-q4_k.gguf) |\n\nOptional model IDs include `english-q5-0`, `english-q5-1`, `english-q6`,\n`english-q8`, `english-f16`, `chinese-q8`, `chinese-f16`, `lid-q2`, `lid-q8`,\nand `lid-f16`. Download a specific option with:\n\n```powershell\nnpx @emiyakatuz/crispasr-agent-transcriber@latest models --model-id english-q8\n```\n\nAll three upstream model families are Apache 2.0 licensed.\n\nFor automatic English/Chinese routing, pass both ASR paths. The language probe\nruns first, and only the matching model is loaded:\n\n```powershell\n--english-model models\\cohere-transcribe-q4_k.gguf\n--chinese-model models\\qwen3-asr-1.7b-q4_k.gguf\n--lid-backend firered --lid-model models\\firered-lid-q4_k.gguf\n```\n\nFor an explicit `english` or `chinese` profile, `--model` remains available as\na single-model override.\n\n## CrispASR binary management\n\nThe tool auto-detects, installs, and updates the CrispASR binary from\n[GitHub releases](https://github.com/CrispStrobe/CrispASR/releases).\n\n| Flag | Effect |\n|---|---|\n| `--install-crispasr` | Download latest platform binary to `bin/` |\n| `--update-crispasr` | Upgrade to newest release |\n| `--crispasr-status` | Show installed version + update availability |\n| `--crispasr-bin-dir PATH` | Custom directory (default `./bin`) |\n| `--crispasr-bin PATH` | Exact path to `crispasr.exe` |\n\nWhen `--manage-server` is set and no binary is found, it auto-installs before\nstarting the server.\n\n### GPU detection\n\nOn install and update, the tool checks your hardware:\n\n1. **CUDA** -- `nvidia-smi` available, or `CUDA_PATH` / `CUDA_HOME` set, or\n   CUDA in `PATH` -> downloads `crispasr-*-cuda` variant.\n2. **Vulkan** -- `vulkaninfo` or `VULKAN_SDK` set (only when CUDA is absent) ->\n   downloads `crispasr-*-vulkan` variant.\n3. **CPU** -- fallback when no GPU toolkit is detected.\n\nmacOS always uses the universal binary.\n\n## Profiles\n\n| Profile | Backend | ASR model | Language hint |\n|---|---|---|---|\n| `english` | `cohere` | Cohere Transcribe 03-2026 | `en` |\n| `chinese` | `qwen3-1.7b` | Qwen3-ASR 1.7B | `zh` |\n| `auto` | determined by LID | determined by LID | detected |\n\n`auto` mode runs FireRed language detection on the media, then routes English\nto Cohere or Chinese to Qwen3-1.7B. Mixed or uncertain content stops with a\nclear error asking you to re-run with `--profile english` or `--profile chinese`.\n\n## Usage\n\n### Managed server (tool starts CrispASR for you)\n\n```powershell\nuv run python scripts/transcribe.py sample.wav `\n  --profile auto `\n  --manage-server `\n  --models-dir models `\n  --format srt `\n  --out-dir outputs\n```\n\nAdd `--keep-server` to leave the server running after transcription.\n\n### Manual server (you start CrispASR)\n\n```powershell\n# Terminal 1 -- start the server\ncrispasr --server --backend cohere `\n  -m models\\cohere-transcribe-q4_k.gguf `\n  --port 8080\n\n# Terminal 2 -- transcribe\nuv run python scripts/transcribe.py sample.mp4 `\n  --profile english `\n  --server-url http://127.0.0.1:8080 `\n  --format verbose_json\n```\n\nIf the running server's backend doesn't match the selected profile, the tool\nprints the exact command you need to start the correct server.\n\n### Output formats\n\n| `--format` | File extension | Contents |\n|---|---|---|\n| `text` | `.txt` | Plain transcript |\n| `verbose_json` | `.json` | Full response with segments |\n| `srt` | `.srt` | SubRip subtitles |\n| `vtt` | `.vtt` | WebVTT subtitles |\n\nA `.metadata.json` sidecar is always written alongside the transcript.\n\n### Video files\n\nVideo files are detected automatically. ffmpeg extracts the audio track to a\ntemporary mono 16 kHz WAV before sending it to CrispASR. The temporary file\nis deleted when transcription finishes.\n\n### All CLI flags\n\n```\n--profile auto|english|chinese\n--format text|verbose_json|srt|vtt|json\n--out-dir PATH\n--server-url URL\n--allow-remote-server\n--manage-server\n--keep-server\n--model PATH               Local GGUF override for an explicit profile\n--english-model PATH       Cohere model selected after English detection\n--chinese-model PATH       Qwen3-ASR model selected after Chinese detection\n--models-dir PATH          Directory containing approved local GGUF models\n--allow-model-auto-download\n--lid-model PATH           Local LID model path\n--lid-backend firered|silero|ecapa|whisper\n--host HOST                Managed server host (default 127.0.0.1)\n--port PORT                Managed server port (default 8080)\n--language CODE            Language hint for transcription\n--prompt TEXT              Initial prompt/context\n--vad                      Enable voice activity detection\n--diarize                  Enable speaker diarization\n--diarize-method METHOD\n--hotwords WORD,WORD       Comma-separated hotwords\n--no-timestamps\n--preprocess auto|always|never\n--api-key KEY              If CRISPASR_API_KEYS is enabled\n--crispasr-bin-dir PATH\n--crispasr-bin PATH\n--install-crispasr\n--update-crispasr\n--crispasr-status\n--list-models\n--download-models\n--model-id MODEL_ID\n--overwrite-models\n```\n\n## MCP server\n\n```powershell\nuv sync --extra mcp\nuv run --extra mcp crispasr-agent-mcp\n```\n\nExposed tools:\n\n| Tool | Description |\n|---|---|\n| `crispasr_health` | Check CrispASR server health |\n| `crispasr_backends` | List available backends |\n| `crispasr_detect_language` | Run language detection on a file |\n| `crispasr_list_models` | List approved model choices and local install status |\n| `crispasr_download_models` | Explicitly download approved model files |\n| `crispasr_resolve_model_paths` | Return recommended local model paths |\n| `transcribe_audio` | Transcribe an audio file |\n| `transcribe_video` | Transcribe a video file |\n| `understand_video` | Transcribe a video, capture synced keyframes, and return an agent context |\n| `transcribe_folder` | Batch-transcribe a folder |\n\n## Security model\n\n- **No cloud uploads.** Media files stay on the local filesystem.\n- **No remote servers by default.** `--server-url` only accepts localhost\n  unless `--allow-remote-server` is explicitly passed.\n- **No URL inputs.** Only local file paths are accepted. URLs, S3, and other\n  remote schemes are rejected.\n- **No shell injection.** ffmpeg is called with argument lists and\n  `shell=False`. No user-controlled strings are interpolated into shell\n  commands.\n- **No implicit model downloads.** Install/update never downloads models, and\n  CrispASR model auto-download (`-m auto`) requires\n  `--allow-model-auto-download`. The `models` command and\n  `crispasr_download_models` tool download only allowlisted Hugging Face files.\n- **Temporary files are cleaned up.** Converted WAV files and LID probe\n  windows are deleted when transcription finishes.\n- **Binary downloads are explicit.** CrispASR binary installs only from the\n  official `CrispStrobe/CrispASR` GitHub releases.\n- **Verified plugin releases.** The npm installer requires the plugin ZIP to\n  match the SHA-256 value published in the same GitHub Release.\n- **Narrow installer writes.** The installer manages only its plugin directory\n  and the named Personal marketplace entry. Updates preserve local models,\n  binaries, and outputs.\n- **Generated understanding stays local.** Video keyframes, manifests, and\n  agent context files are written under the selected output directory and are\n  ignored by Git.\n\n## Verify\n\n```powershell\nuv run pytest\nuv run ruff check .  # zero lint warnings\n```\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n### Third-party components and attribution\n\nThis tool orchestrates several independently-licensed projects. It does not\nbundle, fork, or redistribute their code -- it downloads pre-built binaries\nand calls them as subprocesses or HTTP services at runtime.\n\n| Component | License | Role |\n|---|---|---|\n| [CrispASR](https://github.com/CrispStrobe/CrispASR) | MIT | ASR engine, server, language detection |\n| [ffmpeg](https://ffmpeg.org/) | LGPL 2.1+ / GPL 2+ | Media decoding and audio extraction |\n| [Cohere Transcribe 03-2026](https://huggingface.co/cstr/cohere-transcribe-03-2026-GGUF) | Apache 2.0 | English ASR model (loaded by CrispASR) |\n| [Qwen3-ASR 1.7B](https://huggingface.co/cstr/qwen3-asr-1.7b-GGUF) | Apache 2.0 | Chinese ASR model (loaded by CrispASR) |\n| [FireRed LID](https://huggingface.co/cstr/firered-lid-GGUF) | Apache 2.0 | Language detection model (loaded by CrispASR) |\n| [httpx](https://github.com/encode/httpx) | BSD | HTTP client for CrispASR API |\n| [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) | MIT | MCP server framework |\n| [Node.js](https://nodejs.org/) | MIT | npm installer runtime |\n| [adm-zip](https://github.com/cthackers/adm-zip) | MIT | Verified plugin ZIP extraction |\n\nModel files must be downloaded separately by the user from their respective\nHuggingFace repositories. See [Required models](#required-models) above.\n\n## Related projects\n\n- [CrispASR](https://github.com/CrispStrobe/CrispASR) -- the ASR engine this\n  tool wraps\n- [CrisperWeaver](https://github.com/CrispStrobe/CrisperWeaver) -- CrispASR's\n  desktop GUI (not used by this tool)\n",
  "bytes": 14559,
  "sha": "3b42a2ffa53cb9287ece34c51f11a5e8042fe95cb0b109a344641908e99b374d",
  "repo_slug": "emiyakatuz/crispasr-agent-transcriber",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_emiyakatuz_crispasr_agent_tran_02f059b4/readme"
}