hahadu4520/vlog-cut

burn-subtitles-cn

Use when the user wants Chinese subtitles burned into a finished rough cut.

Ver código-fonte

Como usar

  1. Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
  2. Consulte no original as ferramentas, credenciais e ambientes necessários.
  3. Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/hahadu4520/vlog-cut --skill burn-subtitles-cn

Antes de começar

  • A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
  • Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Documento original do Skill

Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.

burn-subtitles-cn

Three CLIs, used in sequence. Each is fine to call alone too.

stepCLIinputoutput
splitvlog-cut-subs-splittiming.jsonsubs_pages.json
buildvlog-cut-subs-buildsubs_pages.jsonsubtitles.ass
burnvlog-cut-subs-burnmp4 + .ass<name>_subs.mp4

When to use

Trigger on:

  • "加字幕 / 烧字幕 / 把字幕烧上去 / 出带字幕的版本"
  • "burn subtitles / add Chinese subs / hard-coded subs"
  • the user has a finished rough_cut.mp4 + the timing.json that produced it

Skip when:

  • the user wants soft subs they can toggle in players → just hand them the .ass + mp4 separately (use subs-build only, skip subs-burn)
  • the language isn't Chinese — the splitting heuristic (≤12 chars, Chinese punctuation priority) is tuned for CJK

Step 1 — split (paginate)

bash
vlog-cut-subs-split \
  --timing  <project_dir>/timing.json \
  --out     <project_dir>/subs_pages.json \
  --max-chars 12

Algorithm: greedy scan from the start of each line, find the strongest available break point (。!?;—— → ,、: → space) within the next N chars; otherwise hard-cut at N. Each page strips leading/trailing punctuation. Page durations are interpolated from the line's start/end by character-count fraction.

Optional:

  • --max-chars 12 — characters per page (default 12, fits comfortably on 1080p with size 56 font)
  • --keep-together <path> — file with whitespace-separated 2-char bigrams that must NOT split across pages (e.g. proper nouns). One file per project.
  • --script <path> — script.json with sections containing punctuated lines[]. For each timing line whose section matches, the splitter replaces the timing's text with the script's punctuated version (joined by ,). Timestamps are unchanged. Use this when timing.json came from `align-narration` — whisper's Chinese transcription strips punctuation, so without --script the splitter has no soft-break anchors and is forced into hard-cuts every 12 chars (e.g. "AI" + "时代码"). With --script, it can break at commas / periods you wrote.

The output matches shared/schemas/subs_pages.schema.json.

text-source rule of thumb

  • driven from tts-from-script → timing.json already has the script's punctuated text → no --script needed
  • driven from align-narration → timing.json has whisper's no-punct text → always pass `--script` to recover splits at natural break points

If a section in timing.json doesn't match anything in --script, the splitter prints a WARN and keeps the original text for that section.

Step 2 — build (paged JSON → ASS)

bash
vlog-cut-subs-build \
  --pages <project_dir>/subs_pages.json \
  --out   <project_dir>/subtitles.ass

Optional style flags (sensible defaults match a 1080p vlog):

  • --size 1920x1080
  • --font "LXGW WenKai" — open-source 楷体 with a hand-written feel, looks more personal than the macOS default 宋体 (Songti SC). Install via brew install --cask font-lxgw-wenkai (see README's font section for the full set we recommend).
  • --font-size 56
  • --margin-v 80 — distance from bottom in px
  • --outline 2 — black outline around the white text
  • --shadow 1.5
  • --fade-ms 80 — per-page fade-in/out (0 = no fade)

For vertical 9:16 video, drop --size 1080x1920 --font-size 64 --margin-v 200.

Recommended fonts

All four ship as Homebrew casks — brew install --cask <name> and pass the family name to --font:

Family name (--font)CaskStyle
LXGW WenKaifont-lxgw-wenkaihand-written 楷体 — gentle, personal (default)
LXGW Marker Gothicfont-lxgw-marker-gothicmarker-pen handwriting — friendly, casual
Smiley Sansfont-smiley-sansrounded oblique — modern, media-style
Ma Shan Zhengfont-ma-shan-zhengbrush calligraphy — artistic but heavier to read

If --font names a family libass can't find, it falls back to whatever fontconfig picks — usually a system Sans. Pass the family name (left column) exactly, including the space.

--video (recommended): auto-detect letterbox + auto-fit font

When the underlying video has letterbox/pillarbox black bars (e.g. portrait clips inside a 1920x1080 horizontal canvas), subtitles by default span the full canvas width and their tails spill into the bars — reads as "missing characters" to viewers who focus on the inner content.

Just pass `--video <mp4>`. Build will:

  1. Run ffmpeg cropdetect on the video to find the narrowest content

rectangle across all frames

  1. Apply an 18% title-safe padding (default --safe-ratio 0.82, matching

the broadcast convention — tight margins look cramped even when text technically doesn't overflow)

  1. Auto-shrink --font-size so every subtitle page fits inside that budget
  2. If anything still overflows after fitting, print a WARN with the

offending pages

This is the recommended path. No manual safe-width math.

bash
vlog-cut-subs-build \
  --pages   <out>/subs_pages.json \
  --video   <out>/rough_cut.mp4 \
  --out     <out>/subtitles.ass

Manual overrides

  • --safe-width <px> — explicit width budget. Overrides cropdetect AND

bypasses --safe-ratio (use this exact pixel count). Use when --video isn't around or cropdetect picks a wrong rectangle.

  • --safe-ratio <0..1> — fraction of detected content width subtitles may

occupy (default 0.82). Lower for more breathing room (e.g. 0.7), higher if content edges are forgiving (e.g. 0.95). Only applies to cropdetect- derived widths — --safe-width is taken literally.

  • --no-auto-fit — only WARN about overflow, don't auto-shrink. Useful if

you want to manually decide between lowering font-size vs. lowering --max-chars in subs-split.

How the heuristic works

The text-width estimator inside build assumes Chinese chars ≈ 1.0 × font-size, ASCII ≈ 0.55 × font-size. libass does the actual layout — the heuristic is a leading indicator, not a precise measurement. The 5% auto-margin on top of cropdetect's content width accounts for slight underestimation. If you still see overflow in the rendered mp4 that the build-time warning didn't catch, pass --safe-width ~10% lower than the detected content width.

Step 3 — burn (composite onto video)

bash
vlog-cut-subs-burn \
  --video <project_dir>/rough_cut.mp4 \
  --subs  <project_dir>/subtitles.ass \
  --out   <project_dir>/rough_cut_subs.mp4

Optional:

  • --crf 20 — x264 quality (lower = better quality, larger file)
  • --preset veryfast — speed/quality tradeoff (see ffmpeg docs)

Audio is stream-copied (no re-encode). Video is re-encoded once with the subtitles burned into the pixels — there's no toggle-off in players.

Iteration workflow

If the user wants to adjust subtitle text (typos, line breaks):

  1. Edit subs_pages.json directly (it's a JSON list with per-page text).
  2. Re-run subs-build (instant — pure text op).
  3. Re-run subs-burn (slow — full re-encode).

If the user wants different style (font / size / position):

  1. Skip subs-split, skip subs-pages.json edits.
  2. Re-run subs-build with new style flags.
  3. Re-run subs-burn.

Checkpoint (when called from vlog-cut-pipeline)

After subs-build (before subs-burn), stop and ask the user to spot-check `subs_pages.json`. Common issues:

  • punctuation-aware splitter cut a proper noun in two ("阿勒" + "泰") → add it to a --keep-together file and re-split
  • a page is awkwardly long (one big line ran past 12 chars on a punct-free stretch) → bump --max-chars or break the source timing.json line

After subs-burn, stop and ask the user to watch the mp4 (checkpoint 4 in the pipeline becomes "subs preview approved", which is state.checkpoints.subs_preview_approved).

Why this is its own skill (not part of narration-cut)

  • runs after the rough cut is approved, so it's gated behind a separate user decision ("do you want subtitles at all?")
  • has its own iteration loop (style tweaks don't require re-rendering the video timeline)
  • if the user has an existing mp4 + timing.json from elsewhere, this skill works standalone

Dependencies

  • ffmpeg / ffprobe on PATH (libass-enabled build, which Homebrew's ffmpeg is by default)
  • A Chinese font installed for --font. Default is LXGW WenKai; install with brew install --cask font-lxgw-wenkai. See "Recommended fonts" above for alternatives. Without a matching font, libass falls back to whatever fontconfig picks (usually system Sans) — usable but not pretty.
  • no Python deps beyond stdlib
do mesmo repositório

Mais Skills

Todos os Skills
hahadu4520
Comunidade

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.

Instalações / 1h
1
GitHub Stars
49
Atualizado
8 de mai.
hahadu4520
Comunidade

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.

Instalações / 1h
1
GitHub Stars
49
Atualizado
8 de mai.
hahadu4520
Comunidade

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

Instalações / 1h
1
GitHub Stars
49
Atualizado
8 de mai.
hahadu4520
Comunidade

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.

Instalações / 1h
1
GitHub Stars
49
Atualizado
8 de mai.