video-shotcraft：영화 같은 제품 영상 제작

독립적인 제작 능력 라이브러리: 152장의 샷 레시피 카드(demo 구현 소스 코드 및 동적 샘플 갤러리 포함), 검증된 전체 홍보 영상 템플릿, 재사용 가능한 컴포넌트 및 오디오 에셋, 6단계 워크플로우. 현재는 웹/데스크탑 제품 홍보 영상에 초점을 맞추고 있지만, 샷 카드 자체는 범용 모션 그래픽 어휘로 작동합니다. 개별 카드를 뽑아서 임의 영상의 단일 샷으로도 사용할 수 있습니다.

호출 시 먼저 모드 판단

전체 홍보 영상에는 서로 병합되지 않는 세 가지 모드가 있습니다. 자재 수집, 스토리보드 또는 구현을 시작하기 전에 사용자가 이미 명확하게 선택했는지 먼저 판단하십시오. 이미 선택한 경우 직접 실행하고, 반복해서 묻거나 다른 모드로 변경하지 마십시오.

템플릿 직접 사용: Ink Press의 기존 교체流程을 유지합니다. template/TEMPLATE.md를 읽고, 기존 샷 구조에 따라 대상 제품의 스크린샷, 카피 및 브랜드 정보를 교체합니다.
자유 창작: references/pipeline.md를 읽습니다. 에이전트는 사용자의 기존 요구사항과 프로젝트 내용에 따라 시각적 방향, 샷 매핑, 스토리보드, 자재 및 오디오를 자율적으로 결정하고, 완성된 영상까지 연속적으로 진행합니다. 제품 브리핑, 스타일프레임, 샷 매핑 또는 스토리보드 단계에서 사용자 확인을 기다리지 않습니다.
공동 창작: references/guided-free-creation.md를 읽습니다. 에이전트가 먼저 근거 있는 판단과 계획을 제시하고, 사용자가 순서대로 제품 브리핑, 요구사항 결정, 시각적 방향, 샷 매핑 및 최종 스토리보드를 확인합니다. 스토리보드가 승인된 후에 references/pipeline.md의 최종 자재 수집 및 제작 단계로 들어갑니다.

사용자가 프로젝트 경로, URL, 스크린 녹화 또는 페이지 스크린샷을 제공했지만 아직 모드를 선택하지 않은 경우, 먼저 최소한의 읽기 전용 제품 검사를 수행합니다: 제품 포지셔닝, 주요 기능, 페이지 시각적 요소, 전시 가능 상태 및 자재 위험성을 파악합니다. 비즈니스 프로젝트를 수정하거나, 민감한 데이터를 수집하거나, 비디오 코드를 작성하지 않습니다. 검사 후 세 가지 모드를 제시하고 다음을 설명합니다:

Ink Press가 해당 제품에 적합한지, 적합 및 부적합한 구체적인 근거
자유 창작과 공동 창작이 각각 적합한지, 어떤 제품의 시각적 단서를 유지할 것으로 예상되는지
에이전트가 추천하는 모드와 그 근거 및 장단점

그런 다음 명확하게 질문합니다: "위 제품 검사에 따라, 저는 ×× 모드를 추천합니다. 이 모드로 계속하시겠습니까?" 또한 사용자에게 https://vincentwei1021.github.io/video-shotcraft/ 에서 동적 샘플을 보고 비디오에 사용할 모션 효과 샷을 선택할 수 있음을 알려줍니다.

사용자가 검사할 수 있는 프로젝트나 페이지를 제공하지 않은 경우, 세 가지 모드를 간략히 소개한 후 질문합니다. Ink Press가 기성 템플릿이라는 이유만으로 기본적으로 추천하지 마십시오.

사용자가 템플릿을 선택한 경우: template/TEMPLATE.md를 완전히 읽고 원래 템플릿 프로세스에 따라 실행합니다.
사용자가 자유 창작을 선택한 경우: references/pipeline.md를 완전히 읽고, 에이전트가 자율적으로 진행하며 단계별로 확인을 기다리지 않습니다.
사용자가 공동 창작을 선택한 경우: references/guided-free-creation.md를 완전히 읽고, 해당 확인 노드에 따라 협업합니다.
사용자가 아직 결정하지 않은 경우: 여기서 멈추고 선택을 기다립니다. 사용자를 대신하여 기본 선택을 하거나 제작을 시작하지 마십시오.

예외 1: 사용자가 이미 Ink Press 템플릿을 지목한 경우, 템플릿 모드가 선택된 것으로 간주합니다. 예: "Ink Press 템플릿을 사용하여 내 제품 홍보 영상을 만들어 주세요." 이 경우 더 이상 묻지 말고, 바로 template/TEMPLATE.md를 완전히 읽고 템플릿 경로로 실행합니다.

예외 2: 사용자가 이미 특정 샷 카드를 사용하거나 참조하겠다고 명시한 경우, 샷 제약 조건이 이미 선택된 것입니다. 예: "deck-deal-flyin과 row-embed를 사용하여 이 비디오를 만들어 주세요." 또는 "spotlight-hero-card의 효과를 참조해 주세요." 이 경우 템플릿을 소개하거나 사용 여부를 묻지 마십시오. Gallery 이름 분석 규칙에 따라 지정된 샷을 확인하고, 각 카드를 완전히 읽은 후 카드의 "참조 구현"에 따라 정확한 데모 소스 코드를 찾습니다. 단일 샷은 대상 자재가 명확해진 후에 실행할 수 있습니다. 전체 홍보 영상의 경우, 자유 창작 또는 공동 창작 중 어떤 모드를 사용할지 아직 설명되지 않았다면 이 두 가지 모드에 대해서만 질문하고, 지정된 샷은 후속 제작 제약 조건으로 사용하며 자동으로 공동 창작과 동일시하지 않습니다.

네 가지 사용법

전체 홍보 영상 (템플릿 경로): 템플릿 영상과 매우 유사한 결과를 원할 경우 → template/TEMPLATE.md를 읽고, "제품 교체 가이드"에 따라 자재를 교체하며 샷별로 적용합니다.
전체 홍보 영상 (자유 창작): 새로운 스타일을 원하고 에이전트에게 자율적인 결정 권한을 부여할 경우 → references/pipeline.md를 읽고, 제품 이해부터 최종 검사까지 연속적으로 진행하며 중간 단계에서 확인을 기다리지 않습니다.
전체 홍보 영상 (공동 창작): 주요 결정에 참여하려는 경우 → references/guided-free-creation.md를 읽고, 제품 브리핑, 요구사항 결정, 시각적 방향, 샷 매핑 및 최종 스토리보드를 확인합니다. 승인 후 파이프라인의 최종 자재 수집 단계부터 계속 진행합니다.
단일 샷/단일 모션 효과: references/shots/에서 카드를 선택하거나(또는 사용자가 gallery/ 갤러리에서 고르도록 함), 카드 전체를 읽고 "참조 구현"에 따라 정확한 데모 소스 코드를 찾아 대상 자재에 적용합니다.

자유 창작과 공동 창작의 경계

자유 창작은 창의적 및 엔지니어링 결정을 에이전트에게 맡깁니다. 에이전트는 프로젝트 내용에서 제품의 중요 사항, 시각적 방향, 샷 매핑, 스토리보드, 자재 처리 및 오디오 계획을 동적으로 도출하고, 주요 판단을 기록한 후 직접 실행합니다. 안전하게 추론할 수 없는 필수 입력이 부족한 경우가 아니면 질문하지 않으며, 단계별로 중단하지 않고, 중간 산출물에 대한 사용자 확인을 요구하지 않습니다. 사용자의 기존 명확한 요구사항은 항상 제약 조건이며, 에이전트의 기본 선택에 의해 재정의될 수 없습니다.

공동 창작에서만 단계별 확인을 사용합니다. 기본적으로 references/guided-free-creation.md를 읽고, 각 라운드에서 재작업을 가장 많이 줄일 수 있는 1–3개의 질문만 하며, 제품 브리핑, 요구사항 결정, 시각적 방향, 샷 매핑 및 최종 스토리보드에서 중단하고 사용자 확인을 기다립니다. 사용자는 비즈니스 및 창의적 방향을 확인하고, 에이전트는 수집 방식, 구현 매개변수, SFX 핀 프레임, Remotion 프로젝트, 렌더링 및 기술 QA를 자율적으로 완료합니다.

공동 창작 중 사용자가 명시적으로 "전적으로 결정" 또는 "확인 건너뛰고 바로 진행"이라고 말하면, 자유 창작으로 전환하고 이 선택을 기록합니다. 자율적으로 진행한다고 주장하면서 단계별 확인을 계속 요구하지 마십시오.

기능-샷 매핑은 "어떤 동작 문법을 사용할 것인가"일 뿐, 전체 스토리보드가 아닙니다. 공동 창작에서 매핑이 확인된 후, 에이전트는 반드시 샷 순서, 지속 시간, 구체적인 화면, 페이지 상태, 자재 출처, 자막, 전환 및 SFX를 계속 제공해야 합니다. 전체 스토리보드가 확인된 후에야 최종 자재 수집 단계로 들어갑니다. 사용자가 Gallery에서 샷 이름을 복사할 때는 카드 이름 또는 "카드 이름 · 스타일 이름"만 제공하면 되며, 에이전트가 로컬 레시피 카드와 데모 소스 코드를 읽습니다.

핵심 철학

기존 페이지를 재현해야 한다면 반드시 실제 스크린샷을 사용해야 합니다. UI를 직접 만드는 것은 비-재현 시나리오로 제한되며, 품질과 표현의 명확성은 엄격한 기준입니다. 실제 제품 페이지를 표현할 때는 첫 단계로 로컬 dev 서버를 시작하고, 헤드리스 브라우저로 전체 페이지 2x 텍스처 + 요소 수준 분할 + layout.json 좌표표를 캡처합니다. 비-재현 시나리오(추상적인 오프닝/브랜드 섹션/독립적인 디스플레이 컴포넌트)에서는 UI를 직접 만들어도 되지만, 퍼블리싱 수준의 품질에 미치지 못하거나 시청자가 그것이 무엇을 표현하는지 이해하지 못할 경우 스크린샷 경로로 되돌아갑니다. 페이지 데이터는 위험도에 따라 처리합니다. 공개 데모 데이터는 제품 브리핑에서 명확히 확인된 경우에만 유지할 수 있습니다. 고객, 개인, 내부, 키, 실시간 또는 기타 민감한 데이터는 가상 또는 비식별화된 내용을 사용해야 하며, 수집 전에 고정(프리즈)해야 합니다.
전체 비디오의 시각적 언어는 반드시 제품 자체에서 성장해야 하며, 관련 없는 "홍보 영상 스킨"을 별도로 만들어서는 안 됩니다. 스타일프레임을 만들기 전에, 먼저 제품/웹사이트의 디자인 시스템, 소스 코드 또는 계산된 스타일에서 디자인 사양을 추출하고 기록합니다: 글꼴 패밀리와 굵기, 글자 크기 계층, 줄 간격/자간, 그리드, 간격, 정렬, 정보 밀도와 둥근 모서리, 그리고 배경/표면/본문/강조/상태 색상, 그라데이션 및 재질. 영상 내 모든 제목, 자막, 숫자, 텍스트 카드, 타이포그래피, 전환, 파티클, 조명 효과 및 기타 모션 효과 색상은 이 토큰 세트를 재사용하거나 제한적으로 확장해야 하며, 동시에 제품의 톤, 취향 및 질감과 일치해야 합니다. 템플릿 또는 샷 카드 경로를 사용할 때는 샷 구조, 동작 문법, 리듬 및 조정된 매개변수만 상속합니다. 글꼴, 타이포그래피, 색상 및 재질은 대상 제품에 맞게 다시 스키닝해야 합니다. 서사적 필요에 의해 제품의 시각적 요소에서 벗어나야 하는 경우, 공동 창작에서는 먼저 이유를 설명하고 사용자 확인을 받습니다. 자유 창작에서는 이유와 장단점을 디자인 사양에 기록한 후 계속 진행합니다.
영화 같은 느낌은 카메라 움직임, 빛과 그림자, 리듬, 소리의 조화에서 오는 것이지, 기술 과시용 애니메이션에서 오는 것이 아닙니다. 반복적으로 인정받은 것은: 단일 주인공의 완전한 동작 호(스포트라이트 → 줌인 → 플로팅 → 제자리), 물리적 은유로 구동되는 가속(카드 딜링), 측면 경사 궤도 오빗 클로즈업, 라이저 → 임팩트 → 스파클의 소리 구문입니다. 배치 요소의 등장은 움직임 자체에 의존해야 하며, 개별적으로 빛나게 해서는 안 됩니다. 장식용 글린트/범용 플래시는 저렴해 보이며, 단일 고품질 조명 효과는 허용됩니다.
각 샷은 하나의 모션 효과만 전달해야 합니다. 핵심 정보가 자리 잡은 후에는 반드시 숨 쉴 시간을 주어야 합니다. 하나의 애니메이션 기법(플라이인/스택/페이지 넘기기)은 전체 영상에서 단 한 번만 주인공이 되어야 합니다. 반복 샷, 반복 태그라인은 모두 삭제합니다. 리듬 선호도는 단방향입니다: 역사적 피드백은 모두 "느리게/멈춤"을 가리켰으며, "너무 느리다"는 단 한 번도 없었습니다. 브랜드 로고타입이 자리 잡으면 홀드 ≥1초, 배치 모션 효과 마무리는 0.5초 정지, 오프닝 주체 동작은 충분히 3초를 줍니다. 타임라인 작성 시 홀드/휴식에 미리 프레임 예산을 할당합니다.
강한 리듬의 BGM이 있는 영상은 모든 전환과 모션 효과가 반드시 비트에 맞아야 합니다. 사용자가 이미 음악을 선택한 경우 → 작업 시작 전에 리듬 분석을 먼저 수행합니다(librosa 그리드 피팅을 통한 실제 BPM/위상 + 킥/스네어/하이햇 3분류 드럼 히트 위치 파악). 그리드가 과도 커버리지로 검증 통과된 후에야 스토리보드를 작성합니다. 타임라인은 박자 기호 beatF(n)으로 작성하고, 드문 악센트는 실제 과도 현상을 고정하며 그리드 보간점을 사용하지 않습니다. 렌더링 후 완성된 영상에서 오디오 트랙을 추출하여 컷 포인트 오차가 ≤3프레임인지 역으로 테스트합니다. 비트 맞추기는 타이밍에 관한 것이지 진폭에 관한 것이 아닙니다. 전체 화면/카메라 레이어에 적용되는 비트 충격은 큰 슬램으로 간주되며, 전체 영상에서 ≤3곳(심미적 규칙 R4), 나머지 비트 포인트 모션 효과는 요소 레이어에만 적용됩니다. 방법론은 references/music-beat-sync.md를 참조하십시오. BGM이 포함된 영상의 최종 렌더링은 항상 두 가지 버전으로 제공됩니다: BGM 포함 버전 + BGM 미포함 버전(SFX 유지). bgm inputProp을 사용하여 동일한 타임라인에서 렌더링하여 사용자가 나중에 직접 음악을 편집할 수 있도록 합니다.
샷 카드 모션 효과를 사용하려면 먼저 Gallery 인덱스를 파싱하고 정확한 데모 구현 코드를 읽어야 합니다. 먼저 gallery/api/library.json을 사용하여 카드 이름과 style-key의 유효성을 검사한 다음, 카드 문서의 "참조 구현"에 따라 특정 TSX를 찾습니다. 레시피 카드는 의미와 매개변수 테이블을 제공하며, 정확한 데모 소스 코드가 조정된 매개변수의 진실(이징, 시간 값 비율, 마스크 타이밍, 알려진 함정을 피하는 작성 방법)입니다. 적응형 변경은 허용되지만, 카드에 "알려진 함정/약점"으로 표시된 매개변수는 품질을 낮출 수 없습니다. 품질 기준은 항상 유지하거나 높여야 합니다. 카드 이름과 이해를 바탕으로 새로 작성하는 것은 모든 조정된 결과를 포기하는 것입니다.
공동 창작은 저렴한 확인 항목을 앞으로 가져오고, 자유 창작은 동일한 판단을 실행 기록으로 남깁니다. 제품 브리핑 → 요구사항-실행 결정표 → 텍스트 방향 → 스타일프레임 → 샷 매핑 → 스토리보드의 순서는 변경되지 않습니다. 공동 창작은 단계별로 사용자에게 확인을 넘기고, 자유 창작은 에이전트가 자율적으로 선택하고 연속적으로 진행합니다. 두 모드 모두 방향이 정해지지 않은 상태에서 개별 샷 구현 단계로 들어가서는 안 됩니다.
검증은 전체 과정에 걸쳐 이루어지며 + 전달 전 독립적인 검토가 필요합니다. 단계 5부터 각 샷에 대해 npx remotion still로 정지 프레임 자체 검사를 수행하고, 각 수정 후 전체 영상을 렌더링하고 ffmpeg로 프레임을 추출하여 검토합니다. 전달 전에는 반드시 깨끗한 컨텍스트의 서브 에이전트를 보내 독립적인 최종 검토를 수행해야 합니다. 검토 입력에는 완성된 영상, 키프레임, 제품 브리핑, 요구사항-실행 결정표, 현재 모드에서 확인되거나 기록된 시각적 방향/스타일프레임, 기능-샷 매핑, Gallery 카드 이름/변형, 정확한 데모 TSX, Gallery 참조 샘플/추출 프레임, 최종 스토리보드, 선택된 샷 카드 및 심미적 기준이 포함됩니다. references/final-review.md에 따라 계획 일관성, 기능 완전성, 샷 충실도, 시각/오디오 기술 품질 및 데이터 보안을 동시에 확인하고, 각 항목에 대해 프레임 번호가 포함된 증거 보고서를 생성합니다. 제작자는 자신의 결과물에 대해 확인 편향을 가지므로, 첫 번째 검토를 사용자에게 맡겨서는 안 됩니다.
결정론적 렌더링: Date.now()/Math.random()을 금지합니다. 모든 의사 난수는 고정된 시드(mulberry32/해시, 시드는 인덱스에서 파생)를 사용하며, 프레임별로 재현 가능합니다.

워크플로우

자유 창작은 references/pipeline.md에 따라 단계 0부터 연속적으로 실행하며, 단계별로 사용자 확인을 기다리지 않습니다. 공동 창작은 먼저 references/guided-free-creation.md에 따라 단계 0–3(제품 이해, 시각적 방향, 샷 매핑 및 스토리보드 확인)을 완료한 다음, 파이프라인 단계 4(최종 자재 수집)부터 계속 진행하며, 질문을 반복하거나 재설계하지 않습니다. 단계 2–3에서는 references/shots/의 각 카드 앞부분(frontmatter)을 스캔하여 에너지 곡선에 따라 샷을 선택합니다. 단계 5–7에서는 지속적으로 references/aesthetic-rules.md를对照하여 자체 점검합니다. 단계 6에서는 references/sound-design.md를 읽습니다. 비트 동기화 영상은 전체 과정에서 references/music-beat-sync.md를 따릅니다.

모든 모드에서 완성된 영상이 전달된 후, 기본적으로 사용자에게 한 번 Jianying 프로젝트 파일(剪映에서 자막 내용/글꼴 크기/색상 변경, 샷 속도 변경/재정렬, 오디오 조정 또는 교체 가능) 내보내기가 필요한지 묻습니다. 사용자가 필요하거나 직접 내보내기를 요청한 경우 references/jianying-export.md를 읽고 실행합니다.

어떤 파일을 언제 읽을지

시점	읽을 파일
프로젝트 시작 및 모드 미정	최소 읽기 전용 검사 후, 세 가지 전체 홍보 영상 모드 제공 및 추천
자유 창작	pipeline.md (에이전트가 단계 0–7을 자율적으로 완료, 단계별 확인 없음)
공동 창작	guided-free-creation.md (단계 0–3 확인), 그런 다음 pipeline.md 단계 4부터 계속
사용자가 BGM 선택 완료	music-beat-sync.md (분석 후 스토리보드)
템플릿 경로 사용	template/TEMPLATE.md 전체
스토리보드 설계	sequences/ 브리지 템플릿 (전체 영상 골격 먼저 채우기); shots/ 모든 앞부분; 선택된 카드는 전체 내용 읽기
개별 샷 구현	해당 샷 카드 전체 + "참조 구현"에 따라 정확한 데모 소스 코드 전체 + assets/lib/ 해당 컴포넌트
사운드 디자인	sound-design.md + assets/audio/
검수	final-review.md + aesthetic-rules.md 전체 체크리스트 통과 (독립적인 서브 에이전트 실행)
완성 영상 전달 후 (Jianying 프로젝트 내보내기)	jianying-export.md + `jianying-export/` 플랫폼 모듈

에셋 사용 방법

assets/lib/ 컴포넌트: 새 프로젝트로 복사한 후 자유롭게 수정합니다(본 라이브러리를 import하지 않음). 목록: PageCam(2.5D 페이지 카메라 – 모든 "실제 페이지" 샷의 기초), ClipCard(외부 비디오 자재 mp4를 샷 카드 카메라 움직임骨架에 의해 구동될 수 있는 "카드 주인공"으로 감싸기, OffthreadVideo 교차 페이드 루프 포함 – 자재가 샷보다 짧을 때 무음으로 계속 재생), DigitRoll, FlashCut, Caption, FlatPanel, VerticalTicker(3D 무한 스크롤 월), helpers(rand/shake/camera/motion). FlatPanel 및 helpers/camera는 three + @react-three/fiber + @remotion/three 종속성이 필요하며, 나머지는 Remotion만 필요합니다.
assets/scripts/capture-template.mjs: 복사한 후 상단의 CONFIG(BASE/경로/선택기)를 변경합니다.
assets/audio/ 사운드 이펙트: 직접 복사하여 사용합니다(무료 상업용 라이선스, audio/ATTRIBUTION.md 참조). audio/bgm/은 리듬감 있는 BGM 옵션입니다. audio/sfx/<카테고리>/ 149개의 사운드 이펙트가 16개 카테고리로 분류되어 있습니다(transition impact riser camera ui text paper film light data scifi mech glass fluid crowd counter). 소리를 찾으려면 먼저 카테고리 디렉토리를 방문하십시오. 전체 목록은 sound-design.md를 참조하십시오. 단어집 sparkle의 디렉토리 이름은 light/입니다(sparkle/ 없음). S1은 음색을 금지하지만 동작은 금지하지 않습니다. 화면에 실제 클릭/스위치가 있으면 해당 효과음을 넣어야 하지만, ui/의 절반은 합성 피드백 사운드(tone/bleep/notification)이므로 하나씩 들어보고 전체 디렉토리를 허용해서는 안 됩니다(목록은 sound-design 3.3 참조). 긴 샘플과 가벼운 오디오 자재는 각각 특별 처리가 필요한 목록이 있습니다(sound-design 4.1).
demos/ 각 카드 구현 소스 코드: 대부분 자체 포함 그레이스케일 데모(일부는 demos/_fixtures/Fixtures.tsx의 가짜 UI 장면 컴포넌트를 import하고, 일부는 demos/_textures/의 실제 페이지 텍스처를 import). Remotion 프로젝트에 복사하여 실행할 수 있습니다. 일부 데모는 @remotion/motion-blur(CameraMotionBlur)를 사용하므로 npm i @remotion/motion-blur가 필요합니다. 목록은 demos/README.md를 참조하십시오.
template/ 완전한 렌더링 가능 프로젝트: npm install && npx remotion render src/index.ts AiflPromo out/promo.mp4.
jianying-export/ Jianying 프로젝트 내보내기 모듈: mac_draft.py(Mac Jianying 11.2 테스트 완료), windows_draft.py(업스트림 지원 경로에 따라 구현, 실제 기기에서 검증되지 않음), smoke_test.py(새 환경에서 먼저 실행할 최소한의 스모크 테스트). 프로세스, 타임라인 추출 및 트랙 구축 방법은 references/jianying-export.md를 참조하십시오. venv + pip install pyJianYingDraft가 필요합니다.
gallery/ 정적 갤러리: 사용자에게 온라인 버전 https://vincentwei1021.github.io/video-shotcraft/library.html 을 직접 제공하는 것이 우선입니다. 로컬에서 실행하려면 먼저 gallery/fetch-media.sh로 샘플을 가져오고(mp4는 git에 없음), cd gallery && python3 -m http.server 4178을 실행합니다. 152개 카드, 209개의 동적 샘플을 탐색/검색/다중 선택하여 카드 이름을 복사할 수 있습니다. 사용자가 샘플을 보며 샷을 선택하기에 적합합니다.

video-shotcraft：电影感产品视频制作