CrispASR Agent Transcriber

crispasr-agent-transcriber

由 CrispASR 驱动，为 Codex 和基于 MCP 的 AI Agent 提供仅限本地的转录功能。无需上传到云端，也无需 API 密钥即可转录。

GitHub Release | npm 安装程序 | PyPI 软件包 | MCP Registry

功能介绍

提供本地音频或视频文件即可。它会：

1. 使用 CrispASR 的 FireRed LID 探测语音语言（英语或中文）。
2. 启动本地 CrispASR 服务，并选择合适的后端——英语使用 Cohere Transcribe，中文使用 Qwen3-ASR。
3. 必要时使用 ffmpeg 从视频中提取音频。
4. 调用 CrispASR 的 /v1/audio/transcriptions 端点。
5. 将转录文本和元数据写入磁盘。
6. 对于视频理解，捕获同步关键帧并生成 Agent 可读取的清单。

所有操作都在你的设备上运行。媒体文件不会离开设备。

Codex 快速安装

此插件包含 Codex Skill、命令行工具和 MCP 服务。媒体文件会保留在你的计算机上。安装或更新时不会下载模型文件；想让安装程序获取模型时，请使用显式的 models 命令。

1. 安装先决条件

安装 Node.js 20 或更高版本、uv 和 ffmpeg。安装程序使用 uv 来提供 Python。

node --version
uv --version
ffmpeg -version

2. 运行安装程序

npx @emiyakatuz/crispasr-agent-transcriber@latest install

安装程序会：

• 下载匹配的 GitHub Release，并验证其 SHA-256 校验和；
• 将插件安装到 ~/plugins/crispasr-agent-transcriber；
• 安装 Python 和 MCP 依赖项；
• 检测 CUDA、Vulkan 或 CPU，并安装最合适的 CrispASR 构建版本；
• 在 Codex Personal marketplace 中注册插件；
• 更新时保留现有模型、二进制文件和输出。

3. 添加本地模型

下载推荐的本地英语、中文和语言检测模型包：

npx @emiyakatuz/crispasr-agent-transcriber@latest models

该命令只会将经过批准的 GGUF 文件下载到：

~/plugins/crispasr-agent-transcriber/models/

然后验证安装：

npx @emiyakatuz/crispasr-agent-transcriber@latest doctor

4. 启用插件

使用支持插件命令的 Codex 构建版本，运行：

codex plugin add crispasr-agent-transcriber@personal

如果 CLI 中没有 codex plugin 命令，请打开 Codex 桌面版的 Plugins 视图，并从 Personal marketplace 安装 CrispASR Transcriber。开始新的对话，然后询问：

Transcribe C:\path\to\sample.mp4 with CrispASR using auto language detection.
Save a verbose JSON transcript and an SRT subtitle file.

更新或卸载

npx @emiyakatuz/crispasr-agent-transcriber@latest update
npx @emiyakatuz/crispasr-agent-transcriber@latest uninstall

卸载时会保留本地模型、CrispASR 二进制文件和输出。只有在也需要删除这些文件时，才使用 uninstall --purge-data。手动安装和故障排除请参阅插件安装。

直接通过命令行使用

安装后，你可以不通过 Codex，直接运行转录脚本：

Set-Location (Join-Path $HOME "plugins\crispasr-agent-transcriber")
uv run python scripts/transcribe.py sample.mp4 --profile auto `
  --manage-server `
  --models-dir models `
  --format verbose_json

与其他 AI Agent 配合使用

MCP 服务是跨 Agent 的接口。任何支持 MCP stdio 的 Agent 都可以直接从 GitHub 运行发布的软件包：

uvx --from "crispasr-agent-transcriber[mcp] @ git+https://github.com/EmiyaKatuz/[email protected]" crispasr-agent-mcp

在 Claude Desktop、Cursor 或其他 MCP 客户端中使用相同的命令和参数。通用 MCP 配置和 Codex CLI 命令请参阅 AI Agent 集成。

维护者发布

最终用户无需执行发布步骤。维护者应按照发布指南操作，以便向 Codex Marketplace、PyPI、MCP Registry 发布并进行跨 Agent 分发。

必需模型

安装／更新不会下载模型。请使用显式的 models 命令，或将以下三个推荐的 GGUF 文件下载到本地目录，例如 models/：

用途	本地文件	变体／大小	模型页面	文件页面
英语 ASR	cohere-transcribe-q4_k.gguf	Q4_K，较小的默认版本	Cohere Transcribe 03-2026 GGUF	下载
中文 ASR	qwen3-asr-1.7b-q4_k.gguf	Q4_K，较小的默认版本	Qwen3-ASR 1.7B GGUF	下载
语言检测	firered-lid-q4_k.gguf	Q4_K 默认版本	FireRed LID GGUF	下载

可选模型 ID 包括 english-q5-0、english-q5-1、english-q6、english-q8、english-f16、chinese-q8、chinese-f16、lid-q2、lid-q8 和 lid-f16。使用以下命令下载特定选项：

npx @emiyakatuz/crispasr-agent-transcriber@latest models --model-id english-q8

所有三个上游模型系列均采用 Apache 2.0 许可证。

要自动路由英语／中文，请传入两条 ASR 路径。语言探测会先运行，且只加载匹配的模型：

--english-model models\cohere-transcribe-q4_k.gguf
--chinese-model models\qwen3-asr-1.7b-q4_k.gguf
--lid-backend firered --lid-model models\firered-lid-q4_k.gguf

对于显式的 english 或 chinese 配置，仍可使用 --model 指定单模型覆盖项。

CrispASR 二进制文件管理

该工具会从 GitHub 发布页自动检测、安装和更新 CrispASR 二进制文件。

标志	效果
--install-crispasr	将最新的平台二进制文件下载到 bin/
--update-crispasr	升级到最新版本
--crispasr-status	显示已安装版本及更新可用性
--crispasr-bin-dir PATH	自定义目录（默认 ./bin）
--crispasr-bin PATH	crispasr.exe 的确切路径

设置 --manage-server 且未找到二进制文件时，会在启动服务前自动安装。

GPU 检测

安装和更新时，该工具会检查你的硬件：

1. CUDA -- nvidia-smi 可用，或已设置 CUDA_PATH / CUDA_HOME，或 PATH 中有 CUDA -> 下载 crispasr-*-cuda 变体。
2. Vulkan -- 有 vulkaninfo 或已设置 VULKAN_SDK（仅当没有 CUDA 时）-> 下载 crispasr-*-vulkan 变体。
3. CPU -- 未检测到 GPU 工具包时使用的回退选项。

macOS 始终使用通用二进制文件。

配置

配置	后端	ASR 模型	语言提示
english	cohere	Cohere Transcribe 03-2026	en
chinese	qwen3-1.7b	Qwen3-ASR 1.7B	zh
auto	由 LID 决定	由 LID 决定	检测结果

auto 模式会对媒体运行 FireRed 语言检测，然后将英语路由到 Cohere，或将中文路由到 Qwen3-1.7B。遇到混合或不确定的内容时，会停止并显示明确错误，要求你使用 --profile english 或 --profile chinese 重新运行。

用法

托管服务（工具为你启动 CrispASR）

uv run python scripts/transcribe.py sample.wav `
  --profile auto `
  --manage-server `
  --models-dir models `
  --format srt `
  --out-dir outputs

添加 --keep-server 可在转写后让服务继续运行。

手动服务（你启动 CrispASR）

# Terminal 1 -- start the server
crispasr --server --backend cohere `
  -m models\cohere-transcribe-q4_k.gguf `
  --port 8080

# Terminal 2 -- transcribe
uv run python scripts/transcribe.py sample.mp4 `
  --profile english `
  --server-url http://127.0.0.1:8080 `
  --format verbose_json

如果运行中的服务后端与所选配置不匹配，该工具会打印启动正确服务所需的确切命令。

输出格式

--format	文件扩展名	内容
text	.txt	纯文本转写稿
verbose_json	.json	包含分段的完整响应
srt	.srt	SubRip 字幕
vtt	.vtt	WebVTT 字幕

转写稿旁边始终会写入一个 .metadata.json 附属文件。

视频文件

视频文件会自动检测。ffmpeg 会先将音轨提取为临时的单声道 16 kHz WAV，再发送给 CrispASR。转写完成后会删除临时文件。

所有 CLI 标志

--profile auto|english|chinese
--format text|verbose_json|srt|vtt|json
--out-dir PATH
--server-url URL
--allow-remote-server
--manage-server
--keep-server
--model PATH               Local GGUF override for an explicit profile
--english-model PATH       Cohere model selected after English detection
--chinese-model PATH       Qwen3-ASR model selected after Chinese detection
--models-dir PATH          Directory containing approved local GGUF models
--allow-model-auto-download
--lid-model PATH           Local LID model path
--lid-backend firered|silero|ecapa|whisper
--host HOST                Managed server host (default 127.0.0.1)
--port PORT                Managed server port (default 8080)
--language CODE            Language hint for transcription
--prompt TEXT              Initial prompt/context
--vad                      Enable voice activity detection
--diarize                  Enable speaker diarization
--diarize-method METHOD
--hotwords WORD,WORD       Comma-separated hotwords
--no-timestamps
--preprocess auto|always|never
--api-key KEY              If CRISPASR_API_KEYS is enabled
--crispasr-bin-dir PATH
--crispasr-bin PATH
--install-crispasr
--update-crispasr
--crispasr-status
--list-models
--download-models
--model-id MODEL_ID
--overwrite-models

MCP 服务

uv sync --extra mcp
uv run --extra mcp crispasr-agent-mcp

提供的工具：

工具	描述
crispasr_health	检查 CrispASR 服务运行状况
crispasr_backends	列出可用后端
crispasr_detect_language	检测文件的语言
crispasr_list_models	列出已批准的模型选项和本地安装状态
crispasr_download_models	显式下载已批准的模型文件
crispasr_resolve_model_paths	返回建议的本地模型路径
transcribe_audio	转写音频文件
transcribe_video	转写视频文件
understand_video	转写视频、截取同步关键帧，并返回 Agent 上下文
transcribe_folder	批量转写文件夹

安全模型

• 不上传到云端。 媒体文件保留在本地文件系统中。
• 默认不使用远程服务。 --server-url 仅接受 localhost，除非显式传入 --allow-remote-server。
• 不接受 URL 输入。 仅接受本地文件路径。URL、S3 和其他远程协议均会被拒绝。
• 防止 Shell 注入。 调用 ffmpeg 时使用参数列表并设置 shell=False。不会将用户可控的字符串插入 Shell 命令。
• 不隐式下载模型。 安装和更新都不会下载模型；CrispASR 模型自动下载（-m auto）需要使用 --allow-model-auto-download。models 命令和 crispasr_download_models 工具仅下载 Hugging Face 允许列表中的文件。
• 清理临时文件。 转写完成后会删除转换生成的 WAV 文件和 LID 探测窗口。
• 二进制文件下载需显式操作。 CrispASR 二进制文件仅从官方 CrispStrobe/CrispASR GitHub releases 安装。
• 验证插件发布文件。 npm 安装程序会要求插件 ZIP 与同一 GitHub Release 中发布的 SHA-256 值相符。
• 安装程序仅写入指定位置。 安装程序只管理其插件目录和指定的 Personal marketplace 条目。更新会保留本地模型、二进制文件和输出。
• 生成的理解结果保留在本地。 视频关键帧、清单和 Agent 上下文文件会写入所选输出目录，并由 Git 忽略。

验证

uv run pytest
uv run ruff check .  # zero lint warnings

许可证

本项目采用 MIT License。

第三方组件和归属声明

此工具负责协调多个采用独立许可证的项目。它不会捆绑、分叉或重新分发这些项目的代码，而是在运行时下载预构建的二进制文件，并将其作为子进程或 HTTP 服务调用。

组件	许可证	用途
CrispASR	MIT	ASR 引擎、服务、语言检测
ffmpeg	LGPL 2.1+ / GPL 2+	媒体解码和音频提取
Cohere Transcribe 03-2026	Apache 2.0	英语 ASR 模型（由 CrispASR 加载）
Qwen3-ASR 1.7B	Apache 2.0	中文 ASR 模型（由 CrispASR 加载）
FireRed LID	Apache 2.0	语言检测模型（由 CrispASR 加载）
httpx	BSD	CrispASR API 的 HTTP 客户端
MCP Python SDK	MIT	MCP 服务框架
Node.js	MIT	npm 安装程序运行时
adm-zip	MIT	验证插件 ZIP 并提取

用户必须从各自的 HuggingFace 仓库单独下载模型文件。请参阅上文的必需模型。

相关项目

• CrispASR —— 此工具封装的 ASR 引擎
• CrisperWeaver —— CrispASR 的桌面 GUI（此工具不会使用）