Communitygithub.com

samyakiasonline-ctrl/hyperframe

在已有的访谈/播客/人物出镜视频上,叠加一系列精心设计的图形卡片(动态标题、下三分之一区、数据标注、引用、侧边栏、画中画),与逐字稿同步,支持16:9/9:16/4:5画布;原始视频完整播放,不受影响。

hyperframe 是什么?

Talking Head Recut 技能(通过 /hyperframes 入口路由)能够对一段已有的人物出镜视频进行图形化包装,在视频完整播放的基础上,叠加一系列与逐字稿严格同步的图形卡片——包括动态标题、下三分之一区置、数据标注、引用、侧边栏和画中画。该技能完全基于本地运行:使用系统 ffmpeg/ffprobe 提取音视频元数据,通过 hyperframes CLI 本地调用 Whisper 进行转录(无需任何 API 密钥),并由代理直接在对话中编写每张卡片的 HTML 和 GSAP 动画,最终合成一份完整的 composition HTML,渲染为 MP4。工作流程包含环境检查、工作目录创建、音视频提取、本地转录、字幕校正、故事板设计、卡片 HTML 编写、合成组装与渲染输出。关键中间文件(metadata.json、transcript.json、storyboard.json 等)均置于工作目录下,方便检查和调试。支持多种画布方向(横屏、竖屏、4:5)、五种卡片区域(全屏、白板区、下三分之一、侧边栏、视频覆盖),卡片数量和节奏根据视频时长和信息密度自动推导,最少5张以保证节奏感。

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/samyakiasonline-ctrl/hyperframe/tree/HEAD/.claude/skills/talking-head-recut

在你喜欢的 AI 中提问

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

文档

插件安装: 在执行 setup 或 freshness 命令之前,如果此技能位于 HyperFrames 插件内部,请遵循插件执行规则。独立安装则保留下方的更新说明。

首先,保持技能新鲜——与用户确认后再运行: npx hyperframes skills update talking-head-recut。如果一切已是最新,该命令为快速无操作;否则,它会在你依赖此技能之前,刷新此技能及其依赖的核心领域技能。

Talking Head Recut

Talking Head Recut 接收一段本地视频,完整播放,并在其上叠加一系列与讲话内容同步的、经过时间设计的图形卡片——标题、下三分之一区、数据标注、引用、侧边栏、画中画。代理设计每张卡片(时间轴 + 内容),直接在对话中编写每张卡片的 HTML,然后组装成一份合成 HTML,并通过 hyperframes 渲染为 MP4。没有固定的原型列表,也没有预设的卡片结构——叠加的图形完全来自逐字稿实际所说的内容。

入口是 /hyperframes。 本技能为一段已有的人物出镜视频添加设计的图形卡片(标题、下三分之一区、数据标注、引用、侧边栏、画中画)——而不是纯字幕(将口头内容显示为文字)。原始视频完整播放,不受影响。 任何其他意图——纯字幕、独立图形、从头生成视频——或任何不确定性 → 请先阅读 /hyperframes:意图层拥有所有路由决策权。

作为 embedded-captions 的图形包装兄弟技能。字幕是在播放的视频上添加_口语词_作为可读字幕;本技能是在播放的视频上添加_设计的图形_。纯字幕 → embedded-captions。从头构建视频 → 创作工作流(product-launch-video / faceless-explainer / ...)。

通过 /hyperframes 路由后,意图层仅确认输入内容(哪个视频)并声明渲染策略问题作为延后询问——画面比例、布局、风格组和卡片数量保留在第 7 步,届时探测到的素材和逐字稿将为推荐提供依据;该层的运行形态问题不适用。当存在 BRIEF.md 时,它包含已确认的输入和用户的任何注释——请优先阅读。

工作目录中的可检查中间文件:

  • metadata.json —— 时长 / 宽度 / 高度 / 帧率
  • audio.mp3 —— 提取的音频
  • transcript.json —— 扁平单词数组 [{ text, start, end }, …](Whisper 格式;没有 segments,没有 words 包装)
  • storyboard.json —— 轻量级卡片大纲(代理的计划)
  • public/cards/card-XX.html —— 每张卡片的 HTML 片段
  • public/index.html —— 最终的合成文件
  • output.mp4 —— 渲染后的视频

CLI 解析

# hyperframes —— 转录(本地 Whisper)+ 将合成的 HTML 渲染为 MP4
npx hyperframes --help

此技能完全运行在 hyperframes CLI 以及系统 ffmpeg / ffprobe 之上。转录是本地 Whisper,通过 hyperframes transcribe 完成——无需第三方服务、API 密钥或限速代理。

工作流程

1. 检查环境

npx hyperframes doctor          # ffmpeg, 无头浏览器, 渲染依赖
# 确认捆绑的静态资源:
ls "<SKILL_DIR>/assets/fonts" "<SKILL_DIR>/assets/vendor/gsap.min.js"

必要条件:

  • ffmpeg / ffprobe(系统安装)
  • <SKILL_DIR>/assets/fonts/*.woff2,<SKILL_DIR>/assets/vendor/gsap.min.js(已捆绑在此技能中,在第 9 步会放置到工作目录)

转录无需密钥——hyperframes transcribe 在本地运行 Whisper(第 4 步)。

macOS 上强烈建议为 hyperframes render 执行以下操作:

export PRODUCER_BROWSER_GPU_MODE=hardware

2. 创建工作目录

所有产物都存放在 videos/<project-name>/ 目录下——与其他视频工作流(product-launch-video / faceless-explainer / pr-to-video)的约定保持一致。保持当前工作目录在工作区根目录;以下所有内容都写入该子目录中。

VIDEO_PATH="/absolute/path/input.mp4"
WORK_DIR="videos/$(basename "$VIDEO_PATH" | sed 's/\.[^.]*$//')"
mkdir -p "$WORK_DIR"

3. 提取音频和元数据

# 元数据 —— 时长 / 宽度 / 高度 / 帧率
ffprobe -v error -select_streams v:0 \
  -show_entries stream=width,height,r_frame_rate \
  -show_entries format=duration -of json "$VIDEO_PATH" > "$WORK_DIR/metadata.json"
# 音频
ffmpeg -y -i "$VIDEO_PATH" -vn -acodec libmp3lame -q:a 2 "$WORK_DIR/audio.mp3"

输出:metadata.json(读取 width/height/duration;fps = 计算 r_frame_rate 分数,例如 30000/1001 → 29.97)+ audio.mp3。

4. 转录

npx hyperframes transcribe "$WORK_DIR/audio.mp3" -d "$WORK_DIR" --json --model small.en

本地 Whisper——无需 API 密钥、无需代理、无限速。将逐词的 transcript.json 写入工作目录(单词 text + start / end 时间戳)。读取它以获取驱动第 6 步卡片时机的单词/语句时间;根据需要自行根据标点/停顿将单词分组为语句以获取段落级片段。

截断到媒体时长。 Whisper 可能会返回最后一个词的 end 略微超出实际视频长度——将每个卡片的 endSec 和 composition.durationSeconds 截断到 metadata.json 中的时长,否则渲染将在视频结束后显示黑色尾巴。

5. 校对逐字稿

transcript.json 是一个扁平的单词对象数组——[{ "text": "...", "start": s, "end": s }, …](没有 segments 数组,没有 words 包装;每个单词的键是 text)。读取它并修正明显的 ASR 错误:

  • 同音词、产品名、技术术语、标点符号
  • 就地编辑单词的 text;保留其 start / end 时间戳
  • 没有预先分组的 segments 数组——自行将单词分组为语句(在终结标点/停顿处分隔),以便在卡片定时时需要段落级片段

6. 绘制轻量级故事板(在聊天中)

无需 CLI。 读取 transcript.json + metadata.json 并直接设计卡片。storyboard.json 是一个代理内部的规划产物——没有 CLI 命令会消费它;它存在的意义是让你在编写每张卡片的 HTML 之前,能清晰地思考时间和内容。保持以下示例的形状一致,以便相同的大纲可以驱动你在第 9 步创作的合成:

{
  "schemaVersion": 3,
  "composition": {
    "fps": 30,
    "width": 1080,
    "height": 1920,
    "durationSeconds": 121.2,
    "layout": "portrait",
    "themeId": "noir",
    "seed": 42
  },
  "videoTrack": {
    "sourcePath": "input-video.mp4",
    "startSec": 0,
    "endSec": 121.2,
    "bounds": { "x": 0, "y": 0, "width": 1080, "height": 1920 }
  },
  "subtitles": { "enabled": false },
  "cards": [
    {
      "id": "card-01",
      "intent": "用演讲者焦虑的午夜问题吸引观众",
      "startSec": 0.5,
      "endSec": 13.0,
      "accentIndex": 0,
      "zone": "fullscreen",
      "contentHints": {
        "kicker": "一个诚实的问题",
        "title": "深夜灵魂拷问",
        "detail": "客户 60 秒语音消息:‘如果人民币升值,是否意味着我的美元保单亏大了?’"
      }
    }
  ]
}

必需的卡片字段:

字段类型用途
id字符串稳定 ID,用于卡片 HTML 和 GSAP 选择器
intent字符串自然语言描述;输入给卡片合成
startSec / endSec数字以秒为单位的时间 (endSec > startSec)
accentIndex0 | 1 | 2 | 3 | 4此卡片从 5 个主题强调色中选择哪一个
zone枚举(见下文)卡片在画布上所处的位置
contentHints对象自由格式的袋;代理在此处放置 kicker/title/detail/data/quote
archetype (可选)字符串自由格式标签,可附加以记住卡片模式;缺失即自由格式,为默认值
transition (可选)枚举: cut | fade | slide | wipe声明式卡片间切换动画

五个 zone 值:

zone解析后的边界使用场景
fullscreen覆盖整个画布高光时刻、大数字、口号
whiteboard-area内边距 40px (或竖屏高度的 45%)密集数据 / 注解内容
lower-third底部 30% 带状区域在可见视频上的标注
side-panel右侧 42% (横屏) 或底部 40% (竖屏)数据侧边,视频另一侧
video-overlay全画布,期望卡片大部分透明在满铺视频上的注释叠加

当你在第 9 步组装合成时,将每个卡片的 zone 按照上表解析为卡片宿主包裹层的像素边界。视频边界在合成级别(videoTrack.bounds)设置一次;为了让视频看起来“在卡片之间移动”,在合成的 <script> 中编写针对 #video-wrap 的 GSAP 补间(参见第 9 步)。

没有预设的卡片角色,没有预设的叙事弧线。 卡片内容来源于视频实际所说的内容——可以全是引用或全是数据,可以以数字开头或以故事开头。让逐字稿驱动节奏。

多少个信息点?——根据时长和密度自动推断。 没有固定的上限。根据视频时长选择一个基础节奏,然后根据信息密度调整。唯一固定的下限:最少 5 张卡片,以确保即使很短的视频也有节奏感。

第 1 步——按时长确定基础节奏(中等密度下自然的秒数/卡片):

视频时长基础节奏(秒/卡片)理由
< 60s(短视频)6–8s观众在短内容中期待快速切换
60s – 3 分钟8–12s正常的社交媒体节奏
3 – 10 分钟12–20s给予呼吸空间;每张卡片承载更多内容
10 – 30 分钟20–35s长时讲座 / 访谈节奏
> 30 分钟30–60s间歇式、接近章节感

第 2 步——密度乘数(乘以基础节奏):

逐字稿中的信号乘数效果
高密度 —— 大量数字、多个不同的主张、断奏式节奏、列表式枚举、每 1-2 句话一个新想法× 0.7切换更快,更多卡片
中密度 —— 数据和叙述混合的流动× 1.0基础节奏
低密度 —— 一个长篇故事、重复阐述、缓慢反思性节奏、单一论点逐步展开× 1.5切换更慢,更少卡片

第 3 步——计算:

secPerCard = basePace × densityMultiplier
cardCount  = max(5, round(videoDurationSec / secPerCard))

示例(注意——无上限限制;长视频自然会产生更多卡片):

  • 30 秒短视频,单一爆点(低密度) → 7 × 1.5 = 10.5s/卡片 → round(30/10.5)=3 → 取底为 5 张卡片
  • 60 秒反思独白(低密度) → 10 × 1.5 = 15s/卡片 → 4 → 取底为 5 张卡片
  • 121 秒人物出镜,丰富数据(高密度) → 10 × 0.7 = 7s/卡片 → 17 张卡片
  • 5 分钟访谈,混合密度 → 16 × 1.0 = 16s/卡片 → 19 张卡片
  • 10 分钟深入讲解,高密度 → 16 × 0.7 = 11s/卡片 → 55 张卡片
  • 30 分钟讲座,中密度 → 28 × 1.0 = 28s/卡片 → 64 张卡片
  • 1 小时播客,低密度 → 45 × 1.5 = 67.5s/卡片 → 53 张卡片

当一张卡片持续超过 ~15 秒时,计划制作更丰富的卡片(数据块、多步揭示、几个子点以交错动画展开)——静态的一句话在 8 秒后就会变得枯燥。对于长内容,如果许多卡片超过 30 秒,考虑将时间线拆分为子合成(每章节一个 .html,使用 data-composition-src 挂载),以便每个文件的 GSAP 时间线保持可管理——参见 HyperFrames 的 timeline_track_too_dense lint 警告。

contentHints 是一个自由格式的对象;其键和嵌套可以采用任何能够捕捉数据的形状。代理自行决定每个卡片的形状。

可选结尾。 本技能没有内置固定的品牌结尾。如果用户想要一个结束卡片,请自行设计一个中性卡片(文字商标 + 一行标语,约 1.5-2 秒,淡入 -> 短暂停留 -> 淡出),将其追加到 cards[] 中,并将 composition.durationSeconds 延长至其结束时间。

...(后续内容截断)

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

samyakiasonline-ctrl/hyperframe

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet `anchor` rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

samyakiasonline-ctrl/hyperframe

Turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video: there is no site or footage to capture, so the visuals are invented per scene (typography, abstract graphics, diagrams, data-viz). Use for topic explainers, concept breakdowns, how-tos, listicles. Not a video built from a website (/product-launch-video — promo or tour). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Import Figma content into a HyperFrames composition — rendered assets, brand tokens, components, storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI), connector-assisted motion when available, and shaders from a connector or native export. Use when the user pastes a figma.com link or asks to bring a Figma design, frame, logo, brand, or animation into a video/composition.

samyakiasonline-ctrl/hyperframe

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

samyakiasonline-ctrl/hyperframe

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

samyakiasonline-ctrl/hyperframe

Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes drawn on a track's volume or any effect parameter, or one submix bus carrying a chain, a fader and an automation clock for several tracks at once (`<hf-audio-group>`). Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.

samyakiasonline-ctrl/hyperframe

Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, timeline, history, clean, docs, benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local, HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.

samyakiasonline-ctrl/hyperframe

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

samyakiasonline-ctrl/hyperframe

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

samyakiasonline-ctrl/hyperframe

Use when a HyperFrames composition needs a punch-in, punch-out, zoom, reframe, Ken Burns treatment, camera move, visual match/whip handoff, or other seek-safe 2D/3D keyframes; also for GSAP, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics. Don't use for broad scene strategy, brand design, media sourcing, captions, or general video planning.

samyakiasonline-ctrl/hyperframe

Search, install, and wire registry blocks and components into HyperFrames compositions. Use BEFORE hand-building any named visual — whenever a brief, a user, or a storyboard names a look, effect, treatment, or transition such as CRT scanlines, glitch, chromatic aberration, film grain, a shimmer sweep, a chart, a code or terminal window, a map, or a confetti burst — because roughly 400 hosted items already cover many of them and the search ranks all of them with nothing installed, no project, and no account. Also use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

samyakiasonline-ctrl/hyperframe

Mandatory entry point: read this first for any request to make, create, edit, animate, or render a video, animation, or motion graphic, including a promo, explainer, captioned clip, title card, overlay, slideshow or interactive deck, Remotion port, or any HyperFrames HTML composition. Also use it to inspect, diagnose, validate, preview, publish, or batch-render an existing HyperFrames project. Inputs may be a website URL, GitHub PR, Figma design or URL, text or brief, existing footage, or music. It resumes project state, captures intent when applicable, selects and installs the owning workflow, and routes domain capabilities. HyperFrames is the default output framework unless the user explicitly chooses another framework for the deliverable or asks only to record a browser session.

samyakiasonline-ctrl/hyperframe

Use when working with a person on a HyperFrames project in Studio: first, whether their message asks for a change at all (questions, loose ideas and "don't change anything" get an answer and a plan, not an edit); for a new film, the plan, storyboard and build order that the HyperFrames launch films follow; and how the timeline should be laid out so it reads well (one caption track, one element kind per track, every scene a sub-composition) and where captions and key content may sit (safe zones). Don't use for how to perform an individual edit (split, trim, retime, volume, copy, swap): that is `creator-editing-recipes.md` in `/hyperframes-core`.

samyakiasonline-ctrl/hyperframe

Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal.

samyakiasonline-ctrl/hyperframe

A short, design-led motion graphic where motion is the message — kinetic typography, stat count-up, chart/data-viz hit, logo sting / brand lockup, lower-third / callout / social overlay, animated map (highlight regions, connect places, zoom to a location), animated tweet / news-article / headline, webpage / UI animation (scroll, cursor, callouts), or fusing a real image's geometry into a chart. Usually under 10s (up to ~30s), no narration or live-action subject; renders to MP4 or transparent overlay. Longer / narrated / multi-scene → /general-video. Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Turn a product or marketing URL, pasted script, or brief into a product launch / promo video — SaaS promos, feature reveals, product demos, app and company launches. Use when the user wants to market, launch, promote, or reveal a product; the default for any commercial URL. Site tours / showcases of a website route here too — the brief carries the show-it-as-is intent. Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Turn a GitHub pull request (a PR URL, owner/repo#N, or 'this PR' in a checked-out repo) into a code-change explainer video — changelog, feature reveal, fix, or refactor walkthrough built from the diff, commits, and files: the input is a code change, not a website. Not a product promo (/product-launch-video) or a no-PR topic explainer (/faceless-explainer). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Port an existing Remotion (React) composition''s source to HyperFrames HTML. Use ONLY on an explicit ask to port/convert/migrate/translate a Remotion source — one-way, Remotion-only. A passing Remotion mention, reference-only code, or "make something like my Remotion video" is a fresh build (/general-video). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Author a HyperFrames slideshow — a presentation, pitch deck, or interactive deck with discrete slides, fragment reveals, branching, hotspot navigation, and built-in presenter mode with speaker notes; also converts an existing page into a deck. Output is a navigable deck, not a rendered MP4. If the user didn't explicitly ask for a slideshow, confirm before authoring. Unclear → /hyperframes.

相关技能