yichen-volc-asr

火山 ASR 转写 + 口播自动粗剪

这个 skill 同时负责两类任务：

• 纯转写：把本地音视频识别成文字、时间戳和字幕。
• 口播粗剪：基于 ASR 时间戳删重复、停顿、口误和废句，生成可进剪映精修的粗剪 MP4 和 SRT。

安全规则

1. 原片不动。先复制一个工作副本，再对工作副本转写、复转写或剪辑。
2. 不要直接删除任何文件。临时文件清理必须得到用户明确允许，并且只能先放到垃圾篓。
3. 原片、工作副本、粗剪成片、复转写临时文件必须分开保存。
4. 不要把 TOS、ASR Token、Cookie、API Key 写入 skill、普通记忆或日志；只从环境变量或用户指定的私有配置读取。
5. ASR 扣费顺序固定为：先用火山控制台中仍有试用/时长包的豆包语音应用；试用/时长包确认用完后，才允许切到付费应用。试用和付费 AppID 都必须从环境变量读取，不在公开 skill 里硬编码。
6. 试用和付费 token 必须分开：试用应用使用 VOLC_ASR_TRIAL_TOKEN，付费应用使用 VOLC_ASR_PAID_TOKEN 或旧的 VOLC_ASR_TOKEN。在试用包未用完前，不要用付费 token 冒充默认 token。
7. 在试用/时长包未确认用完前，不得设置 VOLC_ASR_TRIAL_EXHAUSTED=1，也不得让 VOLC_ASR_APP_ID 指向付费应用；如确实要临时绕过，必须明确说明会扣费并获得用户确认。
8. 长音频 ASR 提交成功后，不要重复跑同一文件来“再试一次”。优先等当前任务完成，或用已保存的 {工作副本}.asr_pending.json / --request-id 恢复查询，避免重复消耗试用时长或余额。

使用方法

# 基础用法：转写 + 分析 + 自动剪辑
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任务记录，可用于恢复查询，不能当作完成结果

纯转写流程

1. 确认输入文件存在、大小正常；必要时用 ffprobe 看时长和编码。
2. 复制原片为工作副本，例如 source_for_asr.mp4。
3. 运行 python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --no-execute。
4. 交付转写稿、时间戳、字幕草稿和缓存路径。
5. 明确说明本次没有做剪辑。

口播自动粗剪流程

当用户要“帮我剪口播”“自动粗剪”“删重复/停顿/口误/断句”时：

1. 复制原片为工作副本，避免原片被改动。
2. 用火山 ASR 生成带时间戳的转写稿和 .asr_cache.json。
3. 写一份可读删留方案：
   • KEEP：干净、有信息量、叙事必要的内容。
   • DELETE：口误、重复、长停顿、废句、半句话、无效语气词。
   • CHECK：内容可能有用，但啰嗦或听感不确定。
4. 用源片时间码生成删除区间或保留区间。
5. 生成粗剪 MP4。长口播、多段删减时优先使用稳定的分段提取 + concat 流程。
6. 对粗剪 MP4 做复转写审核。
7. 通过审核后，输出粗剪 MP4、SRT、转写稿、删留方案和复查说明。
8. 如需继续精修，将粗剪 MP4 和 SRT 作为交付素材，供后续导入剪映/CapCut。

剪辑规则

#	规则	说明
1	停顿删除	相邻片段时间缺口较长的静音可删除
2	纯语气词删除	整段仅为嗯、啊、呃、哦等语气词时删除
3	相邻重复删除	优先删前保后，灰色地带人工判断
4	句中语气词保留	语气词在句子中间时整段保留
5	连续前缀词清理	然后、所以、其实、就是说等连续开头时清理冗余
6	短片段谨慎处理	非纯语气词短片段默认保留
7	智能 margin	保留片段前后加缓冲，避免吞字
8	Smoothing	过短保留片段合并到相邻片段，避免闪帧

三层审核

每一层都检查：

• 有没有字、短语、句子或段落级重复。
• 有没有把完整句子剪断。
• 有没有残留口误、废句、半句话、只有开头没有结尾的片段。
• 有没有明显停顿、空白或节奏断裂。
• 有没有误删承接句，导致逻辑突然跳跃。
• 段落结构是否仍然顺。

第一层：剪前删留方案

删除区间必须对应重复、口误、废句、明显停顿或不可用残句；边界不能切进完整句子中间，除非后面有更干净的完整版本。

第二层：粗剪成片复转写

粗剪渲染后，对粗剪 MP4 重新转写。成片转写里不能有明显重复、残句、长停顿、逻辑跳跃或硬切造成的句子不完整。

第三层：最终通过

最新版粗剪必须通过一次完整审核后，才能说“可以进入剪映精修”。如果没通过，继续出新版本。

建议用一条人工确认过的粗剪成片作为质量标尺。以后口播粗剪以这个标准为基准：没有重复片段、没有明显停顿、没有把完整句子剪断。

最终回复要求

• 纯转写：给出转写稿路径、字幕路径、缓存路径，并说明没有做剪辑。
• 口播粗剪：给出粗剪 MP4 路径、SRT 路径、转写稿路径、删留方案路径、复查结论。
• 如果失败，说明缺少的环境变量、文件不存在、上传失败、ASR 失败或 ffmpeg 报错。