media-use
Resolva necessidades de mídia em arquivos locais congelados. Um verbo, quatro tipos, zero ruído de contexto.
Quando usar
Chame resolve sempre que uma composição precisar de mídia — música de fundo, efeitos sonoros, imagens ou ícones. media-use pesquisa no catálogo do HeyGen, baixa a melhor correspondência, congela-a localmente e a registra em um manifesto. O agente recebe apenas uma linha; todo o ruído das buscas permanece no disco.
Resolve
node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
Retorna uma linha: resolved <id> → <path> (<type>, <metadata>)
Tipos
| Tipo | O que encontra | Provedor |
|---|---|---|
bgm | Música de fundo | Catálogo de áudio HeyGen (10k+ faixas) |
sfx | Efeitos sonoros | Biblioteca com 19 arquivos + catálogo HeyGen |
image | Fotos, fundos | Pesquisa de ativos HeyGen (75k+ vetores) |
icon | Ícones, logos | Pesquisa de ativos HeyGen (tipo=icon) |
Exemplos
# Música de fundo
node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "lançamento tech animado" --project .
# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)
# Efeito sonoro
node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
# Imagem
node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "fundo tech gradiente" --project .
# → resolved image_001 → .media/images/image_001.jpg (image)
# Ícone
node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "foguete" --project .
# → resolved icon_001 → .media/images/icon_001.png (icon, transparente)
Flags
| Flag | Descrição |
|---|---|
--type, -t | Tipo de mídia: bgm, sfx, image, icon |
--intent, -i | O que você precisa (linguagem natural) |
--entity, -e | Nome da entidade para correspondência de cache (opcional) |
--project, -p | Diretório do projeto (padrão: .) |
--adopt | Importar em lote ativos existentes de assets/ para o manifesto |
--json | Saída em JSON em vez de resultado em uma linha |
Como funciona
- Verifica o manifesto do projeto
.media/manifest.jsonlpor correspondência exata de prompt - Escaneia o diretório
assets/existente em busca de arquivos não registrados que correspondam à necessidade - Verifica o cache global
~/.media/por ativos reutilizáveis - Pesquisa via provedor (catálogo de áudio HeyGen, pesquisa de ativos HeyGen)
- Congela o arquivo em
.media/<type>/, registra no manifesto, regeneraindex.md
O agente recebe apenas uma linha. Candidatos, scores e proveniência permanecem no disco.
Adotar projetos existentes
A maioria dos projetos HyperFrames já possui ativos em assets/. media-use os adota:
node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
# → adotados 9 ativos de assets/
# bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)
# image_001 → assets/images/avatar.jpg (image, 400×400)
ffprobe extrai duração e dimensões reais. Durante o resolve, arquivos não registrados em assets/ que correspondem à intenção são adotados dinamicamente.
Lendo o inventário
Após o resolve ou adopt, leia .media/index.md para o inventário completo:
# .media · 4 ativos
id tipo dur dims caminho descrição
bgm_001 bgm 25s — .media/audio/bgm/bgm_001.mp3 lançamento tech animado
sfx_001 sfx 0.6s — .media/audio/sfx/sfx_001.mp3 whoosh
image_001 image — 1920×1080 .media/images/image_001.jpg fundo tech gradiente
icon_001 icon — 200×200 .media/images/icon_001.png foguete
Reutilização entre projetos
Os ativos são armazenados em cache automaticamente no resolve. Resolves subsequentes para o mesmo prompt atingem o cache global em ~/.media/ — sem novo download, sem chamada ao provedor. Promova um ativo explicitamente com organize --promote <id> para torná-lo reutilizável em todos os projetos.
Arquivos
.media/manifest.jsonl— fonte única da verdade para máquinas, um registro JSON por linha.media/index.md— tabela legível por agentes (id, tipo, dur, dims, caminho, descrição)~/.media/— cache global de reutilização entre projetos (endereçado por conteúdo, SHA-256)
Ferramentas CLI usadas
| Ferramenta | Finalidade | Obrigatório? |
|---|---|---|
ffprobe | Extrair duração, dimensões, codec no adopt | Sim |
heygen | Catálogo de áudio, pesquisa de ativos | Para provedores |
Instale a CLI heygen (binário estático único, sem runtime) e autentique:
curl -fsSL https://static.heygen.ai/cli/install.sh | bash # instala a versão mais recente em ~/.local/bin
heygen update # se já instalado: precisa >= v0.1.6
export HEYGEN_API_KEY=<sua-chave> # ou: heygen auth login --key <key>
Requer heygen >= v0.1.6 — os provedores marcam as requisições com o cabeçalho --headers 'X-HeyGen-Client-Source: media-use', adicionado na v0.1.6. asset search é um comando pré-lançamento oculto do heygen --help, mas funciona. Sem heygen no PATH (ou sem uma chave válida), os provedores imprimem um diagnóstico de uma linha no stderr e o resolve recai para "nenhum provedor pôde resolver".