yichen-volc-asr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

Volcano ASR Transcription + Talking-head Auto Rough Cut

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

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

This skill handles two types of tasks:

Pure transcription: recognize local audio/video into text, timestamps, and subtitles.
Talking-head rough cut: use ASR timestamps to remove repeats, pauses, verbal stumbles, and filler sentences, then generate a rough-cut MP4 and SRT ready for fine editing in CapCut/Jianying.

安全规则

Safety Rules

原片不动。先复制一个工作副本，再对工作副本转写、复转写或剪辑。
不要直接删除任何文件。临时文件清理必须得到用户明确允许，并且只能先放到垃圾篓。
原片、工作副本、粗剪成片、复转写临时文件必须分开保存。
不要把 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
```
恢复查询，避免重复消耗试用时长或余额。

Never modify the original media. Always copy a working copy first, then transcribe, re-transcribe, or edit the working copy.
Do not delete any files directly. Temporary file cleanup must be explicitly approved by the user, and files may only be moved to the trash first.
Original media, working copy, rough-cut output, and re-transcription temporary files must be kept separately.
Do not write TOS, ASR Token, Cookie, or API Key into the skill, normal memory, or logs; only read from environment variables or user-specified private configuration.
ASR billing order is fixed: first use the Doubao speech application that still has trial/duration package in the Volcano console; only after the trial/duration package is confirmed exhausted may you switch to a paid application. Both trial and paid AppIDs must be read from environment variables and not hardcoded in this public skill.
Trial and paid tokens must be kept separate: use
```
VOLC_ASR_TRIAL_TOKEN
```
for the trial application and
```
VOLC_ASR_PAID_TOKEN
```
or legacy
```
VOLC_ASR_TOKEN
```
for the paid application. Do not use the paid token as the default token before the trial package is exhausted.
Before the trial/duration package is confirmed exhausted, you must not set
```
VOLC_ASR_TRIAL_EXHAUSTED=1
```
nor let
```
VOLC_ASR_APP_ID
```
point to a paid application. If a temporary bypass is truly necessary, you must explicitly state that charges will apply and obtain user confirmation.
After a long-audio ASR submission succeeds, do not run the same file again to "try once more". Prefer waiting for the current task to complete, or recover the query using the saved
```
{working_copy}.asr_pending.json
```
/
```
--request-id
```
, to avoid consuming trial time or balance repeatedly.

使用方法

Usage

bash

undefined

bash

undefined

基础用法：转写 + 分析 + 自动剪辑

Basic usage: transcribe + analyze + auto edit

python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>'

python3 yichen-volc-asr/scripts/transcribe.py '<working copy path>'

只看标注不执行剪辑

Review annotations only, do not edit

python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --dry-run

python3 yichen-volc-asr/scripts/transcribe.py '<working copy path>' --dry-run

忽略 ASR 缓存，重新识别

Ignore ASR cache and re-recognize

python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --no-cache

python3 yichen-volc-asr/scripts/transcribe.py '<working copy path>' --no-cache

不执行 ffmpeg 剪辑，仍生成转写、标注和 SRT

Do not run ffmpeg editing; still generate transcription, annotations, and SRT

python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --no-execute

python3 yichen-volc-asr/scripts/transcribe.py '<working copy path>' --no-execute

只转写，不做剪辑分析或生成 SRT

Transcribe only; no edit analysis or SRT generation

python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --transcribe-only

python3 yichen-volc-asr/scripts/transcribe.py '<working copy path>' --transcribe-only

只恢复查询已提交任务，不重新上传/提交

Recover a submitted task only; no re-upload/submit

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` 才会重新上传并提交新任务。

python3 yichen-volc-asr/scripts/transcribe.py '<working copy path>' --request-id '<Volcano ASR request_id>' --no-execute


The script defaults to `VOLC_ASR_TRIAL_APP_ID` and reads `VOLC_ASR_TRIAL_TOKEN` first. Only after confirming the trial/duration package is exhausted should you set `VOLC_ASR_TRIAL_EXHAUSTED=1`; only then will the script switch to `VOLC_ASR_PAID_APP_ID` and read `VOLC_ASR_PAID_TOKEN` or legacy `VOLC_ASR_TOKEN`. If you really need to switch to another Volcano speech application, set `VOLC_ASR_APP_ID` first; if that application is not a trial-package application and the trial exhaustion flag is not set, the script will stop unless `VOLC_ASR_ALLOW_NON_TRIAL_APP=1` is also explicitly set.

If the local legacy environment only has `VOLC_ASR_TOKEN`, the script will not use it by default for the trial application, to avoid a paid token being mistakenly used as a trial. Only when you confirm `VOLC_ASR_TOKEN` is itself a trial token may you temporarily set `VOLC_ASR_ALLOW_LEGACY_TOKEN=1` for compatibility with the old configuration.

After a successful submission, the script writes `{working_copy}.asr_pending.json`, which stores only `request_id`, AppID, audio URL, and status—never tokens/secrets. When re-running without completed cache, it will first recover this unfinished task; only explicitly passing `--force-new` will re-upload and submit a new task.

输出文件

Output Files

文件	说明
`{工作副本}_cut.mp4`	粗剪后的视频，可导入剪映
`{工作副本}_cut.srt`	字幕文件，剪映可导入
`{工作副本}.txt`	完整转写文字和时间戳
`{工作副本}.asr_cache.json`	ASR 缓存，复跑可复用
`{工作副本}.asr_pending.json`	未完成ASR任务记录，可用于恢复查询，不能当作完成结果

File	Description
`{working_copy}_cut.mp4`	Rough-cut video, can be imported into CapCut/Jianying
`{working_copy}_cut.srt`	Subtitle file, importable into CapCut/Jianying
`{working_copy}.txt`	Full transcription text with timestamps
`{working_copy}.asr_cache.json`	ASR cache, reusable on re-run
`{working_copy}.asr_pending.json`	Record of an unfinished ASR task, for query recovery; not a completed result

纯转写流程

Pure Transcription Flow

确认输入文件存在、大小正常；必要时用
```
ffprobe
```
看时长和编码。
复制原片为工作副本，例如
```
source_for_asr.mp4
```
。

运行

python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --no-execute

。

交付转写稿、时间戳、字幕草稿和缓存路径。
明确说明本次没有做剪辑。

Confirm the input file exists and has a reasonable size; use
```
ffprobe
```
to check duration and codec if needed.
Copy the original to a working copy, e.g.,
```
source_for_asr.mp4
```
.

Run

python3 yichen-volc-asr/scripts/transcribe.py '<working copy path>' --no-execute

Deliver the transcription text, timestamps, subtitle draft, and cache path.
Explicitly state that no editing was performed this time.

口播自动粗剪流程

Talking-head Auto Rough Cut Flow

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

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

When the user asks to "edit my talking-head video", "rough cut automatically", or "remove repeats/pauses/verbal stumbles/choppy sentences":

Copy the original to a working copy to avoid modifying the original.
Use Volcano ASR to generate timestamped transcription and
```
.asr_cache.json
```
.
Write a readable keep/delete plan:
- ```
KEEP
```
  : clean, informative, narratively necessary content.
- ```
DELETE
```
  : verbal stumbles, repeats, long pauses, filler sentences, half sentences, ineffective interjections.
- ```
CHECK
```
  : content may be useful but wordy or questionable in listening experience.
Generate delete or keep ranges using source timecodes.
Generate the rough-cut MP4. For long talking-head videos with multiple deletions, prefer a stable segment-extract + concat workflow.
Re-transcribe the rough-cut MP4 for review.
After review passes, output the rough-cut MP4, SRT, transcription, keep/delete plan, and review notes.
If further fine editing is needed, provide the rough-cut MP4 and SRT as delivery materials for later import into CapCut/Jianying.

剪辑规则

Editing Rules

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

#	Rule	Description
1	Pause deletion	Silence with long gaps between adjacent segments can be deleted
2	Pure interjection deletion	Delete segments consisting entirely of interjections like um, ah, uh, oh
3	Adjacent repeat deletion	Prefer deleting the earlier occurrence and keeping the later one; gray areas need manual judgment
4	Keep mid-sentence interjections	Keep the entire segment when interjections appear in the middle of a sentence
5	Consecutive prefix cleanup	Clean redundant consecutive starters like "then", "so", "actually", "I mean"
6	Handle short segments carefully	Keep non-pure-interjection short segments by default
7	Smart margin	Add buffer before/after kept segments to avoid clipped speech
8	Smoothing	Merge overly short kept segments into adjacent segments to avoid flicker frames

三层审核

Three-layer Review

每一层都检查：

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

Each layer checks:

Whether there are word, phrase, sentence, or paragraph-level repeats.
Whether complete sentences have been cut in half.
Whether residual verbal stumbles, filler sentences, half sentences, or fragments with only a beginning remain.
Whether there are obvious pauses, blank spots, or rhythm breaks.
Whether transition sentences were mistakenly deleted, causing abrupt logical jumps.
Whether the paragraph structure still flows smoothly.

第一层：剪前删留方案

Layer 1: Pre-edit keep/delete plan

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

Delete ranges must correspond to repeats, verbal stumbles, filler sentences, obvious pauses, or unusable broken fragments; boundaries must not cut into the middle of a complete sentence unless a cleaner complete version exists later.

第二层：粗剪成片复转写

Layer 2: Re-transcribe the rough cut

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

After rendering, re-transcribe the rough-cut MP4. The final transcription must not contain obvious repeats, broken fragments, long pauses, logical jumps, or incomplete sentences caused by hard cuts.

第三层：最终通过

Layer 3: Final pass

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

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

The latest rough cut must pass a full review before you can say "ready for fine editing in CapCut/Jianying". If it fails, produce a new version.

It is recommended to use a manually confirmed rough-cut video as the quality benchmark. Future talking-head rough cuts should be judged against this standard: no repeated fragments, no obvious pauses, no complete sentences cut in half.

最终回复要求

Final Reply Requirements

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

Pure transcription: provide the transcription path, subtitle path, cache path, and state that no editing was performed.
Talking-head rough cut: provide the rough-cut MP4 path, SRT path, transcription path, keep/delete plan path, and review conclusion.
On failure, explain missing environment variables, missing files, upload failure, ASR failure, or ffmpeg errors.