Communitygithub.com

ChuchoMonster/brand-video-pipeline

端到端多租户品牌解说/宣传视频生成管道。从URL提取品牌标识,撰写脚本,生成语音+AI虚拟主播+B-roll图像+背景音乐,在HyperFrames中组装并渲染。触发短语包括“Hyper Frames for <url>”、“为<品牌>制作Hyper Frames视频”、“Hyper Frames推广视频 for <url>”、“<品牌>解说视频”或直接“Hyper Frames <url>”。

brand-video-pipeline 是什么?

该技能实现了一个端到端的多租户品牌视频生成管道,适用于Claude Code等AI代理。它从给定的URL自动提取品牌标识(配色、字体、语调),编写解说或宣传脚本,生成语音(通过ElevenLabs)、AI虚拟主播(通过HeyGen)、B-roll图像(通过KIE.AI的Nano Banana 2模型)以及背景音乐(通过ElevenLabs Music),最后在HyperFrames中组装并渲染成MP4视频。 管道分为多个阶段:品牌提取(调用brand-book技能)、网站内容理解(使用WebFetch抓取关键页面)、脚本编写(遵循约2.7词/秒的节奏)、语音生成、虚拟主播生成(含绿幕抠像和对称填充)、B-roll图像生成(使用预定义的抽象3D或玻璃图表模板)、背景音乐生成(默认B2B广告风格并混音至-20dB)以及最终合成渲染。该设计在ColdStart(coldstartb2b.com)上验证通过,并计划扩展到任意B2B品牌。 用户可通过自然语言指令触发,如“Hyper Frames <url>”或“为<品牌>制作视频”。管道支持迭代优化,通常在1-3次渲染内完成。它依赖于特定的环境变量配置(API密钥),并包含详细的错误处理与自我诊断机制。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ChuchoMonster/brand-video-pipeline/tree/HEAD/skill

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

HyperFrames 管道 —— 多租户品牌解说视频

端到端管道,接收URL并生成完整的品牌解说/宣传MP4。基于ColdStart(coldstartb2b.com)构建并验证。设计为可扩展到任何B2B品牌,每个租户的配置需求极少。

何时调用

  • 用户说出“Hyper Frames”/“hyperframes”加上URL或品牌名称
  • 用户要求为特定企业制作解说/宣传视频
  • 用户说“为<品牌>制作视频”或类似内容
  • 用户说“让我们在<新URL>上试试”

必需环境(在 $PIPELINE_ROOT/.env 中 —— 复制 .env.example)

KIE_AI_API_KEY=...        # 通过 KIE.AI 使用 Nano Banana 2 + Seedance 2
HEYGEN_API_KEY=...        # HeyGen 虚拟主播生成
ELEVENLABS_API_KEY=...    # 11Labs 语音 + 音乐
ELEVENLABS_VOICE_ID=...   # 默认旁白语音
HEYGEN_TALKING_PHOTO_ID=...  # 默认虚拟主播形象

项目结构

$PIPELINE_ROOT/            # 此仓库根目录
  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/

对于多租户生产环境,未来的第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 抓取首页及关键页面(服务、团队、定价、关于)。综合提取:

  • 他们销售什么
  • 他们的理想客户画像
  • 1-2个最突出的差异化因素
  • 期望的行动号召

这将成为脚本的核心内容。

第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)

调用11Labs TTS,使用 eleven_multilingual_v2。默认语音:来自 .env 的 $ELEVENLABS_VOICE_ID(或用户指定/品牌偏好的语音 —— 如果不确定请询问)。

source .env && curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/$ELEVENLABS_VOICE_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(形象ID)。默认使用 .env 中的 $HEYGEN_TALKING_PHOTO_ID(你的HeyGen账户中的任何说话照片形象)。

始终在角色级别设置 use_avatar_v_model: true。如果该形象未启用V模型,HeyGen将默默回退到Avatar IV(未注册的形象回退到IV;渲染不受影响)。

上传语音 → 提交说话照片渲染 → 轮询 → 下载 → 抠像:

# 上传音频
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秒,首次渲染新形象时对于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

这实现了时间规则:虚拟主播出现 → 语音开始 → 语音结束 → 虚拟主播淡出。(规则为0.5秒前导 + 0.5秒尾随,所有GSAP场景提示偏移+0.5秒,最终淡出在语音结束后0.1秒开始)。

第7阶段 —— 对象位置校准

虚拟主播的面部在画面中的位置取决于源照片,因此需要针对每个形象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)

两个固定模板。品牌颜色按项目替换(从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; }

每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拒绝看起来与法律/暴力/冲突相关的提示(例如“法庭”、“法律斗争”、“原告与被告”)。严格使用两个抽象模板 —— 通过几何/颜色传达含义,绝不使用字面主题。已于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产品发布视频的背景音乐。

提示中应避免的反模式:

  • “电影感”/“情绪化”/“氛围” → 产生伤感拖沓,不适合广告
  • 速度低于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 "$PIPELINE_ROOT/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:打磨

使用 brands/<brand>/claude.md 中的渲染反馈日志进行追踪。


设计约束与稳定性保证

  1. 5场模板结构是为22秒时长优化的。对于更长时长按比例缩放,但始终保持开场钩子 + 问题/解决节奏。
  2. 语音框裁剪(B框):虚拟主播视频始终以720x1280生成。合成时,裁剪区域(帧内的B框)因形象而异。总是从提取的帧校准 object-position。
  3. 音频同步:同步边界是严格的。所有填充必须精确对称。
  4. 音乐混音:-20dB是锁定值。改变它会覆盖语音或暴露背景噪音。
  5. B-roll生成:始终使用模板1或2。如果安全过滤器触发,不要尝试使用字面提示 —— 回到更抽象的措辞。
  6. 错误传播:任何4xx/5xx响应都应在继续之前失败,并包含完整的响应体用于调试。

支持的渲染风格

风格时长脚本场景B-roll数量
快速宣传22秒55
标准解说45秒6-76-7
完整品牌故事60秒+8+8+

默认使用22秒快速宣传风格 —— 它非常适合快速吸引注意力,并自然地限制API成本。

相关技能