lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

mkt-full-video-with-11-hyperframe-heygen

종단간 오케스트레이터: 대본 → 최종 TikTok/Reels MP4 9:16.

파이프라인에는 2개의 사용자 체크포인트가 있습니다:

1. MP3 체크포인트 (오케스트레이터) — Phase 1 이후, 사용자가 음성 해설을 검토합니다.
2. 장면 개요 체크포인트 (Phase 3 하위 에이전트) — 사용자가 장면 구조와 변형을 검토한 후 콘텐츠 작성기로 분산합니다. 사용자가 auto_scenes=true를 전달하면 건너뛸 수 있습니다.

사용 시기

• 사용자가 완성된 TikTok 비디오를 원하는 베트남어/영어 대본(≤ 5000자)을 가지고 있는 경우
• (선택 사항) 용도가 명시된 이미지 또는 비디오 B-roll이 있는 경우
• 대본에서 Studio 미리보기까지 한 번에 진행하고자 하는 경우

다음 경우에는 이 스킬을 사용하지 마십시오:

• 사용자가 이미 MP3를 가지고 있는 경우 → heygen-mp3-to-mp4를 직접 사용
• 사용자가 이미 MP4 talking-head를 가지고 있는 경우 → mkt-hyperframe-talking-head-video를 직접 사용
• 사용자가 HeyGen이 텍스트를 직접 읽도록 해야 하는 경우(ElevenLabs를 거치지 않음) → heygen-script-to-mp4 사용
• 대본이 5000자 초과 → 의미적으로 분할한 후 각 세그먼트에 대해 파이프라인 호출

파이프라인 개요

Script (text + optional b-roll + tts_provider)
    │
    ▼
Phase 1 ── TTS (elevenlabs | minimax) ──► voiceover.mp3
    │                                         │
    │                                         ▼
    │                              CHECKPOINT #1 — 사용자가 MP3 듣고 승인
    │                                         │
    │                                         ▼ (OK)
Phase 2 ── heygen-mp3-to-mp4 ──────────► source.mp4 (9:16 lip-sync)
    │
    ▼
Phase 3 ── 에이전트 mkt-full-video-phase3-packager 생성 (격리된 컨텍스트)
            │
            ├─ 자막 추출 + 정리 + 그룹화
            ├─ 장면 경계 감지 + mockup_variant 분류
            ├─ CHECKPOINT #2 — 사용자가 장면 개요 검토
            ├─ N개의 일반 목적 하위 에이전트로 분산 (장면당 1개) 병렬
            │   → 각 하위 에이전트가 변형 스키마에 따라 콘텐츠 JSON 구축
            ├─ 병합 → scenes.json
            ├─ 병렬: 하위 구성 요소 스캐폴딩 + SFX 복사 + 자막 주입
            ├─ 루트 index.html 생성
            └─ 린트 + Studio 미리보기
    │
    ▼
사용자가 미리보기 검토 → "render" → 최종 MP4

체크포인트 규칙: 오케스트레이터가 체크포인트 #1(MP3)을 관리합니다. Phase 2 → 3은 자동 실행됩니다. 체크포인트 #2(장면 개요)는 Phase 3 하위 에이전트가 관리합니다. 마지막 Render 게이트는 Studio에서 이루어집니다.

입력

입력	필수	형식 / 예시
대본 텍스트	예	파일 경로(.txt/.md) 또는 인라인 문자열. ≤ 5000자.
Slug 프로젝트	아니오	대본의 처음 5단어에서 자동 파생. 소문자, ASCII, 대시.
B-roll 목록	아니오	배열 [{path: "...", purpose: "레슨 1 — X 설명"}, ...].
tts_provider	아니오	elevenlabs (기본 — Hoàng 목소리, 표현력 좋음) 또는 minimax (speech-2.8-hd, 저렴, 베트남어 자연스러움). 사용자가 "minimax 사용" / "eleven 사용"을 말하면 해당 값으로 설정.
Voice ID 재정의	아니오	.env의 기본값을 재정의합니다. ElevenLabs는 ELEVENLABS_VOICE_ID를 읽고, MiniMax는 MINIMAX_VOICE_ID를 읽습니다. 둘 다 CLI 플래그 --voice_id 사용.
음성 설정 재정의	아니오	ElevenLabs: {stability, similarity_boost, style}. MiniMax: {speed, vol, pitch}.
아바타 모양	아니오	HEYGEN_AVATAR_LOOKS env (.env, 쉼표로 구분)에서 가져온 1개의 ID. 선택하지 않으면 무작위.
auto_scenes	아니오	기본값 false. true로 설정하면 Phase 3의 장면 개요 체크포인트를 건너뜁니다.

작업 공간 레이아웃

workspace/content/YYYY-MM-DD/<slug>/
├── script.txt              # Phase 0
├── voiceover.mp3           # Phase 1
├── source.mp4              # Phase 2
├── broll/                  # 사용자가 제공한 B-roll (복사)
├── transcript.json         # Phase 3
├── caption-groups.json     # Phase 3
├── scenes-outline.json     # Phase 3 — 체크포인트 전 개요
├── scenes/                 # Phase 3 — 장면별 콘텐츠가 여기에 기록됨
│   ├── scene-1.json
│   └── ...
├── scenes.json             # Phase 3 — 병합된 최종
├── compositions/           # Phase 3 — HF 하위 구성 요소
├── sfx/                    # Phase 3 — 6개의 SFX
└── index.html              # Phase 3 — 루트 구성 요소

YYYY-MM-DD = 오늘 날짜 (UTC+7).

워크플로우

Step 0 — 설정

1. len(script_text) <= 5000 확인. 초과 시 중단하고 사용자에게 의미적으로 분할하도록 요청.
2. Slug가 없으면 파생: 처음 5단어 → 소문자 → 악센트 제거 → 공백→대시.
3. TTS 제공자 결정 — 사용자 입력에서 tts_provider 읽기 (기본값 elevenlabs). 사용자가 "minimax 사용" / "minimax로 변경"이라고 말하면 → minimax. 사용자가 "eleven 사용" / "elevenlabs"라고 말하면 → elevenlabs. 해당 API 키가 .env에 있는지 확인:
   • elevenlabs → ELEVENLABS_API_KEY 필요 (선택 사항: 기본 K7ewtjKRNtwwt3lKQ6M0을 재정의할 ELEVENLABS_VOICE_ID).
   • minimax → MINIMAX_API_KEY 필요 (선택 사항: 기본 moss_audio_c56d6120-ef9c-11f0-9649-8ee40147f116을 재정의할 MINIMAX_VOICE_ID). 키가 없으면 중단하고 사용자에게 .env에 추가하도록 알림.
4. workspace/content/YYYY-MM-DD/<slug>/ 생성. script.txt 저장.
5. 사용자에게 B-roll이 있는 경우: <folder>/broll/ 생성, 원본 이름 유지하며 파일 복사.
6. 사용자에게 알림: "작업 공간이 <folder>에 생성되었습니다. TTS 제공자: <elevenlabs|minimax>. Phase 1을 시작합니다."

Step 1 — Phase 1: 대본 → MP3 (TTS)

tts_provider에 따라 정확히 1개의 분기를 실행:

분기 A — ElevenLabs (기본):

uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
  --file workspace/content/YYYY-MM-DD/<slug>/script.txt \
  -o workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3

음성 ID: .env에서 ELEVENLABS_VOICE_ID를 자동으로 읽음 (기본 Hoàng 브랜드 음성으로 대체). CLI 재정의: --voice_id <id>. 음성 설정: 사용자가 조정을 요청한 경우 --stability / --similarity_boost / --style 추가.

분기 B — MiniMax:

uv run .claude/skills/mkt-video-script-to-mp3/scripts/text_to_mp3.py \
  --file workspace/content/YYYY-MM-DD/<slug>/script.txt \
  -o workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3

음성 ID: .env에서 MINIMAX_VOICE_ID를 자동으로 읽음 (기본 moss_audio_…으로 대체). CLI 재정의: --voice_id <id>. 음성 설정: --speed (기본값 1.08), --vol, --pitch, --language_boost Vietnamese.

출력 파일 이름은 변경 불가 (두 분기 모두): voiceover.mp3 — Phase 2 (HeyGen)가 올바른 경로를 찾을 수 있도록.

완료 후, 지속 시간 확인 (두 제공자 공통):

uv run .claude/skills/heygen-mp3-to-mp4/scripts/check_duration.py \
  workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3

TOO_LONG → 중단, 사용자에게 MP3가 HeyGen 제한 5분을 초과했음을 알리고 대본 축소 요청.

Step 2 — CHECKPOINT #1: 사용자가 MP3 듣기

오케스트레이터가 관리하는 유일한 중단 지점. 다음 형식으로 사용자에게 알림:

## 음성 해설 준비 완료 — 확인 부탁드립니다

**파일:** `workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3`
**길이:** <X.X>초
**크기:** <Y.Y> MB
**제공자:** `<elevenlabs | minimax>`
**음성:** `<ElevenLabs Brand Voice của Hoàng (K7ewtjKRNtwwt3lKQ6M0)>` 또는 `<MiniMax speech-2.8-hd (moss_audio_…)>` (사용자가 재정의한 경우 `.env` 음성 ID에서 가져옴)

파일을 열어 들어보세요. 다음 중 하나로 답변해 주세요:
- **`OK`** / **`tiếp`** → Phase 2 (HeyGen 아바타 립싱크)를 실행합니다.
- **`regen`** + (선택 사항) 이유 → 음성 설정을 조정하고 MP3를 다시 생성합니다.
- **`sửa script`** + 새 내용 → 새 대본을 저장하고 Phase 1을 다시 실행합니다.

도구 호출 중지. 사용자의 명확한 답변을 기다립니다.

사용자가 OK → Phase 2. 사용자가 regen → 현재 제공자의 TTS 스크립트를 새 설정으로 다시 실행하고 체크포인트로 돌아갑니다. 사용자가 "minimax로 변경" / "eleven 시도"라고 말하면 → tts_provider를 교체하고 Phase 1을 다시 실행합니다. 사용자가 대본 수정 → script.txt를 덮어쓰고 Phase 1을 처음부터 다시 실행합니다 (동일한 제공자 사용).

Step 3 — Phase 2: MP3 → HeyGen MP4 (자동)

하위 스킬 heygen-mp3-to-mp4에 따름:

1. 아바타 ID 선택 — .env에서 HEYGEN_AVATAR_LOOKS 읽기 (쉼표로 구분), 사용자가 지정하지 않으면 무작위 선택:

   HEYGEN_AVATAR_LOOKS=$(grep '^HEYGEN_AVATAR_LOOKS=' .env | cut -d'=' -f2- | tr -d '"' | tr -d "'")
   echo "$HEYGEN_AVATAR_LOOKS" | tr ',' '\n' | awk 'BEGIN{srand()} {a[NR]=$0} END{print a[int(rand()*NR)+1]}'
   

   env 변수가 없거나 비어 있으면 → 중단하고 사용자에게 HEYGEN_AVATAR_LOOKS=<id1>,<id2>를 .env에 추가하도록 알림. MCP를 호출하기 전에 사용자에게 어떤 ID를 선택할지 알림.

2. MP3 업로드 — MCP를 통해 HeyGen에 업로드 (upload_asset, asset type audio). https://upload.heygen.com/...에 curl 사용 금지.

3. 아바타 비디오 생성 — MCP를 통해 (generate_avatar_video):

   character: { type: avatar, avatar_id: <picked>, scale: 1.0 }
   voice:     { type: audio, audio_asset_id: <from upload> }
   dimension: { width: 720, height: 1280 }   # 9:16
   title:     "<slug>-<timestamp>"
   

4. 상태 폴링 — 약 10초마다 → completed (최대 10분). failed → 중단, 오류 표시.

5. MP4 다운로드 → workspace/content/YYYY-MM-DD/<slug>/source.mp4 (파일 이름 변경 불가):

   uv run .claude/skills/heygen-mp3-to-mp4/scripts/download_video.py \
     "<video_url>" "workspace/content/YYYY-MM-DD/<slug>/source.mp4"
   

6. 사용자에게 한 줄로 알림: "Phase 2 완료 — <path> (아바타 <id>, 초, MB). Phase 3 패키저를 생성합니다…"

여기서 중단하지 않음. Phase 3으로 자동 진행.

Step 4 — Phase 3: 패키저 하위 에이전트 생성

subagent_type: "mkt-full-video-phase3-packager"와 함께 Task 도구를 사용하십시오. 에이전트가 필요로 하는 입력이 포함된 독립적인 프롬프트를 전달하십시오. 예:

Workspace: workspace/content/2026-05-03/hom-nay-minh-chia-se/
Slug: hom-nay-minh-chia-se
Script: <전체 대본 텍스트>
B-roll: [
  {"path": "workspace/content/2026-05-03/hom-nay-minh-chia-se/broll/alphabet.png", "purpose": "레슨 1"},
  ...
]
auto_scenes: false
header_label: "3 BÀI HỌC AI"
footer_handle: "@tranvanhoang.com"

자신의 에이전트 정의에 따라 전체 Phase 3 패키징 파이프라인을 실행하십시오. 미리보기가 열리면 Studio URL을 반환하십시오.

하위 에이전트:

• source.mp4를 텍스트로 변환하고 장면 개요를 구축
• auto_scenes: true가 아닌 경우 사용자에게 개요 승인 요청 (CHECKPOINT #2)
• 병렬로 N개의 장면 콘텐츠 작성기를 분산
• 병합 + 스캐폴딩 + 린트 + 미리보기 열기
• Studio URL 반환

하위 에이전트가 실행되는 동안 오케스트레이터의 유일한 역할은 사용자 답변을 하위 에이전트로 전달하는 것입니다 (장면 개요 체크포인트에서의 사용자 답변은 이 대화에 도착합니다. 하위 에이전트가 아직 활성 상태이면 하위 에이전트로 라우팅하고, 그렇지 않으면 후속 지침으로 처리합니다).

Step 5 — 인계

하위 에이전트가 Studio URL을 반환하면 최종 보고서 형식으로 제공:

## 전체 비디오 파이프라인 완료 — 미리보기 준비

**작업 공간:** `workspace/content/YYYY-MM-DD/<slug>/`

**Phase 1 (`<elevenlabs|minimax>`):** voiceover.mp3 — <D1>초, <S1>MB (음성 ID `<id>`)
**Phase 2 (HeyGen):** source.mp4 — 아바타 `<avatar_id>`, <D2>초, <S2>MB
**Phase 3 (HyperFrames):** <N>개 장면 (<리스트 variants>), <K>개 자막 그룹, 6개 SFX

**Studio URL:** http://localhost:3002

브라우저를 열어 타임라인을 스크러빙하세요. 확인되면 **`render`** 라고 말씀해 주세요 → `npx hyperframes render`를 실행하여 1080×1920 30fps MP4를 내보냅니다.

여기서 중단합니다. 자동 렌더링하지 않습니다. 사용자가 확인한 후에 npx hyperframes render를 호출합니다.

중요한 오케스트레이션 규칙

1. 2개의 사용자 체크포인트, 1개의 오케스트레이터 게이트 — 오케스트레이터는 MP3(Step 2)에서만 중단됩니다. 장면 개요 체크포인트는 Phase 3 하위 에이전트가 관리합니다. Render 게이트는 사용자가 Studio에서 수행합니다.

2. 경로 규칙 변경 불가 — voiceover는 voiceover.mp3, talking-head는 source.mp4여야 합니다. HF 하위 스킬은 source.mp4 이름을 예상합니다.

3. HeyGen MCP 전용 — 절대 https://api.heygen.com/...에 curl을 사용하지 마십시오. heygen-mp3-to-mp4의 하드 제약 사항입니다.

4. 음성 ID는 .env에 저장, 스킬에 하드코딩하지 않음. ElevenLabs는 ELEVENLABS_VOICE_ID를 읽습니다 (대체 K7ewtjKRNtwwt3lKQ6M0). MiniMax는 MINIMAX_VOICE_ID를 읽습니다 (대체 moss_audio_…). 호출별 재정의는 --voice_id를 통해 수행합니다. 파이프라인은 Step 0과 체크포인트 #1에서 선택한 제공자와 음성 ID를 명확히 알립니다.

5. 대본 길이 하드 제한 5000자 — Step 0.1에서 빠르게 실패.

6. MP3 길이 ≤ 300초 — HeyGen 단일 비디오 제한. Phase 1 직후 확인.

7. 미리보기 우선 — Phase 3은 자동 렌더링하지 않습니다. feedback_hyperframes_workflow.md 메모리 참조.

8. Phase 3 격리 — Phase 3은 별도의 하위 에이전트 컨텍스트에서 실행됩니다. HF 스킬 본문과 4개의 참조 문서 (~40KB)가 기본 오케스트레이터 대신 하위 에이전트에 로드됩니다.

실패 모드 및 대체

증상	조치
대본 > 5000자	중단, 사용자에게 의미적으로 분할 요청
ElevenLabs API 실패	오류 보고, .env에서 ELEVENLABS_API_KEY 확인 제안 (선택 사항 ELEVENLABS_VOICE_ID). 또는 tts_provider=minimax로 전환하여 Phase 1 재실행
MiniMax API 실패	오류 보고, .env에서 MINIMAX_API_KEY 확인 제안 (선택 사항 MINIMAX_VOICE_ID). 또는 tts_provider=elevenlabs로 전환하여 Phase 1 재실행
Phase 1 후 MP3 > 300초	파이프라인 중단, heygen-short-video (청킹) 제안
HeyGen MCP 미연결	중단, claude mcp list로 확인 안내
HeyGen 렌더링 실패	오류 표시, mcp__heygen__get_current_user로 크레딧 확인 제안
Phase 3 하위 에이전트 실패	오류 추적 읽기, mkt-hyperframe-talking-head-video 스킬을 사용하여 Phase 3을 독립적으로 재실행 제안
장면 작성기가 잘못된 JSON 반환	하위 에이전트가 해당 장면에 대해 자동 재생성 (오케스트레이터의 관심사가 아님)
사용자가 MP3 음성 거부	음성 설정 조정 후 Phase 1으로 돌아가기

종단간 예시

사용자:

대본이 있습니다. 전체 파이프라인을 실행하여 TikTok 비디오를 만들어 주세요. 레슨 1과 레슨 2에 대한 B-roll 이미지 2개도 함께 제공합니다. 대본: "오늘은 Anthropic의 3가지 교훈을 공유하겠습니다. 첫 번째 교훈은 Alphabet ship beta입니다. 두 번째 교훈은 24h…" B-roll: alphabet.png (레슨 1), clock.png (레슨 2)

파이프라인:

1. Step 0 — slug hom-nay-minh-chia-se. 폴더 workspace/content/2026-05-03/hom-nay-minh-chia-se/. script.txt 저장, B-roll 복사.
2. Step 1 — text_to_mp3.py → voiceover.mp3 (45초, 0.7MB).
3. Step 2 — CHECKPOINT #1 — 사용자에게 경로와 길이 알림. 답변 대기.
4. 사용자: OK.
5. Step 3 — 아바타 선택 ( HEYGEN_AVATAR_LOOKS에서 무작위, 예: 66e75e22…). MP3 업로드 → asset_id. 비디오 생성 → 폴링 → source.mp4 다운로드 (45초, 7.5MB).
6. Step 4 — mkt-full-video-phase3-packager 하위 에이전트 생성.
7. 하위 에이전트가 텍스트 변환 (35초), 개요 구축 (3개 레슨 + 요약 + CTA), 개요 표시 → CHECKPOINT #2.
8. 사용자: OK.
9. 하위 에이전트가 5개의 장면 작성기를 병렬로 분산 (직렬 ~40초 대비 벽시계 약 8초).
10. 하위 에이전트가 병합 → scenes.json → 스캐폴딩 + SFX + 자막 병렬

…

[번역을 위해 잘림]