CrispASR Agent Transcriber

crispasr-agent-transcriber

CrispASRを活用した、Codex および MCP ベースの AI エージェント向けローカル専用文字起こしツールです。クラウドへのアップロードはなく、文字起こしに API キーは必要ありません。

GitHub リリース | npm インストーラー | PyPI パッケージ | MCP Registry

できること

ローカルの音声ファイルまたは動画ファイルを渡すと、次の処理を行います。

1. CrispASR の FireRed LID を使って、話されている言語（英語または中国語）を判定します。
2. 適切なバックエンド（英語には Cohere Transcribe、中国語には Qwen3-ASR）を使用して、ローカルの CrispASR サーバーを起動します。
3. 必要に応じて、ffmpeg で動画から音声を抽出します。
4. CrispASR の /v1/audio/transcriptions エンドポイントを呼び出します。
5. 文字起こし結果とメタデータをディスクに書き込みます。
6. 動画を理解するために、同期されたキーフレームを取得し、エージェントが読み取れるマニフェストを書き込みます。

すべての処理はお使いのマシン上で実行されます。メディアが外部に送信されることはありません。

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 マーケットプレイスにプラグインを登録します。
• 更新時に既存のモデル、バイナリ、出力を保持します。

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 デスクトップの「プラグイン」ビューを開き、Personal マーケットプレイスから 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 エージェントで使用する

MCP サーバーは、さまざまなエージェントで共通して使えるインターフェースです。MCP stdio に対応したエージェントなら、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 エージェントとの連携を参照してください。

メンテナー向け公開手順

エンドユーザーはリリース手順を実行する必要はありません。メンテナーは、Codex Marketplace、PyPI、MCP Registry、他のエージェントへの配布について、公開ガイドに従ってください。

必要なモデル

インストールや更新でモデルがダウンロードされることはありません。明示的に models コマンドを使用するか、次の推奨される3つの 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

3つのアップストリームモデルファミリーは、すべて 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	動画を文字起こしし、同期したキーフレームを取得して、エージェント向けコンテキストを返します
transcribe_folder	フォルダー内のファイルを一括で文字起こしします

セキュリティモデル

• クラウドへのアップロードはありません。 メディアファイルはローカルファイルシステムに保持されます。
• デフォルトではリモートサーバーを使用しません。 --server-url で指定できるのは localhost のみです。--allow-remote-server を明示的に渡した場合に限り、リモートサーバーを指定できます。
• URL 入力には対応していません。 ローカルファイルパスのみ受け付けます。URL、S3、その他のリモートスキームは拒否されます。
• シェルインジェクションは発生しません。 ffmpeg は引数リストと shell=False を使って呼び出されます。ユーザーが制御する文字列がシェルコマンドに埋め込まれることはありません。
• モデルを暗黙的にダウンロードしません。 インストールや更新ではモデルをダウンロードしません。また、CrispASR のモデル自動ダウンロード（-m auto）には --allow-model-auto-download が必要です。models コマンドと crispasr_download_models ツールでは、許可リストに登録された Hugging Face ファイルのみをダウンロードします。
• 一時ファイルはクリーンアップされます。 変換された WAV ファイルと LID プローブ用ウィンドウは、文字起こしの完了時に削除されます。
• バイナリのダウンロードは明示的です。 CrispASR のバイナリは、公式の CrispStrobe/CrispASR GitHub リリースからのみインストールされます。
• プラグインのリリースを検証します。 npm インストーラーでは、プラグイン ZIP が同じ GitHub Release で公開されている SHA-256 値と一致する必要があります。
• インストーラーによる書き込み範囲を限定しています。 インストーラーが管理するのは、プラグインディレクトリと名前が指定された Personal マーケットプレイスのエントリのみです。更新時も、ローカルモデル、バイナリ、出力は保持されます。
• 生成された動画解析データはローカルに保持されます。 動画のキーフレーム、マニフェスト、エージェント向けコンテキストファイルは、選択した出力ディレクトリに書き込まれ、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（このツールでは使用しません）