Communitygithub.com

ChuchoMonster/claude-code-skills — HyperFrames 多租戶品牌解說影片管線

端到端多租戶品牌解說/宣傳影片管線。從網址生成完整的品牌影片 — 提取品牌識別、撰寫腳本、生成語音 + AI 虛擬角色 + B-roll 圖片 + 背景音樂,在 HyperFrames 中組合並渲染。

claude-code-skills — HyperFrames 多租戶品牌解說影片管線 是什麼?

這是一個功能強大的 AI 代理技能,專為自動生成品牌解說與宣傳影片而設計。它從目標 URL 開始,執行一個完整的端到端流程:首先提取品牌特徵(包括色彩、字型、語調等),接著分析網站內容以了解業務核心,然後撰寫符合品牌形象的腳本,並依序生成語音(使用 ElevenLabs)、虛擬角色(使用 HeyGen)、B-roll 插圖(使用 Nano Banana 2)和背景音樂(使用 ElevenLabs Music)。所有元素最終在 HyperFrames 編輯器中組合,輸出一個完整的 MP4 影片。此技能支援多租戶場景,可為不同品牌重複使用模板,並已於 ColdStart(coldstartb2b.com)上驗證。觸發短語包括「Hyper Frames for <url>」、「為 <brand> 製作 Hyper Frames 影片」、「Hyper Frames 推廣 for <url>」或「<brand> 的解說影片」。它為開發者和 AI 代理使用者提供了一個可擴展、自動化的品牌影片製作解決方案,顯著減少手動工作。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ChuchoMonster/claude-code-skills/tree/HEAD/skills/hyperframes-pipeline

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

HyperFrames 管線 — 多租戶品牌解說影片

端到端管線,接收 URL 並產出完成品牌化的解說/宣傳 MP4 檔案。在 ColdStart (coldstartb2b.com) 上建置並驗證。旨在擴展至任何 B2B 品牌,且每個租戶僅需最少配置。

何時呼叫

  • 使用者說「Hyper Frames」/「hyperframes」加上 URL 或品牌名稱
  • 使用者要求為特定企業製作解說/宣傳影片
  • 使用者說「為 <品牌> 製作影片」或類似語句
  • 使用者說「讓我們在 <新 URL> 上試試看」

必要的環境變數(在 <your-project-dir>/.env 中)

KIE_AI_API_KEY=...        # 透過 KIE.AI 使用 Nano Banana 2 + Seedance 2
HEYGEN_API_KEY=...        # HeyGen 虛擬角色生成
ELEVENLABS_API_KEY=...    # 11Labs 語音 + 音樂

專案結構

<your-project-dir>/
  brands/
    <brand>/              # 每個品牌一個目錄(由 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 音樂背景
      broll-*.png         # Nano Banana B-roll
    renders/

針對多租戶生產環境,未來的 Stage 0 應為每個品牌複製 template-16x9/。目前,請在每次渲染時就地替換素材。


管線階段

階段 1 — 品牌提取

在目標 URL 上呼叫 brand-book 技能。它會產生:

  • brands/<brand>/brand.json — 調色板、字型、語音/語調摘要
  • brands/<brand>/css-variables.json — 來自即時網站的「所有」CSS 變數
  • brands/<brand>/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. 鉤子(持續時間的 10–15%)— 簡潔有力的 3–6 字句子
  2. 主體 1 — 問題(約 30%)— 什麼出了問題 / 瓶頸
  3. 主體 2 — 數據或證明(約 15%)— 規模大小(對 B-roll 使用範本 2 圖表)
  4. 主體 3 — 我們如何運作(約 25%)— 差異化因素
  5. 結尾 / 行動呼籲(約 15%)— 邀請 + 品牌字標

對於較長影片(45 秒以上),在主體 1 和主體 2 之間添加額外的主體場景(例如「主體 1a — 特定痛點」、「主體 1b — 不行動的代價」)。

11Labs eleven_multilingual_v2 的韻律規則: 標點符號驅動節奏(逗號 = 微暫停,句號 = 完全暫停,破折號 = 節拍)。無需使用 SSML 或情緒標籤 — multilingual_v2 不支援它們。只需使用自然標點撰寫對話式散文。

為便於追蹤,將腳本儲存至 template-16x9/script.txt。

階段 4 — 語音(11Labs)

使用 eleven_multilingual_v2 呼叫 11Labs TTS。預設語音:<your-elevenlabs-voice-id>(將其設為您 11Labs 庫中的某個語音,或使用者指定/品牌偏好的語音 — 如果不確定請詢問)。

source .env && curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/<your-elevenlabs-voice-id>" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"<script>","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:<your-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": "<your-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 秒凍結幀(保留 Alpha 通道)
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(如果在階段 9 中不存在則建立 — 規則是 0.5 秒前導 + 0.5 秒結尾,所有 GSAP 場景提示偏移 +0.5 秒,最終淡出在語音結束後 0.1 秒開始)。

階段 7 — 物件位置校準

虛擬角色的臉部在幀中的位置取決於來源照片,因此每個 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

實務上:臉部位於幀的上三分之一處(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":"<TEMPLATE WITH SLOTS FILLED>","output_format":"png","image_size":"1:1"}}
EOF
)
echo "$RESPONSE"
[[ "$RESPONSE" == *"HTTP_CODE:200"* ]] || { echo "KIE 提交失敗 — 請參閱上方響應主體"; exit 1; }

每 4 秒輪詢 https://api.kie.ai/api/v1/playground/recordInfo?taskId=<id>,直到 data.state == "success",解析 data.resultJson(它是一個 JSON 字串 — 使用 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 PROMPT>",
    "music_length_ms": 22000,
    "force_instrumental": true,
    "model_id": "music_v1"
  }' --output assets/music_raw.mp3

同步返回音訊位元組。music_length_ms 應與合成持續時間匹配(範圍 3000–600000 毫秒)。

B2B 廣告型背景音樂的預設提示(已於 2026-04-27 驗證):

為 B2B 商業廣告設計的樂觀進取器樂背景音樂。明亮的現代鋼琴演奏前進的節奏型態,搭配清脆的斷奏音符,並輔以微妙的提振氣氛合成器音墊。輕柔穩定的脈動 — 柔和的沙鈴或悶音節奏性點擊提供穩定的前進動力。無大鼓,無重擊,無碰撞,無鈸。無人聲。自信、活潑、有活力、樂觀的感覺。現代、乾淨、科技前瞻、專業、當代企業風格。節奏約 115 BPM。明亮的大調,陽光但不甜膩。貫穿始終的均勻動態 — 無漸強,無漸弱,無高潮,無淡出 — 但具有穩定的節奏動力。聽起來像現代 SaaS 產品發布影片的背景音樂。

提示中應避免的反模式:

  • 「電影感」/「氣氛」/「環境」 → 產生感傷的拖沓感,不適合廣告
  • 低於 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=<end-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/<your-project-dir>/template-16x9" && \
npx hyperframes lint && \
npx hyperframes render --output renders/<brand>-v<n>.mp4

關鍵:在前景執行渲染。 背景模式的渲染在幀捕獲開始後會掛在 0% CPU。使用帶有 timeout: 300000 的前景 Bash 呼叫。22 秒合成渲染約需 1–2 分鐘,45 秒約需 3–4 分鐘。

渲染完成後,使用 open -a "QuickTime Player" renders/<brand>-v<n>.mp4 進行審查。


迭代循環

大多數渲染需要 1–3 次迭代:

  • v1:以合理的預設值讓整個鏈路端到端運作
  • v2:修正明顯問題(臉部裁切、音樂過大、轉場問題等)
  • v3:微調品牌顏色、B-roll 選擇、語音變體

完成 v3 後,將 brands/<brand>/ 中的產出儲存為品牌設定。


延伸閱讀

  • project_image_direction_templates.md — 完整的 B-roll 提示範本與決策樹
  • project_audio_video_timing.md — Avatar/Voice/Music 同步規則
  • project_layout_system.md — 所有 10 種版型的詳細資訊
  • project_brand_book.md — brand-book 技能的文件

Individual skills in this repo

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

相關技能