YouTube 동영상을 코드로: 쇼츠와 장편
모션 디자이너가 하는 방식으로, 하지만 코드로 동영상을 제작합니다: HTML 페이지가 시간 값으로부터 프레임을 그리고, 나레이션이 타이밍을 설정하며, 스크립트가 결과물을 렌더링, 믹싱하고 증명합니다.
script.json ──► OmniVoice (MCP) ──► voice/*.wav ──► timeline.py ──► timeline.js ─────────┐
│ format: short | long | long-4k ▼
└─ style preset ─► style.css / style.js ─────────────────────► page(s).html (seek(t), K.layout per format)
│ check_page ► stills ► render (cached chunks)
music (only if asked) ─► make_music.py ─┐ ▼
sound effects (CC0) ─────────────────────┴─► mix_audio.py ─► mix.wav ─► mux ─► final.mp4 ─► verify_video.py
(long-form also: chapters.txt, captions.srt, thumbnail.jpg)
$SKILL은 이 스킬의 폴더를 의미합니다. 모든 작업은 하나의 CLI를 통해 실행됩니다: python3 $SKILL/scripts/short.py <command>.
포맷
short | long | long-4k | |
|---|---|---|---|
| 프레임 | 1080×1920 (9:16) | 1920×1080 (16:9) | 페이지 1920×1080, 출력 3840×2160 |
| 길이 | ≤ 180 초 (최적 < 60 초) | 제한 없음 (보통 5–15 분) | 제한 없음 |
| 안전 영역 | x 60–940, y 288–1440 (Shorts UI) | x 96–1824, y 54–1026 (타이틀 안전) | long과 동일 |
| 자막 | 화면에 내장됨 (스타일 일치) | captions.srt (YouTube용); 내장 선택 사항 | long과 동일 |
| 추가 사항 | — | 챕터, 챕터당 페이지 하나, 썸네일 1280×720 | long과 동일 |
프로필은 engine/formats.json에 있습니다. 페이지는 K.W/K.H와 K.layout({short, long}) 테이블을 사용하므로, 하나의 프로젝트를 두 포맷 중 하나로 빌드할 수 있습니다. 16:9 비디오에 대해서는 reference/long-form.md를 읽으십시오.
폴더 구성
| 경로 | 설명 |
|---|---|
scripts/short.py | 파이프라인 CLI: doctor, styles, init, style, kit, timeline, check, stills, thumb, music, mix, render, mux, verify, build |
scripts/timeline.py | 음성 길이 → 장면 타이밍, 단어 큐, 자막, 효과음 큐, 비트 스냅, 페이지 세그먼트, 챕터, SRT |
scripts/import_voice.py | OmniVoice 클립 가져오기: 변환, 무음 자르기, 잘못된 TTS 테이크 거부 |
scripts/make_music.py | 합성된 배경 음악 (7가지 분위기), 비트 그리드 기반, 모든 길이. 사용자가 요청한 경우에만 |
scripts/mix_audio.py | 음성 + 음악(덕킹) + 효과음 → −14 LUFS, 트루 피크 ≤ −1.5 dBTP |
scripts/verify_video.py | 정확성 게이트: 크기, 화면비, 코덱, fps, 프레임 수, A/V 동기화, 음량, 블랙/프리즈 프레임, 챕터, 안전 영역 시트 |
engine/formats.json | 포맷 프로필 (크기, 안전 영역, 자막 기본값, 제한) |
engine/render.cjs | Playwright 캡처 → ffmpeg H.264 (모션 블러, 프레임 범위, 4K용 2배 캡처), 접촉 시트 |
engine/check_page.cjs | 사전 렌더링 검사: 페이지 계약, 폰트, 결정론적 동작, 안전 영역, 자막, 텍스트 크기, 빈 프레임 |
engine/kit.js | 애니메이션 툴킷 (스프링, 큐, 자막, 전환, 포맷별 레이아웃, Manim 스타일 그리기/쓰기) |
template/ | 두 포맷 모두에서 빌드되는 완전한 작동 비디오 (에디토리얼 스타일) |
styles/ | 8가지 스타일 프리셋: style.json + STYLE.md; 3b1b-math와 kodekloud-devops는 두 포맷의 전체 데모 포함 |
assets/ | 폰트 (OFL/MIT) 및 CC0 사운드 효과 |
reference/ | 해당 단계에 도달했을 때 읽을 문서 (표는 마지막 참조) |
워크플로우
0. 설정 (처음 사용 시)
bash $SKILL/scripts/setup.sh # playwright + chromium into ~/.cache/yt-video, numpy/scipy
python3 $SKILL/scripts/short.py doctor
1. 브리핑 (한 라운드의 질문, 이후 작업)
하나의 메시지로 질문하십시오 (가능하면 AskUserQuestion 사용); 사용자가 이미 말한 내용은 건너뜁니다:
- 포맷: 쇼츠 (9:16) 또는 장편 (16:9, 1080p 또는 4K). 명확할 때 추론하십시오 ("쇼츠", "10분짜리 동영상").
- 주제와 시청자가 기억해야 할 한 가지. 스크립트, 기사 또는 URL이 있으면 함께 받으십시오.
- 스타일:
short.py styles. 기본값은editorial. 선택한 후styles/<name>/STYLE.md를 읽으십시오. - 음성: 복제 (참조 클립 + 대본), 디자인 ("여성, 젊은 성인, 낮은 음조, 영국 악센트") 또는 기본값 사용.
reference/voice-omnivoice.md참조. - 음악: 요청하지 않으면 꺼짐. 요청한 경우: 분위기 (
make_music.py --list). 사용자가 요청하지 않은 음악은 절대 추가하지 마십시오. - 길이: 쇼츠 20–45 초 (최대 180). 장편: 사용자의 목표; 챕터를 계획하십시오.
2. 스크립트 작성 및 승인 받기
reference/shorts-design.md (쇼츠) 또는 reference/long-form.md (16:9)를 읽으십시오. script.json을 작성하십시오 (스키마는 reference/page-contract.md에 있음): 장면당 하나의 아이디어; 모든 장면의 visual은 각 시각적 변화가 어떤 말한 단어에 해당하는지 지정합니다; 장편 장면은 chapter 제목을 가지며, 긴 비디오의 경우 챕터당 하나의 page를 가집니다. 사용자에게 장면 테이블(id, 대사, 시각적 요소, 큐 단어; 장편의 경우 챕터)을 보여주고, 오디오를 생성하기 전에 승인 또는 수정을 기다리십시오. 사실, 숫자, 인용문 또는 결과를 절대 지어내지 마십시오; UI 모형 내의 예시 값은 괜찮으며 예시로 표시됩니다.
3. 프로젝트 생성
python3 $SKILL/scripts/short.py init videos/<slug> --style <style> --format short|long|long-4k
템플릿 (또는 스타일의 demo/), kit.js, 폰트 및 스타일 토큰을 복사합니다. 승인된 script.json을 해당 위치에 넣으십시오 (format 필드를 유지하십시오).
4. OmniVoice (MCP)를 통한 나레이션 → voice/<scene-id>.wav
reference/voice-omnivoice.md를 따르십시오: OmniVoice MCP 도구를 찾고, 동일한 음성 설정으로 장면당 하나의 클립을 생성한 후 각각을 가져오십시오:
python3 $SKILL/scripts/import_voice.py <clip> videos/<slug> <scene-id> --text "<대사>"
무음, 잘리거나, 터무니없이 빠르거나 느린 테이크는 실패합니다 — 해당 테이크는 다시 생성하십시오. OmniVoice에 연결할 수 없으면 그렇게 말하고, 추정 타이밍으로 시각 자료를 계속 빌드한 후 나중에 음성을 추가할 수 있습니다.
5. 타임라인
python3 $SKILL/scripts/short.py timeline videos/<slug>
timeline.js (장면 및 단어 시간, 세그먼트, 챕터)와 out/captions.srt, 챕터가 있으면 out/chapters.txt를 작성합니다. 시각 효과는 K.cue('scene', 'word')를 통해 단어에 맞춰집니다.
6. 페이지 빌드
reference/page-contract.md, reference/kit-api.md, reference/scene-patterns.md 및 스타일의 STYLE.md를 읽으십시오. 비디오가 두 포맷으로 존재할 가능성이 있을 때 모든 레이아웃에 K.layout({short, long}) 항목을 제공하십시오. 모든 시각적 변화는 큐 단어 위에 위치해야 합니다.
7. 렌더링 전 체크 (저렴함, 대부분의 실수를 잡아냄)
python3 $SKILL/scripts/short.py check videos/<slug> # 모든 페이지가 PASS여야 함
python3 $SKILL/scripts/short.py stills videos/<slug> # out/stills*.png, 안전 영역은 빨간색
스틸 이미지를 직접 확인하십시오. 비어 있거나, 잘리거나, 겹치거나, 읽을 수 없거나, 스타일에서 벗어나거나, 해당 단어와 일치하지 않는 것을 수정하십시오. 프레임 0은 이미 훅(hook)을 보여주어야 합니다.
8. 음악 (요청된 경우에만) 및 믹싱
python3 $SKILL/scripts/short.py music videos/<slug> # 음악이 꺼져 있으면 아무 작업도 하지 않음
python3 $SKILL/scripts/short.py mix videos/<slug>
reference/music-and-sound.md를 참조하십시오.
9. 초안 → 검토 → 최종
python3 $SKILL/scripts/short.py build videos/<slug> --draft # 30 fps, 모션 블러 없음, 1080p: 빠른 검토용 복사본
python3 $SKILL/scripts/short.py build videos/<slug> --final # 모션 블러, crf 16, long-4k일 때 4K
build는 timeline → check → music → mix → render → mux → verify를 실행하고 첫 번째 실패 시 중지됩니다. 렌더링은 청크 단위로 캐시되므로, 편집 후 재빌드하면 변경된 부분만 다시 수행됩니다. 먼저 초안을 보내고, 최종 작업을 시작하기 전에 얼마나 걸릴지 알려주십시오 (장편 최종 작업은 시간이 오래 걸릴 수 있습니다; 백그라운드에서 실행하십시오).
10. 검증 및 전달
verify_video.py는 build 내부에서 실행됩니다. VERIFY PASSED가 출력될 때만 MP4가 완료된 것입니다. out/verify_sheet_<mode>.png (프레임 0 + 장면당 한 프레임, UI/안전 영역이 빨간색)를 열어 확인하십시오. reference/verification.md는 모든 검사를 설명합니다.
장편의 경우 short.py thumb videos/<slug>도 실행하십시오 (또는 전용 thumbnail.html을 렌더링).
전달: MP4, 프로젝트 폴더 (index.html은 실제 사운드트랙과 함께 브라우저에서 미리보기 가능), 그리고 간단한 노트: 장면 또는 챕터, 예시임을 명시, 음성 설정, 음악 분위기 (또는 "음악 없음"), 검증 요약 (LUFS, 트루 피크, 길이); 장편의 경우 chapters.txt, captions.srt 및 썸네일도 포함. 당신은 들을 수 없습니다: 사용자에게 귀로 확인할 타임스탬프를 제공하십시오 (훅, 가장 바쁜 효과음 순간, 가장 큰 음악 순간, 각 챕터 시작).
가장 중요한 규칙
seek(t)는 순수한 시간 함수입니다. 렌더링 경로에Math.random,Date.now, CSS 애니메이션/전환 또는 타이머를 사용하지 마십시오. 체커가 이를 강제합니다.- 텍스트는 포맷의 안전 영역 안에 있어야 합니다. 1080/1920을 하드코딩하지 마십시오:
K.W,K.H,K.SAFE,K.layout를 사용하십시오. - 프레임 0에서 화면에 의미 있는 내용이 있어야 합니다; 쇼츠는 1–2초마다, 장편은 몇 초마다 무언가 움직여야 합니다.
- 시각적 효과는 추정 시간이 아닌, 말한 단어 (
K.cue) 위에 위치해야 합니다. - 음악은 요청 시에만 추가합니다. 사운드 효과는 스타일 기본값을 따릅니다 (사용자가 끌 수 있음).
- 스타일은 명명된 크리에이터에게서 영감을 받았습니다; 그들의 로고, 마스코트, 캐릭터, 인트로 또는 이름을 화면에 사용하지 마십시오.
- 오디오가 "좋게 들린다"고 말하지 마십시오 — 측정된 숫자와 확인할 타임스탬프를 보고하십시오.
참조 파일
| 읽을 시점 | 파일 |
|---|---|
| 쇼츠 작성 시 | reference/shorts-design.md |
| 16:9 / 장편 관련 모든 것 | reference/long-form.md |
| 페이지 빌드, script.json 스키마 | reference/page-contract.md |
| 툴킷 사용 | reference/kit-api.md |
| 장면 디자인 | reference/scene-patterns.md |
| 스타일 선택/제작 | styles/README.md, styles/<name>/STYLE.md |
| 나레이션 생성 | reference/voice-omnivoice.md |
| 음악 및 사운드 효과 | reference/music-and-sound.md |
| 체크 실패 시 | reference/verification.md, reference/troubleshooting.md |