funasr-transcribe

FunASR 语音转文字

本 skill 提供本地语音识别服务，将音频或视频文件转换为结构化的 Markdown 文档。

功能概述

• 支持多种音视频格式（mp4、mov、mp3、wav、m4a、flac 等）
• 自动生成时间戳
• 支持说话人分离（diarization，默认启用）
• ONNX 加速模式：支持 paraformer-onnx 与实验性的 SenseVoice-Small ONNX
• 单人快速模式：--fast / "fast": true 关闭 diarization，默认仍走 paraformer
• Paraformer ONNX 后处理优化：paraformer-onnx 单人/多人路径都会先 VAD 分段，再清理文本输出、恢复标点并输出句子级时间戳；单人路径使用全局标点恢复，多人路径使用逐段标点以保留 speaker 对齐
• 视频关键帧截图提取：自动检测并提取 PPT 幻灯片，插入到转录稿对应位置（视频文件自动启用）
• 转录后自动附带 AI 总结提示词，Agent 可一步完成总结
• 输出 Markdown 格式，便于阅读和编辑

依赖

系统依赖

依赖	安装方式
Python 3.8+	macOS: brew install [email protected]
curl	macOS 通常自带；如缺失可执行 brew install curl

Python 包

包名	用途	安装命令
funasr	FunASR 原生推理与 CAM++ diarization	pip install -r assets/requirements.txt
funasr-onnx	Paraformer / SenseVoice ONNX 加速	pip install -r assets/requirements.txt
scenedetect[opencv]、imagehash	视频关键帧提取	pip install -r assets/requirements.txt

首次需要运行 ONNX 模式时，直接执行：

python3 scripts/setup.py

即可同时安装 funasr-onnx 及其依赖；SenseVoiceSmall 仅在显式指定 model=sensevoice 时按需下载。

ONNX 质量调参

paraformer-onnx 默认使用质量优先的参数组合；单人路径会复用多人路径的 ONNX VAD 分段 ASR，但不执行 CAM++ 说话人聚类：

参数	默认值	说明
FUNASR_ONNX_TEXT_SOURCE	preds	使用清理后的 ONNX preds 文本；如遇到异常可设为 raw_tokens 回退
FUNASR_SERVER_ONNX_THREADS	4	ONNX Runtime 推理线程数，主要影响速度，不直接改善识别质量
FUNASR_ONNX_COMPAT_CACHE	~/.cache/funasr-onnx-compat	ONNX 兼容导出缓存目录；兼容导出会复制模型目录，可删除该缓存后重新生成

单人 paraformer-onnx 会将各 VAD 片段的识别文本先拼接，再做一次全局标点恢复；这样比逐片段恢复标点更接近原生 paraformer，也能减少重复调用标点模型的耗时。

ONNX 句子级时间戳是根据字符位置和 token 时间戳做的近似映射，适合定位段落和发言轮次，不应视为逐字强对齐结果。

已验证不建议作为默认的调参方向：

• 调大 VAD 静音阈值会减少切段并提速，但 90 秒多人样本上文本相似度下降明显。
• 合并相邻 VAD 段或整段转录更容易出现错字、重复和长音频塌缩，因此单人和多人 ONNX 都不再默认整段转录。
• 给 VAD 片段额外 padding 会引入边界重复，整体质量不如默认切段。

Agent 默认工作流（转录 + 自动总结）

当用户请求转录音频/视频时，应遵循以下流程，一次性完成转录和 AI 总结：

前置步骤（必须第一个执行）：设置 PATH。 某些执行环境（如 agent-executor headless 模式）的 PATH 被限制为只有插件目录，curl、python3 等系统命令找不到。必须先执行：

export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"

之后所有 bash 命令都必须在同一命令块中跟在 export PATH=... 后面，或在每个命令块开头都加上这行。

步骤 0：环境检测（自动）

在执行转录前，检查 assets/skill-env.json 是否存在。如果不存在，先运行环境检测：

export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && cd <skill目录> && python3 scripts/init_env.py

如果检测失败（退出码非0），按提示运行安装脚本：

export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && cd <skill目录> && python3 scripts/setup.py

安装完成后会自动重新检测并生成 skill-env.json。

步骤 1：启动/检查服务

export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && curl -s http://127.0.0.1:8765/health

如果服务未运行，后台启动：

export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && cd <skill目录> && python3 scripts/server.py --idle-timeout 600 &

等待服务就绪（轮询 /health 直到返回 200）。

步骤 2：转录文件

export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && curl -s -X POST http://127.0.0.1:8765/transcribe \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/path/to/audio.aac"}'

注意：diarize 默认为 true，无需显式传入。如需禁用，传 "diarize": false。 视频文件（mp4、mov 等）会自动启用关键帧截图提取（extract_slides），无需手动传入。如需禁用，显式传 "extract_slides": false。 单人讲课/语音可传 "fast": true 关闭说话人分离，默认仍使用 paraformer；"model": "sensevoice" 仅作为实验性显式选项。

响应中包含以下关键字段：

• output_path: 转录输出的 Markdown 文件路径
• text: 转录全文
• summary_prompt: AI 总结提示词（已自动附带，无需额外调用 /summary）
• text_preview: 转录文本前 500 字预览

步骤 3：生成 AI 总结

根据 summary_prompt（或直接根据 text 内容），Agent 生成结构化 JSON 总结：

{
  "full_summary": "至少400字，分成2-3段，交代背景、问题、关键事实、数据、风险与行动建议",
  "speaker_summary": [
    {
      "speaker_order": "发言人1",
      "speaker_name": "如能识别请写姓名，否则写未知",
      "summary": "至少180字，涵盖该发言人的观点、依据、数据、态度与潜在影响"
    }
  ],
  "highlights": ["6-10条重点，每条60-100字"],
  "keywords": ["5-8个关键词"]
}

步骤 4：注入总结到文件

重要：不要只描述注入操作，必须实际执行以下命令。

将步骤 3 生成的 JSON 写入临时文件，然后调用脚本注入（比 curl 注入更可靠，无需 JSON 转义）：

export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && cat > /tmp/summary_<文件名>.json << 'JSONEOF'
{步骤3生成的JSON内容}
JSONEOF
python3 <skill目录>/scripts/summary.py inject "<output_path>" /tmp/summary_<文件名>.json

脚本会自动：

• 解析 JSON 并格式化为 Markdown
• 注入到 Markdown 文件的正确位置
• 添加 / 标记

步骤 5：验证注入结果（必须执行）

注入后必须执行验证，确认摘要确实写入文件。如果验证失败，必须重试步骤 4。

export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" && python3 <skill目录>/scripts/summary.py verify "<output_path>"

• 如果输出 ✅ 摘要已存在 → 成功，向用户报告完成
• 如果输出 ❌ 摘要不存在 → 失败，回到步骤 4 重试

完整流程示例

用户：转录这个音频
  ↓
Agent：
  1. 检查/启动服务
  2. POST /transcribe {"file_path": "xxx.aac"}  ← 一次调用拿到转录+提示词
  3. 根据转录内容直接生成总结 JSON
  4. 写 JSON 到临时文件 → python3 summary.py inject 注入
  5. python3 summary.py verify 验证 → 失败则重试步骤 4
  ↓
用户：收到带 AI 总结的 Markdown 文件

使用流程

首次使用：环境检测与依赖安装

重要：首次使用前必须先检测环境是否满足要求。

运行环境检测：

python3 scripts/check_env.py

检测脚本会检查以下环境要求：

必需项	要求	检测命令
Python	>= 3.8，python3 命令可用	python3 --version
curl	HTTP 客户端（用于 API 调用）	curl --version
基本命令	ls, ps, grep	shell 内置

如果环境检测失败：

1. Python3 命令不可用：

   # macOS 使用 homebrew 安装 Python
   brew install [email protected]
   

2. curl 不可用：

   # macOS 确保 curl 已安装
   brew install curl
   

3. 验证环境修复后，重新运行检测：

   python3 scripts/check_env.py
   

首次使用：安装依赖和下载模型

运行安装脚本完成环境配置：

python3 scripts/setup.py

安装脚本会自动：

1. 检查 Python 版本（需要 >= 3.8）
2. 安装依赖包（FastAPI、Uvicorn、FunASR、funasr-onnx、PyTorch）
3. 下载 ASR 模型到 ~/.cache/modelscope/hub/models/

验证安装状态：

python3 scripts/setup.py --verify

転写サービスを起動する

python3 scripts/server.py

ONNX アクセラレーションと INT8 量子化をデフォルトで有効にする場合は、次を使用します。

python3 scripts/server-onnx.py --preload

サービスはデフォルトで http://127.0.0.1:8765 で実行されます。

スマート機能：

• 自動起動：初回リクエスト時にモデルを自動的に読み込みます
• アイドル時の終了：デフォルトでは、10 分間アクティビティがないとリソース節約のため自動的に終了します
• タイムアウトの設定：--idle-timeout パラメーターを使用して、アイドルタイムアウト時間（秒）をカスタマイズできます

サービスのライフサイクル：

1. 起動後、アイドル監視状態になります
2. リクエストを受け取ると、モデルを自動的に読み込んで文字起こしを実行します
3. リクエストのたびにアイドルタイマーがリセットされます
4. 10 分間連続してリクエストがないと、自動的に終了します
5. 次のリクエスト時に再起動します

重要な注意事項：

• ⚠️ サービスを手動で終了しないでください - 文字起こしが完了してもサービスを稼働させたままにしてください。アクティビティがない状態が 10 分続くと自動的に終了します
• これにより、サービスを何度も起動せずに複数のファイルを連続して文字起こしできます
• サービスをすぐに終了する場合は、Ctrl+C を押すか、アイドルタイムアウトの 10 分が経過するまでお待ちください

例：アイドルタイムアウトを 30 分に設定する

python3 scripts/server.py --idle-timeout 1800

文字起こしを実行する

クライアントスクリプトを使用してファイルを文字起こしします。

# 转录单个文件
python3 scripts/transcribe.py /path/to/audio.mp3

# 指定输出路径
python3 scripts/transcribe.py /path/to/video.mp4 -o transcript.md

# 启用说话人分离
python3 scripts/transcribe.py /path/to/meeting.m4a --diarize

# Paraformer ONNX（更快；默认仍支持 diarization）
python3 scripts/transcribe.py /path/to/meeting.m4a --model paraformer-onnx

# Paraformer ONNX 单人路径（VAD 分段 ASR，不做说话人聚类）
python3 scripts/transcribe.py /path/to/course.m4a --model paraformer-onnx --no-diarize

# 单人讲课快速模式（关闭说话人分离，保留默认 Paraformer）
python3 scripts/transcribe.py /path/to/course.m4a --fast

# 批量转录目录
python3 scripts/transcribe.py /path/to/media_folder/

# 提取视频关键帧截图（PPT幻灯片）
python3 scripts/transcribe.py /path/to/video.mp4 --slides

# 自定义场景检测阈值（值越低越灵敏，默认20.0）
python3 scripts/transcribe.py /path/to/video.mp4 --slides --slide-threshold 15.0

AI によるスマート要約（Claude Code 環境）

文字起こしが完了した後、Claude Code のネイティブ AI 機能を活用して AI によるスマート要約を生成できます。

自動モード（推奨）：

--auto-summary パラメーターを使用すると、文字起こしの完了後に要約を自動生成して挿入します。

# 转录并自动生成总结（Claude Code 原生环境，无需配置 API Key）
python3 scripts/transcribe.py /path/to/audio.m4a --auto-summary

# 完整流程：说话人分离 + 自动总结
python3 scripts/transcribe.py /path/to/meeting.m4a --diarize --auto-summary

仕組み：

• スクリプトが構造化された要約リクエスト（AI_SUMMARY_REQUEST）を出力します
• Claude Code が自動的に認識し、組み込みの AI 機能を活用して要約を生成します
• 外部 API Key の設定は不要です

手動モード：

1. 文字起こしを実行すると、スクリプトが要約プロンプトを自動的に準備します
2. プロンプトを Claude AI に送信して、構造化された要約を生成します
3. Claude が返した JSON の結果をスクリプトに貼り付けます
4. 要約が Markdown ファイルに自動的に挿入されます

# 转录单个文件（输出提示词供手动调用）
python3 scripts/transcribe.py /path/to/audio.mp3

# 禁用自动总结（只输出提示词）
python3 scripts/transcribe.py /path/to/audio.m4a --no-summary

要約の内容：

• 全文要約 - 400 字以上で、背景、問題、重要な事実を含みます
• 話者別の要約 - 各話者の意見、態度、貢献
• 重要な内容 - 中核となる要点を 6～10 項目
• キーワード - 重要な用語を 5～8 個

プロンプトの特徴：

• 中国語の口語的な会話に特化して最適化されています
• 話者の文脈と会話の流れを保持します
• 解析やフォーマットに適した構造化 JSON を出力します

詳細については、こちらを参照してください：<references/api-reference.md>

HTTP API 経由で呼び出す

サービスの状態を確認する：

curl http://127.0.0.1:8765/health

curl を使用して API を直接呼び出します。

curl -X POST http://127.0.0.1:8765/transcribe \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/path/to/audio.mp3"}'

# 单人快速模式（关闭说话人分离，保留默认 Paraformer）
curl -X POST http://127.0.0.1:8765/transcribe \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/path/to/course.m4a", "fast": true}'

# 指定 Paraformer ONNX（默认启用 diarization）
curl -X POST http://127.0.0.1:8765/transcribe \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/path/to/meeting.m4a", "model": "paraformer-onnx"}'

# Paraformer ONNX 单人路径（VAD 分段 ASR，不做说话人聚类）
curl -X POST http://127.0.0.1:8765/transcribe \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/path/to/course.m4a", "model": "paraformer-onnx", "diarize": false}'

# 提取视频关键帧截图
curl -X POST http://127.0.0.1:8765/transcribe \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/path/to/video.mp4", "extract_slides": true}'

API ドキュメント（Swagger UI）：

FastAPI がインタラクティブな API ドキュメントを自動生成します。こちらにアクセスしてください：http://127.0.0.1:8765/docs

このページでは、次のことができます。

• すべての API エンドポイントを確認する
• API をオンラインでテストする（curl は不要です）
• リクエスト／レスポンスの形式を確認する
• パラメーターの詳細な説明を確認する

レスポンスの例（ヘルスチェック）：

{
  "status": "ok",
  "service": "FunASR Transcribe",
  "uptime": 300,
  "idle_time": 120
}

返却フィールドの説明：

• uptime：サービスの稼働時間（秒）
• idle_time：現在のアイドル時間（秒）

API ドキュメント全文

API リファレンスの詳細については、こちらを参照してください：<references/api-reference.md>

以下を含みます。

• すべての API エンドポイントの完全な仕様
• リクエスト／レスポンス形式の詳細
• パラメーターの説明と例
• curl コマンドの完全な例

スクリプトの説明

スクリプト	用途
scripts/init_env.py	環境検出 + skill-env.json の生成
scripts/check_env.py	環境検出（簡易版）
scripts/setup.py	依存関係のインストールとモデルのダウンロードを一括実行
scripts/server.py	HTTP API サービスを起動
scripts/server-onnx.py	デフォルトの ONNX アクセラレーションサービスを起動
scripts/transcribe.py	コマンドラインクライアント
scripts/auto_transcribe.py	自動文字起こしスクリプト（推奨）

---

自動文字起こし + 要約のワークフロー

この skill は、任意のエージェントプラットフォームで文字起こし + 要約の全ワークフローを自動実行できます。

方法 1：自動化スクリプトを使用する（推奨）

# 自动转录 + 获取总结提示词（说话人分离默认启用）
python3 scripts/auto_transcribe.py /path/to/audio.aac

# 禁用说话人分离
python3 scripts/auto_transcribe.py /path/to/audio.aac --no-diarize

# 单人快速模式（关闭说话人分离，保留默认 Paraformer）
python3 scripts/auto_transcribe.py /path/to/course.m4a --fast

# 只获取总结提示词，不生成总结
python3 scripts/auto_transcribe.py /path/to/audio.aac --prompt-only

方法 2：HTTP API を呼び出す

1. 音声を文字起こしする（レスポンスには要約プロンプトが自動的に含まれます）

curl -X POST http://127.0.0.1:8765/transcribe \
  -H "Content-Type: application/json" \
  -d '{"file_path": "/path/to/audio.aac"}'

レスポンスには summary_prompt フィールドが含まれます。これを要約の生成に直接使用できるため、/summary を追加で呼び出す必要はありません。

2. AI 要約を挿入する

要約を生成した後、次を呼び出します。

curl -X POST http://127.0.0.1:8765/inject_summary \
  -H "Content-Type: application/json" \
  -d '{
    "md_path": "/path/to/audio.md",
    "summary_content": "## AI 摘要\n\n### 全文总结\n...\n\n### 重点内容\n- ...\n\n### 关键词\n..."
  }'

---

API エンドポイント一覧

エンドポイント	メソッド	機能
/health	GET	ヘルスチェック
/transcribe	POST	音声／動画の文字起こし
/batch_transcribe	POST	ディレクトリ内のファイルを一括で文字起こし
/summary	POST	AI 要約プロンプトを生成
/inject_summary	POST	要約を Markdown ファイルに挿入
/verify_summary	POST	要約が挿入済みかどうかを確認

設定ファイル

ファイル	説明
assets/models.json	ASR モデル設定一覧
assets/requirements.txt	Python 依存関係一覧

出力形式

文字起こし結果は Markdown ファイルとして保存され、次の内容が含まれます。

1. タイトル - ファイル名（文字起こしのタイムスタンプなし）
2. 文字起こし内容 - 形式：話者N HH:MM:SS の後に改行して 内容
3. AI 要約（任意）- 全文要約、話者別の要約、重要な内容、キーワードを含みます

形式の例（動画のスクリーンショットを含む場合）：

# 转录：视频.mp4

## 转录内容

发言人1 00:02:49
![](slides/slide_001_02m49s.jpg)
各位好，今天我们来讲...

发言人1 00:03:30
![](slides/slide_002_03m30s.jpg)
这是第二段的内容...

モデル情報

モデルは ModelScope のデフォルトキャッシュディレクトリ ~/.cache/modelscope/hub/models/ に保存されます。

• ASR メインモデル（Paraformer）- 867MB
• SenseVoice-Small（実験的な単一話者 ONNX パス）- 明示的に指定した場合に必要に応じてダウンロード
• VAD モデル - 4MB
• 句読点モデル - 283MB
• 話者分離モデル - 28MB

STT 文字起こしの優先順位（重要）

正しい順序：FunASR（優先）→ Whisper CLI（フォールバック）

• FunASR が第一選択です：中国語の認識精度がより高く、タイムスタンプ、話者分離、動画のキーフレームに対応しています
• Whisper CLI はフォールバックです：FunASR サービスを利用できない場合にのみ使用します（例：funasr-onnx のインストールに失敗した場合、サービスが 500 エラーを返す場合）
• 絶対にしないでください：FunASR を先に試さず、直接 Whisper を使用すること

FunASR が失敗した場合のトラブルシューティング手順

1. python3 scripts/setup.py --verify を実行して、funasr-onnx が利用可能か確認します
2. サービスプロセスのログを確認します：process_log で proc_<session_id> を確認します
3. funasr-onnx をインストールできない場合は、一時的なフォールバックとして Whisper CLI を使用します（下記を参照）

Whisper CLI のフォールバック（FunASR を利用できない場合のみ）

# 提取音频（16kHz 单声道）
ffmpeg -i "/path/to/video.mp4" -vn -acodec pcm_s16le -ar 16000 -ac 1 -y "/tmp/audio.wav"

# Whisper 转录（tiny 模型最快，medium 质量更好）
/opt/homebrew/bin/whisper "/tmp/audio.wav" \
  --model tiny \
  --language Chinese \
  --output_dir /tmp/transcript \
  --output_format all

パフォーマンスの目安：19 分の音声の場合、tiny モデルでは約 3～5 分です（Mac CPU）。

トラブルシューティング

cv2 / opencv 导入失败

症状：POST /transcribe 返回 {"detail":"No module named 'cv2'"}，但 pip show opencv-python-headless 显示已安装。

根因：服务进程使用的 Python 环境与 pip 安装目标不同。常见于 macOS Homebrew Python 3.14 环境，pip 安装到了系统 site-packages，但服务进程加载的是 Homebrew 路径。

排查步骤：

1. 在终端验证 cv2 是否可导入：python3 -c "import cv2; print('ok')"
2. 如果导入失败，执行：python3 -m pip install opencv-python-headless --break-system-packages
3. 确认服务进程的 Python 路径：lsof -p <server_pid> | grep python

正确启动流程：

# 确认 cv2 可用后再启动服务
python3 -c "import cv2; print('cv2 ok')"

# 如服务已在运行，先杀掉再重启
lsof -ti:8765 | xargs kill -9 2>/dev/null; sleep 1

# 重启服务
python3 scripts/server.py --idle-timeout 600 &

服务端口被占用

症状：Address already in use（Errno 48）

# 杀掉占用端口的进程
lsof -ti:8765 | xargs kill -9 2>/dev/null
sleep 1

FunASR 服务无响应 / 模型加载慢

首次转录需要下载模型（约 1-2GB），耐心等待。后续请求模型已缓存，速度会快很多。

视频截图功能：

视频文件（mp4、mov、avi、mkv、wmv、webm）转录时会自动启用关键帧提取。 依赖 scenedetect[opencv] 和 imagehash 已包含在 requirements.txt 中，setup.py 安装时会一并安装。 如未安装这些依赖，服务端会输出提示但不影响普通转录功能。

服务启动失败时，运行验证命令检查安装状态：

python3 scripts/setup.py --verify

重新下载模型：

python3 scripts/setup.py --skip-deps