doubao-multimodal-skill

KO | EN

gitlite — search

#javascript #hacktoberfest #react #golang #rust #deep-learning #linux #nodejs #windows #awesome #awesome-list #security #ios #open-source

doubao-multimodal-skill

(★ 31)

Claude Code Skill + Bun CLI for Doubao-Seed multimodal understanding (ASR, diarization, subtitle align, AST, video timeline, keyframe extraction)

doubao-multimodal-skill 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# doubao-multimodal-skill

一个基于火山方舟 [Doubao-Seed](https://www.volcengine.com/docs/82379) 多模态接口的 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](https://bun.com/)（≥ 1.1）和本机的 `ffmpeg` / `ffprobe`。

```bash
# 克隆仓库
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 凭证：

```bash
cp .env.example .env
```

最少需要：

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

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

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

完整环境变量见 [`.env.example`](.env.example)。

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

## 作为 CLI 使用

```bash
# 远程音频做纯文字 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
```

输出目录结构：

```text
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 目录：

```bash
# 软链（推荐，方便后续 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`](skill/references/asr.md) | 纯文字 ASR |
| [`skill/references/asr-timestamp.md`](skill/references/asr-timestamp.md) | 字符级时间戳 ASR |
| [`skill/references/multispeaker-asr.md`](skill/references/multispeaker-asr.md) | 多说话人 ASR |
| [`skill/references/ast.md`](skill/references/ast.md) | 语音翻译 |
| [`skill/references/diarize.md`](skill/references/diarize.md) | 说话人日志 |
| [`skill/references/subtitle-align.md`](skill/references/subtitle-align.md) | 字幕打轴 |
| [`skill/references/caption.md`](skill/references/caption.md) | 音/视频整体分析 |
| [`skill/references/video-timeline.md`](skill/references/video-timeline.md) | 视频时间轴 JSON |
| [`skill/references/keyframe-extract.md`](skill/references/keyframe-extract.md) | 博客配图关键帧 JSON |
| [`skill/references/understand.md`](skill/references/understand.md) | 通用理解 |

完整工作流和切片规则见 [`skill/SKILL.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](LICENSE)

doubao-multimodal-skill

doubao-multimodal-skill 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

doubao-multimodal-skill

doubao-multimodal-skill 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README