火山 ASR 转写 + 口播自动粗剪
这个 skill 同时负责两类任务：
- 纯转写：把本地音视频识别成文字、时间戳和字幕。
- 口播粗剪：基于 ASR 时间戳删重复、停顿、口误和废句，生成可进剪映精修的粗剪 MP4 和 SRT。
安全规则
- 原片不动。先复制一个工作副本，再对工作副本转写、复转写或剪辑。
- 不要直接删除任何文件。临时文件清理必须得到用户明确允许，并且只能先放到垃圾篓。
- 原片、工作副本、粗剪成片、复转写临时文件必须分开保存。
- 不要把 TOS、ASR Token、Cookie、API Key 写入 skill、普通记忆或日志；只从环境变量或用户指定的私有配置读取。
- ASR 扣费顺序固定为：先用火山控制台中仍有试用/时长包的豆包语音应用；试用/时长包确认用完后，才允许切到付费应用。试用和付费 AppID 都必须从环境变量读取，不在公开 skill 里硬编码。
- 试用和付费 token 必须分开：试用应用使用
VOLC_ASR_TRIAL_TOKEN，付费应用使用VOLC_ASR_PAID_TOKEN或旧的VOLC_ASR_TOKEN。在试用包未用完前，不要用付费 token 冒充默认 token。 - 在试用/时长包未确认用完前，不得设置
VOLC_ASR_TRIAL_EXHAUSTED=1，也不得让VOLC_ASR_APP_ID指向付费应用；如确实要临时绕过，必须明确说明会扣费并获得用户确认。 - 长音频 ASR 提交成功后，不要重复跑同一文件来“再试一次”。优先等当前任务完成，或用已保存的
{工作副本}.asr_pending.json/--request-id恢复查询，避免重复消耗试用时长或余额。
使用方法
bash# 基础用法：转写 + 分析 + 自动剪辑 python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' # 只看标注不执行剪辑 python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --dry-run # 忽略 ASR 缓存，重新识别 python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --no-cache # 不执行 ffmpeg 剪辑，仍生成转写、标注和 SRT python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --no-execute # 只转写，不做剪辑分析或生成 SRT python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --transcribe-only # 只恢复查询已提交任务，不重新上传/提交 python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --request-id '<火山ASR request_id>' --no-execute
脚本默认使用 VOLC_ASR_TRIAL_APP_ID，并优先读取 VOLC_ASR_TRIAL_TOKEN。只有确认试用/时长包已经用完后，才设置 VOLC_ASR_TRIAL_EXHAUSTED=1，脚本才会切到 VOLC_ASR_PAID_APP_ID 并读取 VOLC_ASR_PAID_TOKEN 或旧的 VOLC_ASR_TOKEN。如确实需要切到其他火山语音应用，先设置 VOLC_ASR_APP_ID；若该应用不是试用包应用且未标记试用已用完，脚本会停止，除非同时显式设置 VOLC_ASR_ALLOW_NON_TRIAL_APP=1。
如果本机旧环境里只有 VOLC_ASR_TOKEN，脚本不会默认把它用于试用应用，避免 token 属于付费应用却误以为在走试用。只有确认 VOLC_ASR_TOKEN 本身就是试用 token 时，才可临时设置 VOLC_ASR_ALLOW_LEGACY_TOKEN=1 兼容旧配置。
脚本会在提交成功后写入 {工作副本}.asr_pending.json，只保存 request_id、AppID、音频 URL 和状态，不保存 token/密钥。复跑时如果没有完成缓存，会优先恢复这个未完成任务；只有明确传 --force-new 才会重新上传并提交新任务。
输出文件
| 文件 | 说明 |
|---|---|
{工作副本}_cut.mp4 | 粗剪后的视频，可导入剪映 |
{工作副本}_cut.srt | 字幕文件，剪映可导入 |
{工作副本}.txt | 完整转写文字和时间戳 |
{工作副本}.asr_cache.json | ASR 缓存，复跑可复用 |
{工作副本}.asr_pending.json | 未完成ASR任务记录，可用于恢复查询，不能当作完成结果 |
纯转写流程
- 确认输入文件存在、大小正常；必要时用
ffprobe看时长和编码。 - 复制原片为工作副本，例如
source_for_asr.mp4。 - 运行
python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --no-execute。 - 交付转写稿、时间戳、字幕草稿和缓存路径。
- 明确说明本次没有做剪辑。
口播自动粗剪流程
当用户要“帮我剪口播”“自动粗剪”“删重复/停顿/口误/断句”时：
- 复制原片为工作副本，避免原片被改动。
- 用火山 ASR 生成带时间戳的转写稿和
.asr_cache.json。 - 写一份可读删留方案：
KEEP：干净、有信息量、叙事必要的内容。DELETE：口误、重复、长停顿、废句、半句话、无效语气词。CHECK：内容可能有用，但啰嗦或听感不确定。
- 用源片时间码生成删除区间或保留区间。
- 生成粗剪 MP4。长口播、多段删减时优先使用稳定的分段提取 + concat 流程。
- 对粗剪 MP4 做复转写审核。
- 通过审核后，输出粗剪 MP4、SRT、转写稿、删留方案和复查说明。
- 如需继续精修，将粗剪 MP4 和 SRT 作为交付素材，供后续导入剪映/CapCut。
剪辑规则
| # | 规则 | 说明 |
|---|---|---|
| 1 | 停顿删除 | 相邻片段时间缺口较长的静音可删除 |
| 2 | 纯语气词删除 | 整段仅为嗯、啊、呃、哦等语气词时删除 |
| 3 | 相邻重复删除 | 优先删前保后，灰色地带人工判断 |
| 4 | 句中语气词保留 | 语气词在句子中间时整段保留 |
| 5 | 连续前缀词清理 | 然后、所以、其实、就是说等连续开头时清理冗余 |
| 6 | 短片段谨慎处理 | 非纯语气词短片段默认保留 |
| 7 | 智能 margin | 保留片段前后加缓冲，避免吞字 |
| 8 | Smoothing | 过短保留片段合并到相邻片段，避免闪帧 |
三层审核
每一层都检查：
- 有没有字、短语、句子或段落级重复。
- 有没有把完整句子剪断。
- 有没有残留口误、废句、半句话、只有开头没有结尾的片段。
- 有没有明显停顿、空白或节奏断裂。
- 有没有误删承接句，导致逻辑突然跳跃。
- 段落结构是否仍然顺。
第一层：剪前删留方案
删除区间必须对应重复、口误、废句、明显停顿或不可用残句；边界不能切进完整句子中间，除非后面有更干净的完整版本。
第二层：粗剪成片复转写
粗剪渲染后，对粗剪 MP4 重新转写。成片转写里不能有明显重复、残句、长停顿、逻辑跳跃或硬切造成的句子不完整。
第三层：最终通过
最新版粗剪必须通过一次完整审核后，才能说“可以进入剪映精修”。如果没通过，继续出新版本。
建议用一条人工确认过的粗剪成片作为质量标尺。以后口播粗剪以这个标准为基准：没有重复片段、没有明显停顿、没有把完整句子剪断。
最终回复要求
- 纯转写：给出转写稿路径、字幕路径、缓存路径，并说明没有做剪辑。
- 口播粗剪：给出粗剪 MP4 路径、SRT 路径、转写稿路径、删留方案路径、复查结论。
- 如果失败，说明缺少的环境变量、文件不存在、上传失败、ASR 失败或 ffmpeg 报错。
