Skip to content
HyperFrames Media Use

HyperFrames Media Use Skill

HeyGen's official HyperFrames skill for sourcing media: music, sound effects, images, logos, voiceover, avatar video, transcripts, cutouts and colour grades, resolved into local project files.

GitHub Docs

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from heygen-com/hyperframes.

$ npx skills add heygen-com/hyperframes --skill media-use

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/media-use/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/heygen-com/hyperframes.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/skills/media-use ~/.claude/skills/media-use

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/media-use/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/

About

  • One resolve command that reuses, finds or generates an asset and saves it locally with a ledger record
  • Free HeyGen sign-in unlocks 10k+ music tracks, 75k+ images and icons and 3 minutes a month of Voice Turbo
  • Paid HyperFrames credits for generated images, music, avatar video and video cutouts
  • Local fallbacks on request: MusicGen, FLUX, Kokoro TTS, Parakeet or Whisper transcription
  • Colour grades, LUTs and treatments for dark or flat footage, plus audio mixing
  • Optional credit limit file that makes paid calls refuse to overspend

Media Use is the media skill of HeyGen's HyperFrames, the open-source framework for building videos as code. It gives a coding agent one command for getting whatever a video project needs, npx hyperframes media-use resolve --type <type> --intent "...", which either reuses an asset already in the project or finds or generates a new one, and always lands it as a local file in assets/ with a ledger record. Renders never fetch media from the network.

The skill maps each kind of media to where it comes from. Signing in to HeyGen for free unlocks a catalogue of more than 10,000 music tracks, HeyGen sound effects, an asset search of more than 75,000 images and icons, and three minutes a month of Voice Turbo voiceover on the Free plan. HyperFrames credits pay for generated tracks, images, avatar videos of a presenter speaking and video cutouts. Logos come from theSVG, GitHub avatars or favicons and are never redrawn. Local alternatives (MusicGen, FLUX via mflux, Kokoro text to speech, Parakeet or Whisper transcription, background removal) are used only when the person asks for them.

It also covers treatments for real footage that looks dark, flat or dull, colour grades and LUTs, and mixing of placed audio (fades, ducking, buses). A credit limit can be written to .hyperframes/credit-limit.json so paid calls refuse to exceed it, and the agent is told to offer missing media once rather than add it silently. Note that the skill runs a usage beacon through the HyperFrames CLI's telemetry, which honours the opt-out. Apache-2.0 licensed.

SKILL.md

The instructions your agent loads, as published by HeyGen.

SKILL.md
name
media-use
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.

Running the CLI: every npx hyperframes <command> here, the beacon included, means node <SKILLS>/hyperframes/scripts/plugin-cli.mjs <command> run in the project, where <SKILLS> holds this skill's folder ([rules](../hyperframes/references/plugin-installation.md)).

Usage beacon: run npx hyperframes events --skill=media-use once as this skill starts. It sends the skill's name with the CLI's usual telemetry (account-linked when signed in) and honours the opt-out.

Media in HyperFrames

Media lands as a local file in the project's assets/ with a ledger record; renders never fetch. One verb finds or makes it:

npx hyperframes media-use resolve --type <type> --intent "<what you need>" --project <dir>

It prints one line, resolved <id> → <path> (<type>, <metadata>). List reusable assets first with --candidates and judge the fit yourself; reuse, ingest (--from) and adopt are in references/resolve.md.

Where it comes from
NeedFreeHyperFrames creditsLocal or the person's own key (only when they ask)
Music (bgm)HeyGen catalog of 10k+ tracks (signed in)Generated trackLocal MusicGen
Sound effects (sfx)HeyGen (signed in); Openverse (credit CC BY); bundled
Images, iconsHeyGen asset search, 75k+ (signed in)Generated imagesLocal FLUX (mflux), if installed
Logos (logo)theSVG, GitHub avatar, favicon; never redrawn
Voiceover (voice)Voice Turbo, Free plan: 3 min a monthVoice Turbo on a paid plan, other HeyGen voices, cloningnpx hyperframes tts (Kokoro on device)
A presenter speakingAvatar video (--type video)Local LTX for generic clips, if installed
Transcriptsnpx hyperframes transcribe (Parakeet or whisper)
CutoutsVideo: --type cutoutnpx hyperframes remove-background
Grades, LUTs, looksnpx hyperframes media-treatment

Sign in. Every time a request needs a HeyGen model or the catalog, run npx hyperframes auth status first. Not signed in: tell the person in one line that sign-in is free and gives the music catalog, asset search and 3 min of Voice Turbo a month on the Free plan, ask them to type an exclamation mark and npx hyperframes auth login in the prompt, and wait until they say it is done. Use local tools only when the person asks, not as a fallback.

Host apps. Inside an app with its own media tools, use those first. When HEYGEN_API_BASE is set, the host pays: don't ask for a sign-in; relay a refused call's message as written and stop.

HeyGen. npx hyperframes media-use generate makes images, shots, talking photos, voices and music on the sign-in alone. Helpers and direct recipes need the `heygen` CLI; if it is missing, give the link and wait until they say it is installed. Direct heygen recipes bill that CLI's own login: use them only when that payer is selected.

Credits. Plan for the best result: no cheaper or free swaps, no dropped items, unless asked to save cost. Don't volunteer prices, estimates or usage; --plan is for you. A credit limit the person sets: write it once to .hyperframes/credit-limit.json as {"credits": N}; every paid call then refuses what would go past it, GPT Image and H3 at estimate +10% (references/heygen.md) (--max-credits only tightens). A step that won't fit (a --plan over what is left, or a refused call): say what doesn't, ask before dropping or shrinking it. A refused call names a billing command: say why, ask them to run it, then retry.

Looks on real footage

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 <img>/<video>, pick one intent, and follow references/media-treatments.md; persist with npx hyperframes media-treatment, never a CSS, SVG or .cube stand-in.

Offer once, never add silently

Scan a piece you build or review 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 fixes in one ask. No signal, no suggestion; respect "leave it".

Where to look
TaskRead
Resolve, reuse, adopt, ingest, flagsreferences/resolve.md
Grading, LUTs, grade-comparereferences/grading.md
Voiceover, music, sound effects, captions, transcriptionreferences/audio.md
Cut, reframe or transform media; direct heygen recipesreferences/operations.md
Treatments, realtime effects, overlays, revealsreferences/media-treatments.md
Install, sign-in, credentials, --provider, --local-only, RAM laddersreferences/setup-providers.md
media-use generate, HeyGen transcription, pricesreferences/heygen.md
Fades, gain, ducking, automation, effects, buses on placed tracksreferences/mixing.md
Local commands: grade, cutout, loudness, beatsreferences/local.md
Remembered preferencesreferences/memory.md
Install
New

HeyGen's entry skill for HyperFrames, which renders HTML compositions to video frame by frame: the render contract, the editing loop and per-genre guides for launch films, explainers, data videos, captions and more.

Skill: Showtime

by Favio Vazquez

Local video studio for coding agents: describe a video and your machine renders it, with voice-over, music and captions, no API keys.

New

HeyGen's official skill for driving the HyperFrames CLI: scaffold a video project, lint and check compositions, snapshot frames, edit the timeline, preview and render HTML compositions to MP4 locally, in Docker or in the cloud.

Browse all skills →