media-use

Plugin installs: Before setup or freshness commands, follow plugin execution rules when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.

media-use

The media OS for HyperFrames: resolve · generate · operate · remember — every media type, one skill, zero context noise.

First run: verify the local setup with hyperframes media-use resolve --doctor (it checks ffmpeg, ffprobe, Node and the bundled SFX). Every generator is local-first and opt-in; providers, keys and installs: references/setup-providers.md.

Music and sound effects inside a host app: when the app you run in gives you its own music or sound-effect tools, use those. Otherwise music has no catalog: generate the bed with the audio engine (audio/references/bgm.md — Lyria with GEMINI_API_KEY, else local MusicGen) and resolve --type bgm records it with --from. resolve --type sfx searches Openverse (CC0 and CC BY only, no account) and falls back to its bundled library offline; credit CC BY sounds as audio/references/sfx.md says.

Before generating a voiceover, tell the person which engine will run: ElevenLabs when ELEVENLABS_API_KEY is set, otherwise local Kokoro (Gemini only when asked for). A missing key is their choice to make, not a silent fallback.

Resolve — the one verb

hyperframes media-use resolve --type <type> --intent "<description>" --project <dir>

Returns one line: resolved <id> → <path> (<type>, <metadata>). All search noise stays on disk.

Before resolving fresh, list reusable candidates with --candidates and judge fit yourself — reuse rules, all flags, ingest (--from), and adopt are in references/resolve.md.

Treat broad visual feedback as media intent

When a user explicitly asks to fix, polish, stylize, obscure, emphasize, or reveal photographic media, read references/media-treatments.md even if they do not name color grading or an effect. Inspect the real <img>/<video>, choose one primary intent, then use deterministic persistence and verification. Use a matching recipe as an optional tested seed, or inspect hyperframes media-treatment --capabilities --json, then request one relevant family/effect with --capability <id> and assemble a custom treatment from canonical controls. Never load --all for ordinary authoring. A treatment may compose correction, a preset, finishing, compatible shader effects, supported keyframes, and optional Registry overlays. Add only source-justified bounded tuning and compatible parts, never effects merely to make the result look more sophisticated. Persist the final combined payload with hyperframes media-treatment.

Use one progressively escalating workflow. For video, inspect one labeled early/middle/late contact sheet rather than reading frames separately. Apply one candidate and inspect one after-sheet for ordinary correction or polish. Escalate to individual frames or moving draft evidence only when the result is ambiguous, temporal, stylized, LUT-based, HDR/LOG-sensitive, private, or brand-critical.

For ordinary correction or polish, persist the final treatment's preset/adjustment JSON. Do not generate a .cube LUT merely to encode exposure, shadows, contrast, or warmth. Use a LUT only when the user supplies one or the selected treatment explicitly owns one. resolve --type grade --for ... --analyze is measurement evidence, not permission to replace the chosen treatment with a generated LUT. Do not recreate supported vignette, grain, blur, pixelate, color, or treatment effects with CSS/SVG overlays; that bypasses Studio controls and the canonical preview/render shader path.

Be proactive — run a media opportunity pass

The human usually can't tell which media would lift the piece. You can. When you build or review a composition, do one grounded scan and then ask once — don't silently add, and don't nag per asset.

Surface an opportunity only when a concrete signal is present:

Rules that keep this a help, not nagware: grounded, not generic (no signal → no suggestion); opinionated + concrete (propose the specific fix with defaults chosen — the human approves all / some / none); once per project (one consolidated ask; respect "leave it"); surface, never silently mutate (color grades especially: propose and preview — a gray-world "correction" ruins an intentional sunset or neon look).

Where to look — read only the file your task needs