diff --git a/CLAUDE.md b/CLAUDE.md index 47fd0ab76..3478aeb61 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,11 +4,11 @@ Open-source video rendering framework: write HTML, render video. ## Skills -This repo ships 21 AI agent skills via [vercel-labs/skills](https://github.com/vercel-labs/skills). Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover. +This repo ships 20 AI agent skills via [vercel-labs/skills](https://github.com/vercel-labs/skills). Install them before writing compositions — they encode framework-specific patterns that generic docs don't cover. ```bash npx skills add heygen-com/hyperframes # interactive picker -npx skills add heygen-com/hyperframes --all # install all 21 (skips picker) +npx skills add heygen-com/hyperframes --all # install all 20 (skips picker) npx skills add heygen-com/hyperframes --skill # just one (bare name, no leading slash) ``` @@ -36,8 +36,7 @@ Atomic capabilities the creation workflows compose against — pull one when you - `/hyperframes-animation` — all animation knowledge: atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP default, plus Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU). - `/hyperframes-keyframes` — seek-safe keyframe authoring across runtimes: GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, cursor demos, 3D depth; plus `hyperframes keyframes` diagnostics for surfacing and verifying rendered motion. - `/hyperframes-creative` — non-animation creative direction: `frame.md` / `design.md` handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. -- `/hyperframes-media` — audio + media: TTS voiceover, background music, sound effects, Whisper transcription, background removal, caption authoring (one shared `scripts/audio.mjs` engine, multi-provider). -- `/media-use` — resolve any media need (BGM, SFX, image, icon) into a frozen local file + ledger record. One verb (`resolve`) over the HeyGen catalog with manifest tracking; keeps search noise on disk. +- `/media-use` — the media OS: resolve any media need (BGM, SFX, image, icon, voice) into a frozen local file + ledger record; generate via TTS / music when the catalog misses; transcribe, remove backgrounds, and reuse assets across projects. One shared `scripts/audio.mjs` engine + manifest tracking; keeps search noise on disk. - `/hyperframes-cli` — CLI dev loop: `init`, `add`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, `lambda` (AWS Lambda cloud rendering). - `/hyperframes-registry` — install and wire registry blocks and components into compositions via `hyperframes add`. Covers authoring a new block or component to contribute upstream. - `/figma` — import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations and shaders (MCP) into a composition. @@ -49,7 +48,7 @@ When adding a new skill, or substantially renaming / repurposing an existing one 1. The skill list above (CLAUDE.md) AND the `## Skills` section in `README.md` AND `docs/guides/skills.mdx` (rendered at [hyperframes.heygen.com/guides/skills](https://hyperframes.heygen.com/guides/skills)). Out-of-date entries silently kill discovery. 2. If the skill changes the routing surface for "make a video" requests, also update the capability map and intent router in `skills/hyperframes/SKILL.md` — that's the canonical router agents read first. 3. Mirror the Router / Creation workflows / Domain skills grouping across all three surfaces so a skill always lives in the same column. -4. Skill count appears in the README and CLAUDE.md intro lines ("21 AI agent skills…") — update on add/remove. The `docs/guides/skills.mdx` page deliberately omits a count to avoid drift; keep it count-free. +4. Skill count appears in the README and CLAUDE.md intro lines ("20 AI agent skills…") — update on add/remove. The `docs/guides/skills.mdx` page deliberately omits a count to avoid drift; keep it count-free. The skill's own `SKILL.md` frontmatter `description:` is the source of truth for the one-line "use when" blurb; copy from there into the catalog rather than paraphrasing. diff --git a/README.md b/README.md index ee9962c14..8c080c939 100644 --- a/README.md +++ b/README.md @@ -49,9 +49,9 @@ The skills teach agents the HyperFrames production loop: plan the video, write v ## Skills -HyperFrames ships 21 skills agents load on demand. Read `/hyperframes` first — it's the router and capability map; it picks a workflow for any "make me a video" request and points to the domain skills below. +HyperFrames ships 20 skills agents load on demand. Read `/hyperframes` first — it's the router and capability map; it picks a workflow for any "make me a video" request and points to the domain skills below. -Run `npx skills add heygen-com/hyperframes` for the interactive picker, `npx skills add heygen-com/hyperframes --all` to install all 21 at once (skips the picker), or `npx skills add heygen-com/hyperframes --skill ` for just one (bare name, no leading `/`). +Run `npx skills add heygen-com/hyperframes` for the interactive picker, `npx skills add heygen-com/hyperframes --all` to install all 20 at once (skips the picker), or `npx skills add heygen-com/hyperframes --skill ` for just one (bare name, no leading `/`). ### Router @@ -85,8 +85,7 @@ Atomic capabilities the creation workflows compose against — pull one when you | `/hyperframes-animation` | All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU). | | `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion. | | `/hyperframes-creative` | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. | -| `/hyperframes-media` | Audio + media — TTS voiceover, background music, sound effects, Whisper transcription, background removal, caption authoring (one shared audio engine). | -| `/media-use` | Resolve any media need (BGM, SFX, image, icon) into a frozen local file + ledger record. One verb (`resolve`) over the HeyGen catalog with manifest tracking. | +| `/media-use` | The media OS — resolve any media need (BGM, SFX, image, icon, voice) into a frozen local file + ledger record, generate via TTS/music when the catalog misses, transcribe, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. | | `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress`). | | `/hyperframes-registry` | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream. | | `/figma` | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations and shaders (MCP) into a composition. | diff --git a/docs/guides/antigravity.mdx b/docs/guides/antigravity.mdx index 7c3ebb77c..292b58876 100644 --- a/docs/guides/antigravity.mdx +++ b/docs/guides/antigravity.mdx @@ -42,7 +42,7 @@ Antigravity uses **semantic matching** — when you type a prompt, the agent com | "Create a 10-second product intro with captions" | `hyperframes`, `hyperframes-core` | | "Add a GSAP scale-pop to the title" | `hyperframes-animation` | | "Use Tailwind for styling" | `hyperframes-core` | -| "Transcribe this audio and add captions" | `hyperframes-media` | +| "Transcribe this audio and add captions" | `media-use` | | "Add a shimmer sweep transition" | `hyperframes-registry` | The skill is only injected into the agent's context window when it matches — this keeps the context clean and focused. diff --git a/docs/guides/pipeline.mdx b/docs/guides/pipeline.mdx index 7bd5b7b60..c701ddb7a 100644 --- a/docs/guides/pipeline.mdx +++ b/docs/guides/pipeline.mdx @@ -141,7 +141,7 @@ npx hyperframes transcribe narration.wav | `narration.txt` | The exact spoken text with pronunciation substitutions applied (`API` → `A P I`, `$2T` → `two trillion`). Distinct from `SCRIPT.md` so you can regenerate the audio later with a different voice without redoing the substitutions. | | `transcript.json`| `[{ text, start, end }]` for every word. Every later step reads this for timing. | -Hyperframes ships multiple TTS adapters (Kokoro, ElevenLabs, HeyGen); see [`/hyperframes-media`](/guides/prompting) for the skill that picks one. After generating audio, update `STORYBOARD.md` with the real beat boundaries from `transcript.json`. +Hyperframes ships multiple TTS adapters (Kokoro, ElevenLabs, HeyGen); see [`/media-use`](/guides/prompting) for the skill that picks one. After generating audio, update `STORYBOARD.md` with the real beat boundaries from `transcript.json`. **Gate:** `narration.wav`, `narration.txt`, and `transcript.json` exist. `STORYBOARD.md` beat timings reference real timestamps, not estimates. diff --git a/docs/guides/prompting.mdx b/docs/guides/prompting.mdx index ac4807957..49907ccc6 100644 --- a/docs/guides/prompting.mdx +++ b/docs/guides/prompting.mdx @@ -24,7 +24,7 @@ The installer shows a picker. Select the **core skills** below — every project | `/hyperframes-animation`| All animation — motion rules, scene blueprints, transitions, and the runtime adapters (GSAP, Lottie, Three.js, Anime.js, CSS, WAAPI, TypeGPU) | | `/hyperframes-creative` | Creative direction — design spec, palettes, typography, narration, beats | | `/hyperframes-cli` | Dev-loop CLI — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `doctor` | -| `/hyperframes-media` | Audio + media — TTS voiceover, BGM, SFX, transcription, background removal, caption authoring | +| `/media-use` | Asset preprocessing — `tts`, `transcribe`, `remove-background` | | `/hyperframes-registry` | Block and component installation via `hyperframes add` | | `/general-video` | The general authoring workflow — fallback for any video that doesn't match a specific workflow below | diff --git a/docs/guides/skills.mdx b/docs/guides/skills.mdx index 0662b5d53..b732d391d 100644 --- a/docs/guides/skills.mdx +++ b/docs/guides/skills.mdx @@ -80,8 +80,7 @@ Atomic capabilities the creation workflows compose against — pull one when you | `/hyperframes-animation` | All animation knowledge — atomic motion rules, scene blueprints, transitions, runtime adapters (GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU). | | `/hyperframes-keyframes` | Seek-safe keyframe authoring across runtimes — GSAP timelines, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, 3D depth — plus `hyperframes keyframes` diagnostics for rendered motion. | | `/hyperframes-creative` | Non-animation creative direction — `frame.md` / `design.md`, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns. | -| `/hyperframes-media` | Audio + media — TTS voiceover, background music, sound effects, Whisper transcription, background removal, caption authoring (one shared audio engine). | -| `/media-use` | Resolve any media need (BGM, SFX, image, icon) into a frozen local file + ledger record. One verb (`resolve`) over the HeyGen catalog with manifest tracking. | +| `/media-use` | The media OS — resolve any media need (BGM, SFX, image, icon, voice) into a frozen local file + ledger record, generate via TTS/music when the catalog misses, transcribe, remove backgrounds, and reuse assets across projects. One shared audio engine + manifest tracking. | | `/hyperframes-cli` | CLI dev loop — `init`, `lint`, `validate`, `inspect`, `preview`, `render`, `publish`, `doctor`, plus AWS Lambda cloud rendering (`lambda deploy / render / progress / destroy / policies`). | | `/hyperframes-registry` | Install and wire registry blocks and components into compositions via `hyperframes add`. Authoring a new block or component to contribute upstream. | | `/figma` | Import Figma assets, tokens, components, and storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI) plus Motion animations and shaders (MCP) into a composition. | diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index 2d6363eb8..eeca38924 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -932,7 +932,7 @@ Word-level transcripts (whisper output) are grouped into readable caption cues o | `--codex` | Install to Codex CLI (`~/.codex/skills/`) | | `--cursor` | Install to Cursor (`.cursor/skills/` in current project) | - Skills are fetched from GitHub: the `/hyperframes` entry skill (routes "make me a video" to a workflow), the composition contract and Tailwind v4 browser-runtime guidance (`/hyperframes-core`), all animation including the GSAP / Anime.js / CSS / Lottie / Three.js / WAAPI / TypeGPU runtime adapters (`/hyperframes-animation`), creative direction (`/hyperframes-creative`), media preprocessing (`/hyperframes-media`), registry block/component wiring (`/hyperframes-registry`), and the video workflows. The `init` command also offers to install skills automatically after scaffolding a project. + Skills are fetched from GitHub: the `/hyperframes` entry skill (routes "make me a video" to a workflow), the composition contract and Tailwind v4 browser-runtime guidance (`/hyperframes-core`), all animation including the GSAP / Anime.js / CSS / Lottie / Three.js / WAAPI / TypeGPU runtime adapters (`/hyperframes-animation`), creative direction (`/hyperframes-creative`), media preprocessing (`/media-use`), registry block/component wiring (`/hyperframes-registry`), and the video workflows. The `init` command also offers to install skills automatically after scaffolding a project. #### Troubleshooting: `fatal: active post-checkout hook found during git clone` diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index ce8e8ada5..af6fb3e44 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -22,7 +22,7 @@ The installer shows a picker. Select the **core set** every project needs — th | `/hyperframes-animation` | All animation + the GSAP / Lottie / Three.js / Anime.js / CSS / WAAPI / TypeGPU runtime adapters | | `/hyperframes-creative` | Design direction — palettes, typography, narration, beat planning | | `/hyperframes-cli` | Dev-loop CLI — init, lint, preview, render, doctor | -| `/hyperframes-media` | Asset preprocessing — TTS, transcription, background removal | +| `/media-use` | Asset preprocessing — TTS, transcription, background removal | | `/hyperframes-registry` | Install catalog blocks and components | | `/general-video` | The general authoring workflow — the fallback for any video that doesn't match a specific workflow | diff --git a/scripts/test-skills-fresh.sh b/scripts/test-skills-fresh.sh index 6cac301e4..c57372d73 100755 --- a/scripts/test-skills-fresh.sh +++ b/scripts/test-skills-fresh.sh @@ -237,7 +237,7 @@ ROUTER="hyperframes" WORKFLOWS=(product-launch-video website-to-video faceless-explainer embedded-captions \ talking-head-recut pr-to-video motion-graphics general-video \ remotion-to-hyperframes slideshow) -DOMAIN=(hyperframes-core hyperframes-creative hyperframes-animation hyperframes-cli hyperframes-media hyperframes-registry) +DOMAIN=(hyperframes-core hyperframes-creative hyperframes-animation hyperframes-cli media-use hyperframes-registry) MISSING=() check_skill() { if [[ -d "$SKILLS_DIR/$1" ]]; then ok "$SKILLS_DIR/$1/"; else MISSING+=("$1"); fi; } diff --git a/skills-manifest.json b/skills-manifest.json index bcd3f0d47..f0ca9ef95 100644 --- a/skills-manifest.json +++ b/skills-manifest.json @@ -2,11 +2,11 @@ "source": "heygen-com/hyperframes", "skills": { "embedded-captions": { - "hash": "62aec45830eda54b", + "hash": "1cf326d503115227", "files": 144 }, "faceless-explainer": { - "hash": "6dac80491c3db278", + "hash": "868057217d0499e8", "files": 18 }, "figma": { @@ -14,23 +14,23 @@ "files": 1 }, "general-video": { - "hash": "a30225e30ec7b06c", + "hash": "d30096cfc7bd5db2", "files": 1 }, "hyperframes": { - "hash": "e4e2f137d492c6d7", + "hash": "c52186059c9796ae", "files": 1 }, "hyperframes-animation": { - "hash": "19024009fab8e5d1", + "hash": "6323b750d67287e9", "files": 116 }, "hyperframes-cli": { - "hash": "9b36a367a0e3a332", + "hash": "9f9fa8d0cf3ef9e2", "files": 7 }, "hyperframes-core": { - "hash": "50ed383eb88a58b6", + "hash": "afea2e8bb200ee71", "files": 13 }, "hyperframes-creative": { @@ -41,32 +41,28 @@ "hash": "47f20312033792c3", "files": 3 }, - "hyperframes-media": { - "hash": "56190192ead45ed1", - "files": 47 - }, "hyperframes-registry": { "hash": "e3b389526834109d", "files": 10 }, "media-use": { - "hash": "75dda0086dda18ce", - "files": 19 + "hash": "969e6ed350111d63", + "files": 87 }, "motion-graphics": { - "hash": "be1d1f159d5eb0e4", + "hash": "73771b2d1300236d", "files": 23 }, "music-to-video": { - "hash": "0c5738fac0fe622f", + "hash": "84295adeeebcf923", "files": 132 }, "pr-to-video": { - "hash": "d40ba25aa5af30e1", + "hash": "0bc51f6ba74b2bfd", "files": 22 }, "product-launch-video": { - "hash": "b1895d518ec04da5", + "hash": "40bfb0bf49ae17cd", "files": 20 }, "remotion-to-hyperframes": { @@ -82,7 +78,7 @@ "files": 27 }, "website-to-video": { - "hash": "ac39931f9a7da749", + "hash": "813dc861e4214a35", "files": 32 } } diff --git a/skills/embedded-captions/modes/standard/_anatomy.md b/skills/embedded-captions/modes/standard/_anatomy.md index 234f71c84..0eb3fa023 100644 --- a/skills/embedded-captions/modes/standard/_anatomy.md +++ b/skills/embedded-captions/modes/standard/_anatomy.md @@ -226,7 +226,7 @@ The gallery used a `setInterval` loop; HyperFrames needs the same beats as **abs ## Pairs with HF skills -- `hyperframes-media` — `remove-background` (the matte) + `transcribe` (word timings). +- `media-use` — `remove-background` (the matte) + `transcribe` (word timings). - `hyperframes-captions` — transcript consumption, grouping, positioning, exit guarantees, `fitTextFontSize`. - `hyperframes-animation/rules/asr-keyword-glow.md` — the verbatim active-word envelope. - `hyperframes-gsap` — single paused timeline, transform aliases, ease palette. diff --git a/skills/embedded-captions/references/rail.md b/skills/embedded-captions/references/rail.md index 1f676f724..580380bab 100644 --- a/skills/embedded-captions/references/rail.md +++ b/skills/embedded-captions/references/rail.md @@ -10,7 +10,7 @@ with only the climax(es) promoted to embed. Rail is not a fallback — it's the > **Implementation note.** A dedicated rail renderer is the next build step. The rail is a > plain `fg` caption track and maps cleanly onto hyperframes' native caption pipeline -> (`hyperframes-media` captions) — prefer reusing that over hand-rolling. Until wired, render +> (`media-use` captions) — prefer reusing that over hand-rolling. Until wired, render > the rail as a simple `data-caption-layer="fg"` composition (no matte overlay for these caps). ## Position & safe area diff --git a/skills/embedded-captions/scripts/transcribe.cjs b/skills/embedded-captions/scripts/transcribe.cjs index 818575974..5775d2b82 100644 --- a/skills/embedded-captions/scripts/transcribe.cjs +++ b/skills/embedded-captions/scripts/transcribe.cjs @@ -110,7 +110,7 @@ function main() { console.error("usage: transcribe.cjs [model] [language]"); process.exit(1); } - // Default = multilingual `small`, NOT `small.en`. Per hyperframes-media: ".en models + // Default = multilingual `small`, NOT `small.en`. Per media-use: ".en models // mistranslate non-English and mis-handle accented speech; default to small (auto-detects // language)." We hardcoded small.en before — it hallucinated a wrong transcript on an // accented speaker. Pass `small.en` only for known-clean-English; tough accents → a larger model. diff --git a/skills/faceless-explainer/SKILL.md b/skills/faceless-explainer/SKILL.md index 6a80d44e9..4d0d7a251 100644 --- a/skills/faceless-explainer/SKILL.md +++ b/skills/faceless-explainer/SKILL.md @@ -25,7 +25,7 @@ Initialize only if `hyperframes.json` is missing. Name `` from the topi `npx hyperframes init "videos/" --non-interactive --example=blank` — `init` checks the installed skills against the latest on GitHub and updates the global set if any are out of date. -**Show sign-in status before the brief** — run `npx hyperframes auth status` and **relay its output verbatim (don't paraphrase or rewrite it).** It reports whether voice/BGM will use HeyGen or local engines and, when not signed in, how to sign in. **If not signed in, STOP and wait for the user to choose — sign in, or say "go"/"offline" to continue with local engines — before asking the brief or anything else.** Treat it as a real decision point, not a passing note; don't fold the choice into the brief question, and don't write keys into a per-repo `.env`. (In autonomous mode, note the status and continue offline.) See `../hyperframes-media` → Preflight for the canonical guidance. +**Show sign-in status before the brief** — run `npx hyperframes auth status` and **relay its output verbatim (don't paraphrase or rewrite it).** It reports whether voice/BGM will use HeyGen or local engines and, when not signed in, how to sign in. **If not signed in, STOP and wait for the user to choose — sign in, or say "go"/"offline" to continue with local engines — before asking the brief or anything else.** Treat it as a real decision point, not a passing note; don't fold the choice into the brief question, and don't write keys into a per-repo `.env`. (In autonomous mode, note the status and continue offline.) See `../media-use` → Preflight for the canonical guidance. **Gate:** `hyperframes.json` exists, and angle, length, aspect ratio, and language are locked; sign-in status was shown (signed in, or continuing offline). @@ -88,7 +88,7 @@ Start audio after Step 3 approval. Run it in the background, then continue to St `node /scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &` -The audio script handles narration, word timings, BGM lookup from HeyGen's music library, and timing metadata. BGM mood comes from the storyboard's `music:` field. This uses the HeyGen Audio API for retrieval, not generation, and the same `~/.heygen` credential as TTS. For provider details, read `../hyperframes-media/references/tts.md`. +The audio script handles narration, word timings, BGM lookup from HeyGen's music library, and timing metadata. BGM mood comes from the storyboard's `music:` field. This uses the HeyGen Audio API for retrieval, not generation, and the same `~/.heygen` credential as TTS. For provider details, read `../media-use/audio/references/tts.md`. If there is no narration and no `SCRIPT.md`, skip voice generation. BGM may still run if the storyboard has a music mood. @@ -200,7 +200,7 @@ The reusable, domain-agnostic shot shapes live in `../hyperframes-animation/blue | `[../hyperframes-animation/blueprints-index.md](../hyperframes-animation/blueprints-index.md)` | Step 3: role→blueprint menu. Step 4: pick the shot shape. | | `[../hyperframes-core/references/storyboard-format.md](../hyperframes-core/references/storyboard-format.md)` | Step 3: write `STORYBOARD.md`. | | `[../hyperframes-core/references/script-format.md](../hyperframes-core/references/script-format.md)` | Step 3: write `SCRIPT.md`. | -| `[../hyperframes-media/references/tts.md](../hyperframes-media/references/tts.md)` | Step 3.1: choose or understand TTS providers and voices. | +| `[../media-use/audio/references/tts.md](../media-use/audio/references/tts.md)` | Step 3.1: choose or understand TTS providers and voices. | | `[references/visual-design.md](references/visual-design.md)` | Step 4: write the frame's shot sequence (+ Layout vocabulary). | | `[references/motion-language.md](references/motion-language.md)` | Step 4: the motion vocabulary + the motion doctrine. | | `[references/cut-catalog.md](references/cut-catalog.md)` | Step 4-5: the cut catalog (worker builds within-frame seams). | diff --git a/skills/faceless-explainer/scripts/audio.mjs b/skills/faceless-explainer/scripts/audio.mjs index f1f9df1b9..864e66214 100644 --- a/skills/faceless-explainer/scripts/audio.mjs +++ b/skills/faceless-explainer/scripts/audio.mjs @@ -1,12 +1,14 @@ #!/usr/bin/env node -// audio.mjs — faceless-explainer audio ADAPTER. The TTS / BGM / SFX implementation +// audio.mjs — audio ADAPTER (reuses the product-launch SCRIPT.md / STORYBOARD.md +// model; this file is intentionally identical across the reusing skills). The +// TTS / BGM / SFX implementation // no longer lives here: it is the shared engine at -// ../../hyperframes-media/scripts/audio.mjs. This file only (a) maps the -// frame model (SCRIPT.md frames + STORYBOARD.md music/sfx) into the +// ../../media-use/audio/scripts/audio.mjs. This file only (a) maps the +// product-launch model (SCRIPT.md frames + STORYBOARD.md music/sfx) into the // engine's neutral audio_request.json, (b) converts the engine's id-keyed // audio_meta back into the frame-keyed shape captions.mjs / assemble-index.mjs // already consume, and (c) keeps the local `sync-durations` pass (it rewrites -// STORYBOARD.md, which is this skill's concern). +// STORYBOARD.md, which is product-launch-specific). // // Three modes (unchanged CLI surface): // (default) generate — engine --only tts,bgm. BGM mode is "retrieve" (strict: @@ -27,7 +29,7 @@ import { fileURLToPath } from "node:url"; import { parseStoryboard } from "./lib/storyboard.mjs"; const HERE = dirname(fileURLToPath(import.meta.url)); -const DEFAULT_ENGINE = join(HERE, "..", "..", "hyperframes-media", "scripts", "audio.mjs"); +const DEFAULT_ENGINE = join(HERE, "..", "..", "media-use", "audio", "scripts", "audio.mjs"); const flag = (argv, name, def) => { const i = argv.indexOf(`--${name}`); @@ -86,9 +88,9 @@ function runEngine({ request, hyperframesDir, neutral, only, extra = [] }, die) if (r.status !== 0) die(`media audio engine exited ${r.status}`); } -// Engine neutral meta (id-keyed) → frame-keyed meta consumed by +// Engine neutral meta (id-keyed) → product-launch meta (frame-keyed) consumed by // captions.mjs / assemble-index.mjs. id is the zero-padded frame number. -function toFrameKeyedMeta(neutral) { +function toProductLaunchMeta(neutral) { const voices = (neutral.voices ?? []).map((v) => ({ frame: Number(v.id), path: v.path, @@ -152,7 +154,7 @@ function runGenerate(argv) { const neutral = neutralPath(outPath); runEngine({ request, hyperframesDir, neutral, only: "tts,bgm" }, die); - const meta = toFrameKeyedMeta(JSON.parse(readFileSync(neutral, "utf8"))); + const meta = toProductLaunchMeta(JSON.parse(readFileSync(neutral, "utf8"))); writeFileSync(outPath, JSON.stringify(meta, null, 2)); console.log( `✓ audio generate: ${meta.voices.length} voice + ${meta.bgm ? "1 bgm" : "no bgm"} → ${outPath}`, @@ -189,7 +191,7 @@ function runFetchSfx(argv) { // voices/bgm written by the earlier generate (--only tts,bgm) pass are preserved. runEngine({ request, hyperframesDir, neutral, only: "sfx" }, die); - const meta = toFrameKeyedMeta(JSON.parse(readFileSync(neutral, "utf8"))); + const meta = toProductLaunchMeta(JSON.parse(readFileSync(neutral, "utf8"))); writeFileSync(outPath, JSON.stringify(meta, null, 2)); console.log(`✓ audio fetch-sfx: ${meta.sfx.length} SFX cue(s) → ${outPath}`); } diff --git a/skills/general-video/SKILL.md b/skills/general-video/SKILL.md index 2a4b5d376..c3f1975b3 100644 --- a/skills/general-video/SKILL.md +++ b/skills/general-video/SKILL.md @@ -96,24 +96,24 @@ Never use `position: absolute; top: Npx` on a content container — it overflows ## Build — delegate to the domain skills -This maps the skill's full surface (see the `description`) to its references — non-exhaustive; when an intent isn't listed, route through `hyperframes-creative` (look/concept), `hyperframes-animation` (motion), `hyperframes-core` (contract), `hyperframes-media` (audio/captions). **The first row is ADDITIVE — read it AND your intent row, not one or the other.** +This maps the skill's full surface (see the `description`) to its references — non-exhaustive; when an intent isn't listed, route through `hyperframes-creative` (look/concept), `hyperframes-animation` (motion), `hyperframes-core` (contract), `media-use` (audio/captions). **The first row is ADDITIVE — read it AND your intent row, not one or the other.** -| Building… | Read first (in order) | -| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **ALWAYS — every non-trivial piece, on top of your intent row below** | `hyperframes-creative/references/house-style.md` + `references/video-composition.md` (also gated in Step 1 / HARD-GATE; the "produced, not generated" foreground detailing) | -| **Kinetic typography / text-forward** | `hyperframes-animation/techniques.md` (kinetic type) + `adapters/gsap-easing-and-stagger.md` + `rules/kinetic-beat-slam.md` | -| **Title card / lower-third / overlay / PiP / text-behind-subject** | `hyperframes-creative/references/composition-patterns.md` + (for the centered/sized frame) `hyperframes-core` → "Root must be sized" | -| **Logo / brand-mark reveal** | `hyperframes-animation/rules/svg-path-draw.md` (draw-on) + `rules/3d-text-depth-layers.md` + `rules/scale-swap-transition.md` | -| **Data / stats / numbers** | `hyperframes-animation/rules/counting-dynamic-scale.md` + `rules/stat-bars-and-fills.md` + `hyperframes-creative/references/data-in-motion.md` | -| **Product / app / UI demo** | `hyperframes-animation/rules/3d-page-scroll.md` + `rules/cursor-click-ripple.md` + `rules/press-release-spring.md` | -| **Audio-reactive / music-driven** | `hyperframes-creative/references/audio-reactive.md` (pre-extract bands; map to motion) | -| **Narrated / voiceover / music / SFX / captions** | `hyperframes-media` → the shared audio engine `scripts/audio.mjs` (one call = TTS + BGM + SFX → `audio_meta.json`); caption authoring + asset placement via `hyperframes-core`. See **Audio** below. | -| **Multi-scene / transitions** | `hyperframes-animation/transitions/overview.md` **then** `transitions/catalog.md` (you are not done after the overview — the GSAP recipe is in the catalog) | -| **Modular / sub-compositions** | `hyperframes-core/references/composition-patterns.md` + `references/sub-compositions.md` | +| Building… | Read first (in order) | +| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **ALWAYS — every non-trivial piece, on top of your intent row below** | `hyperframes-creative/references/house-style.md` + `references/video-composition.md` (also gated in Step 1 / HARD-GATE; the "produced, not generated" foreground detailing) | +| **Kinetic typography / text-forward** | `hyperframes-animation/techniques.md` (kinetic type) + `adapters/gsap-easing-and-stagger.md` + `rules/kinetic-beat-slam.md` | +| **Title card / lower-third / overlay / PiP / text-behind-subject** | `hyperframes-creative/references/composition-patterns.md` + (for the centered/sized frame) `hyperframes-core` → "Root must be sized" | +| **Logo / brand-mark reveal** | `hyperframes-animation/rules/svg-path-draw.md` (draw-on) + `rules/3d-text-depth-layers.md` + `rules/scale-swap-transition.md` | +| **Data / stats / numbers** | `hyperframes-animation/rules/counting-dynamic-scale.md` + `rules/stat-bars-and-fills.md` + `hyperframes-creative/references/data-in-motion.md` | +| **Product / app / UI demo** | `hyperframes-animation/rules/3d-page-scroll.md` + `rules/cursor-click-ripple.md` + `rules/press-release-spring.md` | +| **Audio-reactive / music-driven** | `hyperframes-creative/references/audio-reactive.md` (pre-extract bands; map to motion) | +| **Narrated / voiceover / music / SFX / captions** | `media-use` → the shared audio engine `scripts/audio.mjs` (one call = TTS + BGM + SFX → `audio_meta.json`); caption authoring + asset placement via `hyperframes-core`. See **Audio** below. | +| **Multi-scene / transitions** | `hyperframes-animation/transitions/overview.md` **then** `transitions/catalog.md` (you are not done after the overview — the GSAP recipe is in the catalog) | +| **Modular / sub-compositions** | `hyperframes-core/references/composition-patterns.md` + `references/sub-compositions.md` | ### Audio: one engine (TTS · BGM · SFX) -Only when the piece calls for it (per "build exactly what was asked" — no ambient music on a title card). Don't hand-roll TTS or vendor a copy: write a neutral `audio_request.json` and call the shared engine in `hyperframes-media`. It auto-degrades on one switch — HeyGen credential present → HeyGen TTS + music/SFX **retrieval**; absent → ElevenLabs/Kokoro TTS, Lyria/MusicGen BGM **generation**, and the bundled SFX library. Full flag list + request/meta schema: the header comment of `hyperframes-media/scripts/audio.mjs`. +Only when the piece calls for it (per "build exactly what was asked" — no ambient music on a title card). Don't hand-roll TTS or vendor a copy: write a neutral `audio_request.json` and call the shared engine in `media-use`. It auto-degrades on one switch — HeyGen credential present → HeyGen TTS + music/SFX **retrieval**; absent → ElevenLabs/Kokoro TTS, Lyria/MusicGen BGM **generation**, and the bundled SFX library. Full flag list + request/meta schema: the header comment of `media-use/audio/scripts/audio.mjs`. ```jsonc // audio_request.json — one line per narrated segment; `id` is yours (joins audio_meta back) @@ -127,11 +127,11 @@ Only when the piece calls for it (per "build exactly what was asked" — no ambi ``` ```bash -# = the installed hyperframes-media skill dir (sibling of this skill) +# = the installed media-use skill dir (sibling of this skill) node /scripts/audio.mjs --request ./audio_request.json --hyperframes . --out ./audio_meta.json ``` -Then read `audio_meta.json`: mount each `voices[].path` + (`bgm.path`, `sfx[]`) as `