자동 스토리텔러 애니메이트은(는) 무엇을 하나요?
음성 파일과 스크립트만 주면 전체 영화를 완성합니다: 타이밍, 레이아웃, 렌더링, 편집, 자막, 사운드, 믹싱, QA까지 모두 자동으로 처리합니다. 수동 스토리보드, 장면 코드, 편집 타임라인이 필요 없습니다.
python scripts/run.py --project my-film --voice voice.mp3 --script script.md
한 번의 명령으로 전체 파이프라인이 실행되어 my-film/out/FILM.mp4, my-film/out/FILM.srt (captioned.mp4 옆에 생성), credits.md, beats.json, plan.json, beats.md, out/qa/ 폴더의 검토 스틸 이미지, 그리고 모든 중간 파일이 생성됩니다.
시작하기 전에 — 사전 요구사항 확인 (자동)
모든 실행은 다른 작업보다 먼저 check_requirements.py로 시작합니다. 필요한 모든 도구가 설치되어 있으면 설정 없이 즉시 제작을 진행합니다. 누락된 것이 있으면 자동으로 다운로드/설치한 후 제작을 계속합니다.
다음 순서로 확인합니다:
- Python 3.8+
- Python 패키지 — numpy, skia-python, Pillow, faster-whisper — 누락 시 자동 pip 설치
- ffmpeg + ffprobe on PATH — 누락 시
winget(Windows),brew(macOS) 또는apt-get(Linux)을 통해 자동 설치 - cinematic-film 이 스킬 옆에 위치 (또는
CINEMATIC_SCRIPTS=<path to its scripts>설정)
모든 것이 준비되면 requirements: ok 한 줄 메시지와 함께 빌드가 시작됩니다. Python 패키지 설치가 실패하면 정확한 수정 명령어를 출력하고 빌드를 시작하지 않고 종료합니다. cinematic-film을 찾을 수 없는 경우에도 마찬가지로 누락된 것과 설정 방법을 정확히 알려줍니다.
제작 결과물 (비주얼 스타일)
두 가지 시각 언어가 3~10초마다 하드하게 번갈아 가며 나타나며, 각 블록의 레이아웃은 감독(director)이 결정합니다:
- Board - 전체 화면을 채우는 청사진 시트. 어두운 파란색 격자 위에 손으로 그린 듯한 초크 타이포그래피로 단어가 나타나며, 스케치 사각형 콜아웃 박스, 흔들리는 선, 낙서 코드 창, 체크 표시, 구분선, 그리고 네온 아이콘 (두 번의 글로우 패스 + 핫 코어)이 코드로 그려집니다.
- Photo - cinematic-film의 밤 증거 벽: 실제 라이선스가 있는 Wikimedia Commons 사진에 그림자와 핀을 추가하고, 종이 문서, 지터 하이라이트 규칙, 빛나는 네온 아이콘을 배치하며, 모든 출처는
credits.md에 기록됩니다.
자막은 화면 하단 중앙에 하단 가장자리에 딱 붙어서 (720p 기준 6px, 해상도에 따라 비례 조정), 대문자로 표시되며, 9가지 시드 기반 캔디색 중 하나를 사용합니다. 등장 애니메이션 (rise/pop/slide/tilt/fade/wipe/stagger)과 퇴장 애니메이션 (fade/drop/riseout/shrink)이 적용되고, 3패스 블룸 후광, 음성 단어에 무지개 그라데이션 스윕 (네온 튜브 흰색 테두리)이 추가됩니다. 자막 뒤에는 그라데이션 배경이 있어 어떤 화면에서도 가독성을 보장합니다. 텍스트는 음성을 그대로 반영합니다.
새 프로젝트 시작 vs. 이어서 작업
- 새 프로젝트: 음성과 스크립트를 제공하면 스킬이 모든 것을 빌드합니다.
python scripts/run.py --project my-film --voice voice.mp3 --script script.md - 이어서 작업: 이미
out/FILM.mp4(및 plan/photos)가 있는 프로젝트에서 다시 실행하면 QA만 다시 수행하여 확인합니다. 아무것도 다시 다운로드하거나 다시 렌더링하지 않습니다.--force를 추가하면 처음부터 다시 빌드합니다.
입력
--voice: ffmpeg가 읽을 수 있는 모든 오디오 파일 (mp3/wav/m4a...). 깔끔한 단일 테이크 나레이션에서 최상의 결과를 얻습니다. 원본 그대로 사용되며, 48 kHz 스테레오 AAC로만 변환됩니다.--script:.md/.txt/.srt/.json. Markdown 제목은 화면에 섹션 키커(section kicker)로 표시됩니다. 빈 줄과 단락은 문장으로 분할된 후 자막 청크(<= 9 단어 / <= 64자)로 나뉩니다. 화면에 표시되는 텍스트는 파일의 텍스트를 그대로 사용합니다.script.json에{"title": ..., "takes": [...]}형식이 있으면 이를 따릅니다.
옵션
| 플래그 | 효과 |
|---|---|
--size 1920x1080 | 렌더링 크기 (기본값 1920x1080) |
--crf 16 | 품질 (낮을수록 좋음; 16=영화, 26=미리보기) |
| `--photos auto | existing |
| `--music auto | none |
--model tiny.en | 정렬을 위한 faster-whisper 크기 (base.en/small.en이 더 정확함) |
--preview | 빠른 확인을 위해 블록 0-1만 640x360으로 렌더링 |
--skip-render | 계획만 다시 수립 (렌더링 없음) |
--workers WORKERS | 렌더링 + 자막 작업자 수 (0 = 모든 코어 - 1) |
--force | 완성된 out/FILM.mp4가 이미 있어도 다시 빌드 |
성능 및 안전
- 프로덕션 캐시 위치:
E:\Storyteller catche files(STORYTELLER_CACHE로 재정의 가능). 모든 무거운 아티팩트는 콘텐츠 해시 아래에 캐시되므로, 이후 단계를 다시 실행하거나 조정할 때 변경된 부분만 다시 처리합니다:
| 폴더 | 캐시 대상 | 키 |
|---|---|---|
whisper/ | faster-whisper 단어 타이밍 | 음성 파일 + 모델 + 장치 |
commons_search/ | Commons 검색 결과 세트 | 쿼리 + 제한 |
commons_files/ | 다운로드된 Commons 원본 + 크레딧 사이드카 | Commons 제목 |
blocks/ | 렌더링된 스타일 블록 | 장면 + 비트 + 블록 지오메트리 + 크기 + CRF |
silent/ | 이어붙인 무음 영화 | 블록 파일 + CRF + fps |
captioned/ | 자막이 추가된 영화 + SRT | 비디오 + 타이밍 + 자막 코드 + CRF |
sfx/ | 합성된 SFX 버스 | 큐 시트 + build_sfx.py |
music/ | 반복된 음악 트랙 | 음악 파일 + 영화 길이 |
mix/ | 완성된 오디오 믹스 | 음성 + 큐 + 음악 + 레벨 + LUFS |
파일은 <label>-<hash12>.<ext> 형식으로 이름이 지정되고 종류별로 정렬되며 (sort 목록이 자연스럽게 읽힘), 루트에 추가 전용 index.jsonl 매니페스트와 README.txt가 있습니다. 캐시 미스는 자동으로 다시 빌드됩니다. 캐시를 삭제하는 것은 항상 안전합니다. 변경되지 않은 단계를 다시 실행하는 데는 몇 초밖에 걸리지 않습니다 (whisper/blocks/stitch/captions/sfx/mix 모두 캐시 히트).
- 각 블록은 개별적으로 렌더링된 후 프레임 단위
concat필터로 이어붙입니다. 스크립트 편집 후 다시 실행하면 계획이 변경된 블록만 다시 렌더링됩니다 (render_blocks.py는 신규 블록 파일과 프로덕션 캐시를 두 번째 레이어로 재사용). - 12코어 / 충분한 RAM:
--workers 6사용. 3분 1080p 영화는 약 15-30분 소요. - 사용자가 요청하지 않은 최종 영화는 절대 렌더링하지 마세요: 먼저
--preview또는 작은--size를 사용하여 보여주고, 그 다음에야 전체 크기의FILM.mp4를 생성하세요. - Whisper tiny.en은 CPU에서 실시간의 약 1배 속도입니다. 긴 줄에서 타이밍이 어긋나면
--model base.en을 사용하세요.
감독(Director)의 역할
각 자막 줄은 하나의 비트(beat) 가 됩니다. 비트는 그 단어들로부터 정확히 하나의 레이아웃을 부여받습니다:
| 레이아웃 | 트리거 | 그리기 |
|---|---|---|
title / end | 처음 2 / 마지막 2 줄 | 네온 아이콘 + 큰 초크 제목 (제목 = 줄의 내용 단어들의 title case) |
chain | first/second/then/process/pipeline | 화살표가 있는 3개의 스케치 상자 |
split | before/after/versus/compared/instead | 찢어진 구분선 양쪽에 레이블이 지정된 두 프레임 |
window | code/script/terminal/agent/model/server | 손으로 그린 터미널 창 + 낙서 행 + 강조된 줄 |
check | protect/patch/secure/prevent/never | 목록 아래로 내려가는 초크 체크표시 |
stat | 모든 숫자 | 거대하게 빛나는 숫자 |
quote | 기타 모든 것 / 질문 | 초크 인용구 |
| 사진 변형 | 매 다른 블록 | station (사진 + 카드), doc (종이 문서 + 도장), stat |
연속된 줄(1-4줄, 최대 약 9초, 문장 끝에서 끊음)은 블록으로 그룹화됩니다. 블록은 영화 전체에 걸쳐 board/photo를 번갈아 가며 나타납니다. 첫 번째와 마지막 블록은 항상 board입니다.
생성되는 파일
audio/narration.m4a 노멀라이즈된 음성
audio/timing.json 줄별 시작/종료 (엔진 스키마)
script.json 말하는 순서의 takes, ID 순서 유지
beats.json 줄별: start/end/layout/kicker/headline/points/number/icon/ink/photo/x
plan.json 블록 (스타일, 프레임 범위, 월드 x), fps, 지속 시간
beats.md 전체 계획의 사람이 읽을 수 있는 테이블
sfx_cues.json build_sfx.py를 위한 합성 효과
photos.json 라이선스/크레딧/출처가 포함된 Commons 선택
out/blocks/bNNN.mp4 스타일 블록당 하나의 클립
out/silent.mp4 이어붙인 그림
out/captioned.mp4 + 네온 자막 추가 (+ .srt)
out/FILM.mp4 최종본, 혼합 오디오 포함
out/qa/*.png 검토 스틸 이미지
credits.md 이미지 + 음악 크레딧
QA 게이트 (scripts/qa.py, run.py에 의해 자동 실행)
다음 조건에서 빌드 실패 처리: 프레임 수가 timing.total_duration * fps와 불일치, 오디오 스트림 없음/누락, 음량이 -15 +/- 1.5 LUFS 범위를 벗어남, 진정 피크(true peak)가 -0.8 dBTP 초과, 자막 청크가 보이지 않음, 또는 자막 기준선이 프레임 높이의 8.5% 이상 위쪽에 위치.
동반 스킬 (실제 프로덕션이 완료되는 방식)
이 스킬은 교육/설명 영화 워크플로우("AI 익스플로잇 에이전트 영화 같은 비디오")를 위한 전용 오케스트레이터입니다. 프로덕션을 완료하기 위해 두 개의 동반 스킬을 구동합니다. 이전 영화들이 제작된 방식과 동일하게 작동하며, 직접 호출할 필요 없이 run.py와 qa.py가 처리합니다. 절대적인 규칙은: 이 스킬이 작동하도록 동반 스킬이나 다른 프로젝트 (예: C:\remotion-build\dark-reality-explainer)를 편집하지 마세요 — 동반 스킬을 제공된 그대로 사용하세요. 모든 오케스트레이션 로직, 캐시, QA 및 스타일 결정은 이 스킬에 있습니다.
1. cinematic-film — 세계관, 사진, 사운드 (필수, 강한 의존성)
이 스킬 옆에 위치 (재정의: CINEMATIC_SCRIPTS=<path to its scripts dir>). 다음 스크립트에서 호출:
| 스크립트 | 사용처 | 이 영화를 위해 하는 일 |
|---|---|---|
prep_assets.py | prep 단계 | Commons 사진을 흑백 룩으로 등급 조정 (`--grade bw |
fetch_commons.py | fetch_photos.py | 라이선스된 원본 다운로드 (get), 파일/크레딧/라이선스 채우기, credits.md 작성 (credits) |
render.py | render_blocks.py | --t0/--t1로 각 스타일 블록 렌더링; board/photo 세계, 카메라 및 프레임별 모든 항목 그리기 |
engine.py | storyboard.py, 모든 렌더링 | 세계 모델: Film, 카메라 키, Board, PaperDoc, StylePanel, 스플라인 카메라 |
captions.py | captions_burn.py | 핫 워드 타이밍에 사용되는 단어 시계 (words_with_times) |
build_sfx.py | audio_finish.py | sfx_cues.json에서 효과 버스 합성 (라이선스할 샘플 라이브러리 없음) |
mix_soundtrack.py | audio_finish.py | 음성 + SFX + 음악: -19 dB SFX, -18 dB 음악, 4:1 덕킹, -15 LUFS / -1.5 dBTP 마스터 |
규칙: 이 스킬을 위해 cinematic-film의 스크립트를 수정하지 마세요 — 동작 변경은 storyboard.py / render_blocks.py / 여기에서 이루어져야 합니다. CLI 계약 (--t0/--t1, fetch_commons get|credits, mix_soundtrack --lufs)은 프로덕션 캐시가 해시하는 대상입니다. cinematic-film이 변경되면 여기 단계를 업데이트하고 E:\Storyteller catche files를 삭제하여 오래된 히트가 남지 않도록 하세요.
2. remotion-studio — 브라우저 미리보기 / 조정 (선택 사항, 검토 전용)
npx remotion studio (출력된 URL 열기; 또는 --no-open으로 직접 URL 열기).
정확한 범위: Studio는 Remotion 컴포지션만 미리봅니다 — Remotion 프로젝트에 등록된 React 컴포넌트. 이 스킬의 완성된 마스터 (out/FILM.mp4는 skia/ffmpeg 렌더링 결과물이며 Remotion 프로젝트가 아닙니다; AI-attack 영화도 마찬가지였습니다)를 재생할 수 없습니다. 결과물이 Remotion 프로젝트로도 존재하고 편집하면서 미리보기를 원할 때 (또는 Remotion 기반 변형을 조정할 때) 사용하세요. 이 스킬의 출력물을 검토하려면 out/FILM.mp4 / out/preview_captioned.mp4와 out/qa/ 스틸 이미지를 사용하세요 — Studio는 연결할 대상이 없습니다.
프로덕션 레시피 (세 스킬이 함께 영화를 완성하는 방법, 이전과 동일)
- 음성 + 스크립트 ->
run.py --preview(2 블록, 640x360, 약 2분). 룩, board/photo 리듬, 자막 크기와 하단 정렬, 그리고qa.py가 PASS를 반환하는지 확인. - 전체 계획 — 수집 (whisper 정렬) -> 감독 (비트, 레이아웃, 스타일 교대) -> Commons 사진 (무료 라이선스,
credits.md크레딧) -> 준비 (bw 등급) -> 장면 -> 큐. - 렌더링 — 각 블록을 1080p로 개별 렌더링;
E:\Storyteller catche files의 프로덕션 캐시를 통해 재사용. - 마무리 — 이어붙이기 (concat 필터) -> 하단 정렬 네온 자막 -> SFX
-19 dB/ 음악-18 dB, 덕킹,-15 LUFS마스터. - 검토 —
out/FILM.mp4재생;out/qa/에 스틸 이미지 보관. Remotion 패키징/검토 단계가 필요하면 해당 Remotion 프로젝트를remotion studio로 열고 로드되는지 확인. - 전달 —
FILM.mp4+FILM.srt+credits.md. 업로드/내보내기는 이 스킬 외부에서 처리.
SRT / 배포 측면
qa PASS 후: out/captioned.srt가 out/captioned.mp4 옆에 생성됩니다 (마무리 단계에서 FILM.mp4 옆에 복사 가능). 소셜 변형(9:16 재편집, 플랫폼 내보내기, 썸네일 스테이징)의 경우 이 스킬에서 다시 렌더링하지 말고 배포 스킬을 사용하세요 — 이 스킬은 16:9 마스터만 생성합니다.
요구사항
시작하기 전에 — 사전 요구사항 확인 참조: Python 3.8+, numpy, skia-python, Pillow, faster-whisper, PATH에 ffmpeg/ffprobe, 그리고 이 스킬 옆에 cinematic-film 스킬 필요 (재정의: CINEMATIC_SCRIPTS). 확인은 모든 실행 시작 시 자동으로 실행됩니다.
알려진 제한 사항
- 정렬은 기본적으로 whisper tiny.en을 사용합니다. 중얼거리는 테이크는 타이밍이 어긋날 수 있습니다.