Vincentwei1021/video-shotcraft 딥다이브
— 코딩 에이전트에게 건네주면 내 제품의 영화 같은 홍보 영상을 통째로 만들어 주는 "스킬"

1프로젝트 한 줄 요약

가장 먼저 오해를 풀어야 한다. video-shotcraft는 당신이 여는 앱이 아니다. 클릭할 UI도, 타임라인 편집기도 없다. 이것은 AI 코딩 에이전트가 읽는 문서와 코드의 묶음이다. 당신이 Claude Code에게 "이 스킬로 내 제품 홍보 영상 만들어줘"라고 말하면, 에이전트가 저장소 안의 SKILL.md를 읽고, 거기 적힌 규칙과 레시피를 따라 스스로 Remotion 영상 프로젝트 코드를 짜서 .mp4를 뽑아낸다.

구체적으로 video-shotcraft가 담고 있는 것은 네 덩어리다. ① 샷 레시피 카드 106장(references/shots/) — 각 카드는 "이 컷은 무엇을 표현하나, 에너지는 어느 정도, 몇 초, 어떤 이징(easing)·타이밍을 쓰나, 흔한 함정은 무엇인가"를 적은 한 컷의 완결된 사용 설명서다. ② Remotion 구현 소스 97개(demos/) — 각 카드의 파라미터가 실제로 튜닝된 TSX 코드. ③ 완성 템플릿 "Ink Press"(template/) — 바로 렌더되는 36.2초짜리 검수 완료 홍보 영상. ④ 복사해 쓰는 자산(assets/) — 2.5D 페이지 카메라·자막·효과음 라이브러리.

이름은 video-shotcraft지만, 진짜 핵심어는 "검증된 모션 레시피를 에이전트에게 위임(delegate)한다"이다. 사람이 영상 편집기를 만지는 게 아니라, 사람이 방법론을 문서로 굳혀 두고 → AI가 그 문서를 읽어 실행한다는 구도가 이 도구의 정체성이자, 이 문서에서 배울 것을 관통하는 열쇠다.

2왜 주목받는가

2026년 개발자 생태계에는 세 가지 흐름이 있다. ① Claude Code·Codex를 확장하는 "에이전트 스킬" 생태계의 폭발(트렌딩에 skills 관련 레포가 줄줄이 오른다), ② 좋은 제품 홍보 영상은 외주 스튜디오에 수백만 원이 드는데 스타트업에는 그 예산이 없다는 현실, ③ AI가 만든 결과물이 "AI 슬롭(slop)"처럼 어색해 보이는 것에 대한 반발. video-shotcraft가 트렌딩에 오른 이유는 이 세 흐름이 정확히 겹치는 지점에 서 있기 때문이다.

차별점 ① — "그냥 만들어줘"가 아니라 "전문 방법론을 이식한다"

대부분의 AI 영상 도구는 프롬프트 한 줄 → 결과물이라 품질을 통제할 수 없다. video-shotcraft의 급소는 전문 모션 디자이너가 축적한 판단을 카드로 굳혀 에이전트에게 준다는 것이다. 각 샷 카드에는 "정상 속도에서 결론이 먼저 읽혀야 한다", "완료 후 최소 15프레임은 정지시켜라", "역사적 피드백은 전부 '더 느리게'를 가리켰다" 같은 실전에서 얻은 규칙이 파라미터 표와 함께 들어 있다. AI가 즉흥으로 만드는 게 아니라 검증된 레시피를 실행한다.

차별점 ② — 진짜 페이지를 재료로 쓴다 (스크린샷 → 2.5D 카메라)

이 스킬의 하드 규칙 하나: 실제 제품 페이지를 표현할 때는 반드시 진짜 스크린샷을 쓴다. 로컬 dev 서버를 띄우고, 헤드리스 브라우저로 전체 페이지를 2배 해상도 텍스처 + 요소별 추출 + 좌표표(layout.json)로 캡처한 뒤, PageCam이라는 2.5D 카메라 컴포넌트로 그 페이지 위를 밀고·당기고·기울인다. "가짜 UI를 손으로 그리는" 것은 비복제 장면(추상 오프닝·브랜드 컷)에만 허용되고, 그마저 출판급 품질이 안 나오면 스크린샷 경로로 돌아가라고 못박는다.

차별점 ③ — 눈으로 고를 수 있는 갤러리 (161개 모션 프리뷰)

샷 카드가 아무리 많아도 이름만으로는 뭘 고를지 모른다. video-shotcraft는 온라인 갤러리에 161개 모션 프리뷰를 올려, 사용자가 실제 움직임을 보고 검색·필터·비교한 뒤 원하는 컷 이름을 복사해서 에이전트에게 건네게 한다. "이 효과를 원해"를 말이 아니라 실물 샘플로 지목할 수 있다. 갤러리 자체는 python3 -m http.server로 로컬에서도 열 수 있는 정적 사이트다.

차별점 ④ — "완성 템플릿"이라는 가장 빠른 길

처음부터 창작하는 건 어렵다. 그래서 검수 완료된 Ink Press 템플릿(36.2초·10컷·페이퍼-잉크-앰버 스타일)을 통째로 넣어, "내 제품 스크린샷·문구·브랜드로 갈아끼우기만" 하면 같은 품질의 영상이 나오게 했다. README는 이걸 "가장 빠르고 신뢰할 수 있는 완성 경로"라고 부른다. 창작 자유도가 필요하면 자율 창작 모드로, 관여하고 싶으면 공동 창작 모드로 넘어간다.

3기술 스택 전체 지도

video-shotcraft 저장소를 처음 열면 헷갈린다. 영상 소프트웨어인가, 그냥 마크다운 문서 모음인가? 답은 "둘이 한 몸"이다. 이 저장소는 (A) AI가 읽는 방법론 문서, (B) 그 방법론을 실제로 구현한 Remotion/React 코드, (C) 영상에 쓰이는 효과음·캡처 스크립트 자산이 함께 산다. 이 셋을 구분하는 순간 전체 그림이 선명해진다.

세계 A — 지식 계층 (SKILL.md + references/)

코드가 아니라 마크다운으로 쓰인 "제작 두뇌"다. 에이전트가 읽고 판단하는 규칙·레시피가 전부 여기 있다.

세계 B — 렌더 엔진 계층 (demos/ + template/ + assets/lib/)

실제로 영상을 그리는 Remotion/React/TypeScript 코드다. 카드가 "레시피"라면 이건 "이미 튜닝된 실물 조리 과정"이다.

세계 C — 자산·캡처 계층 (assets/audio/ + assets/scripts/ + gallery/)

영상의 원재료다. 효과음(무료 상업 라이선스)·BGM 후보·페이지 캡처 스크립트·온라인 갤러리가 여기 있다.

4아키텍처 심화 분석

video-shotcraft의 모든 것은 하나의 설계 결정에서 나온다: "무엇을 만들지(의도)"와 "어떻게 만들지(구현)"를 분리하되, 반드시 짝지어 읽게 한다. 샷 카드는 의미와 파라미터의 표를 주고, 실제 튜닝된 진실은 demos/의 데모 소스에 있다. SKILL.md는 "카드만 보고 새로 짜지 말고, 반드시 참조 구현 TSX를 찾아 읽어라"라고 강제한다 — 그래야 조율된 이징·타이밍이 보존되기 때문이다.

4-1. 샷 카드의 해부 — 한 장에 담긴 여섯 블록

references/shots/의 카드는 정확히 같은 골격을 갖는다. 아래는 ai-stream-response(AI 응답이 차오르는 컷) 카드의 구조다.

이 구조가 핵심인 이유: 에이전트는 frontmatter만 훑어(에너지·시간) 컷을 고르고, 선택한 카드는 전문을 읽은 뒤, 참조 구현 TSX를 열어 실제 파라미터를 가져온다. 카드의 "함정" 섹션이 품질을 지키는 안전벨트 역할을 한다 — 예: "행 본문과 상태 아이콘이 같은 프레임에 떨어지면 정적 리스트처럼 보인다, 2~4프레임 지연을 둬라".

4-2. PageCam — "실제 페이지" 컷의 지반

가장 재사용 가치가 큰 컴포넌트. 평평한 전체 페이지 스크린샷 한 장을 받아 2.5D 카메라 키프레임으로 유영시킨다. 각 키(CamKey)는 화면 중심에 놓을 페이지 좌표(cx,cy)·줌·그리고 선택적 3D 기울기(rotX/rotY/rotZ)·원근(persp)을 담는다.

// assets/lib/PageCam.tsx — 2.5D 페이지 카메라의 키프레임 타입
export type CamKey = {
  frame: number;
  cx: number; cy: number;   // 1920x1080 뷰포트 중앙에 놓을 페이지 좌표
  zoom: number;             // 1 = 1 CSS px → 1 출력 px
  rotX?: number;            // 위쪽이 뒤로 눕는 기울기(테이블 보듯)
  rotY?: number;            // 오른쪽 가장자리가 물러남(왼쪽에서 본 것)
  persp?: number;           // 원근 강도(기본 1400; 작을수록 강함)
};
// 핵심 우아함: 어떤 키도 3D 필드를 안 쓰면 → 평평한 팬/줌으로
// 자동 강등돼 픽셀 단위로 동일하게 렌더된다(3D는 순수 선택적).

4-3. 데모 소스 — 튜닝된 파라미터의 "진실"

demos/ai-stream-response/StreamResponse.tsx를 보면, 카드의 파라미터 표가 어떻게 실제 코드가 되는지 드러난다. Remotion의 interpolate와 Easing.bezier로 프레임 구간을 값으로 매핑한다.

import {AbsoluteFill, Easing, Img, interpolate, useCurrentFrame} from 'remotion';

// 카드의 "行节拍 cue" 표가 그대로 상수 배열이 된다
const ROW_CUES = [42, 53, 63, 72, 80, 87, 93];
const ease = Easing.bezier(0.2, 0.75, 0.25, 1);
const clamp = {extrapolateLeft: 'clamp', extrapolateRight: 'clamp'};

const EvidenceRow = ({cue, title}) => {
  const frame = useCurrentFrame();
  // 행 본문: cue~cue+12 프레임에 걸쳐 0→1로 등장
  const body = interpolate(frame, [cue, cue + 12], [0, 1], {...clamp, easing: ease});
  // 상태 아이콘: 본문보다 3프레임 늦게(拖拽 계층) → 정적 리스트로 안 보이게
  const status = interpolate(frame, [cue + 3, cue + 11], [0, 1], {...clamp, easing: ease});
  // ... y이동·blur·opacity를 frame으로 계산해 style에 반영 ...
};

4-4. 세 가지 사용 모드 — 자유도 vs. 관여도의 축

SKILL.md의 첫 관문은 모드 판별이다. 완성 홍보 영상에는 서로 섞이지 않는 세 모드가 있고, 에이전트는 사용자가 이미 고른 게 아니면 먼저 최소한의 읽기전용 제품 점검을 한 뒤 세 모드를 제안한다.

4-5. 8단계 파이프라인 — "방향 결정이 비싼 단계 앞에서 끝난다"

자율 창작의 척추. 핵심 철학은 "방향성 논쟁은 첫 Remotion 코드 한 줄을 쓰기 전에 끝내라"이다 — 방향이 틀린 걸 컷 구현 단계에서 발견하면 장면 세트 전체를 폐기해야 하기 때문이다.

5디렉토리 구조 해부

구조를 보면 저자의 규율이 보인다. AI가 읽을 지식(references/), 그 지식을 구현한 코드(demos/·template/·assets/lib/), 영상의 원재료(assets/audio/·gallery/)를 뚜렷이 분리했다. 진입점은 언제나 SKILL.md 하나다.

구조가 말하는 이야기는 분명하다. 진짜 무게중심은 references/shots/의 106장 카드와 demos/의 튜닝된 구현에 있다. 카드가 "무엇을·왜"라면 데모가 "어떻게"이고, 둘을 짝지어 읽는 것이 이 도구를 쓰는 핵심 동작이다. template/은 그 조합의 완결된 실증이고, assets/lib/는 어느 프로젝트에나 복사해 재사용할 수 있는 부품 창고다.

6학습 포인트

배울 것 ① — "좋은 에이전트 스킬"은 어떻게 쓰는가

이 저장소는 잘 설계된 SKILL.md의 교과서다. 모드 판별로 시작하고, "언제 어느 문서를 읽나"를 표로 라우팅하며, 애매할 때만 질문하고, 확증 편향을 피하려 독립 검수를 강제한다. AI에게 복잡한 다단계 작업을 안정적으로 위임하려면 지시를 어떻게 구조화해야 하는지를 실물로 배운다. 자기만의 스킬을 만들려는 사람에게 최고의 참고 사례다.

배울 것 ② — Remotion으로 "코드가 곧 영상"

demos/의 TSX들은 Remotion 입문 실전 예제다. useCurrentFrame()으로 시간을 읽고, interpolate(frame, [입력구간], [출력값], {easing})으로 애니메이션을 만들고, <Sequence>로 컷을 잇고, <Audio>로 효과음을 프레임에 고정한다. "영상 편집을 코드로 한다"는 패러다임을 가장 실전적인 예제로 익힐 수 있다.

배울 것 ③ — 2.5D 카메라로 평면에 깊이 주기

PageCam.tsx는 CSS 3D 변환(perspective·rotateX/Y)과 키프레임 보간만으로 카메라 워크를 만드는 법을 보여준다. 무거운 3D 엔진 없이 스크린샷 한 장을 영화적으로 유영시키는 이 기법은, 제품 데모·설명 영상 어디에나 응용된다. "3D 필드가 없으면 평평한 팬/줌으로 자동 강등"되는 우아한 점진적 복잡도 설계도 함께 배운다.

배울 것 ④ — 결정적(재현 가능) 애니메이션

helpers/rand.ts의 시드 기반 의사난수(mulberry32)는 게임·시뮬레이션·영상 어디서나 중요한 패턴이다. "왜 Math.random()을 쓰면 안 되나"를 실제 렌더 파이프라인의 맥락에서 이해하면, 재현 가능성이 왜 정확성 요건인지가 몸에 남는다.

배울 것 ⑤ — 모션 디자인의 "문법"

106장의 카드는 그 자체로 모션 디자인 강의다. "한 컷에 하나의 동효만", "완료 후 최소 15프레임 정지(호흡)", "브랜드→동효 파라미터 추론표(에너지 축·톤 축)", "물리 은유로 가속도 만들기(카드 발기)", "riser→impact→sparkle 사운드 구문". 디자이너가 아니어도 좋은 움직임과 나쁜 움직임을 가르는 기준을 언어로 배운다.

배울 것 ⑥ — librosa 기반 비트 싱크

music-beat-sync.md는 오디오 신호에서 BPM·위상·드럼 강박을 추출하고, 그걸 영상 타임라인에 매핑한 뒤 렌더 결과로 역검하는 완결된 워크플로다. 음악 시각화·리듬 게임·영상 자동화에 관심 있다면 "측정→배치→검증" 루프의 좋은 본보기다.

7시스템/실행 요구사항

주목할 점은 "비용의 위치"다. 스킬 자체는 문서와 소스라 가볍지만, 진짜 부하는 에이전트가 페이지를 캡처하고, Remotion으로 수백 프레임을 렌더하고, 매 컷을 정지 프레임으로 자가 검수하는 반복 루프에서 나온다. 그래서 파이프라인이 "방향을 스타일프레임(정적 HTML)에서 먼저 잠그고", "컷별로 still만 뽑아 빠르게 확인"하도록 짜여 있다 — 비싼 전체 렌더를 최대한 아끼는 구조다. 방법론과 실행 비용이 한 몸으로 설계돼 있다.

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

이 순서를 밟으면 video-shotcraft는 단순한 "AI 영상 도구"가 아니라 Remotion 코드 영상·2.5D 카메라·모션 디자인 방법론·에이전트 스킬 설계를 잇는 살아있는 교과서가 된다. 각 주차 개념이 정확히 어느 카드·어느 데모 소스에 구현돼 있어, "이론 → 실제 코드" 왕복 학습이 가능하다.

10핵심 키워드 사전

11참고 링크

• GitHub 저장소: github.com/Vincentwei1021/video-shotcraft (Apache-2.0 · 저자 Wei Yihao)
• 온라인 갤러리: vincentwei1021.github.io/video-shotcraft — 161개 모션 프리뷰 검색·필터·카드명 복사
• TrendShift: trendshift.io/repositories/88911 (2026-07-25 Daily #14)
• Remotion: remotion.dev — React 기반 영상 프레임워크(별도 라이선스 유의)
• 빠른 시작: npx skills add Vincentwei1021/video-shotcraft 또는 에이전트에게 "이 스킬 설치해줘: (저장소 URL)"
• 템플릿 렌더: cd template && npm install && npx remotion render src/index.ts AiflPromo out/promo.mp4
• 핵심 문서: SKILL.md(진입점·규칙 9조) · references/pipeline.md(8단계) · references/shots/(카드 106장) · references/aesthetic-rules.md(QA)
• 대표 소스: assets/lib/PageCam.tsx(2.5D 카메라) · demos/*/*.tsx(참조 구현) · template/src/aifl/Main.tsx(Ink Press 타임라인)
• 배경 개념: Remotion·React 영상 렌더 · CSS 3D 원근 · 모션 디자인(이징·타이밍·hold) · 시드 난수(mulberry32) · librosa 비트 싱크 · 에이전트 스킬/플러그인 설계