Communitygithub.com

simpletibr/simplicio-loop-marketing

HTML을 진리 소스로 하는 모션 컴포지션(키네틱 타이포그래피, 모션 인용 카드, 프로그래매틱 데이터 시각화 릴)을 HyperFrames 렌더러용으로 제작합니다. 라우팅 매트릭스가 확인한 비디오 제공자가 `hyperframes`일 때 사용됩니다.

simplicio-loop-marketing란 무엇인가요?

이 스킬은 HyperFrames HTML→MP4 렌더러용 모션 컴포지션을 제작하는 전문 도구입니다. 마케팅 엔진 디스패처가 비디오 제공자를 `hyperframes`로 결정했을 때 호출되며, `hyperframes-prompt-builder` 스킬이 전달한 브리프를 바탕으로 HTML 작성을 수행합니다. 주요 기능은 다음과 같습니다: - `data-start`, `data-duration`, `data-track-index` 속성을 가진 HTML 파일을 작성하여 타임라인 기반 애니메이션 구현 - GSAP을 사용한 진입/퇴장 애니메이션, 모든 타임라인은 `paused` 상태로 등록 - `Math.random()`이나 `Date.now()` 같은 비결정적 요소 금지, 대신 선언된 변수(`data-composition-variables`) 사용 - 장면 간 트랜지션 필수 적용 - 비디오는 음소거, 오디오는 별도 `<audio>` 요소로 관리 - `npx hyperframes lint`와 `npx hyperframes inspect`로 로컬 검증 후 렌더링 - 주간 KPI 릴, 모션 인용 카드, 프로그래매틱 쇼트 등 다양한 포맷 지원 - 최종 산출물로 `manifest.json`과 MP4 파일 생성 변수를 사용해 동일한 컴포지션을 재렌더링할 수 있으며, 클라이언트 디자인 토큰( `clients/<slug>/design.md`)을 준수해야 합니다. 실패 모드로는 디자인 토큰 누락, 린트/검사 오류, 오디오 길이 초과 등이 있으며, 이 경우 렌더링 전에 수정이 필요합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/simpletibr/simplicio-loop-marketing/tree/HEAD/.skills/hyperframes

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

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

문서

HyperFrames

HyperFrames는 HTML → MP4 렌더러(Apache 2.0)입니다. 컴포지션은 data-start, data-duration, data-track-index 속성을 가진 일반 HTML 파일입니다. 렌더러는 헤드리스 Chrome을 타임라인에 따라 프레임 정확도로 구동하고, 프레임을 FFmpeg로 전달합니다. hyperframes-prompt-builder 스킬이 마케팅 엔진 디스패처 진입점이며, 이 스킬은 저작 규칙을 담당합니다.

호출 시점

  • 라우팅(PROVIDERS.md 또는 프론트매터의 provider_override.video: hyperframes 통해) 결과 HyperFrames 제공자로 할당된 경우.
  • 작업이 motion-typography, data-viz-reel, programmatic-short이거나, 선언된 변수로부터 결정적 출력이 필요한 컴포지션(예: 새로운 숫자로 재렌더링해도 동일한 주간 KPI 릴)인 경우.
  • 승인된 정적 이미지(인용 카드, 캐러셀 슬라이드)를 타이포그래피 시스템 변경 없이 짧은 모션 작품으로 업그레이드해야 하는 경우.
  • 오케스트레이터가 재렌더링 가능한 아티팩트(동일 컴포지션, 다른 --variables, 바이트 단위로 동일한 기준선)를 필요로 하는 경우.

입력

  • composition_id: 문자열. 프로젝트 디렉토리 및 data-composition-id에 사용되는 짧은 슬러그.
  • aspect: 9:16 | 1:1 | 16:9 | 4:5.
  • duration_seconds: 정수. 전체 컴포지션 길이.
  • scenes: 배열. 각 항목: { id, start_s, duration_s, role: "hook" | "body" | "cta", copy?, asset_ref? }.
  • design_tokens: 객체. 브랜드 색상, 기본/보조 서체군, 간격 척도. 존재하는 경우 clients/<slug>/design.md에서 가져옵니다.
  • variables: 배열, 선택 사항. 호출자가 렌더 시 재정의할 수 있는 선언된 매개변수: { id, type, label, default }.
  • assets: 객체, 선택 사항. { video?, audio?, images[] } — 프로젝트 하위의 로컬 경로.
  • output_dir: 문자열. 렌더러가 MP4를 기록하는 경로(기본값: outputs/<client>/<date>/<piece-id>/).

프로세스

  1. 먼저 브랜드 컨텍스트를 읽습니다. clients/<active-client>/design.md(또는 전달된 디자인 토큰)를 로드합니다. 토큰을 알기 전까지 HTML 작성을 거부합니다. — 클라이언트에 디자인 파일이 없는 경우에만 저장소 기본값으로 대체합니다.
  2. 내러티브 아크를 명시적으로 계획합니다(장면, 리듬, 트랜지션, 비트). 마크업을 작성하기 전에 수행합니다. Hook은 처음 1.5초, 본문(body), CTA는 마지막에 배치합니다.
  3. 애니메이션 전에 레이아웃을 먼저 작성합니다. 최종 화면 레이아웃을 먼저 작성합니다 — 요소가 최종 위치에 배치됩니다. gsap.from()을 사용하여 해당 위치로 애니메이션합니다. 마지막 장면만 gsap.to() 퇴장을 사용할 수 있습니다.
  4. HTML을 구성합니다. 루트 <html>은 data-composition-id, data-width, data-height를 포함합니다. 각 클립은 id, data-start, data-duration, data-track-index를 포함합니다. <html>의 data-composition-variables(JSON 배열)로 매개변수화합니다. 런타임에 window.__hyperframes.getVariables()로 읽습니다.
  5. 모든 타임라인을 paused 상태로 등록합니다. const tl = gsap.timeline({ paused: true }); window.__timelines["<id>"] = tl; — 프레임워크가 재생을 제어합니다. 무한 반복, Math.random(), 시간 기반 로직, 비동기 타임라인 구성은 금지됩니다.
  6. 모든 장면 사이에 트랜지션을 적용합니다. 절단(cut)은 없습니다. 업스트림 references/transitions.md에 나열된 트랜지션(페이드, 와이프, 마스크, 셰이더)을 사용합니다.
  7. 비디오 및 오디오. <video>는 음소거되어야 합니다. 오디오는 별도의 <audio> 요소에 자체 트랙으로 존재합니다.
  8. 로컬에서 검증합니다: npx hyperframes lint를 실행한 후 npx hyperframes inspect(텍스트 오버플로우, 컨테이너 클리핑)를 실행합니다. 두 검사가 모두 통과한 경우에만 렌더링합니다. hyperframes-cli 스킬에 위임됩니다.
  9. 매니페스트를 생성합니다. MP4 옆에 manifest.json을 작성합니다: { composition_id, aspect, duration_seconds, variables_resolved, lint_pass, inspect_pass, render_settings }. CLAUDE.md의 완료 조건(Definition of Done)에 필요합니다.

출력

  • project_path: 문자열. HyperFrames 프로젝트 디렉토리 경로.
  • composition_html: 문자열. 작성된 index.html 콘텐츠(또는 project_path 아래의 경로).
  • render_args: 객체. npx hyperframes render에 전달할 플래그(--fps, --quality, --variables, --strict).
  • expected_artifact: 문자열. 렌더 후 output_dir 아래에 생성될 MP4 경로.
  • cost_estimate_usd: 숫자. 로컬 렌더 — 컴퓨팅 시간만; DRY_RUN인 경우 0으로 보고, 그렇지 않으면 --workers × duration에서 추정.

불가침 규칙

  • 모든 요소는 진입 애니메이션(gsap.from())이 있어야 합니다.
  • 모든 타임라인은 paused 상태로 시작하며 window.__timelines에 등록됩니다.
  • 컴포지션 로직에 Math.random(), Date.now(), setTimeout 기반 애니메이션은 금지됩니다.
  • 비디오 트랙은 음소거; <video>에 오디오를 내장하지 마십시오.
  • 클라이언트 카피가 변수일 수 있는 경우 마크업에 직접 포함하지 마십시오 — data-composition-variables에 선언하여 동일한 컴포지션을 새 작품에 재렌더링할 수 있도록 합니다.
  • outputs/ 아래의 렌더링된 MP4를 편집하지 마십시오. 대신 hyperframes render를 다시 실행하십시오.

예제

예제 1: 주간 KPI 릴 (programmatic-short)

입력: { composition_id: "kpi-weekly-w21", aspect: "9:16", duration_seconds: 12, scenes: [{ id: "hook", start_s: 0, duration_s: 2, role: "hook", copy: "Semana 21" }, { id: "metric", start_s: 2, duration_s: 8, role: "body" }, { id: "cta", start_s: 10, duration_s: 2, role: "cta", copy: "Veja o detalhamento" }], variables: [{ id: "leads", type: "number", label: "Novos leads", default: 0 }, { id: "delta_pct", type: "number", label: "Variação %", default: 0 }] } 출력: outputs/<client>/<date>/kpi-weekly-w21/ 아래의 프로젝트. index.html이 두 숫자 변수를 읽고 애니메이션합니다. render_args.--variables가 각 작품에 대해 변수를 해석합니다.

예제 2: 모션 인용 카드 (motion-typography)

입력: { composition_id: "quote-marcos-2026-05", aspect: "1:1", duration_seconds: 6, scenes: [{ id: "main", start_s: 0, duration_s: 6, role: "body", copy: "Coloque a sua marca onde os olhos já estão." }] } 출력: 활성 클라이언트의 타이포그래피 페어링을 준수하는 키네틱 타이포그래피 컴포지션. 마스크된 텍스트 진입과 마지막 프레임에서 부드럽게 유지됩니다.

실패 모드

  • design.md가 없고 디자인 토큰이 전달되지 않은 경우: 중단하고 질문합니다. 팔레트를 임의로 생성하지 마십시오.
  • npx hyperframes lint에서 오류 보고(data-composition-id 누락, 트랙 중첩, 등록되지 않은 타임라인): 수정될 때까지 렌더링 차단.
  • npx hyperframes inspect에서 장면 텍스트 오버플로우 보고: 시스템 최소값 이하로 서체 축소보다는 레이아웃 재배치를 선호합니다.
  • 오디오 트랙이 컴포지션 duration_seconds보다 긴 경우: 오디오를 자르고, duration_seconds를 늘리지 마십시오.
  • 컴포지션이 Math.random() 또는 벽시계 시간을 사용하는 경우: 선언된 변수 또는 시드 기반 결정적 생성기로 리팩터링한 후 렌더링합니다.

관련 스킬

  • hyperframes-cli: lint, inspect, preview, render 명령어. 저작 후 항상 호출됩니다.
  • hyperframes-prompt-builder: 마케팅 엔진 전문 스킬. 작품 브리프를 이 스킬이 기대하는 입력 형태로 변환하며, 매트릭스가 hyperframes로 확인될 때 video-prompt-builder가 호출합니다.
  • video-prompt-builder: 일반 디스패처.
  • qa-tech-specs: 렌더링된 MP4를 플랫폼 사양(종횡비, 길이, 안전 영역)에 대해 검증합니다.
  • compliance-<active client>: 렌더 후, 렌더링된 아티팩트와 변수에서 해석된 화면 카피에 대해 실행합니다.

업스트림 참고

전체 업스트림 스킬(컴포지션 패턴, 트랜지션 카탈로그, 오디오 반응형, 캡션, 데이터 인 모션): https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

관련 스킬