Communitygithub.com

samyakiasonline-ctrl/hyperframe

在現有的單一主體談話性影片中加入字幕或說明文字,而無需編輯原始素材。用於純逐字字幕、嵌在主體後方的電影級字幕、VFX 字幕、「炸/特效/酷炫字幕」,或從 35 種風格目錄中選取指定的視覺識別。

hyperframe 是什麼?

這個 AI 助手技能專為將字幕或說明文字嵌入單一主體的談話性影片而設計,其核心是基於視覺識別進行路由,而非底層引擎。它預設使用「錨點」(anchor)軌道,這是一種低調的逐字字幕,僅在用戶明確要求完整的電影級效果時,才會將每個詞彙嵌入主體後方。此技能支援三種主要模式:標準模式(預設)結合了前景的逐字字幕軌道和關鍵字詞的嵌入效果;電影模式則完全使用嵌入效果,適合營造氛圍;主題模式則提供如「ordnance」「stardust」等完整的視覺主題包。整個工作流程完全在本地端執行,包括語音轉寫和主體去背,用戶需在使用前將多鏡頭素材分割開來。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/samyakiasonline-ctrl/hyperframe/tree/HEAD/.claude/skills/embedded-captions

在你喜歡的 AI 中提問

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

說明文件

外掛安裝: 在執行設定或更新命令前,當此技能位於 HyperFrames 外掛內部時,請遵循外掛安裝規則。獨立安裝則保留下方的更新說明。

首先,保持此技能為最新狀態 — 在執行前先與用戶確認: npx hyperframes skills update embedded-captions。如果一切已經是最新,則快速無操作;否則,它會在你依賴之前,先更新此技能及其依賴的核心領域技能。

嵌入式字幕

一個目錄,預先選定(CATALOG.md — 35 種識別;其背後的引擎是實作細節)。標準(預設)會建構一個乾淨的逐字 軌道(承載大部分文字的下方三分之一字幕)+ 一個在高峰時合成到場景中主體背後的 嵌入高潮。電影級是純嵌入 — 沒有軌道,每個字幕都合成在主體背後(英雄字體排版、堆疊、遮擋效果)。主題是一個完整的主題式構成 — 主體範例 × 英雄場景 × 前景特效 × 底板反應,由註冊表(themes/README.md)組成:ordnance terminal neonsign stardust stomp。大多數的說明/配音是 標準;嵌入是稀缺且應得的巔峰 — 將每個詞都嵌入是常見錯誤;主題則適用於 VFX 等級的需求(「炸」、「特效」、「像 AE 做的」)。


執行環境先決條件

外掛安裝使用已捆綁、清單鎖定的 CLI 來進行去背、轉寫和渲染;無需原始碼簽出。本地預覽和字幕測量輔助工具還需要 Sharp、Puppeteer(及其 Chromium 瀏覽器)和 GSAP。請將這些安裝在字幕專案中,而非唯讀的外掛內部:

npm install --prefix <project> --save-dev --save-exact [email protected] [email protected] [email protected]

保留專案的 lockfile。如果這些依賴已存在,則使用其鎖定的版本,而不是覆蓋它們。Bash 和 FFmpeg/ffprobe 必須在 PATH 中。去背和轉寫可能會在首次使用時下載其自己的模型。

渲染會等待 CLI 成功退出後才進行合成。不再使用舊的 HF_TIMEOUT_S shell 看門狗:大的部分檔案並不能證明渲染完成。一個明確的建構簽出參數或 HYPERFRAMES_ROOT 會選擇貢獻者 CLI 而非外掛鎖定。如果需要取消卡住的渲染,請透過 CLI/終端機正常進行;字幕輔助工具不會強制終止或從進程快照中恢復渲染。

操作流程(TL;DR)

經過 /hyperframes 路由後,意圖層僅確認輸入(哪個片段)並宣布識別選擇作為延後詢問 — 候選清單需要已探測的片段,所以它停留在下面的步驟 1;該層的運作形狀問題不適用(素材未經修改,也沒有情提要審查)。當 BRIEF.md 存在時,它承載已確認的輸入和任何用戶註記 — 請先閱讀它。

下面的工藝散文很長;管線本身很短 — 並且所有確定性的事情都是計算或編譯出來的,絕非手寫:

  1. 決策關卡(拒絕不良片段)→ 從 CATALOG.md 選取一個識別(35 種識別;引擎/編譯器透過查表取得 — 切勿提出模式/類別問題)
  2. hyperframes init(如果專案目錄已存在且包含影片,則跳過 — matte.cjs/transcribe.cjs 會將目錄中的任何影片作為 source.mp4 採用)→ bash scripts/prepare.sh <project>(去背 ∥ 轉寫 ∥ 音訊包絡 並行處理,然後是帶有場景調色板/光學/照明的安全區域 v2 — 一個命令,無遺漏)
  3. 編寫一個小的創意選擇 JSON(先讀取 safe-zones.json):電影級 → cinematic.json → make-cinematic.cjs(衍生 plan.json 並編譯它);主題 → theme.json → make-theme.cjs(軌道/面板/詩篇/接管範例;anchor 是低調軌道預設值)
  4. 視覺 QA:node scripts/preview-frames.cjs <project> → 約 2 秒/幀的忠實合成預覽(無需渲染)。在支付渲染費用前檢查 § 視覺 QA。
  5. render-and-composite.sh → 關卡(時間/遮擋+英雄/溢出/交接)→ final.mp4

人們經常忽略的承載規則:

  • 軌道(預設)+ 嵌入(升級)。 drop(填充詞,不顯示)/ rail(逐字下方三分之一字幕,在前景,承載大部分文字)/ embed(合成在主體背後的巔峰詞彙)。標準模式兩者都做,僅嵌入巔峰。請參閱 § 字幕模型。
  • 影片以「未經修改」的狀態交付(標準/電影級;主題模式的 PLATE 預算是唯一的例外 — 由註冊表閘控的反應拍(charge-dim、punch、shake、grain)根據每個主題的 DNA 定義,並在去背合成後應用,使主體+文字+底板作為一個框架移動) — 只添加字幕;去背只是為了讓主體遮擋嵌入軌道。切勿對素材進行調色/重新上色/掃描線處理。
  • 兩本規則書:軌道 → references/rail.md(簡潔),嵌入工藝 → references/composition-craft.md(豐富,僅嵌入)。根據需求瀏覽。

字幕模型 — 軌道 + 嵌入

每個口語短語都是以下三種之一:

什麼如何顯示
drop填充詞 — 嗯/呃、口吃、自我修正不顯示
rail預設 — 一般口語內容(逐字)乾淨的下方三分之一字幕,在前景,可讀。一個重點詞可以獲得內聯的 emphasis 高亮(強調色 / 動態詞彈出)— 它仍保留在軌道上。
embed一個被升級的巔峰 — 標題性的節拍一個大字合成在主體背後(去背遮擋),設計入場 + 出場

軌道承載大部分文字;嵌入是稀缺且應得的巔峰。 稀缺性是每個節拍/區塊,而非每個片段:每個區塊 ≤1 個英雄(想法),永不兩個同時可見,英雄窗口之間至少有一個節拍的間隔(編譯器會對低於 0.6 秒的間隔發出警告)。一個短片段 → 通常 1–2 個;一個長的說明 → 大約每個章節一個。在多個英雄中,最大的一個是 APEX(它獨自獲得完整的鎖定嵌入 + 寬度適配提升);較小的則是次要巔峰,它們作為加大尺寸的強調行(前景,阻尼運動)沿著其列移動 — 並非每個節拍都需要去背展示,這正是保持巔峰成為一個事件的原因。將每個詞都嵌入仍然是常見錯誤。

軌道表面識別建構的就是這個(軌道 = rail.html,嵌入 = index.html 中的高潮)。列流識別會放棄軌道,讓所有東西都變成嵌入風格 — 僅在需要氛圍勝過逐字要求時推薦它們,永遠不要用於說明/配音,因為文字必須可讀(CATALOG.md 為每個識別編碼了這點)。

步驟 0 — 從目錄中選取一個識別

一個前端,三個後端。 用戶從 CATALOG.md(35 個條目:10 個經典 + 25 個主題)選取一個識別;引擎、編譯器和編寫檔案透過從目錄行查表來衍生。切勿將「標準 vs 電影級 vs 主題」作為問題提出 — 那些是後端名稱(一個產品即使有多個引擎也只有一個 UX)。目錄編碼了路由所需的一切:閱讀表面、語調、推薦用途、場景需求、以及真正接近配對的相鄰註記(loud↔ordnance, neon↔neonsign, cream↔stardust)。

識別選擇是一個偏好關卡(../hyperframes/references/brief-contract.md § 1):在自主模式中(「給我驚喜」/「替我決定」),從你的候選清單中自行選取,並說明一行原因,而不是詢問。

流程:探測片段 → 從目錄中篩選 2–3 個識別 → 推薦一個並附上一行原因 → 用戶選擇(自主模式:你選擇,說明原因)→ 編寫該識別的檔案。識別是引擎鎖定的(無交叉組合;開啟一個是驗證事件 — 請參閱 dna/README.md)。

在編寫之前,務必提出你的推薦並讓用戶選擇。 不要默默使用預設值。

(完整的識別表格位於 CATALOG.md — 路由的單一事實來源。下面的引擎文件描述了每個後端的編寫合約。)

CATALOG.md 是這裡的完整答案空間:此工作流程不會搜尋 HyperFrames 元件註冊表。 合成工作流程在編寫命名外觀之前會執行 npx hyperframes catalog;這個工作流程則不應這樣做。它的引擎是鎖定的編譯器,會消耗 cinematic.json / theme.json 並自己發出合成結果,因此註冊表項目 — 包含 caption-* 區塊 — 沒有東西可以掛載進去。註冊表區塊在設計好的畫布上為文字設定樣式;此技能透過去背將字幕燒錄到某人的素材中。當沒有識別符合要求時,說出來並選擇最接近的,而不是求助於目錄之外。

推薦啟發法:使用 CATALOG.md 中的「篩選啟發法」 — 它們是識別層級的(例如「炸」會篩選出 ordnance/stomp/terminal/loud 並根據應該爆炸的內容來選擇),絕非類別層級。不確定時 → anchor。

  • 電影級 → 為鎖定的模板編寫 cinematic.json,由 make-cinematic.cjs 編譯。
  • 主題 → 閱讀 themes/README.md,編寫 theme.json,執行 scripts/render-theme.sh(編譯 + 渲染 + 底板反應 → final_fx.mp4)。

決策關卡 — 優先執行

在任一種模式前,先探測影片並分類場景。

ffprobe <video.mp4>                    # 規格
ffmpeg -ss <t> -i <video.mp4> -vframes 1 sample.png   # 在 20/50/80% 處

讀取樣本。在以下情況拒絕:

  • 多位說話者 / 有硬切(先分割再渲染每個鏡頭,或直接拒絕)
  • 沒有人類主體(此技能專為談話性影片設計)
  • 少於 3 秒,沒有語音,或臉部從未清晰可見 — transcribe.cjs 會在音訊接近靜音時發出警告(Whisper 可能會在靜音上幻覺出像「Thank you.」這樣的詞);請注意並拒絕,而不是為虛構的文字加上字幕
  • 來源已帶有內嵌字幕 / 說明文字 / 厚重的文字圖形 — 加上第二個字幕系統會造成衝突,且素材必須保持未經修改(無法遮蓋/修復)。燒錄的文字通常只在片段中間出現:取樣一個 1fps 的連拍表(ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png),不要只相信 3 個隨機幀。
  • 轉寫結果是垃圾 — 非母語/口音重的語音可能會被轉寫成自信的胡言亂語。在編寫前先理智閱讀 transcript.json;如果它無法解析為語言,請嘗試 WHISPER_MODEL=medium 一次,否則拒絕(一段逐字軌道但充滿虛構的文字比沒有字幕更糟)。
  • 手持攝影且快速移動(去背會閃爍)

預飛行探測(幾乎不耗費成本,防止最嚴重的失敗)

  1. 鏡頭切換探測。 在 20%、50%、80% 處取樣幀。如果出現不同的主體/場景,在切換處裁剪片段。
  2. 信箱/柱箱探測。 第一幀有黑條?計算安全內容矩形並將字幕放置限制在其內。
  3. 亮度探測。 取樣字幕區域的平均亮度 — 低於 60 → 淺色文字保持原樣可讀,60-180 → 添加文字遮罩,180+ → 不透明文字 + 遮罩(永遠不要使用裸淺色文字)。電影級模板是奶油色+screen 且已鎖定 — 使用這個探測來_選擇一個適合的識別_(明亮場景 → ink,或具有不透明軌道的 anchor 主題),而不是重新著色其中一個。
  4. 根據語調推薦識別(你推薦;用戶選擇 — 請參閱步驟 0 + CATALOG.md)。 說明/訪談/必須閱讀的文字 → 軌道/面板表面識別;詩意/社交/「電影級」 → 按變化層次的列流識別;「炸 / 特效 / VFX」/ 命名世界 → 主題識別。不確定時 → anchor(文字可讀,場景安全)— 但提出一個候選清單並讓用戶選擇。

管線 — 5 個步驟

1. hyperframes init <project> --non-interactive --video <video.mp4> --skill=embedded-captions
2. bash scripts/prepare.sh <project>       # 去背 ∥ 轉寫(並行)→ 安全區域。單一命令。
                                           #   → frames_fg/ transcript.json safe-zones.json
3. [代理步驟 — 唯一的創意步驟] 編寫一個小的 JSON;請根據模式參考下方
   電影級:編寫 cinematic.json → node scripts/make-cinematic.cjs <project>
   主題:   編寫 theme.json → bash scripts/render-theme.sh <project>   (編譯 + 渲染 + 底板特效)
4. node scripts/preview-frames.cjs <project>   # 約 2 秒/幀的合成預覽 → § 視覺 QA(在渲染之前)
5. bash scripts/render-and-composite.sh <project>  # 關卡 → final.mp4 + history/ 快照
   (主題模式:跳過步驟 3b/5 — render-theme.sh 已經執行了編譯 + render-and-composite
    + _postfx.sh;交付物是 final_fx.mp4,final.mp4 是未經底板反應的狀態)

步驟 1 的 init 會檢查已安裝的技能是否與 GitHub 上的最新版本一致,如果有任何過期的,則更新全域集合。

步驟 3 根據模式而不同:

步驟 3 — 電影級模式(純嵌入)

  1. 先讀取 safe-zones.json。 旁白平面放置在 zones.hugLeft/hugRight — 緊貼輪廓的乾淨條帶(遠離身體的文字看起來像是浮動的,而非嵌入的;遠角是備用方案,而非預設值)。英雄預設為 heroAnchor/heroBands.best(在主體上居中,約 30–55% 被遮擋)。recommendation:"fg" 會將旁白移到前景以提高可讀性;只要 heroBands.feasible,英雄就保持在嵌入狀態 — 英雄前景是最後的手段。
  2. DNA 是你在步驟 0 中選取的識別

…

[已截斷以利翻譯]

Individual skills in this repo

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

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.

samyakiasonline-ctrl/hyperframe

Package an existing talking-head / interview / podcast video with timed, designed GRAPHIC OVERLAY cards — kinetic titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture — synced to the transcript, on a 16:9 / 9:16 / 4:5 canvas of your choice; the clip plays untouched underneath. Trigger on "graphic overlays", "on-screen graphics", "package / dress up my video". Not plain subtitles (/embedded-captions). Unclear → /hyperframes.

相關技能