Docs & Knowledge · heygen-com/hyperframes

slideshow

Name: slideshow
Author: heygen-com/hyperframes

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.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit

Author heygen-comGitHub heygen-com/hyperframes ↗Stars 44283License Apache-2.0（仓库根 LICENSE 为 Apache License Version 2.0；池内值亦为 Apache-2.0）Commit d2f0bc7f34

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Artifact definition precedes everything: Deliver a "live deck" rather than an MP4, and explicitly forbid passing the deck to hyperframes render — because a deck is composed of multiple top-level scenes without a master root, render only parses the first composition and silently truncates it into a short clip.

skills/slideshow/SKILL.md

**Do not `hyperframes render` a slideshow into a single MP4.**

What this does: Establishes a red line against the most common silent error during rendering (e.g., a 40-second deck outputting only 6 seconds), and marks linear export as "deferred" — prior to that, the only supported outputs are the live deck via present and slide-by-slide snapshots.

The implementation mechanism is "standard compositions + a declarative JSON island": Compositions remain HF scenes/clips/GSAP; the additional piece is an application/hyperframes-slideshow+json block, which the player's SlideshowController reads to turn continuous timelines into a discretely navigable deck.

skills/slideshow/SKILL.md

A HyperFrames slideshow is a normal HyperFrames composition — scenes, clips, GSAP timelines — with one extra ingredient: a **JSON island**

What this does: Consolidates discrete navigation capabilities into data (slide order, notes, fragment timestamps, hotspots, branch sequences) rather than relying on custom navigation scripts — thus establishing the island as the single source of truth.

The island must be a physical DOM block, placed flexibly but positioned early in the body: present statically parses the composition HTML; if the manifest is hidden behind other script tags and generated at runtime, present will fail to read it.

skills/slideshow/SKILL.md

The `present` command reads the composition HTML statically and expects the real `application/hyperframes-slideshow+json` island to already be present.

What this does: Blocks "dynamically injecting the island" — an approach that looks cleaner but breaks present — and enforces an exact match between sceneId and data-composition-id (which lint uses for parsing).

Fragments are reveal stops at **absolute composition time**, and navigation is driven by deterministic seeks rather than playback: Entering a slide with fragments immediately seeks to fragments[0] and pauses; Next sequentially seeks to the subsequent stop.

skills/slideshow/SKILL.md

Navigation is seek-driven, not play-driven.

What this does: Converts slide flipping from playback semantics into addressing semantics to ensure bi-directional reliability; it also stipulates that slides without fragments rest on an internal static frame (typically the midpoint) rather than slide.end.

Branches are real scenes that simply aren't listed in the main sequence: Clicking a hotspot pushes {sequenceId, slideIndex:0} onto the stack to enter the branch entry, back pops the stack to return to the parent slide, and backToMain clears the stack; breadcrumbs and counters are rendered per sequence scope.

skills/slideshow/SKILL.md

Clicking a hotspot pushes `{sequenceId, slideIndex: 0}` onto the nav stack and enters the branch's first slide.

What this does: Implements "Q&A-style jumps" using an explicit navigation stack, and forbids adding branch sceneIds into main slides (which lint flags as overlaps).

Authoring discipline is a hard constraint rather than a suggestion (full-sentence headlines, one idea per slide, lead with the hardest-hitting point, bottom-up market sizing, minimum font sizes, and searching the live catalog for off-the-shelf blocks before writing), complete with rationale: Non-compliant slides are replaced outright during review.

skills/slideshow/SKILL.md

**Headline is a complete-sentence claim, not a label.**

What this does: Deconstructs "presenting like to an investor" into verifiable rules (72–96px headlines, 48px body, no critical text below 40px), emphasizing that catalog search requires no setup or installation.

Porting existing pages requires fidelity down to the mechanism level: Native media elements serve as the single source of truth, visual states are derived from media events and media.currentTime, font tokens must resolve to concrete font stacks, and screenshot-type evidence must use contain at its native aspect ratio rather than cover.

skills/slideshow/SKILL.md

Treat native `<video>` / `<audio>` elements as the source of truth for any custom media chrome, canvas visualizer, waveform, beat grid, or playhead.

What this does: Enforces "reproducing interaction details" as a contract (migrating custom players, visualizations, and scroll-driven camera movements), while ensuring common behaviors live in the player/controller rather than in ad-hoc deck scripts.

Presenter mode is owned by shared components: Present button / P key, opens a new audience tab, synchronized across tabs via BroadcastChannel; speaker notes are edited in the presenter view and stored in localStorage (overriding the manifest without mutating the composition file).

skills/slideshow/SKILL.md

**Presenter mode:** use the built-in Present icon button in the slideshow nav capsule, or press P.

What this does: Explicitly forbids building custom Present buttons, mute toggles, or speaker notes scripts (shared components govern placement, icons, styling, and audience-mode hiding), offering actionable guidance for Meet/Zoom sharing (share the audience tab, not the entire screen).

Media cleanup and muting are controller responsibilities with cross-realm nuances: The controller calls stopMedia on slide/sequence transitions; fragment navigation within the same slide does not clear media; iframe media cannot be tested with the parent page's instanceof (returns false in real browsers).

skills/slideshow/SKILL.md

The slideshow controller owns slide-exit media cleanup.

What this does: Clearly delineates responsibility boundaries for pause/mute to prevent individual decks from writing custom cleanup scripts, emphasizing that such fixes must be verified in real browsers rather than single-realm unit tests.

The standalone harness is an interim solution rather than the standard path: Until the engine-managed path (preview --slideshow / studio present mode) lands, running demos via a bare player requires three workarounds (exposing a seekable root timeline, copying the island into the wrapper, and letting the wrapper own audio).

skills/slideshow/references/standalone-harness.md

These patterns are a **temporary workaround** for standalone demos.

What this does: Provides an implementation reference with a comprehensive pitfall checklist (island not copied → nav bar fails to render; wrapper SFX placed in iframe → silence; missing self-clock → landing on wrong slide; Three.js occlusion → 3D invisible), while reiterating that most of this collapses once the native engine path lands.

2Core Capabilities

01JSON island authoring: An application/hyperframes-slideshow+json block declaring main slides, branch slideSequences, per-slide notes / fragments / hotspots (TTS fields reserved)

02Fragment reveals: Declares multiple reveal stops within a slide as absolute timestamps; navigation seeks point-to-point and pauses without playing

03Branch navigation: Hotspots (with percentage bounds or fallback full-slide buttons) trigger branch sequences, supporting back / backToMain, breadcrumbs, and sequence-scoped counters

04Presenter mode: Present button / P key opens an audience tab; presenter view features current thumbnail, next slide preview, notes, and timers; synced via BroadcastChannel; note edits persist to localStorage

05Presentation & delivery: Local server via present (including package.json dev script examples), Meet/Zoom sharing guides, automatic media cleanup on slide transitions, and optional global mute overriding iframes and top-level audio

06Source page porting: Preserves original site visual, motion, interaction, and media behaviors, remaps scroll-driven camera moves to slide navigation, and displays screenshot-based evidence with aspect-ratio contain

07Structural validation contract: lint checks sceneId resolution, hotspot target validity, fragment bounds, and main timeline non-overlap; check executes runtime validation

08Standalone harness (interim): Parent wrapper copies island, compositions expose root timeline + visibility controller, postTimeline message bridge, independent Three.js rAF loop, audio unlock, and self-hosted SFX

09Confirmation gate: Prompts with "Do you want this as a HyperFrames slideshow?" when not explicitly requested, treating wrong artifact deliverables as a quality failure rather than a preference

3External Dependencies

Kind	Dependency / Endpoint
cli	官方 hyperframes CLI：present（起 deck 服务与讲者/观众同步）、lint、check、preview、snapshot（逐页静帧）
package	播放器构建产物（本仓 packages/player/dist 的 hyperframes-player / hyperframes-slideshow 全局包；改播放器行为后需在 packages/player 跑 bun run build）
network	CDN 资源（harness 示例）：Three.js 模块从 jsdelivr 导入，供独立 demo 的 3D 背景层使用（产物期由浏览器拉取，按范式不判级）
package	浏览器平台 API（非外部服务）：BroadcastChannel 讲者/观众同步、localStorage 备注持久化、postMessage 与 iframe 播放器通信、WebAudio/Audio 自持音效
package	兄弟 skill 关联：deck 内容来自 Figma 时必须先跑 /figma（资产导出/品牌令牌/分镜重建），基础合成契约在 /hyperframes-core，词级字幕规则在 /embedded-captions
cli	官方 registry 搜索/安装（写页面前先 catalog 查现成视觉积木，需要时 add 进 deck）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Execute local scripts or commands: No bundled scripts inside this skill directory (contains 2 files: SKILL.md + references/standalone-harness.md); ha
网络端点: Declare external network access: Artifact runtime (unrated per conventions, logged only): harness Three.js sample imports three@0.160.0 from cdn.jsdelivr.net, fetched by the browser
本地工作目录: File I/O and artifact output: Project files (authored by agent): composition HTML (containing island and scene divs), wrapper/index.html, and composition/

Audit Notes: Grading target = skill directory itself: 2 markdown files, zero scripts, zero network calls, zero credential reading, zero write instructions. Global HTTP(S) scan matches only 1 location — the three@0.160.0 CDN import in the harness sample (fetched by the browser at artifact runtime; unrated per conventions, logged in reason and network_calls). Capability implementation relies on "authored data + local CLI and server": writing composition HTML/JSON islands, serving/validating locally via npx hyperframes present/lint/check/snapshot, and running artifacts through packages/player/dist player bundles from this repo. This falls under "local CLI and local read/write only", matching repo precedents hyperframes-core (Blue) and talking-head-recut (Blue). Does not qualify for Orange: no credential/environment variable access, and does not transmit user assets to external generation backends (no TTS/image generation calls; TTS fields in the island are explicitly reserved). Does not qualify for Red: no sandbox disablement, TLS downgrades, anti-automation bypass, or arbitrary code execution surfaces (sample code serves as human-adoptable reference implementations, not auto-executing scripts).

5Second-Pass Verification

[ok] 网络面是否真如声明（蓝档判定的关键反例检查） — 全目录仅 1 处 http(s) 命中：standalone-harness.md 第 895 行的 three@0.160.0 jsdelivr 导入（示例代码块内）；无 fetch(、无 process.env、无 child_process、无凭证关键词。SKILL.md 侧只有本地命令（present/lint/check/preview/snapshot）与浏览器 API（BroadcastChannel/localStorage/postMessage），均为本地或浏览器内行为。
[ok] 「禁止 render」的声明是否与机理自洽（不是随口警告） — SKILL.md 给出原因：deck 由多个顶层 scene 合成（每页一个 data-composition-id）且**没有 master-root 合成**，所以 render 只解析第一个合成，产出静默截断的 MP4（举例 6s/40s）；并说明线性导出（仅主线、排除分支）目前是 deferred，故支持输出为 present 活 deck 与逐页 snapshot。声明与结构描述一致。
[ok] island 的「静态可读」要求与 present 行为是否一致 — 文档明确 present 静态解析合成 HTML、期望真实的 application/hyperframes-slideshow+json 已存在，并禁止用另一个 application/json 块 + 运行时代码生成 island。这与「JSON 岛是唯一真源、sceneId 必须匹配 data-composition-id」的 lint 契约自洽。
[ok] harness 内容是否被当成正统做法（避免误判为「本 skill 主张两套实现」） — harness 开头即写 interim framing（临时绕行）与「When that path ships, most of what follows collapses」，SKILL.md 亦写「Do not treat the patterns there as the blessed model」。两处口径一致，属过渡文档而非第二套正统。
[ok] 是否存在夸大（把引擎/播放器能力算作本 skill 能力） — 文档反复把导航、presenter mode、媒体清理、静音归给共享播放器组件（<hyperframes-slideshow> / SlideshowController / hyperframes-player.stopMedia），本 skill 只声明 island 数据契约与写作/移植纪律，未见据他人之功。

6Verdict & Scenarios

Clear deliverable definition with mechanical explanations, preventing the most common misuse of trying to extract MP4s via render

Consolidates discrete navigation into declarative data (island) and enforces implementation constraints around the single source of truth (prohibiting runtime generation and sceneId/data-composition-id mismatches)

Deterministic navigation semantics: Fragments are absolute time stops and navigation is seek-based rather than playback-based, preserving state during forward/backward stepping

Strict shared component boundaries (Present buttons, mute toggles, notes, and media cleanup must not be custom-built), ensuring consistent behavior across Studio, present, and custom demos

Transparent about work-in-progress areas (standalone as interim, linear MP4 export as deferred) with practical pitfalls (cross-realm instanceof, background tab throttling, Zoom full-window lag) documented in references

Best for: Ideal for creators needing presentation-ready decks: fundraising/sales pitches, internal reviews, lectures, or tech talks requiring discrete slides, step-by-step reveals, Q&A branching (hotspot jumps to appendix slides and back), speaker notes, and multi-screen audience sync. Also suited for converting existing web pages (featuring custom players, visualizations, and scroll animations) into high-fidelity interactive decks, or serving locally via present for client delivery.

Not for: Not suitable for: 1) Scenarios requiring MP4/video file delivery (explicitly unsupported; linear export is deferred — use /general-video or dedicated workflows for video); 2) Presentations requiring voiceover narration (TTS is unwired; use audio workflows such as /hyperframes-audio); 3) Single static images or posters (snapshot or other skills are more direct); 4) Users expecting an out-of-the-box Studio GUI editor workflow (this skill recommends final delivery via present rather than Studio); 5) Those unwilling to maintain front-end web artifacts (decks are live web pages whose longevity relies on player packages and browser behaviors).

Install Agent-Ready

① Verified Mirror 2026-09-28

Option A · Direct DownloadDownload slideshow.tar.gz

sha256: 034ea590dd179243…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d2f0bc7f34.