Communitygithub.com

ChuchoMonster/claude-code-skills

URL 입력만으로 브랜드 설명/홍보 비디오를 제작하는 엔드투엔드 멀티테넌트 파이프라인입니다. 브랜드 아이덴티티 추출, 스크립트 작성, 음성·AI 아바타·B-roll 이미지·배경 음악 생성, HyperFrames 조립 및 렌더링을 자동화합니다.

claude-code-skills란 무엇인가요?

이 스킬은 URL 하나만 제공하면 완성된 브랜드 설명/홍보 MP4 비디오를 생성하는 완전 자동화 파이프라인입니다. ColdStart(coldstartb2b.com)에서 검증되었으며, 최소한의 설정만으로 모든 B2B 브랜드로 확장 가능합니다. 'Hyper Frames for <url>', 'make a Hyper Frames video for <brand>', 'Hyper Frames promo for <url>', 'explainer video for <brand>', 'Hyper Frames <url>' 등의 트리거 문구로 호출할 수 있습니다. 파이프라인은 11단계로 구성됩니다: URL에서 브랜드 정보 추출(brand-book 스킬 활용), 웹사이트 분석 및 비즈니스 이해, 스크립트 작성(2.7단어/초 기준), 11Labs TTS 음성 생성, HeyGen 아바타 생성 및 크로마키·패딩 처리, KIE.AI Nano Banana 2로 B-roll 이미지 생성, 11Labs Music 배경 음악 생성, HyperFrames로 최종 조립·렌더링까지 전 과정을 자동화합니다. 각 단계는 반복 가능하며, 보통 1~3회의 반복으로 최종 결과물을 완성합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ChuchoMonster/claude-code-skills/tree/HEAD/skills/hyperframes-pipeline

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

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

문서

HyperFrames 파이프라인 — 멀티테넌트 브랜드 설명 비디오

URL 하나를 입력하면 완성된 브랜드 설명/홍보 MP4를 생성하는 엔드투엔드 파이프라인입니다. ColdStart(coldstartb2b.com)에서 구축 및 검증되었습니다. 최소한의 테넌트별 설정만으로 모든 B2B 브랜드로 확장 가능하도록 설계되었습니다.

호출 시점

  • 사용자가 "Hyper Frames" / "hyperframes" + URL 또는 브랜드명을 언급할 때
  • 사용자가 특정 비즈니스에 대한 설명/홍보 비디오를 요청할 때
  • 사용자가 "<브랜드> 비디오 만들어줘" 또는 유사한 표현을 사용할 때
  • 사용자가 "<새 URL>로 해보자"고 말할 때

필수 환경 변수 (<프로젝트-디렉토리>/.env)

KIE_AI_API_KEY=...        # KIE.AI를 통한 Nano Banana 2 + Seedance 2
HEYGEN_API_KEY=...        # HeyGen 아바타 생성
ELEVENLABS_API_KEY=...    # 11Labs 음성 + 음악

프로젝트 구조

<프로젝트-디렉토리>/
  brands/
    <브랜드>/              # 브랜드별 디렉토리 (brand-book이 생성)
      brand.json
      colors.md
      typography.md
      voice-tone.md
      reference.png
  template-16x9/          # 활성 컴포지션 (단일 작업 디렉토리; 브랜드별로 에셋 교체)
    index.html
    styles/
      brand.css           # 브랜드 인터페이스 — 브랜드별 CSS가 있는 유일한 파일
      template.css        # 브랜드에 무관한 모션
      layouts.css         # 10가지 레이아웃 시스템
    assets/
      voice.mp3           # 11Labs 출력 (패딩 처리됨)
      avatar.webm         # HeyGen 출력 (크로마키 + 패딩 처리됨)
      music.mp3           # 11Labs Music 배경 음악
      broll-*.png         # Nano Banana B-roll
    renders/

멀티테넌트 프로덕션의 경우, 향후 Stage 0에서 template-16x9/를 브랜드별로 복사해야 합니다. 현재는 렌더링 시 에셋을 제자리에서 교체합니다.


파이프라인 단계

1단계 — 브랜드 추출

대상 URL에 brand-book 스킬을 호출합니다. 다음 파일을 생성합니다:

  • brands/<브랜드>/brand.json — 팔레트, 타이포그래피, 음성/어조 요약
  • brands/<브랜드>/css-variables.json — 라이브 사이트의 모든 CSS 변수
  • brands/<브랜드>/reference.png — 홈페이지 스크린샷

모든 후속 단계를 구동하는 두 가지 고정 색상을 추출합니다:

  • bg: 브랜드의 배경색 (일반적으로 거의 검은색, 예: #050508)
  • accent: 브랜드의 시그널 색상 (일반적으로 채도가 높은 색상, 예: #8b9cf7)

이 색상들은 B-roll 프롬프트와 styles/brand.css에서 치환됩니다.

2단계 — 사이트 읽기, 비즈니스 이해

WebFetch를 사용하여 홈페이지 + 주요 페이지(서비스, 팀, 가격, 소개)를 읽습니다. 다음을 종합합니다:

  • 판매하는 제품/서비스
  • 대상 고객 (ICP)
  • 가장 강력한 1~2가지 차별점
  • 원하는 CTA (상담 예약, 무료 체험 시작 등)

이 정보가 스크립트의 내용이 됩니다.

3단계 — 스크립트

요청된 길이에 맞춰 스크립트를 작성합니다. 속도 규칙: 음성 기준 초당 약 2.7단어 (multilingual_v2 템포). 따라서 22초 ≈ 60단어, 45초 ≈ 120단어, 60초 ≈ 160단어입니다.

구조 (22초 기준 5장면 템플릿, 더 길면 비례적으로 확장):

  1. 훅 (전체 길이의 1015%) — 강력한 36단어 라인
  2. 본문 1 — 문제 (약 30%) — 무엇이 잘못되었는지 / 병목 현상
  3. 본문 2 — 통계 또는 증거 (약 15%) — 그 규모 (B-roll용 템플릿 2 차트 사용)
  4. 본문 3 — 우리의 접근 방식 (약 25%) — 차별점
  5. 종료 / CTA (약 15%) — 초대 + 브랜드 워드마크

더 긴 비디오(45초 이상)의 경우, 본문 1과 본문 2 사이에 추가 본문 장면을 삽입합니다 (예: "본문 1a — 특정 pain point", "본문 1b — 무조치 시 비용").

11Labs eleven_multilingual_v2를 위한 운율: 구두점이 템포를 결정합니다 (쉼표 = 미세 일시 정지, 마침표 = 완전 일시 정지, 대시 = 박자). SSML이나 감정 태그는 사용하지 마십시오 — multilingual_v2는 이를 지원하지 않습니다. 자연스러운 구두점을 가진 대화체 산문만 작성하면 됩니다.

추적 가능성을 위해 스크립트를 template-16x9/script.txt에 저장합니다.

4단계 — 음성 (11Labs)

eleven_multilingual_v2로 11Labs TTS를 호출합니다. 기본 음성: <사용자-11labs-음성-id> (이 값을 사용자의 11Labs 라이브러리 음성 ID로 설정하거나, 사용자가 지정했거나 브랜드가 선호하는 음성으로 설정 — 불명확하면 질문).

source .env && curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/<사용자-11labs-음성-id>" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"<스크립트>","model_id":"eleven_multilingual_v2"}' \
  --output assets/voice_raw.mp3

FFmpeg로 볼륨을 92%로 후처리 (파이프라인 표준):

ffmpeg -y -i voice_raw.mp3 -af "volume=0.92" -c:a libmp3lame -b:a 192k voice.mp3

5단계 — 아바타 (HeyGen)

talking_photo_id (Look ID)를 선택합니다. 기본값은 사용자 자신의 HeyGen 계정에 있는 Look으로 설정하세요: <사용자-heygen-talking-photo-id>.

항상 use_avatar_v_model: true를 캐릭터 레벨에서 설정하세요. Look이 V에 등록되지 않은 경우 HeyGen은 자동으로 Avatar IV로 대체됩니다 (Avatar IV 출력은 정상 렌더링됨).

음성 업로드 → talking_photo 렌더 제출 → 폴링 → 다운로드 → 크로마키:

# 오디오 업로드
AUDIO_ID=$(curl -s -X POST "https://upload.heygen.com/v1/asset" \
  -H "X-Api-Key: $HEYGEN_API_KEY" -H "Content-Type: audio/mpeg" \
  --data-binary @assets/voice.mp3 | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['id'])")

# 렌더 제출
VID=$(curl -s -X POST "https://api.heygen.com/v2/video/generate" \
  -H "X-Api-Key: $HEYGEN_API_KEY" -H "Content-Type: application/json" \
  --data-binary @- <<EOF | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['video_id'])"
{
  "video_inputs": [{
    "character": {
      "type": "talking_photo",
      "talking_photo_id": "<사용자-heygen-talking-photo-id>",
      "use_avatar_v_model": true
    },
    "voice": { "type": "audio", "audio_asset_id": "$AUDIO_ID" },
    "background": { "type": "color", "value": "#00FF00" }
  }],
  "dimension": { "width": 720, "height": 1280 }
}
EOF
)

# 완료될 때까지 폴링 (일반적으로 IV는 60~90초, 새 Look의 V는 첫 렌더에 5~20분)
# GET https://api.heygen.com/v1/video_status.get?video_id=$VID → data.status == "completed"
# 그런 다음 data.video_url을 assets/avatar_green.mp4로 다운로드

6단계 — 크로마키 + 대칭 패딩

HeyGen 그린스크린 MP4 → 투명 VP9 webm으로 변환하고 양 끝에 0.5초 프리즈프레임 패딩을 추가합니다:

# 크로마키 + 디스필 → 원시 투명 webm
ffmpeg -y -i avatar_green.mp4 \
  -vf "chromakey=0x00FF00:0.10:0.05,despill=type=green:mix=0.6:expand=0" \
  -c:v libvpx-vp9 -pix_fmt yuva420p -auto-alt-ref 0 -b:v 0 -crf 30 -an \
  avatar.raw.webm

# 양 끝에 0.5초 프리즈프레임 추가 (알파 채널 유지)
ffmpeg -y -c:v libvpx-vp9 -i avatar.raw.webm \
  -vf "tpad=start_duration=0.5:start_mode=clone:stop_duration=0.5:stop_mode=clone" \
  -c:v libvpx-vp9 -pix_fmt yuva420p -auto-alt-ref 0 -b:v 0 -crf 30 -an \
  avatar.webm

voice.mp3의 양 끝에 0.5초 무음을 대칭적으로 추가하여 오디오 오프셋이 아바타 타이밍과 일치하도록 합니다:

ffmpeg -y -f lavfi -i anullsrc=r=44100:cl=stereo -t 0.5 -c:a libmp3lame -b:a 192k silence.mp3
ffmpeg -y -f concat -safe 0 -i <(printf "file '%s/silence.mp3'\nfile '%s/voice_raw.mp3'\nfile '%s/silence.mp3'\n" "$PWD" "$PWD" "$PWD") \
  -c:a libmp3lame -b:a 192k voice.mp3

이렇게 하면 타이밍 규칙이 달성됩니다: 아바타 등장 → 음성 시작 → 음성 종료 → 아바타 페이드 아웃. project_audio_video_timing.md 참조 (Phase 9에서 생성, 없을 경우 — 규칙은 0.5초 리드 + 0.5초 테일, 모든 GSAP 장면 큐는 +0.5초 시프트, 최종 페이드 아웃은 음성 종료 후 0.1초 후 시작).

7단계 — Object-position 캘리브레이션

프레임 내 아바타 얼굴 위치는 원본 사진에 따라 달라지므로, Look ID별로 재캘리브레이션합니다:

ffmpeg -y -ss 0.7 -i avatar.webm -vframes 1 avatar-frame-check.png

프레임을 읽고, 얼굴 중심 y-좌표(1280 높이 소스 기준)를 측정합니다. 레이아웃별로 object-position을 계산합니다:

object_position_y_pct = ( (face_y_px / 1280) * scaled_height_for_layout - layout_slot_height/2 ) / (scaled_height_for_layout - layout_slot_height) * 100

실제로는: 얼굴이 프레임 상단 1/3 위치(face_y ~380)에 있는 경우, 좁은 슬롯은 '50% 30%', 전체 프레임 슬롯은 '50% 50%'를 사용합니다. index.html의 LAYOUT_AVATAR_SLOTS를 업데이트하세요. 절대 추측하지 마세요 — 항상 추출된 프레임에서 캘리브레이션하세요.

8단계 — B-roll 이미지 (KIE.AI의 Nano Banana 2)

두 가지 고정 템플릿 — 전체 버전은 project_image_direction_templates.md를 참조하세요. 브랜드 색상은 프로젝트별로 교체됩니다 (brand.json의 BG_HEX 및 ACCENT_HEX 치환).

템플릿 1 — 순수 추상 조각 (분위기, 무드, 내러티브 비트):

고체 [BG_HEX] 배경 위의 추상 3D 조각적 렌더링. [FORM_DESCRIPTION], [MOTION_INTENT] 암시. [ACCENT_HEX] 빛이 서브서피스 스캐터링과 함께 형태 주변과 내부로 굴절되어, 미세하게 반사되는 어두운 바닥에 부드러운 코스틱을 드리움. 부드러운 방향성 스튜디오 조명. 하이퍼리얼 Octane 렌더. 프리미엄 기술 키노트 미학. 중앙 형태에 선명한 초점, 가장자리로 갈수록 그림자 속으로 깊이 감쇠. 텍스트, 로고 없음.

템플릿 2 — 유리 차트 (통계, 비교, 성장, 비율, "X×", "Y%" 등을 언급하는 라인):

고체 [BG_HEX] 배경 위의 추상 3D 데이터 시각화. [CHART_TYPE]이 [DATA_CONCEPT]을 묘사하는 떠다니는 반투명 유리 형태로 완전히 렌더링됨. 베이스라인 요소는 음영 처리된 무광 회색 유리; 초점 요소는 [ACCENT_HEX] 서브서피스 스캐터링과 굴절로 빛나며, 미세하게 반사되는 어두운 바닥에 부드러운 코스틱을 드리움. 얇은 오프-화이트 축선. 부드러운 방향성 스튜디오 조명. 하이퍼리얼 Octane 렌더. 프리미엄 기술 키노트 미학. 여유로운 네거티브 공간이 있는 미니멀리스트 에디토리얼 구성. 텍스트, 숫자, 라벨, 로고 없음.

장면별 결정 규칙: 스크립트 라인이 숫자/통계/비교를 인용하면 → 템플릿 2. 그렇지 않으면 → 템플릿 1.

제출 패턴 (기본 1:1 비율, 모든 비율 지원). 항상 HTTP 코드 + 본문을 캡처하여 4xx 오류가 자체 진단되도록 합니다:

source .env && RESPONSE=$(curl -sS -w "\nHTTP_CODE:%{http_code}" -X POST "https://api.kie.ai/api/v1/playground/createTask" \
  -H "Authorization: Bearer $KIE_AI_API_KEY" -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{"model":"nano-banana-2","input":{"prompt":"<슬롯이 채워진 템플릿>","output_format":"png","image_size":"1:1"}}
EOF
)
echo "$RESPONSE"
[[ "$RESPONSE" == *"HTTP_CODE:200"* ]] || { echo "KIE 제출 실패 — 위 본문 참조"; exit 1; }

https://api.kie.ai/api/v1/playground/recordInfo?taskId=<id>를 4초마다 폴링하여 data.state == "success"가 될 때까지 기다린 후, data.resultJson을 파싱하고 (json.loads() 사용), URL을 assets/broll-N.png로 다운로드합니다.

여러 B-roll 생성을 병렬로 실행하세요 — KIE.AI는 동시 작업을 잘 처리합니다.

일반적인 400 오류 원인: 프롬프트 안전 필터. Nano Banana 2는 법률/폭력/갈등 관련 프롬프트(예: "법정", "법적 분쟁", "원고 vs 피고")를 거부합니다. 두 가지 추상 템플릿을 엄격히 준수하세요 — 의미를 기하학/색상으로 인코딩하고, 문자 그대로의 주제는 사용하지 마세요. 2026-04-28 검증 완료: 최소한의 추상 프로브는 동일한 인증/스키마로 200을 반환하므로, 여기서 400은 거의 항상 프롬프트 내용 문제입니다.

9단계 — 배경 음악 (11Labs Music)

source .env && curl -s -X POST "https://api.elevenlabs.io/v1/music?output_format=mp3_44100_128" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "prompt": "<음악 프롬프트>",
    "music_length_ms": 22000,
    "force_instrumental": true,
    "model_id": "music_v1"
  }' --output assets/music_raw.mp3

동기식으로 오디오 바이트를 반환합니다. music_length_ms는 컴포지션 길이와 일치합니다 (범위 3000~600000ms).

기본 음악 프롬프트 (B2B 광고 배경 음악, 2026-04-27 검증 완료):

B2B 비즈니스 광고를 위한 경쾌하고 낙관적인 인스트루멘탈 언더스코어. 밝고 현대적인 피아노가 선명한 스타카토 노트로 앞으로 나아가는 리드미컬한 패턴을 연주하며, 미묘하고 고양되는 신스 패드와 어우러짐. 가볍고 부드러운 맥박 — 부드러운 셰이커나 음소거된 리드미컬한 클릭이 꾸준한 전진 모멘텀을 제공. 큰 드럼, 킥, 크래시, 심벌즈 없음. 보컬 없음. 자신감 있고, 활기차고, 에너제틱하며 낙관적인 느낌. 현대적이고, 깔끔하며, 기술 지향적이고, 전문적이며, 현대적인 기업 이미지. 템포 약 115 BPM. 밝은 메이저 키, 맑지만 지나치지 않은. 전체적으로 고른 다이나믹 — 스웰, 드롭, 클라이맥스, 페이드 없음 — 그러나 꾸준한 리드미컬한 모멘텀 있음. 현대 SaaS 제품 출시 비디오 배경 음악처럼 들림.

프롬프트에서 피해야 할 안티패턴:

  • "Cinematic" / "moody" / "ambient" → 감상적인 분위기를 유발, 광고에 부적합
  • 90 BPM 이하의 템포 → 너무 졸림
  • 스웰, 클라이맥스, 다이나믹 변화를 언급 → 음성과 경쟁
  • "보컬 없음"을 빼먹음 → ElevenLabs가 허밍을 추가할 수 있음

짧은 페이드로 -20dB 믹스하여 음성 아래에 자연스럽게 배치:

ffmpeg -y -i music_raw.mp3 \
  -af "volume=-20dB,afade=t=in:st=0:d=0.4,afade=t=out:st=<끝-0.6>:d=0.6" \
  -c:a libmp3lame -b:a 192k music.mp3

10단계 — 컴포지션 조립

template-16x9/index.html이 작업 컴포지션입니다. 각 렌더링마다:

  1. 루트, 음성, 아바타, 음악 요소의 data-duration을 대상 길이에 맞게 업데이트
  2. styles/brand.css에서 브랜드 색상 업데이트 (변수 --bg, --accent 등)
  3. 브랜드가 다른 글꼴 패밀리를 사용하는 경우 brand.css에서 글꼴 업데이트
  4. GSAP 타임라인의 장면 전환 타이밍을 스크립트 비트에 맞게 조정
  5. 4개의 시간 요소(아바타 비디오, 음성 오디오, 음악 오디오, 루트 컴포지션) 모두 정렬된 data-start 및 data-duration을 가지는지 확인

오디오 트랙 인덱스: avatar=1, voice=2, music=3. 모두 class="clip". 모두 data-start="0".

11단계 — 렌더링

cd "$HOME/<프로젝트-디렉토리>/template-16x9" && \
npx hyperframes lint && \
npx hyperframes render --output renders/<브랜드>-v<n>.mp4

중요: 렌더를 포그라운드에서 실행하세요. 백그라운드 모드 렌더는 프레임 캡처 시작 후 CPU 0%에서 멈춥니다. timeout: 300000과 함께 포그라운드 Bash 호출을 사용하세요. 22초 컴포지션의 경우 렌더링에 약 12분, 45초의 경우 약 34분이 소요됩니다.

렌더링 완료 후, open -a "QuickTime Player" renders/<브랜드>-v<n>.mp4로 검토합니다.


반복 루프

대부분의 렌더링은 1~3회의 패스가 필요합니다:

  • v1: 적절한 기본값으로 체인이 엔드투엔드로 작동하는지 확인
  • v2: 명백한 문제 수정 (얼굴 잘림, 음악 너무 큼, 전환 어색함 등)
  • v3: 미세 조정 (색상, 타이밍, 분위기)

각 패스 후, 비디오를 재생하고(중요: QuickTime Player 사용 — 실제 재생), 개선이 필요한 사항을 메모하고, 필요한 단계로 돌아가십시오. HeyGen 아바타는 비용이 많이 드는 작업이므로 반복 시 다시 생성할 필요가 없는 경우 --skip-avatar 플래그가 HyperFrames 파이프라인에 추가될 예정입니다.


향후 개선 사항

  • Stage 0: 렌더링 시 에셋 교체 대신 브랜드별로 template-16x9/ 복사
  • 바이너리 다운로드 재시도: curl 다운로드에 재시도 로직 추가 (일시적인 네트워크 문제)
  • 렌더링 시간 초과: timeout을 파이프라인 래퍼에 통합 (하드 실패, 매달림 없음)
  • 알려진 문제: 때때로 11Labs 음성이 "완료" 상태를 반환하지 않음 — 타임아웃 후 재시도; HeyGen V 모델은 새로운 Look ID로 첫 렌더링 시 5~20분이 소요됨 — 캐시 워밍업; HeyGen Avatar V.2의 비디오는 때때로 손상된 헤더를 반환함 — ffmpeg -i corrupted.mp4 -c copy fixed.mp4로 다시 래핑

이 파이프라인은 Claude Code + KIE.AI + HeyGen + ElevenLabs + HyperFrames로 구동됩니다. 워크플로우 질문이나 문제는 ColdStart 팀에 문의하세요.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

관련 스킬