SuperAPI AI Directory

celebrity-slice

General & other

View repository

Updated 10-16 08:44

About this skill

DouBaoYa · Celebrity Clip (livestream recording → premium recommendation vertical clip)

This duck's one-sentence positioning:Cut a full livestream recording into a 50-70 second vertical (9:16) premium recommendation short-video clip— fully through the five-gate pipeline (ASR → proofreading + annotation → segment selection → composition → QA), restrained wording, natural breath points, subtitles faithful to the audio, every segment traceable.

  • Methodology details:references/methodology.md(positioning red lines, three hard alignments, first 3 seconds, breath points, stickers, QA four metrics)
  • Single source of truth for numeric rules:references/rules.json(scripts and agent read together,do not copy numeric values elsewhere)
  • ASR API contract:references/asr-api.md(proxy routing pending backend launch, before launch use the "degraded path")

Applicable to: livestream clip editing, e-commerce short-video operations, clothing/lifestyle host teams.

❌ The most critical discipline (remember first) Subtitles must be faithful to the audio: proofreading only corrects errors (typos/person names/brand names), never rewriting into marketing copy that was not said in the audio. Celebrity clips default to premium recommendation positioning: do not cut into a low-price livestream style, by default do not use price as the opening hook (see methodology.md for details, price_rule interpretation).

0. Environment requirements

  • Python 3 (scripts have zero third-party dependencies, standard library only)
  • ffmpeg / ffprobe in PATH (audio extraction, energy analysis, cutting and splicing, subtitle burning)

1. Get the key (DOUBAOYA_API_KEY)

Calling the ASR API requires a key (API Key). Four steps to get the key:

  1. Open doubaoya.com
  2. Log in
  3. Enter Key Center
  4. Click Generate Key

The key looks like dyh_xxxxxxxx. Once obtained, configure it into the environment variable:

export DOUBAOYA_API_KEY="dyh_xxxxxxxx"
Variable name Description Required
DOUBAOYA_API_KEY DouBaoYa key, looks like dyh_… Only needed for Gate 1 ASR

Security conventions:Never print the key out, write it into logs, paste it into conversations, or commit it into the repository. The script only uses it in the request header, and will not echo it back.

2. Data contract (JSON shape read by all scripts)

Word-level ASR JSON(asr_transcribe.py output, the other three scripts' --asr input):

{
  "version": 1,
  "source": "live.mp4",
  "duration_s": 3600.5,
  "segments": [
    { "text": "白", "start": 12.30, "end": 12.45 },
    { "text": "T", "start": 12.45, "end": 12.60 }
  ]
}

EDL JSON(agent handwrites it at the segment selection gate;snap_breath.py / validate_edl.py / make_captions.py --edl input):

{
  "clips": [
    {
      "id": "c1",
      "source_start": 12.3,
      "source_end": 18.9,
      "selection_reason": "痛点+证据开头",
      "selling_point": "白T不透",
      "visual_point": "上身抻拉",
      "risk_note": "",
      "signal_level": 3,
      "cuts": [ { "start": 13.0, "end": 13.4, "reason": "口水词" } ]
    }
  ]
}

signal_level(1-6, corresponding to rules.json selection_signals.levels) and cuts(in-segment cleanup, source-coordinate deletion intervals) optional.Red line: breath points are assets, cuts only delete explicitly marked word intervals, and by default do not touch pauses.

Proofread script JSON(agent produces it at the proofreading gate;make_captions.py --proofread input, only status=="confirmed" sentences take effect):

{
  "sentences": [
    { "start": 12.3, "end": 15.1, "original": "白提最怕透", "corrected": "白T最怕透", "status": "confirmed" }
  ]
}

⚠️ start/end must cover the entire sentence(from the sentence-initial character's start to the sentence-final character's end). The time range of the proofread sentence determines "which segment of the original ASR characters is corrected replaced" — if the declared end is shorter than the actual end of the whole sentence, those few characters at the tail will be both covered by the corrected text and retained once in the original ASR form, causing a duplicated tail in the subtitles (e.g. 洗几次都不变形。 immediately followed by a block of 不变形。). Better to set end up to just before the start of the next sentence than to set it too short.

3. Five-gate workflow

Gate 1 — ASR (word-level transcription)

python3 "$SKILL_PATH/scripts/asr_transcribe.py" 直播录像.mp4 --out-json words.json --out-srt raw.srt

Produces word-level JSON + a reference SRT.If the backend is not online or there is no DOUBAOYA_API_KEY , the script will clearly report an error and give a fallback path(see Section 6).

Gate 2 — Proofreading + Annotation (agent AI layer)

Per references/methodology.md , proofread sentence by sentence raw.srt / words.json:correct errors only, do not rewrite, stay faithful to the audio(typos, personal names, brand names, obvious homophone errors); produce the proofread draft proofread.json(contract see Section 2). At the same time, read through the transcript to annotate: script segments (against rules.json selection_signals.levels six-level signals), energy points, product information (selling points/risk words).

Gate 3 — Segment Selection

Per rules.json's selection_signals(six-level highlight signals + boundary signal words + no_cut_points) and rubric(e-commerce five-dimension 0-100 self-rating, total must equal the sum of the five dimensions), select the core script segments and hand-write the EDL JSON (contract see Section 2). Target total duration 50-70s.

Gate 4 — Composition

# 4.1 切点吸附气口(--apply 直接回写 EDL 坐标;同时产出能量互证标注)
python3 "$SKILL_PATH/scripts/snap_breath.py" --edl edl.json --asr words.json \
    --video 直播录像.mp4 --energy energy.json --apply --out edl_snapped.json

# 4.2 ffmpeg 逐段裁切 + 拼接 9:16(横版源居中裁切示例;agent 按实际分辨率调整)
ffmpeg -y -ss 12.34 -to 18.90 -i 直播录像.mp4 \
    -vf "crop=ih*9/16:ih,scale=1080:1920" -c:v libx264 -crf 18 -c:a aac clip_01.mp4
printf "file 'clip_01.mp4'\nfile 'clip_02.mp4'\n" > concat.txt
ffmpeg -y -f concat -safe 0 -i concat.txt -c copy raw_no_caption.mp4

# 4.3 生成成片时间轴字幕(--edl 把源时间轴重映射到成片时间轴,并产出溯源 source_map.json)
python3 "$SKILL_PATH/scripts/make_captions.py" --asr words.json --proofread proofread.json \
    --edl edl_snapped.json --format srt --source-map-out source_map.json --out captions.srt
python3 "$SKILL_PATH/scripts/make_captions.py" --asr words.json --proofread proofread.json \
    --edl edl_snapped.json --format ass --style karaoke --out captions.ass

# 4.4 烧字幕
ffmpeg -y -i raw_no_caption.mp4 -vf "ass=captions.ass" -c:v libx264 -crf 18 -c:a copy final.mp4

Regarding the shape of edl_snapped.json shape:snap_breath.py --apply --out 's output is an envelope — the top-level clips issnap report rows(snapped_start/gap_before_s/start_energy , etc., not containing id/cuts, and source_start/source_end is still the pre-snapbeforeoriginal value),the EDL after write-back is under the edl subkey:

{ "clips": [ /* 吸附报告 */ ], "rule": {...}, "energy_rule": {...},
  "edl": { "clips": [ /* 回写坐标后的真 EDL */ ] } }

make_captions.py --edl and validate_edl.py --edl will automatically recognize and use the edl sub-object, so just pass edl_snapped.json directly, no need to split manually. But when you read it yourself with jq and other tools, remember to take .edl— reading the top-level clips will get unsnapped coordinates and lose id and provenance fields.

About clips with cuts clip:cuts is only read by Gate 5's mechanical check (items 6 and 10),4.2's ffmpeg trimming and 4.3's make_captions.py --edl do not recognize it— both process by the whole segment of source_start→source_end . So clips with cuts mustfirst be expanded into multiple sub-segments according to the retention intervals, then fed to 4.2 and 4.3 (both use the same expanded EDL, otherwise the final video is net duration while the subtitles are gross duration,cuts and the subtitles after that will drift overall by one cuts total length). Gate 5 still usesthe unexpanded, with cuts withthat EDL to run, so as to verify the legality of cuts.

Gate 5 — QA (two layers, both must pass for delivery)

Mechanical layer(12 mechanical checks, fails must be cleared to zero, script exit code 0 = cleared):

python3 "$SKILL_PATH/scripts/validate_edl.py" --edl edl_snapped.json --asr words.json \
    --video 直播录像.mp4 --energy energy.json --out qa_report.json

fail-level 7 items: EDL non-empty / source exists / interval valid / does not exceed duration / no overlap / cuts valid / id unique. warn-level 5 items: no overly short fragments / cut points snapped to breath pauses (with energy annotations) / cuts snapped to text boundaries / word-level timestamp verification / total duration and provenance fields.

Semantic layer: the four metrics are self-assessed and zeroed out by the agent per methodology.md and written into the QA report: cross_cut_caption_count / split_semantic_across_screen_count / orphan_caption_fragment_count / screen_without_complete_meaning_count must all be 0.

Deliverables

final.mp4 + captions.srt / captions.ass + source_map.json(each segment traceable to source timestamps) + qa_report.json(machine-check checklist).

4. Script usage quick reference

Script Purpose Key parameters
scripts/asr_transcribe.py Extract audio → chunk → POST doubaoya ASR → merge word-level JSON + SRT <video> --language zh --chunk-seconds 600 --endpoint URL --out-json --out-srt; exit code 2 = no key
scripts/snap_breath.py EDL cut points snapped to breath pauses + RMS energy cross-validation annotations --edl --asr --video --energy(energy cache, read/write)--apply(write back coordinates,The result is under the output edl subkey)--rules --out
scripts/make_captions.py Word-level ASR + proofread script → SRT/ASS (including karaoke), can be remapped to the final cut timeline per EDL --asr --proofread --edl --format srt|ass --style --source-map-out(requires --edl)--rules --out
scripts/validate_edl.py 12-item machine check, outputs machine-check checklist JSON --edl --asr --video --energy --rules --out; exit code 0 = fail cleared, 1 = has fail

All scripts' --rules defaults to references/rules.json, generally no need to pass it. make_captions.py / validate_edl.py of all scripts' --edl accepts both bare EDL and snap_breath.py --apply 's output envelope (automatically takes the edl subobject).

5. Error codes (ASR interface)

First check the envelope success: if true , then read data; otherwise read error.code / error.message。

HTTP code Meaning / Handling
401 MISSING_API_KEY / UNAUTHORIZED No key provided or key invalid → check DOUBAOYA_API_KEY, go to the key center to regenerate
400 VALIDATION_ERROR Incorrect parameters → check audio base64 / format / language values
402 INSUFFICIENT_CREDITS Insufficient quota (general ASR call routing deducts per call) → go to doubaoya.com to top up/renew quota
404 NOT_FOUND ASR proxy routeBackend not yet online → follow the fallback path in Section 6
502 PROVIDER_FAILED Upstream ASR temporary failure,automatic refund issued, safe to retry → just rerun later

The script sends all failures uniformly to stderr:[error] code: message, and exits with a non-zero exit code.

6. Fallback path (when ASR is unavailable)

When the backend ASR route is not yet online, or the user does not have DOUBAOYA_API_KEY , Gate 1 switches to any one of:

  1. User provides ready-made subtitles: srt/vtt are both fine. The agent converts it to the word-level JSON in Section 2 (if there are no word-level timestamps, fill in at sentence level,snap_breath.py 's breath-pause snapping precision will decrease; inform the user truthfully).
  2. Local whisper: when the user's machine has whisper (e.g. whisper 直播录像.mp4 --model medium --language zh --word_timestamps True --output_format json), the agent converts its JSON to this contract's word-level JSON.

Gates 2-5 are unrelated to fallback and proceed as usual.

7. Directory structure

celebrity-slice/
├── SKILL.md                  # 本说明
├── references/
│   ├── methodology.md        # 完整方法论(定位红线/三硬对齐/前3秒/气口/贴纸/QA)
│   ├── rules.json            # 数值规则单一事实源
│   └── asr-api.md            # doubaoya ASR 代理接口契约(待后端上线)
└── scripts/
    ├── asr_transcribe.py     # 闸 1:抽音频→分块→ASR→合并词级 JSON+SRT
    ├── snap_breath.py        # 闸 4:气口吸附(RMS 能量互证)
    ├── make_captions.py      # 闸 4:SRT/ASS/karaoke 字幕 + source_map
    └── validate_edl.py       # 闸 5:12 项机检

About the notice field in the response

After calling the doubaoya API corresponding to this skill, if the returned JSON has at the top level notice field, please relay this sentence to the user verbatim—this is a notice that there is an update to this skill, it does not affect the result of this invocation, and no retry or change in behavior is needed.