media-use
Löse Medienanforderungen in lokale Dateien auf. Ein Befehl, vier Typen, null Kontextrauschen.
Wann verwenden
Rufe resolve immer dann auf, wenn eine Komposition Medien benötigt – Hintergrundmusik, Soundeffekte, Bilder oder Symbole. media-use durchsucht den HeyGen-Katalog, lädt den besten Treffer herunter, friert ihn lokal ein und registriert ihn in einem Manifest. Der Agent bekommt eine Zeile zurück; das gesamte Suchrauschen bleibt auf der Platte.
Resolve
node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
Gibt eine Zeile zurück: resolved <id> → <path> (<type>, <metadata>)
Typen
| Typ | Findet | Anbieter |
|---|---|---|
bgm | Hintergrundmusik | HeyGen-Audiokatalog (10.000+ Titel) |
sfx | Soundeffekte | Gebündelte 19-Datei-Bibliothek + HeyGen-Katalog |
image | Fotos, Hintergründe | HeyGen-Assetsuche (75.000+ Vektoren) |
icon | Symbole, Logos | HeyGen-Assetsuche (Typ=icon) |
Beispiele
# Hintergrundmusik
node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --project .
# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)
# Soundeffekt
node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
# Bild
node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech background" --project .
# → resolved image_001 → .media/images/image_001.jpg (image)
# Symbol
node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .
# → resolved icon_001 → .media/images/icon_001.png (icon, transparent)
Flags
| Flag | Beschreibung |
|---|---|
--type, -t | Medientyp: bgm, sfx, image, icon |
--intent, -i | Was du brauchst (natürliche Sprache) |
--entity, -e | Entitätsname für Cache-Abgleich (optional) |
--project, -p | Projektverzeichnis (Standard: .) |
--adopt | Bulk-Import vorhandener Assets/ in Manifest |
--json | JSON-Ausgabe statt einzeiligem Ergebnis |
Funktionsweise
- Prüfe Projekt
.media/manifest.jsonlauf exakte Prompt-Übereinstimmung - Durchsuche vorhandenes
assets/-Verzeichnis nach nicht registrierten Dateien, die zur Anforderung passen - Prüfe globalen Cache
~/.media/auf wiederverwendbares Asset - Suche über Anbieter (HeyGen-Audiokatalog, HeyGen-Assetsuche)
- Friere Datei nach
.media/<type>/ein, registriere im Manifest, generiereindex.mdneu
Der Agent bekommt eine Zeile zurück. Kandidaten, Bewertungen, Herkunft bleiben auf der Platte.
Vorhandene Projekte übernehmen
Die meisten HyperFrames-Projekte haben bereits Assets in assets/. media-use übernimmt sie:
node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
# → adopted 9 assets from assets/
# bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)
# image_001 → assets/images/avatar.jpg (image, 400×400)
ffprobe extrahiert echte Dauer und Abmessungen. Während resolve werden nicht registrierte Dateien in assets/, die zur Absicht passen, spontan übernommen.
Bestand einsehen
Nach resolve oder adopt lies .media/index.md für den vollständigen Bestand:
# .media · 4 assets
id type dur dims path description
bgm_001 bgm 25s — .media/audio/bgm/bgm_001.mp3 upbeat tech launch
sfx_001 sfx 0.6s — .media/audio/sfx/sfx_001.mp3 whoosh
image_001 image — 1920×1080 .media/images/image_001.jpg gradient tech background
icon_001 icon — 200×200 .media/images/icon_001.png rocket
Projektübergreifende Wiederverwendung
Assets werden beim Auflösen automatisch zwischengespeichert. Nachfolgende Auflösungen für denselben Prompt treffen den globalen Cache unter ~/.media/ – kein erneuter Download, kein Provider-Aufruf. Werbe ein Asset explizit mit organize --promote <id>, um es projektübergreifend wiederverwendbar zu machen.
Dateien
.media/manifest.jsonl– maschinelle Single Source of Truth, ein JSON-Eintrag pro Zeile.media/index.md– agentenlesbare Tabelle (id, type, dur, dims, path, description)~/.media/– globaler Cache für projektübergreifende Wiederverwendung (content-addressed, SHA-256)
Verwendete CLI-Werkzeuge
| Werkzeug | Zweck | Erforderlich? |
|---|---|---|
ffprobe | Dauer, Abmessungen, Codec beim Übernehmen ermitteln | Ja |
heygen | Audiokatalog, Assetsuche | Für Anbieter |
Installiere die heygen-CLI (einzelne statische Binärdatei, keine Laufzeit) und authentifiziere dich:
curl -fsSL https://static.heygen.ai/cli/install.sh | bash # installiert neueste Version nach ~/.local/bin
heygen update # falls bereits installiert: benötigt >= v0.1.6
export HEYGEN_API_KEY=<your-key> # oder: heygen auth login --key <key>
Erfordert heygen >= v0.1.6 – die Anbieter versehen Anfragen mit dem zugelassenen Flag --headers 'X-HeyGen-Client-Source: media-use', das in v0.1.6 hinzugefügt wurde. asset search ist ein Vorab-Befehl, der in heygen --help versteckt ist, aber läuft. Ohne heygen im PATH (oder einen gültigen Schlüssel) geben die Anbieter eine einzeilige Diagnose an stderr aus und die Auflösung fällt auf „kein Anbieter konnte auflösen" zurück.