Audio To Subtitle

gsd:workflow gsd:meta audio-to-subtitle video-processing python3, mlx-whisper, ffmpeg, AskUserQuestion 环境依赖检查通过 音频文件存在且格式支持 用户明确选择转录引擎 用户确认输出格式 引擎选择不可默认、不可跳过，必须等用户明确选择 禁止自动回退：当用户选择的引擎失败时，必须通过 AskUserQuestion 让用户决定下一步，绝对不能自作主张切换引擎 云端 API 密钥不得硬编码，必须通过环境变量或配置文件读取 长音频（>30min）必须提醒用户分段处理以避免内存压力 MacBook Air 无风扇，批量任务建议串行处理避免过热降频

gsd:goal将用户指定的音频文件转录为目标格式的字幕文件，输出到指定目录。

<gsd:phase name="precheck" order="1"> gsd:step并行检查 Python3、mlx-whisper、ffmpeg 是否已安装 gsd:step检查引擎配置状态： - 本地引擎：验证 MLX-Whisper 模型是否可用（尝试加载默认模型） - 豆包引擎：检查 API 凭证是否存在（~/.audio2subtitle/config.json 或环境变量） gsd:step确认输入音频/视频文件路径和格式（注意文件名中的特殊字符如 #） gsd:step获取文件时长信息，如 >30min 则提醒用户 gsd:checkpoint环境依赖就绪，引擎配置验证通过，音频文件可访问

<gsd:phase name="config" order="2">

<!-- Step 1: 引擎选择（独立的交互步骤） -->
<gsd:step>
  📝 【Step 1/3：选择引擎 — 必须单独执行，不可合并】

  使用 AskUserQuestion 让用户选择转录引擎：
  - local：本地 MLX-Whisper（免费、快速、隐私保护，Apple Silicon 优化）
  - doubao：豆包云端 ASR（中文优化、大模型增强，适合高难度音频）

  规则：
  - 此步骤不可跳过、不可默认选择
  - 必须等待用户明确选择后才进入下一步
  - 禁止在这一步同时询问模型、格式等其他问题
</gsd:step>

<!-- Step 2: 引擎相关配置（分支逻辑） -->
<gsd:step>
  🔄 【Step 2/3：引擎相关配置 — 根据选择分支处理】

  【分支 A - 用户选择 local】：
    1. 使用 AskUserQuestion 选择 Whisper 模型：
       - large-v3-turbo（推荐，最快，准确率很高）
       - large-v3（最佳准确率，稍慢）
       - medium（轻量任务）
    2. 继续进入 Step 3

  【分支 B - 用户选择 doubao】：
    1. 检查豆包 API 凭证（~/.audio2subtitle/config.json 或环境变量 DOUBAO_APP_ID / DOUBAO_ACCESS_TOKEN）
    2. 如果凭证缺失 → 🛑 Human-Action 检查点：引导用户配置凭证
       方式一（推荐）：运行 python3 scripts/transcribe.py --setup-doubao
       方式二：手动写入 ~/.audio2subtitle/config.json
       配置完成后验证文件写入成功
    3. 凭证就绪 → 跳过模型选择，直接进入 Step 3
</gsd:step>

<!-- Step 3: 通用配置 -->
<gsd:step>
  📝 【Step 3/3：输出格式】

  使用 AskUserQuestion 选择输出格式：
  - MD（推荐，带时间轴，适合笔记整理）
  - SRT（通用字幕格式）
  - VTT（Web 字幕格式）
  - TXT（纯文本，无时间戳）
</gsd:step>

<gsd:step>确认输出目录（默认与音频同目录）</gsd:step>

<gsd:checkpoint>用户已确认所有转录参数</gsd:checkpoint>

<gsd:phase name="transcribe" order="3"> gsd:step展示参数确认表（引擎 / 模型 / 格式 / 输出目录 / 时长） gsd:step执行转录脚本（加 --yolo 跳过脚本内交互，因为 Claude 侧已完成交互确认）

<!-- 错误处理：豆包 API 失败 -->
<gsd:step>
  🛑 【豆包 API 失败时 — Decision 检查点，禁止自动回退】

  当豆包引擎转录失败（DoubaoApiError）时，按以下流程处理：

  1. ✅ 展示诊断报告（脚本已输出到 stderr）
  2. ✅ 解释错误原因：
     - 凭证未配置 → 说明需要获取 APP ID 和 Access Token
     - 认证失败 → 提示检查凭证是否正确
     - resource not granted → 说明火山引擎账号未开通对应服务，提供控制台链接：
       https://console.volcengine.com/speech/service/subscription
  3. 🔄 使用 AskUserQuestion 让用户选择下一步（Decision 检查点）：
     - 选项 A：去开通服务，修复豆包配置后重试
     - 选项 B：改用本地 MLX-Whisper 引擎转录
     - 选项 C：取消本次操作
  4. 根据用户选择执行（不是自动决定）

  绝对禁止的行为：
  - ❌ 未经用户同意自动回退到另一个引擎
  - ❌ 在用户不知情的情况下切换引擎
  - ❌ 假设用户想用本地引擎"先完成再说"
</gsd:step>

<gsd:step>处理完成后验证输出文件完整性</gsd:step>
<gsd:checkpoint>转录完成，字幕文件已生成</gsd:checkpoint>

<gsd:phase name="deliver" order="4"> gsd:step报告输出文件路径、大小和段落数 gsd:step展示字幕前几行预览 gsd:step如质量不佳，建议切换引擎或模型重新转录

Audio to Subtitle - 音频转字幕工具

基于 Apple Silicon MLX 框架的高性能音频转字幕工具，支持本地和云端混合转录。

⚠️ 用户交互点总结

LLM 执行提示：

• 🛑 → 必须等待用户完成操作（如配置 API 凭证），不能跳过
• 📝 → 需要用户输入，使用 AskUserQuestion
• ✅ → 自动验证后报告结果，不需要用户操作
• 🔄 → 需要用户选择，提供选项，不能自动决定

核心架构

音频文件 → ffmpeg 预处理 → MLX-Whisper / 豆包 ASR → 格式化 → SRT/VTT/TXT/MD
                                                          ↕
                                                自动分段（长音频）

环境要求

首次安装

# 优先使用 Agent 当前加载到的 Skill 目录；也可显式设置该变量。
AUDIO_TO_SUBTITLE_SKILL_DIR="${AUDIO_TO_SUBTITLE_SKILL_DIR:-}"
if [ -z "$AUDIO_TO_SUBTITLE_SKILL_DIR" ]; then
  for candidate in \
    "$HOME/.j-skills/linked/audio-to-subtitle" \
    "$HOME/.claude/skills/audio-to-subtitle" \
    "$HOME/.codex/skills/audio-to-subtitle" \
    "$HOME/.agents/skills/audio-to-subtitle"; do
    if [ -f "$candidate/scripts/setup.sh" ]; then
      AUDIO_TO_SUBTITLE_SKILL_DIR="$candidate"
      break
    fi
  done
fi

[ -n "$AUDIO_TO_SUBTITLE_SKILL_DIR" ] || {
  echo "未找到 audio-to-subtitle；请设置 AUDIO_TO_SUBTITLE_SKILL_DIR" >&2
  exit 1
}
bash "$AUDIO_TO_SUBTITLE_SKILL_DIR/scripts/setup.sh"

或手动安装：

pip install mlx-whisper
brew install ffmpeg

支持格式

输入

输出

转录引擎

本地引擎：MLX-Whisper

Apple Silicon 优势：24GB 统一内存直接当显存用，无需 GPU 数据拷贝，比原版 Whisper 快 4-70 倍。

云端引擎：豆包（可选）

必须开通以下服务才能使用豆包引擎

必须开通的服务

在火山引擎控制台开通：https://console.volcengine.com/speech/service/subscription

新用户有免费额度。支持最长 2 小时音频。

⚠️ 注意：开通「大模型语音识别」后，需要在「应用管理」中将应用绑定到该服务。 应用管理页面：https://console.volcengine.com/speech/app

不需要开通的服务（脚本已不再使用）

豆包 API 注册指南

1. 访问 https://www.volcengine.com 注册并实名认证
2. 进入 https://console.volcengine.com/speech/service/subscription
3. 开通「豆包大模型语音识别 - 录音文件识别（模型 2.0）」服务 ← 这是必须的
4. 进入 https://console.volcengine.com/speech/app 创建应用，获取 APP ID 和 Access Token
5. 确保应用已绑定到开通的服务
6. 配置凭证（三选一）：
   • 运行 python3 scripts/transcribe.py --setup-doubao 交互式输入
   • 写入 ~/.audio2subtitle/config.json
   • 设置环境变量 DOUBAO_APP_ID + DOUBAO_ACCESS_TOKEN

使用方式

交互模式（推荐）

# 直接运行，会先确认参数再执行
python3 scripts/transcribe.py audio.mp3

YOLO 模式（跳过交互）

# 跳过交互，默认使用本地引擎 local
python3 scripts/transcribe.py audio.mp3 --yolo

单文件转录

python3 scripts/transcribe.py audio.mp3 -f vtt
python3 scripts/transcribe.py audio.mp3 -m large-v3
python3 scripts/transcribe.py audio.mp3 -o ~/Desktop/subtitles/
python3 scripts/transcribe.py audio.mp3 --engine doubao
python3 scripts/transcribe.py audio.mp3 -l zh

命令选项

MacBook Air 特别注意事项

1. 散热：无风扇设计，长时间满载会降频，批量任务建议串行处理
2. 内存：24GB 足够运行 large-v3 模型（4-bit 量化后仅需 ~4GB）
3. 长音频：>30 分钟建议分段处理（脚本内置自动分段 15 分钟/段）

性能参考（MacBook Air M2 24GB）