SRT-Driven Video（SRT 기반 영상 파이프라인）
대본 한 편을 코드로 생성된 비주얼이 있는 설명 영상으로 만듭니다. SRT를 유일한 시간 기준으로 삼아 5단계로 진행되며, 각 단계가 끝나면 사용자 확인을 기다립니다.
환경 및 의존성
- Windows: Playwright(
channel="msedge", 로컬 Edge 사용으로 Chromium 불필요) + imageio-ffmpeg(ffmpeg 제공; ffprobe 미포함,ffmpeg -istderr로 사양 파싱). - 의존성 설치:
pip install playwright imageio-ffmpeg(스크립트 내에서 ffmpeg 위치 자동 처리). - 이 스킬의 scripts/는 모두 Windows에서 테스트된 버전입니다. Linux/macOS에서는
channel="msedge"를 제거하고 시스템 ffmpeg를 사용하세요.
5단계 개요
| 단계 | 산출물 | 확인 관문 |
|---|---|---|
| 0 개요 | outline.md + 의사결정표 | 사용자가 개요와 결정 확인 |
| 1 대본+SRT | script.md / subtitles.srt / 발표자 메모.md | 사용자가 대본 확인 |
| 2 스토리보드 | storyboard.json(check_timeline.py 필수 통과) | 사용자가 스토리보드 확인 |
| 3a 첫 장면+컴포넌트 라이브러리 | assets/shared/ + scene-001 저해상도 샘플 | 사용자가 스타일 확정 후에만 일괄 렌더링 |
| 3b 개별 장면 일괄 렌더링 | scenes/scene-NNN/scene.mp4 × N | 사용자가 주요 장면 재확인 |
| 4 합성 및 전달 | output/final.mp4 + cover.png | 사용자가 최종 영상 확인 |
자세한 절차, 의사결정표 필드, 일반적인 문제점(imageio-ffmpeg의 filter_complex_script 부재, alimiter의 level 함정 등)은 references/pipeline.md를 참조하세요.
3가지 핵심 계약(생략 불가)
- SRT 시간 기준: 스토리보드 장면 경계는 자막 경계와 일치해야 하며, 전체 시간 오차는 0.1초 이내여야 합니다.
python scripts/check_timeline.py <project_dir>로 각 단계마다 재확인합니다. - WORKLOG 이어받기: 프로젝트 루트에
WORKLOG.md를 생성합니다(템플릿은 references/worklog-template.md 참조). 세션 간 유일한 상태 전달 매체입니다. 의사결정표가 확정된 후에는 임의로 변경할 수 없습니다. 단계 3/4에 들어가면 기준 파일(outline/script/SRT/발표자메모/storyboard/assets/shared/scenes)이 고정됩니다. - 단계별 확인 관문: 각 단계 보고 후 사용자의 명시적 확인을 기다린 후 다음 단계로 진행합니다.
장면 렌더링(단계 3)
각 장면은 독립적인 HTML 페이지이며, window.setTime(t)를 통해 결정적 렌더링을 구현합니다(모든 애니메이션은 t의 순수 함수). 자막은 통일된 계약 요소 div#subtitle을 사용하여 합성합니다. 전체 개발 계약, 품질 검사 프로세스(check_frames.py 키프레임 모자이크), 디자인 가이드라인은 references/visual-authoring.md를 참조하세요.
시작 템플릿: assets/neon-theme/(확정된 테크네온 스타일의 theme.css + components.js, 파티클/글자 날아들기/데이터 카드/비교 막대/위험 색상 표시/전환/자막 컴포넌트 포함). 사용자가 동일한 스타일을 원하면 프로젝트 assets/shared/에 복사하고, 다른 스타일은 이를 구조적 템플릿으로 삼으세요.
python scripts/render_scene.py scenes/scene-001 --duration 10.5 --fps 30 --size 960x540 # 저해상도 샘플
python scripts/check_frames.py scenes/scene-NNN --times 0.5,3,6,9.2 # 렌더링 전 품질 검사
python scripts/render_all.py . # 전체 일괄 렌더링
python scripts/render_all.py . --no-subtitle --outdir output/nosub # 자막 없는 변형
python scripts/concat_final.py . # 합성 + 커버
선택적 효과음 모듈(기본 꺼짐)
사용자가 명시적으로 박자에 맞는 효과음을 요청할 때만 활성화하며, 단계 0 의사결정표에서 이미 확정해야 합니다.素材는 Freesound CC0(개별 라이선스 확인)에서 가져오고, 타임라인은 assets/sfx/mix_timeline.json에 저장하여 사용자에게 사전 검토를 받습니다. 전달은 두 가지 경로 중 하나를 선택합니다: FFmpeg 자동 믹싱(mix_sfx.py) 또는 CapCut 싱크 시트 내보내기(make_cue_sheet.py)로 사용자가 수동 추가 — 후자가 실제로 더 안정적입니다. 전체 절차는 references/sound.md를 참조하세요.
참조 외부 스킬/도구
- vibe-motion/sound(GitHub, 프로젝트 tools/sound/에 클론): Freesound 검색/다운로드 CLI. 저장소에 라이선스가 없으므로 내부 다운로드 도구로만 사용; 라이선스는 Freesound 개별 효과음의 CC0 선언을 따릅니다.
전달 사양
final.mp4: 1920×1080 / 30fps / h264 / yuv420p, 길이는 SRT 전체 시간과 정확히 일치; cover.png는 클라이맥스 고정 프레임(실제 프레임 샘플링으로 위치 결정)을 사용합니다. 길이, 프레임 수, 사양, 오디오 레벨을 검증한 후 WORKLOG를 업데이트하고 보고합니다.