Communitygithub.com

leocosta/octopus

실행 중인 앱을 고품질의 동적 프로모션 비디오로 변환합니다. 실제 제품(Headless Chrome)을 데모/샌드박스 환경에서 구동하고, 깨끗한 스크린샷을 캡처한 후 HyperFrames + GSAP로 모션 디자인 컷(운동 타이포그래피, 시네마틱 푸시인, 스포트라이트 하이라이트, 폰 프레임, 스코어)을 합성합니다. 앱에 구애받지 않으며, 프로젝트별 promo.config와 비트 목록을 읽고 대상 앱의 디자인 시스템을 자동 추출하여 오버레이가 브랜드와 일치하도록 합니다. 16:9 마스터와 9:16 컷을 출력합니다.

octopus란 무엇인가요?

이 스킬은 **실제 제품을 사용한 동적 프로모션 비디오 제작**을 자동화합니다. 단순한 화면 녹화나 목업이 아닌, 실제 앱을 headless Chrome에서 구동하여 각 화면의 깨끗한 정지 이미지를 캡처한 후, HyperFrames(HTML→MP4)와 GSAP으로 모션 디자인을 합성합니다. 운동 타이포그래피, 시네마틱 푸시인, 스포트라이트 하이라이트, 폰 프레임, 음악 배경 등을 포함한 고품질의 광고 수준 비디오를 생성합니다. **주요 특징:** - **앱 독립적(App-agnostic):** 모든 웹 앱에 적용 가능하며, `extract-design.mjs`가 대상 앱의 디자인 시스템(배경색, 강조색, 폰트 등)을 자동으로 추출하여 오버레이가 브랜드에 맞게 조정됩니다. - **재현 가능(Deterministic & Re-runnable):** 화면 녹화 대신 HTML 기반 합성을 사용하므로 일관된 결과를 보장하며, CORS, 데이터 대기, 하이라이트 정렬 등 까다로운 문제를 사전에 해결합니다. - **플랫폼:** Claude Code, Cursor, Codex 등 AI 에이전트와 함께 사용하도록 설계되었습니다. Headless Chrome, ffmpeg, Node 20+가 필요합니다. - **워크플로우:** 데모 데이터 준비 → 앱 서빙 → 디자인 시스템 추출 → 화면 캡처 → 비트 정의 → 음악 선택 → 렌더링 → 하이라이트 정렬 검토 → 음악 믹싱 → 9:16 컷 생성의 단계별 파이프라인을 따릅니다.

지원 대상~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/leocosta/octopus/tree/HEAD/skills/motion-promo

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Motion Promo Protocol

개요

이 스킬은 실제 제품의 동적이고 광고 수준의 프로모션 비디오를 렌더링합니다. 화면 녹화나 목업이 아닙니다. 실제 앱을 headless 브라우저에서 데모 환경에 대해 구동하고, 각 화면의 깨끗한 정지 이미지를 캡처한 후 그 위에 모션 디자인 컷을 합성합니다: 운동 타이포그래피, 시네마틱 푸시인, 줌을 추적하는 스포트라이트 하이라이트, 모바일 화면용 폰 프레임, 리드미컬한 장면 컷, 음악 배경. 출력은 16:9 마스터와 9:16 세로 컷입니다.

이 스킬은 launch-feature의 렌더링 파트너입니다: launch-feature는 video-script.md(대본/비트를 산문으로)를 작성하고, motion-promo는 비트 목록을 완성된 스코어 비디오로 변환합니다. 둘 다 실행할 때는 체인으로 연결하세요 — launch-feature 스크립트 → motion-promo 비트.

HyperFrames(HTML→MP4)를 사용하고 화면 녹화를 사용하지 않는 이유: 결정적이고, 재실행 가능하며, 브랜드 제어가 가능하고, 실시간 탐색 캡처의 실패 모드를 우회합니다(규칙 참조). 앱은 정지 이미지 + 디자인 토큰을 생성하는 데만 사용됩니다. 모든 모션은 작성됩니다.

사용 시기

  • 랜딩 페이지 / 판매 페이지에 제품 데모 또는 히어로 비디오가 필요한 경우.
  • 기능을 발표하고 스크립트뿐만 아니라 렌더링된 비디오를 원하는 경우.
  • 실제 데이터로 데모/샌드박스 테넌트를 사용할 수 있는 경우.

사용하지 말아야 할 경우: 충실도가 중요하지 않은 내부 워크스루(원시 화면 캡처가 더 저렴함), 또는 실행 가능한 데모 환경이 없는 앱.

사전 요구 사항 및 비밀

API 키 / 비밀은 필요하지 않습니다. HyperFrames render는 키가 없으며(로컬 HTML→MP4), 폰트(Google Fonts) + 기본 음악(incompetech)은 공개 URL입니다. 유일한 자격 증명은 대상 앱의 데모 로그인이며, 이는 대상 저장소의 promo.config.mjs에 있습니다. 이 스킬에는 절대 없습니다. 인증은 플러그형 레시피입니다: authInject()는 주입할 값(로컬 스토리지의 토큰, 쿠키, API 키, 다단계 테넌트 선택)을 반환하거나, authFlow(page)는 대화형 로그인 UI(Azure AD / Entra, Okta, Google SSO)를 구동하고 엔진이 세션(로컬 스토리지 + sessionStorage + 쿠키, HttpOnly 포함)을 스냅샷합니다. SSO 자격 증명은 파일이 아닌 환경 변수에서 가져옵니다. Headless는 대화형 MFA를 통과할 수 없습니다 — MFA가 면제된 데모 계정(Conditional Access 예외) 또는 앱 비밀번호를 사용하세요.

시스템 종속성(직접 설치해야 함 — 스킬이 설치할 수 없음): Node 20+, 시스템 Chrome(google-chrome/Chromium), ffmpeg + ffprobe. 폰트/음악을 위한 네트워크 송신.

자동/주문형 종속성: hyperframes는 npx를 통해 주문형으로 가져옵니다(사전 설치 불필요). puppeteer-core는 스캐폴드된 npm 종속성입니다 — 시스템 Chrome을 사용하며 Chromium을 다운로드하지 않습니다.

설정: templates/를 video/<slug>/로 스캐폴드합니다(hyperframes.json 포함; meta.json은 compose-gen에서 생성). gitignore을 .gitignore로 이름을 바꾸고, npm install 및 npm run preflight를 실행합니다(Chrome, ffmpeg/ffprobe, puppeteer-core 확인; 누락된 경우 큰 소리로 실패). 단계별로 파이프라인을 실행하거나 npm run build를 실행합니다.

  • 대상 앱의 실행 가능한 데모/샌드박스.

입력

프로젝트별 모든 것은 대상 저장소에 있으며, 이 스킬에는 절대 없습니다:

  1. promo.config.mjs — 계약(templates/promo.config.example.mjs 참조). 앱 URL / 제공 방법, 인증 레시피, 데모 계정/테넌트, 출력 경로, 음악 선호도. 디자인 토큰은 자동 추출(2단계)되지만 여기서 재정의할 수 있습니다.
  2. beats.json — 정렬된 샷 목록(templates/beats.schema.json 참조). 각 비트 = 화면(경로 또는 캡처된 정지 이미지) + 선택적 하이라이트 대상 + 콜아웃 사본 + 뷰포트(데스크톱/모바일).

둘 다 templates/에서 대상 저장소의 video/<slug>/로 스캐폴드합니다.

프로토콜

대상 저장소의 video/<slug>/ 내에서 작업합니다. 각 단계에는 검증이 있습니다.

0. 데모 데이터 준비(먼저 수행 — 비디오의 성패를 좌우함)

데모/샌드박스 데이터는 일반적으로 현재 기간에 대해 오래되었거나 초기화됨(미지불된 현재 월 인보이스, 빈 퍼널) 상태여서 "R$0 수익"이 "자동 조종" 옆에 표시되어 적극적으로 메시지에 어긋납니다. 캡처하기 전에 각 비트에 건강한 숫자를 제공하는 멱등적이고 현재 날짜 기준 시드를 작성합니다(규칙 → 데모 데이터 0 참조). 각 비트가 표시할 메트릭을 쿼리하여 확인합니다.

1. CORS 허용 출처에서 데모 API에 대해 앱 제공

데모 API를 가리키는 앱을 빌드/제공합니다. 제공 출처는 API의 CORS 허용 목록에 있어야 합니다. 그렇지 않으면 모든 데이터 가져오기가 차단되고 화면이 비어 렌더링됩니다(규칙 → CORS 출처 참조). API의 허용 목록을 프로브하고 허용된 포트에서 제공합니다. 확인: 깊은 경로가 200을 반환하고 해당 출처에서 인증된 /api/... 요청이 2xx를 반환합니다.

2. 대상 앱의 디자인 시스템 추출

제공되고 인증된 앱에 대해 templates/engine/extract-design.mjs를 실행합니다. 계산된 스타일(페이지 배경, 버튼/링크의 기본/강조 색상, 제목 + 고정 폭 폰트 패밀리, 반경)을 샘플링하여 → design.tokens.json을 생성합니다. 이는 CSS 변수로 구성을 공급하여 운동 오버레이, 강조 및 폰트가 앱의 브랜드와 자동으로 일치하도록 합니다. 샘플링된 토큰이 잘못된 경우 검토하고 promo.config에서 재정의합니다.

3. 비트별로 깨끗한 정지 이미지 캡처

templates/engine/capture.mjs를 실행합니다. 인증(구성의 authInject 레시피를 통해)하고, 각 비트의 경로를 해당 뷰포트에서 탐색하고, 실제 데이터가 도착할 때까지 기다린 후(네트워크 유휴 상태만이 아님 — 규칙 참조) assets/<beat>.png로 스크린샷을 저장합니다. 각 정지 이미지에 로드된 콘텐츠가 있는지 확인합니다(크기 > ~10 KB, 대상 요소가 있는지 점검).

4. 비트 정의 + 구성 생성

beats.json을 채웁니다(경로/정지 이미지, 여전히 픽셀 공간의 하이라이트 {x,y,w,h,label} — 또는 {selector,label,padding?}, capture.mjs에 의해 자동 측정되며 수동 조정 좌표보다 선호됨, 콜아웃 {kicker,headline,sub}, 뷰포트, 지속 시간). templates/engine/compose-gen.mjs를 실행 → templates/composition.html에서 index.html로, 토큰 + 비트를 주입합니다. 간결하게 유지하세요: 비트당 3~5초, 하드 컷, 비트당 하나의 아이디어.

5. 무료 음악 트랙 가져오기

templates/engine/fetch-music.mjs를 실행 → assets/music.mp3. 기본 소스는 CC-BY(incompetech)입니다. CC-BY는 저작자 표시가 필요합니다(LP 설명에 기록). 가능하면 프로젝트 제공/CC0 트랙을 선호합니다.

6. 렌더링

npx hyperframes render → 사일런트 MP4. 먼저 hyperframes lint/inspect를 실행하세요. 캔버스 밖 장식/종료 애니메이션 오버플로는 노이즈로 처리하고, 실제 텍스트 클리핑은 수정 사항으로 처리합니다.

7. 프레임 검토 + 하이라이트 정렬 수정

각 푸시인의 시작과 끝에서 프레임을 추출하고 눈으로 확인합니다. #1 결함: 스포트라이트 하이라이트가 줌 중에 대상에서 벗어남 — 하이라이트 상자가 크기 조정된 컨테이너의 자식이어야 하기 때문입니다(규칙 → 하이라이트 추적 참조). 또한 확인: 빈/스피너 화면 없음, 모바일 화면이 폰 프레임 안에 깔끔하게 위치함, 사본이 읽기 쉬움.

8. 음악 믹싱

templates/engine/mux.mjs를 실행 → 최종 스코어 MP4(loudnorm, 페이드 인/아웃, -shortest). 출력에 오디오 스트림이 있고 비디오 지속 시간과 일치하는지 확인합니다.

9. 9:16 컷 파생

mux.mjs --reframe은 1080×1920 컷을 생성합니다. 중앙 자르기하지 마십시오(하단 고정 콜아웃이 잘림) — 전체 프레임을 보존하는 흐린 레터박스를 사용하세요. 모바일 비트는 이미 중앙에 위치합니다.

규칙(힘들게 얻은 교훈 — 다시 배우지 마십시오)

  • 하이라이트 추적. 푸시인하는 화면 위의 스포트라이트/하이라이트 사각형은 scale 변환이 적용되는 동일한 요소의 자식이어야 하며, 정지 이미지의 픽셀 좌표 공간에 있어야 합니다. 형제 요소로 있으면 이미지가 확대될 때 고정되어 있어 샷 전체에서 대상에서 벗어납니다.
  • 데모 데이터 0. 현재 기간은 종종 미지불/비어 있습니다. 멱등적(결정적 ID, 삭제 후 삽입)이고 current_date에 상대적인 시드로 해결하여 매 기간 자동 복구되도록 합니다.
  • CORS 출처. 로컬에서 제공된 빌드가 배포된 데모 API를 호출하는 것은 교차 출처입니다. API가 허용 목록에 있는 출처에서 제공하십시오(프로브) — 절대 브라우저 웹 보안을 비활성화하여 해결하지 마십시오.
  • 실제 데이터 대기. networkidle2는 앱의 데이터 요청이 도착하기 전에 해결될 수 있습니다 → 스피너를 캡처합니다. 스크린샷을 찍기 전에 성공적인 /api/... 응답(또는 대상 콘텐츠 선택자)을 추가로 기다리십시오.
  • 라이브 캡처보다 HyperFrames. CDP 스크린캐스트는 시각적으로 정적인 페이지에서 프레임 방출을 중단하고 공칭 fps 이하로 실행됩니다. HTML(GSAP)로 작성하면 둘 다 피할 수 있습니다. 라이브 녹화가 반드시 필요한 경우 커서를 흔들고 유효 fps로 인코딩하십시오.
  • 음악 라이선싱. CC-BY(incompetech/Kevin MacLeod)는 LP 설명에 저작자 표시가 필요합니다. CC0(Pixabay 등)는 필요하지 않습니다. 게시된 페이지에 라이선스가 없는 스크랩된 클립을 절대 배포하지 마십시오.
  • 세그먼트의 fps가 다른 경우 디먹서가 아닌 필터로 연결 — 디먹서는 자동으로 프레임을 드롭합니다.

디자인 시스템 추출(무관한 브랜딩)

구성은 브랜드 중립적입니다. extract-design.mjs는 CSS 변수를 대상 앱 자체에서 채웁니다: --bg(본문 배경), --accent(기본/링크 색상), --fg(제목 색상), --font-hero/--font-mono(계산된 폰트 패밀리), --radius. 이것이 하나의 스킬이 토큰을 수동으로 선택하지 않고도 모든 앱에 대해 브랜드에 맞는 프로모션을 생성할 수 있는 이유입니다. 항상 샘플링된 토큰을 검토하십시오 — 낮은 대비나 임시 색상이 가끔 잘못 샘플링될 수 있습니다. promo.config.design에서 재정의하십시오.

오류

  • 앱이 headless로 인증되지 않음 → 구성의 authInject 레시피가 잘못되었습니다. 첫 번째 탐색 전에 토큰이 localStorage/쿠키에 있는지 확인하십시오.
  • 화면이 비어 렌더링됨 → CORS 출처(1단계) 또는 데이터 대기(규칙)를 놓쳤습니다.
  • 캔버스 밖 오류 렌더링 → 실제 텍스트 클리핑은 더 작은 글꼴/줄 바꿈이 필요합니다. 장식/종료 오버플로는 노이즈입니다.
  • 하이라이트 정렬 불량 → 크기 조정된 컨테이너의 자식이 아닙니다(규칙).

마케터 역할과의 구성

사본에 마케터 역할을 사용하십시오: 비트당 키커, 헤드라인 및 가치 프레이밍은 프로젝트 음성(launch-feature의 voice.md / marketer-hooks.md가 있을 때)을 따라야 합니다. 화면상 사본은 비트당 키커 + 짧은 헤드라인 + 한 줄의 서브라인으로 유지하십시오.

관련 스킬