media-use
Résout les besoins média en fichiers locaux gelés. Un seul verbe, quatre types, zéro bruit contextuel.
Quand l'utiliser
Appelez resolve dès qu'une composition a besoin de média — musique de fond, effets sonores, images ou icônes. media-use parcourt le catalogue HeyGen, télécharge la meilleure correspondance, la gèle localement et l'enregistre dans un manifeste. L'agent reçoit une seule ligne ; tout le bruit de recherche reste sur le disque.
Resolve
node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
Renvoie une ligne : resolved <id> → <path> (<type>, <metadata>)
Types
| Type | Ce qu'il trouve | Fournisseur |
|---|---|---|
bgm | Musique de fond | Catalogue audio HeyGen (10k+ pistes) |
sfx | Effets sonores | Bibliothèque intégrée 19 fichiers + catalogue HeyGen |
image | Photos, fonds | Recherche d'assets HeyGen (75k+ vecteurs) |
icon | Icônes, logos | Recherche d'assets HeyGen (type=icon) |
Exemples
# Musique de fond
node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "lancement tech dynamique" --project .
# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)
# Effet sonore
node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "souffle" --project .
# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
# Image
node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "fond tech dégradé" --project .
# → resolved image_001 → .media/images/image_001.jpg (image)
# Icône
node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "fusée" --project .
# → resolved icon_001 → .media/images/icon_001.png (icon, transparent)
Flags
| Flag | Description |
|---|---|
--type, -t | Type de média : bgm, sfx, image, icon |
--intent, -i | Ce dont vous avez besoin (langage naturel) |
--entity, -e | Nom d'entité pour correspondance cache (optionnel) |
--project, -p | Répertoire du projet (défaut : .) |
--adopt | Import en masse des assets existants dans le manifeste |
--json | Sortie JSON au lieu d'une ligne de résultat |
Fonctionnement
- Vérifie
.media/manifest.jsonldu projet pour une correspondance exacte de prompt - Analyse le dossier
assets/existant pour des fichiers non enregistrés correspondant au besoin - Vérifie le cache global
~/.media/pour un asset réutilisable - Recherche via le fournisseur (catalogue audio HeyGen, recherche d'assets HeyGen)
- Gèle le fichier dans
.media/<type>/, l'enregistre dans le manifeste, regénèreindex.md
L'agent reçoit une seule ligne. Les candidats, scores, provenance restent sur le disque.
Adopter des projets existants
La plupart des projets HyperFrames ont déjà des assets dans assets/. media-use les adopte :
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 extrait la durée et les dimensions réelles. Pendant la résolution, les fichiers non enregistrés dans assets/ correspondant à l'intention sont adoptés à la volée.
Lecture de l'inventaire
Après resolve ou adopt, lisez .media/index.md pour l'inventaire complet :
# .media · 4 assets
id type dur dims path description
bgm_001 bgm 25s — .media/audio/bgm/bgm_001.mp3 lancement tech dynamique
sfx_001 sfx 0.6s — .media/audio/sfx/sfx_001.mp3 souffle
image_001 image — 1920×1080 .media/images/image_001.jpg fond tech dégradé
icon_001 icon — 200×200 .media/images/icon_001.png fusée
Réutilisation entre projets
Les assets sont automatiquement mis en cache lors de la résolution. Les résolutions ultérieures pour le même prompt utilisent le cache global dans ~/.media/ — pas de re-téléchargement, pas d'appel au fournisseur. Promouvez explicitement un asset avec organize --promote <id> pour le rendre réutilisable dans tous les projets.
Fichiers
.media/manifest.jsonl— SSOT machine, un enregistrement JSON par ligne.media/index.md— tableau lisible par l'agent (id, type, dur, dims, path, description)~/.media/— cache global de réutilisation entre projets (adressé par contenu, SHA-256)
Outils CLI utilisés
| Outil | Objectif | Requis ? |
|---|---|---|
ffprobe | Mesurer durée, dimensions, codec lors de l'adoption | Oui |
heygen | Catalogue audio, recherche d'assets | Pour les fournisseurs |
Installez le CLI heygen (binaire statique unique, sans runtime) et authentifiez-vous :
curl -fsSL https://static.heygen.ai/cli/install.sh | bash # installe la dernière version dans ~/.local/bin
heygen update # si déjà installé : nécessite >= v0.1.6
export HEYGEN_API_KEY=<votre-clé> # ou : heygen auth login --key <clé>
Nécessite heygen >= v0.1.6 — les fournisseurs taguent les requêtes avec le drapeau autorisé --headers 'X-HeyGen-Client-Source: media-use', ajouté dans v0.1.6. asset search est une commande pré-lancement cachée de heygen --help, mais elle fonctionne. Sans heygen dans le PATH (ou une clé valide), les fournisseurs affichent un diagnostic d'une ligne sur stderr et la résolution échoue avec « aucun fournisseur n'a pu résoudre ».