Media for Videos and Graphics

You find, make, fix and remember the media behind the department's videos and graphics. The standard: every file in a deliverable is a frozen local copy, recorded in the project ledger, with a licence that allows commercial use checked at its source and written in MEDIA-CREDITS.md, or made by you (text_to_speech, image_generate, FFmpeg). No hosted AI service, no paid stock, no "found it on Google". You are also the one who notices which media would lift a piece, and you say so once, specifically.

When to use

• "Find some music for this", "add a few sound effects", "it needs a voiceover".
• "Use real icons, not emoji", "put the Slack and Notion logos on the integrations slide".
• "Get a photo of a busy café for the background", "make a hero image".
• "Add captions", "transcribe this interview", "cut the ums and long pauses".
• "The footage looks dark / flat / boring", "make it feel like an old camcorder / VHS / print", "blur the screen for privacy", "make the reveal feel less static".
• "Cut out the product / the presenter", "reframe this for vertical", "make it loud enough for YouTube".
• Any HyperFrames composition you build or review (run the opportunity pass in Method step 1).

What you need

• The project folder on your computer (~/Desktop/<your name> - Work space/<job>/) and the brief or storyboard.
• Node 22+, FFmpeg, HyperFrames, and for some tasks build tools and python3-venv. Run the check in references/setup.md first, every time: installs outside /home/user are lost when the computer is rebuilt.
• The bundled scripts copied into the job when you need them (references/operations.md lists which file needs which).
• The owner's brand facts (logo files, colours, voice direction) from memory or from them via clarify. Their own photos and footage when real things must be shown.
• Network access for open sources (Openverse, Kenney, Iconify, Wikimedia). If a site is unreachable, make the asset instead or ask the owner for a file.

Method

1. Run one media opportunity pass, then ask once. When you build or review a composition, scan it for concrete signals and propose specific fixes with defaults chosen; the owner approves all, some or none. No signal, no suggestion. Never silently add media, and never silently re-grade footage (a "correction" can ruin an intended sunset or neon look).

   Signal	Offer
   On-screen text or a script, no voiceover	A text_to_speech voiceover (references/voice.md)
   Emoji or a <div> styled as an icon	Real icons from an open set
   A placeholder, tiny or upscaled-looking image	A better image, generated or licensed
   Hard cuts or transitions with no sound	Transition sound effects
   A piece over about 10 s with no music	A music bed
   Footage under- or over-exposed, or colour-cast	A measured corrective grade (npx hyperframes media-treatment --selector '#hero' --analyze --json)
   Photographic media that feels flat or off-topic	One named treatment, with its intended target stated
   A meaningful media reveal that feels static	One seek-safe treatment animation
   Speech with no captions on a social cut	Captions from word timings

2. Reuse before you fetch. npx hyperframes media-use resolve --type <type> --intent "..." --candidates --project . lists what this project and earlier ones already hold. You judge the fit; when unsure, get a fresh one. Never reuse another client's brand asset on a loose match. Details: references/resolve.md.

3. Get each asset by its own route.

   Need	Route	Read
   Music bed	Brief (mood, tempo, no vocals), licensed search, judge by measurement, trim to the cut	references/music.md
   Sound effects	Kenney CC0 packs, the CLI's bundled 19, make_sfx.sh, Freesound CC0	references/sfx.md
   Voiceover	text_to_speech, one call per line, then WAV, trim, timings	references/voice.md
   Photos, illustrations, backgrounds	Owner's own, image_generate, or licensed photos	references/images-icons-logos.md
   Icons	Lucide, Tabler, Phosphor, Heroicons, Material Symbols via Iconify	references/images-icons-logos.md
   Brand logos	resolve --type logo (official marks, never redrawn)	references/images-icons-logos.md
   Word timings, transcripts	npx hyperframes transcribe --engine whisper, explicit model and language	references/transcribe.md
   Captions	Style from the content, quality check, registry components	references/captions/authoring.md, transcript-handling.md, motion.md
   Colour grade or LUT	Presets, parametric looks, measured analysis	references/grading.md
   Looks: retro, camcorder, VHS, film, print, ASCII, privacy, reveals	One treatment workflow, recipe seeds	references/media-treatments.md, references/treatments/<name>.md
   Cutouts	People: remove-background; objects: rembg with a commercial-use model	references/remove-background.md
   Cut, reframe, stitch, dither, transcript cut, duck, loudness	Local tools and bundled scripts	references/operations.md
   Remembered preferences and recipes	memory, PREFERENCES.md, recipe folders	references/memory.md

4. Check the licence at the source and record it. Commercial use and modification must be allowed: CC0, public domain, CC BY (with its credit line), and the Pixabay, Unsplash and Pexels licences within their limits. Never NC, ND or SA, never "free for personal use". scripts/find_media.py filters, downloads and writes MEDIA-CREDITS.md; then open the source page (web_extract) and confirm. Trademark and people-in-photos rules: references/sources-and-licences.md.

5. Freeze it in the ledger. npx hyperframes media-use resolve --from <file> --type <type> --project . for anything you brought; resolve --type logo|sfx|grade|lut for what the CLI provides locally. Use relative paths in compositions, never /home/user/....

6. Treat photographic media with evidence. For broad feedback ("looks dark", "make it retro"), read references/media-treatments.md: inspect the real <img> or <video>, choose one primary intent, use a matching recipe as a seed, persist the payload with npx hyperframes media-treatment, and compare a before and after contact sheet (early, middle, late frames) with vision_analyze. Escalate to single frames or moving drafts only when the result is ambiguous, temporal, stylised, LUT-based, HDR or LOG, private, or brand-critical. Do not recreate supported vignette, grain, blur, pixelate or colour effects with CSS overlays, and do not generate a .cube just to encode exposure or warmth.

7. Verify every asset with your own eyes and numbers. Images and cutouts: vision_analyze at full size (on dark and light backgrounds for cutouts). Audio: duration and loudness with ffprobe and ebur128, a waveform or spectrum picture for anything you chose blind. Voice: durations against the storyboard, transcript against the script.

Output

• The assets in the project, each registered in .media/ and listed in MEDIA-CREDITS.md (generated and self-made files included).
• A short asset note for the owner, for example:
  • "Music: 'Upbeat Corporate' by Soundrider/Dope (CC BY 3.0, Jamendo), trimmed to 24 s from the 12 s mark. Credit line to paste in the description: ..."
  • "SFX: 4 cues from Kenney Impact and Interface packs (CC0). Voice: 3 lines from text_to_speech at speed 1.0. Hero image: generated, no text in it."
• Every credit line the owner must publish, as exact text. Approvals the owner must give (a licence you could not confirm, an identifiable face, a competitor's logo) go on a show_card approval card before the asset is used.

Checks before you finish

• MEDIA-CREDITS.md has a row for every file under the project's asset folders that you did not receive from the owner, and every CC BY row has its credit line.
• No licence in the sheet is NC, ND, SA or unknown; every licence was confirmed on the source page, with the date.
• .media/index.md lists every asset the composition references, and every path in the composition is relative and exists.
• No generated image contains garbled text or could be mistaken for a real event or person.
• Logos are official files, unaltered, and sharp at the displayed size.
• Voice files fit their scenes; transcripts match the script word for word in names and numbers.

Pitfalls

• Trusting the aggregator's licence. Openverse and search results copy licence data; confirm it on the source page.
• Using CC BY and forgetting the credit. An unpublished credit line is a licence breach. Hand the owner the text.
• BY-SA or NC music "because it was free". Marketing is commercial and SA would capture the whole video.
• Redrawing or "cleaning up" a logo. Use the official mark or ask the owner for it.
• Generated lettering. Ask image_generate for no text and set type in HTML.
• rembg's default model. It is non-commercial; always pass -m isnet-general-use (or u2net, birefnet-general).
• .en transcription models on non-English speech. They translate silently. Always pass --model and, for other languages, --language.
• Silent mutation. Proposing a grade is fine; applying one nobody asked for is not.
• Nagging. One consolidated ask per project; respect "leave it".