用途
media-transcriber 是一个用于视频/音频转写与摘要的技能。它使用本地 OpenAI Whisper 对视频或音频文件进行文字转写，并输出两个文件：全文 md 和摘要 md。适用于“把视频转写出来”“总结这段音频”“整理会议录像”“转写 mp4 并摘要”“根据访谈音频制作会议纪要”等请求。
主要能力
- 支持扩展名：mp3 / m4a / wav / ogg / flac / mp4 / mov / mkv / webm / avi 等。由于 whisper 内部调用 ffmpeg，视频可直接传入。
- 转写结果带时间戳，输出全文 md。
- 在全文基础上由 Claude 自身生成摘要 md，默认采用指定模板（概要、关键点、按主题总结、后续行动）。
- 支持多种分段粒度：按词、按 N 秒、按句、Whisper 自然分割。
- 支持模型选择、语言指定、输出格式（md / json）。
- 可通过 .env 配置输出目录。
使用方式
执行步骤：
- 确定用户指定的文件路径（拖拽时用引号包裹）。
- 用以下命令执行转写：
基本（推荐默认：turbo = large-v3-turbo + Whisper 自然分割）：
python .claude/skills/media-transcriber/scripts/transcribe.py "输入文件" --language ja
最高精度（专有名词多的会议纪要、重要项目）：
python .claude/skills/media-transcriber/scripts/transcribe.py "输入文件" --model large-v3 --language ja
轻量高速（草稿用途）：
python .claude/skills/media-transcriber/scripts/transcribe.py "输入文件" --model base --language ja
每 N 秒强制分段（约每 5 秒拾取）：
python .claude/skills/media-transcriber/scripts/transcribe.py "输入文件" --language ja --segment-seconds 5
按句（句子）单位分段（标点检测 + 最大 60 秒 cap）：
python .claude/skills/media-transcriber/scripts/transcribe.py "输入文件" --language ja --sentence
按词（用于发言时间分析，行数会大量增加，注意）：
python .claude/skills/media-transcriber/scripts/transcribe.py "输入文件" --language ja --word-level
- 用 Read 读取输出的全文 md（<项目根目录>/YYYYMMDD_HHMMSS_{basename}.md）。
- 基于全文内容，由 Claude 自身用 Write 创建摘要 md。文件名为 YYYYMMDD_HHMMSS_{basename}_summary.md（与全文 md 相同时间戳、相同目录）。摘要结构默认采用下方“摘要 md 模板”，如有用户指示则遵循。
- 向用户报告全文 md 和摘要 md 两个路径。
参数
| 参数 | 说明 | 默认 |
|---|---|---|
| file | 输入音频/视频文件路径（必填） | — |
| --model | whisper 模型名 (tiny / base / small / medium / large-v3 / turbo) | turbo |
| --language | 语言代码（例：ja, en）。未指定时自动检测 | auto-detect |
| --output-format | 输出格式 (md / json) | md |
| --segment-seconds | 每 N 秒分行 | 未指定 |
| --sentence | 按句（句子）单位分段。标点检测 + 上限秒 cap 重新分块 | false |
| --word-level | 每个词输出一行。最优先 | false |
| --sentence-max-seconds | --sentence 时的回退上限秒。在无标点音频中防止单句过长而强制 flush | 60.0 |
分段粒度优先级（从上到下更强）：--word-level > --segment-seconds > --sentence > Whisper 自然分割（默认）。
配置
在项目根目录的 .env 中设置以下环境变量（可选。未设置时输出到项目根目录下）：
# 例：想输出到 transcripts/ 下时
TRANSCRIPT_OUTPUT_PATH=transcripts
| 变量名 | 说明 |
|---|---|
| TRANSCRIPT_OUTPUT_PATH | 输出目录（默认：. = 项目根目录下） |
输出
全文 md 示例：
# 文字起こし: meeting_20260421.mp4
- 元ファイル: /path/to/meeting_20260421.mp4
- モデル: medium
- 言語: ja (auto-detected)
- 実行日時: 2026-04-21 14:30:00
- 総尺: 00:45:12
## 全文
[00:00:00] 今日は四半期の振り返りから始めましょう。
[00:00:12] まず売上の件ですが、前年同月比で...
文件名：YYYYMMDD_HHMMSS_{basename}.md（basename 为输入文件去掉扩展名后的名称） 保存位置：项目根目录下（默认）。可用 .env 的 TRANSCRIPT_OUTPUT_PATH 覆盖。
摘要 md 模板（Claude 以此模板为默认骨架写出）：
# 要約: meeting_20260421.mp4
- 元ファイル: /path/to/meeting_20260421.mp4
- 総尺: 00:45:12
- 文字起こし: 20260421_143000_meeting_20260421.md
## 概要
3〜5行で全体像
## キーポイント
- 箇条書き5〜8個
## トピック別まとめ
### トピック1
...
## 次のアクション
- 担当 / 期限 / 内容
文件名：YYYYMMDD_HHMMSS_{basename}_summary.md（与全文 md 相同时间戳） 保存位置：与全文 md 相同目录。
摘要注意事项：以作为客户会议记录/会议纪要使用为前提，采用以下语气：
- 不使用“全滅”“即停止”“劣後”“死蔵”“失敗”等负面断定词。
- 以数值陈述事实可以。不对事实使用否定对方的评价表达。
- 如用户给出其他语气指示，优先遵循。
模型选择参考
| 模型 | 大小 | 速度 | 日语精度 | 用途 |
|---|---|---|---|---|
| tiny | ~75MB | 超高速 | 低 | 草稿、英语短音频 |
| base | ~150MB | 高速 | 中下 | 英语短音频、速度优先 |
| small | ~500MB | 中速 | 中 | 简单日语 |
| medium | ~1.5GB | 稍慢 | 高 | 旧经典（可被 turbo 替代） |
| turbo | ~1.5GB | 高速 | 高（相当于 v2） | 推荐默认（日语、通用） |
| large-v3 | ~3GB | 慢 | 最高 | 专有名词较多、重要会议纪要 |
2025 年实测比较中，日语用途下 turbo (large-v3-turbo) 在 speed/accuracy 平衡上最优。medium 与 turbo 内存、速度相当而精度相当或更高，因此通常首选 turbo。仅在需要最高精度时使用 large-v3。
首次执行时模型会下载到 ~/.cache/whisper/（仅一次）。turbo 约 1.5GB。
依赖包确认
首次报错时用以下命令安装：
pip install -U openai-whisper python-dotenv
需要另外安装 ffmpeg（whisper 内部调用）：
brew install ffmpeg
适用场景
- 会议录像、访谈音频的转写与纪要制作。
- 视频内容的文字化与摘要。
- 需要带时间戳文字稿的场合。
- 需要按词、按秒、按句等不同粒度分析发言的场合。
限制
- 依赖本地 OpenAI Whisper 与 ffmpeg，首次运行需下载模型。
- 摘要由 Claude 自身生成，非独立模型。
- 关于收费、价格、平台支持等未在资料中提供。