SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsyichen-volc-asr

yichen-volc-asr

General & other

View repository

Updated 10-16 00:22

About this skill

Volcengine ASR transcription + talking-head auto rough-cut

This skill handles two types of tasks at the same time:

  • Pure transcription: recognize local audio/video into text, timestamps, and subtitles.
  • Talking-head rough cut: based on ASR timestamps, remove repeats, pauses, slips of the tongue, and junk sentences, and generate a rough-cut MP4 and SRT that can go into CapCut for fine editing.

Safety rules

  1. The original footage stays untouched. First copy a working copy, then transcribe, re-transcribe, or edit the working copy.
  2. Do not directly delete any files. Temporary file cleanup must have the user's explicit permission, and files can only be moved to the recycle bin first.
  3. The original footage, working copy, rough-cut output, and re-transcription temporary files must be stored separately.
  4. Do not write TOS, ASR Token, Cookie, or API Key into the skill, ordinary memory, or logs; read them only from environment variables or a private configuration specified by the user.
  5. The ASR billing order is fixed: first use the Doubao Speech app in the Volcengine console that still has a trial/duration package; only after the trial/duration package is confirmed used up is switching to the paid app allowed. Both the trial and paid AppID must be read from environment variables and not hardcoded in the public skill.
  6. Trial and paid tokens must be separated: the trial app uses VOLC_ASR_TRIAL_TOKEN, and the paid app uses VOLC_ASR_PAID_TOKEN or the old VOLC_ASR_TOKEN. Before the trial package is used up, do not use the paid token as a stand-in for the default token.
  7. Before the trial/duration package is confirmed used up, VOLC_ASR_TRIAL_EXHAUSTED=1must not be set, and VOLC_ASR_APP_ID must not be made to point to the paid app; if a temporary bypass is truly needed, you must clearly state that it will incur charges and obtain user confirmation.
  8. After a long audio ASR submission succeeds, do not repeatedly run the same file to "try again". Prefer to wait for the current task to complete, or use the saved {工作副本}.asr_pending.json / --request-id to resume the query, avoiding repeated consumption of trial duration or balance.

How to use

# 基础用法：转写 + 分析 + 自动剪辑
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

The script uses VOLC_ASR_TRIAL_APP_IDby default, and preferentially reads VOLC_ASR_TRIAL_TOKEN. Only after confirming that the trial/duration package has been used up should VOLC_ASR_TRIAL_EXHAUSTED=1be set, and only then will the script switch to VOLC_ASR_PAID_APP_ID and read VOLC_ASR_PAID_TOKEN or the old VOLC_ASR_TOKEN. If it is truly necessary to switch to another Volcengine Speech app, first set VOLC_ASR_APP_ID; if that app is not a trial-package app and has not been marked as trial used up, the script will stop, unless VOLC_ASR_ALLOW_NON_TRIAL_APP=1。

If the local old environment only has VOLC_ASR_TOKEN, the script will not use it by default for the trial app, to avoid the token belonging to a paid app while mistakenly thinking it is using the trial. Only when it is confirmed that VOLC_ASR_TOKEN itself is a trial token may VOLC_ASR_ALLOW_LEGACY_TOKEN=1 be temporarily set for compatibility with the old configuration.

After a successful submission, the script writes {工作副本}.asr_pending.json, saving only request_id, AppID, audio URL, and status, and not saving token/secret. When rerunning, if there is no completed cache, it will preferentially resume this unfinished task; only when --force-new is explicitly passed will it re-upload and submit a new task.

Output files

File Description
{工作副本}_cut.mp4 The rough-cut video, which can be imported into CapCut
{工作副本}_cut.srt Subtitle file, importable into Jianying
{工作副本}.txt Full transcript text and timestamps
{工作副本}.asr_cache.json ASR cache, reusable on re-runs
{工作副本}.asr_pending.json Incomplete ASR task records, usable for recovery queries, cannot be treated as completed results

Pure transcription workflow

  1. Confirm the input file exists and its size is normal; if necessary, use ffprobe to check duration and encoding.
  2. Copy the original footage as a working copy, for example source_for_asr.mp4。
  3. Run python3 yichen-volc-asr/scripts/transcribe.py '<工作副本路径>' --no-execute。
  4. Deliver the transcript, timestamps, subtitle draft, and cache path.
  5. Clearly state that no editing was done this time.

Talking-head automatic rough-cut workflow

When the user asks to "help me cut a talking-head video", "automatic rough cut", or "remove repeats/pauses/slips of the tongue/broken sentences":

  1. Copy the original footage as a working copy to avoid modifying the original.
  2. Use Volcano ASR to generate a timestamped transcript and .asr_cache.json。
  3. Write a readable keep/remove plan:
    • KEEP: clean, informative, narratively necessary content.
    • DELETE: slips of the tongue, repeats, long pauses, useless sentences, half sentences, invalid filler words.
    • CHECK: content that may be useful but is verbose or uncertain in how it sounds.
  4. Use source footage timecodes to generate deletion intervals or retention intervals.
  5. Generate a rough-cut MP4. For long talking-head videos and multi-segment deletions, prioritize a stable segmented extraction + concat workflow.
  6. Perform re-transcription review on the rough-cut MP4.
  7. After passing review, output the rough-cut MP4, SRT, transcript, keep/remove plan, and review notes.
  8. If further refinement is needed, use the rough-cut MP4 and SRT as delivery materials for subsequent import into Jianying/CapCut.

Editing rules

# Rule Description
1 Pause deletion Silence with a relatively long gap between adjacent segments can be deleted
2 Pure filler word deletion Delete when an entire segment is only filler words such as um, ah, uh, oh, etc.
3 Adjacent repeat deletion Prioritize deleting the earlier one and keeping the later one; gray areas require manual judgment
4 Keep mid-sentence filler words When a filler word is in the middle of a sentence, keep the entire segment
5 Consecutive prefix word cleanup Clean up redundancy when words such as then, so, actually, I mean, etc. start consecutively
6 Handle short segments cautiously Short segments that are not pure filler words are kept by default
7 Smart margin Add buffer before and after retained segments to avoid cutting off words
8 Smoothing Merge overly short retained segments into adjacent segments to avoid flicker frames

Three-layer review

Check at every layer:

  • Whether there are repeats at the character, phrase, sentence, or paragraph level.
  • Whether any complete sentence has been cut off.
  • Whether there are residual slips of the tongue, useless sentences, half sentences, or segments with only a beginning and no ending.
  • Whether there are obvious pauses, blanks, or rhythm breaks.
  • Whether transitional sentences were mistakenly deleted, causing logic to jump suddenly.
  • Whether the paragraph structure is still smooth.

First layer: pre-cut keep/remove plan

Deletion intervals must correspond to repeats, slips of the tongue, useless sentences, obvious pauses, or unusable fragments; boundaries must not cut into the middle of a complete sentence unless there is a cleaner complete version afterward.

Second layer: re-transcription of the rough-cut final video

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

Third layer: final pass

The latest rough cut must pass one complete review before you can say "it can proceed to CapCut fine editing." If it does not pass, continue producing new versions.

It is recommended to use a manually confirmed rough cut final video as the quality benchmark. From now on, spoken-word rough cuts should use this standard as the baseline: no repeated segments, no obvious pauses, and no cutting off of complete sentences.

Final reply requirements

  • Pure transcription: provide the transcription file path, subtitle path, and cache path, and state that no editing was done.
  • Spoken-word rough cut: provide the rough cut MP4 path, SRT path, transcription file path, keep/delete plan path, and review conclusion.
  • If it fails, explain the missing environment variables, nonexistent files, upload failure, ASR failure, or ffmpeg error.