hahadu4520/vlog-cut

vlog-cut-pipeline

Use when the user wants to take a script + a folder of raw clips all the way to a finished rough cut.

Zobacz źródło

Jak używać

  1. Skopiuj polecenie instalacji i sprawdź źródła przed instalacją we własnym środowisku agenta.
  2. W oryginale sprawdź wymagane narzędzia, dane dostępowe i obsługiwane środowiska.
  3. Opisz dane wejściowe i oczekiwany rezultat; porównaj wynik ze źródłami.
npx skills add https://github.com/hahadu4520/vlog-cut --skill vlog-cut-pipeline

Przed rozpoczęciem

  • Instalacja nie obejmuje subskrypcji modelu, limitu API ani uprawnień do plików.
  • Gwiazdki i instalacje pokazują aktywność, a nie niezależny test jakości lub bezpieczeństwa.
Oryginalny dokument Skill

Treść z repozytorium z zachowaniem nagłówków, przykładów, kodu, tabel, linków i obrazów.

vlog-cut-pipeline

Top-level orchestration. Stop and ask for approval at every checkpoint — that's the whole point of this pipeline.

When to use

The user gives you:

  • a narration script (text or script.json)
  • a folder of raw video clips
  • a project directory to put outputs in

…and wants a rough-cut mp4 at the end.

If they only need one stage, call the underlying skill directly instead.

High-level flow

script.json ── tts-from-script ──▶ timing.json + narration.wav
                                              │
                            🔴 CHECKPOINT 1 — listen to narration.wav
                                              │
clips/      ── video-asset-index ──▶ assets_index.json + sheets/
                                              │
                            🔴 CHECKPOINT 2 — spot-check tags & usable
                                              │
        narration-cut.plan  ──────▶ timeline.json (draft)
        Claude refines by reading sheets ──▶ timeline.json (final)
        narration-cut.validate ─▶ exit 0 required
                                              │
                            🔴 CHECKPOINT 3 — review timeline.json
                                              │
        narration-cut.render  ────▶ rough_cut.mp4
                                              │
                            🔴 CHECKPOINT 4 — watch rough_cut.mp4
                                              │
                                            done

State file

Maintain <project_dir>/.vlog-cut/state.json matching shared/schemas/state.schema.json. Update stage, outputs.* paths, and checkpoints.* flags as you go. Read it at every entry to know where to resume.

Initial state when starting fresh:

json
{
  "project_dir": "<abs path>",
  "stage": "init",
  "outputs": {},
  "checkpoints": {
    "narration_approved": false,
    "timeline_approved": false,
    "rough_cut_approved": false,
    "subs_preview_approved": false
  },
  "settings": {
    "narration_source": "tts",
    "voice": "zh-CN-XiaoyiNeural",
    "rate": "-5%",
    "output_aspect": "16:9",
    "output_size": "1920x1080",
    "fps": 30,
    "want_subtitles": false
  }
}

Step-by-step

Stage A — narration (stage init → narration_ready)

Branch on `settings.narration_source`:

A1 — TTS (narration_source=tts, the default):

  1. If user gave plain text, help them write <project_dir>/script.json (validate against shared/schemas/script.schema.json).
  2. Run:
bash
   vlog-cut-tts --script <project_dir>/script.json --out <project_dir>
  1. Update state: stage=narration_ready, outputs.timing=<project_dir>/timing.json, outputs.narration=<project_dir>/narration.wav.

A2 — User-supplied audio (narration_source=user):

The user has their own recording (.m4a / .mp3 / .wav). Use align-narration instead.

  1. Probe local whisper first: which whisper. If absent, ask the user to install (pip install openai-whisper). Don't ask if it's already there.
  2. Help them author a script.json with a head_text field per section — the first few characters of that section as actually spoken. (Anchors are how align knows where each section begins in the recording.)
  3. Run:
bash
   vlog-cut-align --audio <path/to/recording.m4a> \
                  --script <project_dir>/script.json \
                  --out <project_dir>

For first-pass / no-script use, omit --script — you get one narration_00 line covering the whole audio.

  1. Read timing.json and check the alignment: any WARN about head_text not matching means that section is using the equal-fraction fallback. Edit head_text, rerun (whisper output is cached).
  2. Update state: stage=narration_ready, outputs.timing=<project_dir>/timing.json, outputs.narration=<project_dir>/narration.wav.

🔴 Checkpoint 1 — narration approved

STOP. Tell the user the narration is ready at <project_dir>/narration.wav and the timing is in timing.json. Ask them to listen and approve, OR to tell you which line(s) need re-synthesis.

If they want changes:

  • edit the line(s) in script.json
  • delete the corresponding tts/<id>.mp3 files
  • rerun vlog-cut-tts

Only when they say "approved" do you set checkpoints.narration_approved=true and continue.

Stage B — asset index (stage narration_ready → assets_indexed)

  1. Confirm with the user where the source clips live (e.g. <project_dir>/clips/ or an external folder).
  2. Run:
bash
   vlog-cut-index --src <clips_folder> --out <project_dir>
   # add --describe api ONLY if the user asks for auto-tagging
  1. If --describe api was not used: open assets_index.json and for each clip, Read its <project_dir>/sheets/<stem>.jpg and fill in scene / description / tags / usable / optionally chapters and highlight.
  2. Update state: stage=assets_indexed, outputs.assets_index=<project_dir>/assets_index.json.

🔴 Checkpoint 2 — tags spot-checked

STOP. Show the user a brief summary: how many clips, how many marked usable: false (and why), distribution across chapters. Ask them to spot-check the index.

If they want changes, edit assets_index.json directly. Don't continue until they approve.

Stage C — timeline (stage assets_indexed → timeline_reviewed)

  1. Run the deterministic baseline:
bash
   vlog-cut-plan \
     --timing  <project_dir>/timing.json \
     --assets  <project_dir>/assets_index.json \
     --out     <project_dir>/timeline.json \
     --size    <output_size>  --fps <fps>
  1. Refine. Read timeline.json. For any line where the picked shots look weak (low score, repeated clip, odd why), open sheets/<stem>.jpg for candidate alternatives and rewrite that line's shots array. Keep sum(shots.dur) >= line.duration so audio doesn't outrun video.
  2. Validate:
bash
   vlog-cut-validate \
     --timeline <project_dir>/timeline.json \
     --src      <clips_folder> \
     --timing   <project_dir>/timing.json

Must exit 0. Fix and re-validate until clean. (Exit 1 = warnings — usable but show the warnings to the user.)

  1. Update state: stage=timeline_drafted, outputs.timeline=<project_dir>/timeline.json.

🔴 Checkpoint 3 — timeline approved

STOP. Summarize the timeline for the user (lines × shots, any reused clips, any tpad freeze-frames the renderer will need). Ask them to read timeline.json and approve, or call out lines they want different.

When approved, set checkpoints.timeline_approved=true, stage=timeline_reviewed.

Stage D — render (stage timeline_reviewed → rough_cut_rendered)

  1. Run:
bash
   vlog-cut-render \
     --timeline  <project_dir>/timeline.json \
     --timing    <project_dir>/timing.json \
     --src       <clips_folder> \
     --narration <project_dir>/narration.wav \
     --out       <project_dir> \
     --name      rough_cut.mp4
  1. Update state: stage=rough_cut_rendered, outputs.rough_cut=<project_dir>/rough_cut.mp4.

🔴 Checkpoint 4 — rough cut approved

STOP. Tell the user where the file is, mention the duration / size from the final probe. Ask them to watch and approve.

If they want changes: most fixes happen by editing timeline.json and re-running render (segs are cached — only changed shots re-encode). Bigger fixes (wrong narration line, mistagged clip) loop back to earlier stages.

When approved, set checkpoints.rough_cut_approved=true, stage=rough_cut_approved.

If settings.want_subtitles=false: → stage=done. Otherwise continue to Stage E.

Stage E — subtitles (stage rough_cut_approved → subtitles_burned → done)

Triggered when settings.want_subtitles=true OR the user explicitly asks for subtitles.

  1. Split timing into pages. If narration came from `align-narration`, pass `--script` so the splitter uses your punctuated text instead of whisper's no-punct version:
bash
   vlog-cut-subs-split \
     --timing  <project_dir>/timing.json \
     --script  <project_dir>/script.json \
     --out     <project_dir>/subs_pages.json \
     --max-chars 12

For TTS-driven projects (timing already has punctuation), omit --script.

  1. Read `subs_pages.json` and spot-check the splits. If a page still wraps awkwardly (proper nouns split across pages), call subs-split with --keep-together <bigrams.txt>. See burn-subtitles-cn/SKILL.md for full options.
  2. Build the .ass — always pass `--video <rough_cut.mp4>`. Build will probe the video's actual content rectangle via cropdetect and automatically shrink --font-size so every subtitle fits inside the inner content area (no text bleeding into letterbox/pillarbox black bars):
bash
   vlog-cut-subs-build \
     --pages <project_dir>/subs_pages.json \
     --video <project_dir>/rough_cut.mp4 \
     --out   <project_dir>/subtitles.ass

For vertical 9:16: add --size 1080x1920 --font-size 64 --margin-v 200.

Override paths (rare):

  • --safe-width <px> — manual override if cropdetect picks a wrong rectangle
  • --no-auto-fit — only warn about overflow, don't auto-shrink font-size
  1. Burn onto the rough cut:
bash
   vlog-cut-subs-burn \
     --video <project_dir>/rough_cut.mp4 \
     --subs  <project_dir>/subtitles.ass \
     --out   <project_dir>/rough_cut_subs.mp4
  1. Update state: stage=subtitles_burned, outputs.final=<project_dir>/rough_cut_subs.mp4.

🔴 Checkpoint 5 — subtitles preview approved

STOP. Ask the user to watch rough_cut_subs.mp4. Common adjustments:

  • font/size/position not right → re-run subs-build with style flags + re-burn (no need to re-split)
  • wrong text on a page → edit subs_pages.json then re-build/burn
  • whole subtitle layer should go away → fall back to the no-subs version

When approved, set checkpoints.subs_preview_approved=true, stage=done.

Resuming

If state.json already exists, read it first and resume from stage. Don't redo earlier stages unless the user explicitly asks ("redo TTS", "re-index").

Hard rules

  • Never skip a checkpoint to "save time". The user signing off is the contract.
  • Never claim a stage succeeded without the corresponding output file existing. Verify with ls / Read.
  • All paths configurable. No hardcoded absolute paths anywhere — always derive from project_dir + clips_folder.
  • Don't auto-render after plan. Always pause for the timeline review checkpoint, even if validate exits clean.
z tego samego repozytorium

Więcej Skills

Wszystkie Skills
hahadu4520
Społeczność

align-narration

Use when the user has their OWN narration audio (m4a/mp3/wav) and needs the same timing.json + narration.wav that tts-from-script would emit. Calls whisper to transcribe, then groups segments into one line per section (using each section's optional headtext anchor in script.json). Triggers on "我自己录了配音 / 自带口播 / align my narration / 我有现成的录音". This is the v0.4 alternative to tts-from-script.

Instalacje / 1h
1
GitHub Stars
49
Aktualizacja
8 maj
hahadu4520
Społeczność

burn-subtitles-cn

Use when the user wants Chinese subtitles burned into a finished rough cut. Three CLIs — split (timing.json → paged subspages.json), build (subspages.json → ASS), burn (mp4 + ASS → mp4 with hard-burnt subs). Triggers on "加字幕 / 烧字幕 / burn subtitles / add Chinese subs". Designed for ≤12-char per-page Chinese subtitles with punctuation-priority line breaks.

Instalacje / 1h
1
GitHub Stars
49
Aktualizacja
8 maj
hahadu4520
Społeczność

narration-cut

Use when narration audio (timing.json + narration.wav) and an indexed asset pool (assetsindex.json) exist, and the user wants a rough cut. Three sub-tools — plan (draft a timeline), validate (check it before render), render (cut + concat + mux into mp4). Triggers on "对齐镜头 / 排时间线 / 出粗剪 / cut to narration / build timeline". Plan is a deterministic baseline; Claude usually rewrites timeline.json by hand before render.

Instalacje / 1h
1
GitHub Stars
49
Aktualizacja
8 maj
hahadu4520
Społeczność

tts-from-script

Use when the user has a narration script (script.json) and needs voiceover audio plus per-line timing data — synthesizes each line with edge-tts, probes durations, and writes timing.json + a merged narration.wav. Triggers on "做配音 / TTS / 文案配音 / 生成口播". Skip when the user already has their own narration audio (then use align-narration instead, planned for v0.4).

Instalacje / 1h
1
GitHub Stars
49
Aktualizacja
8 maj