SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsvolc-asr

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 duplicates, pauses, slips of the tongue, and useless sentences, and generate a rough-cut MP4 and SRT that can go into CapCut for fine editing.

Safety rules

  1. Do not touch the original footage. 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 can only be moved to the trash first.
  3. The original footage, working copy, rough-cut final video, 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; only read them from environment variables or a private configuration specified by the user.
  5. The ASR billing order is fixed as: first use the Doubao Speech application in the Volcengine console that still has a trial/duration package; only after the trial/duration package is confirmed used up is it allowed to switch to a paid application. Both the trial and paid AppID must be read from environment variables, and must not be hardcoded in the public skill.
  6. Trial and paid tokens must be separate: the trial application uses VOLC_ASR_TRIAL_TOKEN, and the paid application 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 application; if it is truly necessary to temporarily bypass this, you must clearly state that it will incur charges and obtain the user's 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, to avoid repeatedly consuming trial duration or balance.

How to use

# 基础用法：转写 + 分析 + 自动剪辑
python3 volc-asr/scripts/transcribe.py '<工作副本路径>'

# 只看标注不执行剪辑
python3 volc-asr/scripts/transcribe.py '<工作副本路径>' --dry-run

# 忽略 ASR 缓存，重新识别
python3 volc-asr/scripts/transcribe.py '<工作副本路径>' --no-cache

# 不执行 ffmpeg 剪辑，仍生成转写、标注和 SRT
python3 volc-asr/scripts/transcribe.py '<工作副本路径>' --no-execute

# 只转写，不做剪辑分析或生成 SRT
python3 volc-asr/scripts/transcribe.py '<工作副本路径>' --transcribe-only

# 只恢复查询已提交任务，不重新上传/提交
python3 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, set VOLC_ASR_TRIAL_EXHAUSTED=1, and the script will 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 application, first set VOLC_ASR_APP_ID; if that application is not a trial package application 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 for the trial application by default, to avoid the token belonging to a paid application while mistakenly thinking it is using the trial. Only when it is confirmed that VOLC_ASR_TOKEN itself is a trial token may you temporarily set VOLC_ASR_ALLOW_LEGACY_TOKEN=1 to be compatible with the old configuration.

After a successful submission, the script will write {工作副本}.asr_pending.json, saving only request_id, AppID, audio URL, and status, and not saving token/key. 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 CapCut
{工作副本}.txt Full transcript text and timestamps
{工作副本}.asr_cache.json ASR cache, reusable on re-runs
{工作副本}.asr_pending.json Records of incomplete ASR tasks, 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 volc-asr/scripts/transcribe.py '<工作副本路径>' --no-execute。
  4. Deliver the transcript, timestamps, subtitle draft, and cache paths.
  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 repetition/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, repetition, long pauses, useless sentences, half-sentences, meaningless 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 it needs to go into CapCut, hand it to jianying-editor for importing, track placement, visual refinement, and export.

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 consists only of filler words such as um, ah, uh, oh, etc.
3 Adjacent repetition deletion Prioritize deleting the earlier one and keeping the later one; gray areas are judged manually
4 Keep filler words within sentences 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 is repetition at the character, phrase, sentence, or paragraph level.
  • Whether a complete sentence has been cut apart.
  • 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, blank spaces, or rhythm breaks.
  • Whether transitional sentences were mistakenly deleted, causing the logic to jump suddenly.
  • Whether the paragraph structure is still smooth.

First layer: pre-cut keep/remove plan

Deletion intervals must correspond to repetition, 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 transcript must not contain obvious repetitions, incomplete sentences, long pauses, logical jumps, or incomplete sentences caused by hard cuts.

Third layer: final approval

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. Future spoken-word rough cuts should use this standard as the baseline: no repeated segments, no obvious pauses, and no cutting complete sentences apart.

Final reply requirements

  • Pure transcription: provide the transcript path, subtitle path, and cache path, and explain that no editing was done.
  • Spoken-word rough cut: provide the rough cut MP4 path, SRT path, transcript 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.