doubao-multimodal-skill

一个基于火山方舟 Doubao-Seed 多模态接口的 Claude Code Skill，封装了音视频理解的常见任务：ASR、说话人日志、字幕打轴、AST 翻译、视频时间轴、技术博客关键帧选取等。

底层是一个独立可用的 Bun + TypeScript CLI（skill/scripts/main.ts），既可以作为 Claude Code Skill 让 Agent 直接调用，也能脱离 Claude 单独命令行运行。

功能一览

--task	说明	视频自动转音频
asr	纯文字转写（无标点格式约束）	✅
asr-timestamp	每字带 开始-结束-字符; 模板	✅
multispeaker-asr	[spk0]...[spk1]... 输出	✅
ast	语音翻译，配合 --target-language	✅
diarize	说话人日志：[spk][start-end]文本	✅
subtitle-align	已知字幕做字符级打轴	✅
caption	音频/视频整体分析（markdown 报告）	❌ 视频时保留画面
video-timeline	视频时间轴 JSON：start_end_time/event/people/emotion（仅视频）	❌ 视频时保留画面
keyframe-extract	技术博客配图关键帧 JSON（仅视频，可选 transcript）	❌ 视频时保留画面
understand	自定义 prompt 的通用理解	❌ 视频时保留画面

特性：

• 本地/远程都能跑：远程 URL 自动下载到缓存，本地文件自动上传到火山 TOS 拿预签名 URL 给 Ark。
• 大文件自动切片：视频 > 20 min 或 > 50 MB、音频 > 120 min 或 > 50 MB，自动 ffmpeg 切段，多段并发请求 Ark，按时间顺序合并。
• Token 用量回写：每段保留 usage / log_id / response_id，方便对账和向火山技术支持报问题。

安装

需要 Bun（≥ 1.1）和本机的 ffmpeg / ffprobe。

# 克隆仓库
git clone https://github.com/JimLiu/doubao-multimodal-skill.git
cd doubao-multimodal-skill

# 安装依赖
cd skill/scripts
bun install

ffmpeg 缺失时 CLI 启动会停下来给出对应平台的安装命令（Homebrew / apt / dnf / pacman），回 y 即可，或者加 --yes 跳过确认。

配置

复制示例文件，填上你的火山方舟和 TOS 凭证：

cp .env.example .env

最少需要：

ARK_API_KEY=...           # 火山方舟 API Key
ARK_MODEL=...             # endpoint id 或 model 名，例如 doubao-seed-2-0-lite-260428 或 doubao-seed-1-6-flash-250928

只要会用到本地音视频文件作为输入，就还需要 TOS 凭证：

TOS_ACCESS_KEY_ID=...
TOS_ACCESS_KEY_SECRET=...
TOS_BUCKET=...
TOS_REGION=cn-beijing

完整环境变量见 .env.example。

部分 Doubao-Seed endpoint 仅支持 input_audio 字段（不接受 audio_url）。命中 400 invalid value: audio_url 时，加 --audio-part-type input_audio。

作为 CLI 使用

# 远程音频做纯文字 ASR
bun run skill/scripts/main.ts \
  --task asr \
  --url "https://example.com/clip.wav" --type audio \
  --audio-part-type input_audio \
  --out-dir ./out/asr

# 本地视频 → 自动抽音频 → 多说话人 ASR
bun run skill/scripts/main.ts \
  --task multispeaker-asr \
  --path "/abs/path/to/meeting.mp4" \
  --audio-part-type input_audio \
  --out-dir ./out/meeting

# 视频时间轴 JSON
bun run skill/scripts/main.ts \
  --task video-timeline \
  --url "https://ark-public.tos-cn-beijing.volces.com/carcrash.mp4" --type video \
  --out-dir ./out/timeline

# 技术博客配图关键帧（带 transcript 提升准确度）
bun run skill/scripts/main.ts \
  --task keyframe-extract \
  --path ./talk.mp4 \
  --transcript-file ./talk.transcript.txt \
  --out-dir ./out/keyframes

# 任意自定义 prompt 的理解
bun run skill/scripts/main.ts \
  --task understand \
  --path "/abs/path/to/replay.mp4" \
  --prompt "你是 CS2 教练，先描述这一回合的关键事件，再点评经济与道具使用。" \
  --out-dir ./out/cs2-replay

输出目录结构：

out-dir/
  <task>.json         # 完整结构：每段 start/end/text + log_id/response_id/usage + usage_total + merged
  <task>.txt          # 仅 merged 文本，便于直接消费
  cache/
    downloads/        # 远程 URL 下载缓存
    audio/            # ffmpeg 抽出的音频（仅 ASR-only 视频任务）
    segments/         # 切片后的音/视频片段

<task>.json 关键字段：

• usage_total.{prompt_tokens,completion_tokens,total_tokens,audio_tokens,cached_tokens,reasoning_tokens} — 所有片段累加，便于成本核算
• segments[i].usage — 单段同上字段
• segments[i].log_id — 来自响应头 x-tt-logid，向火山技术支持报问题时必备
• segments[i].response_id / response_model — 响应体 id 和实际命中的底层模型名

作为 Claude Code Skill 使用

把整个 skill/ 目录链接或复制到 Claude Code 的 skills 目录：

# 软链（推荐，方便后续 git pull 同步）
ln -s "$PWD/skill" ~/.claude/skills/doubao-multimodal

# 或者直接复制
cp -r skill ~/.claude/skills/doubao-multimodal

确认 ~/.claude/skills/doubao-multimodal/SKILL.md 存在后，重启 Claude Code，让模型在你提到「转写这个视频」「给这段访谈做说话人日志」「帮我从这个 talk 里挑配图」等需求时自动召唤这个 skill。

环境变量推荐在 shell 里 export，或者放在 ~/.claude/skills/doubao-multimodal/.env，由 Claude 调起时直接继承。

任务模板与 Prompt

每个 task 的 system / user prompt、示例输出、解析片段都拆成独立 reference 文件，按需查阅：

文件	Task
skill/references/asr.md	纯文字 ASR
skill/references/asr-timestamp.md	字符级时间戳 ASR
skill/references/multispeaker-asr.md	多说话人 ASR
skill/references/ast.md	语音翻译
skill/references/diarize.md	说话人日志
skill/references/subtitle-align.md	字幕打轴
skill/references/caption.md	音/视频整体分析
skill/references/video-timeline.md	视频时间轴 JSON
skill/references/keyframe-extract.md	博客配图关键帧 JSON
skill/references/understand.md	通用理解

完整工作流和切片规则见 skill/SKILL.md。

切片规则速查

类型	切片阈值	单段限制
视频	> 20 min 或 > 50 MB	≤ 20 min, ≤ 50 MB
音频	> 120 min 或 > 50 MB	≤ 120 min, ≤ 50 MB

视频默认下采样到 720p（不上采样），H.264 veryfast + CRF 28 + maxrate 1500 kbps + AAC 96 kbps；编码后单段仍 > 50 MB 会按时间二分继续切，递归到 30 s 兜底。音频统一转 mp3 16k mono @ 48 kbps。

多段按 --concurrency（默认 3）并发请求 Ark，结果按时间顺序拼接 === Part N (start-end) ===，并把 Segment.index 拍平后从 0 重排。

常见坑

• 远程 URL 带签名时，确保过期时间 ≥ Ark 调用预计耗时；CLI 会重新下载到本地，原 URL 过期不影响 Ark 调用。
• TOS 凭证错误最常见：SignatureDoesNotMatch 大概率是 TOS_ACCESS_KEY_SECRET 多/少粘了字符。
• understand + 视频时如果你只关心音频，请改用对应 ASR/diarize 任务，否则会浪费 video token。
• 长程任务（> 2h）建议结合 chunked-summary 工作流，不要把所有 part 直接喂给后续模型。

License

MIT