Communitygithub.com

Manavv007/S.A.R.A.L.-Scheme-Access-Retrieval-Analysis-Layer-

HyperFrames CLI 開發循環。用於執行 npx hyperframes init、add、catalog、capture、lint、validate、inspect、layout、snapshot、preview、play、render、publish、lambda、doctor、browser、info、upgrade、skills、compositions、docs、benchmark、telemetry、transcribe、tts 或 remove-background,以及排解 HyperFrames 建置/渲染環境問題時使用。也是 AWS Lambda 雲端渲染的進入點(`hyperframes lambda deploy / render / progress / destroy / policies`)。

S.A.R.A.L.-Scheme-Access-Retrieval-Analysis-Layer- 是什麼?

此技能為 HyperFrames CLI 的完整參考指南,這是一套用於合成影片製作與渲染的命令列工具。它涵蓋從初始化專案(`npx hyperframes init`)到透過多種方式渲染的最終產出:本機草稿模式、高品質輸出、Docker 容器化渲染,以及用於長時間或大型專案的 AWS Lambda 雲端渲染。該指南強調使用 lint、validate 和 inspect 命令進行靜態分析與視覺驗證的結構化工作流程,這些命令能捕捉常見錯誤,例如遺失的 `data-composition-id`、重疊的軌道、未註冊的時間軸、執行時期控制台錯誤、無障礙問題以及文字溢出容器。對於複雜的動畫,它建議使用快照驅動的疊代搭配 `*.motion.json` 側邊檔案,以確保動作意圖(如進場時序與交錯順序)的正確性。此技能也詳述了代理程式規範,例如在非 TTY 環境中支援 `--json` 輸出、非互動模式、基於 `--strict` 旗標的 CI 整合,以及渲染前的使用者確認。此外,它還提供路由指引,將特定任務(如雲端渲染、疑難排解或素材預處理)連結到更詳細的參考文件,並定義與其他技能(如 `hyperframes-core`、`hyperframes-registry` 和 `hyperframes-media`)的交接點。最後,它說明了使用快照進行視覺冒煙測試的關鍵需求——特別是對於使用子合成的專案——因為靜態檢查無法捕捉跨檔案的掛載失敗。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Manavv007/S.A.R.A.L.-Scheme-Access-Retrieval-Analysis-Layer-/tree/HEAD/.agents/skills/hyperframes-cli

在你喜歡的 AI 中提問

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

說明文件

HyperFrames CLI

所有操作都透過 npx hyperframes 執行,除非專案說明指定了本機包裝器。請嚴格遵守本機包裝器。需要 Node.js >= 22 和 FFmpeg。

工作流程

  1. 建立骨架 — npx hyperframes init my-video(或從 URL 使用 capture)
  2. 編寫 — 編寫 HTML 合成(請參閱 hyperframes-core 技能)
  3. Lint — npx hyperframes lint
  4. 驗證 — npx hyperframes validate(執行時期錯誤 + 對比度)
  5. 視覺檢查 — npx hyperframes inspect
  6. 預覽 — npx hyperframes preview 會開啟 Studio,這是一個時間軸編輯器,使用者可以在此手動編輯任何內容(不僅是觀看)。在那裡審閱,然後再要求渲染。
  7. 渲染 — 選擇變體:
    • 疊代:npx hyperframes render --quality draft
    • 交付:npx hyperframes render --quality high --output out.mp4
    • CI / 跨主機重現:npx hyperframes render --docker --strict --output out.mp4
    • 雲端(長時間/大型):npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait(請參閱下方的 Lambda)

在預覽前執行 lint、validate 和 inspect。lint 會捕捉遺失的 data-composition-id、重疊的軌道和未註冊的時間軸。validate 會在無頭 Chrome 中載入合成,並回報執行時期控制台錯誤以及 WCAG 對比度問題。inspect 會掃描時間軸,回報文字溢出氣泡/容器或畫布的情況——並且,當存在 *.motion.json 側邊檔案時,會根據相同的掃描時間軸驗證動作意圖(進場觸發、交錯順序、在畫面內、活性)。

對於動作密集的工作,建議使用快照驅動的疊代和 *.motion.json 側邊檔案——請參閱 references/lint-validate-inspect.md 以了解規範和動作驗證規格。

代理程式規範

適用於每個命令的通用規則:

  • 除了 render、preview 和 play 之外,每個命令都可使用 --json。 在任何代理程式 / CI 呼叫支援的命令時使用它;輸出包含一個 _meta 信封(cli 版本、最新可用版本、更新建議)。render 僅透過 stdout + 退出碼回報狀態——請使用下方的渲染後檢查來驗證成功;preview / play 是伺服器,沒有 JSON。
  • doctor --json 總是退出 0,即使環境已損壞。根據負載的 ok 欄位進行判斷:npx hyperframes doctor --json | jq -e '.ok' > /dev/null。這使管線不受 CLI 版本變動的影響。
  • 非 TTY 模式會自動偵測。 當 stdout 不是 TTY(CI、代理程式、管道輸出)時,CLI 會自動切換到非互動模式;init 然後需要 --example。傳遞 --non-interactive 以強制在 TTY 上使用此模式。
  • CI 基於渲染的閘控:--strict 在 lint 錯誤時失敗,--strict-all 也在警告時失敗,--strict-variables 在未宣告的 --variables 鍵時失敗。
  • --json 中的路徑會被遮罩——$HOME 會變成字面量 $HOME,因此輸出可以安全地貼到錯誤報告和代理程式上下文中。
  • 渲染需要使用者許可。 檢查通過後絕不要自動渲染。在 preview 處暫停,告訴使用者影片可在 Studio 中編輯,並且只在他們批准後才渲染。
  • 渲染後驗證。 在 render 返回退出碼 0 後,確認輸出檔案存在且具有合理大小,然後再回報成功:[ -s "$OUTPUT" ] || echo "render produced no output"。CLI 會在成功時列印 ◇ <path>;對於長時間渲染,也使用 ffprobe -i "$OUTPUT" -show_format -v error 進行合理性檢查。

路由

想要…請閱讀
建立專案骨架(init、capture、skills)references/init-and-scaffold.md
檢查正確性(lint、validate、inspect、snapshot)references/lint-validate-inspect.md
預覽或渲染(preview、play、render、publish)references/preview-render.md
診斷環境(doctor、browser)references/doctor-browser.md
在 AWS Lambda 上進行雲端渲染(lambda deploy / sites / render / progress / destroy / policies)references/lambda.md
其他所有內容(info、upgrade、compositions、docs、benchmark、telemetry、素材預處理)references/upgrade-info-misc.md

跨技能交接

  • Tailwind 專案(init --tailwind)→ 在編輯類別或主題 token 前,使用 hyperframes-core(Tailwind 參考)。
  • 註冊表區塊/元件(hyperframes add、hyperframes catalog)→ 使用 hyperframes-registry 處理安裝路徑、子合成接線和程式碼片段合併。
  • 素材預處理(tts、transcribe、remove-background)→ 使用 hyperframes-media 處理語音選擇、Whisper 模型規則、字幕和 TTS 到字幕的鏈路。
  • 參數化渲染(--variables)→ 透過 <html> 上的 data-composition-variables 宣告;請參閱 hyperframes-core 以了解完整架構。

Lambda(雲端渲染)

hyperframes lambda 將分散式渲染部署到 AWS Lambda,並從您的筆電或 CI 驅動渲染。端到端總共三個命令:

npx hyperframes lambda deploy                                             # 佈建 SAM 堆疊(Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy                                            # 拆除(S3 儲存桶會保留)

當渲染對單一主機來說太長/太大(多分鐘影片、4K、大型平行批次)且您已設定 AWS 憑證時,請使用 Lambda。對於開發循環疊代,請保持在本地端使用 render。

請參閱 references/lambda.md 以了解先決條件、所有 6 個子命令(deploy、sites create、render、progress、destroy、policies)、IAM 政策驗證、狀態檔案以及成本/清理規則。

最低完成閘控

靜態閘控

npx hyperframes lint
npx hyperframes validate

對於版面敏感的專案,請加入 inspect,並在 CI 中加入 render --strict 以在 lint 錯誤時失敗。

視覺冒煙測試 — 當專案使用子合成時為必選

lint / validate / inspect 各自獨立評估每個合成。它們從不載入 index.html 並透過 data-composition-src 掛載子合成,因此無法捕捉跨檔案掛載失敗(請參閱 hyperframes-core → references/sub-compositions.md 中的「常見陷阱」)。唯一能捕捉它們的閘控是實際載入 index.html 並掃描時間軸的閘控。

使用 hyperframes snapshot——它以與 render 相同的方式載入專案(因此它會執行相同的掛載路徑),但只捕捉您要求的時間戳,因此只需幾秒鐘,而不是完整渲染:

# 在每個子合成的中點捕捉一個畫格。
# 中點 = index.html 中每個主機插槽的 data-start + data-duration/2。
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...

# 或者,如果您不需要針對每個場景,也可以使用均勻間隔的樣本:
npx hyperframes snapshot --frames 9

輸出會存放在 snapshots/frame-NN-at-Xs.png。比對每個畫格與場景計劃。

每個畫格的紅旗(每個都對應到靜態閘控遺漏的特定失敗模式):

您看到的根原因
文字在左上角顯示為極小且無樣式<style> 區塊留在 <template> 外部的 <head> 中(陷阱 1)—— 沒有 CSS 到達實際 DOM
SVG/圖示元素放大到畫布大小同上——未套用寬度/高度限制
場景的主要元素完全遺失;僅顯示背景和浮水印主機 id ≠ 模板 id(陷阱 2)—— 時間軸從未執行,畫格在初始狀態下捕捉
快照命令記錄 Sub-composition timelines not registered after 45000ms陷阱 2—— 直接確認

snapshots/ 可以在目視檢查後刪除;使用者最終的渲染是一個單獨的 npx hyperframes render 程序。

Individual skills in this repo

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

Manavv007/S.A.R.A.L.-Scheme-Access-Retrieval-Analysis-Layer-

The fallback workflow for authoring custom HyperFrames video compositions at any length or format — longer or multi-scene pieces, brand / sizzle reels, montages, title cards, static loops, and freeform compositions. Input- and length-agnostic. If a specialized workflow clearly fits the input — a marketed product, a website, a topic explainer, a GitHub PR, existing footage, a short motion graphic, or a Remotion port — prefer it (see /hyperframes); use this only as the general fallback when none fit.

Manavv007/S.A.R.A.L.-Scheme-Access-Retrieval-Analysis-Layer-

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). HyperFrames-native: single paused timeline, seek-safe, deterministic.

Manavv007/S.A.R.A.L.-Scheme-Access-Retrieval-Analysis-Layer-

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.

Manavv007/S.A.R.A.L.-Scheme-Access-Retrieval-Analysis-Layer-

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

Manavv007/S.A.R.A.L.-Scheme-Access-Retrieval-Analysis-Layer-

Capture a general website/URL and turn it into a HyperFrames video (site tour, showcase, or social clip from the site's own visuals). Uses headless Chrome screenshots + brand assets. Use when intent is general — portfolio/blog/landing-page showcase or social clip from the site. NOT for: product/SaaS launch or promo (→ /product-launch-video, even from a URL); topic explainer with no site (→ /faceless-explainer); GitHub PR (→ /pr-to-video); adding captions to existing video (→ /embedded-captions); short unnarrated page-highlight motion graphic (→ /motion-graphics). Unclear launch-vs-general-site? Ask one question or start at /hyperframes.

Manavv007/S.A.R.A.L.-Scheme-Access-Retrieval-Analysis-Layer-

Audio and media assets for HyperFrames compositions, produced by one shared audio engine (`scripts/audio.mjs`) — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), background music + sound effects (HeyGen audio-library retrieval by default, with local Lyria / MusicGen BGM generation and a bundled SFX library as the no-credential fallback), Whisper transcription, background removal, and caption authoring. Use for voiceover / TTS, BGM, SFX / sound effects, transcription, captions / subtitles / lyrics / karaoke / per-word styling, voice + provider selection, and music-mood prompting.

Manavv007/S.A.R.A.L.-Scheme-Access-Retrieval-Analysis-Layer-

S.A.R.A.L. is an advanced AI-powered platform designed to bridge the "information gap" between rural Indian citizens and government welfare. While thousands of schemes exist, the complex language of official PDFs often makes them inaccessible to the common man.

相關技能