media-use — Skillopedia

Plugin installs: Before setup or freshness commands, follow plugin execution rules when this skill is inside a HyperFrames plugin. Media in HyperFrames Media lands as a local file in the project's with a ledger record; renders never fetch. One verb finds or makes it: It prints one line, . List reusable assets first with and judge the fit yourself; reuse, ingest ( ) and adopt are in . Where it comes from | Need | Free | HyperFrames credits | Local or the person's own key (only when they ask) | | --- | --- | --- | --- | | Music ( ) | HeyGen catalog of 10k+ tracks (signed in) | Generated track |…

\u003cSKILL_DIR>/references/media-treatment-recipes.md`,\nthen read only from that heading to the next `##`. Do not load the entire\ncookbook for one request.\n\nWhen source intent is unclear, inspect the concise capability overview:\n\n```bash\nhyperframes media-treatment --capabilities --json\n```\n\nIt lists the complete surface by family with one-line descriptions. Then load\nonly the family, effect, preset, or palette relevant to the inspected source:\n\n```bash\nhyperframes media-treatment --capability \u003cid> --json\n```\n\nThe focused result provides legal controls, recommended apply values, render\ncost, palette support, and the exact animation contract when supported. Use\n`--all` only for tooling/tests or a genuinely exhaustive audit. Compose one\nnested payload from these existing parts. Recipes and catalog-built payloads\nuse the same renderer and persistence contract.\n\nTreat `renderLane: \"multipass\"` as a cost signal. Blur, Bloom, and Kuwahara are\nbounded but more expensive than single-pass effects; avoid stacking several of\nthem across many simultaneous media elements unless the composition needs it,\nthen verify playback and a draft render.\nCost follows treated pixel area as well as element count. More than two\nsimultaneously visible full-frame multipass media layers requires a continuous\nplayback check on the target machine; simplify or pre-render the stack if it\ndrops frames. Do not impose or claim a universal hard cap from one machine.\n\n## Common workflow\n\n1. Confirm the target is a real `\u003cimg>` or `\u003cvideo>` and inspect source color\n metadata.\n2. For an image, read it once. For video, capture early/middle/late output as\n one labeled sheet and read that one image:\n\n ```bash\n hyperframes snapshot \u003cproject> --frames 3 --no-end --describe false \\\n --output snapshots/treatment-before\n ```\n\n Read `snapshots/treatment-before/contact-sheet.jpg`; do not spend separate\n model turns reading each frame unless the sheet exposes a specific problem.\n Do not infer semantics from signal statistics alone.\n\n3. Choose one primary lane. Use one matching recipe as a tested seed, or read\n the overview and one focused capability detail when the request is bespoke.\n A seed may be changed or combined with compatible catalog controls when the\n contact sheet justifies it. Do not invent keys, exceed reported ranges, or\n stack effects without a visual reason. Do not run the generic grade/LUT\n resolver first; it adds irrelevant candidates and may download an unused\n LUT. Use `media-treatment --selector \"#hero\" --analyze --json` only when\n correction needs measured signal evidence.\n4. Persist pixel settings with `hyperframes media-treatment`; it validates and\n merges a patch into the existing nested `data-color-grading` contract. Use registered\n GSAP only for supported animated values and Registry overlay blocks only\n for authored dressing.\n ```bash\n hyperframes media-treatment --selector \"\u003cselector>\" \\\n --grading '\u003cnested JSON patch>' --apply --json\n ```\n A selector that matches several images or videos patches every match, each\n merged into its own current grading (the JSON reports `count` and each\n target); run `--clear` first for an identical look, or add\n `--selector-index` to patch only one.\n For a temporal reveal, use the focused capability result's `animation`\n contract. If it is `null`, the capability is static. Author the starting CSS\n property inline on the real media element and return temporary treatment\n values to neutral so the finished shot preserves its existing pixels.\n Prefer that bounded media animation first; if an overlay is justified,\n install the owned Registry block instead of recreating it with bespoke\n overlay markup.\n For correction and ordinary polish, keep those values as editable\n preset/adjustment JSON; do not generate a LUT for controls the realtime shader\n already owns.\n Use the canonical `details`/`effects` fields for vignette, grain, blur,\n pixelate, and related primitives. Do not duplicate them with CSS filters,\n SVG turbulence, opacity, or decorative DOM overlays.\n5. When the treatment calls for an overlay, install that named block with\n `hyperframes add \u003cname> --dir \u003cproject> --no-clipboard --json`, inspect its\n returned `data-composition-src` host, and place it once using the block's\n timing contract. Check for the installed file and host element\n ID before insertion; never duplicate an existing overlay block. This is one\n treatment workflow: do not make the user discover Catalog or separately ask\n for the recipe's justified overlay.\n6. For ordinary correction/polish, capture one after-sheet with the same three\n timestamps under `snapshots/treatment-after`, compare it to the before-sheet,\n and stop when the result is clearly better. Run the normal project check;\n do not encode a draft solely to prove a static correction.\n7. Escalate only when evidence requires it. Read individual frames to diagnose a\n specific visual problem. Preview and render moving evidence when judging\n treatment keyframes, glitch/tape motion, overlays, playback smoothness, LUT\n timing, or any other temporal behavior. HDR/LOG, privacy, and brand-sensitive\n work also require the existing explicit caveats and stronger verification.\n If the treatment is not clearly better, keep the source unchanged.\n8. Report the selected media, primary intent, recipe seed if used, final\n composed controls, optional overlays, and the frames/render that were\n actually checked. Do not report visual quality from command success alone.\n\n`media-treatment --analyze` provides deterministic clipping and signal\nevidence for local composition media, not subject recognition or automatic\ntaste. It reports HDR/metadata caveats and a bounded primary-correction patch;\nit does not invent wheels, curves, or HSL selections from statistics.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":14168,"content_sha256":"2125e106e7f891e14716efabda40f5d6a46284592c6f37d5a14b2b86bda96c1a"},{"filename":"references/memory.md","content":"# User memory — preferences and recipes\n\n## Preferences — remembered defaults\n\nThe lightweight tier of user memory: confirmed brief answers (destination, aspect, language, flow, storyboard, voice, style preset) persisted on the same two-tier split as assets — project `.media/preferences.json` (committed, the team inherits it) and personal `~/.media/preferences.json`. A value earns the personal tier by being confirmed in **two different projects**, so a one-off choice never pollutes the global defaults.\n\n```bash\nnode \u003cSKILL_DIR>/scripts/prefs.mjs get --hyperframes . --json # merged view (project overrides user)\nnode \u003cSKILL_DIR>/scripts/prefs.mjs record --hyperframes . --key destination --value x-feed\nnode \u003cSKILL_DIR>/scripts/prefs.mjs record --hyperframes . --key style_preset --value pin-and-paper --workflow explainer\n```\n\nOnly what the user actually confirmed gets recorded — never an inferred or defaulted value. A remembered value becomes the recommended default, shown with where it came from; it never skips a question.\n\nPreference records serialize writes with `preferences.json.lock` beside each tier's file. If a process stops while holding that lock, later records leave it in place and report \"Settings are locked…\". After confirming no HyperFrames process is recording preferences, delete the named lock file and retry. A locked personal tier does not fail the project record; personal promotion waits for a later record.\n\nKeep the project's preference file committed, and add `.media/*.lock` to the project's `.gitignore` so transient locks are never shared with the team.\n\n## Recipes — frozen video bundles\n\nThe heavyweight tier of user memory: one approved run frozen as a named, versioned bundle — `frame.md`, the storyboard skeleton (structure kept, content blanked to per-frame fill-ins), the brief skeleton (from `BRIEF.md` when the project has one — reusable frontmatter kept, run-shape and prose blanked), and the confirmed brief values. Same two tiers: project `.media/recipes/\u003cname>/` (committed) and `~/.media/recipes/\u003cname>/` (a freeze is already a confirmed bundle, so it promotes immediately — no two-project rule). Re-freezing a name bumps `version` and archives the old folder as `\u003cname>@v\u003cN>`.\n\n```bash\nnode \u003cSKILL_DIR>/scripts/recipe.mjs freeze --hyperframes . --name weekly-promo # workflow read from BRIEF.md (--workflow only for briefless projects)\nnode \u003cSKILL_DIR>/scripts/recipe.mjs list --hyperframes . --workflow explainer\nnode \u003cSKILL_DIR>/scripts/recipe.mjs use --hyperframes . --name weekly-promo # also: resolve.mjs --type recipe --entity weekly-promo\n```\n\nOffer the freeze once, after the final approval; before the first question about a new video, check `recipe.mjs list` for a match. Adopting a recipe fills the brief, the design spec, and the storyboard skeleton — and unlike preferences it may skip the questions it answers: the bundle was approved as a whole, and adoption itself is the question.\n\n## Files\n\n- `.media/manifest.jsonl`: machine SSOT, one JSON record per line. Records are keyed by path and only appended, so\n the last record for a path is the file's record; a file moved or replaced by hand keeps (or loses) its record by path.\n- `.media/index.md`: agent-readable table (id, type, dur, dims, path, description)\n- `.media/preferences.json`: the project's remembered defaults (committed)\n- `~/.media/`: global cross-project reuse cache (content-addressed, SHA-256)\n- `~/.media/preferences.json`: personal remembered defaults (promoted after two projects)\n- `.media/recipes/\u003cname>/`: frozen video bundles — recipe.json + frame.md + storyboard skeleton (committed)\n- `~/.media/recipes/\u003cname>/`: personal recipe tier (promoted on freeze)\n- `~/.media/misses.jsonl`: local-only resolve misses, including intent text for `--stats`\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":3828,"content_sha256":"55477edafb7f9c8294cafd3f1633b7a1820d538695c0868f9c3ddb6b418dadbc"},{"filename":"references/meta.md","content":"# Ownership matrix, usage stats, telemetry, privacy\n\nMaintainer-facing reference. Nothing here changes how you resolve or operate on media.\n\n## What it owns (the gaps HyperFrames leaves)\n\nHyperFrames owns media _playback_; media-use owns everything else. Each row is enforced by `packages/cli/src/media-use/lib/coverage.test.mjs` so the claim can't rot.\n\n| HyperFrames gap | media-use owns it via |\n| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Audio-only, no image/icon | `resolve --type image\\|icon` (heygen asset search) |\n| No third-party brand logos | `resolve --type logo` (theSVG → GitHub org avatar → domain favicon) |\n| No voice / audio generation | `resolve --type voice` (HeyGen TTS free-usage path; optional local Kokoro) + the audio engine (`audio/scripts/audio.mjs`) |\n| Scattered/duplicated audio engine | one consolidated engine under `audio/` (hyperframes-media retired) |\n| No agent media-ops (cut/reframe/transform) | `references/operations.md` + `resolve --from` to register outputs |\n| No transcript-driven cutting | `scripts/transcript-cut.mjs` compiles word-timestamp edits into cut lists |\n| No auto-duck / publish loudness | `scripts/audio-duck.mjs` + `references/operations.md` loudnorm/sidechain recipes |\n| No cross-project memory | global content-addressed cache + auto-promote (`~/.media`) |\n| Grade recipes and LUT freezing | `resolve --type grade` emits a paste-ready recipe and `resolve --type lut` freezes validated `.cube` files; direct element analysis/authoring lives in `hyperframes media-treatment` |\n| No image generation | `resolve --type image` — RAM-graded local mflux (FLUX), codex `image_gen` upsell |\n| No video generation | `resolve --type video` — HeyGen avatar video first (free-usage path, sign-in nudge on auth failure), local LTX fallback (`videogen` ladder); image-to-video, photo-avatar, dub/translate remain manual `heygen` CLI recipes (`references/operations.md`) |\n| Weak local-model defaults | HeyGen free-usage path via the `heygen` CLI; local open-source tools only as opt-in alternatives |\n\n## Usage stats\n\nUse `resolve --stats` for a local, shareable report over the current project's `.media/` manifest, the global `~/.media/` cache, and local resolve misses. Human output is compact; add `--json` for a single machine-readable object, and `--days N` to window timestamped records.\n\n```bash\nnpx hyperframes media-use resolve --stats --project . --days 7\n# media-use stats\n# total resolves: 12\n# misses: 2\n# hit rate: 86%\n```\n\n## Telemetry\n\n`resolve` and the edit tools (transcribe / transcript-cut / audio-duck) send a\nusage event to PostHog (`scripts/lib/telemetry.mjs`), so we can see which\ncapabilities are actually used. It is anonymous until you sign in to HeyGen\n(see Privacy below). It records only the media TYPE, the\nresolution SOURCE, and the winning PROVIDER: never the intent text, file names,\nor paths, and `$ip:null` so no IP is stored. Best-effort and non-blocking (a\nresolve never waits on or fails from telemetry).\n\nOpt out with `DO_NOT_TRACK=1` or `HYPERFRAMES_NO_TELEMETRY=1` (also off in CI and\ndev). Same public PostHog project key and opt-outs as the `hyperframes` CLI.\n\nHeyGen request tagging: every generating `heygen` call (TTS, avatar video, catalog\nsearch) carries the allowlisted `X-HeyGen-Client-Source: media-use` header, sourced\nfrom one shared constant (`HEYGEN_CLIENT_SOURCE_ARGV` in `packages/cli/src/media-use/lib/heygen-cli.mjs`)\nso a future call site can't silently ship untagged. Read-only discovery calls\n(`voice list`, `avatar list`) are intentionally left untagged.\n\n## Privacy\n\nmedia-use uses the same shared install id as the `hyperframes` CLI/studio\n(`~/.hyperframes/config.json`). When you are signed in to HeyGen, usage is\nlinked to your HeyGen account (keyed on an id derived from your username, with\nyour email and username stored on it), matching the CLI behavior. The events stay coarse: media type, source, provider, and\nsmall counts only; intent text and paths stay local. Disable telemetry with\n`HYPERFRAMES_NO_TELEMETRY=1` or `DO_NOT_TRACK=1`.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":6545,"content_sha256":"3651b66e86874b21e9636de65be5a4581f4f394f3c8fc02ddc9128f4dcfa107c"},{"filename":"references/mixing.md","content":"# Mixing in HyperFrames\n\nPreview and render run the same Web Audio graph, so what plays while scrubbing is what renders. Everything lives in attributes on the `\u003caudio>` or `\u003cvideo>` element.\n\n## Level and fades\n\n| Attribute | Meaning |\n| ------------------------------- | ----------------------------------------------------------------------------------------- |\n| `data-volume` | Track gain, 1 = 0 dB |\n| `data-fade-in`, `data-fade-out` | Edge fades in seconds |\n| `data-playback-rate` | Constant speed, 0.1–10, pitch preserved; give a video and its paired audio the same value |\n\nA crossfade is two clips on different tracks that overlap, each with a fade.\n\n## `data-automation`: envelopes\n\n```html\n\u003caudio\n id=\"music\"\n data-automation='{\"version\":1,\"lanes\":[{\"target\":\"volume\",\"points\":[{\"t\":0,\"v\":1},{\"t\":2.5,\"v\":0.35}]}]}'\n …\n>\u003c/audio>\n```\n\n- `target` is `volume`, `rate` (a speed ramp, 0.1–10, overrides `data-playback-rate`) or `fx.\u003cnodeId>.\u003cparam>`.\n- `t` is seconds from the start of the clip, not of the composition. `v` is in the parameter's unit: 0..1 for volume, dB for a gain, Hz for a frequency.\n- A `volume` lane multiplies `data-volume` in preview and render, so write the level in one of them: `data-volume=\"0.5\"` under a lane at `0.5` plays at `0.25`.\n- A lane holds its first value back to the clip's start and its last value to its end, so a bed that starts before the voice needs an explicit full-level point at `t: 0`.\n- `curve` (-1..1) bends the segment leaving a point. 512 points per lane at most.\n- Don't also tween `volume` with GSAP on a track that has a volume lane or a `data-volume`; lint flags both.\n\n## `data-fx-chain`: effects\n\n```json\n{\n \"version\": 1,\n \"nodes\": [\n { \"type\": \"highpass\", \"id\": \"n1\", \"label\": \"Remove rumble\", \"params\": { \"frequency\": 80 } },\n {\n \"type\": \"peaking\",\n \"id\": \"n2\",\n \"label\": \"Clarity\",\n \"params\": { \"frequency\": 3000, \"gain\": 2.5, \"q\": 1 }\n },\n { \"type\": \"limiter\", \"id\": \"n3\", \"params\": { \"limit\": -1 } }\n ]\n}\n```\n\n- Write the attribute double-quoted with the JSON's quotes as `"`.\n- Order is signal order. `id` is what automation targets (`fx.n2.gain`); give every node one, and a `label` when it does a named job. `enabled: false` bypasses a node.\n- Effects: `gain`, `highpass`, `lowpass`, `peaking`, `lowshelf`, `highshelf`, `compressor`, `limiter`, `gate`, `saturate`, `delay`, `reverb`, `chorus`, `phaser`, `bitcrush`.\n- `compressor`, `limiter`, `gate` and `bitcrush` can't be automated; a lane on them does nothing. Automate a `gain` before them instead.\n- Never set `fromCarve` by hand.\n- `reverb` and `delay` make the rendered track longer than its source; that is expected.\n\n| It sounds like | Reach for |\n| --------------------------- | ------------------------------------------- |\n| Hum, rumble, handling noise | `highpass` at 80 Hz |\n| Boomy, too close | `peaking` 200 Hz, −4 dB |\n| Muffled | `peaking` 250 Hz, −3 dB |\n| Words hard to make out | `peaking` 3 kHz, +2.5 dB, or duck the music |\n| Harsh | `peaking` 3.2 kHz, −3 dB |\n| Peaks clipping | `limiter` last in the chain |\n\n## Music under a voice\n\nDuck the bed with a `volume` lane on the music: full level before the voice, down to about 0.3–0.4 while anyone speaks (word timings from `npx hyperframes transcribe` or the voiceover give the times), back up after. Then carve the bed, which dips only the bands the voice uses: `node \u003cSKILL_DIR>/audio/scripts/carve.mjs --comp index.html` (needs `ffmpeg` and `@hyperframes/core` in the project; `--dry-run` to see the plan). It is the same analysis as Studio's carve panel. It reads only double-quoted attributes (JSON quotes as `"`), so write the bed's chain and lanes that way or it overwrites them. Never put a carve on a voice track.\n\n## Group buses\n\nGive clips the same `data-audio-group=\"\u003cid>\"` to treat them as one group. An `\u003chf-audio-group id=\"\u003cid>\">\u003c/hf-audio-group>` element with that id (closed like that: `/>` does not close it) makes the group a submix bus with one `data-fx-chain`, one volume and one automation clock for every member. Keep one role per group: `voiceover`, `music`, `sfx`.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4636,"content_sha256":"0ac67d3230cf1a6e31ca9355371ea133557d7e2fdb541742a02f086eac20a574"},{"filename":"references/operations.md","content":"# Media operations: agent guidance\n\nmedia-use resolves and remembers assets. For **operating** on them: cutting,\nreframing, stitching, transforming, it does not wrap every action as a bespoke\ncommand. Instead it points you at the right local tool (decision OP1). Run the\ntool, then register the output with `resolve --from \u003coutput> --type \u003ctype>` so the\nresult lands in the ledger and the global cache like any other asset.\n\nThe ffmpeg and local-model operations below run locally. Direct `heygen` recipes\nuse the HeyGen CLI's own login and HeyGen/API billing; they do not inherit a\nHyperFrames subscription. Use those recipes only when that separate payer was\nselected. `hyperframes media-use resolve` uses the HyperFrames-selected credential.\nffmpeg is assumed present (it backs the engine already).\n\n## Cut / trim: keep a slice\n\n```bash\nffmpeg -i in.mp4 -ss 00:00:12 -to 00:00:20 -c copy out.mp4 # 0:12–0:20, no re-encode\n```\n\nIn-composition trimming usually needs **no new file**: a clip plays a sub-window\nvia `data-media-start` + `data-duration` (see `/hyperframes` → `references/format.md`). Only cut a\nphysical file when exporting/assembling outside the composition.\n\n## Reframe / crop: change aspect ratio\n\n```bash\n# 16:9 -> 9:16, crop centered\nffmpeg -i in.mp4 -vf \"crop=ih*9/16:ih,scale=1080:1920\" out.mp4\n```\n\nFor a non-destructive crop, set a `clip-path` on the element in the composition\nitself (render-time, source file untouched) instead of re-encoding with ffmpeg.\n\n## Montage / stitch: join clips\n\n```bash\nprintf \"file '%s'\\n\" a.mp4 b.mp4 c.mp4 > list.txt\nffmpeg -f concat -safe 0 -i list.txt -c copy out.mp4\n```\n\n## Silence-cut / highlight: trim dead air, grab the best moment\n\n```bash\nauto-editor in.mp4 --edit audio:threshold=4% -o tight.mp4 # pip install auto-editor\nscenedetect -i in.mp4 detect-adaptive list-scenes # pip install scenedetect\n```\n\n## Transforms with a quality choice (process)\n\nThese have a local option AND a higher-quality HeyGen-CLI option. Run the local\none for free/offline; use the HeyGen CLI when quality matters. Showing the user\na **side-by-side** (local vs HeyGen) is the honest way to let them choose.\n\n| Op | Local (free) | HeyGen CLI (quality) |\n| ----------------------- | -------------------------------------------------- | --------------------------- |\n| Background removal | `hyperframes remove-background in.png` (u2net) | `heygen background-removal` |\n| Upscale | `realesrgan-ncnn-vulkan -i in.png -o out.png -s 4` | n/a |\n| Lipsync (dub) | n/a | `heygen lipsync` |\n| Translate | n/a | `heygen video-translate` |\n| Clone a voice | n/a | `heygen voice clone create` |\n| Text to video | n/a | `heygen video-agent create` |\n| Clips from a long video | n/a | `heygen ai-clipping` |\n\nAfter any op: `resolve --from out.ext --type \u003ctype>` to register the derived\nasset (it records provenance and auto-promotes to the global cache).\n\n> ponytail: media-use doesn't re-wrap ffmpeg/heygen here, that's deliberate\n> (OP1). The value it adds is the ledger + global reuse on the _output_, via\n> `--from`. Add a thin `process` verb only if agents repeatedly fumble these\n> recipes.\n\n## Exact error-diffusion dither\n\nUse the local processor when the requested look specifically calls for\nFloyd-Steinberg, Atkinson/Macintosh, Jarvis-Judice-Ninke, Stucki, Burkes, or a\nSierra variant. These are sequential error-diffusion algorithms, not the\nrealtime Bayer `effects.dither` shader.\n\n```bash\nnode \u003cSKILL_DIR>/scripts/dither.mjs \\\n --input source.mp4 \\\n --out source.atkinson.mp4 \\\n --algorithm atkinson \\\n --palette '#0f380f,#306230,#8bac0f,#9bbc0f' \\\n --point-size 3\n\nnpx hyperframes media-use resolve \\\n --from source.atkinson.mp4 --type video --project .\n```\n\nAvailable algorithms: `floyd-steinberg`, `atkinson`,\n`jarvis-judice-ninke`, `stucki`, `burkes`, `sierra`, `sierra-lite`, and\n`two-row-sierra`. The default is balanced Floyd-Steinberg with a black/white\npalette. Palettes contain 2-6 `#rrggbb` colors in authored dark-to-light order;\nreversing the order intentionally inverts the mapping. `--point-size` controls\n1-20px blocks; `--brightness` and `--contrast` accept 0.5-2; `--detail` accepts\n0.1-1.\n\nThe processor supports ordinary SDR images and MP4 video, preserves video\naudio, and emits BT.709 MP4. It rejects tagged PQ/HLG input rather than silently\ntone-mapping it. To animate the transformation, keep the original and processed\nfiles as two real media layers and use the seek-safe GSAP timeline to reveal or\ncrossfade between them. Use the realtime Bayer shader instead when the dither\namount itself must animate continuously.\n\n## Transcription (default: Parakeet, better than whisper.cpp)\n\n`transcribe.mjs` is the default local transcription path. It runs **NVIDIA\nParakeet-TDT via parakeet-mlx**, which beats whisper.cpp on the Open ASR\nLeaderboard (avg WER ~6.05% vs 7.44%; on NOISY audio 4.73% vs 5.96%, where\nwhisper-large-v3 hallucinated to 308% WER on meetings) and is 5-10x faster.\nIt emits `{ text, words:[{text,start,end}] }` with word timestamps (merged from\nParakeet's sub-word tokens), feeding transcript-cut, captions, and the audio\nengine directly.\n\n```bash\n# install once: uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx\nnode \u003cSKILL_DIR>/scripts/transcribe.mjs --input talk.mp4 --out talk.transcribe.json\n\n# the hyperframes CLI runs Parakeet on macOS, Linux and Windows once it is installed:\nnpx hyperframes models install parakeet # once, ~640 MB, ask the user first\nnpx hyperframes transcribe talk.mp4 --engine parakeet # or --engine auto (default)\n```\n\nVERIFIED on 24GB: accurate, ~3s (cached) for 8s audio. Parakeet covers 25\nEuropean languages, English included. For other languages, or when parakeet-mlx is not\ninstalled, transcribe.mjs falls back to `hyperframes transcribe`, which uses the\nCLI's Parakeet when `models install parakeet` has run and whisper.cpp (99\nlanguages) otherwise. `--engine parakeet|whisper` forces one, except that a\n`--language` other than English runs whisper whenever it is installed, since\nParakeet detects the language itself. (Cohere\nTranscribe tops the leaderboard on paper but its mlx-audio quants produced\ngarbage and ran 40-70x slower on a Mac in testing, so it is not wired in.)\n\n## Text-based editing (transcript cut)\n\n`transcript-cut.mjs` is a compiler, not a wrapper: it turns word timestamps and\nagent cut decisions into exact kept segments. It is provided even though the rest\nof this file is guidance-only.\n\n```bash\nnode \u003cSKILL_DIR>/scripts/transcript-cut.mjs \\\n --input talk.mp4 \\\n --transcript talk.transcribe.json \\\n --remove \"12.41-15.02,88.3-91.7\" \\\n --remove-fillers \"um,uh,like\" \\\n --cut-silence 0.8 \\\n --out talk.cut.mp4\n\nresolve --from talk.cut.mp4 --type video\n```\n\nUse `--plan` first when you want to inspect the kept segment JSON before encoding.\n\n## Ducking (declare in-composition / bake for export)\n\nB1, declare ducking in the composition. `audio-duck.mjs` emits a volume lane\nas a `data-automation` attribute. Add it to the background `\u003caudio>` element;\nthe source file stays untouched. Lane times are clip-local, so pass\n`--composition` to let the script subtract the element's `data-start`.\n\n```bash\nnode \u003cSKILL_DIR>/scripts/audio-duck.mjs \\\n --meta audio_meta.json \\\n --target \"#bgm\" \\\n --composition index.html\n```\n\n```html\n\u003c!-- auto-duck: #bgm under narration; add to its \u003caudio> element -->\ndata-automation='{\"version\":1,\"lanes\":[{\"target\":\"volume\",\"points\":[{\"t\":0,\"v\":0.6},{\"t\":3.42,\"v\":0.6},{\"t\":3.57,\"v\":0.15},{\"t\":9.87,\"v\":0.15},{\"t\":10.27,\"v\":0.6}]}]}'\n```\n\nB2, bake ducking only for exported or standalone files.\n\n```bash\nffmpeg -i bgm.mp3 -i voice.wav \\\n -filter_complex \"[0][1]sidechaincompress=threshold=0.03:ratio=8:attack=200:release=400[ducked]\" \\\n -map \"[ducked]\" bgm.ducked.wav\n```\n\nDeclare inside compositions. Bake only for assets leaving the hyperframes\npipeline.\n\n## Publish loudness\n\nTwo-pass `loudnorm` measures first, then applies the measured values with the\ntarget LUFS baked in.\n\nSocials target, -14 LUFS:\n\n```bash\nffmpeg -i mix.wav \\\n -af loudnorm=I=-14:TP=-1.5:LRA=11:print_format=json \\\n -f null -\n\nffmpeg -i mix.wav \\\n -af loudnorm=I=-14:TP=-1.5:LRA=11:measured_I=\u003cinput_i>:measured_TP=\u003cinput_tp>:measured_LRA=\u003cinput_lra>:measured_thresh=\u003cinput_thresh>:offset=\u003ctarget_offset>:linear=true:print_format=summary \\\n mix.social.wav\n```\n\nPodcast target, -16 LUFS:\n\n```bash\nffmpeg -i mix.wav \\\n -af loudnorm=I=-16:TP=-1.5:LRA=11:print_format=json \\\n -f null -\n\nffmpeg -i mix.wav \\\n -af loudnorm=I=-16:TP=-1.5:LRA=11:measured_I=\u003cinput_i>:measured_TP=\u003cinput_tp>:measured_LRA=\u003cinput_lra>:measured_thresh=\u003cinput_thresh>:offset=\u003ctarget_offset>:linear=true:print_format=summary \\\n mix.podcast.wav\n```\n\n## Generate: images (local first, cloud upsell)\n\n`resolve --type image` retrieves from the HeyGen catalog first; on a miss it\nGENERATES. Two paths, best-for-the-machine picked automatically:\n\n1. **Local (default, free, private): mflux** (FLUX-on-MLX). `resolve` spec-checks\n AVAILABLE RAM and runs the best FLUX-class model that fits, using the\n CLI-bundled `imagegen` ladder (its modules are not shipped in the standalone\n skill). The RAM ladder:\n\n | Tier | Model | Needs (available RAM) | Notes |\n | ------ | -------------------- | --------------------- | ----------------------------------- |\n | medium | FLUX.1 schnell int4 | ~8GB (`--low-ram`) | ~20s/512px on 24GB. VERIFIED. Fast. |\n | large | FLUX.2 Klein 4B int4 | ~32GB | higher quality, full-resident |\n | xlarge | Qwen-Image | ~64GB | top quality, 64GB+ Macs only |\n\n Gotchas baked into the table: the official FLUX repos are HF-gated, so it\n points at non-gated community 4-bit re-uploads; and `--low-ram` is MANDATORY\n at the medium tier (without it a 768x512 run swap-thrashed to 90 minutes on\n 24GB; with it, 20 seconds).\n\n2. **Cloud upsell (better quality): the `codex` CLI** `image_gen` tool, on the\n user's ChatGPT subscription (codex owns auth, no key here, no per-call\n charge). It is the automatic fallback when no local model fits AND the\n explicit \"make it better\" choice on any machine. Users who just want codex\n can ask for it directly. Verified: prompt -> raster -> frozen + ledgered.\n\n`--local-only` keeps mflux (once cached) and skips codex (network).\n\n## Generate: video (`resolve --type video`, HeyGen avatar first)\n\n`resolve --type video \"\u003cintent>\"` is the default path. It generates a\nscript-driven HeyGen avatar video first using the HyperFrames-selected credential\n(the server decides eligibility and charges; explicit API keys use API billing), falling back to local generative LTX only when\nHeyGen is unavailable, uncredentialed, or `--local-only` is passed. The two\nare non-substitutable outputs (a real presenter vs. a generic generative\nclip), so treat the fallback as \"HeyGen wasn't reachable,\" not \"upgrade the\nquality\":\n\n- **HeyGen avatar video (default):**\n The CLI-bundled provider shells the\n `heygen` CLI — never the raw API — auto-picking a public avatar and a\n starfish voice (override with `--avatar-id`/`--voice-id`, threaded through\n as `ctx.avatarId`/`ctx.voiceId`). If the CLI reports `not_authenticated`,\n the provider prints a HyperFrames sign-in recommendation to stderr and falls through to LTX instead of\n hard-failing.\n- **Local fallback: LTX 2.3 on MLX** via `dgrauet/ltx-2-mlx`, the `videogen`\n ladder bundled in the HyperFrames CLI. Generative clips\n (t2v), spec-gated to RAM. Verified on 24GB: 512x320 x 33f with audio.\n\nEvery generating `heygen` call from media-use — TTS, avatar video, and\ncatalog search — sends the allowlisted `X-HeyGen-Client-Source: media-use`\nheader (persistent flag, works on every subcommand) via the shared\nCLI-internal `HEYGEN_CLIENT_SOURCE_ARGV` constant, so usage\ntags correctly in billing/resource meta and shows up in the API dashboards.\nRead-only discovery (`avatar list`, `voice list`) doesn't need it.\n\nFor structured bodies `resolve --type video` doesn't expose yet (a specific\n`avatar_id`/`voice_id` combination beyond the ctx overrides, or a\npre-recorded `audio_url` instead of a script), the raw `heygen video create`\nrecipe below remains the escape hatch. This direct command uses the separate\nHeyGen CLI credential and HeyGen/API billing, not the HyperFrames subscription:\n\n```bash\n# discover an avatar + a starfish voice, then create + wait\nheygen avatar list --ownership public --limit 5\nheygen voice list --engine starfish --limit 5\nheygen video create --headers \"X-HeyGen-Client-Source: media-use\" --wait -d '{\n \"type\": \"avatar\",\n \"avatar_id\": \"\u003cavatar-id>\",\n \"script\": \"Your narration here.\",\n \"voice_id\": \"\u003cvoice-id>\"\n}'\n```\n\nAvatar videos are deterministic + script-driven (lip-sync from a script or a\npre-recorded `audio_url`), distinct from the generative LTX clips. After a\nmanual recipe renders, `resolve --from \u003cdownloaded.mp4> --type video` to\nledger it (not needed when generating via `resolve --type video` directly —\nthat already ledgers the result).\n\n### Image-to-video (animate any still into a talking clip)\n\nNot wired into `resolve --type video` (deferred — the `avatar` type covers\nthe default script-driven case). `heygen video create` takes the raw\n`POST /v3/videos` body, so switching `type`\nfrom `avatar` to `image` animates **any image of a person** into a lip-synced\ntalking video, with no avatar/photo-avatar creation step first. Point `image` at a\npublic URL or an uploaded `asset_id`, and drive speech with a `script`+`voice_id`\nor a pre-recorded `audio_url`:\n\n```bash\nheygen video create --headers \"X-HeyGen-Client-Source: media-use\" --wait -d '{\n \"type\": \"image\",\n \"image\": { \"type\": \"url\", \"url\": \"https://example.com/person.jpg\" },\n \"script\": \"Your narration here.\",\n \"voice_id\": \"\u003cvoice-id>\"\n}'\n```\n\nCommon optional fields: `title`, `resolution` (`4k`/`1080p`/`720p`),\n`aspect_ratio`, `remove_background`, `background`, `voice_settings`,\n`motion_prompt` + `expressiveness` (photo-avatar animation), and\n`callback_url`/`callback_id` for webhooks. Don't hardcode these from memory: the\nCLI self-documents the full, current body with\n`heygen video create --request-schema` (a discriminated union keyed on `type`),\nso read the schema rather than trusting a stale field list. For a still you'll\nreuse across many scripts, create a reusable **Photo Avatar** once instead\n(`heygen avatar create`). Ledger the result with\n`resolve --from \u003cdownloaded.mp4> --type video`. Docs:\n\u003chttps://developers.heygen.com/image-to-video>.\n\n## HEVC / H.265 sources\n\nHEVC/H.265 sources need no conversion for **render** (FFmpeg pre-decodes all\ninput video) or for **preview** (auto-proxy transcodes and caches an H.264\ncopy on first use, disable with `--no-proxy` or `media.autoProxy: false` in\nhyperframes.json). A manual H.264 proxy via `ffmpeg -i in.mp4 -c:v libx264\n-crf 18 proxy.mp4`, registered with `resolve --from`, remains available for\nedge cases (e.g. auto-proxy disabled, or ffmpeg unavailable at preview time).\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":15534,"content_sha256":"f59189bb31501c9b55c45311ac2bf36c8652c17010c5f8a4d81b9274ae84b810"},{"filename":"references/resolve.md","content":"# Resolve — command, flags, reuse, adopt, inventory\n\n```bash\nnpx hyperframes media-use resolve --type \u003ctype> --intent \"\u003cdescription>\" --project \u003cdir>\n```\n\nReturns one line: `resolved \u003cid> → \u003cpath> (\u003ctype>, \u003cmetadata>)`\n\n## Types\n\n| Type | What it finds | Provider / cascade |\n| ------- | -------------------------------- | ------------------------------------------------------------ |\n| `bgm` | Background music | HeyGen audio catalog (10k+ tracks) |\n| `sfx` | Sound effects | Openverse (CC0 / CC BY), then the bundled 21-file library |\n| `image` | Photos, backgrounds | HeyGen asset search (75k+ vectors) |\n| `icon` | Icons, symbols | HeyGen asset search (type=icon) |\n| `logo` | Official brand marks | theSVG → GitHub org avatar → domain favicon |\n| `voice` | TTS voiceover | HeyGen TTS free-usage path; optional local Kokoro |\n| `grade` | HyperFrames color-grading blocks | Core preset → look index params/CDN LUT → deterministic cube |\n| `lut` | Reusable `.cube` LUT files | Look index params/CDN LUT → deterministic cube |\n\n## Examples\n\n```bash\n# Background music\nnpx hyperframes media-use resolve --type bgm --intent \"upbeat tech launch\" --project .\n# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)\n\n# Sound effect\nnpx hyperframes media-use resolve --type sfx --intent \"whoosh\" --project .\n# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)\n\n# Image\nnpx hyperframes media-use resolve --type image --intent \"gradient tech background\" --project .\n# → resolved image_001 → .media/images/image_001.jpg (image)\n\n# Icon\nnpx hyperframes media-use resolve --type icon --intent \"rocket\" --project .\n# → resolved icon_001 → .media/images/icon_001.png (icon, transparent)\n\n# Brand logo (official mark — never redrawn by hand)\nnpx hyperframes media-use resolve --type logo --entity linkedin --intent \"LinkedIn logo\" --project .\n# → resolved logo_001 → .media/images/logo_001.svg (logo, official mark)\n\n# Color grade block\nnpx hyperframes media-use resolve --type grade --intent \"warm daylight\" --project . --json\n# → {\"ok\":true,\"preset\":\"warm-daylight\",\"grading\":{\"preset\":\"warm-daylight\",\"intensity\":1},...}\n\n# LUT file\nnpx hyperframes media-use resolve --type lut --intent \"teal orange blockbuster\" --project .\n# → resolved lut_001 → .media/luts/lut_001.cube (lut)\n```\n\n## Flags\n\n| Flag | Description |\n| --------------- | ------------------------------------------------------------------------------------ |\n| `--type, -t` | Media type: bgm, sfx, image, icon, logo, voice, grade, lut |\n| `--intent, -i` | What you need (natural language) |\n| `--entity, -e` | Entity name for cache matching (optional) |\n| `--project, -p` | Project directory (default: .) |\n| `--candidates` | List reusable assets (project + global cache) for `--type`; no download, no mutation |\n| `--reuse \u003csha>` | Import a specific global-cache asset (by content sha/prefix, from `--candidates`) |\n| `--from` | Freeze a local file or direct public URL (ingest) |\n| `--for` | Analyze a local image/video and add measured adjust suggestions (`grade` only) |\n| `--local-only` | Offline: skip every network provider (cache + local only) |\n| `--provider` | Force one generator (e.g. `codex`, `mflux`, `kokoro`, `heygen`) |\n| `--adopt` | Bulk-import existing assets/ into manifest |\n| `--doctor` | Check local CLI dependencies; no manifest changes |\n| `--stats` | Print local usage stats from `.media/` and `~/.media`; no manifest changes |\n| `--days N` | Limit `--stats` to timestamped records/misses from the last N days |\n| `--json` | Output JSON instead of one-line result |\n\n## Reuse before you resolve\n\nBefore resolving bgm/sfx/image/icon/logo/grade/lut, **check what already exists and reuse it when it fits.** media-use does not semantically match for you — you are the judge. It surfaces candidates; you decide.\n\n```bash\nnpx hyperframes media-use resolve --type bgm --intent \"upbeat tech launch\" --candidates --project .\n# [project] upbeat tech launch (25s, heygen.audio.sounds)\n# .media/audio/bgm/bgm_001.wav\n# [global] energetic tech intro (22s, heygen.audio.sounds)\n# --reuse 06e052c075fd2b80\n```\n\nRead the list and judge semantic fit yourself — \"upbeat tech launch\" ≈ \"energetic tech intro\" is a call only you can make from the descriptions. Then:\n\n- **A project candidate fits** → just reference its path in your composition. Nothing else to run.\n- **A global candidate fits** → `resolve --type bgm --reuse \u003csha>` copies it into this project (self-contained render) and records it.\n- **Nothing fits** → resolve fresh (`--type ... --intent ...`).\n\n**Trust guardrail — when unsure, resolve fresh.** A redundant download is cheap; shipping the wrong asset is not. Judge fit from description + prompt + type + duration/dims. For **brand/entity** assets, reuse a _global_ candidate only when the entity matches exactly — the global cache aggregates every project you have worked on, so a `--candidates` list can surface another client's brand mark and its prompt text. Never reuse a cross-project brand asset on a loose match.\n\nThe deterministic floor still runs automatically: an identical (case/whitespace-insensitive) repeat auto-reuses with no `--candidates` step. `--candidates` is only for the semantic layer above that floor — and a fuzzy match is **never** auto-applied; reuse is always your explicit call. On a resolve that misses the floor and is about to fetch, media-use prints a one-line stderr hint when similar cached assets exist, pointing you back here.\n\n## How it works\n\n`resolve` runs an automatic floor, then falls through to fetching:\n\n1. Check project `.media/manifest.jsonl` for a prompt match (case- and whitespace-insensitive) — auto-reuse\n2. Scan existing `assets/` directory for unregistered files that share a word with the need\n3. Check global cache `~/.media/` for a reusable asset matched on the same normalized prompt — auto-reuse\n4. Search via provider (HeyGen audio catalog, HeyGen asset search), or resolve color locally\n5. Freeze file to `.media/\u003ctype>/`, register in manifest, regenerate `index.md`, auto-promote to `~/.media/`\n\nSteps 1 and 3 are the **deterministic floor**: they only auto-reuse an exact-normalized match, never a fuzzy one. Semantic reuse (\"close enough\") is the agent's explicit call via [Reuse before you resolve](#reuse-before-you-resolve) — it never happens automatically. The agent gets back **one line**; candidates, scores, provenance stay on disk.\n\n## Stamping provenance when mounting a resolved video\n\n`resolve` never writes composition HTML itself — mounting a `\u003cvideo>` element\ninto a composition is always the agent's own edit. When the mounted video's\nmanifest record has `provenance.provider === \"heygen.video\"` (check\n`.media/manifest.jsonl` or the one-line resolve output for the provider name),\nadd `data-media-source=\"heygen\"` to that `\u003cvideo>` tag. Leave the attribute off\nentirely for every other provider (`ltx.local`, an adopted/local file, etc.) —\nthis is not a general provider taxonomy, just the one signal render telemetry\ntracks today.\n\n## Adopt existing projects\n\nMost HyperFrames projects already have assets in `assets/`. media-use adopts them:\n\n```bash\nnpx hyperframes media-use resolve --adopt --project .\n# → adopted 9 assets from assets/\n# bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)\n# image_001 → assets/images/avatar.jpg (image, 400×400)\n```\n\n`ffprobe` extracts real duration and dimensions. During resolve, unregistered files in `assets/` matching the intent are adopted on the fly.\n\n## Reading the inventory\n\nAfter resolve or adopt, read `.media/index.md` for the full inventory:\n\n```\n# .media · 4 assets\n\nid type dur dims path description\nbgm_001 bgm 25s - .media/audio/bgm/bgm_001.mp3 upbeat tech launch\nsfx_001 sfx 0.6s - .media/audio/sfx/sfx_001.mp3 whoosh\nimage_001 image - 1920×1080 .media/images/image_001.jpg gradient tech background\nicon_001 icon - 200×200 .media/images/icon_001.png rocket\n```\n\n## Cross-project reuse\n\nAssets are cached automatically on resolve. Every resolved/ingested asset is auto-promoted to the global cache at `~/.media/`, so subsequent resolves for the same (or near-identical) prompt, in any project, hit the cache with no re-download and no provider call.\n\nFor a _semantically_ similar (not identical) need in another project, the exact-match floor won't fire — use [Reuse before you resolve](#reuse-before-you-resolve): `--candidates` lists the global assets, and `--reuse \u003csha>` imports the one you pick. This is how a track resolved in one project gets reused in the next when the wording differs.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":9605,"content_sha256":"c90a833f6c3dcc8f33b289f5ad90e9f835f59581873bdc774035f25b6eb72314"},{"filename":"references/setup-providers.md","content":"# Setup and providers — install, auth, RAM ladders, forcing a provider\n\n## Setup — install the helper and sign in to HyperFrames\n\nInstall the HeyGen CLI through its [verified release instructions](https://developers.heygen.com/cli), then run:\n\n```bash\nheygen update # requires v0.3.0+\nnpx hyperframes auth login # dedicated HyperFrames OAuth session\n```\n\nHyperFrames owns the OAuth session in `~/.hyperframes/credentials` and supplies an access-only temporary credential to the HeyGen helper. Signing into `heygen` separately does not configure this path. The server decides subscription eligibility, free allowances and charges; an explicit API key uses API billing. **media-use requires heygen >= v0.3.0 uniformly.** Verify setup with:\n\n```bash\nnpx hyperframes media-use resolve --doctor\n```\n\n## Host HeyGen access (no CLI sign-in)\n\nA host app can give media-use HeyGen access of its own by setting\n`HEYGEN_API_BASE` (its gateway), `HEYGEN_API_KEY` (the token that gateway\naccepts) and, for a loopback gateway, `HEYGEN_ALLOW_HTTP=1`. The gateway adds\nthe host's key, so it never enters the agent's environment, and every\ncall is charged to that key's API credits. The `heygen` CLI honours the same\nvariables, so `resolve` (bgm/sfx/image/icon/voice/avatar-video) and the audio\nengine's TTS all go through the host. With host access, skip CLI install and\nsign-in, prefer the host's own HeyGen tools where it has them, never fall back\nto a local or third-party generator on your own, and relay a refused call's\nmessage (for example \"add a key in Settings > Account\") as written.\n\n## Providers\n\nHyperFrames selects the credential for its HeyGen media helpers. Install\n`heygen` and sign in with `hyperframes auth login` before resolving\nbgm/sfx/image/icon/voice/avatar-video; music and sound effects from\na host app's own tools need none of it. Local tools are opt-in\nalternatives where they exist: mflux for image, Kokoro for voice, Parakeet for\ntranscription, and LTX for local video generation. `resolve` spec-checks\nAVAILABLE RAM for those local ladders inside the CLI (the image tiers are listed\nin `references/operations.md`).\n\n| Type | Provider / path |\n| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| bgm | heygen catalog HyperFrames-authenticated path; a host app's own music tools come first |\n| sfx | Openverse (CC0 / CC BY, no account), bundled library offline; a host app's own sound tools come first |\n| image | heygen search HyperFrames-authenticated path; optional local mflux; codex `image_gen` upsell |\n| voice | heygen tts HyperFrames-authenticated path; optional local **Kokoro** (free, on-device) |\n| icon | heygen asset search HyperFrames-authenticated path |\n| logo | theSVG (thesvg.org), then GitHub org avatar, then domain favicon (all free) |\n| grade/lut | local core-preset map, params/CDN look index, deterministic `buildCube` fallback |\n| video | heygen avatar video HyperFrames-authenticated path (sign-in nudge on auth failure); optional local LTX (`videogen` ladder). Image-to-video / photo-avatar / dub stay manual `heygen` recipes |\n\nLocal Kokoro (voice), mflux (image), and LTX (video) run on-device (free,\nprivate, offline once cached). The `codex` CLI remains the ChatGPT-sub image\nupsell. Paid calls follow the Credits rule in `SKILL.md`: no prices unasked,\nand a question only when a step won't fit.\n\nTo force a specific generator (e.g. a user says \"make this image with codex\"),\npass `--provider codex`: it pins resolution to that provider and skips the\ndefault provider. See `references/operations.md` for the RAM ladders and\nprovider recipes.\n\n`--local-only` skips every network provider, including HeyGen,\nleaving the project + global cache and any installed local provider. For\nHeyGen-only types, that means no fresh resolve.\n\n## CLI tools used (what to run, and how to enable each)\n\n`resolve` auto-cascades; each provider shells one CLI. HeyGen is the\nHyperFrames-authenticated path for bgm/image/icon catalog search, TTS (voice), and avatar\nvideo, so those capabilities need `heygen` installed and a HyperFrames login. Local\ntools are OPT-IN alternatives where they exist; install one to unlock its free,\nprivate, on-device path instead of or ahead of HeyGen for that type. Only\n`ffmpeg`/`ffprobe` are strictly required for the tool to run at all.\n\n| Tool | Serves | Install |\n| ------------------ | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `ffmpeg`/`ffprobe` | adopt probing, smart-grade signalstats, cut, duck bake, loudnorm | system package (`brew install ffmpeg`) |\n| `heygen` | catalog (bgm/image/icon) + TTS (voice) + avatar video — the HyperFrames-authenticated path | install through [verified HeyGen release instructions](https://developers.heygen.com/cli), then `npx hyperframes auth login` (helper needs >= v0.3.0) |\n| `mflux-generate` | local image gen (FLUX), best-for-RAM | `uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6` |\n| `codex` | image gen upsell (ChatGPT sub) | Codex CLI, logged in via ChatGPT (owns its own auth) |\n| `parakeet-mlx` | local transcription (default ASR, best) on Apple Silicon | `uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx` |\n| `ltx-2-mlx` | local video gen | `git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras` |\n| `npx hyperframes` | Kokoro TTS (voice), Parakeet or whisper.cpp (transcribe), remove-background | via the hyperframes CLI; Kokoro needs Python 3.10+ with `pip install kokoro-onnx soundfile`; Parakeet on macOS, Windows and glibc 2.32+ Linux: `npx hyperframes models install parakeet`; whisper.cpp is built on first use (Homebrew on macOS, else git+cmake) |\n\nThe RAM-graded local-model shortlist + exact per-tier install/invoke lives in\nthe CLI's bundled media-use engine, not in the standalone skill. Without a tool on PATH, its provider\nprints a one-line diagnostic to stderr and resolve falls through where another\nprovider exists (e.g. no `mflux` -> codex image upsell; no `parakeet-mlx` -> whisper.cpp).\n\n`heygen asset search` is a pre-launch command hidden from `heygen --help`, but it\nruns; providers tag requests with the allowlisted `X-HeyGen-Client-Source` header\n(v0.3.0+).\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":9329,"content_sha256":"4aa68405654ad2215f5612bd036a9e14c37133e3c433b5f532dfcd5d57674096"},{"filename":"references/telemetry-dashboard.md","content":"# media-use usage dashboard\n\nReproducible definition of the media-use usage dashboard. The dashboard answers\n\"how much is media-use used, for what, is reuse working, and what can't it\nsatisfy\" from the telemetry `scripts/lib/telemetry.mjs` already emits. Build it\nin an authorized HyperFrames analytics project; this doc is the source of truth\nso it can be recreated. Local complement: `resolve --stats` (same questions,\nfrom `.media/` + `~/.media`, no dashboard access needed).\n\n## Identity (see `scripts/lib/telemetry.mjs`)\n\nEvents attribute to the **same person as the hyperframes CLI and studio**\n— the shared install id in `~/.hyperframes/config.json` (`anonymousId`), stitched\nto the HeyGen account (`$identify`, `distinct_id` = email/username) on sign-in.\nNot fully anonymous by design; pseudonymous before sign-in, account-linked after.\n`$ip:null`. Opt-out: `HYPERFRAMES_NO_TELEMETRY=1` / `DO_NOT_TRACK=1` (also CI, dev).\n\n## Event catalog (verified present in-project)\n\nEvery event carries `surface: \"media-use\"`. Event **properties are coarse** —\nnever intent text, file names, or paths.\n\n| Event | Fires on | Key properties |\n| ---------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------- |\n| `media_use_resolve` | a resolve that produced/returned an asset | `type`, `source`, `provider`, `via`, `local_only`, `provider_override` |\n| `media_use_resolve_miss` | a resolve that found nothing | `type`, `local_only`, `provider_override` (no intent) |\n| `media_use_candidates` | `--candidates` / `--dry-run` listing | `type`, counts |\n| `media_use_doctor_run` | `--doctor` | `ok`, `checks_failed`, `failed[]` |\n| `media_use_compare` | `grade-compare` / `compare` | `command`, `cells`, `truncated`, `total`, `render_ready_timed_out` |\n| `media_use_transcribe` · `media_use_duck` · `media_use_transcript_cut` | audio-engine ops | op-specific |\n\n## Dashboard tiles\n\n1. **Invocation volume** — `query-trends`, count of `media_use_resolve` over time (daily). \"How much.\"\n2. **By media type** — `media_use_resolve` broken down by `type` (bgm/sfx/image/icon/logo/voice/grade/lut). \"For what.\"\n3. **Resolve hit-rate** — trends formula: `A / (A + B)` where A = `media_use_resolve`, B = `media_use_resolve_miss`. \"Is the catalog covering needs.\"\n4. **Provider mix** — `media_use_resolve` broken down by `provider`; a second tile by `via` (`url` / `params-fallback` / `params`) to catch CDN→params LUT downgrades.\n5. **Top misses** — `media_use_resolve_miss` broken down by `type` (the tuning signal — pair with local `resolve --stats`, which also shows the missed _intents_ that telemetry deliberately omits).\n6. **Doctor health** — `media_use_doctor_run` broken down by `failed[]` (which dependency check fails most) + `checks_failed` distribution.\n7. **Compare cost** — `media_use_compare` by `command`, plus `truncated` / `render_ready_timed_out` rates (observe before lifting the 16-cell cap).\n8. **Adoption (optional)** — if the `first_run` property ships (plan U5), segment `media_use_resolve` first-run vs repeat.\n\n## Recreate in an analytics dashboard\n\nFor each tile, confirm the event/property schema, build its trend or breakdown,\nthen add it to a dashboard. Keep names prefixed `media-use:` so the dashboard is\ngreppable. Cross-surface note: because identity is shared with CLI/studio, you\ncan also break these down by the same person across `cli_command*` and `studio:*`\nevents.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4200,"content_sha256":"bdc30ad1ff84ebe7f5ca835acb9f47b33717e041ea79b41c6f0db489b86094a7"},{"filename":"scripts/audio-duck.mjs","content":"#!/usr/bin/env node\n\nimport { readFileSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport { parseArgs } from \"node:util\";\nimport { duckKeyframes, duckLane, speechSpans } from \"./lib/duck.mjs\";\nimport { track } from \"./lib/telemetry.mjs\";\n\nconst { values: args } = parseArgs({\n options: {\n meta: { type: \"string\" },\n target: { type: \"string\" },\n duck: { type: \"string\", default: \"0.25\" },\n attack: { type: \"string\", default: \"0.15\" },\n release: { type: \"string\", default: \"0.4\" },\n \"merge-gap\": { type: \"string\", default: \"0.6\" },\n sequential: { type: \"boolean\", default: false },\n gap: { type: \"string\", default: \"0\" },\n offsets: { type: \"string\" },\n composition: { type: \"string\" },\n json: { type: \"boolean\", default: false },\n help: { type: \"boolean\", short: \"h\", default: false },\n },\n strict: true,\n});\n\nif (args.help) {\n console.log(`media-use audio-duck — generate a volume ducking lane (data-automation)\n\nUsage:\n node audio-duck.mjs --meta audio_meta.json --target \"#bgm\"\n\nOptions:\n --meta audio_meta.json or JSON word transcript\n --target GSAP selector for the background audio element\n --duck Duck multiplier (default: 0.25)\n --attack Duck-in duration seconds (default: 0.15)\n --release Restore duration seconds (default: 0.4)\n --merge-gap Bridge speech gaps smaller than this many seconds (default: 0.6)\n --sequential Place multi-line meta back to back at composition time\n --gap Extra seconds between sequential lines (default: 0)\n --offsets Explicit placement, \"l1=0,l2=3.4\" (voice id = start seconds)\n --composition Read target data-volume and data-start from this HTML file\n --json Output { spans, keyframes, lane }\n --help, -h Show this help`);\n process.exit(0);\n}\n\ntry {\n run();\n await track(\"media_use_duck\", { sequential: !!args.sequential });\n} catch (err) {\n if (args.json) console.log(JSON.stringify({ ok: false, error: err.message }));\n else console.error(`error: ${err.message}`);\n process.exit(1);\n}\n\nfunction run() {\n if (!args.meta || !args.target) throw new Error(\"--meta and --target are required\");\n const meta = JSON.parse(readFileSync(resolve(args.meta), \"utf8\"));\n const target = args.target;\n const { baseVolume, clipStart } = readTargetAttrs(args.composition, target);\n const offsets = args.offsets\n ? Object.fromEntries(\n args.offsets.split(\",\").map((pair) => {\n const [id, t] = pair.split(\"=\");\n return [id.trim(), Number(t)];\n }),\n )\n : undefined;\n const spans = speechSpans(meta, {\n mergeGap: Number(args[\"merge-gap\"]),\n sequential: args.sequential,\n gap: Number(args.gap),\n offsets,\n });\n const keyframes = duckKeyframes(spans, {\n duck: Number(args.duck),\n attack: Number(args.attack),\n release: Number(args.release),\n baseVolume,\n });\n\n const lane = duckLane(keyframes, { clipStart, baseVolume });\n\n if (args.json) {\n console.log(JSON.stringify({ spans, keyframes, lane }));\n return;\n }\n\n console.log(`\u003c!-- auto-duck: ${target} under narration; add to its \u003caudio> element -->`);\n console.log(`data-automation='${JSON.stringify(lane)}'`);\n}\n\nfunction readTargetAttrs(composition, target) {\n if (!composition || !target.startsWith(\"#\")) return { baseVolume: 1, clipStart: 0 };\n const id = target.slice(1);\n const html = readFileSync(resolve(composition), \"utf8\");\n // ponytail: regex is enough here because this only reads one attribute from\n // one user-authored composition element, not arbitrary HTML.\n const tag = html.match(new RegExp(`\u003c[^>]*\\\\bid=[\"']${escapeRegExp(id)}[\"'][^>]*>`, \"i\"))?.[0];\n const attr = (name) => Number(tag?.match(new RegExp(`\\\\b${name}=[\"']([^\"']+)[\"']`, \"i\"))?.[1]);\n const volume = attr(\"data-volume\");\n const start = attr(\"data-start\");\n return {\n baseVolume: Number.isFinite(volume) ? volume : 1,\n clipStart: Number.isFinite(start) ? start : 0,\n };\n}\n\nfunction escapeRegExp(value) {\n return value.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\{head-tags}\");\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":4069,"content_sha256":"6beac3c1c6c0e0375e67a04c184406ced3740cc832bb3ba9a09c796bbe16d40e"},{"filename":"scripts/compatibility.test.mjs","content":"import { cpSync, mkdtempSync, rmSync } from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { execFileSync } from \"node:child_process\";\nimport test from \"node:test\";\n\nprocess.env.HYPERFRAMES_MEDIA_HOME = mkdtempSync(join(tmpdir(), \"media-use-compat-home-\"));\n\nfunction run(scriptsDir, script, args) {\n return execFileSync(process.execPath, [join(scriptsDir, script), ...args], {\n encoding: \"utf8\",\n stdio: [\"ignore\", \"pipe\", \"pipe\"],\n });\n}\n\ntest(\"published memory scripts run without reaching outside the skill\", () => {\n const scratchDir = mkdtempSync(join(tmpdir(), \"media-use-compat-\"));\n const skillDir = join(scratchDir, \"media-use\");\n cpSync(new URL(\"..\", import.meta.url), skillDir, { recursive: true });\n const scriptsDir = join(skillDir, \"scripts\");\n const projectDir = join(scratchDir, \"project\");\n try {\n run(scriptsDir, \"prefs.mjs\", [\"get\", \"--hyperframes\", projectDir, \"--json\"]);\n run(scriptsDir, \"recipe.mjs\", [\"list\", \"--hyperframes\", projectDir, \"--json\"]);\n run(scriptsDir, \"transcribe.mjs\", [\"--help\"]);\n } finally {\n rmSync(scratchDir, { recursive: true, force: true });\n }\n});\n\ntest(\"published audio helpers import without the CLI package tree\", () => {\n const root = mkdtempSync(join(tmpdir(), \"media-use-audio-\"));\n const skill = join(root, \"media-use\");\n try {\n cpSync(new URL(\"..\", import.meta.url), skill, { recursive: true });\n for (const helper of [\"heygen.mjs\", \"tts.mjs\"])\n run(join(skill, \"audio/scripts/lib\"), helper, []);\n } finally {\n rmSync(root, { recursive: true, force: true });\n }\n});\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":1610,"content_sha256":"3263a2e82b06560d2c0ea9f7e41b3fe46bec624b70c539ccb121b880dae2250e"},{"filename":"scripts/dither.mjs","content":"#!/usr/bin/env node\n\nimport { execFileSync, spawn } from \"node:child_process\";\nimport { once } from \"node:events\";\nimport { existsSync, mkdirSync, renameSync, rmSync } from \"node:fs\";\nimport { dirname, extname, resolve } from \"node:path\";\nimport { text } from \"node:stream/consumers\";\nimport { parseArgs } from \"node:util\";\nimport {\n ERROR_DIFFUSION_ALGORITHMS,\n applyErrorDiffusionRgba,\n errorDiffusionBufferLength,\n} from \"./lib/error-diffusion.mjs\";\n\nconst IMAGE_EXTENSIONS = new Set([\".png\", \".jpg\", \".jpeg\", \".webp\", \".bmp\", \".tif\", \".tiff\"]);\nconst OUTPUT_IMAGE_EXTENSIONS = new Set([\".png\", \".jpg\", \".jpeg\", \".webp\"]);\n\nconst { values: args } = parseArgs({\n options: {\n input: { type: \"string\", short: \"i\" },\n out: { type: \"string\", short: \"o\" },\n algorithm: { type: \"string\", short: \"a\", default: \"floyd-steinberg\" },\n palette: { type: \"string\", default: \"#000000,#ffffff\" },\n \"point-size\": { type: \"string\", default: \"3\" },\n brightness: { type: \"string\", default: \"1\" },\n contrast: { type: \"string\", default: \"1.2\" },\n detail: { type: \"string\", default: \"1\" },\n json: { type: \"boolean\", default: false },\n help: { type: \"boolean\", short: \"h\", default: false },\n },\n strict: true,\n});\n\nif (args.help) {\n console.log(`media-use dither — exact cached error-diffusion for image or MP4 media\n\nUsage:\n node dither.mjs --input in.mp4 --out out.mp4 [options]\n\nOptions:\n --algorithm, -a ${Object.keys(ERROR_DIFFUSION_ALGORITHMS).join(\" | \")}\n --palette 2-6 authored-order #rrggbb colors, comma-separated\n --point-size Block size in pixels, 1-20 (default: 3)\n --brightness 0.5-2 (default: 1)\n --contrast 0.5-2 (default: 1.2)\n --detail Diffused-error strength, 0.1-1 (default: 1)\n --json Output JSON status\n --help, -h Show this help\n\nVideo output uses the source average frame rate as CFR; VFR cadence is normalized.\n\nAfter processing, register the output with:\n node resolve.mjs --from \u003coutput> --type image|video`);\n process.exit(0);\n}\n\ntry {\n const result = await run();\n if (args.json) console.log(JSON.stringify({ ok: true, ...result }));\n else {\n console.log(`dithered ${result.input} -> ${result.out} (${result.algorithm})`);\n console.log(`next: resolve --from ${result.out} --type ${result.type}`);\n }\n} catch (error) {\n const message = error instanceof Error ? error.message : String(error);\n if (args.json) console.log(JSON.stringify({ ok: false, error: message }));\n else console.error(`error: ${message}`);\n process.exit(1);\n}\n\nasync function run() {\n if (!args.input || !args.out) throw new Error(\"--input and --out are required\");\n const inputPath = resolve(args.input);\n const outPath = resolve(args.out);\n if (!existsSync(inputPath)) throw new Error(`input file not found: ${inputPath}`);\n if (inputPath === outPath) throw new Error(\"--out must differ from --input\");\n\n const metadata = probe(inputPath);\n if (metadata.colorTransfer === \"smpte2084\" || metadata.colorTransfer === \"arib-std-b67\") {\n throw new Error(\n `HDR ${metadata.colorTransfer} input is not supported by the 8-bit SDR dither processor; tone-map to Rec.709 first`,\n );\n }\n const options = {\n algorithm: args.algorithm,\n palette: args.palette.split(\",\").map((color) => color.trim()),\n pointSize: Number(args[\"point-size\"]),\n brightness: Number(args.brightness),\n contrast: Number(args.contrast),\n detail: Number(args.detail),\n };\n // Validate before starting FFmpeg or creating an output file.\n applyErrorDiffusionRgba(new Uint8ClampedArray(4), 1, 1, options, new Float32Array(3));\n\n mkdirSync(dirname(outPath), { recursive: true });\n const inputIsImage = IMAGE_EXTENSIONS.has(extname(inputPath).toLowerCase());\n if (inputIsImage) {\n if (!OUTPUT_IMAGE_EXTENSIONS.has(extname(outPath).toLowerCase())) {\n throw new Error(\"image output must use .png, .jpg, .jpeg, or .webp\");\n }\n processImage(inputPath, outPath, metadata, options);\n } else {\n if (extname(outPath).toLowerCase() !== \".mp4\") throw new Error(\"video output must use .mp4\");\n await processVideo(inputPath, outPath, metadata, options);\n }\n\n return {\n input: inputPath,\n out: outPath,\n type: inputIsImage ? \"image\" : \"video\",\n algorithm: options.algorithm,\n palette: options.palette,\n point_size: options.pointSize,\n brightness: options.brightness,\n contrast: options.contrast,\n detail: options.detail,\n };\n}\n\nfunction probe(filePath) {\n const raw = execFileSync(\n \"ffprobe\",\n [\"-v\", \"error\", \"-print_format\", \"json\", \"-show_streams\", \"-show_format\", \"--\", filePath],\n { encoding: \"utf8\", timeout: 10_000 },\n );\n const parsed = JSON.parse(raw);\n const video = parsed.streams?.find((stream) => stream.codec_type === \"video\");\n if (!video?.width || !video?.height)\n throw new Error(`no readable video/image stream: ${filePath}`);\n const fps = usableFrameRate(video.avg_frame_rate) ?? usableFrameRate(video.r_frame_rate) ?? \"30\";\n return {\n width: video.width,\n height: video.height,\n fps,\n colorTransfer: video.color_transfer || \"\",\n };\n}\n\nfunction processImage(inputPath, outPath, metadata, options) {\n const frameBytes = metadata.width * metadata.height * 4;\n const rgba = execFileSync(\n \"ffmpeg\",\n [\n \"-hide_banner\",\n \"-loglevel\",\n \"error\",\n \"-nostdin\",\n \"-i\",\n inputPath,\n \"-frames:v\",\n \"1\",\n \"-f\",\n \"rawvideo\",\n \"-pix_fmt\",\n \"rgba\",\n \"-\",\n ],\n { maxBuffer: frameBytes + 1024 },\n );\n if (rgba.length !== frameBytes)\n throw new Error(`decoded ${rgba.length} bytes; expected ${frameBytes}`);\n applyErrorDiffusionRgba(rgba, metadata.width, metadata.height, options);\n\n const temporary = temporaryOutput(outPath);\n try {\n execFileSync(\n \"ffmpeg\",\n [\n \"-y\",\n \"-hide_banner\",\n \"-loglevel\",\n \"error\",\n \"-f\",\n \"rawvideo\",\n \"-pix_fmt\",\n \"rgba\",\n \"-s:v\",\n `${metadata.width}x${metadata.height}`,\n \"-i\",\n \"-\",\n \"-frames:v\",\n \"1\",\n temporary,\n ],\n { input: rgba, maxBuffer: frameBytes + 1024 },\n );\n renameSync(temporary, outPath);\n } finally {\n rmSync(temporary, { force: true });\n }\n}\n\nasync function processVideo(inputPath, outPath, metadata, options) {\n const temporary = temporaryOutput(outPath);\n const frameBytes = metadata.width * metadata.height * 4;\n const keyframeInterval = String(Math.max(1, Math.round(frameRateNumber(metadata.fps))));\n const errors = new Float32Array(\n errorDiffusionBufferLength(metadata.width, metadata.height, options.pointSize),\n );\n const decoder = spawn(\"ffmpeg\", [\n \"-hide_banner\",\n \"-loglevel\",\n \"error\",\n \"-nostdin\",\n \"-i\",\n inputPath,\n \"-map\",\n \"0:v:0\",\n \"-f\",\n \"rawvideo\",\n \"-pix_fmt\",\n \"rgba\",\n \"-\",\n ]);\n const encoder = spawn(\"ffmpeg\", [\n \"-y\",\n \"-hide_banner\",\n \"-loglevel\",\n \"error\",\n \"-f\",\n \"rawvideo\",\n \"-pix_fmt\",\n \"rgba\",\n \"-s:v\",\n `${metadata.width}x${metadata.height}`,\n \"-r\",\n metadata.fps,\n \"-i\",\n \"-\",\n \"-i\",\n inputPath,\n \"-map\",\n \"0:v:0\",\n \"-map\",\n \"1:a?\",\n \"-map_metadata\",\n \"1\",\n \"-c:v\",\n \"libx264\",\n \"-preset\",\n \"veryfast\",\n \"-crf\",\n \"18\",\n \"-g\",\n keyframeInterval,\n \"-keyint_min\",\n keyframeInterval,\n \"-sc_threshold\",\n \"0\",\n \"-pix_fmt\",\n \"yuv420p\",\n \"-x264-params\",\n \"colorprim=bt709:transfer=bt709:colormatrix=bt709\",\n \"-color_primaries:v\",\n \"bt709\",\n \"-color_trc:v\",\n \"bt709\",\n \"-colorspace:v\",\n \"bt709\",\n \"-color_range\",\n \"tv\",\n \"-c:a\",\n \"aac\",\n \"-b:a\",\n \"192k\",\n \"-shortest\",\n \"-movflags\",\n \"+faststart\",\n temporary,\n ]);\n const decoderError = text(decoder.stderr);\n const encoderError = text(encoder.stderr);\n const decoderDone = once(decoder, \"close\").then(([code]) => code ?? 1);\n const encoderDone = once(encoder, \"close\").then(([code]) => code ?? 1);\n\n try {\n const frame = Buffer.allocUnsafe(frameBytes);\n let frameOffset = 0;\n for await (const chunk of decoder.stdout) {\n let chunkOffset = 0;\n while (chunkOffset \u003c chunk.length) {\n const length = Math.min(frameBytes - frameOffset, chunk.length - chunkOffset);\n chunk.copy(frame, frameOffset, chunkOffset, chunkOffset + length);\n chunkOffset += length;\n frameOffset += length;\n if (frameOffset !== frameBytes) continue;\n applyErrorDiffusionRgba(frame, metadata.width, metadata.height, options, errors);\n await writeFrame(encoder.stdin, frame);\n frameOffset = 0;\n }\n }\n if (frameOffset)\n throw new Error(`decoder returned a partial RGBA frame (${frameOffset} bytes)`);\n encoder.stdin.end();\n const [decoderCode, encoderCode] = await Promise.all([decoderDone, encoderDone]);\n if (decoderCode !== 0) throw new Error(`FFmpeg decode failed: ${(await decoderError).trim()}`);\n if (encoderCode !== 0) throw new Error(`FFmpeg encode failed: ${(await encoderError).trim()}`);\n renameSync(temporary, outPath);\n } catch (error) {\n decoder.kill(\"SIGKILL\");\n encoder.kill(\"SIGKILL\");\n throw error;\n } finally {\n rmSync(temporary, { force: true });\n }\n}\n\nfunction writeFrame(stream, frame) {\n return new Promise((resolveWrite, reject) => {\n stream.write(frame, (error) => (error ? reject(error) : resolveWrite()));\n });\n}\n\nfunction usableFrameRate(value) {\n if (!value || value === \"0/0\") return null;\n const number = frameRateNumber(value);\n return Number.isFinite(number) && number > 0 ? value : null;\n}\n\nfunction frameRateNumber(value) {\n const [numerator, denominator = \"1\"] = value.split(\"/\");\n return Number(numerator) / Number(denominator);\n}\n\nfunction temporaryOutput(outPath) {\n const extension = extname(outPath);\n return `${outPath.slice(0, -extension.length)}.part-${process.pid}${extension}`;\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":9969,"content_sha256":"8e9f437526f39f417f6793912ddeef71094ddb5a5b8d4893c5339086bc39547f"},{"filename":"scripts/dither.test.mjs","content":"import assert from \"node:assert/strict\";\nimport { execFileSync, spawnSync } from \"node:child_process\";\nimport { mkdtempSync, rmSync } from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport test from \"node:test\";\nimport { fileURLToPath } from \"node:url\";\n\nconst SCRIPT = fileURLToPath(new URL(\"./dither.mjs\", import.meta.url));\nconst HAS_FFMPEG =\n spawnSync(\"ffmpeg\", [\"-version\"], { stdio: \"ignore\" }).status === 0 &&\n spawnSync(\"ffprobe\", [\"-version\"], { stdio: \"ignore\" }).status === 0;\n\nfunction fixture() {\n const dir = mkdtempSync(join(tmpdir(), \"media-use-dither-\"));\n return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };\n}\n\nfunction ffmpeg(args) {\n execFileSync(\"ffmpeg\", [\"-y\", \"-hide_banner\", \"-loglevel\", \"error\", ...args]);\n}\n\nfunction run(args) {\n return spawnSync(process.execPath, [SCRIPT, ...args, \"--json\"], { encoding: \"utf8\" });\n}\n\ntest(\"processes an image into the requested ordered palette\", { skip: !HAS_FFMPEG }, (t) => {\n const { dir, cleanup } = fixture();\n t.after(cleanup);\n const input = join(dir, \"source.png\");\n const output = join(dir, \"dithered.png\");\n ffmpeg([\"-f\", \"lavfi\", \"-i\", \"testsrc2=size=16x12:rate=1\", \"-frames:v\", \"1\", input]);\n\n const result = run([\n \"--input\",\n input,\n \"--out\",\n output,\n \"--algorithm\",\n \"floyd-steinberg\",\n \"--palette\",\n \"#000000,#ffffff\",\n \"--point-size\",\n \"3\",\n ]);\n assert.equal(result.status, 0, result.stderr || result.stdout);\n assert.equal(JSON.parse(result.stdout).type, \"image\");\n\n const rgb = execFileSync(\"ffmpeg\", [\n \"-hide_banner\",\n \"-loglevel\",\n \"error\",\n \"-i\",\n output,\n \"-frames:v\",\n \"1\",\n \"-f\",\n \"rawvideo\",\n \"-pix_fmt\",\n \"rgb24\",\n \"-\",\n ]);\n for (let index = 0; index \u003c rgb.length; index += 3) {\n const value = rgb[index];\n assert.ok(value === 0 || value === 255);\n assert.equal(rgb[index + 1], value);\n assert.equal(rgb[index + 2], value);\n }\n});\n\ntest(\"processes moving MP4 frames, audio, and BT.709 metadata\", { skip: !HAS_FFMPEG }, (t) => {\n const { dir, cleanup } = fixture();\n t.after(cleanup);\n const input = join(dir, \"source.mp4\");\n const output = join(dir, \"dithered.mp4\");\n ffmpeg([\n \"-f\",\n \"lavfi\",\n \"-i\",\n \"testsrc2=size=16x12:rate=3:duration=2\",\n \"-f\",\n \"lavfi\",\n \"-i\",\n \"sine=frequency=440:duration=3\",\n \"-c:v\",\n \"libx264\",\n \"-pix_fmt\",\n \"yuv420p\",\n \"-c:a\",\n \"aac\",\n input,\n ]);\n\n const result = run([\n \"--input\",\n input,\n \"--out\",\n output,\n \"--algorithm\",\n \"atkinson\",\n \"--palette\",\n \"#0f380f,#306230,#8bac0f,#9bbc0f\",\n ]);\n assert.equal(result.status, 0, result.stderr || result.stdout);\n const probe = JSON.parse(\n execFileSync(\n \"ffprobe\",\n [\"-v\", \"error\", \"-print_format\", \"json\", \"-show_streams\", \"-show_format\", \"--\", output],\n {\n encoding: \"utf8\",\n },\n ),\n );\n const video = probe.streams.find((stream) => stream.codec_type === \"video\");\n const audio = probe.streams.find((stream) => stream.codec_type === \"audio\");\n assert.equal(video.width, 16);\n assert.equal(video.height, 12);\n assert.equal(video.nb_frames, \"6\");\n assert.equal(video.color_space, \"bt709\");\n assert.equal(video.color_transfer, \"bt709\");\n assert.equal(video.color_primaries, \"bt709\");\n assert.equal(video.color_range, \"tv\");\n assert.equal(audio.codec_name, \"aac\");\n assert.ok(Number(probe.format.duration) \u003c 2.5, \"audio must not outlive processed video\");\n const keyframes = execFileSync(\n \"ffprobe\",\n [\n \"-v\",\n \"error\",\n \"-select_streams\",\n \"v:0\",\n \"-skip_frame\",\n \"nokey\",\n \"-show_entries\",\n \"frame=best_effort_timestamp_time\",\n \"-of\",\n \"csv=p=0\",\n \"--\",\n output,\n ],\n { encoding: \"utf8\" },\n )\n .trim()\n .split(/\\s+/)\n .map((value) => Number.parseFloat(value));\n assert.deepEqual(keyframes, [0, 1]);\n});\n\ntest(\"rejects tagged PQ or HLG instead of silently producing SDR\", { skip: !HAS_FFMPEG }, (t) => {\n const { dir, cleanup } = fixture();\n t.after(cleanup);\n const input = join(dir, \"hlg.mp4\");\n ffmpeg([\n \"-f\",\n \"lavfi\",\n \"-i\",\n \"color=c=white:size=16x12:rate=1:duration=1\",\n \"-c:v\",\n \"libx264\",\n \"-pix_fmt\",\n \"yuv420p10le\",\n \"-x264-params\",\n \"colorprim=bt2020:transfer=arib-std-b67:colormatrix=bt2020nc\",\n \"-color_primaries:v\",\n \"bt2020\",\n \"-color_trc:v\",\n \"arib-std-b67\",\n \"-colorspace:v\",\n \"bt2020nc\",\n input,\n ]);\n\n const result = run([\"--input\", input, \"--out\", join(dir, \"wrong.mp4\")]);\n assert.equal(result.status, 1);\n assert.match(JSON.parse(result.stdout).error, /HDR arib-std-b67 input is not supported/);\n});\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":4723,"content_sha256":"c22c3a0ae41647ac3f733b489a6bc6043fd294155d00954be5d901b3cff7d216"},{"filename":"scripts/eval.mjs","content":"#!/usr/bin/env node\n\n/**\n * media-use eval — compare baseline (no media-use) vs. with media-use\n * on real registry blocks. Produces an HTML report.\n */\n\nimport {\n mkdtempSync,\n cpSync,\n rmSync,\n readFileSync,\n readdirSync,\n existsSync,\n writeFileSync,\n} from \"node:fs\";\nimport { join, basename, resolve, dirname } from \"node:path\";\nimport { execFileSync } from \"node:child_process\";\nimport { tmpdir } from \"node:os\";\nimport { fileURLToPath } from \"node:url\";\n\nconst SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));\nconst REPO_ROOT = resolve(SCRIPT_DIR, \"..\", \"..\", \"..\");\nconst RESOLVE_SCRIPT = join(SCRIPT_DIR, \"resolve.mjs\");\n\nconst TEST_BLOCKS = [\n \"registry/blocks/nyc-paris-flight\",\n \"registry/blocks/macos-tahoe-liquid-glass\",\n \"registry/blocks/blue-sweater-intro-video\",\n \"registry/blocks/vpn-youtube-spot\",\n \"registry/blocks/apple-money-count\",\n \"registry/blocks/liquid-glass-notification\",\n \"registry/blocks/instagram-follow\",\n];\n\n// Run resolve.mjs with args as a literal argv array (no shell), so values\n// interpolated from manifest metadata (--intent prompt, --type) can't inject\n// shell. Mirrors the execFileSync fix in probe.mjs / heygen-search.mjs.\nfunction run(args, opts = {}) {\n try {\n return {\n ok: true,\n output: execFileSync(process.execPath, [RESOLVE_SCRIPT, ...args], {\n encoding: \"utf8\",\n timeout: 15000,\n stdio: \"pipe\",\n ...opts,\n }).trim(),\n };\n } catch (err) {\n return { ok: false, output: (err.stdout || \"\") + (err.stderr || \"\"), code: err.status };\n }\n}\n\nfunction countAssetFiles(dir) {\n const assetsDir = join(dir, \"assets\");\n if (!existsSync(assetsDir)) return { count: 0, files: [] };\n const files = [];\n function walk(d, base = \"\") {\n for (const e of readdirSync(d, { withFileTypes: true })) {\n const rel = base ? `${base}/${e.name}` : e.name;\n if (e.isDirectory()) walk(join(d, e.name), rel);\n else files.push(rel);\n }\n }\n walk(assetsDir);\n return { count: files.length, files };\n}\n\nfunction evalBlock(blockPath) {\n const fullPath = join(REPO_ROOT, blockPath);\n if (!existsSync(fullPath)) return null;\n\n const name = basename(blockPath);\n const tmp = mkdtempSync(join(tmpdir(), `mu-eval-${name}-`));\n\n try {\n cpSync(fullPath, tmp, { recursive: true });\n\n // baseline: what the agent sees WITHOUT media-use\n const baseline = countAssetFiles(tmp);\n const htmlFiles = readdirSync(tmp).filter((f) => f.endsWith(\".html\"));\n\n // parse compositions for asset references\n const assetRefs = [];\n for (const hf of htmlFiles) {\n const html = readFileSync(join(tmp, hf), \"utf8\");\n const srcMatches = html.matchAll(/src=[\"']([^\"']+?)[\"']/g);\n for (const m of srcMatches) {\n const ref = m[1];\n if (ref.startsWith(\"data:\") || ref.startsWith(\"http\")) continue;\n assetRefs.push({ composition: hf, ref });\n }\n const urlMatches = html.matchAll(/url\$[\"']?([^\"')]+?)[\"']?\$/g);\n for (const m of urlMatches) {\n const ref = m[1];\n if (ref.startsWith(\"data:\") || ref.startsWith(\"http\") || ref.startsWith(\"#\")) continue;\n assetRefs.push({ composition: hf, ref });\n }\n }\n\n // with media-use: run --adopt\n const adoptResult = run([\"--adopt\", \"--project\", tmp, \"--json\"]);\n let adopted = { ok: false, adopted: 0, assets: [] };\n if (adoptResult.ok) {\n try {\n adopted = JSON.parse(adoptResult.output);\n } catch {\n /* */\n }\n }\n\n // read the generated index\n const indexPath = join(tmp, \".media\", \"index.md\");\n const indexContent = existsSync(indexPath)\n ? readFileSync(indexPath, \"utf8\")\n : \"(no index generated)\";\n\n // read manifest for detail\n const manifestPath = join(tmp, \".media\", \"manifest.jsonl\");\n const manifest = existsSync(manifestPath)\n ? readFileSync(manifestPath, \"utf8\")\n .trim()\n .split(\"\\n\")\n .map((l) => {\n try {\n return JSON.parse(l);\n } catch {\n return null;\n }\n })\n .filter(Boolean)\n : [];\n\n // test resolve cache hit: try resolving something that was adopted\n let resolveTest = null;\n if (manifest.length > 0) {\n const first = manifest[0];\n const prompt = first.provenance?.prompt || first.description;\n const r = run([\"--type\", first.type, \"--intent\", prompt, \"--project\", tmp, \"--json\"]);\n if (r.ok) {\n try {\n resolveTest = JSON.parse(r.output);\n } catch {\n /* */\n }\n }\n }\n\n // test resolve miss: try resolving something that doesn't exist\n const missResult = run([\n \"--type\",\n \"bgm\",\n \"--intent\",\n \"nonexistent query xyz\",\n \"--project\",\n tmp,\n \"--json\",\n ]);\n let resolveMiss = null;\n if (!missResult.ok) {\n try {\n resolveMiss = JSON.parse(missResult.output);\n } catch {\n /* */\n }\n }\n\n // coverage: which composition refs are covered by the manifest\n const manifestPaths = new Set(manifest.map((m) => m.path));\n const coverage = assetRefs.map((r) => ({\n ...r,\n covered: manifestPaths.has(r.ref),\n }));\n\n return {\n name,\n baseline: { fileCount: baseline.count, files: baseline.files, htmlCount: htmlFiles.length },\n compositions: htmlFiles,\n assetRefs: coverage,\n adopted: { count: adopted.adopted, assets: adopted.assets || [] },\n index: indexContent,\n manifest,\n resolveTest,\n resolveMiss,\n };\n } finally {\n rmSync(tmp, { recursive: true, force: true });\n }\n}\n\nfunction generateReport(results) {\n const all = results.filter(Boolean);\n const passed = all.filter((r) => r.adopted.count > 0);\n\n const rows = results\n .filter(Boolean)\n .map((r) => {\n const hasMetadata = r.manifest.some((m) => m.duration || m.width);\n const cacheHit = r.resolveTest?._source === \"cached\";\n const missHandled = r.resolveMiss?.ok === false;\n\n return `\u003ctr>\n \u003ctd>\u003cstrong>${r.name}\u003c/strong>\u003c/td>\n \u003ctd>${r.baseline.fileCount} files, ${r.baseline.htmlCount} comp${r.baseline.htmlCount === 1 ? \"\" : \"s\"}\u003c/td>\n \u003ctd>${r.adopted.count} adopted\u003c/td>\n \u003ctd>${hasMetadata ? \"\u003cspan class='pass'>with metadata\u003c/span>\" : \"\u003cspan class='warn'>no metadata\u003c/span>\"}\u003c/td>\n \u003ctd>${cacheHit ? \"\u003cspan class='pass'>cache hit\u003c/span>\" : \"\u003cspan class='warn'>no hit\u003c/span>\"}\u003c/td>\n \u003ctd>${missHandled ? \"\u003cspan class='pass'>handled\u003c/span>\" : \"\u003cspan class='fail'>unexpected\u003c/span>\"}\u003c/td>\n \u003c/tr>`;\n })\n .join(\"\\n\");\n\n const details = results\n .filter(Boolean)\n .filter((r) => r.adopted.count > 0)\n .map((r) => {\n const assetRows = r.manifest\n .map((m) => {\n const dur = m.duration != null ? `${m.duration}s` : \"—\";\n const dims = m.width && m.height ? `${m.width}×${m.height}` : \"—\";\n return `\u003ctr>\u003ctd>${m.id}\u003c/td>\u003ctd>${m.type}\u003c/td>\u003ctd>${dur}\u003c/td>\u003ctd>${dims}\u003c/td>\u003ctd class=\"path\">${m.path}\u003c/td>\u003ctd>${m.description || \"\"}\u003c/td>\u003c/tr>`;\n })\n .join(\"\\n\");\n\n const coveredCount = r.assetRefs.filter((c) => c.covered).length;\n const totalRefs = r.assetRefs.length;\n const coveragePct = totalRefs > 0 ? Math.round((coveredCount / totalRefs) * 100) : 100;\n\n const refRows = r.assetRefs\n .map(\n (c) =>\n `\u003ctr>\u003ctd class=\"path\">${c.composition}\u003c/td>\u003ctd class=\"path\">${c.ref}\u003c/td>\u003ctd>${c.covered ? \"\u003cspan class='pass'>covered\u003c/span>\" : \"\u003cspan class='warn'>not in manifest\u003c/span>\"}\u003c/td>\u003c/tr>`,\n )\n .join(\"\\n\");\n\n return `\u003cdiv class=\"block-detail\">\n \u003ch3>${r.name}\u003c/h3>\n \u003cp style=\"font-size:13px;color:var(--muted)\">${r.compositions.length} composition${r.compositions.length === 1 ? \"\" : \"s\"}: ${r.compositions.join(\", \")}\u003c/p>\n\n \u003cdiv class=\"comparison\">\n \u003cdiv class=\"col\">\n \u003ch4>Baseline (no media-use)\u003c/h4>\n \u003cp>Agent sees: ${r.baseline.fileCount} raw files in assets/\u003cbr>No metadata, no type info, no relationship to compositions.\u003c/p>\n \u003cpre class=\"file-list\">${r.baseline.files.join(\"\\n\") || \"(no assets)\"}\u003c/pre>\n \u003c/div>\n \u003cdiv class=\"col\">\n \u003ch4>With media-use (after --adopt)\u003c/h4>\n \u003cp>Agent reads index.md — structured, typed, with metadata:\u003c/p>\n \u003cpre class=\"index\">${escapeHtml(r.index)}\u003c/pre>\n \u003c/div>\n \u003c/div>\n\n ${\n totalRefs > 0\n ? `\u003ch4>Composition → asset coverage \u003cspan class=\"${coveragePct === 100 ? \"pass\" : \"warn\"}\">${coveragePct}%\u003c/span> (${coveredCount}/${totalRefs} refs)\u003c/h4>\n \u003ctable class=\"manifest\">\n \u003cthead>\u003ctr>\u003cth>composition\u003c/th>\u003cth>asset reference\u003c/th>\u003cth>in manifest?\u003c/th>\u003c/tr>\u003c/thead>\n \u003ctbody>${refRows}\u003c/tbody>\n \u003c/table>`\n : \"\"\n }\n\n \u003ch4>Manifest records\u003c/h4>\n \u003ctable class=\"manifest\">\n \u003cthead>\u003ctr>\u003cth>id\u003c/th>\u003cth>type\u003c/th>\u003cth>dur\u003c/th>\u003cth>dims\u003c/th>\u003cth>path\u003c/th>\u003cth>description\u003c/th>\u003c/tr>\u003c/thead>\n \u003ctbody>${assetRows}\u003c/tbody>\n \u003c/table>\n \u003c/div>`;\n })\n .join(\"\\n\");\n\n return `\u003ctitle>media-use eval report\u003c/title>\n\u003cstyle>\n:root { --bg: #fafaf7; --text: #1b1b18; --muted: #7a756a; --accent: #0d7377; --good: #1a7a3a; --warn: #b45309; --fail: #dc2626; --border: #e8e5df; --surface: #fff; --mono: ui-monospace, 'SF Mono', Menlo, Consolas, monospace; --sans: system-ui, -apple-system, sans-serif; --serif: Georgia, serif }\n* { box-sizing: border-box; margin: 0 } body { background: var(--bg); color: var(--text); font-family: var(--serif); line-height: 1.6; font-size: 15px; padding: 40px 24px }\n.wrap { max-width: 1100px; margin: 0 auto }\nh1 { font-family: var(--sans); font-size: 28px; font-weight: 700; margin-bottom: 8px; letter-spacing: -.02em }\nh2 { font-family: var(--sans); font-size: 20px; font-weight: 650; margin: 32px 0 12px; letter-spacing: -.01em }\nh3 { font-family: var(--sans); font-size: 17px; font-weight: 650; margin: 24px 0 8px }\nh4 { font-family: var(--sans); font-size: 14px; font-weight: 600; margin: 16px 0 6px; color: var(--muted) }\np { margin-bottom: 10px }\n.meta { font-family: var(--mono); font-size: 12px; color: var(--muted); margin-bottom: 24px }\n.summary { display: flex; gap: 16px; margin: 16px 0; flex-wrap: wrap }\n.stat { background: var(--surface); border: 1px solid var(--border); border-radius: 8px; padding: 14px 18px; flex: 1; min-width: 140px }\n.stat .num { font-family: var(--sans); font-size: 28px; font-weight: 700; color: var(--accent) }\n.stat .label { font-family: var(--mono); font-size: 11px; color: var(--muted); text-transform: uppercase; letter-spacing: .1em }\ntable { width: 100%; border-collapse: collapse; font-size: 13px; font-family: var(--sans); margin: 8px 0 }\nth { text-align: left; font-family: var(--mono); font-size: 10px; letter-spacing: .08em; text-transform: uppercase; color: var(--muted); border-bottom: 2px solid var(--border); padding: 6px 8px; font-weight: 700 }\ntd { border-bottom: 1px solid var(--border); padding: 7px 8px; vertical-align: top }\ntd.path { font-family: var(--mono); font-size: 12px; color: var(--muted); max-width: 300px; overflow: hidden; text-overflow: ellipsis }\n.pass { color: var(--good); font-weight: 600 } .warn { color: var(--warn); font-weight: 600 } .fail { color: var(--fail); font-weight: 600 }\n.comparison { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; margin: 12px 0 }\n@media(max-width:700px) { .comparison { grid-template-columns: 1fr } }\n.col { background: var(--surface); border: 1px solid var(--border); border-radius: 8px; padding: 14px 16px }\n.col h4 { margin-top: 0 }\npre { font-family: var(--mono); font-size: 12px; background: #1b1b18; color: #d4d0c8; border-radius: 6px; padding: 12px 14px; overflow-x: auto; margin: 6px 0; line-height: 1.5 }\npre.file-list { background: var(--bg); color: var(--muted); border: 1px solid var(--border) }\npre.index { white-space: pre; }\n.block-detail { border-top: 1px solid var(--border); padding-top: 20px; margin-top: 20px }\n.verdict { margin-top: 24px; padding: 16px 20px; border-radius: 8px; font-family: var(--sans); font-size: 15px }\n.verdict.ship { background: #edfbf0; border: 1px solid #1a7a3a; color: #1a7a3a }\n.verdict.wait { background: #fff3ec; border: 1px solid #d94f04; color: #d94f04 }\n\u003c/style>\n\u003cdiv class=\"wrap\">\n\u003ch1>media-use eval report\u003c/h1>\n\u003cp class=\"meta\">${new Date().toISOString().slice(0, 10)} · ${all.length} blocks evaluated · baseline vs. media-use --adopt\u003c/p>\n\n\u003cdiv class=\"summary\">\n \u003cdiv class=\"stat\">\u003cdiv class=\"num\">${all.length}\u003c/div>\u003cdiv class=\"label\">blocks tested\u003c/div>\u003c/div>\n \u003cdiv class=\"stat\">\u003cdiv class=\"num\">${passed.length}\u003c/div>\u003cdiv class=\"label\">with assets\u003c/div>\u003c/div>\n \u003cdiv class=\"stat\">\u003cdiv class=\"num\">${all.reduce((s, r) => s + r.adopted.count, 0)}\u003c/div>\u003cdiv class=\"label\">assets adopted\u003c/div>\u003c/div>\n \u003cdiv class=\"stat\">\u003cdiv class=\"num\">${all.filter((r) => r.manifest.some((m) => m.duration || m.width)).length}\u003c/div>\u003cdiv class=\"label\">with ffprobe metadata\u003c/div>\u003c/div>\n \u003cdiv class=\"stat\">\u003cdiv class=\"num\">${(() => {\n const refs = all.flatMap((r) => r.assetRefs);\n const covered = refs.filter((c) => c.covered).length;\n return refs.length > 0 ? Math.round((covered / refs.length) * 100) + \"%\" : \"—\";\n })()}\u003c/div>\u003cdiv class=\"label\">composition coverage\u003c/div>\u003c/div>\n\u003c/div>\n\n\u003ch2>Results matrix\u003c/h2>\n\u003ctable>\n \u003cthead>\u003ctr>\u003cth>Block\u003c/th>\u003cth>Baseline\u003c/th>\u003cth>Adopted\u003c/th>\u003cth>Metadata\u003c/th>\u003cth>Cache hit\u003c/th>\u003cth>Miss handling\u003c/th>\u003c/tr>\u003c/thead>\n \u003ctbody>${rows}\u003c/tbody>\n\u003c/table>\n\n\u003ch2>Before / after comparisons\u003c/h2>\n${details}\n\n\u003cdiv class=\"verdict ${passed.length >= 3 ? \"ship\" : \"wait\"}\">\n ${\n passed.length >= 3\n ? `\u003cstrong>Ship it.\u003c/strong> ${passed.length}/${all.length} blocks adopted successfully with metadata. Resolve cache hits work. Miss handling is clean.`\n : `\u003cstrong>Needs work.\u003c/strong> Only ${passed.length} blocks adopted. Check the failures above.`\n }\n\u003c/div>\n\u003c/div>`;\n}\n\nfunction escapeHtml(str) {\n return str.replace(/&/g, \"&\").replace(/\u003c/g, \"<\").replace(/>/g, \">\");\n}\n\nconsole.log(\"media-use eval · running against registry blocks...\\n\");\n\nconst results = [];\nfor (const block of TEST_BLOCKS) {\n const fullPath = join(REPO_ROOT, block);\n if (!existsSync(fullPath)) {\n console.log(` skip ${basename(block)} (not found)`);\n results.push(null);\n continue;\n }\n process.stdout.write(` ${basename(block)}...`);\n const result = evalBlock(block);\n if (result) {\n console.log(\n ` ${result.adopted.count} adopted, ${result.manifest.filter((m) => m.duration || m.width).length} with metadata`,\n );\n } else {\n console.log(\" failed\");\n }\n results.push(result);\n}\n\nconst report = generateReport(results);\nconst outPath = join(SCRIPT_DIR, \"..\", \"eval-report.html\");\nwriteFileSync(outPath, report);\nconsole.log(`\\nReport: ${outPath}`);\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":14891,"content_sha256":"fadf274111a682acbfdff91eca75b977e3821c53026cd058551c538027f21f51"},{"filename":"scripts/lib/config-lock.mjs","content":"// The one lock on ~/.hyperframes/config.json, for the CLI, its auto-update step and media-use. The auto-update step\n// embeds this function's source, so it must use only its arguments and globals.\nexport function withFileLock(lockPath, fs, task) {\n const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;\n const started = Date.now();\n for (;;) {\n let fd;\n try {\n fd = fs.openSync(lockPath, \"wx\");\n } catch (error) {\n if (error.code !== \"EEXIST\") throw error;\n // Never taken over: a lock older than any hold was left by a process that stopped, and a person removes it.\n let leftover = false;\n try {\n leftover = Date.now() - fs.statSync(lockPath).mtimeMs > 5000;\n } catch {}\n if (leftover || Date.now() - started > 10000)\n throw Object.assign(\n new Error(\n `Settings are locked by another hyperframes process. If none is running, delete ${lockPath}`,\n ),\n { code: \"HF_SETTINGS_LOCKED\" },\n );\n Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);\n continue;\n }\n try {\n fs.writeSync(fd, token);\n } catch (error) {\n fs.rmSync(lockPath, { force: true });\n throw error;\n } finally {\n fs.closeSync(fd);\n }\n break;\n }\n try {\n return task();\n } finally {\n // No code removes another's lock, so release needs no check (only a person deleting a live one defeats it).\n try {\n fs.rmSync(lockPath);\n } catch {}\n }\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":1520,"content_sha256":"a9d1679e2039be38cd1756a1011f813ae4be0577c2ff77b9ed411b99b1c94275"},{"filename":"scripts/lib/cutlist.mjs","content":"import { normalizeWords } from \"./words.mjs\";\n\nconst MIN_SEGMENT_SECONDS = 0.2;\nconst SILENCE_PAD_SECONDS = 0.15;\n\nexport function compileCutList(transcript, opts = {}) {\n const words = normalizeWords(transcript);\n if (opts.keep != null && hasRemovalSource(opts)) {\n throw new Error(\"--keep is mutually exclusive with removal options\");\n }\n\n if (opts.keep != null) {\n const duration = durationFrom(words, opts);\n const ranges = parseTimeRanges(opts.keep);\n return finalizeKept(duration != null ? clampRanges(ranges, duration) : ranges);\n }\n\n const duration = durationFrom(words, opts);\n if (!duration) return [];\n\n const removals = [\n ...parseTimeRanges(opts.remove),\n ...wordIndexRanges(words, opts.removeWords),\n ...fillerRanges(words, opts.removeFillers),\n ...silenceRanges(words, opts.cutSilence),\n ];\n const mergedRemovals = mergeRanges(clampRanges(removals, duration));\n return finalizeKept(invertRanges(mergedRemovals, duration));\n}\n\nfunction hasRemovalSource(opts) {\n return (\n opts.remove != null ||\n opts.removeWords != null ||\n opts.removeFillers != null ||\n opts.cutSilence != null\n );\n}\n\nfunction durationFrom(words, opts) {\n const explicit = Number(opts.duration ?? opts.totalDuration);\n if (Number.isFinite(explicit) && explicit > 0) return explicit;\n const last = words.at(-1);\n return last && Number.isFinite(last.end) && last.end > 0 ? last.end : null;\n}\n\nfunction parseTimeRanges(value) {\n if (value == null || value === false || value === \"\") return [];\n if (typeof value === \"string\") {\n return value\n .split(\",\")\n .map((part) => part.trim())\n .filter(Boolean)\n .map(parseRangeString);\n }\n if (!Array.isArray(value)) throw new Error(\"range list must be a string or array\");\n return value.map((range) => {\n if (Array.isArray(range)) return cleanRange(Number(range[0]), Number(range[1]));\n return cleanRange(Number(range?.start), Number(range?.end));\n });\n}\n\nfunction parseRangeString(value) {\n const match = value.match(/^([0-9]*\\.?[0-9]+)\\s*-\\s*([0-9]*\\.?[0-9]+)$/);\n if (!match) throw new Error(`invalid range: ${value}`);\n return cleanRange(Number(match[1]), Number(match[2]));\n}\n\nfunction cleanRange(start, end) {\n if (!Number.isFinite(start) || !Number.isFinite(end)) {\n throw new Error(\"range start/end must be finite numbers\");\n }\n if (end \u003c start) throw new Error(`range end ${end} is before start ${start}`);\n return { start, end };\n}\n\nfunction wordIndexRanges(words, value) {\n if (value == null || value === false || value === \"\") return [];\n const ranges = typeof value === \"string\" ? value.split(\",\") : value;\n if (!Array.isArray(ranges)) throw new Error(\"--remove-words must be a string or array\");\n return ranges\n .map((range) => (typeof range === \"string\" ? range.trim() : range))\n .filter(Boolean)\n .map((range) => {\n const [first, last = first] =\n typeof range === \"string\" ? range.split(\"-\").map((n) => n.trim()) : range;\n const startIndex = Number(first);\n const endIndex = Number(last);\n if (!Number.isInteger(startIndex) || !Number.isInteger(endIndex)) {\n throw new Error(`invalid word range: ${range}`);\n }\n if (startIndex \u003c 0 || endIndex \u003c startIndex || endIndex >= words.length) {\n throw new Error(`word range out of bounds: ${range}`);\n }\n return { start: words[startIndex].start, end: words[endIndex].end };\n });\n}\n\nfunction fillerRanges(words, value) {\n if (value == null || value === false || value === \"\") return [];\n const fillers = Array.isArray(value)\n ? value\n : String(value)\n .split(\",\")\n .map((s) => s.trim());\n const set = new Set(fillers.filter(Boolean).map(bareToken));\n if (set.size === 0) return [];\n // Whisper emits words with attached punctuation and arbitrary case\n // (\"UM,\" / \"Um.\"), so compare bare tokens.\n return words\n .filter((word) => set.has(bareToken(word.text)))\n .map((word) => ({ start: word.start, end: word.end }));\n}\n\nfunction bareToken(text) {\n return String(text)\n .toLowerCase()\n .replace(/^[^\\p{L}\\p{N}]+|[^\\p{L}\\p{N}]+$/gu, \"\");\n}\n\nfunction silenceRanges(words, value) {\n if (value == null || value === false || value === \"\") return [];\n const threshold = Number(value);\n if (!Number.isFinite(threshold) || threshold \u003c= 0) {\n throw new Error(\"--cut-silence must be a positive number\");\n }\n const ranges = [];\n for (let i = 0; i \u003c words.length - 1; i++) {\n const current = words[i];\n const next = words[i + 1];\n const gap = next.start - current.end;\n if (gap \u003c= threshold) continue;\n const start = current.end + SILENCE_PAD_SECONDS;\n const end = next.start - SILENCE_PAD_SECONDS;\n if (end > start) ranges.push({ start, end });\n }\n return ranges;\n}\n\nfunction clampRanges(ranges, duration) {\n return ranges\n .map((range) => ({\n start: Math.max(0, Math.min(duration, range.start)),\n end: Math.max(0, Math.min(duration, range.end)),\n }))\n .filter((range) => range.end > range.start);\n}\n\nfunction mergeRanges(ranges) {\n const sorted = ranges\n .map((range) => ({ start: round6(range.start), end: round6(range.end) }))\n .sort((a, b) => a.start - b.start || a.end - b.end);\n const merged = [];\n for (const range of sorted) {\n const prev = merged.at(-1);\n if (prev && range.start \u003c= prev.end) {\n prev.end = Math.max(prev.end, range.end);\n } else {\n merged.push({ ...range });\n }\n }\n return merged;\n}\n\nfunction invertRanges(removals, duration) {\n const kept = [];\n let cursor = 0;\n for (const range of removals) {\n if (range.start > cursor) kept.push({ start: cursor, end: range.start });\n cursor = Math.max(cursor, range.end);\n }\n if (cursor \u003c duration) kept.push({ start: cursor, end: duration });\n return kept;\n}\n\n// Range bounds are rounded only to shed float noise, never to the millisecond:\n// these values become ffmpeg's -ss/-to, where a millisecond is wide enough to\n// step a boundary onto the next frame at 29.97/30/60 fps.\nfunction finalizeKept(ranges) {\n return mergeRanges(ranges)\n .map((range) => ({ start: round6(range.start), end: round6(range.end) }))\n .filter((range) => round3(range.end - range.start) >= MIN_SEGMENT_SECONDS);\n}\n\nfunction round6(n) {\n return Math.round(Number(n) * 1e6) / 1e6;\n}\n\nfunction round3(n) {\n return Math.round(Number(n) * 1000) / 1000;\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":6381,"content_sha256":"c395f49bdb602b29dfc1ea98b7f6d0d5d8781f00eca1c16d009d10e7ef0205be"},{"filename":"scripts/lib/duck.mjs","content":"import { wordListsFromMediaMeta } from \"./words.mjs\";\n\n// audio_meta.json word times are relative to each line's own file.\nexport function speechSpans(meta, { mergeGap = 0.6, offsets, sequential = false, gap = 0 } = {}) {\n const merge = Number(mergeGap);\n const lists = wordListsFromMediaMeta(meta);\n const voices = Array.isArray(meta?.voices) ? meta.voices : [];\n if (lists.filter((words) => words.length > 0).length > 1 && !offsets && !sequential) {\n throw new Error(\n \"audio_meta has multiple voice lines with file-relative times; pass --sequential or --offsets so spans land at composition time\",\n );\n }\n const intervals = [];\n let cursor = 0;\n for (let i = 0; i \u003c lists.length; i++) {\n const voice = voices[i];\n let offset = 0;\n if (offsets) {\n if (lists[i].length === 0) continue;\n const id = voice?.id ?? String(i);\n if (!(id in offsets)) throw new Error(`--offsets is missing voice \"${id}\"`);\n offset = Number(offsets[id]) || 0;\n } else if (sequential) {\n offset = cursor;\n const lineDuration = Number(voice?.duration_s) || Math.max(...lists[i].map((w) => w.end), 0);\n cursor += lineDuration + (Number(gap) || 0);\n }\n for (const word of lists[i]) {\n if (word.end > word.start)\n intervals.push({ start: word.start + offset, end: word.end + offset });\n }\n }\n return mergeIntervals(intervals, Number.isFinite(merge) && merge >= 0 ? merge : 0.6);\n}\n\nexport function duckKeyframes(\n spans,\n { duck = 0.25, attack = 0.15, release = 0.4, baseVolume = 1 } = {},\n) {\n const base = finiteOr(baseVolume, 1);\n const ducked = round3(base * finiteOr(duck, 0.25));\n const keyframes = [];\n for (const span of spans) {\n keyframes.push({\n time: round3(Math.max(0, finiteOr(span.start, 0))),\n volume: ducked,\n duration: round3(finiteOr(attack, 0.15)),\n });\n keyframes.push({\n time: round3(Math.max(0, finiteOr(span.end, 0))),\n volume: round3(base),\n duration: round3(finiteOr(release, 0.4)),\n });\n }\n return keyframes.sort((a, b) => a.time - b.time);\n}\n\n/** Volume lane for `data-automation`: composition-time keyframes as clip-local ramps. */\nexport function duckLane(keyframes, { clipStart = 0, baseVolume = 1 } = {}) {\n const start = finiteOr(clipStart, 0);\n const points = [{ t: 0, v: round3(finiteOr(baseVolume, 1)) }];\n const push = (t, v) => {\n if (t > points.at(-1).t) points.push({ t: round3(t), v });\n };\n for (const kf of keyframes) {\n const t = Math.max(0, kf.time);\n push(t, points.at(-1).v);\n push(t + kf.duration, kf.volume);\n }\n\n const next = points.findIndex((point) => point.t > start);\n const before = points[next - 1] ?? points.at(-1);\n const after = points[next];\n const initial =\n next === 0\n ? points[0].v\n : after\n ? before.v + ((after.v - before.v) * (start - before.t)) / (after.t - before.t)\n : before.v;\n const localPoints = [\n { t: 0, v: initial },\n ...points\n .filter((point) => point.t > start)\n .map((point) => ({ t: round3(point.t - start), v: point.v })),\n ];\n return { version: 1, lanes: [{ target: \"volume\", points: localPoints }] };\n}\n\nfunction mergeIntervals(intervals, mergeGap) {\n const sorted = intervals\n .map((range) => ({ start: round3(range.start), end: round3(range.end) }))\n .sort((a, b) => a.start - b.start || a.end - b.end);\n const merged = [];\n for (const range of sorted) {\n const prev = merged.at(-1);\n if (prev && (range.start \u003c= prev.end || range.start - prev.end \u003c mergeGap)) {\n prev.end = Math.max(prev.end, range.end);\n } else {\n merged.push({ ...range });\n }\n }\n return merged;\n}\n\nfunction finiteOr(value, fallback) {\n const n = Number(value);\n return Number.isFinite(n) ? n : fallback;\n}\n\nfunction round3(n) {\n return Math.round(Number(n) * 1000) / 1000;\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":3849,"content_sha256":"0930aea672a8cb204d344902cb90442491a8979f9f554f9c7c61cd13666a6846"},{"filename":"scripts/lib/error-diffusion.mjs","content":"export const ERROR_DIFFUSION_ALGORITHMS = {\n \"floyd-steinberg\": {\n kernel: [\n [1, 0, 7],\n [-1, 1, 3],\n [0, 1, 5],\n [1, 1, 1],\n ],\n divisor: 16,\n },\n atkinson: {\n kernel: [\n [1, 0, 1],\n [2, 0, 1],\n [-1, 1, 1],\n [0, 1, 1],\n [1, 1, 1],\n [0, 2, 1],\n ],\n divisor: 8,\n },\n \"jarvis-judice-ninke\": {\n kernel: [\n [1, 0, 7],\n [2, 0, 5],\n [-2, 1, 3],\n [-1, 1, 5],\n [0, 1, 7],\n [1, 1, 5],\n [2, 1, 3],\n [-2, 2, 1],\n [-1, 2, 3],\n [0, 2, 5],\n [1, 2, 3],\n [2, 2, 1],\n ],\n divisor: 48,\n },\n stucki: {\n kernel: [\n [1, 0, 8],\n [2, 0, 4],\n [-2, 1, 2],\n [-1, 1, 4],\n [0, 1, 8],\n [1, 1, 4],\n [2, 1, 2],\n [-2, 2, 1],\n [-1, 2, 2],\n [0, 2, 4],\n [1, 2, 2],\n [2, 2, 1],\n ],\n divisor: 42,\n },\n burkes: {\n kernel: [\n [1, 0, 8],\n [2, 0, 4],\n [-2, 1, 2],\n [-1, 1, 4],\n [0, 1, 8],\n [1, 1, 4],\n [2, 1, 2],\n ],\n divisor: 32,\n },\n sierra: {\n kernel: [\n [1, 0, 5],\n [2, 0, 3],\n [-2, 1, 2],\n [-1, 1, 4],\n [0, 1, 5],\n [1, 1, 4],\n [2, 1, 2],\n [-1, 2, 2],\n [0, 2, 3],\n [1, 2, 2],\n ],\n divisor: 32,\n },\n \"sierra-lite\": {\n kernel: [\n [1, 0, 2],\n [-1, 1, 1],\n [0, 1, 1],\n ],\n divisor: 4,\n },\n \"two-row-sierra\": {\n kernel: [\n [1, 0, 4],\n [2, 0, 3],\n [-2, 1, 1],\n [-1, 1, 2],\n [0, 1, 3],\n [1, 1, 2],\n [2, 1, 1],\n ],\n divisor: 16,\n },\n};\n\nconst DEFAULTS = {\n algorithm: \"floyd-steinberg\",\n brightness: 1,\n contrast: 1.2,\n detail: 1,\n palette: [\"#000000\", \"#ffffff\"],\n pointSize: 3,\n};\n\nexport function errorDiffusionBufferLength(width, height, pointSize) {\n return Math.ceil(width / pointSize) * Math.ceil(height / pointSize) * 3;\n}\n\nexport function applyErrorDiffusionRgba(data, width, height, options = {}, errorBuffer) {\n if (!Number.isInteger(width) || width \u003c 1 || !Number.isInteger(height) || height \u003c 1) {\n throw new Error(\"width and height must be positive integers\");\n }\n if (!data || data.length !== width * height * 4) {\n throw new Error(`RGBA data must contain ${width * height * 4} bytes`);\n }\n\n const algorithm = options.algorithm ?? DEFAULTS.algorithm;\n const diffusion = ERROR_DIFFUSION_ALGORITHMS[algorithm];\n if (!diffusion) throw new Error(`unknown error-diffusion algorithm: ${algorithm}`);\n\n const pointSize = integerInRange(options.pointSize ?? DEFAULTS.pointSize, 1, 20, \"pointSize\");\n const brightness = numberInRange(options.brightness ?? DEFAULTS.brightness, 0.5, 2, \"brightness\");\n const contrast = numberInRange(options.contrast ?? DEFAULTS.contrast, 0.5, 2, \"contrast\");\n const detail = numberInRange(options.detail ?? DEFAULTS.detail, 0.1, 1, \"detail\");\n const palette = parsePalette(options.palette ?? DEFAULTS.palette);\n const blockColumns = Math.ceil(width / pointSize);\n const blockRows = Math.ceil(height / pointSize);\n const errorLength = errorDiffusionBufferLength(width, height, pointSize);\n const errors = errorBuffer ?? new Float32Array(errorLength);\n if (!(errors instanceof Float32Array) || errors.length !== errorLength) {\n throw new Error(`errorBuffer must be a Float32Array of length ${errorLength}`);\n }\n errors.fill(0);\n\n const centerOffset = Math.floor(pointSize / 2);\n for (let blockRow = 0; blockRow \u003c blockRows; blockRow++) {\n const blockY = blockRow * pointSize;\n for (let blockColumn = 0; blockColumn \u003c blockColumns; blockColumn++) {\n const blockX = blockColumn * pointSize;\n const centerX = Math.min(blockX + centerOffset, width - 1);\n const centerY = Math.min(blockY + centerOffset, height - 1);\n const rgbaIndex = (centerY * width + centerX) * 4;\n const errorIndex = (blockRow * blockColumns + blockColumn) * 3;\n const red = correctedChannel(data[rgbaIndex], errors[errorIndex], brightness, contrast);\n const green = correctedChannel(\n data[rgbaIndex + 1],\n errors[errorIndex + 1],\n brightness,\n contrast,\n );\n const blue = correctedChannel(\n data[rgbaIndex + 2],\n errors[errorIndex + 2],\n brightness,\n contrast,\n );\n const luminance = 0.299 * red + 0.587 * green + 0.114 * blue;\n const output = palette[Math.min(palette.length - 1, Math.floor(luminance * palette.length))];\n\n for (let y = blockY; y \u003c Math.min(blockY + pointSize, height); y++) {\n for (let x = blockX; x \u003c Math.min(blockX + pointSize, width); x++) {\n const outputIndex = (y * width + x) * 4;\n data[outputIndex] = Math.round(output[0] * 255);\n data[outputIndex + 1] = Math.round(output[1] * 255);\n data[outputIndex + 2] = Math.round(output[2] * 255);\n }\n }\n\n for (const [dx, dy, weight] of diffusion.kernel) {\n const targetColumn = blockColumn + dx;\n const targetRow = blockRow + dy;\n if (\n targetColumn \u003c 0 ||\n targetColumn >= blockColumns ||\n targetRow \u003c 0 ||\n targetRow >= blockRows\n ) {\n continue;\n }\n const target = (targetRow * blockColumns + targetColumn) * 3;\n const scale = (weight / diffusion.divisor) * detail;\n errors[target] += (red - output[0]) * scale;\n errors[target + 1] += (green - output[1]) * scale;\n errors[target + 2] += (blue - output[2]) * scale;\n }\n }\n }\n return data;\n}\n\nfunction correctedChannel(byte, error, brightness, contrast) {\n return Math.min(1, Math.max(0, ((byte / 255 - 0.5) * contrast + 0.5) * brightness + error));\n}\n\nfunction parsePalette(colors) {\n if (!Array.isArray(colors) || colors.length \u003c 2 || colors.length > 6) {\n throw new Error(\"palette must contain 2 to 6 colors\");\n }\n return colors.map((color) => {\n const match = /^#([0-9a-f]{6})$/i.exec(color);\n if (!match) throw new Error(`palette color must use #rrggbb: ${color}`);\n const value = Number.parseInt(match[1], 16);\n return [(value >> 16) / 255, ((value >> 8) & 255) / 255, (value & 255) / 255];\n });\n}\n\nfunction numberInRange(value, min, max, name) {\n const number = Number(value);\n if (!Number.isFinite(number) || number \u003c min || number > max) {\n throw new Error(`${name} must be between ${min} and ${max}`);\n }\n return number;\n}\n\nfunction integerInRange(value, min, max, name) {\n const number = Number(value);\n if (!Number.isInteger(number) || number \u003c min || number > max) {\n throw new Error(`${name} must be an integer between ${min} and ${max}`);\n }\n return number;\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":6631,"content_sha256":"aa718fe95f98087979bab5ea31d68b8e45fbde0c5b874c6888ad21923fb45936"},{"filename":"scripts/lib/index-gen.mjs","content":"import { writeFileSync, mkdirSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { currentRecords, indexPath } from \"./manifest.mjs\";\n\nfunction pad(str, len) {\n return String(str ?? \"\").padEnd(len);\n}\n\nfunction formatDur(record) {\n if (record.duration == null) return \"—\";\n return `${record.duration}s`;\n}\n\nfunction formatDims(record) {\n if (record.width && record.height) return `${record.width}×${record.height}`;\n if (record.type === \"icon\" && record.transparent) return \"svg\";\n return \"—\";\n}\n\nexport function generateIndexContent(records) {\n const count = records.length;\n const header = `# .media · ${count} asset${count === 1 ? \"\" : \"s\"}\\n`;\n if (count === 0) return header;\n\n const cols = { id: 4, type: 5, dur: 4, dims: 5, path: 5, desc: 11 };\n for (const r of records) {\n cols.id = Math.max(cols.id, (r.id ?? \"\").length);\n cols.type = Math.max(cols.type, (r.type ?? \"\").length);\n cols.dur = Math.max(cols.dur, formatDur(r).length);\n cols.dims = Math.max(cols.dims, formatDims(r).length);\n cols.path = Math.max(cols.path, (r.path ?? \"\").length);\n }\n\n const heading =\n pad(\"id\", cols.id + 2) +\n pad(\"type\", cols.type + 2) +\n pad(\"dur\", cols.dur + 2) +\n pad(\"dims\", cols.dims + 2) +\n pad(\"path\", cols.path + 2) +\n \"description\";\n\n const lines = [header, heading];\n for (const r of records) {\n lines.push(\n pad(r.id, cols.id + 2) +\n pad(r.type, cols.type + 2) +\n pad(formatDur(r), cols.dur + 2) +\n pad(formatDims(r), cols.dims + 2) +\n pad(r.path, cols.path + 2) +\n (r.description ?? \"\"),\n );\n }\n return lines.join(\"\\n\") + \"\\n\";\n}\n\nexport function regenerateIndex(projectDir) {\n const records = currentRecords(projectDir);\n const content = generateIndexContent(records);\n const p = indexPath(projectDir);\n mkdirSync(dirname(p), { recursive: true });\n writeFileSync(p, content);\n return content;\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":1924,"content_sha256":"fde84f36ebfb4fa819935956b2b6dc43a70b749a5c846d5470295d7c439e40e6"},{"filename":"scripts/lib/manifest.mjs","content":"import {\n readFileSync,\n appendFileSync,\n mkdirSync,\n existsSync,\n readdirSync,\n openSync,\n closeSync,\n writeFileSync,\n rmSync,\n statSync,\n} from \"node:fs\";\nimport { randomBytes } from \"node:crypto\";\nimport { basename, join } from \"node:path\";\n\nconst MANIFEST_FILE = \"manifest.jsonl\";\nconst INDEX_FILE = \"index.md\";\n\nconst TYPE_DIRS = {\n bgm: \"audio/bgm\",\n sfx: \"audio/sfx\",\n voice: \"audio/voice\",\n image: \"images\",\n icon: \"images\",\n logo: \"images\",\n brand: \"images\",\n video: \"video\",\n grade: \"luts\",\n lut: \"luts\",\n recipe: \"recipes\",\n};\n\nexport function mediaDir(projectDir) {\n return join(projectDir, \".media\");\n}\n\nexport function manifestPath(projectDir) {\n return join(mediaDir(projectDir), MANIFEST_FILE);\n}\n\nexport function indexPath(projectDir) {\n return join(mediaDir(projectDir), INDEX_FILE);\n}\n\nexport function typeSubdir(type) {\n const sub = TYPE_DIRS[type];\n if (!sub) throw new Error(`unknown media type: ${type}`);\n return sub;\n}\n\nexport function typeDirPath(projectDir, type) {\n return join(mediaDir(projectDir), typeSubdir(type));\n}\n\nexport function readManifest(projectDir) {\n const p = manifestPath(projectDir);\n if (!existsSync(p)) return [];\n const raw = readFileSync(p, \"utf8\");\n const records = [];\n for (const line of raw.split(/\\r?\\n/)) {\n const trimmed = line.trim();\n if (!trimmed) continue;\n try {\n records.push(JSON.parse(trimmed));\n } catch {\n // ponytail: skip malformed lines, don't crash\n }\n }\n return records;\n}\n\nexport function appendRecord(projectDir, record) {\n const dir = mediaDir(projectDir);\n mkdirSync(dir, { recursive: true });\n const typeDir = typeDirPath(projectDir, record.type);\n mkdirSync(typeDir, { recursive: true });\n\n const p = manifestPath(projectDir);\n const line = JSON.stringify(record) + \"\\n\";\n appendFileSync(p, line);\n}\n\n/** Sources that mean the agent made or fetched the file; any other file is the person's own. */\nexport const AGENT_SOURCES = [\"generated\", \"search\", \"bundled\"];\n\n/** The record a path has now: the manifest only appends, so the last one for a path wins. */\nexport function latestRecordFor(projectDir, path) {\n return readManifest(projectDir).findLast((record) => record.path === path);\n}\n\n/** Records with every older record for the same path dropped, since the last one for a path is its record. */\nexport function currentRecords(projectDir) {\n const records = readManifest(projectDir);\n const last = new Map(records.map((record, index) => [record.path, index]));\n return records.filter((record, index) => !record.path || last.get(record.path) === index);\n}\n\n/** Records a file already in the project where it is, unless its current record already says the same thing. */\nexport function recordInPlace(\n projectDir,\n { type, path, source, description, duration, provenance },\n) {\n const fields = {\n type,\n path,\n source,\n description: description || basename(path),\n ...(duration != null && { duration: Math.round(duration * 10) / 10 }),\n };\n return withMediaLock(projectDir, () => {\n const latest = latestRecordFor(projectDir, path);\n const same = [\"source\", \"description\", \"duration\"].every(\n (key) => latest?.[key] === fields[key],\n );\n if (latest && same) return latest;\n const record = { id: nextFreeId(projectDir, type), ...fields, provenance };\n appendRecord(projectDir, record);\n return record;\n });\n}\n\n// Match prompts forgivingly. Agents rarely re-emit a byte-identical intent, so\n// keying cache lookups on exact equality meant \"Calm piano\" and \"calm piano\"\n// re-searched and re-downloaded. Normalize (trim, lowercase, collapse internal\n// whitespace) on both sides; the raw prompt is still stored for audit.\nexport function normalizePrompt(prompt) {\n return String(prompt ?? \"\")\n .trim()\n .toLowerCase()\n .replace(/\\s+/g, \" \");\n}\n\nexport function findByPrompt(projectDir, prompt, type) {\n const key = normalizePrompt(prompt);\n if (!key) return null;\n const records = currentRecords(projectDir);\n return (\n records.find(\n (r) => normalizePrompt(r.provenance?.prompt) === key && (type == null || r.type === type),\n ) || null\n );\n}\n\nexport function findByEntity(projectDir, entity) {\n const lower = entity.toLowerCase();\n const records = currentRecords(projectDir);\n return records.find((r) => r.entity && r.entity.toLowerCase() === lower) || null;\n}\n\nexport function nextId(projectDir, type) {\n const records = readManifest(projectDir);\n const prefix = type;\n let max = 0;\n for (const r of records) {\n if (r.type !== type) continue;\n const m = r.id?.match(new RegExp(`^${prefix}_(\\\\d+) media-use — Skillopedia ));\n if (m) max = Math.max(max, parseInt(m[1], 10));\n }\n return `${prefix}_${String(max + 1).padStart(3, \"0\")}`;\n}\n\n// Sync sleep (no busy-spin) for the allocation lock retry.\nfunction sleepMs(ms) {\n Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);\n}\n\n// Coarse per-project lock so concurrent resolves don't race on id allocation.\n// ponytail: one lock file with a 15s stale-steal (a crashed holder can't wedge\n// the project); fine for agent-scale concurrency — revisit if throughput needs\n// finer locking. Date.now() is available here (a normal Node CLI, not a\n// workflow DSL), so mtime-based staleness is safe.\nconst LOCK_STALE_MS = 15000;\nconst LOCK_TIMEOUT_MS = 20000;\n\nfunction withLock(dir, fn) {\n const lock = join(dir, \".lock\");\n const start = Date.now();\n for (;;) {\n try {\n closeSync(openSync(lock, \"wx\")); // O_EXCL: atomic acquire\n break;\n } catch (err) {\n if (err.code !== \"EEXIST\") throw err;\n try {\n if (Date.now() - statSync(lock).mtimeMs > LOCK_STALE_MS) {\n rmSync(lock, { force: true }); // steal a stale lock from a dead holder\n continue;\n }\n } catch {\n continue; // lock vanished between check and stat — retry the acquire\n }\n if (Date.now() - start > LOCK_TIMEOUT_MS) {\n throw new Error(\"media-use: timed out acquiring .media/.lock\");\n }\n sleepMs(25);\n }\n }\n try {\n return fn();\n } finally {\n rmSync(lock, { force: true });\n }\n}\n\n/** Runs `fn` holding the project's `.media/.lock`, so concurrent resolves take turns on what it guards. */\nexport function withMediaLock(projectDir, fn) {\n mkdirSync(mediaDir(projectDir), { recursive: true });\n return withLock(mediaDir(projectDir), fn);\n}\n\n// Atomically allocate the next free id for `type` AND reserve it on disk, so a\n// slow download/copy between allocation and appendRecord can't let a concurrent\n// caller grab the same id (the MU-23 clobber). Under the lock we take the max id\n// across BOTH the manifest and any already-reserved files in the type dir, then\n// O_EXCL-create an empty marker under core's atomic temp name, which Studio's\n// project history skips. Returns { id, localPath, markerPath }.\nexport function allocateId(projectDir, type, ext) {\n mkdirSync(typeDirPath(projectDir, type), { recursive: true });\n return withMediaLock(projectDir, () => {\n const id = nextFreeId(projectDir, type);\n const localPath = `.media/${typeSubdir(type)}/${id}${ext}`;\n // Same shape as core atomicTempPath: an empty file at the final name would be committed.\n const markerPath = `${join(projectDir, localPath)}.hf${randomBytes(3).toString(\"hex\")}.tmp`;\n writeFileSync(markerPath, \"\", { flag: \"wx\" }); // durable reservation\n return { id, localPath, markerPath };\n });\n}\n\n// Call under the lock: counts recorded ids and ids reserved by a file not yet recorded.\nfunction nextFreeId(projectDir, type) {\n const re = new RegExp(`^${type}_(\\\\d+)`);\n let max = 0;\n for (const r of readManifest(projectDir)) {\n if (r.type !== type) continue;\n const m = r.id?.match(re);\n if (m) max = Math.max(max, parseInt(m[1], 10));\n }\n const typeDir = typeDirPath(projectDir, type);\n for (const f of existsSync(typeDir) ? readdirSync(typeDir) : []) {\n const m = f.match(re);\n if (m) max = Math.max(max, parseInt(m[1], 10));\n }\n return `${type}_${String(max + 1).padStart(3, \"0\")}`;\n}\n\nfunction reservedFile(projectDir, type, ext) {\n const allocation = allocateId(projectDir, type, ext);\n return { ...allocation, fullPath: join(projectDir, allocation.localPath) };\n}\n\nfunction releaseReservation(reservation, committed) {\n if (!committed) rmSync(reservation.fullPath, { force: true });\n rmSync(reservation.markerPath, { force: true });\n}\n\n// A reservation is committed only when populate returns a non-null value.\n// Throwing/rejecting or returning null means no usable asset was produced, so\n// the reservation and any partial asset are released. Keeping this transaction\n// beside allocateId prevents provider/cache/LUT paths from forgetting the rollback.\nexport function withReservedFileSync(projectDir, type, ext, populate) {\n const reservation = reservedFile(projectDir, type, ext);\n try {\n const result = populate(reservation);\n releaseReservation(reservation, result != null);\n return result;\n } catch (error) {\n releaseReservation(reservation, false);\n throw error;\n }\n}\n\nexport async function withReservedFile(projectDir, type, ext, populate) {\n const reservation = reservedFile(projectDir, type, ext);\n try {\n const result = await populate(reservation);\n releaseReservation(reservation, result != null);\n return result;\n } catch (error) {\n releaseReservation(reservation, false);\n throw error;\n }\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":9424,"content_sha256":"67f827f7591241c170fd92eb7fa789df2f1756b2cd4889907141936179f5d00f"},{"filename":"scripts/lib/media-fetch.mjs","content":"// Media downloads use public HTTP(S) URLs. Validate every redirect target;\n// a provider result must meet the same host policy as a direct ingest URL.\n// Public HTTPS-to-HTTP redirects are allowed, matching direct HTTP support.\n// This is a literal-host policy, not DNS pinning: DNS resolution remains trusted.\n\nimport { BlockList, isIP } from \"node:net\";\n\nconst blocked = new BlockList();\nfor (const [network, prefix] of [\n [\"0.0.0.0\", 8],\n [\"10.0.0.0\", 8],\n [\"100.64.0.0\", 10],\n [\"127.0.0.0\", 8],\n [\"169.254.0.0\", 16],\n [\"172.16.0.0\", 12],\n [\"192.0.0.0\", 24],\n [\"192.0.2.0\", 24],\n [\"192.88.99.0\", 24],\n [\"192.168.0.0\", 16],\n [\"198.18.0.0\", 15],\n [\"198.51.100.0\", 24],\n [\"203.0.113.0\", 24],\n [\"224.0.0.0\", 4],\n [\"240.0.0.0\", 4],\n])\n blocked.addSubnet(network, prefix, \"ipv4\");\nfor (const [network, prefix] of [\n [\"::\", 128],\n [\"::1\", 128],\n [\"fc00::\", 7],\n [\"fe80::\", 10],\n [\"fec0::\", 10],\n [\"ff00::\", 8],\n [\"2001:db8::\", 32],\n])\n blocked.addSubnet(network, prefix, \"ipv6\");\n\nexport function isPublicMediaUrl(value) {\n try {\n const url = new URL(value);\n if (url.protocol !== \"http:\" && url.protocol !== \"https:\") return false;\n const host = url.hostname.replace(/\\.$/, \"\");\n if (\n host === \"localhost\" ||\n host.endsWith(\".localhost\") ||\n host.endsWith(\".local\") ||\n host.endsWith(\".internal\")\n )\n return false;\n const address = host.replace(/^\\[|\\]$/g, \"\");\n const family = isIP(address);\n return family === 0 || !blocked.check(address, family === 4 ? \"ipv4\" : \"ipv6\");\n } catch {\n return false;\n }\n}\n\nexport async function fetchMedia(url, { method = \"GET\", signal, fetchImpl = fetch } = {}) {\n let current = String(url);\n for (let hop = 0; hop \u003c= 5; hop++) {\n if (!isPublicMediaUrl(current))\n throw new Error(\"Media download blocked: URL is not public HTTP(S)\");\n const response = await fetchImpl(current, { method, signal, redirect: \"manual\" });\n if (!(response.status >= 300 && response.status \u003c 400)) return response;\n const location = response.headers.get(\"location\");\n if (!location) return response;\n await response.body?.cancel();\n current = new URL(location, current).href;\n }\n throw new Error(\"Media download exceeded redirect limit\");\n}\n\n// Stream and abort once the cap is crossed, so a lying or chunked body can't buffer past it.\nexport async function readCappedBody(res, maxBytes, label) {\n const declared = Number(res.headers.get(\"content-length\"));\n if (declared > maxBytes) throw new Error(`${label}: ${declared} bytes exceeds ${maxBytes} cap`);\n const chunks = [];\n let total = 0;\n for await (const chunk of res.body) {\n total += chunk.length;\n if (total > maxBytes) throw new Error(`${label}: stream exceeds ${maxBytes} cap`);\n chunks.push(chunk);\n }\n return Buffer.concat(chunks, total);\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":2838,"content_sha256":"6a90740eee3e4765b83b4c9726676b2935a7fbc9990f61ad5b166f9263188366"},{"filename":"scripts/lib/media-home.mjs","content":"import { homedir } from \"node:os\";\nimport { join } from \"node:path\";\n\n// The one owner of where the person's media library lives. This repo's test runs set\n// HYPERFRAMES_MEDIA_HOME_REQUIRED, so a test that forgot HYPERFRAMES_MEDIA_HOME fails instead\n// of writing fixtures into the media library apps list as the person's own files.\nexport function mediaHome() {\n const override = process.env.HYPERFRAMES_MEDIA_HOME;\n if (override) return override;\n if (process.env.HYPERFRAMES_MEDIA_HOME_REQUIRED) {\n throw new Error(\n \"media-use: a test reached the real ~/.media; set HYPERFRAMES_MEDIA_HOME to a temp dir\",\n );\n }\n return homedir();\n}\n\nexport function globalMediaDir() {\n return join(mediaHome(), \".media\");\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":730,"content_sha256":"7f69890d7b822f202b44ddec0d8176c767cd8b1da4dfc4d918599c6a05cfecb1"},{"filename":"scripts/lib/npx-sync.mjs","content":"import { existsSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\n\nfunction resolveNpxCliPath(env, pathExists) {\n const npmExecPath = env.npm_execpath;\n const nodeExecPath = env.npm_node_execpath || process.execPath;\n if (npmExecPath) {\n const fileName = npmExecPath.replace(/\\\\/g, \"/\").split(\"/\").pop()?.toLowerCase();\n const candidate =\n fileName === \"npx-cli.js\" ? npmExecPath : join(dirname(npmExecPath), \"npx-cli.js\");\n if (pathExists(candidate)) return candidate;\n }\n const besideNode = join(dirname(nodeExecPath), \"node_modules\", \"npm\", \"bin\", \"npx-cli.js\");\n return pathExists(besideNode) ? besideNode : null;\n}\n\n// Sync-spawn analog of the audio engine's spawnP, for execFileSync call sites\n// that must hard-fail (rather than fall through to another provider) when npx\n// cannot be resolved. On Windows a bare \"npx\" is npx.cmd, which\n// execFileSync/spawnSync cannot exec (spawnSync npx ENOENT) —\n// resolveSpawnCommand reroutes it through node + npx-cli.js, no shell:true.\n//\n// `platform`/`env`/`pathExists` params (defaulting to the real values) exist\n// so tests can exercise the win32 branch without mocking node:child_process\n// (its ESM exports are non-configurable) — same idiom as spawnP and\n// localTtsGenerate.\nexport function resolveNpxInvocation(\n argv,\n opts,\n platform = process.platform,\n env = process.env,\n pathExists = existsSync,\n) {\n const resolved =\n platform !== \"win32\"\n ? { cmd: \"npx\", args: argv, opts: { stdio: \"ignore\", ...opts } }\n : (() => {\n const nodeExecPath = env.npm_node_execpath || process.execPath;\n const npxCliPath = resolveNpxCliPath(env, pathExists);\n return npxCliPath\n ? {\n cmd: nodeExecPath,\n args: [npxCliPath, ...argv.map((arg) => String(arg))],\n opts: { stdio: \"ignore\", windowsHide: true, ...opts },\n }\n : null;\n })();\n if (!resolved) {\n // npx-on-win32 with no resolvable npx-cli.js — same terminal condition\n // spawnP warns about, surfaced as a throw for callers with no fallback.\n throw new Error(\n \"cannot run npx on Windows: npm's npx-cli.js was not found \" +\n \"(install npm with Node, or run via npx/npm run so npm_execpath is set)\",\n );\n }\n return resolved;\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":2328,"content_sha256":"1dc7f6372da36242f8c373defcba80fe9e006ce824e0f459e6d56226b3bf919a"},{"filename":"scripts/lib/parakeet-words.mjs","content":"// Merge Parakeet-MLX token timestamps into word timestamps.\n//\n// parakeet-mlx JSON emits SUB-WORD tokens (\" H\", \"ello\", ...) with per-token\n// start/end. Captions + transcript-cut need WORD timestamps, so join tokens\n// into words on the space boundary: a token whose text starts with a space\n// (or the very first token) begins a new word; the rest append. Output matches\n// the { words: [{ text, start, end }] } shape the rest of media-use consumes\n// (see words.mjs / cutlist.mjs).\n\nexport function mergeTokensToWords(parakeet) {\n const sentences = Array.isArray(parakeet?.sentences) ? parakeet.sentences : [];\n const words = [];\n for (const s of sentences) {\n for (const t of s.tokens ?? []) {\n const raw = typeof t.text === \"string\" ? t.text : \"\";\n const startsWord = raw.startsWith(\" \") || words.length === 0;\n if (startsWord) {\n words.push({ text: raw.trim(), start: t.start, end: t.end });\n } else {\n const w = words[words.length - 1];\n w.text += raw;\n w.end = t.end;\n }\n }\n }\n return { text: (parakeet?.text ?? \"\").trim(), words: words.filter((w) => w.text.length > 0) };\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":1149,"content_sha256":"d5b66efe6cb8975beab2f523503113c3be3117e687ebc20695e7ab08c2ba1b4d"},{"filename":"scripts/lib/prefs-store.mjs","content":"import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from \"node:fs\";\nimport * as fs from \"node:fs\";\nimport { basename, dirname, join, resolve } from \"node:path\";\nimport { withFileLock } from \"./config-lock.mjs\";\nimport { globalMediaDir } from \"./media-home.mjs\";\n\n/**\n * Remembered defaults — the lightweight tier of HyperFrames user memory.\n *\n * Two files, same shape as the rest of media-use's storage split:\n * - project `.media/preferences.json` — committed with the repo, so the whole\n * team inherits it; written every time a brief answer is confirmed.\n * - user `~/.media/preferences.json` — personal, cross-repo. A key is promoted\n * here only once the same value has been confirmed in two different projects\n * (`PROMOTE_AT`), so a one-off choice never pollutes the global defaults.\n * Pre-promotion evidence accumulates in the user file's `sightings` ledger —\n * project files can't see each other, so the cross-project count has to live\n * user-side.\n *\n * Consumption contract (media-use references/memory.md): a remembered\n * value becomes the recommended option with a receipt naming its source — it\n * never skips a question, and explicit request content always wins.\n */\n\nconst PREFS_FILE = \"preferences.json\";\n\n/** Keys the brief contract records; `style_preset` is stored per workflow. */\nexport const PREFERENCE_KEYS = [\n \"destination\",\n \"aspect\",\n \"language\",\n \"flow\",\n \"storyboard\",\n \"voice\",\n \"style_preset\",\n];\n\n/** A value must be confirmed in this many distinct projects to go user-tier. */\nexport const PROMOTE_AT = 2;\n\nexport function projectPrefsPath(projectDir) {\n return join(resolve(projectDir), \".media\", PREFS_FILE);\n}\n\nexport function userPrefsPath() {\n return join(globalMediaDir(), PREFS_FILE);\n}\n\nfunction emptyFile() {\n return { version: 1, preferences: {}, sightings: {} };\n}\n\nfunction isRecord(value) {\n return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/** Tolerant read — a missing or malformed file counts as empty. */\nfunction readPrefsFile(path) {\n try {\n if (!existsSync(path)) return emptyFile();\n const parsed = JSON.parse(readFileSync(path, \"utf8\"));\n if (!isRecord(parsed)) return emptyFile();\n return {\n version: 1,\n preferences: isRecord(parsed.preferences) ? parsed.preferences : {},\n sightings: isRecord(parsed.sightings) ? parsed.sightings : {},\n };\n } catch {\n return emptyFile();\n }\n}\n\n/** Atomic write (tmp + rename) so a crash never leaves a torn file. */\nfunction writePrefsFile(path, file) {\n const tmp = `${path}.${process.pid}.tmp`;\n try {\n writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\\n`);\n renameSync(tmp, path);\n } finally {\n try {\n fs.rmSync(tmp, { force: true });\n } catch {}\n }\n}\n\nfunction updatePrefsFile(path, update) {\n mkdirSync(dirname(path), { recursive: true });\n return withFileLock(`${path}.lock`, fs, () => {\n const file = readPrefsFile(path);\n const result = update(file);\n writePrefsFile(path, file);\n return result;\n });\n}\n\n/** `style_preset` entries are stored per workflow as `style_preset.\u003cworkflow>`. */\nexport function preferenceKeyFor(key, workflow) {\n return key === \"style_preset\" && workflow ? `style_preset.${workflow}` : key;\n}\n\nfunction validEntry(entry) {\n return isRecord(entry) && typeof entry.value === \"string\" && entry.value.length > 0;\n}\n\n/**\n * The merged view the brief reads: user-tier promoted entries first, project\n * entries on top (project wins). Each entry carries `source` plus the receipt\n * material (`confirmed_in`, `updated_at`).\n */\nexport function mergedPreferences(projectDir) {\n const user = readPrefsFile(userPrefsPath());\n const project = readPrefsFile(projectPrefsPath(projectDir));\n const merged = {};\n for (const [key, entry] of Object.entries(user.preferences)) {\n if (validEntry(entry)) merged[key] = { ...entry, source: \"user\" };\n }\n for (const [key, entry] of Object.entries(project.preferences)) {\n if (validEntry(entry)) merged[key] = { ...entry, source: \"project\" };\n }\n return merged;\n}\n\nfunction dedupe(list) {\n return [...new Set(list)];\n}\n\n/**\n * Project tier: same value accumulates confirmations; a changed value starts\n * provenance over (the old confirmations vouched for the old value).\n */\nfunction recordProjectTier(projectDir, fullKey, value, projectName, now) {\n return updatePrefsFile(projectPrefsPath(projectDir), (file) => {\n const previous = file.preferences[fullKey];\n const keepProvenance = validEntry(previous) && previous.value === value;\n const confirmedIn = keepProvenance\n ? dedupe([\n ...(Array.isArray(previous.confirmed_in) ? previous.confirmed_in : []),\n projectName,\n ])\n : [projectName];\n file.preferences[fullKey] = { value, confirmed_in: confirmedIn, updated_at: now };\n return confirmedIn;\n });\n}\n\n/**\n * User tier: accumulate this sighting in the ledger, and promote the key once\n * the same value has been confirmed in PROMOTE_AT distinct projects.\n */\nfunction recordUserSighting(fullKey, value, projectName, now) {\n return updatePrefsFile(userPrefsPath(), (file) => {\n const keySightings = isRecord(file.sightings[fullKey]) ? file.sightings[fullKey] : {};\n const seenIn = dedupe([\n ...(Array.isArray(keySightings[value]) ? keySightings[value] : []),\n projectName,\n ]);\n keySightings[value] = seenIn;\n file.sightings[fullKey] = keySightings;\n const promoted = seenIn.length >= PROMOTE_AT;\n if (promoted) {\n file.preferences[fullKey] = { value, confirmed_in: seenIn, updated_at: now };\n }\n return promoted;\n });\n}\n\n/**\n * Record one confirmed brief answer. Always writes the project tier; feeds the\n * user tier's sightings ledger and promotes once the same value has been\n * confirmed in PROMOTE_AT distinct projects. Idempotent per project.\n */\nexport function recordPreference({ projectDir, key, value, workflow }) {\n if (!PREFERENCE_KEYS.includes(key)) {\n throw new Error(`unknown preference key: \"${key}\" (known: ${PREFERENCE_KEYS.join(\", \")})`);\n }\n if (typeof value !== \"string\" || !value.trim()) {\n throw new Error(\"a preference needs a non-empty string value\");\n }\n if (key === \"style_preset\" && (!workflow || !String(workflow).trim())) {\n throw new Error(\"style_preset is stored per workflow — pass --workflow \u003cw>\");\n }\n const fullKey = preferenceKeyFor(key, workflow);\n const projectName = basename(resolve(projectDir));\n const trimmed = value.trim();\n const now = new Date().toISOString();\n\n const confirmedIn = recordProjectTier(projectDir, fullKey, trimmed, projectName, now);\n\n // Best-effort — a read-only home directory must never fail a brief.\n let promoted = false;\n try {\n promoted = recordUserSighting(fullKey, trimmed, projectName, now);\n } catch {\n // The project record already landed; promotion just waits for next time.\n }\n\n return { key: fullKey, value: trimmed, confirmed_in: confirmedIn, promoted };\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":7012,"content_sha256":"960429595e5c5dda3f88f2899852d2ac2322a7d26b27ed8139612d0161fff749"},{"filename":"scripts/lib/recipe-store.mjs","content":"import {\n cpSync,\n existsSync,\n mkdirSync,\n readdirSync,\n readFileSync,\n renameSync,\n rmSync,\n writeFileSync,\n} from \"node:fs\";\nimport { basename, join, resolve } from \"node:path\";\nimport { globalMediaDir } from \"./media-home.mjs\";\nimport { appendRecord, mediaDir, nextId } from \"./manifest.mjs\";\nimport { regenerateIndex } from \"./index-gen.mjs\";\nimport { mergedPreferences } from \"./prefs-store.mjs\";\n\n// A filter keeps Node 22 off its native copy, which writes nothing under a non-ASCII path on Windows.\nconst NON_ASCII_SAFE_DIR_COPY = { recursive: true, force: true, filter: () => true };\n\n/**\n * Recipes — the heavyweight tier of HyperFrames user memory.\n *\n * A recipe is the full confirmed bundle for one video type: the frozen design\n * spec (`frame.md`), the storyboard skeleton (structure with the content\n * blanked), and the confirmed brief values — frozen after the run's final\n * approval, reused to start the next video of the same type from everything\n * already approved.\n *\n * Storage is **named folders**, not content-addressed cache entries: a recipe\n * is an evolving bundle with a `version`, so re-freezing the same name bumps\n * the version and archives the old folder as `\u003cname>@v\u003cN>`. Two tiers, same\n * split as everything else in media-use: project `.media/recipes/\u003cname>/`\n * (committed) and user `~/.media/recipes/\u003cname>/` (a freeze is already a\n * confirmed bundle, so it promotes immediately — no two-project rule here).\n */\n\n/** Frontmatter keys that describe THIS video, not the reusable type. */\nconst FRONTMATTER_CONTENT_KEYS = new Set([\"message\", \"audience\", \"mode\"]);\n\n/** BRIEF.md frontmatter keys that describe this run, not the reusable type —\n * a recipe never locks the run's shape, so these are always asked again. */\nconst BRIEF_CONTENT_KEYS = new Set([\"flow\", \"storyboard\", \"message\", \"audience\"]);\n\n/** Per-frame metadata that is content, not structure. */\nconst FRAME_CONTENT_KEYS = new Set([\n \"voiceover\",\n \"vo\",\n \"voice_over\",\n \"narration\",\n \"scene\",\n \"description\",\n \"summary\",\n \"caption\",\n \"asset_candidates\",\n]);\n\nconst FRAME_HEADING_RE = /^(#{2,3})\\s+(?:frame|beat|scene)\\s+\\d+/i;\n\nexport function projectRecipesDir(projectDir) {\n return join(mediaDir(projectDir), \"recipes\");\n}\n\nexport function userRecipesDir() {\n return join(globalMediaDir(), \"recipes\");\n}\n\nexport function slugifyRecipeName(name) {\n const slug = String(name ?? \"\")\n .trim()\n .toLowerCase()\n .replace(/[\\s_]+/g, \"-\")\n .replace(/[^a-z0-9-]/g, \"\")\n .replace(/-+/g, \"-\")\n .replace(/^-|-$/g, \"\");\n if (!slug) throw new Error(`recipe name \"${name}\" has no usable characters`);\n return slug;\n}\n\nfunction frameTitle(headingLine) {\n const dash = headingLine.split(/\\s+—\\s+/)[1];\n if (dash && dash.trim()) return dash.trim();\n return headingLine.replace(/^#+\\s*/, \"\").trim();\n}\n\n/** Frontmatter: drop the content keys, keep structure/style keys verbatim. */\nfunction skeletonFrontmatter(lines, out, contentKeys = FRONTMATTER_CONTENT_KEYS) {\n if (lines[0]?.trim() !== \"---\") return 0;\n out.push(lines[0]);\n let i = 1;\n while (i \u003c lines.length && lines[i].trim() !== \"---\") {\n const key = lines[i].match(/^(\\w+)\\s*:/)?.[1]?.toLowerCase();\n if (!key || !contentKeys.has(key)) out.push(lines[i]);\n i++;\n }\n if (i \u003c lines.length) {\n out.push(lines[i]); // closing ---\n i++;\n }\n return i;\n}\n\n/** One line inside a frame section — returns the replacement lines (may be none). */\nfunction skeletonFrameLine(line, state, out) {\n const bulletKey = line.match(/^-\\s+(\\w+)\\s*:/)?.[1]?.toLowerCase();\n if (bulletKey) {\n if (bulletKey === \"status\") out.push(\"- status: outline\");\n else if (!FRAME_CONTENT_KEYS.has(bulletKey)) out.push(line);\n return;\n }\n if (!line.trim()) {\n out.push(line);\n return;\n }\n // Frame prose: one placeholder per frame in place of the narrative.\n if (!state.proseReplaced) {\n out.push(\n `\u003cfill in: this video's content for the \"${state.title}\" beat — keep the layout role, replace the words.>`,\n );\n state.proseReplaced = true;\n }\n}\n\n/**\n * Skeletonize a STORYBOARD.md: keep the reusable structure (frame count,\n * durations, transitions, src paths, the Video direction block, style-ish\n * frontmatter), reset every status to `outline`, and blank the content\n * (message/audience, narration guides, per-frame prose) down to a fill-in\n * placeholder that names the frame's role.\n */\n/**\n * Skeletonize a BRIEF.md: keep the frontmatter's reusable keys (workflow,\n * destination, aspect, language, length, angle…), drop the run-shape and\n * content keys (flow, storyboard, message, audience), and blank each body\n * section down to a fill-in placeholder under its kept heading.\n */\nexport function skeletonizeBrief(source) {\n const lines = String(source ?? \"\").split(/\\r?\\n/);\n const out = [];\n let i = skeletonFrontmatter(lines, out, BRIEF_CONTENT_KEYS);\n for (; i \u003c lines.length; i++) {\n const heading = lines[i].match(/^##\\s+(.+)$/);\n if (heading) {\n out.push(lines[i], \"\");\n out.push(\n `\u003cfill in: this video's ${heading[1].trim().toLowerCase()} — the recipe keeps the shape, this run supplies the specifics.>`,\n );\n out.push(\"\");\n }\n }\n return out.join(\"\\n\").replace(/\\n{3,}/g, \"\\n\\n\");\n}\n\nexport function skeletonizeStoryboard(source) {\n const lines = String(source ?? \"\").split(/\\r?\\n/);\n const out = [];\n const state = { inFrame: false, proseReplaced: false, title: \"\" };\n for (let i = skeletonFrontmatter(lines, out); i \u003c lines.length; i++) {\n const line = lines[i];\n if (/^#{2,3}\\s/.test(line)) {\n state.inFrame = FRAME_HEADING_RE.test(line);\n state.proseReplaced = false;\n state.title = state.inFrame ? frameTitle(line) : \"\";\n out.push(line);\n } else if (!state.inFrame) {\n out.push(line);\n } else {\n skeletonFrameLine(line, state, out);\n }\n }\n return out.join(\"\\n\").replace(/\\n{3,}/g, \"\\n\\n\");\n}\n\n/** The run's workflow as BRIEF.md records it — the source of truth a freeze\n * must not contradict. Undefined when no BRIEF.md (or no `workflow:`) exists. */\nfunction briefWorkflow(root) {\n const brief = join(root, \"BRIEF.md\");\n if (!existsSync(brief)) return undefined;\n const lines = readFileSync(brief, \"utf8\").split(/\\r?\\n/);\n if (lines[0]?.trim() !== \"---\") return undefined;\n for (let i = 1; i \u003c lines.length && lines[i].trim() !== \"---\"; i++) {\n const match = lines[i].match(/^workflow\\s*:\\s*(.+?)\\s*$/);\n if (match) return match[1].replace(/^[\"']|[\"']$/g, \"\") || undefined;\n }\n return undefined;\n}\n\nfunction readRecipeJson(dir) {\n try {\n const parsed = JSON.parse(readFileSync(join(dir, \"recipe.json\"), \"utf8\"));\n if (typeof parsed !== \"object\" || parsed === null || typeof parsed.name !== \"string\") {\n return null;\n }\n return parsed;\n } catch {\n return null;\n }\n}\n\nfunction prefValue(prefs, key) {\n return prefs[key]?.value;\n}\n\n/**\n * Freeze the current project's approved run as a named recipe. Writes the\n * project-tier folder + a manifest record, then copies to the user tier (a\n * freeze is already confirmed — it promotes immediately).\n */\nexport function freezeRecipe({ projectDir, name, workflow, blocks }) {\n const slug = slugifyRecipeName(name);\n const root = resolve(projectDir);\n const fromBrief = briefWorkflow(root);\n const fromFlag = workflow && String(workflow).trim() ? String(workflow).trim() : undefined;\n // BRIEF.md decides; the flag only covers projects briefed before it existed.\n const resolvedWorkflow = fromBrief ?? fromFlag;\n if (!resolvedWorkflow) {\n throw new Error(\"no workflow found — BRIEF.md names none and no --workflow was given\");\n }\n const frameSpec = join(root, \"frame.md\");\n const storyboard = join(root, \"STORYBOARD.md\");\n if (!existsSync(frameSpec)) throw new Error(\"no frame.md to freeze — run the design step first\");\n if (!existsSync(storyboard)) throw new Error(\"no STORYBOARD.md to freeze\");\n\n const dir = join(projectRecipesDir(root), slug);\n let version = 1;\n const previous = existsSync(dir) ? readRecipeJson(dir) : null;\n if (previous) {\n version = (Number.isInteger(previous.version) ? previous.version : 1) + 1;\n const archive = `${dir}@v${previous.version ?? 1}`;\n rmSync(archive, { recursive: true, force: true });\n renameSync(dir, archive);\n }\n mkdirSync(dir, { recursive: true });\n\n const prefs = mergedPreferences(root);\n const recipe = {\n version,\n name: slug,\n workflow: resolvedWorkflow,\n approved_at: new Date().toISOString(),\n source_project: basename(root),\n destination: prefValue(prefs, \"destination\"),\n aspect: prefValue(prefs, \"aspect\"),\n language: prefValue(prefs, \"language\"),\n voice: prefValue(prefs, \"voice\"),\n // The bare-key fallback tolerates records made before the store required\n // style_preset to be workflow-scoped.\n style_preset:\n prefValue(prefs, `style_preset.${resolvedWorkflow}`) ?? prefValue(prefs, \"style_preset\"),\n blocks: Array.isArray(blocks) && blocks.length > 0 ? blocks : undefined,\n };\n\n writeFileSync(join(dir, \"recipe.json\"), `${JSON.stringify(recipe, null, 2)}\\n`);\n cpSync(frameSpec, join(dir, \"frame.md\"));\n writeFileSync(\n join(dir, \"storyboard-skeleton.md\"),\n `${skeletonizeStoryboard(readFileSync(storyboard, \"utf8\")).trimEnd()}\\n`,\n );\n\n // Best-effort fourth artifact — projects briefed before BRIEF.md existed\n // (or by workflows that don't write one) freeze fine without it.\n const brief = join(root, \"BRIEF.md\");\n const briefSkeleton = existsSync(brief);\n if (briefSkeleton) {\n writeFileSync(\n join(dir, \"brief-skeleton.md\"),\n `${skeletonizeBrief(readFileSync(brief, \"utf8\")).trimEnd()}\\n`,\n );\n }\n\n const id = nextId(root, \"recipe\");\n appendRecord(root, {\n id,\n type: \"recipe\",\n path: `.media/recipes/${slug}/recipe.json`,\n entity: slug,\n description: `recipe: ${slug} (${recipe.workflow}, v${version})`,\n provenance: { provider: \"recipe.freeze\", version, source_project: recipe.source_project },\n });\n regenerateIndex(root);\n\n // User tier — best-effort, like every other promotion.\n try {\n const userDir = join(userRecipesDir(), slug);\n mkdirSync(userDir, { recursive: true });\n cpSync(dir, userDir, NON_ASCII_SAFE_DIR_COPY);\n if (!briefSkeleton) rmSync(join(userDir, \"brief-skeleton.md\"), { force: true });\n } catch {\n // The project-tier freeze already landed.\n }\n\n return {\n id,\n slug,\n version,\n dir,\n briefSkeleton,\n workflow: resolvedWorkflow,\n workflowOverridden: Boolean(fromBrief && fromFlag && fromBrief !== fromFlag),\n };\n}\n\nfunction scanRecipesDir(dir, source) {\n if (!existsSync(dir)) return [];\n const found = [];\n for (const entry of readdirSync(dir, { withFileTypes: true })) {\n if (!entry.isDirectory() || entry.name.includes(\"@v\")) continue;\n const recipe = readRecipeJson(join(dir, entry.name));\n if (recipe) found.push({ ...recipe, source, dir: join(dir, entry.name) });\n }\n return found;\n}\n\n/** Two-tier merged listing (project wins), newest approval first. */\nexport function listRecipes({ projectDir, workflow }) {\n const merged = new Map();\n for (const recipe of scanRecipesDir(userRecipesDir(), \"user\")) merged.set(recipe.name, recipe);\n for (const recipe of scanRecipesDir(projectRecipesDir(resolve(projectDir)), \"project\")) {\n merged.set(recipe.name, recipe);\n }\n let list = [...merged.values()];\n if (workflow) list = list.filter((r) => r.workflow === workflow);\n return list.sort((a, b) =>\n String(b.approved_at ?? \"\").localeCompare(String(a.approved_at ?? \"\")),\n );\n}\n\n/**\n * Adopt a recipe into the current project: import the folder from the user\n * tier when the project doesn't have it, copy its frame.md over the project's,\n * and hand back the values + the skeleton path for the storyboard draft.\n */\nexport function useRecipe({ projectDir, name }) {\n const slug = slugifyRecipeName(name);\n const root = resolve(projectDir);\n let dir = join(projectRecipesDir(root), slug);\n\n if (!readRecipeJson(dir)) {\n const userDir = join(userRecipesDir(), slug);\n if (!readRecipeJson(userDir)) {\n const known = listRecipes({ projectDir: root }).map((r) => r.name);\n throw new Error(\n `no recipe named \"${slug}\"${known.length ? ` (known: ${known.join(\", \")})` : \"\"}`,\n );\n }\n mkdirSync(dir, { recursive: true });\n cpSync(userDir, dir, NON_ASCII_SAFE_DIR_COPY);\n const imported = readRecipeJson(dir);\n appendRecord(root, {\n id: nextId(root, \"recipe\"),\n type: \"recipe\",\n path: `.media/recipes/${slug}/recipe.json`,\n entity: slug,\n description: `recipe: ${slug} (${imported.workflow}, v${imported.version})`,\n provenance: { provider: \"recipe.local\", imported_from: \"user-tier\" },\n });\n regenerateIndex(root);\n }\n\n const recipe = readRecipeJson(dir);\n cpSync(join(dir, \"frame.md\"), join(root, \"frame.md\"));\n return {\n recipe,\n dir,\n frameSpecPath: \"frame.md\",\n skeletonPath: `.media/recipes/${slug}/storyboard-skeleton.md`,\n // Recipes frozen before BRIEF.md existed have no brief skeleton — degrade.\n briefSkeletonPath: existsSync(join(dir, \"brief-skeleton.md\"))\n ? `.media/recipes/${slug}/brief-skeleton.md`\n : undefined,\n };\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":13287,"content_sha256":"6d2786c2ba4959178351047c3b6d1d2b29a701685c9b256fcc4793c50717ce83"},{"filename":"scripts/lib/telemetry.mjs","content":"// Usage tracking shares the CLI and Studio identity. Properties stay coarse and\n// never carry intent text, file names, or paths.\n\nimport { createHash, randomUUID } from \"node:crypto\";\nimport * as fs from \"node:fs\";\nimport { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport { dirname, join } from \"node:path\";\nimport { withFileLock } from \"./config-lock.mjs\";\nimport { globalMediaDir } from \"./media-home.mjs\";\n\nconst POSTHOG_API_KEY = \"phc_zjjbX0PnWxERXrMHhkEJWj9A9BhGVLRReICgsfTMmpx\";\nconst POSTHOG_HOST = \"https://us.i.posthog.com\";\nconst TIMEOUT_MS = 1500;\nlet identifiedAccount = false;\nlet warnedNonDefaultHost = false;\n\nfunction isTestOrCiContext() {\n return (\n process.env.CI === \"true\" ||\n process.env.CI === \"1\" ||\n process.env.NODE_ENV === \"test\" ||\n process.env.NODE_ENV === \"development\"\n );\n}\n\nfunction posthogHost() {\n const override = process.env.MEDIA_USE_TELEMETRY_HOST;\n if (override && !warnedNonDefaultHost && !isTestOrCiContext()) {\n warnedNonDefaultHost = true;\n console.error(\n `media-use: telemetry is redirected to a non-default host via MEDIA_USE_TELEMETRY_HOST (${override}) — unset it unless this is intentional.`,\n );\n }\n return override || POSTHOG_HOST;\n}\n\n/** True when telemetry must NOT be sent (opt-out envs, CI, dev, shared config). */\nexport function optedOut() {\n return (\n // `hyperframes telemetry disable` writes telemetryEnabled: false to the\n // shared config; one opt-out must cover the CLI and the media-use scripts.\n readSharedConfig().telemetryEnabled === false ||\n process.env.HYPERFRAMES_NO_TELEMETRY === \"1\" ||\n process.env.DO_NOT_TRACK === \"1\" ||\n process.env.CI === \"true\" ||\n process.env.CI === \"1\" ||\n process.env.NODE_ENV === \"development\"\n );\n}\n\n// Read and write the shared config so media-use keeps one identity per install.\nfunction sharedConfigPath() {\n return join(homedir(), \".hyperframes\", \"config.json\");\n}\n\nfunction readSharedConfig() {\n try {\n const file = sharedConfigPath();\n if (existsSync(file)) {\n const parsed = JSON.parse(readFileSync(file, \"utf8\"));\n if (parsed && typeof parsed === \"object\" && !Array.isArray(parsed)) return parsed;\n }\n } catch {\n // unreadable config → treat as empty; never throw\n }\n return {};\n}\n\n// Best effort: skipped when the lock cannot be taken or the file cannot be read, never written unlocked.\nfunction updateSharedConfig(patch) {\n const file = sharedConfigPath();\n mkdirSync(dirname(file), { recursive: true });\n try {\n withFileLock(`${file}.lock`, fs, () => {\n let config = {};\n try {\n config = JSON.parse(readFileSync(file, \"utf8\"));\n } catch (error) {\n if (error.code !== \"ENOENT\") return;\n }\n if (!config || typeof config !== \"object\" || Array.isArray(config)) return;\n const tmp = `${file}.${process.pid}.tmp`;\n writeFileSync(tmp, JSON.stringify({ ...config, ...patch }, null, 2) + \"\\n\", { mode: 0o600 });\n renameSync(tmp, file);\n });\n } catch {}\n}\n\n// Adopt a pre-existing media-use-only id (~/.media/anon-id from before this\n// change) so upgraders keep their PostHog persona instead of resetting to a new\n// one — otherwise cross-surface continuity would start over on upgrade.\nfunction legacyMediaAnonId() {\n try {\n const file = join(globalMediaDir(), \"anon-id\");\n if (existsSync(file)) {\n const id = readFileSync(file, \"utf8\").trim();\n if (id) return id;\n }\n } catch {\n // ignore\n }\n return null;\n}\n\n// Stable per-machine id from the shared config; seeds it (adopting a legacy\n// media-use id when present) if absent.\nfunction anonymousId() {\n try {\n const config = readSharedConfig();\n if (typeof config.anonymousId === \"string\" && config.anonymousId.trim()) {\n return config.anonymousId.trim();\n }\n const id = legacyMediaAnonId() || randomUUID();\n updateSharedConfig({ anonymousId: id });\n return id;\n } catch {\n return \"anon\"; // best-effort; a shared bucket is fine if the fs is read-only\n }\n}\n\n// The HyperFrames user id for a HeyGen username: the same sha256-derived UUID\n// the CLI (auth/telemetryIdentity.ts), web app and Desktop key PostHog on.\nconst UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n\nexport function heygenUserId(username) {\n if (UUID_PATTERN.test(username)) return username;\n const hash = createHash(\"sha256\").update(username).digest();\n hash[6] = (hash[6] & 0x0f) | 0x50;\n hash[8] = (hash[8] & 0x3f) | 0x80;\n const hex = hash.toString(\"hex\");\n return [\n hex.slice(0, 8),\n hex.slice(8, 12),\n hex.slice(12, 16),\n hex.slice(16, 20),\n hex.slice(20, 32),\n ].join(\"-\");\n}\n\n// The signed-in HeyGen account, keyed like the CLI's own identify call: the\n// username's user id, else the lowercased email (lowercased so different stored\n// casing never splits one person). `heygen_username` is the cross-project join\n// column for the Snowflake event table.\nfunction heygenAccount() {\n const root = process.env.HYPERFRAMES_CONFIG_DIR || join(homedir(), \".hyperframes\");\n const file = join(root, ...(process.env.HYPERFRAMES_ENV === \"dev\" ? [\"dev\"] : []), \"credentials\");\n try {\n if (!existsSync(file)) return null;\n const raw = readFileSync(file, \"utf8\").trim();\n if (!raw.startsWith(\"{\")) return null;\n const parsed = JSON.parse(raw);\n if (!parsed || typeof parsed !== \"object\" || Array.isArray(parsed)) return null;\n if (!parsed.api_key && !parsed.oauth) return null;\n const user = parsed.user;\n if (!user || typeof user !== \"object\" || Array.isArray(user)) return null;\n const email =\n typeof user.email === \"string\" && user.email.trim() ? user.email.trim().toLowerCase() : null;\n const username =\n typeof user.username === \"string\" && user.username.trim() ? user.username : null;\n const traits = {};\n if (email) traits.email = email;\n if (username) traits.heygen_username = username;\n if (username) return { distinctId: heygenUserId(username), traits };\n if (email) return { distinctId: email, traits };\n return null;\n } catch {\n return null;\n }\n}\n\nfunction showTelemetryNotice() {\n if (optedOut()) return;\n try {\n const config = readSharedConfig();\n // Shared with the CLI (config.telemetryNoticeShown): shown once per person\n // across surfaces, not once per tool.\n if (config.telemetryNoticeShown === true) return;\n console.error(\n [\n \"media-use sends usage telemetry: media type, resolution source, and provider; never intent text, file names, or paths.\",\n \"If you sign in to HeyGen, usage links to your account (email and username). Opt out with HYPERFRAMES_NO_TELEMETRY=1 or DO_NOT_TRACK=1.\",\n ].join(\"\\n\"),\n );\n updateSharedConfig({ telemetryNoticeShown: true });\n } catch {\n // notice is best-effort; never surface into the command\n }\n}\n\nasync function postBatch(batch) {\n try {\n await fetch(`${posthogHost()}/batch/`, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\", Connection: \"close\" },\n body: JSON.stringify({ api_key: POSTHOG_API_KEY, batch }),\n signal: AbortSignal.timeout(TIMEOUT_MS),\n });\n } catch {\n // telemetry is best-effort; never surface into the command\n }\n}\n\nasync function postEvent(event, properties, distinctId) {\n await postBatch([\n {\n event,\n properties: { ...properties, surface: \"media-use\", $ip: null },\n distinct_id: distinctId,\n timestamp: new Date().toISOString(),\n },\n ]);\n}\n\nasync function identifyAccount(anonId, account) {\n if (optedOut() || identifiedAccount || !account) return;\n identifiedAccount = true;\n await postEvent(\n \"$identify\",\n { $anon_distinct_id: anonId, $set: account.traits },\n account.distinctId,\n );\n}\n\n/**\n * Fire-and-forget a single event to PostHog. Best-effort: awaited with a short\n * timeout so a short-lived script flushes before exit, but any failure (offline,\n * opted out) is swallowed. `properties` must be non-PII (no intent/paths).\n */\nexport async function track(event, properties = {}) {\n if (optedOut()) return;\n showTelemetryNotice();\n const anonId = anonymousId();\n const account = heygenAccount();\n await identifyAccount(anonId, account);\n const username = account?.traits.heygen_username;\n if (!username) return postEvent(event, properties, anonId);\n await postEvent(event, { ...properties, heygen_username: username }, heygenUserId(username));\n}\n\nexport function __anonymousIdForTest() {\n return anonymousId();\n}\n\nexport function __resetTelemetryForTest() {\n identifiedAccount = false;\n warnedNonDefaultHost = false;\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":8693,"content_sha256":"3524441159efd13de22ced004c9e40fe0c241c5ef64cc047f0b567310d6436f0"},{"filename":"scripts/lib/telemetry.test.mjs","content":"import assert from \"node:assert/strict\";\nimport { mkdirSync, mkdtempSync, rmSync, writeFileSync } from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { dirname, join } from \"node:path\";\nimport { test } from \"node:test\";\nimport { optedOut } from \"./telemetry.mjs\";\n\n// optedOut() reads ~/.hyperframes/config.json and env vars. Point HOME at a temp\n// dir so the run never touches the real config, and pin the env opt-outs to a\n// neutral state; restore both afterwards.\nconst ENV_KEYS = [\n \"HOME\",\n \"USERPROFILE\",\n \"HYPERFRAMES_NO_TELEMETRY\",\n \"DO_NOT_TRACK\",\n \"CI\",\n \"NODE_ENV\",\n];\nconst savedEnv = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));\nconst home = mkdtempSync(join(tmpdir(), \"mu-telemetry-\"));\nconst configPath = join(home, \".hyperframes\", \"config.json\");\n\nfunction writeConfig(contents) {\n if (contents === null) {\n rmSync(configPath, { force: true });\n } else {\n mkdirSync(dirname(configPath), { recursive: true });\n writeFileSync(configPath, contents);\n }\n}\n\ntest.before(() => {\n for (const key of ENV_KEYS) delete process.env[key];\n process.env.HOME = process.env.USERPROFILE = home;\n});\n\ntest.after(() => {\n for (const key of ENV_KEYS) {\n if (savedEnv[key] === undefined) delete process.env[key];\n else process.env[key] = savedEnv[key];\n }\n rmSync(home, { recursive: true, force: true });\n});\n\ntest(\"optedOut is false with no config and no opt-out env\", () => {\n writeConfig(null);\n assert.equal(optedOut(), false);\n});\n\ntest(\"optedOut honors telemetryEnabled: false from the shared config\", () => {\n writeConfig(JSON.stringify({ telemetryEnabled: false }));\n assert.equal(optedOut(), true);\n});\n\ntest(\"optedOut is false when the shared config enables telemetry\", () => {\n writeConfig(JSON.stringify({ telemetryEnabled: true }));\n assert.equal(optedOut(), false);\n});\n\ntest(\"optedOut treats an unreadable shared config as no opt-out\", () => {\n writeConfig(\"{not json\");\n assert.equal(optedOut(), false);\n});\n\ntest(\"optedOut still honors the env opt-outs\", () => {\n writeConfig(JSON.stringify({ telemetryEnabled: true }));\n process.env.DO_NOT_TRACK = \"1\";\n try {\n assert.equal(optedOut(), true);\n } finally {\n delete process.env.DO_NOT_TRACK;\n }\n});\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":2233,"content_sha256":"b7f6513eede2eb33f6fde626162b2fd4ef74b0034a3e81b9eebdede89f766373"},{"filename":"scripts/lib/transcriptCutFade.mjs","content":"function round3(n) {\n return Math.round(Number(n) * 1000) / 1000;\n}\n\n// 30ms in/out ramps kill the click at every concat boundary. A segment shorter\n// than 4x the ramp would spend its whole length fading, so scale down there and\n// skip entirely on a degenerate one. fadeIn/fadeOut are false at the export's\n// own true start/end, where there is no splice to smooth.\nexport function fadeFilterFor(durationSeconds, { fadeIn, fadeOut }) {\n if (!fadeIn && !fadeOut) return null;\n const FADE_SECONDS = 0.03;\n if (!Number.isFinite(durationSeconds) || durationSeconds \u003c= 0.01) return null;\n const d = Math.min(FADE_SECONDS, durationSeconds / 4);\n const parts = [];\n if (fadeIn) parts.push(`afade=t=in:st=0:d=${round3(d)}`);\n if (fadeOut) {\n const out = round3(durationSeconds - d);\n if (out > 0) parts.push(`afade=t=out:st=${out}:d=${round3(d)}`);\n }\n return parts.length ? parts.join(\",\") : null;\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":911,"content_sha256":"ee9c7ec28650cf0f6a0f1f21f1c6a1faa5e152337163cccc0cc9a109b3c99805"},{"filename":"scripts/lib/words.mjs","content":"export function normalizeWords(input) {\n const raw = Array.isArray(input) ? input : Array.isArray(input?.words) ? input.words : [];\n return raw\n .map((w, index) => {\n const text = String(w?.text ?? w?.word ?? \"\").trim();\n const start = Number(w?.start);\n const end = Number(w?.end);\n if (!text || !Number.isFinite(start) || !Number.isFinite(end)) return null;\n return { id: w?.id ?? `w${index}`, text, start, end };\n })\n .filter(Boolean);\n}\n\nexport function wordListsFromMediaMeta(input) {\n if (Array.isArray(input) || Array.isArray(input?.words)) return [normalizeWords(input)];\n if (!Array.isArray(input?.voices)) return [];\n return input.voices.map((voice) => normalizeWords(voice));\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":728,"content_sha256":"bfc1f93523d2fc8ce55580b262efcca537c7feabaf029c1c6f33433591377adb"},{"filename":"scripts/prefs.mjs","content":"#!/usr/bin/env node\n/**\n * Remembered defaults CLI — the lightweight tier of HyperFrames user memory.\n *\n * node prefs.mjs get --hyperframes . [--json]\n * Print the merged view (project `.media/preferences.json` over user\n * `~/.media/preferences.json`), each key with its source and the receipt\n * material (confirmed_in, updated_at).\n *\n * node prefs.mjs record --hyperframes . --key destination --value x-feed [--workflow \u003cw>]\n * Record one confirmed brief answer into the project tier; the same value\n * confirmed in two different projects promotes the key to the user tier.\n *\n * Consumption rule (references/memory.md): a remembered value becomes the\n * recommended option with a receipt — it never skips a question.\n */\nimport { parseArgs } from \"node:util\";\nimport { mergedPreferences, recordPreference } from \"./lib/prefs-store.mjs\";\n\nconst { values: args, positionals } = parseArgs({\n options: {\n hyperframes: { type: \"string\", default: \".\" },\n key: { type: \"string\" },\n value: { type: \"string\" },\n workflow: { type: \"string\" },\n json: { type: \"boolean\", default: false },\n },\n allowPositionals: true,\n});\n\nconst verb = positionals[0];\n\nfunction fail(message) {\n console.error(message);\n process.exit(1);\n}\n\nif (verb === \"get\") {\n const merged = mergedPreferences(args.hyperframes);\n if (args.json) {\n console.log(JSON.stringify(merged, null, 2));\n } else if (Object.keys(merged).length === 0) {\n console.log(\"no remembered preferences yet\");\n } else {\n for (const [key, entry] of Object.entries(merged)) {\n console.log(\n `${key} = ${entry.value} (${entry.source}; confirmed in ${entry.confirmed_in.join(\", \")})`,\n );\n }\n }\n} else if (verb === \"record\") {\n if (!args.key || !args.value) fail(\"record needs --key and --value\");\n try {\n const result = recordPreference({\n projectDir: args.hyperframes,\n key: args.key,\n value: args.value,\n workflow: args.workflow,\n });\n const promotion = result.promoted ? \"; promoted to user tier\" : \"\";\n console.log(`recorded ${result.key} = ${result.value} (project${promotion})`);\n } catch (err) {\n fail(err instanceof Error ? err.message : String(err));\n }\n} else {\n fail(\n \"usage: prefs.mjs \u003cget|record> --hyperframes . [--key \u003ck> --value \u003cv> --workflow \u003cw>] [--json]\",\n );\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":2350,"content_sha256":"f551d5efe51dea7b59d37595c052b950111c6734d913567630181959e7497a04"},{"filename":"scripts/recipe.mjs","content":"#!/usr/bin/env node\n/**\n * Recipes CLI — the heavyweight tier of HyperFrames user memory.\n *\n * node recipe.mjs freeze --hyperframes . --name \u003cn> [--workflow \u003cw>] [--blocks a,b,c]\n * Freeze the current approved run as a named recipe: frame.md + the\n * storyboard skeleton (structure kept, content blanked) + the brief\n * skeleton (when BRIEF.md exists) + the confirmed brief values.\n * The workflow is read from BRIEF.md; --workflow only covers projects\n * briefed before BRIEF.md existed. Re-freezing the same name bumps the\n * version and archives the old folder as \u003cname>@v\u003cN>. Promotes to\n * ~/.media/recipes/ immediately.\n *\n * node recipe.mjs list --hyperframes . [--workflow \u003cw>] [--json]\n * Two-tier merged listing (project wins), newest approval first.\n *\n * node recipe.mjs use --hyperframes . --name \u003cn> [--json]\n * Adopt a recipe: import it from the user tier if needed, copy its\n * frame.md over the project's, and print the brief values + skeleton path.\n *\n * When recipes are offered and consumed: references/memory.md.\n */\nimport { parseArgs } from \"node:util\";\nimport { freezeRecipe, listRecipes, useRecipe } from \"./lib/recipe-store.mjs\";\n\nconst { values: args, positionals } = parseArgs({\n options: {\n hyperframes: { type: \"string\", default: \".\" },\n name: { type: \"string\" },\n workflow: { type: \"string\" },\n blocks: { type: \"string\" },\n json: { type: \"boolean\", default: false },\n },\n allowPositionals: true,\n});\n\nconst verb = positionals[0];\n\nfunction fail(message) {\n console.error(message);\n process.exit(1);\n}\n\ntry {\n if (verb === \"freeze\") {\n if (!args.name) fail(\"freeze needs --name\");\n const frozen = freezeRecipe({\n projectDir: args.hyperframes,\n name: args.name,\n workflow: args.workflow,\n blocks: args.blocks\n ? args.blocks\n .split(\",\")\n .map((b) => b.trim())\n .filter(Boolean)\n : undefined,\n });\n if (args.json) console.log(JSON.stringify({ ok: true, ...frozen }));\n else {\n console.log(\n `froze recipe ${frozen.slug} (v${frozen.version}, ${frozen.workflow}) → ${frozen.dir}`,\n );\n if (frozen.workflowOverridden)\n console.log(` (BRIEF.md says \"${frozen.workflow}\" — the --workflow flag was ignored)`);\n if (!frozen.briefSkeleton)\n console.log(\" (no BRIEF.md in the project — brief skeleton skipped)\");\n }\n } else if (verb === \"list\") {\n const list = listRecipes({ projectDir: args.hyperframes, workflow: args.workflow });\n if (args.json) console.log(JSON.stringify(list));\n else if (list.length === 0) console.log(\"no recipes yet\");\n else {\n for (const r of list) {\n console.log(\n `${r.name} v${r.version} ${r.workflow} (${r.source}; approved ${String(r.approved_at ?? \"?\").slice(0, 10)})`,\n );\n }\n }\n } else if (verb === \"use\") {\n if (!args.name) fail(\"use needs --name\");\n const used = useRecipe({ projectDir: args.hyperframes, name: args.name });\n if (args.json) console.log(JSON.stringify({ ok: true, ...used }));\n else {\n console.log(\n `using recipe ${used.recipe.name} (v${used.recipe.version}, ${used.recipe.workflow})`,\n );\n console.log(` frame spec → ${used.frameSpecPath} (copied over)`);\n console.log(` storyboard skeleton → ${used.skeletonPath}`);\n if (used.briefSkeletonPath) console.log(` brief skeleton → ${used.briefSkeletonPath}`);\n for (const key of [\"destination\", \"aspect\", \"language\", \"voice\", \"style_preset\"]) {\n if (used.recipe[key]) console.log(` ${key}: ${used.recipe[key]}`);\n }\n }\n } else {\n fail(\n \"usage: recipe.mjs \u003cfreeze|list|use> --hyperframes . [--name \u003cn>] [--workflow \u003cw>] [--blocks a,b] [--json]\",\n );\n }\n} catch (err) {\n fail(err instanceof Error ? err.message : String(err));\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":3892,"content_sha256":"97d2a12604084668599c44f235d6300b77593f86a9a58a6034cf5aa92c98fcba"},{"filename":"scripts/resolve-plugin.test.mjs","content":"import assert from \"node:assert/strict\";\nimport { spawnSync } from \"node:child_process\";\nimport { copyFileSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from \"node:fs\";\nimport { delimiter, join } from \"node:path\";\nimport { tmpdir } from \"node:os\";\nimport { fileURLToPath } from \"node:url\";\nimport { test } from \"node:test\";\n\ntest(\n \"plugin resolver uses the release CLI without a repository checkout\",\n { skip: process.platform === \"win32\" },\n (t) => {\n const dir = mkdtempSync(join(tmpdir(), \"hf-resolve-plugin-\"));\n t.after(() => rmSync(dir, { recursive: true, force: true }));\n mkdirSync(join(dir, \"lib\"));\n for (const file of [\"resolve.mjs\", \"lib/npx-sync.mjs\"]) {\n copyFileSync(fileURLToPath(new URL(file, import.meta.url)), join(dir, file));\n }\n writeFileSync(\n join(dir, \"npx\"),\n `#!${process.execPath}\\nconsole.log(JSON.stringify({args:process.argv.slice(2),skip:process.env.HYPERFRAMES_SKIP_SKILLS}));process.exit(7);`,\n { mode: 0o755 },\n );\n const result = spawnSync(process.execPath, [join(dir, \"resolve.mjs\"), \"--intent\", \"a & b\"], {\n cwd: dir,\n encoding: \"utf8\",\n env: {\n ...process.env,\n PATH: `${dir}${delimiter}${process.env.PATH}`,\n HYPERFRAMES_PLUGIN_VERSION: \"1.2.3\",\n HYPERFRAMES_SKIP_SKILLS: \"1\",\n },\n });\n assert.equal(result.status, 7, result.stderr);\n assert.deepEqual(JSON.parse(result.stdout), {\n args: [\"--yes\", \"[email protected]\", \"media-use\", \"resolve\", \"--intent\", \"a & b\"],\n skip: \"1\",\n });\n },\n);\n\ntest(\"helper package override keeps a contributor's local CLI\", (t) => {\n const root = mkdtempSync(join(tmpdir(), \"hf-resolve-local-\"));\n t.after(() => rmSync(root, { recursive: true, force: true }));\n const scripts = join(root, \"skills/media-use/scripts\");\n mkdirSync(join(scripts, \"lib\"), { recursive: true });\n mkdirSync(join(root, \"packages/cli/dist\"), { recursive: true });\n for (const file of [\"resolve.mjs\", \"lib/npx-sync.mjs\"]) {\n copyFileSync(fileURLToPath(new URL(file, import.meta.url)), join(scripts, file));\n }\n writeFileSync(join(root, \"packages/cli/dist/cli.js\"), 'console.log(\"local-cli\");');\n const result = spawnSync(process.execPath, [join(scripts, \"resolve.mjs\")], {\n encoding: \"utf8\",\n env: {\n ...process.env,\n HYPERFRAMES_PLUGIN_VERSION: \"\",\n HYPERFRAMES_SKILL_PKG_VERSION: \"0.8.79\",\n },\n });\n assert.equal(result.status, 0, result.stderr);\n assert.equal(result.stdout.trim(), \"local-cli\");\n});\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":2512,"content_sha256":"fe8f4dce139b3a88e9ba817da335ae7667a644a715f250613901f7cc1e75f0ed"},{"filename":"scripts/resolve.mjs","content":"#!/usr/bin/env node\nimport { spawnSync } from \"node:child_process\";\nimport { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { resolveNpxInvocation } from \"./lib/npx-sync.mjs\";\n\n// Installed plugins have no monorepo packages/ tree. The plugin launcher passes\n// the release version and suppression environment through to this legacy shim.\nconst pluginVersion = process.env.HYPERFRAMES_PLUGIN_VERSION;\nif (pluginVersion) {\n const invocation = resolveNpxInvocation(\n [\"--yes\", `hyperframes@${pluginVersion}`, \"media-use\", \"resolve\", ...process.argv.slice(2)],\n { stdio: \"inherit\" },\n );\n const result = spawnSync(invocation.cmd, invocation.args, invocation.opts);\n if (result.error) console.error(result.error.message);\n process.exit(result.status ?? 1);\n}\nconst root = join(fileURLToPath(new URL(\"../../../\", import.meta.url)));\nconst dist = join(root, \"packages/cli/dist/cli.js\");\nconst result = existsSync(dist)\n ? spawnSync(process.execPath, [dist, \"media-use\", \"resolve\", ...process.argv.slice(2)], {\n stdio: \"inherit\",\n })\n : spawnSync(\n \"bun\",\n [join(root, \"packages/cli/src/cli.ts\"), \"media-use\", \"resolve\", ...process.argv.slice(2)],\n { stdio: \"inherit\" },\n );\nprocess.exit(result.status ?? 1);\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":1305,"content_sha256":"85aec401d22b65639fa6a91056e515563135962a127516aaae1e2644d48fa0b9"},{"filename":"scripts/transcribe.mjs","content":"#!/usr/bin/env node\n\nimport { execFileSync } from \"node:child_process\";\nimport {\n existsSync,\n readFileSync,\n writeFileSync,\n copyFileSync,\n renameSync,\n mkdtempSync,\n rmSync,\n} from \"node:fs\";\nimport { homedir, tmpdir } from \"node:os\";\nimport { basename, extname, join, resolve } from \"node:path\";\nimport { parseArgs, stripVTControlCharacters } from \"node:util\";\nimport { mergeTokensToWords } from \"./lib/parakeet-words.mjs\";\nimport { track } from \"./lib/telemetry.mjs\";\nimport { resolveNpxInvocation } from \"./lib/npx-sync.mjs\";\n\n// The DEFAULT local transcription path. Prefers NVIDIA Parakeet-TDT via\n// parakeet-mlx, which beats whisper.cpp on the Open ASR Leaderboard (~6.05% vs\n// 7.44% avg WER, and 4.73% vs 5.96% on noisy test-other) and is 5-10x faster\n// with native punctuation. Emits { text, words:[{text,start,end}] } (word\n// timestamps merged from Parakeet's sub-word tokens) for transcript-cut /\n// captions / the audio engine.\n//\n// Parakeet v3 covers English + 25 European languages. For other languages, or\n// when parakeet-mlx is not installed, it falls back to whisper.cpp via\n// `hyperframes transcribe` (99 languages; the CLI resolves/builds whisper.cpp\n// on first use — it is not bundled). `--engine` forces one.\n\nconst { values: args } = parseArgs({\n options: {\n input: { type: \"string\", short: \"i\" },\n out: { type: \"string\", short: \"o\" },\n engine: { type: \"string\", default: \"auto\" }, // auto | parakeet | whisper\n model: { type: \"string\", default: \"mlx-community/parakeet-tdt-0.6b-v3\" },\n json: { type: \"boolean\", default: false },\n help: { type: \"boolean\", short: \"h\", default: false },\n },\n strict: true,\n});\n\nif (args.help) {\n console.log(`media-use transcribe: better-than-whisper local ASR (Parakeet), whisper.cpp fallback\n\nUsage:\n node transcribe.mjs --input audio.wav [--out audio.transcribe.json] [--engine auto|parakeet|whisper]\n\nParakeet (default) beats whisper.cpp on accuracy + speed for English/European\nlanguages; whisper.cpp (99 languages) is the fallback. Install Parakeet once:\n npx hyperframes models install parakeet (macOS, Windows, Linux with glibc 2.32+)\n uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx (Apple Silicon)`);\n process.exit(0);\n}\n\nif (!args.input) {\n console.error(\"error: --input is required\");\n process.exit(2);\n}\nconst inputPath = resolve(args.input);\nif (!existsSync(inputPath)) {\n console.error(`error: input not found: ${inputPath}`);\n process.exit(2);\n}\nconst outPath = resolve(\n args.out || `${inputPath.slice(0, -extname(inputPath).length)}.transcribe.json`,\n);\n\n// Locate the parakeet-mlx runner the same way the CLI does: env override, then\n// the documented ~/.venvs/parakeet install, then PATH. Checking the venv (not\n// just PATH) is what keeps a user who followed the install docs verbatim from\n// silently falling through to whisper. Returns the runner path, or null.\nfunction resolveParakeet() {\n for (const p of [\n process.env.HYPERFRAMES_PARAKEET,\n join(homedir(), \".venvs\", \"parakeet\", \"bin\", \"parakeet-mlx\"),\n ]) {\n if (p && existsSync(p)) return p;\n }\n try {\n execFileSync(\"parakeet-mlx\", [\"--help\"], {\n stdio: [\"ignore\", \"ignore\", \"ignore\"],\n timeout: 20000,\n });\n return \"parakeet-mlx\";\n } catch {\n return null;\n }\n}\n\n// Write via a sibling temp + atomic rename so a SIGKILL mid-write can't leave a\n// truncated transcript at outPath (downstream reads it as valid JSON).\nfunction atomicWrite(target, data) {\n const tmp = `${target}.tmp-${process.pid}`;\n writeFileSync(tmp, data);\n renameSync(tmp, target);\n}\n\nfunction report(engine, wordCount) {\n if (args.json) console.log(JSON.stringify({ ok: true, out: outPath, engine, words: wordCount }));\n else\n console.log(\n `transcribed ${basename(inputPath)} -> ${outPath}${wordCount != null ? ` (${wordCount} words,` : \" (\"}${engine})`,\n );\n}\n\nfunction runParakeet(runner) {\n const workDir = mkdtempSync(join(tmpdir(), \"media-use-asr-\"));\n try {\n execFileSync(\n runner,\n [inputPath, \"--model\", args.model, \"--output-format\", \"json\", \"--output-dir\", workDir],\n { stdio: [\"ignore\", \"pipe\", \"pipe\"], timeout: 1_800_000 },\n );\n const jsonPath = join(workDir, `${basename(inputPath, extname(inputPath))}.json`);\n if (!existsSync(jsonPath)) throw new Error(\"parakeet produced no JSON\");\n const merged = mergeTokensToWords(JSON.parse(readFileSync(jsonPath, \"utf8\")));\n atomicWrite(outPath, JSON.stringify(merged, null, 2));\n report(\"parakeet\", merged.words.length);\n } finally {\n rmSync(workDir, { recursive: true, force: true });\n }\n}\n\n// The hyperframes CLI (its Parakeet, else whisper.cpp built on first use — see\n// SKILL.md): writes transcript.json into --dir; relocate to --out.\nfunction runCli(cliEngine) {\n const workDir = mkdtempSync(join(tmpdir(), \"media-use-whisper-\"));\n try {\n // On Windows a bare \"npx\" is npx.cmd, which execFileSync cannot exec\n // (spawnSync npx ENOENT) — resolveNpxInvocation reroutes it through\n // node + npx-cli.js (and throws actionably when it can't), same\n // mechanism as the audio engine's TTS spawns.\n // Under auto or parakeet the CLI may run its own Parakeet; --json says which engine ran.\n const resolved = resolveNpxInvocation(\n [\"hyperframes\", \"transcribe\", inputPath, \"--dir\", workDir, \"--engine\", cliEngine, \"--json\"],\n { stdio: [\"ignore\", \"pipe\", \"pipe\"], timeout: 1_800_000 },\n );\n let stdout;\n try {\n stdout = String(execFileSync(resolved.cmd, resolved.args, resolved.opts));\n } catch (e) {\n // stderr holds spinner redraws and --json prints the reason on stdout, so keep the last lines.\n const tail = stripVTControlCharacters(`${e.stderr ?? \"\"}\\n${e.stdout ?? \"\"}`)\n .split(/[\\r\\n]+/)\n .map((l) => l.trim())\n .filter((l) => l && l !== \"│\")\n .slice(-3)\n .join(\"\\n\");\n throw new Error(\n `hyperframes transcribe failed (exit ${e.status ?? e.code})${tail ? `:\\n${tail}` : \"\"}`,\n );\n }\n const produced = join(workDir, \"transcript.json\");\n if (!existsSync(produced))\n throw new Error(\"hyperframes transcribe produced no transcript.json\");\n const tmp = `${outPath}.tmp-${process.pid}`;\n copyFileSync(produced, tmp);\n renameSync(tmp, outPath); // atomic publish\n let words;\n try {\n const t = JSON.parse(readFileSync(outPath, \"utf8\"));\n // The CLI writes a flat word array, not { words }.\n words = Array.isArray(t) ? t.length : undefined;\n } catch {\n /* leave undefined */\n }\n let ran = \"whisper\";\n try {\n ran = JSON.parse(stdout.trim().split(\"\\n\").at(-1)).engine === \"parakeet\" ? \"parakeet\" : ran;\n } catch {\n /* no JSON line: keep whisper */\n }\n report(ran, words);\n return ran;\n } finally {\n rmSync(workDir, { recursive: true, force: true });\n }\n}\n\ntry {\n const parakeetBin = resolveParakeet();\n const asked = args.engine === \"parakeet\" || args.engine === \"whisper\" ? args.engine : \"auto\";\n // Without parakeet-mlx, the CLI's own Parakeet (any OS, `hyperframes models install parakeet`).\n let engine = \"parakeet\";\n if (asked !== \"whisper\" && parakeetBin) runParakeet(parakeetBin);\n else engine = runCli(asked);\n await track(\"media_use_transcribe\", { engine });\n} catch (err) {\n if (args.json) console.log(JSON.stringify({ ok: false, error: err.message }));\n else console.error(`error: transcription failed: ${err.message}`);\n process.exit(1);\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":7510,"content_sha256":"9e0f2fd2775e3a76267fc219d4b5aa52373a95478812884f8f40f6292e09dac7"},{"filename":"scripts/transcribe.test.mjs","content":"import assert from \"node:assert/strict\";\nimport { execFileSync, spawnSync } from \"node:child_process\";\nimport { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport test from \"node:test\";\nimport { fileURLToPath } from \"node:url\";\n\n// The stub stands in for `npx hyperframes transcribe \u003cin> --dir \u003cdir> ...`: it records its args,\n// writes the CLI's flat array and prints the CLI's --json line naming `cliEngine`.\nfunction runScript(engine, cliEngine) {\n const root = mkdtempSync(join(tmpdir(), \"media-use-transcribe-\"));\n try {\n const bin = join(root, \"bin\");\n mkdirSync(bin);\n writeFileSync(\n join(bin, \"npx\"),\n `#!/bin/sh\\necho \"$@\" > \"${root}/args\"\\nwhile [ \"$1\" != \"--dir\" ]; do shift; done\\n` +\n `echo '[{\"text\":\"a\",\"start\":0,\"end\":1},{\"text\":\"b\",\"start\":1,\"end\":2}]' > \"$2/transcript.json\"\\n` +\n `echo '{\"ok\":true,\"engine\":\"${cliEngine}\"}'\\n`,\n );\n chmodSync(join(bin, \"npx\"), 0o755);\n const input = join(root, \"in.wav\");\n writeFileSync(input, \"\");\n const script = fileURLToPath(new URL(\"./transcribe.mjs\", import.meta.url));\n const env = { ...process.env, PATH: `${bin}:${process.env.PATH}`, HOME: root };\n delete env.HYPERFRAMES_PARAKEET;\n const out = execFileSync(\n process.execPath,\n [script, \"--input\", input, \"--engine\", engine, \"--json\"],\n {\n encoding: \"utf8\",\n env: { ...env, HYPERFRAMES_MEDIA_HOME: join(root, \"home\"), HYPERFRAMES_NO_TELEMETRY: \"1\" },\n },\n );\n return { result: JSON.parse(out.trim()), args: readFileSync(join(root, \"args\"), \"utf8\") };\n } finally {\n rmSync(root, { recursive: true, force: true });\n }\n}\n\ntest(\n \"--engine whisper makes the CLI run whisper and reports the flat transcript's word count\",\n { skip: process.platform === \"win32\" },\n () => {\n const { result, args } = runScript(\"whisper\", \"whisper\");\n assert.match(args, /--engine whisper --json/);\n assert.equal(result.words, 2);\n assert.equal(result.engine, \"whisper\");\n },\n);\n\ntest(\n \"auto reports the engine the CLI says it ran, Parakeet included\",\n { skip: process.platform === \"win32\" },\n () => {\n const { result, args } = runScript(\"auto\", \"parakeet\");\n assert.match(args, /--engine auto --json/);\n assert.equal(result.engine, \"parakeet\");\n },\n);\n\ntest(\n \"--engine parakeet without parakeet-mlx asks the CLI for its Parakeet\",\n { skip: process.platform === \"win32\" },\n () => {\n const { result, args } = runScript(\"parakeet\", \"parakeet\");\n assert.match(args, /--engine parakeet --json/);\n assert.equal(result.engine, \"parakeet\");\n },\n);\n\ntest(\n \"a failed --engine parakeet run reports the reason the CLI printed on stdout\",\n { skip: process.platform === \"win32\" },\n () => {\n const root = mkdtempSync(join(tmpdir(), \"media-use-transcribe-\"));\n try {\n const bin = join(root, \"bin\");\n mkdirSync(bin);\n const reason =\n \"Parakeet is not installed. Install it with: hyperframes models install parakeet\";\n writeFileSync(\n join(bin, \"npx\"),\n `#!/bin/sh\\necho '{\"ok\":false,\"error\":\"${reason}\"}'\\nexit 1\\n`,\n );\n chmodSync(join(bin, \"npx\"), 0o755);\n const input = join(root, \"in.wav\");\n writeFileSync(input, \"\");\n const script = fileURLToPath(new URL(\"./transcribe.mjs\", import.meta.url));\n const res = spawnSync(\n process.execPath,\n [script, \"--input\", input, \"--engine\", \"parakeet\", \"--json\"],\n {\n encoding: \"utf8\",\n env: {\n ...process.env,\n HYPERFRAMES_PARAKEET: \"\",\n PATH: `${bin}:${process.env.PATH}`,\n HOME: root,\n HYPERFRAMES_MEDIA_HOME: join(root, \"home\"),\n HYPERFRAMES_NO_TELEMETRY: \"1\",\n },\n },\n );\n assert.equal(res.status, 1);\n assert.match(JSON.parse(res.stdout.trim()).error, /hyperframes models install parakeet/);\n } finally {\n rmSync(root, { recursive: true, force: true });\n }\n },\n);\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":4074,"content_sha256":"39a456ac37a0eca282417b09d7e556c0f2ac11ab3726bc361ff077e75a963ae1"},{"filename":"scripts/transcript-cut.mjs","content":"#!/usr/bin/env node\n\nimport { execFileSync } from \"node:child_process\";\nimport { mkdtempSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { dirname, extname, join, resolve } from \"node:path\";\nimport { parseArgs } from \"node:util\";\nimport { compileCutList } from \"./lib/cutlist.mjs\";\nimport { fadeFilterFor } from \"./lib/transcriptCutFade.mjs\";\nimport { track } from \"./lib/telemetry.mjs\";\n\nconst { values: args } = parseArgs({\n options: {\n input: { type: \"string\" },\n transcript: { type: \"string\" },\n remove: { type: \"string\" },\n \"remove-words\": { type: \"string\" },\n \"remove-fillers\": { type: \"string\" },\n \"cut-silence\": { type: \"string\" },\n keep: { type: \"string\" },\n copy: { type: \"boolean\", default: false },\n plan: { type: \"boolean\", default: false },\n out: { type: \"string\" },\n json: { type: \"boolean\", default: false },\n help: { type: \"boolean\", short: \"h\", default: false },\n },\n strict: true,\n});\n\nif (args.help) {\n console.log(`media-use transcript-cut — compile transcript edits into video cuts\n\nUsage:\n node transcript-cut.mjs --input in.mp4 --transcript transcript.json --remove \"12-15\" --out out.mp4\n\nOptions:\n --input Source video/audio file\n --transcript JSON word transcript, array or { words: [...] }\n --remove Time ranges to remove, seconds: a-b,c-d\n --remove-words Word-index ranges to remove: 12-18,40-41\n --remove-fillers Comma list of filler words to remove\n --cut-silence Remove inter-word gaps longer than this many seconds\n --keep Inverse mode: direct kept ranges, mutually exclusive with removal\n --copy Use stream copy for faster, keyframe-snapped cuts\n --plan Print kept segment JSON and exit without ffmpeg\n --out Output file\n --json Output JSON status\n --help, -h Show this help`);\n process.exit(0);\n}\n\ntry {\n run();\n await track(\"media_use_transcript_cut\", {\n mode: args.plan ? \"plan\" : \"encode\",\n remove_fillers: !!args[\"remove-fillers\"],\n cut_silence: !!args[\"cut-silence\"],\n ranges: !!args.remove,\n keep: !!args.keep,\n });\n} catch (err) {\n if (args.json) console.log(JSON.stringify({ ok: false, error: err.message }));\n else console.error(`error: ${err.message}`);\n process.exit(1);\n}\n\nfunction run() {\n if (!args.transcript) throw new Error(\"--transcript is required\");\n const transcript = JSON.parse(readFileSync(resolve(args.transcript), \"utf8\"));\n const segments = compileCutList(transcript, {\n remove: args.remove,\n removeWords: args[\"remove-words\"],\n removeFillers: args[\"remove-fillers\"],\n cutSilence: args[\"cut-silence\"],\n keep: args.keep,\n });\n\n if (args.plan) {\n console.log(JSON.stringify(segments));\n return;\n }\n\n if (!args.input || !args.out)\n throw new Error(\"--input and --out are required unless --plan is set\");\n if (segments.length === 0) throw new Error(\"cut list has no kept segments\");\n\n const inputPath = resolve(args.input);\n const outPath = resolve(args.out);\n mkdirSync(dirname(outPath), { recursive: true });\n const tmpDir = mkdtempSync(join(tmpdir(), \"media-use-cut-\"));\n const keptSeconds = sumDurations(segments);\n const totalSeconds = probeDuration(inputPath);\n\n try {\n const parts = segments.map((segment, index) => {\n // Intermediates carry PCM audio, not the final codec. Encoding each\n // segment to a lossy codec separately makes the encoder pad every segment\n // with priming silence (~25-35ms for AAC), which concat then bakes in as a\n // gap at each cut -- a defect distinct from, and surviving, the fades\n // below. PCM has no priming, so audio is encoded exactly once, at concat.\n // The video container is .mov, not .mkv: ffmpeg writes Matroska\n // timestamps in whole milliseconds, which moves frames off the source's\n // frame grid, and the concat copy below carries that into the output.\n const ext = args.copy ? extname(outPath) || \".mp4\" : isAudioOnly(outPath) ? \".wav\" : \".mov\";\n const out = join(tmpDir, `segment-${String(index).padStart(4, \"0\")}${ext}`);\n // --copy stays fade-free (stream copy cannot filter). A segment's true\n // start/end (index 0's start, the last segment's end) borders nothing\n // kept, so only an interior splice edge gets a ramp.\n const fade = args.copy\n ? null\n : fadeFilterFor(segment.end - segment.start, {\n fadeIn: index > 0,\n fadeOut: index \u003c segments.length - 1,\n });\n cutSegment(inputPath, segment, out, args.copy, fade);\n return out;\n });\n const listPath = join(tmpDir, \"list.txt\");\n writeFileSync(\n listPath,\n parts.map((part) => `file '${escapeConcatPath(part)}'`).join(\"\\n\") + \"\\n\",\n );\n // Encode to a sibling temp (same extension so ffmpeg picks the right muxer),\n // then atomic-rename so a SIGKILL mid-encode can't leave a truncated outPath.\n const tmpOut = `${outPath}.part${extname(outPath) || \".mp4\"}`;\n // --copy already produced final-codec segments, so concat can stream-copy.\n // Otherwise the PCM intermediates are encoded here, once, for the whole file.\n const concatCodecs = args.copy\n ? [\"-c\", \"copy\"]\n : isAudioOnly(outPath)\n ? encodeArgsFor(extname(outPath).toLowerCase())\n : [\"-c:v\", \"copy\", \"-c:a\", \"aac\", \"-b:a\", \"192k\", \"-movflags\", \"+faststart\"];\n execFileSync(\n \"ffmpeg\",\n [\"-y\", \"-f\", \"concat\", \"-safe\", \"0\", \"-i\", listPath, ...concatCodecs, tmpOut],\n {\n stdio: \"ignore\",\n },\n );\n renameSync(tmpOut, outPath);\n } finally {\n rmSync(tmpDir, { recursive: true, force: true });\n }\n\n // Stream copy can only cut on keyframes; on sparse-keyframe footage the snap\n // can silently swallow the whole cut. Compare, then surface the drift in BOTH\n // the stderr warning (human) and the --json result (pipelines).\n let copyDrift = null;\n if (args.copy) {\n const outSeconds = probeDuration(outPath);\n if (Math.abs(outSeconds - keptSeconds) > 1) {\n copyDrift = { produced_s: round3(outSeconds), expected_s: round3(keptSeconds) };\n if (!args.json) {\n console.error(\n `warning: --copy keyframe snapping produced ${round3(outSeconds)}s instead of ${round3(keptSeconds)}s kept; drop --copy for frame-accurate cuts`,\n );\n }\n }\n }\n\n if (args.json) {\n console.log(\n JSON.stringify({\n ok: true,\n input: inputPath,\n out: outPath,\n segments,\n kept_s: round3(keptSeconds),\n total_s: round3(totalSeconds),\n ...(copyDrift && { copy_drift: copyDrift }),\n }),\n );\n return;\n }\n\n console.log(\n `cut ${inputPath} -> ${outPath} (${segments.length} segments, ${fmt(keptSeconds)}s kept of ${fmt(\n totalSeconds,\n )}s)`,\n );\n console.log(`next: resolve --from ${outPath} --type \u003ctype>`);\n}\n\nfunction cutSegment(inputPath, segment, outPath, copy, fade) {\n const argv = [\n \"-y\",\n \"-nostdin\",\n \"-ss\",\n seekTime(segment.start),\n \"-i\",\n inputPath,\n \"-to\",\n seekTime(segment.end - segment.start),\n ];\n if (copy) {\n argv.push(\"-c\", \"copy\", \"-avoid_negative_ts\", \"make_zero\");\n } else if (extname(outPath).toLowerCase() === \".mov\") {\n // Concat splices raw segment edges together; without a short ramp the\n // waveform steps discontinuously at every boundary and you hear a click.\n if (fade) argv.push(\"-af\", fade);\n // Video intermediate: keep the picture cheap and the audio uncompressed.\n argv.push(\"-c:v\", \"libx264\", \"-preset\", \"veryfast\", \"-crf\", \"18\", \"-c:a\", \"pcm_s16le\");\n // A keyframe every second. The renderer seeks into this footage, and x264\n // on its own leaves up to 250 frames between keyframes.\n argv.push(\"-force_key_frames\", \"expr:gte(t,n_forced)\");\n // Constant frame rate from the first frame. Left to itself, ffmpeg 7 starts\n // a range that begins between two source frames one frame late, and .mov\n // rounds that lead-in to the millisecond.\n argv.push(\"-fps_mode\", \"cfr\");\n } else {\n if (fade) argv.push(\"-af\", fade);\n argv.push(\"-c:a\", \"pcm_s16le\");\n }\n argv.push(outPath);\n execFileSync(\"ffmpeg\", argv, { stdio: \"ignore\" });\n}\n\n// Codec set per output container. Audio-only outputs must not get the\n// video-centric aac/x264 set (aac inside .wav breaks timing entirely).\nfunction isAudioOnly(filePath) {\n return [\".wav\", \".mp3\", \".m4a\", \".aac\", \".flac\"].includes(extname(filePath).toLowerCase());\n}\n\nfunction encodeArgsFor(ext) {\n if (ext === \".wav\") return [\"-c:a\", \"pcm_s16le\"];\n if (ext === \".mp3\") return [\"-c:a\", \"libmp3lame\", \"-q:a\", \"2\"];\n if (ext === \".m4a\" || ext === \".aac\") return [\"-c:a\", \"aac\"];\n if (ext === \".flac\") return [\"-c:a\", \"flac\"];\n return [\n \"-c:v\",\n \"libx264\",\n \"-preset\",\n \"veryfast\",\n \"-crf\",\n \"18\",\n \"-c:a\",\n \"aac\",\n \"-movflags\",\n \"+faststart\",\n ];\n}\n\nfunction probeDuration(filePath) {\n const raw = execFileSync(\n \"ffprobe\",\n [\n \"-v\",\n \"error\",\n \"-show_entries\",\n \"format=duration\",\n \"-of\",\n \"default=noprint_wrappers=1:nokey=1\",\n \"--\",\n filePath,\n ],\n { encoding: \"utf8\" },\n );\n const duration = Number(raw.trim());\n if (!Number.isFinite(duration) || duration \u003c= 0)\n throw new Error(`could not probe duration: ${filePath}`);\n return duration;\n}\n\nfunction escapeConcatPath(filePath) {\n return filePath.replace(/'/g, \"'\\\\''\");\n}\n\nfunction sumDurations(segments) {\n return segments.reduce((sum, segment) => sum + (segment.end - segment.start), 0);\n}\n\nfunction fmt(n) {\n return round3(n)\n .toFixed(3)\n .replace(/\\.?0+$/, \"\");\n}\n\n// -ss/-to name frames, and ffmpeg's accurate seek drops everything before the\n// time it is given: at 30 fps, frame 386 sits at 12.866666 s, and a 3-decimal\n// -ss of 12.867 starts that segment on frame 387 instead, leaving the cut a\n// frame short from the join on. So the values ffmpeg gets keep frame precision,\n// while fmt() above stays at 3 decimals for the times that are only printed.\nfunction seekTime(n) {\n return Number(n).toFixed(6);\n}\n\nfunction round3(n) {\n return Math.round(Number(n) * 1000) / 1000;\n}\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":10266,"content_sha256":"17e148571738ad8cf30b0ccb3f28d0837df5072114b9dfb63bc8d9f5d25e5a5d"},{"filename":"scripts/transcript-cut.test.mjs","content":"import assert from \"node:assert/strict\";\nimport { execFileSync, spawnSync } from \"node:child_process\";\nimport { mkdtempSync, rmSync, writeFileSync } from \"node:fs\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport test from \"node:test\";\nimport { fileURLToPath } from \"node:url\";\n\nconst SCRIPT = fileURLToPath(new URL(\"./transcript-cut.mjs\", import.meta.url));\nconst HAS_FFMPEG =\n spawnSync(\"ffmpeg\", [\"-version\"], { stdio: \"ignore\" }).status === 0 &&\n spawnSync(\"ffprobe\", [\"-version\"], { stdio: \"ignore\" }).status === 0;\n\nconst SAMPLE_RATE = 44100;\n// A continuous tone's own slope between samples never exceeds amplitude * 2*pi*f/rate\n// (~2054 for 440Hz at full scale here); a raw splice between two independently-cut\n// points on the same tone lands at two unrelated phases, so an unfaded join jumps far\n// past that. This threshold sits well above normal tone motion and well below a splice.\nconst MAX_CONTINUOUS_STEP = 6000;\nconst MIN_SUSPICIOUS_ZERO_RUN = 20;\n\nfunction fixture() {\n const dir = mkdtempSync(join(tmpdir(), \"media-use-transcript-cut-\"));\n return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };\n}\n\nfunction run(args) {\n return spawnSync(process.execPath, [SCRIPT, ...args], { encoding: \"utf8\" });\n}\n\nfunction readPcm(filePath) {\n const raw = execFileSync(\"ffmpeg\", [\n \"-hide_banner\",\n \"-loglevel\",\n \"error\",\n \"-i\",\n filePath,\n \"-f\",\n \"s16le\",\n \"-ac\",\n \"1\",\n \"-ar\",\n String(SAMPLE_RATE),\n \"-\",\n ]);\n const samples = new Int16Array(raw.buffer, raw.byteOffset, raw.length / 2);\n return samples;\n}\n\n// Three kept ranges, none starting or ending on a frame boundary of any rate below.\nconst UNALIGNED_KEEP = \"0.137-1.913,2.845-4.111,4.9-5.47\";\nconst UNALIGNED_KEPT_SECONDS = 1.776 + 1.266 + 0.57;\n\nfunction cutVideo(t, rate, keep = UNALIGNED_KEEP) {\n const { dir, cleanup } = fixture();\n t.after(cleanup);\n\n const source = join(dir, \"source.mp4\");\n execFileSync(\"ffmpeg\", [\n \"-y\",\n \"-hide_banner\",\n \"-loglevel\",\n \"error\",\n \"-f\",\n \"lavfi\",\n \"-i\",\n `testsrc2=size=160x90:rate=${rate}:duration=6`,\n \"-f\",\n \"lavfi\",\n \"-i\",\n `sine=frequency=440:duration=6:sample_rate=${SAMPLE_RATE}`,\n \"-c:v\",\n \"libx264\",\n \"-preset\",\n \"ultrafast\",\n \"-pix_fmt\",\n \"yuv420p\",\n \"-c:a\",\n \"aac\",\n source,\n ]);\n\n const transcriptPath = join(dir, \"transcript.json\");\n writeFileSync(transcriptPath, JSON.stringify({ words: [{ text: \"tone\", start: 0, end: 6 }] }));\n\n const output = join(dir, \"out.mp4\");\n const result = run([\n \"--input\",\n source,\n \"--transcript\",\n transcriptPath,\n \"--keep\",\n keep,\n \"--out\",\n output,\n \"--json\",\n ]);\n assert.equal(result.status, 0, result.stderr || result.stdout);\n return output;\n}\n\nfunction readVideoTimestamps(filePath) {\n const probe = JSON.parse(\n execFileSync(\n \"ffprobe\",\n [\n \"-v\",\n \"error\",\n \"-select_streams\",\n \"v:0\",\n \"-show_entries\",\n \"stream=time_base:packet=pts\",\n \"-of\",\n \"json\",\n \"--\",\n filePath,\n ],\n { encoding: \"utf8\" },\n ),\n );\n const [tickNum, tickDen] = probe.streams[0].time_base.split(\"/\").map(Number);\n // Packets come in decode order; B-frames put that out of presentation order.\n const pts = probe.packets.map((packet) => Number(packet.pts)).sort((a, b) => a - b);\n return { tickNum, tickDen, pts };\n}\n\nfor (const rate of [\"30\", \"30000/1001\", \"60\"]) {\n test(\n `puts every frame of a ${rate} fps video cut on the frame grid, with no gaps`,\n { skip: !HAS_FFMPEG },\n (t) => {\n const [rateNum, rateDen = 1] = rate.split(\"/\").map(Number);\n const { tickNum, tickDen, pts } = readVideoTimestamps(cutVideo(t, rate));\n assert.ok(pts.length > rateNum / rateDen, \"expected several seconds of video\");\n\n // Frame i belongs at exactly i / rate seconds. Compared as integers, so a\n // timestamp rounded to the millisecond (0.067 for 2/30) cannot pass.\n const offGrid = pts.filter(\n (value, index) => value * tickNum * rateNum !== index * rateDen * tickDen,\n );\n assert.equal(\n offGrid.length,\n 0,\n `${offGrid.length} of ${pts.length} frames are off the ${rate} fps grid (timestamps in units of ${tickNum}/${tickDen} s)`,\n );\n },\n );\n}\n\ntest(\n \"keeps the keyframes of a video cut no more than a second apart\",\n { skip: !HAS_FFMPEG },\n (t) => {\n // One kept range of almost four seconds, so only the encoder decides where keyframes go.\n const output = cutVideo(t, \"30\", \"0.137-4.111,4.9-5.47\");\n const probe = JSON.parse(\n execFileSync(\n \"ffprobe\",\n [\n \"-v\",\n \"error\",\n \"-select_streams\",\n \"v:0\",\n \"-show_entries\",\n \"packet=pts_time,flags\",\n \"-of\",\n \"json\",\n \"--\",\n output,\n ],\n { encoding: \"utf8\" },\n ),\n );\n const keyframes = probe.packets\n .filter((packet) => packet.flags.startsWith(\"K\"))\n .map((packet) => Number(packet.pts_time))\n .sort((a, b) => a - b);\n const gaps = keyframes.slice(1).map((time, index) => time - keyframes[index]);\n const widest = Math.max(...gaps);\n // A frame of slack: the forced keyframe is the first frame at or after each second.\n assert.ok(widest \u003c 1.05, `keyframes are up to ${widest.toFixed(3)}s apart`);\n },\n);\n\ntest(\n \"does not pad the audio of a video cut with encoder priming at each splice\",\n { skip: !HAS_FFMPEG },\n (t) => {\n const seconds = readPcm(cutVideo(t, \"30\")).length / SAMPLE_RATE;\n // The single AAC encode may round the end up by a frame or two (23 ms each).\n // Encoding every segment separately instead adds about 25 ms per splice on top.\n assert.ok(\n Math.abs(seconds - UNALIGNED_KEPT_SECONDS) \u003c 0.05,\n `audio runs ${seconds.toFixed(3)}s for ${UNALIGNED_KEPT_SECONDS.toFixed(3)}s kept`,\n );\n },\n);\n\ntest(\n \"keeps a spliced tone continuous at every cut, with no raw phase jump or silence gap\",\n { skip: !HAS_FFMPEG },\n (t) => {\n const { dir, cleanup } = fixture();\n t.after(cleanup);\n\n const source = join(dir, \"tone.wav\");\n execFileSync(\"ffmpeg\", [\n \"-y\",\n \"-hide_banner\",\n \"-loglevel\",\n \"error\",\n \"-f\",\n \"lavfi\",\n \"-i\",\n `sine=frequency=440:duration=6:sample_rate=${SAMPLE_RATE}`,\n source,\n ]);\n\n const transcriptPath = join(dir, \"transcript.json\");\n writeFileSync(transcriptPath, JSON.stringify({ words: [{ text: \"tone\", start: 0, end: 6 }] }));\n\n const output = join(dir, \"out.wav\");\n // Two \"ugly\" removal ranges: neither aligned to the 440Hz period, so the kept\n // segments' cut edges land at unrelated phases of the same continuous tone --\n // exactly the shape that clicks without a fade, and the shape jrusso1020's\n // review proved this branch never actually fades.\n const result = run([\n \"--input\",\n source,\n \"--transcript\",\n transcriptPath,\n \"--remove\",\n \"1.37-1.83,3.29-3.71\",\n \"--out\",\n output,\n \"--json\",\n ]);\n assert.equal(result.status, 0, result.stderr || result.stdout);\n\n const samples = readPcm(output);\n assert.ok(samples.length > SAMPLE_RATE, \"expected several seconds of audio\");\n\n let maxStep = 0;\n let zeroRun = 0;\n let maxZeroRun = 0;\n for (let i = 1; i \u003c samples.length; i++) {\n const step = Math.abs(samples[i] - samples[i - 1]);\n if (step > maxStep) maxStep = step;\n if (samples[i] === 0) {\n zeroRun++;\n if (zeroRun > maxZeroRun) maxZeroRun = zeroRun;\n } else {\n zeroRun = 0;\n }\n }\n\n assert.ok(\n maxStep \u003c= MAX_CONTINUOUS_STEP,\n `largest sample-to-sample step was ${maxStep}, expected \u003c= ${MAX_CONTINUOUS_STEP} (a raw, unfaded splice)`,\n );\n assert.ok(\n maxZeroRun \u003c MIN_SUSPICIOUS_ZERO_RUN,\n `found a run of ${maxZeroRun} consecutive zero samples, expected \u003c ${MIN_SUSPICIOUS_ZERO_RUN} (a priming-silence gap)`,\n );\n },\n);\n\n// Frame 32 at 30 fps sits at 1.0666666 s. A -ss rounded to 1.067 lands just past\n// it, so ffmpeg's accurate seek starts that segment on frame 33 and the cut comes\n// out a frame short from the join on.\nconst THIRTY_FPS_FRAME_32 = 32 / 30;\n\ntest(\"a kept range starting on a 30 fps frame keeps that frame\", { skip: !HAS_FFMPEG }, (t) => {\n const { dir, cleanup } = fixture();\n t.after(cleanup);\n\n const source = join(dir, \"src.mp4\");\n execFileSync(\"ffmpeg\", [\n \"-y\",\n \"-hide_banner\",\n \"-loglevel\",\n \"error\",\n \"-f\",\n \"lavfi\",\n \"-i\",\n \"testsrc2=size=320x180:rate=30\",\n \"-f\",\n \"lavfi\",\n \"-i\",\n `sine=frequency=440:sample_rate=${SAMPLE_RATE}`,\n \"-t\",\n \"4\",\n \"-c:v\",\n \"libx264\",\n \"-pix_fmt\",\n \"yuv420p\",\n \"-c:a\",\n \"aac\",\n source,\n ]);\n\n const transcriptPath = join(dir, \"transcript.json\");\n writeFileSync(transcriptPath, JSON.stringify([{ text: \"a\", start: 0.1, end: 3.9 }]));\n\n const output = join(dir, \"out.mp4\");\n const result = run([\n \"--input\",\n source,\n \"--transcript\",\n transcriptPath,\n \"--keep\",\n `0-1,${THIRTY_FPS_FRAME_32}-3`,\n \"--out\",\n output,\n \"--json\",\n ]);\n assert.equal(result.status, 0, result.stderr || result.stdout);\n\n // Frames 0-29 for 0-1s, then frames 32-89 for the second segment. Rounding\n // -ss to the millisecond drops frame 32 and yields 87.\n const frames = Number(\n execFileSync(\n \"ffprobe\",\n [\n \"-v\",\n \"error\",\n \"-select_streams\",\n \"v\",\n \"-count_packets\",\n \"-show_entries\",\n \"stream=nb_read_packets\",\n \"-of\",\n \"csv=p=0\",\n \"--\",\n output,\n ],\n { encoding: \"utf8\" },\n ).trim(),\n );\n assert.equal(frames, 88, `expected 88 frames, got ${frames}`);\n});\n","content_type":"text/javascript; charset=utf-8","language":"javascript","size":9849,"content_sha256":"af546cd7d473eb5f4258148a8dd8ec637a67a242cd50948abe1e0dcd6f64c527"}],"content_json":{"type":"doc","content":[{"type":"paragraph","content":[{"text":"Plugin installs:","type":"text","marks":[{"type":"strong"}]},{"text":" Before setup or freshness commands, follow ","type":"text"},{"text":"plugin execution rules","type":"text","marks":[{"type":"link","attrs":{"href":"../hyperframes/references/plugin-installation.md","title":null}}]},{"text":" when this skill is inside a HyperFrames plugin.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Media in HyperFrames","type":"text"}]},{"type":"paragraph","content":[{"text":"Media lands as a local file in the project's ","type":"text"},{"text":"assets/","type":"text","marks":[{"type":"code_inline"}]},{"text":" with a ledger record; renders never fetch. One verb finds or makes it:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"npx hyperframes media-use resolve --type \u003ctype> --intent \"\u003cwhat you need>\" --project \u003cdir>","type":"text"}]},{"type":"paragraph","content":[{"text":"It prints one line, ","type":"text"},{"text":"resolved \u003cid> → \u003cpath> (\u003ctype>, \u003cmetadata>)","type":"text","marks":[{"type":"code_inline"}]},{"text":". List reusable assets first with ","type":"text"},{"text":"--candidates","type":"text","marks":[{"type":"code_inline"}]},{"text":" and judge the fit yourself; reuse, ingest (","type":"text"},{"text":"--from","type":"text","marks":[{"type":"code_inline"}]},{"text":") and adopt are in ","type":"text"},{"text":"references/resolve.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Where it comes from","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Need","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Free","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"HyperFrames credits","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Local or the person's own key (only when they ask)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Music (","type":"text"},{"text":"bgm","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"HeyGen catalog of 10k+ tracks (signed in)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Generated track","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Local MusicGen","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Sound effects (","type":"text"},{"text":"sfx","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Openverse (credit CC BY sounds); 21 bundled offline","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph"}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph"}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Images, icons","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"HeyGen asset search, 75k+ (signed in)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Generated images","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Local FLUX (mflux), if installed","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Logos (","type":"text"},{"text":"logo","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"theSVG, GitHub avatar, favicon; never redrawn","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph"}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph"}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Voiceover (","type":"text"},{"text":"voice","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"HeyGen Voice Turbo (signed in)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Other HeyGen voices, voice cloning","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"npx hyperframes tts","type":"text","marks":[{"type":"code_inline"}]},{"text":" (Kokoro on device)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"A presenter speaking","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph"}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Avatar video (","type":"text"},{"text":"--type video","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Local LTX for generic clips, if installed","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Transcripts","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"npx hyperframes transcribe","type":"text","marks":[{"type":"code_inline"}]},{"text":" (Parakeet or whisper)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph"}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph"}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Cutouts","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph"}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"heygen background-removal","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"npx hyperframes remove-background","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Grades, LUTs, looks","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"npx hyperframes media-treatment","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph"}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph"}]}]}]},{"type":"paragraph","content":[{"text":"Sign in.","type":"text","marks":[{"type":"strong"}]},{"text":" Every time a request needs a HeyGen model or the catalog, run ","type":"text"},{"text":"npx hyperframes auth status","type":"text","marks":[{"type":"code_inline"}]},{"text":" first. Not signed in: tell the person in one line that sign-in is free and gives Voice Turbo, the music catalog and asset search, ask them to type an exclamation mark and ","type":"text"},{"text":"npx hyperframes auth login","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the prompt, and wait until they say it is done. Use local tools only when the person asks, not as a fallback.","type":"text"}]},{"type":"paragraph","content":[{"text":"Host apps.","type":"text","marks":[{"type":"strong"}]},{"text":" Inside an app with its own media tools, use those first. When ","type":"text"},{"text":"HEYGEN_API_BASE","type":"text","marks":[{"type":"code_inline"}]},{"text":" is set, the host pays: don't ask for a sign-in; relay a refused call's message as written and stop.","type":"text"}]},{"type":"paragraph","content":[{"text":"HeyGen.","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"npx hyperframes media-use generate","type":"text","marks":[{"type":"code_inline"}]},{"text":" makes images, shots, talking photos, voices and music on the sign-in alone. Helpers and direct recipes need the ","type":"text"},{"text":"heygen","type":"text","marks":[{"type":"link","attrs":{"href":"https://developers.heygen.com/cli","title":null}},{"type":"code_inline"}]},{"text":" CLI","type":"text","marks":[{"type":"link","attrs":{"href":"https://developers.heygen.com/cli","title":null}}]},{"text":"; if it is missing, give the link and wait until they say it is installed. Direct ","type":"text"},{"text":"heygen","type":"text","marks":[{"type":"code_inline"}]},{"text":" recipes bill that CLI's own login, not HyperFrames: use them only when that separate payer is selected.","type":"text"}]},{"type":"paragraph","content":[{"text":"Credits.","type":"text","marks":[{"type":"strong"}]},{"text":" Plan for the best result: don't swap in cheaper or free options, or drop items, unless the person asks to save cost. Never tell the person prices, estimates or what a run used; ","type":"text"},{"text":"--plan","type":"text","marks":[{"type":"code_inline"}]},{"text":" is for you. A credit limit the person sets: pass what is left of it as ","type":"text"},{"text":"--max-credits","type":"text","marks":[{"type":"code_inline"}]},{"text":" on every ","type":"text"},{"text":"generate","type":"text","marks":[{"type":"code_inline"}]},{"text":", minus each call's ","type":"text"},{"text":"credits","type":"text","marks":[{"type":"code_inline"}]},{"text":", and never go past it. When a step won't fit (a ","type":"text"},{"text":"--plan","type":"text","marks":[{"type":"code_inline"}]},{"text":" over what is left, or a refused call), say what doesn't fit and ask before dropping or shrinking it. A refused call names a ","type":"text"},{"text":"billing","type":"text","marks":[{"type":"code_inline"}]},{"text":" command: tell the person why, ask them to run it the same way, then retry the step.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Looks on real footage","type":"text"}]},{"type":"paragraph","content":[{"text":"Feedback that footage is dark, flat or dull, should feel retro or printed, needs a face hidden, or needs a reveal is media intent. Inspect the real ","type":"text"},{"text":"\u003cimg>","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"\u003cvideo>","type":"text","marks":[{"type":"code_inline"}]},{"text":", pick one intent, and follow ","type":"text"},{"text":"references/media-treatments.md","type":"text","marks":[{"type":"code_inline"}]},{"text":"; persist with ","type":"text"},{"text":"npx hyperframes media-treatment","type":"text","marks":[{"type":"code_inline"}]},{"text":", never a CSS, SVG or ","type":"text"},{"text":".cube","type":"text","marks":[{"type":"code_inline"}]},{"text":" stand-in.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Offer once, never add silently","type":"text"}]},{"type":"paragraph","content":[{"text":"When you build or review a piece, scan once for concrete gaps (on-screen text with no voiceover, emoji standing in for icons, placeholder images, silent cuts, 10 s+ with no music, a colour cast) and offer the specific fixes in one ask. No signal, no suggestion; respect \"leave it\".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Where to look","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Task","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Read","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Resolve, reuse, adopt, ingest, flags","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/resolve.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Grading, LUTs, ","type":"text"},{"text":"grade-compare","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/grading.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Voiceover, music, sound effects, captions, transcription","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/audio.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Cut, reframe or transform media; direct ","type":"text"},{"text":"heygen","type":"text","marks":[{"type":"code_inline"}]},{"text":" recipes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/operations.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Treatments, realtime effects, overlays, reveals","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/media-treatments.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Install, sign-in, credentials, ","type":"text"},{"text":"--provider","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--local-only","type":"text","marks":[{"type":"code_inline"}]},{"text":", RAM ladders","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/setup-providers.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"media-use generate","type":"text","marks":[{"type":"code_inline"}]},{"text":", HeyGen transcription, prices","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/heygen.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Fades, gain, ducking, automation, effects, buses on placed tracks","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/mixing.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Local commands: grade, cutout, loudness, beats","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/local.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Remembered preferences","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"references/memory.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]}]},"metadata":{"date":"2026-11-02","name":"media-use","author":"@skillopedia","source":{"stars":77594,"repo_name":"hyperframes","origin_url":"https://github.com/heygen-com/hyperframes/blob/HEAD/skills/media-use/SKILL.md","repo_owner":"heygen-com","body_sha256":"27953684efc3615938f824371462b2f6085b0e0982ae3667fe0a12ac89d0ebf9","cluster_key":"4dd73468f3ab9beeceffba240ffed0474fe94e64afc34120acb8dbe736a58e3a","clean_bundle":{"format":"clean-skill-bundle-v1","source":"heygen-com/hyperframes/skills/media-use/SKILL.md","text_bytes":598634,"source_commit":"0bcd816d5b79c4b037ab351acec331b0fad7e55f","skills_sh_rank":12,"attachment_count":96,"text_attachments":96,"attachment_storage":"skill_attachments","binary_attachments":0},"cluster_size":1,"skill_md_path":"skills/media-use/SKILL.md","import_metadata":{"date":"2026-11-02","author":"@skillopedia","version":"v1","category":"media-content","category_label":"Media"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"media-content","import_tag":"skills-sh-top20k-2026-11","description":"Get or make any media for a HyperFrames video - music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks - with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden."}},"renderedAt":1793671885257}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.