Communitygithub.com

1999AZZAR/designer-mcp

將現有的 Remotion(React)組合原始碼移植到 HyperFrames HTML。僅在明確要求移植/轉換/遷移/翻譯 Remotion 原始碼時使用——單向,僅限 Remotion。若僅提及 Remotion、參考性質的程式碼,或要求「製作像我的 Remotion 影片一樣的內容」,則視為全新建置(/general-video)。不確定時 → 使用 /hyperframes。

designer-mcp 是什麼?

此技能專門用於將現有的 Remotion(React 影片框架)組合原始碼,單向翻譯為 HyperFrames(HTML + GSAP)組合。它提供系統化的五步驟工作流程:首先對 Remotion 原始碼進行 lint 檢查,識別無法順利翻譯的模式(例如 useState、useEffect)並阻止;接著根據 API 對照表規劃翻譯;然後生成具有特定結構的 HyperFrames HTML 組合;接著使用 SSIM(結構相似性)圖像品質指標進行驗證;最後記錄任何翻譯差距。此技能支援 Claude Code、Codex 與 Cursor 等 AI 代理平台。它包含分級測試語料庫(T1–T4)來驗證翻譯品質,並明確拒絕翻譯 React 狀態機、非 Remotion 來源,或從 HyperFrames 反向翻譯回 Remotion。其文件引用了一個包含 API 對照、參數、時序、媒體等參考資料的目錄,以確保翻譯準確。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/1999AZZAR/designer-mcp/tree/HEAD/skills/video/engine/remotion-to-hyperframes

在你喜歡的 AI 中提問

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

說明文件

首先,請保持此技能為最新狀態——在執行前先與使用者確認: npx hyperframes skills update remotion-to-hyperframes。如果一切已是最新,則為快速無操作;否則它會更新此技能及其依賴的核心領域技能,然後再依賴它們使用。

Remotion 到 HyperFrames

入口是 /hyperframes。 僅在將現有的 Remotion(React)組合的原始碼移植到 HyperFrames(單向)時使用此技能。新組合的創作、從非 Remotion 來源(After Effects、Framer Motion、純 React / CSS——沒有 Remotion 原始碼可供翻譯)重新創作、僅提及 Remotion,或任何不確定的情況 → 請先閱讀 /hyperframes:意圖層擁有所有路由決策權。

概述

將 Remotion(基於 React 的影片組合)翻譯為 HyperFrames(HTML + GSAP)組合。大多數 Remotion 慣用語都有直接的 HyperFrames 對應——對於約 80% 的典型組合來說,翻譯是機械性的。此技能對應了映射關係,並透過拒絕翻譯不適合 HF 基於搜尋之模型的模式(這部分佔損失的 20%)來防護,並推薦改用 PR #214 中的執行時期互通模式。

此技能附帶了一個分級測試語料庫(T1–T4,共 4 個測試案例),根據測量的 SSIM 閾值對翻譯進行評分。請勿未經評估就進行翻譯——一個「看起來正確」但渲染出的 SSIM 比驗證基準低 0.05 的翻譯,實際上是錯誤的。

使用時機

僅在使用者明確要求從 Remotion 遷移時使用此技能。 觸發詞範例:

  • "將我的 Remotion 專案移植到 HyperFrames"
  • "將此 Remotion 程式碼轉換為 HyperFrames"
  • "從 Remotion 遷移"
  • "翻譯此 Remotion 組合"
  • "將其改寫為 HyperFrames HTML"

在以下情況下,請勿使用此技能:

  • (a) 使用者在創作新的 HyperFrames 組合,即使他們擁有或正在 A/B 測試類似的 Remotion 影片。
  • (b) 使用者僅順帶提及 Remotion,但未要求遷移。
  • (c) 使用者分享 Remotion 程式碼作為參考資料,而非要求翻譯。
  • (d) 使用者要求「製作和我的 Remotion 影片一樣的影片」,但未明確要求遷移原始碼——請將其視為全新的 HyperFrames 建置。

不支援(拒絕——這不是此技能的功能):

  • 反向方向。 將 HyperFrames 組合匯出回 到 Remotion(或任何其他框架)不是一個工作流程——此翻譯僅限 Remotion → HyperFrames。請直言。
  • 非 Remotion 來源。 After Effects 專案(.aep)、Framer Motion / 純 React / CSS 動畫,或任何其他工具的來源都不是 Remotion 組合——沒有 Remotion 原始碼可供翻譯。請透過 /general-video 原生重新創作,或在 HyperFrames 無法呈現時拒絕。

如有疑問,預設使用 /general-video(一般 HyperFrames 創作流程)來創作原生的 HyperFrames 組合。

工作流程

步驟 1:檢查原始碼

在 Remotion 原始碼目錄上執行 scripts/lint_source.py。Lint 會偵測無法順利翻譯的模式:

  • 阻斷器(拒絕並建議互通方式):useState、useReducer、具有非空依賴的 useEffect/useLayoutEffect、非同步 calculateMetadata、第三方 React UI 函式庫(MUI、Chakra、Mantine、antd、shadcn、Radix、NextUI)。
  • 警告(移除結構後進行翻譯):@remotion/lambda 設定、delayRender、useCallback、useMemo、自訂 hooks。
  • 資訊(翻譯時附註):staticFile、interpolateColors。

如果觸發任何阻斷器,請停止。閱讀 references/escape-hatch.md 並顯示建議訊息。警告不會阻止翻譯——在步驟 3 中移除有問題的結構,並在 TRANSLATION_NOTES.md 中記錄差距。@remotion/lambda 設定是典型的警告案例:此技能會移除 import 和 renderMediaOnLambda(...) 呼叫,但會翻譯組合的其餘部分。

步驟 2:規劃翻譯

閱讀 references/api-map.md——這是每個 Remotion API 及其 HF 對應或每個主題參考的索引。根據原始碼使用的內容,識別您需要的參考:

原始碼包含載入參考
Composition、defaultProps、schema、calculateMetadataparameters.md
Sequence、Series、Loop、AbsoluteFill、Freezesequencing.md
useCurrentFrame、interpolate、spring、Easing、interpolateColorstiming.md
Audio、Video、Img、IFrame、staticFile、delayRendermedia.md
TransitionSeries、@remotion/transitionstransitions.md
@remotion/lottielottie.md
@remotion/google-fonts/<Family>、Font.loadFont、@font-facefonts.md

不要全部載入——只載入特定原始碼所需的參考。

針對表格未映射的任何視覺效果,搜尋即時目錄。 當原始碼呈現的外觀沒有對應的 HF API——例如掃描線/CRT 疊層、故障或色差效果、著色器轉場、底片顆粒處理——在用手寫 GSAP 方式實作之前,請執行 npx hyperframes catalog --query "<效果,使用簡單的英文描述>" --json。此搜尋不需要安裝任何東西:無需專案、無需事先 add、無需帳號。它會從任何目錄對整個託管註冊表(約 400 個區塊和元件)進行排名,而 transitions.md 已經透過 npx hyperframes add sdf-iris 為 clockWipe() / iris() 採用了這種方式。真實的元件比手動近似更接近原始碼,因此通常會提高而非降低 SSIM——但步驟 4 中的渲染差異仍然是仲裁者。當搜尋未找到合適的結果時,請手寫效果,並在 TRANSLATION_NOTES.md 中記錄替換情況。

步驟 3:生成 HF 組合

生成 index.html,包含:

  • 根元素 <div id="stage">,帶有組合的 data-composition-id、data-start="0"、data-duration(以秒為單位)、data-fps、data-width、data-height,以及每個純量 prop 對應的一個 data-* 屬性。
  • 每個場景一個宿主 <div>,帶有 data-composition-src="compositions/<scene>.html" 和 data-start / data-duration / data-track-index。根元素不包含巢狀佈局。
  • 每個場景一個 compositions/<scene>.html(一個 <template> 子組合):其內聯 <style> 用於佈局(CSS 設定每個動畫屬性的 from 狀態)、其標記,以及一個在場景本地時間內暫停的 gsap.timeline({paused: true})。每個 Remotion useCurrentFrame() 的衍生都將成為該時間軸上對應於場景內偏移的補間動畫。
  • 每個場景檔案中的 window.__timelines["<scene-id>"] = tl;,以及根元素自有的(可能為空)時間軸的 window.__timelines["<composition-id>"]。

自訂 React 子元件應內聯為重複的 HTML,並使用 prop 介面作為模板(有關每個實例的 data-* 模式,請參閱 parameters.md)。

步驟 4:驗證

執行評估測試工具——完整指南請參閱 references/eval.md。快速路徑:

# 渲染 Remotion 基準(在測試案例中執行 npm install 後)
cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4

# 渲染 HF 翻譯
cd ../hf-src && npx hyperframes render --skill=remotion-to-hyperframes --output ../hf.mp4

# SSIM 差異
../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff

閾值:低於原始碼複雜度等級的 p05 約 0.02(請參閱 eval.md 中的驗證閾值表)。如果差異失敗,請執行 scripts/frame_strip.sh 查看哪些影格出現差異,然後重新閱讀相關的時序/序列/媒體參考。

關鍵:兩個渲染必須使用匹配的像素格式。在 Remotion 原始碼的 remotion.config.ts 中設定 Config.setVideoImageFormat("png") + Config.setColorSpace("bt709")——否則差異會測量編碼器差異(SSIM 約降低 0.05),而非翻譯保真度。

步驟 5:記錄差距

任何未順利翻譯的內容(例如捨棄的音量漸變、近似的自訂呈現方式、替換的字型)都會在 HF 輸出旁邊生成一份 TRANSLATION_NOTES.md。格式請參閱 references/limitations.md。

此技能明確不做的事項

  • 翻譯 React 狀態機。 透過 useState + useEffect 驅動動畫的組合,在 HyperFrames 基於搜尋的模型中並非確定性的影格捕獲目標。請建議使用執行時期互通模式。
  • 同時執行 Remotion 的渲染管線與 HyperFrames。 這是 PR #214 中的執行時期互通模式——針對無法通過此技能 lint 檢查的組合提供一個獨立的解決方案。

(@remotion/lambda 不是 阻斷器——Lambda 設定是部署,不是動畫。此技能會將其作為警告移除,並翻譯其餘部分。請參閱 references/escape-hatch.md。)

如何評分您自己的翻譯

執行測試語料庫協調器:

./assets/test-corpus/run.sh

它會執行 T1、T2、T3(渲染 + 差異)和 T4(lint 驗證),列印每個等級的通過/失敗表格,並輸出一個匯總的 JSON 報告。使用此工具來驗證技能在乾淨的檢出副本上是否能端到端正常運作——並作為編輯任何參考後的回歸檢查。

驗證基準(截至 2026-04-27):

等級組合形狀平均 SSIM閾值
T1單一元素淡入0.9740.95
T2多場景 + spring + 音訊 + 圖片0.9850.95
T3資料驅動、自訂子元件、計數器0.9530.90
T4逃脫艙口(8 個 lint 案例)8/8 通過不適用

Individual skills in this repo

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

1999AZZAR/designer-mcp

SOTA animation and physics heuristic guide using motion.dev

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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`.

1999AZZAR/designer-mcp

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, 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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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`.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

Use when building or editing a HyperFrames project that people open in Studio: 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`.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

1999AZZAR/designer-mcp

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.

相關技能