hyperframes 0.8.58 → 0.8.59

package/dist/skills/media-use/luts/README.md

@@ -0,0 +1,28 @@
+# LUT library (authoring)
+
+`index.json` is the agent-consumed catalog of color-grade looks. Each entry resolves
+on demand — no `.cube` bodies are committed to the repo.
+
+Each look has:
+
+- `id`, `description`, `tags`, `intensity` — matching + application metadata.
+- `url` (optional) — a hosted `.cube` downloaded, validated, and frozen at resolve
+  time, exactly like bgm/image assets.
+- `params` (optional) — a deterministic `buildCube` spec used offline (`--local-only`)
+  or as a fallback if the `url` download/validation fails.
+
+An entry needs at least one of `url` or `params`; prefer both (CDN url with a params
+fallback) so resolution is never blocked on the network.
+
+## Hosting a new look (operators)
+
+1. Generate the `.cube` (e.g. `resolve -t lut --params '{...}'` or a graded export).
+2. Upload it to the public CDN origin bucket:
+
+   ```
+   aws s3 cp <id>.cube s3://heygen-public/luts/<id>.cube
+   ```
+
+   It is then served at `https://static.heygen.ai/luts/<id>.cube` (CloudFront).
+
+3. Add an entry to `index.json` with that `url` (and ideally a `params` fallback).

package/dist/skills/media-use/luts/index.json

@@ -0,0 +1,57 @@
+{
+  "notes": "Look entries resolve on-demand from a CDN .cube `url` (downloaded + frozen, like bgm/image); `params` is a deterministic buildCube fallback used offline (--local-only) or if the download/validation fails. No .cube bodies are committed. See README.md to author or host a new look.",
+  "looks": [
+    {
+      "id": "teal-orange-blockbuster",
+      "description": "Teal shadows and warm orange highlights for blockbuster-style cinematic footage.",
+      "tags": ["teal", "orange", "blockbuster", "cinematic", "split tone", "movie"],
+      "intensity": 0.85,
+      "url": "https://static.heygen.ai/luts/teal-orange-blockbuster.cube",
+      "params": {
+        "contrast": 0.18,
+        "saturation": 0.08,
+        "vibrance": 0.12,
+        "splitTone": {
+          "intensity": 0.62,
+          "balance": 0.52,
+          "shadows": [-0.04, 0.05, 0.09],
+          "highlights": [0.1, 0.04, -0.03]
+        }
+      }
+    },
+    {
+      "id": "bleach-bypass",
+      "description": "High-contrast desaturated bleach bypass look with strong blacks.",
+      "tags": ["bleach", "bypass", "desaturated", "high contrast", "gritty", "film"],
+      "intensity": 0.8,
+      "url": "https://static.heygen.ai/luts/bleach-bypass.cube",
+      "params": {
+        "blacks": 0.04,
+        "shadows": -0.08,
+        "highlights": 0.08,
+        "whites": 0.18,
+        "contrast": 0.55,
+        "temperature": -0.02,
+        "saturation": -0.72,
+        "vibrance": -0.25
+      }
+    },
+    {
+      "id": "film-fade",
+      "description": "Soft faded film wash with lifted blacks and warm highlights.",
+      "tags": ["film", "fade", "faded", "wash", "warm", "vintage"],
+      "intensity": 0.75,
+      "url": "https://static.heygen.ai/luts/film-fade.cube",
+      "params": {
+        "blacks": 0.35,
+        "shadows": 0.18,
+        "highlights": 0.02,
+        "whites": -0.03,
+        "contrast": -0.28,
+        "temperature": 0.16,
+        "saturation": -0.12,
+        "vibrance": -0.08
+      }
+    }
+  ]
+}

package/dist/skills/media-use/references/audio.md

@@ -0,0 +1,19 @@
+# Audio engine — voiceover, music, SFX, captions, transcription
+
+For a full audio pass (TTS voiceover + background music + sound effects in one
+shot), use the shared engine at `audio/scripts/audio.mjs`. It takes a neutral
+`audio_request.json` and writes `audio_meta.json` plus assets under
+`.media/audio/{voice,bgm,sfx}`:
+
+```bash
+node <SKILL_DIR>/audio/scripts/audio.mjs --request ./audio_request.json --out ./audio_meta.json
+```
+
+- **Request** `{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }`: `id` joins each line back to your model; `bgm.mode` = `retrieve | generate | none` (omit for auto). `--only tts,bgm,sfx` runs a subset and merges into an existing `--out`.
+- **Output** `audio_meta.json` (id-keyed): `voices[].{path,duration_s,words[]}` (word timestamps for captions), `sfx[]`, `bgm`, `total_duration_s`.
+- **HeyGen free-usage path**: HeyGen CLI auth unlocks TTS plus music/SFX retrieval. Local/provider-specific generators are explicit alternatives where installed; run `npx hyperframes media-use resolve --doctor` before assuming retrieval or TTS will work.
+- If BGM took the generate path (`bgm_pending: true`), run `audio/scripts/wait-bgm.mjs` before final render.
+
+Single-shot helpers: `audio/scripts/heygen-tts.mjs` (one voice file). Transcription / background removal / captions use the `hyperframes` CLI (`transcribe`, `remove-background`), see the per-topic guides in `audio/references/` (`tts.md`, `bgm.md`, `sfx.md`, `transcribe.md`, `remove-background.md`, `captions/`).
+
+Transcription defaults to Parakeet (better than whisper.cpp: 6.05% vs 7.44% WER, 5-10x faster) via `scripts/transcribe.mjs`, with whisper.cpp auto-fallback (see `references/operations.md`).

package/dist/skills/media-use/references/grading.md

@@ -0,0 +1,160 @@
+# Color grading — grade blocks and LUTs
+
+Use `grade` when you need a canonical HyperFrames grading/effects payload for
+an `<img>` or `<video>`. Core presets and params-backed LUT entries resolve
+locally; future CDN-backed LUT entries require network unless already
+frozen. Persist a decided payload with the CLI rather than editing HTML by
+hand:
+
+For a vague but explicit polish request, do not jump directly from intent to a
+preset name. Read `media-treatments.md`, choose a treatment whose subject and
+avoid rules match the actual media, apply its conservative base with only
+justified bounded tuning, then complete its visual verification steps. A named
+owned treatment uses the exact preset/payload in its recipe; do not run the
+generic grade/LUT resolver first.
+
+Stop here and use that treatment workflow for requests such as retro, old home
+video, camcorder, film, print, ASCII, glitch, privacy, or a media reveal. Do not
+assemble those from a generic LUT plus handmade CSS vignette/grain/opacity.
+
+**Never `cat`/read a `.cube` file into context.** A 3D LUT is ~size^3 lines of raw numbers (33^3 ≈ 36k lines at the default size). It bloats context and carries zero human/agent-legible signal. To understand or choose a LUT, use `hyperframes grade-compare` to see it rendered, or `cube-validate.mjs` for a one-line `{ok,size}` check. Read `.media/index.md` or `luts/index.json` for the description. Never read the LUT body itself.
+
+```bash
+npx hyperframes media-use resolve --type grade --intent "warm daylight" --project . --json
+```
+
+Preset-first output uses the core runtime vocabulary and does not freeze a file:
+
+```json
+{
+  "preset": "warm-daylight",
+  "intensity": 1
+}
+```
+
+Apply that payload to one unambiguous real media element:
+
+```bash
+hyperframes media-treatment --project . --file index.html \
+  --selector '#hero' \
+  --grading '{"preset":"warm-daylight","intensity":1}' --apply --json
+```
+
+Use `--dry-run` before writing when scope is uncertain and `--clear` to remove
+the treatment. The low-level persisted result is still normal HTML:
+
+```html
+<video
+  class="clip"
+  src="./media/scene.mp4"
+  data-color-grading='{"preset":"warm-daylight","intensity":1}'
+></video>
+```
+
+Direct attribute authoring is a fallback for environments where the CLI is not
+available, not the primary agent workflow.
+
+To build a treatment that is not already represented by a recipe, inspect the
+canonical toolbox first:
+
+```bash
+hyperframes media-treatment --capabilities --json
+```
+
+It reports a concise family map. Read `--capability grading` for the processing
+order, then request only the focused family needed to get its legal controls
+and ranges from Core. Compose one nested payload and pass it back through
+`hyperframes media-treatment`; the command rejects unknown keys before
+mutation. Do not generate or hand-edit a LUT merely to combine controls already
+owned by the realtime shader.
+
+For seek-safe effect motion, animate only the runtime-supported CSS properties
+on that same real media element with its registered paused GSAP timeline:
+
+| CSS property                       | Range   |
+| ---------------------------------- | ------- |
+| `--hf-color-grading-intensity`     | 0 to 1  |
+| `--hf-color-grading-lut-intensity` | 0 to 1  |
+| `--hf-color-grading-exposure`      | -2 to 2 |
+| `--hf-color-grading-blur`          | 0 to 1  |
+| `--hf-color-grading-bloom`         | 0 to 3  |
+| `--hf-color-grading-kuwahara`      | 0 to 1  |
+| `--hf-color-grading-pixelate`      | 0 to 1  |
+| `--hf-color-grading-ascii`         | 0 to 1  |
+| `--hf-color-grading-dither`        | 0 to 1  |
+
+Author the initial value directly in the media element's inline `style`, then
+use finite `tl.to()` keyframes. Do not use a frame-zero `tl.set()`, CSS
+animation clocks, timers, random values, or `onUpdate` callbacks. The static
+`data-color-grading` payload remains the fallback and source of the other
+controls.
+
+For a reusable color transform beyond the preset vocabulary, freeze a validated
+`.cube` under `.media/luts/` and return a block that references it:
+
+```bash
+npx hyperframes media-use resolve --type grade --intent "teal orange blockbuster" --project . --json
+```
+
+```json
+{
+  "intensity": 1,
+  "lut": { "src": ".media/luts/grade_001.cube", "intensity": 0.85 }
+}
+```
+
+Use `lut` when you only need the reusable `.cube` file:
+
+```bash
+npx hyperframes media-use resolve --type lut --intent "teal orange blockbuster" --project .
+```
+
+For a describable technical look, author an explicit parametric LUT with `--params`:
+
+```bash
+npx hyperframes media-use resolve --type lut --params '{"contrast":0.2,"temperature":-0.3}' --project .
+npx hyperframes media-use resolve --type grade --params '{"exposure":0.2}' --project . --json
+```
+
+For a LUT generated by your own script, ingest it with `--from`; media-use validates it before registration and rejects invalid or oversized cubes:
+
+```bash
+npx hyperframes media-use resolve --type lut --from custom.cube --project .
+```
+
+Parametric math (`buildCube`) cannot reproduce real film stocks or emulsion
+transforms. Use a CDN-backed scanned `.cube` entry or ingest a real scanned
+`.cube` for those.
+
+For visual selection, list reusable LUT candidates with
+`resolve --type grade --candidates`, write the promising entries to a
+`grades.json`, run
+`hyperframes grade-compare --for <frame> --grades grades.json`, then commit the
+winner with `resolve -t grade` as the final `data-color-grading` block.
+
+For media already selected in a composition, use `media-treatment --analyze`
+when you need side-effect-free `ffmpeg`/`ffprobe` signalstats evidence. It
+returns source metadata, HDR/unknown-LOG warnings, and a bounded `adjust`
+suggestion without modifying the composition. The suggestion is a starting
+point for visual review, not an automatic neutralization of intentional color.
+
+```bash
+hyperframes media-treatment --project . --file index.html \
+  --selector '#hero' --analyze --json
+```
+
+For an unbound source file, `resolve --type grade --for ... --analyze` remains
+available. Without `--analyze`, that resolver records a grade candidate in
+`.media`; use that form only when you intend to keep the candidate.
+
+Library LUT entries live in `luts/index.json`. Each entry keeps `id`,
+`description`, `tags`, and `intensity`, then supplies either compact `params`
+for on-demand `buildCube(params)` generation or a direct CDN `url` for future
+scanned `.cube` files. Do not commit generated `.cube` bodies; resolve
+validates generated or downloaded cubes as it freezes them under
+`.media/luts/`.
+
+```bash
+npx hyperframes media-use resolve --type lut --intent "teal orange blockbuster" --project . --json
+node skills/media-use/scripts/lib/cube-validate.mjs .media/luts/lut_001.cube
+```