remotion-broll

소재 엔지니어링 (실행 가능 파이프라인)

위치: 이것은 일하는 스킬이며, 규칙 문서가 아닙니다 — 판정, 명령, 검증을 한 번에 수행합니다. 완전한 규칙 원본은 remotion-assembly/references/broll.md에 있습니다 (4단계 우선순위 세부사항/사례별 소재 목록 의무/참조 규격). 충돌 시 해당 문서가 우선합니다.

호출 시점

• 구분 공방 2단계에서 '진짜 소재 구간' 판정 (제품 체험형 화면: 타이핑/생성/인터페이스/데모/조작)
• 조립 계획표 확정 전 소재 목록 수집 (사례당 제품 스크린샷 1장 또는 5초 화면 녹화, AI 자체 수집, 공급 대기 없음)
• 사용자가 화면 녹화/실제 촬영 소재를 제공하여 본편에 삽입해야 할 때

실행 파이프라인 (각 단계마다 검증, 단계별 진행)

① 등급 결정: 4단계 우선순위에 따라 경로 선택 — 사용자 자체 녹화 > 공식 비디오 > 웹페이지 스크린샷 > UI 시뮬레이션 카드. 공식 웹사이트/공식 채널이 있는 사례는 4단계로 바로 내려가는 것을 금지합니다.

② 수집

• 공식 비디오: yt-dlp --print "%(channel)s | %(title)s | %(duration)ss | %(id)s" "ytsearch8:<제품명> official" 으로 공식 채널 확인 → yt-dlp -f "bv*[height<=1080][vcodec^=avc1]+ba[ext=m4a]/b[vcodec^=avc1]/b" -o "public/broll/<이름>.mp4" <url> ([vcodec^=avc1]는 기본 AV1 필터링, HEVC와 동일하게 저장 금지, broll.md 2c 참조); 403 오류 시 UA / --cookies-from-browser / 프록시 순서로 시도.
• 웹페이지 스크린샷: node_modules/.remotion/chrome-headless-shell/*/chrome-headless-shell*/chrome-headless-shell --headless --screenshot=<out.png> --window-size=1920,1080 --virtual-time-budget=10000 <url>.

③ 진위 확인 (건너뛸 수 없음): file <파일> 로 'PNG가 실제로 HTML'인지 방지; 비디오는 ffprobe로 코덱 검증, HEVC는 우선 H.264로 변환 (검은 화면 방지); 스크린샷은 육안으로 읽어 로그인 벽/Cookie 팝업이 아닌지 확인.

④ 구간 선택: ffmpeg -vf fps=0.5 로 프레임을 추출하여 접촉 시트 생성, Read로 프레임별 그림 읽기, 내레이션과 의미가 동기화된 3-8초 렌즈 구간 선택 (입력→동작→대기→결과), 시작 및 종료 초 기록.

⑤ 삽입: Takeover 내에 <Sequence from={beat(x)}> + <OffthreadVideo muted src={staticFile('broll/….mp4')} startFrom={F(시작 초)}> (muted 필수 추가); Takeover은 PiP를 포함하지 않음 (사용자 판단); 스크린샷은 ShotCard/WindowCard에 삽입. 미디어 Sequence에는 premountFor≈fps를 추가하여 첫 프레임 검은 화면 방지, 단 해당 Sequence는 layout="none" 설정 금지 (래퍼 제거 후 premount失效); 외부가 return null로 컨테이너 가시성을 제어하는 경우, null은 premountFor 프레임보다 충분히 일찍 열려야 함 (seg06 실제 측정: 컨테이너 frame<enterAt-30 return null + 내부 premountFor={30}), 그렇지 않으면 부모 null이 프리로드 창을 제거하여 premount가 무효화됨.

⑥ 색보정 통일: 소재 레이어에 filter: brightness(0.9-0.92) saturate(0.95) 추가 (본편 밝기에 따라 미세 조정), 원색 그대로 사용은 패치 느낌 (오답 #18); Takeover 구간은 통일 설정 brightness(.92) saturate(.95) 사용 (seg06 실제 측정으로 고정, 구간별 육안 미세 조정 금지).

⑦ 편집 가공: 강조 부분 펀치인 (crop+scale로 주요 영역 확대, 주요 문장 글자 높이 ≥40px), 프레임 선택, 속도 변경; 인용 유형은 '전체 카드 2-3초 → 펀치인 주요 문장' 2단계 방식. Takeover 창은 소재 자연 길이에 맞추고, 자연 속도 우선 — 소재가 창보다 짧으면 창을 먼저 줄이고 크로스페이드 추가, 창을 채우기 위해 느리게 재생하지 않음; playbackRate<1은 인터페이스 스크롤 유형이고 창을 줄일 수 없을 때 최후 수단 (≥0.7). 하이라이트/자막이 입혀진 소재는 깨끗한 프레임 없음 → 마스크 공개 방식 (흰색 마스크 scaleX 1→0 으로 공개), 저장 시 SOURCES.md에 '마스크 공개 방식 적용' 등록 필수, broll.md 8.5 참조.

⑧ 구간 렌더링 검증: 해당 구간만 렌더링 --frames=a-b, 프레임 추출하여 확인: 패치 느낌 (색보정), 가독성 (≥16px), 라이딩 라인 (화이트보드 안전 영역), 내레이션과의 싱크.

저장 규칙

비디오 public/broll/; 스크린샷 public/assets/; 부족분은 조립 계획표에 기록하여 사용자에게 공급 요청. 저작권 기준: 공식 홍보 자료는 논평성 비디오에 사용.

인물 이름에는 반드시 초상화 (사용자 판결 2026-07-22, 철칙)

내레이션에서 특정 인물 이름을 언급할 때, 인물 카드의 아바타 원에는 가능한 한 해당 인물의 실제 사진을 배치하며, 이니셜 모노그램으로 대체하지 않음 (사용자 원문: "이런 이름을 언급하는 경우, 가능한 한 모두 이미지를 넣고, 네가 직접 인터넷에서 그 인물의 가장 대표적인 이미지를 찾아서 이 아바타 원 안에 넣어라"). 모노그램/아이콘은 사진을 구할 수 없을 때만 최후의 수단.

사진 수집 기준 (두 가지 유형 구분, 혼동 금지):

• 공인 (조브스, 머스크 등): AI가 직접 사진 수집, 단 명시적으로 상업적 사용이 허가된 출처에서만 수집 —首选 Wikimedia Commons의 CC BY / CC BY-SA / Public Domain 항목, 다음으로 공식 보도 자료. 검색 엔진 이미지를 함부로 가져오는 것 금지 (대부분 권리가 불명확한 상업 사진이며, 사용자 영상이 공개될 예정임). 사진 수집 후 public/broll/<영상명>/SOURCES.md에 등록 필수: 파일명 / 출처 URL / 라이선스 유형 / 사진 작가 저작자 표시. CC BY-SA는 엔딩 크레딧 또는 설명에 저작자 표시 필요 시, 인도 시 사용자에게 함께 알림.
• 비공인 (예: 내레이션에서 언급된 선생님, 친구, 동료): AI가 직접 온라인에서 사진을 찾아서는 안 됨 — 본인 확인 불가능, 라이선스도 없음. '이름 거론 소재' 프로세스로 사용자에게 제공 요청; 사용자가 제공하지 않으면 수제 명패/모노그램 유지, 인도 시 이유 설명.

이 규칙은 이전 기준을 대체: 초기 계획에서 '조브스 초상화 금지, 문자/아이콘 칩만 사용'이라는 작성은 저작권 우려로 인한 보수적 접근이었으나, 현재는 사용자 판결에 따라 '라이선스가 명확한 실제 사진'으로 변경되었으며, 저작권 문제는 라이선스 출처 선택으로 해결하고 사진을 아예 넣지 않는 방식은 사용하지 않음.

AI 생성 콜라주 B-roll (실제 소재가 없는 감정/은유 장면, 0722-01 정형화)

실제 소재 4단계에 해당하지 않으면서 감정적 또는 추상적 은유 화면 (반복, 수술, 스마트폰 사용, 주의력 분산 등 화면 녹화나 공식 비디오가 불가능한 구간)이 필요할 때 이 프로세스를 사용: Codex image_gen 으로 정지 프레임 생성 → Grok image_to_video 로 활성화 → 본편에 삽입. 실행은 gbro-collage-broll 스킬의 3중 게이트 (Gate1 은유 / Gate2 정지 프레임 / Gate3 비디오)를 따르지만, 리듬, 수용 방식, 구도 기준은 이 섹션을 따름 (gbro 기본값 덮어쓰기).

① 수용: 기본값은 우측 카드, 전체 화면 아님. B-roll은 3단 레이아웃의 우측 증거 카드에 배치 (16:9 비율 objectFit:contain 으로 전체 표시, 자르지 않음 — 사용자 판결 "등비율 축소"), 인물은 항상 제자리에 유지, 좌측에는 사이드바+타임라인 HUD 유지. 전체 화면 Takeover는 '소재와 병치할 정보가 전혀 없을 때'만 사용 (A-roll 철칙: 전체 화면은 인물을 제거할 수 있는 유일한 경우, 레이아웃 §2 참조). 수용 구성 요소는 src/koubo/scenes-0722-01/CollageBroll.tsx 참조 (카드 + OffthreadVideo, 테두리는 챕터 색상과 일치). 기본값으로 전체 화면을 사용하지 말 것 — 0722-01에서 전체 화면을 잘못 사용하여 사용자에게 거절당하고 재작업함.

② 리듬: 내레이션 한 문장에 한 장의 그림, 전환점은 리듬 제공, 프레임 내 공개에 의존하지 않음. 밀집된 내레이션에서는 각 장이 1-3초만 지속, assemble-from-empty 조립 애니메이션 금지 (빈 공간에서 조립하여 마지막 프레임에서야 완성 = 정보가 항상 반 박자 늦어, 말하기 속도 곡선과 충돌, 8개 비디오가 이로 인해 폐기됨). '활성화' 필요 — 정지 프레임의 구도는 0번째 프레임부터 완전해야 하며, Grok은 지속적인 미세 움직임만 추가 (종이 조각 흩날림/기어 회전/광대 미끄러짐/안개 흐름), 구도는 단 한 프레임도 변경 금지.

③ 정지 프레임 구도 규칙 (Codex image_gen):

• 비율 유형 (일괄 적용 시 실패): 객체 기반 은유 (병상/약알/달력/조각/책더미 — 인물은 요소일 뿐) 인물 높이 45-60%; 인물 기반 은유 (작업 중/단정히 앉음/버튼 누름/멍 때림 — 인물이 주체) 반드시 근경 65-80%, 원경은 바로 실패.
• 엄격한 금지선: 가짜 글자/읽을 수 있는 영숫자/로고/워터마크/UI; 네 가장자리 동시 확인 (Codex 자체 확인은 가장자리 가짜 글자 누락 가능, 주 세션에서 ffmpeg로 네 가장자리 잘라 확대하여 독립 재확인 필수).
• 신원 참조 이미지는 사용자 지정 (0722-01은 my-face-studio-default.JPG 사용); 표정은 서사에 따름, 저조 구간에서는 실루엣/고개 숙임/누운 자세를 많이 사용하여 어색함 방지, 웃지도 않고 괴로워하지도 않음.
• 각 배치 생성 후 md5 중복 제거, 파일 혼동 방지.

④ Grok 활성화 세 가지 함정 (오답 #39 상세):

• 해상도: grok CLI image_to_video의 resolution_name은 480p/720p 두 가지뿐, 1080p 없음 (2026-07-24 실제 측정 확인, 1080p 요청 시 720p로 다운그레이드됨); xAI API 측 grok-imagine-video-1.5는 1080p i2v 지원 (공식 문서). 전체 화면은 1080p 필요 = CLI 불가능: xAI API 1.5 사용, 실제 소재 또는 다른 생성기 (Sora 2 / Veo / Kling / Seedance; ChatCut MCP 내장 Seedance/Kling)로 전환. 명령어는 해상도를 명시적으로 고정해야 최대 단계 획득 — 지정하지 않으면 기본값 736×400 (더 흐림). 720p로 충분한지 여부는 수용 방식에 따라 다름: 카드/화면 속 화면 (표시 영역이 보통 <720px)은 720p로 충분하고 선명함; 전체 화면 1920×1080 채우기는 720p를 1.5배 확대하면 흐려짐. 완성 영상은 1080p이며, B-roll은 4K 불필요 (표시되지 않거나 크게 확대할 때만 필요).
• morph 증식: 깨지기 쉬운 요소 (기어/원형 고리/달력 칸) 프롬프트 끝에 잠금 제약 추가 (단일 원래 크기 유지/칸 수 및 색상 변경 금지/원형 고리 연속 유지).
• 강제 보완: '희소 요소+넓은 빈 배경+속 빈 인형+얼굴 조각'이 트리거되어 모델이 빈 공간을 채우고/구멍을 메우고/얼굴을 생성하여 구도를 변경하며, 금지 명령만으로는 부족.
• 호출: headless는 --always-approve --permission-mode bypassPermissions --max-turns 10 필요; 여러 agent가 cwd 공유 시 grok --continue 금지 (세션 혼동으로 A 영상이 B 경로에 기록됨); 인도 전 모든 파일 md5 중복 제거.

⑤ 환경 사전 설정: Codex 프로젝트는 쓰기 가능한 작업 공간에 생성해야 함 (로컬 = ~/Documents/remotion剪辑/ 아래). ~/hyperframes-projects/에 생성하면 image_gen은 성공하지만 저장이 거부됨; 다중 항목 작업은 항목당 하나의 agent로 병렬 발송, 하나의 agent가 모든 항목을 직렬로 처리하게 하지 말 것 (중간에 완료 판단하고 종료할 수 있음).