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.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/hahadu4520/vlog-cut --skill align-narration

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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
같은 저장소의 Skills

더 많은 Skills

모든 Skills
hahadu4520
커뮤니티

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.

1시간 설치 수
1
GitHub Stars
49
업데이트
5월 8일
hahadu4520
커뮤니티

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.

1시간 설치 수
1
GitHub Stars
49
업데이트
5월 8일
hahadu4520
커뮤니티

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

1시간 설치 수
1
GitHub Stars
49
업데이트
5월 8일
hahadu4520
커뮤니티

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.

1시간 설치 수
1
GitHub Stars
49
업데이트
5월 8일