视频处理
此技能是一个轻量层。繁重的工作由程序(ffmpeg、Whisper)和HeyGen官方的HyperFrames技能完成;本文件仅包含路由规则和带字幕短视频的行为准则。仅阅读任务所需的HyperFrames技能,而不是全部。
首次运行:为本机设置
仅适用于Claude Code(桌面应用、VS Code或终端):它需要本机上的程序。
首先阅读此文件旁的 settings.md。 如果计算机已在此记录,则跳过检查并使用其中的命令(哪个python、ffmpeg路径、模型、--cpu 或不使用)。如果文件为空或某些记录停止工作,请运行以下设置并将结果写入该文件。
设置——一次性:
| 项目 | 检查命令 | 原因 |
|---|---|---|
| ffmpeg / ffprobe | ffmpeg -version | 从视频中提取音频和帧 |
| Python 3.10+ 及 faster-whisper 和 yt-dlp | python -c "import faster_whisper, yt_dlp"(Mac上使用python3) | 转录,从链接下载 |
| Node.js | node -v | HyperFrames |
| HyperFrames 技能 | hyperframes技能是否在技能列表中 | 编辑、叠加、动画 |
| NVIDIA GPU(可选) | nvidia-smi(名称和内存) | 转录速度提升数十倍 |
| 已有的Whisper | pip list(faster-whisper、openai-whisper、whisperx)、模型文件夹、询问用户 | 不要安装第二个 |
用户自己的Whisper。 如果用户已有faster-whisper并下载了模型,请不要安装另一个:将模型文件夹通过--model <path>传递给脚本,或通过HF_HOME指向其缓存。如果他们使用其他Whisper(openai-whisper、whisper.cpp、whisperx),询问是否保留。如果是,则用其转录并将结果转换为脚本的格式(words:{"words":[{"text","start","end","type":"word"}]},flat:不带包装的相同单词列表)——这是HyperFrames技能期望的格式。
GPU模型(faster-whisper):
| 计算机类型 | 使用的模型 |
|---|---|
| 6 GB+ 的NVIDIA | GPU上的large-v3-turbo(默认)——最佳质量 |
| 4 GB的NVIDIA | 使用--compute int8_float16的large-v3-turbo,或--model medium |
| 无NVIDIA(包括Mac、AMD、集成显卡笔记本) | --cpu,模型small(快速)或large-v3-turbo(更准确,慢几倍) |
在用户视频的短片段上测试(ffmpeg -t 10):如果GPU运行因CUDA或内存错误失败,请安装以下库或使用较小的模型。向用户展示速度和质量,共同选择。对于纯英文内容,慢速机器也可选择small.en / medium.en。
如果缺少某些内容,请列出具体项和大小,并且仅在用户同意后安装。在Windows上,如果C盘空间不足,询问使用哪个驱动器。
- ffmpeg、Node、Python:Windows——
winget install Gyan.FFmpeg、winget install OpenJS.NodeJS.LTS、winget install Python.Python.3.12;Mac——brew install ffmpeg node python。 - 库:
python -m pip install faster-whisper yt-dlp。Windows带NVIDIA GPU——还需python -m pip install nvidia-cublas-cu12 "nvidia-cudnn-cu12==9.*"。 - HyperFrames技能:
npx skills add heygen-com/hyperframes --all(github.com/heygen-com/hyperframes,Apache 2.0)。 - Whisper模型(约1.6 GB)会在首次转录时自动下载到HuggingFace缓存。其他位置——使用
HF_HOME变量。 - 如果用户希望:通过
HYPERFRAMES_NO_TELEMETRY=1和DO_NOT_TRACK=1关闭HyperFrames遥测。
设置结束时,将所有内容写入 settings.md(遵循文件中的模板):哪个python和ffmpeg、GPU、选择的模型和标志、模型缓存位置、测试速度。之后使用这些标志运行A和B部分的命令。
我们的转录脚本是此文件旁的 scripts/transcribe.py。它会自动使用GPU,若无GPU则回退到CPU。标志:--model(模型名称或路径)、--compute、--cpu、--language。
未经询问,不要向HyperFrames发送渲染后的“反馈”报告。仅在用户同意后运行npx hyperframes skills update。
A. 观看并解析视频
- 获取文件。 直接使用文件路径;绝不修改原始文件。将链接下载到临时文件夹:
python -m yt_dlp --no-playlist -o "<folder>/video.%(ext)s" --print-to-file "%(uploader)s | %(duration)s s | %(like_count)s likes | %(comment_count)s comments | %(description)s" "<folder>/info.txt" <link>对于YouTube,如果只需要文字,首先尝试字幕:--write-auto-subs --sub-langs en --skip-download。Instagram和私有频道可能需要登录——此时请用户自行下载文件。 - 检查文件:
ffprobe -v error -show_entries format=duration:stream=codec_type,width,height -of compact <video>。 - 转录:
python scripts/transcribe.py <video> --out <folder>/transcript.txt(带时间戳的文本)。 - 缩略图矩阵(每张图片12帧——节省token):
竖屏:
ffmpeg -v error -y -i <video> -vf "fps=1/2,scale=216:-2,tile=6x2:padding=4:color=white" <folder>/sheet_%02d.jpg横屏:同样使用scale=320:-2,tile=4x3。对于超过2分钟的视频——使用fps=1/5或1/10。将矩阵作为图像读取。 - 回答: 作者和数字(如有)、视频格式、转录文本(如果较长则提供摘要)、屏幕内容,以及单独列出——对用户有用的部分。如果视频内容夸张,如实说明。
B. 使用HyperFrames制作视频
使用哪个技能:
| 任务 | 技能 |
|---|---|
| 任何视频,起始点;不确定使用哪个时 | hyperframes(主要入口,自动路由) |
| 对镜头说话视频的字幕:每行1-3个单词,关键颜色,卡拉OK效果 | embedded-captions |
| 在人物头部视频上叠加图形:卡片、图标、“手机界面”插入、分屏、画中画圆形 | talking-head-recut |
| 约30秒内的无语音简短动画:开场、数字、标志、UI原型、前后对比 | motion-graphics |
| 视频结构:图层、每张卡片出现时间、视频插入 | hyperframes-core |
| 卡片滑入、贴纸、全屏单词“冲击”、动态排版 | hyperframes-animation |
| 镜头推进和拉出、平滑缩放 | hyperframes-keyframes |
| 音乐、音效、图标、处理插入 | media-use |
| 检查、渲染为MP4、背景移除(“从肩膀后方”插入) | hyperframes-cli |
| 现有效果(故障特效、五彩纸屑、图表)、语音下的音乐音量、颜色和字体 | hyperframes-registry、hyperframes-audio、hyperframes-creative |
根据HyperFrames规则,首先读取hyperframes技能;对于简单任务,其SKILL.md文件足够,无需引用其他。
使用脚本准备转录文本(精确的单词时间,使用GPU),而不是内置的hyperframes transcribe:
- 对于
embedded-captions:python scripts/transcribe.py <video> --out <工作文件夹>/transcript.json --format words——技能会拾取准备好的transcript.json; - 对于
talking-head-recut:同样使用--format flat(扁平的单词数组),跳过技能的转录步骤。 使用前,阅读转录文本并修正识别错误(姓名、品牌、术语)。向用户显示一行修正列表。
项目: 询问使用哪个文件夹。内部结构:sources/(源文件的副本——绝不修改或删除原始文件)、HyperFrames工作文件、done/(存放最终MP4)。
格式: Reels/Shorts/Stories/TikTok——1080×1920,9:16,30 fps;YouTube——1920×1080;动态帖子——1080×1350。
字幕和屏幕文字
- 字体必须包含文本所需的每个字形(重音符号、如果视频是多语言的则需要其他字母表)——渲染前检查。优先使用项目文件夹中的本地
.woff2文件,而非网络上的Google Fonts。 - 每行2-4个单词。不要以冠词、介词或连词(a、an、the、of、to、in、on、and、but)结尾——将其移到下一个单词。
- 数字用阿拉伯数字,使用弯引号和撇号,使用真正的长破折号。
- 全大写仅用于简短强调(1-3个单词),而非整个句子。
- 字幕不得遮挡面部或Reels/TikTok的底部UI区域(按钮、字幕)——保持在安全区内。将吸引点放在画面中央或稍下方,而非顶部边缘。
- 如果技能文件夹中的
brand.md已填写(字体、颜色、强调方式)——使用它。如果为空,向用户询问一次其风格,并提议将答案保存在那里。
在说“完成”之前
在长时间渲染前展示计划(内容、位置、风格)。渲染后,从结果中截取缩略图矩阵(A4)并自行查看:文字可读、不超出边缘、所有字形正常渲染、与语音同步。然后才将done/中的文件路径提供给用户。