cycle-atlas/.claude/skills/media-use/references/local.md

Local media commands

These run on this machine, free, and write into the project.

Grade and style footage and images

• Measure, then correct: npx hyperframes media-treatment --selector '#hero' --analyze --json, then --grading '<json>' --apply. --dry-run previews; --clear removes the treatment.
• --file defaults to index.html: for media inside a scene, pass --file compositions/<scene>.html.
• Grain, blur, vignette, presets, palettes: npx hyperframes media-treatment --capabilities --json, then --capability <id> for one family's controls and ranges.
• The result is a data-color-grading attribute on the media element. It treats the whole element in SDR, so it can't blur one region such as a face.
• To animate it, set the start value in the element's inline style and tween these custom properties with finite tl.to() on the composition's timeline: --hf-color-grading- followed by intensity, lut-intensity, blur, kuwahara, pixelate, ascii or dither (each 0–1), exposure (−2 to 2) or bloom (0–3).
• Compare candidate grades on one frame: npx hyperframes grade-compare --for frame.png --grades grades.json --json, or --luts a.cube,b.cube.

Cutouts

• npx hyperframes remove-background <in> -o cutout.webm (.png for an image; --quality best for a closer colour match over its source). --background-output plate.webm also writes the background with the subject cut out.
• A cutout over its own source: both clips data-start="0" and data-media-start="0", so they decode in sync.
• The runtime forces opacity: 1 on a timed clip. To fade a cutout, wrap it in an untimed <div> and animate the wrapper.

Sound

• Match loudness: npx hyperframes normalize-audio --reference <id> --target <id> --write, or --lufs=-16 (the default target; write a negative value with =) without a reference. --write edits the volume in the HTML.
• Beat grid: npx hyperframes beats --json reads the local music <audio> (marked data-timeline-role="music", or an id containing music, bgm or soundtrack) and writes beats/<path>.json, which Studio shows as its beat grid. A beat time minus a scene's data-start is its time inside that scene.
• Local transcription, or importing .srt, .vtt or Whisper JSON: npx hyperframes transcribe <file> --json. The default model translates non-English speech: see ../../hyperframes/references/captions.md.