motion-diorama

Motion Diorama — 교육 영상 제작 스킬 (v3.0 · 공개 에디션)

핵심 원칙: 렌더 전에 확인하라, 렌더 후에 확인하지 말 것. 저렴하게 확인할 수 있는 모든 것(타임라인, 스틸 프레임, 텍스트 너비)은 반드시 먼저 통과해야 합니다. 풀 해상도 렌더링은 모든 게이트가 녹색일 때, 마지막에 한 번만 수행합니다.

이 파일은 핵심입니다. 모드별 시각적 세부 사항은 references/에 있습니다 — 모드 A는 mode-a.md, 모드 B는 mode-b.md, 모드 C는 mode-c.md (해당 비디오 모드에 맞는 것을 반드시 읽어야 합니다, 씬을 구축하기 전에). 테스트 시나리오는 evals/evals.md에 있습니다. scripts/의 스크립트는 있는 그대로 실행합니다 — 함수를 다시 작성하지 마십시오.

고정된 결정 사항 (스킬 제작자로부터 — 함부로 변경하지 마십시오; 이 스킬을 사용하여 변경하는 경우, 의식적으로 변경하십시오)

• 세 가지 활성 모드: 모드 A (풍경/역사 + 라이브 맵 변형), 모드 B (사물 분해 — 사물/기계 작동 방식), 및 모드 C (해부학 — 인체 시리즈). 모드는 각 비디오 시작 시 사용자가 프롬프트를 통해 선택합니다. 세션은 2단계 전에 해당 모드의 참조 파일을 읽습니다.
• 목표: 시청자층 구축. 기본 클로징 = 결론 (모드 A) / 콜백 (모드 C) + 페이드 투 블랙. 비디오 내에 시리즈 카드/레이블이 없고 화면에 단계 알약/위치 표시기가 없습니다 (2026년 11월 13일 v2.8 결정) — 시리즈 정체성은 캡션에만 있습니다. 콜 투 밸류는 가끔만, 주제가 적합하고 사용자가 해당 비디오에 대해 요청할 때만 — 필수 요소가 아닙니다. 판매 CTA는 금지됩니다.
• 숫자/데이터 = 하이브리드: 화면 판독값(DOM 오버레이)은 모든 숫자의 기본 시스템입니다. 예외: 비디오당 최대 하나의 황금색 3D 히어로 숫자, 해당 비디오의 최고 숫자에만 사용 — 그리고 동일한 숫자는 반드시 판독값/캡션으로도 표시되어야 합니다. 3D 버전은 시각적 강조일 뿐, 정보 전달자가 아닙니다.
• 최종 길이 30~60초, 오디오에 따름.
• 음성: 이 스킬은 음성에 무관합니다 — 사용자가 public/narasi.mp3에 제공하는 모든 MP3 내레이션을 사용합니다.
• 음악: public/musik.*에 있는 사용자 파일 — 음악을 선택하지 마십시오.
• 사실: 사용자 출처가 기본 참고 자료이며 충돌 시 우선합니다. 세션은 웹 검색으로 보완할 수 있습니다. 단, 최종 보고서에 출처를 명시하고, 권위 있는 출처(저널, 기관, 공식)를 우선하며, 확인되지 않은 주장은 반드시 불확실함으로 표시해야 합니다 — 추측을 사실로 제시하는 것은 금지됩니다.
• 단일 운영자: 한 명. 모든 결과물은 세션에 파일(스틸, 프리뷰, 최종)로 표시되어 다운로드 가능해야 합니다.
• 목표 리듬: 하루 1~2개 비디오. 효율성은 설계 요구 사항입니다 — 스캐폴드, 프리미티브, 컴포넌트를 재사용하십시오. 이미 있는 것을 다시 구축하지 마십시오.
• 게이트 — 잔류 모드는 공개 에디션의 기본값: 세션은 사용자 승인을 기다리지 않고 진행됩니다. 게이트 1(타임라인 요약) 및 게이트 2(연락처 시트 스틸)는 내부적으로 실행됩니다: 세션은 이 스킬의 문서화된 기준(검증기 통과 + QC 체크리스트)에 대해 자체 단계 결과를 평가하고, 자체적으로 발견 사항을 수정하며(씬당 최대 2회 수정 시도), 그런 다음 계속합니다. 결정 사항은 프롬프트의 결정 블록을 따릅니다(기본값: 너무 긴 내레이션은 최대 1.25배 속도로 가속; 확인되지 않은 사실은 보고서에 표시). 해당 블록에서 답변되지 않은 질문은 구축이 시작되기 전에 단일 메시지로 한 번에 제기됩니다 — 중간에 질문하는 것은 금지됩니다. 세션은 하드 블로커에 대해서만 중단될 수 있습니다: (a) 자료 누락 또는 손상, (b) 대본 생성 불가능, (c) 최대 속도 적용 후에도 내레이션이 30~60초 범위를 벗어남. 프롬프트에 "잔류 모드: 아니요"라고 명시된 경우, 클래식 게이트가 적용됩니다 — 두 번의 사용자 승인 (1단계 후 및 3단계 후)과 증거 기반 게이트 2 완화 사다리: 연속 3회 클린 합격 → 씬당 1스틸; 또 3회 → 입증된 씬 유형에 대해 선택 사항; 게이트 1은 절대 완화되지 않음; 한 번의 주요 시각적 수정은 전체 형식으로 되돌림; 모든 완화 사항은 최종 보고서에 기록됩니다.

엄격한 금지 사항

• AI 이미지/사진/2D/스프라이트/외부 텍스처/다운로드 모델을 씬으로 사용하는 것 금지. 모든 시각 자료 = 절차적 Three.js 3D 지오메트리.
• 레터박스 금지; 카메라는 기본 9:16.
• 움직임은 3D 공간의 카메라에서만 발생(실제 시차). 2D 이미지의 줌/팬으로 움직임을 시뮬레이션하는 것 금지.
• 사람은 얼굴이 없는 작은 어두운 실루엣만 허용. 모드 A의 주요 피사체는 클로즈업 금지 (풍경 히어로 동물/물체에 대한 최소 카메라 거리 8m) — 모드 C에서는 이 거리 규칙이 적용되지 않음: 히어로 장기가 실제로 프레임을 채움; 모드 B에서는 이 규칙이 컨텍스트 단계의 프레이밍에만 적용됨 — 실험실 단계의 히어로 물체는 실제로 프레임을 채움 (references/mode-b.md 및 references/mode-c.md 참조).
• 모든 씬에 대해 단일 렌더러, 단일 재질 세트, 단일 조명 장치.
• 단어 수/스토리보드로 길이를 추측하는 것 금지. 타이밍은 오디오에서만 가져옴 (타이밍 참조).
• useFrame(), Math.random(), Date.now(), 또는 프레임 누적으로 애니메이션하는 것 금지 — 모든 움직임은 useCurrentFrame() 및 고정 시드 난수 상수에서 파생되어야 함.

타이밍 — timeline.json이 유일한 진실 공급원입니다

1. public/narasi.mp3가 있는지 확인하십시오. 없으면: 중단하고 사용자에게 알리십시오. 오디오를 사용할 수 있기 전에 타이밍을 결정하지 마십시오.
2. 다음 계층 구조로 단어별 타임스탬프를 가져옵니다: a. 사용자가 제공하는 경우 TTS 기본 타임스탬프(예: 타임스탬프 포함 ElevenLabs) — 가장 정확합니다. b. 폴백 Whisper: BIG 모델만, language="id" 강제(자동 감지 금지), Whisper는 시간만 제공 — 문장 텍스트는 사용자의 공식 스크립트에서 가져와야 함 (인도네시아어 ASR은 숫자와 이름에서 쉽게 오류 발생).
3. docs/timeline.json을 정확히 다음 스키마로 구성하십시오:

{
  "fps": 30,
  "audio_duration_s": 40.20,
  "total_duration_s": 41.00,
  "sentences": [
    {"id": 1, "text": "…", "start_s": 0.00, "end_s": 3.68, "scene": 1}
  ],
  "scenes": [
    {"id": 1, "sentence_ids": [1, 2], "start_s": 0.00, "end_s": 6.44}
  ]
}

4. 매핑 규칙: 씬 경계 = 다음 씬의 첫 번째 문장의 시작 초; 매핑은 문장 내용 기반 — 길이를 채우기 위해 문장을 그룹화하는 것 금지; 실제 컷과 타임라인 간의 차이는 ≤ 0.3초.
5. python3 scripts/validate_timeline.py docs/timeline.json을 실행하십시오. 실패하면: 타임라인을 수정하고 반복하십시오. 실패 시 진행 금지.
6. 타임라인 요약(문장 수, 씬 매핑, 전체 길이)을 작성하고 다음 기준에 대해 스스로 평가하십시오 — 이것이 게이트 1입니다. 잔류 모드: 중단하지 마십시오. 요약을 최종 보고서에 저장하십시오. 클래식 게이트 모드: 사용자에게 표시하고 승인을 기다리십시오.
7. total_duration_s는 3060초여야 합니다. 범위를 벗어난 경우: 잔류 모드 — 프롬프트 정책 적용(너무 긴 경우 최대 1.25배 속도; 너무 짧은 경우 종료 간격 연장)하고 보고서에 기록하십시오. 여전히 범위를 벗어나면 하드 블로커입니다: 중단하고 보고하십시오. 클래식 모드: 사용자에게 보고하십시오 — 조용히 자르거나 패치하지 마십시오. 이유 없는 침묵은 금지됩니다. 종료 시 0.31초의 페이오프 간격은 허용되며 전체 길이에 포함됩니다.

스타일 잠금 (요약 — 모드별 세부 사항은 references/에 있음)

모드 A (세부 사항은 references/mode-a.md에 있음)

• 반현실적 스타일화된 3D 디오라마: 영화적인 따뜻한 팔레트, 단일 고정 황혼 조명 장치, 깨끗하고 매끄러운 표면, 단순화된 배경. 팔레트는 주제/계절에 맞게 조정 가능; 조명 장치와 재질은 불가능.
• 주제 제목: 움직이는 에스타블리싱 샷 위의 SERIF 대문자 타이포그래피. 후크 = 첫 1.5초 이내에 텍스트 + 음성 + 시각적으로 표시되는 첫 번째 내레이션 문장(질문/신화 반박/역설).
• 자막: 2~4단어 페이지 내 단어별 가라오케(한 단어 아님), 활성 단어는 선명하게, 키워드는 악센트 색상, 하단 안전 영역에 배치.
• 데이터 판독값: 내레이션이 숫자를 언급하는 정확한 순간에 카운트하는 애니메이션 카운터
  • 작은 레이블 + 포인터 라인; 후속 판독값은 동일한 스타일. 표시될 수 있는 유일한 3D 텍스트: 최고 숫자를 위한 하나의 황금색 히어로 숫자(고정된 결정 사항 참조).
• 카메라: 세그먼트 내에서 연속적인 여정; 논증 구조로서의 줌 계단; 사실 세그먼트 간의 하드 컷만, 약 0.1초 블랙 페이드 형태.
• 내레이션 구조: 시스템/흐름 주제의 경우 "하나의 흐름을 따르기" 사용; 하나의 비디오는 데모 세그먼트가 있는 하나의 주제에 대해 두 가지 사실을 포함할 수 있음.
• 클로징: 뷰티 샷 + 반복된 제목/시대 세리프 + 결론 문장. 블랙으로 페이드; 비디오 내 시리즈 레이블/카드 없음 (v2.8). (콜 투 밸류는 이 비디오에 대해 요청된 경우에만 해당.)

모드 B — 사물 분해 (세부 사항은 references/mode-b.md에 있음)

• 두 가지 세계 단계: 모드 A 스타일의 따뜻한 컨텍스트 디오라마(사물이 서식지에 온전히 표시됨) → 사물이 분해되는 어두운 기술 그리드 배경의 LAB 단계; 줌 연속(배경 페이드/아이리스)을 통한 전환, 하드 컷 없음.
• 하나의 절차적 히어로 객체 모델이 한 번 구축됨; 폭발도 및 단면도는 동일한 모델에서 파생됨.
• 제목 카드 없음 (후크 = 컨텍스트 샷의 첫 번째 내레이션 문장) 및 영구 HUD 없음 — 브레드크럼, 줌 카운터, 참조 미니맵은 제거됨 (연구 결정 + v2.8 방향). 연속 카메라, 리더 라인 레이블, 순간적인 단계 제목으로 탐색.
• 기본 단계: 컨텍스트 → 줌 + 객체 레이블 → 분해(부품 레이블 인도네시아어 + 영어 용어, 내레이션 순서대로 표시) → 단면(프로세스 애니메이션 + 프로세스 판독값) → 작동 중(단면 실행, 하나의 흐름 따르기, 프로세스 레이블, 의미론적 색상 코딩된 흐름 입자) → 결정적 메커니즘 매크로 → 카메라가 뒤로 물러날 때 한 줄 원칙 레이블 페이오프.
• 모드 B 클로징: 결론/원칙 문장 + 블랙으로 페이드; 시리즈 카드/레이블 없음 (v2.8).

모드 C — 해부학 (세부 사항은 references/mode-c.md에 있음)

• 디오라마 아님: 보케가 있는 어두운 보라색 공허에 떠 있는 하나의 광택 3D 히어로 장기; 하나의 장기 모델이 한 번 구축되어 모든 씬에서 사용됨. 기본 시리즈 이름 예시: "인체 시리즈" (자신의 시리즈 이름으로 변경).
• 흐름 색상 코드 절대적: 파랑 = 산소 부족, 밝은 빨강 = 산소 풍부 — 이 비디오나 시리즈 비디오 간에 절대 반전되지 않음. 세포 입자는 교환 지점에서, 정확히 해당 문장에서 색상이 변경됩니다.
• 필수 하나의 흐름 따르기 구조: 카메라는 전체 회로를 통해 하나의 패킷을 안내합니다. 장기 → 시스템 → 미시적 → 장기 → 전체 신체(실루엣)로 줌 계단.
• 후크 = 시청자의 실시간 참조 + 첫 번째 초부터 장기 시각적 비트와 동기화되어 실행되는 라이브 카운터. Serif 제목은 약 5~8초 후(후크 이후)까지 지연되고, 사실 주석이 이어집니다.
• 단계 알약 및 HUD 없음 (v2.8): 흐름 위치는 카메라 여정에서 읽음; 해부학 레이블 칩은 장기에 붙어 있으며 해당 부분이 활성화될 때 켜집니다.
• 모드 C 클로징: 애니메이션 최종 카운터 + 후크를 반영하는 콜백 문장; 블랙으로 페이드; 시리즈 카드/레이블 없음 (v2.8). 고어/그래픽 의학적 사실감 금지.

텍스트 규칙 (잘림 방지 — 수정 사유 1위)

• 읽어야 하는 모든 텍스트는 DOM 오버레이(Remotion 컴포넌트)이며, WebGL 캔버스 내의 텍스트가 아닙니다. 유일한 예외: 고정된 결정 사항의 하이브리드 3D 히어로 숫자 — 다른 3D 텍스트는 금지됩니다.
• 폰트가 로드된 후 @remotion/layout-utils의 measureText/fitText로 모든 텍스트를 측정하십시오. fontSize = min(모드 한계, 피트 결과); 최대 너비는 프레임 너비의 90%; 모든 면에서 5% 안전 여백; 플랫폼 안전 영역 존중(중요 텍스트의 경우 위쪽 ±250px 및 아래쪽 ±310px 피함).
• 텍스트가 가독성 최소 크기에도 맞지 않으면: 두 페이지/줄로 분할하십시오 — 읽을 수 없을 정도로 줄이거나 잘린 채로 두지 마십시오.
• 대비: 밝은 배경의 밝은 텍스트에는 어두운 윤곽선/그림자가 필요합니다.
• 리더 라인 레이블도 동일한 규칙을 따릅니다.

오디오

• 내레이션이 마스터 클록입니다: 모든 씬 경계, 캡션, 카운터, 카메라는 docs/timeline.json을 읽습니다 — 두 번째 타이밍 소스는 없습니다.
• 사용자 파일의 음악은 내레이션 아래에 베드로 설치됩니다(단순 덕킹; 단어를 덮지 않도록). 사용자로부터 음악 파일이 없는 경우: 음악을 만들어내지 마십시오 — 사용자에게 알리십시오.
• 최종 출력은 -14 LUFS로 정규화되고, 피크는 ≤ -1dB입니다.

제작 워크플로 (순서를 건너뛸 수 없음)

• 0단계 — 스캐폴드: 기존 프로젝트 스캐폴드를 사용하십시오. 렌더러, 카메라 장치, 스타일 잠금, 프리미티브는 다시 작성하지 않습니다. 리포지토리에 Remotion 프로젝트가 아직 없는 경우(첫 번째 프로덕션): 이 스킬 패키지 리포지토리의 starter/ 폴더에서 스캐폴드를 구축하십시오 (작동하는 것으로 입증된 정확한 버전의 종속성 사용), 그런 다음 기존 스캐폴드로 취급하십시오.
• 1단계 — 타임라인: 타이밍 섹션에 따라 → 검증기 통과 → 게이트 1 (잔류 모드에서는 내부적으로; 클래식 모드에서는 사용자 승인).
• 2단계 — 씬 구축: timeline.json과 이 비디오 모드의 참조 파일(references/mode-a.md, references/mode-b.md 또는 references/mode-c.md)을 읽습니다.
• 3단계 — 스틸 게이트: 씬당 3개의 스틸(씬 시작/중간/끝) + 연락처 시트를 렌더링합니다. 잔류 모드: 이 모드의 QC 체크리스트에 대해 연락처 시트를 평가하고, 스틸 단계에서 발견 사항을 수정하며(씬당 최대 2회 시도), 그런 다음 계속 진행합니다 — 사용자를 기다리지 마십시오. 연락처 시트 + 평가 목록을 최종 보고서를 위해 저장합니다. 클래식 모드: 표시하고 사용자 승인을 기다리십시오. 스틸 단계에서 수정하십시오 — 비디오에서 수정하는 것보다 훨씬 저렴합니다.
• 4단계 — 프리뷰 + 자체 QC: 0.5 스케일 프리뷰를 렌더링하고, 자체 결과에 대해 아래 QC를 실행하고, 보고하기 전에 모든 발견 사항을 수정하십시오(변경된 씬만 다시 렌더링).
• 5단계 — 최종: 풀 해상도를 한 번 렌더링하십시오. bash scripts/check_output.sh out/<slug>-final.mp4를 실행하십시오. 세션에 파일 + QC 보고서를 표시하십시오.

빠른 렌더링 (고정된 파이프라인)

• 씬별 렌더링: out/scenes/scene-N.mp4; FFmpeg concat -c copy로 병합 (코덱/해상도/FPS 매개변수는 모든 씬에서 동일해야 하며, 그렇지 않으면 병합이 깨짐).
• --concurrency = 세션의 CPU 코어 수(nproc 확인), 기본값 사용 금지.
• 프리뷰는 항상 --scale=0.5; 풀 해상도 1080×1920은 5단계에서만.
• 프레임당 비용을 낮게 유지하십시오: 기본 지오메트리, 요소에 대한 인스턴싱