media-use
Turn an approved local asset into a stable project path and ledger record. This skill is an inventory and ingestion layer: it performs no web search, download, media generation, or voice synthesis.
For revisioned audition decisions, generated images/video, derivatives and the distinction between a reviewed asset and one actually used in a release, read review and derivative provenance. Keep those editorial records alongside the resolver manifest; do not pretend its existing flags implement a full editorial state machine.
Voice is outside this resolver. fish-audio-api is the bundled synthesis adapter. Respect supplied narration or a user-selected provider; prepare that audio through its supported route, then import the resulting local narration file and measured timing into the composition.
Public package setup
No media recordings, author library, review database or cache is included. Supply your own reviewed files and rights records. A new project can begin with an empty library; discovery may return no results. Use explicit --source ingestion when you already have a permitted file.
The project wrapper finds .agents/skills/media-use or the directory named by MEDIA_USE_SKILL_DIR. Its optional MEDIA_CATALOG points to a catalog within the project/workspace; --catalog overrides it. The resolver's optional MEDIA_USE_GLOBAL_CACHE_DIR selects a user-owned cache. These paths are configuration, not assets supplied by this release. Standalone resolver/catalog commands read environment variables; the scaffolded wrapper additionally reads the project .env.
Resolve
bashnode <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description-or-id>" --project <dir>
Types: bgm, sfx, image, icon, and the local-only brand record.
For brand, a local frame.md, FRAME.md, design.md, or DESIGN.md can be frozen as the design record. Flat YAML frontmatter is retained when present; a plain Markdown design document is still a valid local record.
Resolution is deterministic and local:
- Reuse a valid project-manifest record matching the requested id, path, exact prompt, or entity.
- Adopt a matching unregistered file from the project's
assets/tree, preserving supplied review/rights flags. Strict HyperFrames audio delivery still requires those fields before wiring. - Reuse a frozen record from the local global cache. BGM and SFX cache entries must carry local-origin provenance.
- On a miss, stop with staging instructions. The agent or user selects and reviews the asset before retrying.
Review-catalog handoff
In a scaffolded HyperFrames project, npm run audio:discover -- --type bgm --query "<semantic job>" (or --type sfx) searches workspace review catalogs without copying or approving anything. Treat its result as a lead: inspect the source/license/technical metadata, audition the file, then ingest that exact reviewed candidate with --source, --reviewed, and the catalog's --expected-sha256. Preserve source id/page, catalog id, license name/URL, a substantive review note, and creator/attribution when present. Catalog membership alone is never approval, and a render must never reference the review-library path directly.
After explicit ingestion, the resolver prints one concise result:
textresolved sfx_001 → assets/sfx/soft-whoosh.wav (sfx)
Ingest an explicit local file
Use --source after selecting and reviewing a file. The resolver copies it into .media/, probes its metadata, and records its local provenance.
bashnode <SKILL_DIR>/scripts/resolve.mjs \ --type sfx \ --intent "soft interface whoosh" \ --source /absolute/path/to/reviewed-whoosh.wav \ --reviewed \ --expected-sha256 <64-hex-catalog-hash> \ --source-id <source-provider-asset-id> \ --source-page <original-asset-page> \ --catalog-id <catalog-asset-id> \ --license <license-name-or-id> \ --license-url <license-page> \ --review-note "auditioned under narration; clean short tail" \ --project .
--source is an explicit ingestion path, so it bypasses discovery and cache matching. It accepts a regular local file only. When --catalog-id is present, the review, hash, source, rights, and substantive-note fields shown above are mandatory. The resolver verifies the hash both before and after freezing the copy, before it writes the manifest.
Flags
| Flag | Meaning |
|---|---|
--type, -t | bgm, sfx, image, icon, or brand |
--intent, -i | Description, manifest id, or manifest path |
--entity, -e | Optional exact entity match |
--source | Reviewed local file to freeze and register |
--source-page | Original asset page retained as audit metadata |
--license | License name or identifier retained as audit metadata |
--license-url | License page retained as audit metadata |
--attribution | Attribution text retained as audit metadata |
--reviewed | Record that the candidate was explicitly reviewed before ingestion |
--expected-sha256 | Require the source bytes to match a 64-hex catalog hash |
--creator | Creator retained as audit metadata |
--source-id | Source provider's asset id retained as audit metadata |
--catalog-id | Local review-catalog asset id retained as audit metadata |
--review-note | Human audition/review note retained as audit metadata |
--project, -p | Project directory; defaults to . |
--adopt | Inventory supported files already under assets/; bulk inventory alone does not approve audio for rendering |
--json | Emit machine-readable output |
Adopt an existing project
bashnode <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
Adoption probes supported media with ffprobe, appends records to .media/manifest.jsonl, and regenerates .media/index.md. Bulk adoption is an inventory operation, not editorial approval: BGM/SFX records still need substantive review and rights provenance before the strict HyperFrames sound gate will allow them to render. Resolve a selected staged audio asset individually with the relevant review/license flags to make that provenance explicit. Narration and voice files are intentionally ignored; TTS outputs remain owned by the Fish Audio workflow.
Inventory and cache
.media/manifest.jsonlis the project source of truth..media/index.mdis the readable inventory.~/.media/is the frozen cross-project cache.MEDIA_USE_GLOBAL_CACHE_DIRmay point the resolver at another trusted local cache root.
The resolver does not purge older cache entries. It simply refuses BGM or SFX records whose provenance does not establish local selection or adoption. Legacy adopted records marked with both provider: local and adopted: true remain reusable; a remote provider marker is never accepted as local provenance.
Cache eligibility is not current editorial approval. Before reuse, check the current project's decisions and exclusions by candidate id and source hash. A cached asset rejected in this project remains excluded even if an earlier project approved it.
Miss handling
When resolution misses, use the HyperFrames project's read-only audio:discover command, or select a properly licensed asset outside this skill, then ingest the reviewed file with --source. Preserve source, license, attribution, hash, catalog identity, and review notes in the project record.
Requirement
ffprobe is recommended for duration, codec, and dimensions. Resolution still works when probing fails, but those metadata fields remain empty.
