hahadu4520/vlog-cut

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.

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/hahadu4520/vlog-cut --skill align-narration

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

align-narration

What this does

Takes a user-recorded narration audio file and produces:

  • <out>/narration.wav — the audio re-encoded to canonical mono 24kHz PCM WAV (same format tts-from-script emits, so narration-cut.render doesn't have to special-case)
  • <out>/timing.json — Timing data (per-line start / end / duration + total_duration), matching shared/schemas/timing.schema.json
  • <out>/whisper/<stem>.json — raw whisper output, cached for reruns

When to use

Trigger when the user says:

  • "我自己录了配音" / "我有现成的口播" / "用我自己录的"
  • "align my narration" / "I already have audio"
  • they drop an .m4a / .mp3 / .wav into the project folder instead of asking for TTS

Skip when:

  • the user wants TTS — that's tts-from-script
  • the user only wants a transcript (no timing alignment) — call whisper directly

How to call

Minimum-friction (no script):

bash
vlog-cut-align --audio /path/to/口播.m4a --out /path/to/project_dir

Produces a single line narration_00 covering the whole audio. The downstream timeline plan/render then chooses shots for that one giant line. Works but loses per-section structure.

With section alignment (recommended):

bash
vlog-cut-align \
  --audio /path/to/口播.m4a \
  --script /path/to/script.json \
  --out /path/to/project_dir

The script.json must include, for each section, a head_text field — the first few characters of that section as actually spoken. align uses head_text to find each section's start in the recording.

json
{
  "voice": "user-recorded",
  "rate": "+0%",
  "sections": [
    { "id": "intro",  "title": "钩子",   "head_text": "AI越好用",    "lines": [...] },
    { "id": "scene",  "title": "场景",   "head_text": "写代码",       "lines": [...] },
    { "id": "reason", "title": "道理",   "head_text": "对着屏幕",     "lines": [...] },
    { "id": "outro",  "title": "收尾",   "head_text": "散步当正经事", "lines": [...] }
  ]
}

If a section is missing head_text, align falls back to equal-fraction splitting (audiodur × sectionidx / n_sections) and prints a warning. Iterate by adding anchors as you review the output.

Optional flags

  • --engine whisperx — use word-level forced alignment (more accurate). Falls back to whisper with a warning if whisperx not installed.
  • --model large-v3-turbo — whisper model (default; for Chinese, large-v3-turbo is the sweet spot for speed × quality)
  • --language Chinese — whisper --language (default Chinese)

Caching

<out>/whisper/<audio_stem>.json is cached. If you re-run with the same audio (e.g. to retry section grouping with a different script.json), whisper isn't called again. To force re-transcription, delete that file.

narration.wav is also cached — delete it to re-encode.

Checkpoint (when called from vlog-cut-pipeline)

After this skill returns, stop and ask the user to spot-check `timing.json`. Common issues:

  • a section's head_text failed to match → that section's start is wrong → review the WARN lines align printed
  • whisper misheard a word → the text field looks wrong, but the timestamps are still usable; only fix if you'll burn subtitles later
  • audio has a long opening gap before the first word → first line's start > 0 is fine

Mark state.checkpoints.narration_approved = true once the user confirms.

How it differs from tts-from-script

tts-from-scriptalign-narration
inputtext in script.jsonrecorded audio (any format)
outputper-line MP3s + merged WAV + timingsingle canonical WAV + timing
line granularityevery script line gets its own MP3+timestampsone timing line per section (coarser)
iteration costedit script line, delete that MP3, rerun (only that line re-synths)edit head_text or re-record audio, rerun (whisper cached)
voice controledge-tts voices/rateswhatever you sound like

Dependencies

  • ffmpeg / ffprobe on PATH (re-encode audio, probe duration)
  • whisper CLI on PATH (pip install openai-whisper — adds ~3GB of PyTorch + a one-time model download)
  • optional: whisperx for word-level alignment
du même dépôt

Autres Skills

Tous les Skills
hahadu4520
Communauté

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.

Installations / 1h
1
GitHub Stars
49
Mis à jour
8 mai
hahadu4520
Communauté

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.

Installations / 1h
1
GitHub Stars
49
Mis à jour
8 mai
hahadu4520
Communauté

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).

Installations / 1h
1
GitHub Stars
49
Mis à jour
8 mai
hahadu4520
Communauté

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. Orchestrates tts-from-script → video-asset-index → narration-cut (plan / validate / render), with FOUR mandatory human-review checkpoints between stages. Triggers on "做视频 / 剪个视频 / 把这段文案做成视频 / make a video from this script". Do NOT bypass the checkpoints — Claude pauses, the user approves, then the next stage runs. State is tracked in /.vlog-cut/state.json.

Installations / 1h
1
GitHub Stars
49
Mis à jour
8 mai