Communitygithub.com

MattiaIppoliti/tia-skills

驅動 Remotion CLI 開發循環:建立專案、Studio、型別檢查、組合、靜態畫面測試、單一與批次渲染、打包、Lambda 與 Cloud Run 渲染、效能測試、版本管理、升級及 GPU 檢查。亦適用於診斷建置或渲染失敗,以及尋找已退役 HyperFrames CLI 曾擁有的功能。

tia-skills 是什麼?

此技能提供完整的 Remotion CLI 開發循環指引,支援 scaffold、type-check、composition 列出、still 探測、studio 審閱、render、bundle 以及 Lambda/Cloud Run 遠端渲染。其設計哲學是透過 `npx remotion still` 快速探測畫面,在幾秒內驗證文字位置、資源載入與色彩正確性,遠比完整渲染節省時間;再搭配 `npx remotion studio` 讓使用者透過時間軸與 Zod schema 編輯器自行審閱。對於批次渲染,技能建議在 shell 中迴圈處理 id,或對於大量資料使用 `renderMedia()` 以節省多次 bundle 的開銷。此外,技能涵蓋 `--concurrency`、`--jpeg`、`npx remotion benchmark` 與 `npx remotion gpu` 等效能調校指令,並以表格列出常見渲染失敗的診斷方法(如 `delayRender` 未配對、CSS 動畫不支援、`Math.random()` 未加種子等)。最後,技能將已退役 HyperFrames CLI 的所有功能對應至 Remotion 同等指令,避免使用者執行過時的 `npx hyperframes <anything>` 指令。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MattiaIppoliti/tia-skills/tree/HEAD/skills/video/hyperframes-cli

在你喜歡的 AI 中提問

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

說明文件

Remotion CLI

此工具為 remotion,來自 @remotion/cli。所有指令皆透過 npx remotion <command> 執行,且每個指令都會先打包專案,因此型別錯誤或錯誤的引入會顯現為打包失敗,而非渲染失敗。

npx remotion --help 與 npx remotion <command> --help 是標誌的權威來源。 標誌在不同版本間會變動;請閱讀幫助輸出,而非信任任何清單(包括本清單)。以下內容為開發循環與失敗模式,並非標誌參考。

開發循環

階段指令原因
建立專案 Scaffoldnpx create-video@latest --blank產生匹配的 package.json、remotion.config.ts、tsconfig
型別檢查npx tsc --noEmit成本最低的關卡;在渲染前捕捉 schema/prop 漂移
列出組合npx remotion compositions確認即將渲染的 id 確實存在
探測畫面npx remotion still <id> out/probe.png --frame=<n>花費數秒而非數分鐘;迭代的主力工具
審閱npx remotion studio交給使用者;他們自行拖動時間軸並編輯 props
渲染npx remotion render <id> out/video.mp4僅在使用者核准後進行
遠端部署npx remotion bundle → npx remotion lambda render <url> <id>分散式渲染;需要已部署的 AWS 基礎設施

在渲染前先探測靜態畫面

一個 45 秒 1080p 組合的完整渲染耗時數分鐘。靜態畫面僅需數秒,且能回答大部分問題:文字是否在畫面內、資源是否載入、顏色是否正確。請探測每個場景的中間點,檢視所有圖片,然後再進行渲染。

npx remotion still launch out/s1.png --frame=45
npx remotion still launch out/s2.png --frame=180

切勿僅因打包成功就回報組合可正常運作。請查看像素。

Studio 是審閱工具,而非除錯器

npx remotion studio 提供含有時間軸、由 Zod schema 驅動的 props 編輯器以及精確畫面跳轉的服務。將其交給使用者進行審閱。對於你自己的驗證,偏好使用 still 探測:它們可腳本化,且你可以直接查看輸出,無需要求使用者描述所見。

傳遞 props

--props 接受 JSON 字串或 JSON 檔案路徑,並覆蓋 defaultProps:

npx remotion render launch out/video.mp4 --props='{"productName":"Acme"}'

若 props 不符組合的 Zod schema,則渲染會大聲失敗。這正是宣告 schema 的目的,因此請保持其準確。

批次渲染

沒有批次子指令。請在 shell 中對 id 或 prop 載荷進行迴圈:

for id in $(npx remotion compositions --quiet); do
  npx remotion render "$id" "out/$id.mp4"
done

對於同一組合的多個資料集渲染,建議在 Node 腳本中使用 @remotion/renderer 的 renderMedia():它只打包一次,而非每次渲染都打包,這項差異主導了實際時間。

渲染效能

  • --concurrency=<n> 設定並行工作數。預設為 CPU 核心數一半(上限 8);最大值為核心數,請求更多工作會導致錯誤,而非自動限制。在記憶體緊張的機器上,降低此值可解決看似渲染器錯誤的崩潰。
  • --jpeg(取代預設的 PNG 畫面格式)在組合無需保留透明度時可大幅加速。
  • npx remotion benchmark 測量實際渲染,因此可用於證明變更並行數或編解碼器的效果,而非猜測。
  • npx remotion gpu 報告瀏覽器實際會加速的項目。在把緩慢渲染歸咎於著色器或大量濾鏡之前,值得先檢查此項。

診斷失敗

症狀可能原因
打包失敗型別錯誤或錯誤的引入。執行 npx tsc --noEmit 以取得相同錯誤的可讀版本。
"No composition with id …"Root.tsx 中的 id 與你傳遞的不同。npx remotion compositions 可解決此問題。
渲染卡住,然後超時delayRender() 沒有對應的 continueRender()。每個延遲控制代碼都必須被釋放。
每一幀看起來都像第 0 幀CSS 動畫/轉場,或使用了 requestAnimationFrame。渲染器不會推進瀏覽器時鐘。
動畫在幀之間閃爍或跳動未使用種子 seed 的 Math.random()。請改用 random(seed)。
向前拖動時間軸時動作正常,跳轉時卻出錯狀態驅動的動畫。請改用 useCurrentFrame() 來推導。
僅在 Lambda 或打包渲染中出現資源 404使用了硬編碼路徑而非 staticFile()。
版本錯誤令人困惑Remotion 套件版本不一致。npx remotion versions 會報告不一致之處。
渲染中途記憶體不足並行數過高,不符合機器規格。請降低 --concurrency。

回報失敗時,請提供實際錯誤輸出。請勿轉述堆疊追蹤。

已退役 HyperFrames CLI 功能去向

舊的 hyperframes CLI 包含了 Remotion CLI 所沒有的編寫、媒體與 QA 指令。以下所有內容皆非 Remotion 指令,請勿嘗試執行:

退役指令該功能現在的位置
initnpx create-video@latest --blank,然後 /hyperframes-core → references/project-structure.md
lint、check、layout、validatenpx tsc --noEmit 加上 still 探測。那些閘門強制的 data-* 合約已不存在。
snapshot、compare、grade-comparenpx remotion still 在選定的畫面;自行使用工具比對 PNG 差異。
preview、play、presentnpx remotion studio
add、catalog/hyperframes-registry
capture/product-launch-video(網站捕捉)及 /media-use
tts、transcribe、remove-background/media-use
beats、keyframes/hyperframes-creative(節拍規劃)、/hyperframes-keyframes
cloud、publishnpx remotion bundle + remotion lambda / remotion cloudrun,或自行託管
skills、docs、upgrade、doctor這些技能已收錄在此 repo 中;npx remotion upgrade 與 npx remotion versions

如有任何工作流程技能或參考檔案仍指示你執行 npx hyperframes <anything>,則該指示已過時。請從上表執行對應的 Remotion 動作,並在你的摘要中說明遇到過時指標,以便修正。

Individual skills in this repo

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

MattiaIppoliti/tia-skills

The technique catalog: five velocity-matched SEAMS (zoom-through, INVERSE zoom-through, cut-the-curve, waterfall cut, rack-focus blur-cut) plus the two in-scene techniques — waterfall ENTRY (staggered arrival cascades for title cards / segment openers) and the nudge curve (slow-fast-slow three-phase group slides). Covers partial-travel (~12% of frame) velocity matching via mirrored power4 eases, the Z scale-sign rule, size-scaled blur (10px text / 18-20px full-frame), word-by-word staggered cuts, cascade pacing by element weight, and the 10/65/25 slide ratio. Read before authoring any transition, text-beat handoff, kinetic text entry, or group reposition. [depth, zoom, inverse-zoom, scale-sign, mirrored-zoom, rack-focus, pacing, velocity, cut-the-curve, waterfall, stagger, cascade, kinetic-text, title-card, segment-opener, nudge, slide, easing, group-motion, z-depth, motion-graphics, cinematic, transition, blur, directional-continuity]

MattiaIppoliti/tia-skills

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.

MattiaIppoliti/tia-skills

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.

MattiaIppoliti/tia-skills

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.

MattiaIppoliti/tia-skills

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), or automation envelopes drawn on a track's volume or any effect parameter. 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`.

MattiaIppoliti/tia-skills

The composition contract for building one renderable Remotion project. Use for project structure, `<Composition>` registration, `<Sequence>` timing, layer/track ordering, scene components, props and schemas, framework-owned media playback, deterministic-render rules, and validation. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition code.

相關技能