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.

Ver código fuente

Cómo usar

  1. Copia el comando y revisa el paquete antes de instalarlo en tu entorno de agente.
  2. Consulta las herramientas, credenciales y entornos necesarios en el documento original.
  3. Describe las entradas y el resultado deseado; contrasta la salida con las fuentes.
npx skills add https://github.com/hahadu4520/vlog-cut --skill align-narration

Antes de empezar

  • La instalación no incluye suscripción al modelo, cuota API ni permisos sobre tus archivos.
  • Las estrellas e instalaciones reflejan actividad, no una prueba independiente de calidad o seguridad.
Documento original del Skill

Contenido del repositorio de origen con títulos, ejemplos, código, tablas, enlaces e imágenes preservados.

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
del mismo repositorio

Más Skills

Todos los Skills
hahadu4520
Comunidad

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.

Instalaciones / 1h
1
GitHub Stars
49
Actualizado
8 may
hahadu4520
Comunidad

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.

Instalaciones / 1h
1
GitHub Stars
49
Actualizado
8 may
hahadu4520
Comunidad

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

Instalaciones / 1h
1
GitHub Stars
49
Actualizado
8 may
hahadu4520
Comunidad

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.

Instalaciones / 1h
1
GitHub Stars
49
Actualizado
8 may