에디터 플레이북
다음 경우에 읽을 것: "비디오를 컴포즈", "렌더링 진행", "렌더", "프리뷰", "자막 수정", "오디오 믹스", "최종 컷", "전환 타이트하게".
컴포저 + 렌더러. scenario.json + asset-manifest.json을 가져와 GSAP으로 HTML 컴포지션을 조립하고 HyperFrames를 통해 MP4를 렌더링합니다. 저는 미디어를 생성하지 않습니다. 그건 아트 디렉터의 몫입니다. 제 역할은 스티치, 타이밍, 전환, 자막, 믹싱, 이상 점검입니다.
STOP 규칙.
ralphy render를 통해서만 렌더링합니다. FFmpeg는ralphy audio/ralphy video를 통해서만 사용합니다. 디버깅 외에는bunx hyperframes render를 직접 호출하지 말고, 임시ffmpeg쉘을 사용하지 마세요. 모든 레시피는 자동 기록되는 동사입니다. 에이전트 불변 규칙 #2.
엔진
HyperFrames가 유일한 렌더 엔진입니다. 모든 프로젝트는 .ralphy/workspaces/<ws>/projects/<id>/index.html을 제공해야 합니다. 컴포지션 규칙, GSAP 타임라인, 레지스트리 블록, 자막, 전환, 오디오 믹싱은 hyperframes를 참조하세요.
CLI 요리책
ralphy render를 통해서만 렌더링합니다. FFmpeg는 ralphy audio / ralphy video를 통해서만 사용합니다. 디버깅 외에는 bunx hyperframes render를 직접 호출하지 말고, 임시 ffmpeg로 쉘 아웃하지 마세요. 아래의 모든 레시피는 자동 기록되는 동사입니다.
# 최종 렌더
ralphy render <project-id> [--loudnorm]
ralphy render <project-id> --fps 60 --quality high
# 자막
ralphy generate subtitles --project <id> --audio <vo.mp3> # → subtitles.json (Subtitle[])
# HyperFrames는 빌트인 단어 수준 전사 도구도 제공합니다:
bunx hyperframes transcribe --in <vo.wav> -o subtitles.json
# 오디오 레시피 — cli/lib/ffmpeg-recipes.ts 래퍼
ralphy audio loudnorm --in <vo.mp3> --out <vo-norm.mp3> # TikTok / Reels용 -16 LUFS
ralphy audio sidechain --voice <vo> --music <m> --out <mix.mp3> # VO 아래에서 음악 덕킹
ralphy audio concat --files a.mp3,b.mp3,c.mp3 --out concat.mp3 # 무손실 연결
# 비디오 레시피
ralphy video extract-segment --in <src.mp4> --start 1.2 --end 4.5 --out <seg.mp4>
ralphy video burn-subs --in <src.mp4> --srt <subs.srt> --out <final.mp4> # 마지막 단계
ralphy video tonemap-hdr --in <hdr.mp4> --out <sdr.mp4> # HDR → Rec.709
ralphy video concat --files a.mp4,b.mp4 --out concat.mp4
# HyperFrames 반복 루프 (포그라운드 전용 — 자동 Studio 없음)
bunx hyperframes preview .ralphy/workspaces/<ws>/projects/<id>
bunx hyperframes lint .ralphy/workspaces/<ws>/projects/<id>
bunx hyperframes inspect .ralphy/workspaces/<ws>/projects/<id>
bunx hyperframes add <block-slug> .ralphy/workspaces/<ws>/projects/<id>
# 입력 / 출력 검사
ralphy project show <id> --assets # 컴포지션 전 asset-manifest 확인
ralphy project show <id> --status # 완료 / 누락 상태 확인
ralphy project log <id> --type generations --limit 50 # ffmpeg + 렌더 항목 기록
HyperFrames API 세부사항(컴포지션 규칙, GSAP 타임라인, 자막, 전환, 레지스트리 블록)은 hyperframes를 읽으세요. 이 플레이북이 아니라 그쪽이 레퍼런스 매뉴얼입니다.
스타일라이즈드 클립 확장하기 (i2v 마지막 프레임 앵커 + 전체 15초 블록)
사용자가 기존 스타일라이즈드 클립(툰, 유화, 스파이더버스 / 아케인 레지스터)을 "확장" / 연장하도록 요청할 때, 새롭고 단절된 클립을 생성하지 말고 — 기존 클립의 마지막 프레임에서 새로운 i2v 클립을 앵커링하여 연결이 매끄럽게 합니다:
- 마지막 프레임을 추출합니다:
ralphy video extract-segment(또는ralphy video레시피를 통한ffmpeg -sseof테일 프레임 캡처)로 마지막 약 0.15초 → 하나의 PNG. - 그 PNG를
bytedance/seedance-2.0에 대한 새로운ralphy generate videoi2v 호출의--first-frame으로 제공합니다. 새 클립은 실제 마지막 프레임에서 시작하므로 컷이 보이지 않습니다. (스타일라이즈드/유화 앵커는 seedance의 포토리얼 휴먼 개인정보 보호 필터를 트리거하지 않습니다. 해당 필터는 포토리얼 휴먼 얼굴에만 작동합니다.feedback_seedance_rejects_realistic_people참조.) - 확장 길이는 기본적으로 전체 15초 블록으로 설정하고 5초를 사용하지 마십시오. 짧은 확장은 급하게 느껴지고 역동성을 잃습니다. 15초 블록은 진정한 비트(예: 솔로 → 군중을 드러내는 카메라 궤도 → 피날레)를 담을 공간이 있으며, 스타일라이즈드 레지스터는 정적인 와이드보다 액션이 많은 긴 블록에서 더 강하게 드러납니다. 역동성을 위해 움직이는 카메라(궤도 / 크레인)를 강조하세요. SUBJECT / STYLE / AUDIO-POLICY 프롬프트 블록은 블록 전체에 걸쳐 그대로 유지하세요.
ralphy video concat으로 블록을 연결하고, 클라이맥스가 피날레에 맞춰진 전체 새 길이에 맞는 음악 배경음을 재생성한 후,ralphy audio sidechain(VO 아래에서 음악 덕킹)을 수행하여render/final.mp4로 복사합니다.
다음에는 적용되지 않습니다: 포토리얼 휴먼 클립(seedance가 앵커를 거부 — 대신 kwaivgi/kling-v3.0-pro로 확장); 느린 정적 / 대화 중심 비트(5초 확장이 적절한 길이인 경우); 새 비트가 연속성이 아닌 하드씬 체인지인 경우(그러면 새로운 씬이므로 확장이 아니며 마지막 프레임 앵커가 필요하지 않음).
하위 문서 (필요 시 읽기)
| 파일 | 읽을 시점 |
|---|---|
| editor/render-pipeline.md | 프리플라이트, 컴포지션 작성, 프리뷰, 최종 렌더 |
| editor/vo-sync.md | VO에 맞춘 컷 — 스티치 → 전사 → 슬라이스; reverse-areverse + concat demuxer (에이전트 불변 규칙 #16) |
| editor/captions.md | captions.json을 자막 컴포넌트에 연결; 타이밍 상수를 작성하기 전에 자막 먼저 |
| editor/transitions.md | 크로스페이드 / 푸시 / 와이프 패턴 |
| editor/audio-mixing.md | VO + 음악 + SFX 레벨, 덕킹, 페이드 |
| editor/green-zone.md | 1080×1920 안전 영역 내 텍스트/오버레이 배치 |
| editor/hard-rules.md | 최종본을 위한 12개 항목 ffmpeg / 컷 규율 체크리스트 |
하위 태스크
| 하위 태스크 | 시점 | 하위 문서 |
|---|---|---|
preflight | "렌더링할 준비가 되었나요?" | render-pipeline |
generate-captions | VO 준비 완료, subtitles.json 없음 | subtitles + vo-sync (VO 맞춤 컷의 경우) |
author-composition | 매니페스트 완료, 컴포지션 없음 | render-pipeline + transitions + hyperframes |
preview | "브라우저에서 확인" | render-pipeline + bunx hyperframes preview |
final-render | 컴포지션 승인 | render-pipeline + hard-rules |
시작 시 읽는 항목
- 먼저
ralphy editor preflight <id>를 실행합니다. 지속 시간, fps, 코덱, 오디오 트랙, 총 클립 길이 대비 음악 간격, 시나리오-디스크 완전성을 단일 정식 검사합니다. 적색 시 종료 코드 1 반환 — 컴포지션 전에 수정하세요. 모든 프로젝트의 임시ffprobe루프를 대체합니다. (#034) - 그런 다음
ralphy editor trim-analyze <id>를 실행합니다.artifacts/videos/에 대해 gemini-3.1-pro-preview 비전 패스를 배치로 실행하여 클립별 데드타임 / 핫모먼트 / 제안trim_in_s/trim_out_s를 식별합니다. 결과를artifacts/analysis/summary.json에 집계합니다(mtime을 통해 멱등 — 변경된 클립만 재분석).--dry-run으로 계획 + 캐시 상태를 미리 볼 수 있습니다. kling/seedance의 약 1초 오버슛에 대한 정식 해결사입니다(#042). (#034) AGENTS.md— 불변 규칙(자동 Studio 없음, 스크립트 없음, ralphy render).- hyperframes playbook — HyperFrames 컴포지션 / 자막 / 전환 / GSAP / 레지스트리 참조 매뉴얼.
- art-director/pre-render-checklist.md — 핸드오프 전 아트 디렉터가 반드시 통과해야 하는 HARD 스냅샷 리뷰 게이트. 스냅샷이 디스크에 없이 여기에 도착했다면 아트 디렉터로 돌아가세요.
.ralphy/workspaces/<ws>/projects/<id>/scenario.json— 구조 및 타이밍..ralphy/workspaces/<ws>/projects/<id>/asset-manifest.json— 에셋 경로.
.ralphy/workspaces/<ws>/projects/<id>/index.html— 컴포지션..ralphy/workspaces/<ws>/projects/<id>/design.md— 브랜드 진실 공급원(HyperFrames 스킬 게이트).docs/green-zone.md— 텍스트 위치 지정용.
하드 규칙 (AGENTS.md에서 상속)
ralphy render <id>— 유일한 렌더 경로.bunx hyperframes render를 직접 호출하지 마세요(디버깅 제외).- 자동 실행 프리뷰 / Studio 없음.
hyperframes preview를 백그라운드에서 실행하지 마세요. 사용자가 프리뷰를 원하면 — 명확하게 포그라운드에서 실행하라고 알려주세요. - 자막은
ralphy generate captions(whisper-1 OpenRouter) 또는 단어 수준 타임스탬프를 위해bunx hyperframes transcribe사용. 컴포지션에 자막 오버레이가 있을 때 HF / Remotion 타이밍 상수를 작성하기 전에 실행하세요 (에이전트 불변 규칙 #16). 전체 VO 맞춤 컷의 경우 editor/vo-sync.md를 통해 먼저 전사하세요. editor/captions.md 참조. - 최종 렌더 전 품질 게이트 — 매니페스트의 모든 슬롯은
score >= 7또는 명시적 바이패스 동의가 있어야 합니다. - FFmpeg 후처리 —
cli/lib/ffmpeg-recipes.ts를 통해서만. editor/hard-rules.md(12개 항목) 참조. - 모션 그래픽 → 컴포지션 코드, 절대 비디오 모델 아님 (
04.0A.02). 아래 결정 트리 참조 — 애니메이션 텍스트, 운동 타이포그래피, 로워 서드, 애니메이션 차트, 애니메이션 UI 목업, 전환 와이프는 모두 HyperFrames HTML + GSAP으로 컴포지션됩니다. 이들은ralphy generate video를 통해 생성되지 않습니다. 그 경로는 실사 / 일러스트레이션 / 포토리얼 씬 — 모델이 생성하는 픽셀 콘텐츠(코드가 컴포지션한 모션 아님)를 위해 예약되어 있습니다. - 렌더에 대한 모든 사용자 피드백 턴을 반드시 기록
ralphy project log-prompt <id> --text "<그대로>" --stage <feedback|approval|critique|rejection>— 컷에 대한 반박, 자막 수정, 오디오 리믹스, "배송" 승인, 렌더 중단 비판. 시나리오 작가 플레이북과 동일한 MUST-log 규율(scenarist.md→ "사용자 프롬프트 로깅" 참조). 로그가 드문 경우 사후 분석 레이어는 사용자가 실제로 어떤 렌더 버전을 승인했는지 추측하게 됩니다. - Kling + seedance
--duration을 약 1초 초과.kwaivgi/kling-v3.0-pro및bytedance/seedance-2.0의 모든 클립은 요청된 지속 시간보다 약 1초 더 길게 생성됩니다(tokyo-y2k-001 측정: 5s/4s/9s → 6.04/5.04/10.04). 멀티 클립 컷을 컴포지션하기 전에 (a) 아트 디렉터 단계에서--duration을 1초 더 짧게 요청하거나, (b) 클립별 비전 트림 패스를 예산에 포함하세요. 전체 레시피와 수치는 editor/render-pipeline.md → 소스 클립 지속 시간 오버슛에 있습니다. 구조적 해결책은 향후ralphy editor trim-analyze동사에 있습니다(이슈 034).
픽셀 vs 코드 — 모션 그래픽 결정 트리 (04.0A.02)
씬을 ralphy generate video로 라우팅하기 전에 출력을 분류하세요:
| 패턴 | 경로 | 이유 |
|---|---|---|
| 실사 씬 (사람, 방, 액션, 날씨, 게임플레이 캡처) | ralphy generate video (i2v / t2v) | 모델이 코드로 위조할 수 없는 픽셀을 생성 |
| 포토리얼 스틸 + 시차 | ralphy generate image + HyperFrames GSAP 트윈 | 이미지가 에셋이고, 모션은 컴포지션 |
| 애니메이션 텍스트 / 운동 타이포그래피 / "단어가 강하게 들어옴" | HyperFrames 컴포넌트 + GSAP 타임라인 | 코드가 타이밍과 정확한 철자를 제어하고, 비디오 모델은 글자를 번지게 하고 폰트를 표류시킴 |
| 로워 서드 / 이름 카드 / 자막 | HyperFrames HTML + GSAP | 쉽게 매개변수화됨; 픽셀 경로는 생성할 때마다 폰트를 다시 렌더링 |
| 애니메이션 차트 / 데이터 시각화 | HyperFrames HTML + GSAP / Three.js | 코드가 데이터에 대한 진실 공급원; 픽셀 경로는 값을 환각 |
| 애니메이션 UI 목업 / 앱 화면 | HyperFrames HTML + GSAP | 픽셀 경로는 UI 어포던스를 발명하고, 결과는 AI 쓰레기처럼 읽힘 |
| 두 클립 간 전환 | HyperFrames 셰이더/크로스페이드 레지스트리 블록 | 두 클립이 에셋이고, 전환은 코드 레시피 |
| 파티클 / FX 오버레이 | HyperFrames CSS/SVG/Canvas/WebGPU | 반복 가능; 픽셀 경로는 비결정적 |
| Lottie 애니메이션 드롭인 | HyperFrames lottie 어댑터 | Lottie 파일이 에셋이고, 런타임이 결정적으로 재생 |
신호 단어 (bun run lint:templates에서 prompts.json의 알려진 위반자를 플래그 지정): "animated text", "kinetic typography", "lower third animates in", "chart animates in", "logo slides in", "transition wipe" → 이들은 HTML+GSAP 측으로 이동하며, 비디오 모델로 가지 않습니다. 만약 위 구문 중 하나를 ralphy generate video의 --prompt로 작성하고 있다면, 멈추고 대신 컴포넌트를 컴포지션하세요.
교차 참조: API 세부사항은 hyperframes를 읽으세요.
역사적 참고 사항 (Remotion).
92ef823이전 브랜치나STATIC_ROOT/composition-props.json을 언급하는 사후 분석을 뒤지고 있다면, 레거시 Remotion 규칙은 editor/render-pipeline.md → 레거시: RemotionSTATIC_ROOT레시피에 문서화되어 있습니다. 현재 HyperFrames 작업과 무관합니다.
핸드오프
preflight에서 누락된 에셋 발견 → art-director 플레이북으로 재생성.- 타이밍이 어긋남 (VO ≠ scenario.duration) → scenarist 플레이북으로 씬 재타이밍.
final-render후, 배치의 일부인 경우 → producer 플레이북.- 새로운 HyperFrames 패턴 → 코드 작성 전 hyperframes playbook + 관련 스킬 본문 (
gsap,lottie,animejs, …). - 재컴포지션/재생성 중 동일한 축에서 씬이 두 번 실패함 — art-director 플레이북 → 재생성 대신 씬 분할 을 참조하세요. 재프롬프팅을 중단하고, 동일한 슬롯 예산 내에서 마이크로 샷으로 분할하세요.