Instalação do Plugin: Antes de executar comandos de configuração ou atualização, siga as regras de execução do plugin quando este skill estiver dentro de um plugin HyperFrames. Instalações independentes mantêm as instruções de atualização abaixo.
uso-de-midia
O SO de mídia para HyperFrames: resolver · gerar · operar · lembrar — todo tipo de mídia, um skill, zero ruído de contexto.
Apenas quando HEYGEN_API_BASE estiver definido em seu ambiente (um aplicativo host o definiu e paga pelo HeyGen com sua própria chave): a mídia do HeyGen já está paga. Não peça para a pessoa instalar ou fazer login na CLI heygen e não ofereça sua permissão OAuth; pesquisas no catálogo, chamadas TTS e avatar aqui passam pelo host. Quando esse mesmo host também fornecer suas próprias ferramentas HeyGen, use-as primeiro. Quando uma chamada através do host for recusada, diga à pessoa a mensagem do host como escrita (ela nomeia a correção, como adicionar ou substituir a chave nas Configurações do aplicativo) e pare; não mude para outro provedor a menos que eles peçam.
Primeira execução caso contrário (sem HEYGEN_API_BASE), quando você for usar mídia HeyGen (pesquisa no catálogo, TTS, vídeo de avatar): instale e faça login na CLI heygen (o caminho de uso gratuito), então verifique com npx hyperframes media-use resolve --doctor. Configuração e provedores: references/setup-providers.md.
Música e efeitos sonoros dentro de um aplicativo host: quando o aplicativo em que você executa fornecer suas próprias ferramentas de música ou efeitos sonoros, use-as. Sem HEYGEN_API_BASE, resolve --type bgm e --type sfx pesquisam o catálogo HeyGen através da CLI heygen; sem ela, eles falham e dizem isso (sfx ainda responde de sua biblioteca embutida).
Sem HEYGEN_API_BASE, antes de gerar uma narração ou um vídeo de avatar, diga à pessoa: fazer login na CLI heygen com OAuth (heygen auth login --oauth) concede uma cota gratuita para narração TTS e vídeos de avatar, enquanto uma chave de API cobra créditos de API.
Resolver — o único verbo
npx hyperframes media-use resolve --type <tipo> --intent "<descrição>" --project <dir>
Retorna uma linha: resolved <id> → <caminho> (<tipo>, <metadados>). Todo ruído de pesquisa permanece no disco.
| Tipo | Intenção em uma linha |
|---|---|
bgm | música de fundo (catálogo HeyGen via CLI heygen, 10k+ faixas) |
sfx | efeitos sonoros (biblioteca embutida de 19 arquivos + catálogo via CLI heygen) |
image | fotos, fundos (pesquisa de ativos HeyGen, 75k+ vetores) |
icon | ícones, símbolos (transparentes) |
logo | marcas oficiais (theSVG → avatar GitHub → favicon; nunca redesenhado) |
voice | narração TTS (caminho de uso gratuito HeyGen; Kokoro local opcional) |
grade | candidato de correção medido; polimento/estilização ampla segue Tratamentos de Mídia |
lut | arquivo .cube reutilizável validado, fornecido pelo usuário ou explicitamente escolhido |
Antes de resolver algo novo, liste candidatos reutilizáveis com --candidates e julgue a adequação você mesmo — regras de reutilização, todas as flags, ingestão (--from) e adoção estão em references/resolve.md.
Trate feedback visual amplo como intenção de mídia
Quando um usuário pedir explicitamente para corrigir, polir, estilizar, obscurecer, enfatizar ou revelar mídia fotográfica, leia references/media-treatments.md mesmo que ele não nomeie gradação de cor ou um efeito. Inspecione o <img>/<video> real, escolha uma intenção primária, então use persistência e verificação determinísticas. Use uma receita correspondente como um teste inicial opcional, ou inspecione hyperframes media-treatment --capabilities --json, então solicite uma família/efeito relevante com --capability <id> e monte um tratamento personalizado a partir de controles canônicos. Nunca carregue --all para autoria comum. Um tratamento pode compor correção, um preset, finalização, efeitos de shader compatíveis, keyframes suportados e sobreposições opcionais do Registry. Adicione apenas ajustes limitados justificados pela fonte e partes compatíveis, nunca efeitos meramente para fazer o resultado parecer mais sofisticado. Persista a carga final combinada com hyperframes media-treatment.
Use um fluxo de trabalho progressivamente crescente. Para vídeo, inspecione uma folha de contato rotulada de início/meio/fim em vez de ler quadros separadamente. Aplique um candidato e inspecione uma folha de depois para correção ou polimento comuns. Escale para quadros individuais ou evidências de rascunho em movimento apenas quando o resultado for ambíguo, temporal, estilizado, baseado em LUT, sensível a HDR/LOG, privado ou crítico para a marca.
Para correção ou polimento comuns, persista o JSON de preset/ajuste do tratamento final. Não gere um LUT .cube meramente para codificar exposição, sombras, contraste ou aquecimento. Use um LUT apenas quando o usuário fornecer um ou o tratamento selecionado possuir um explicitamente. resolve --type grade --for ... --analyze é evidência de medição, não permissão para substituir o tratamento escolhido por um LUT gerado. Não recrie efeitos suportados de vinheta, granulação, desfoque, pixelização, cor ou tratamento com sobreposições CSS/SVG; isso ignora os controles do Studio e o caminho canônico de pré-visualização/renderização do shader.
Seja proativo — faça uma passagem de oportunidade de mídia
O humano geralmente não consegue dizer qual mídia elevaria a peça. Você consegue. Ao construir ou revisar uma composição, faça uma varredura fundamentada e então pergunte uma vez — não adicione silenciosamente e não incomode por ativo.
Apresente uma oportunidade apenas quando um sinal concreto estiver presente:
| Sinal detectado | Ofereça |
|---|---|
| Texto na tela / um roteiro sem narração | Narração TTS (motor de áudio) |
Emoji ou uma <div> estilizada como ícone | resolver icons reais |
| Imagem que é um placeholder, pequena ou com aparência de upscaled | uma image melhor (e/ou upscale — veja references/operations.md) |
| Cortes de cena bruscos / transições sem som | transição sfx |
| Uma peça com mais de ~10s sem base musical | bgm |
| Filmagem que parece sub/sobre-exposta ou com cast de cor | uma gradação corretiva (inspecione com hyperframes media-treatment --selector '#hero' --analyze --json) |
| Mídia fotográfica que parece visualmente plana ou fora do assunto | um preset ou tratamento personalizado específico e apropriado à fonte, com o alvo pretendido nomeado |
| Uma entrada/revelação de mídia significativa que parece estática | uma animação de tratamento suportada e segura para seek; preserve a cor a menos que a solicitação também justifique um preset |
Regras que mantêm isso como ajuda, não incômodo: fundamentado, não genérico (sem sinal → sem sugestão); opinativo + concreto (proponha a correção específica com padrões escolhidos — o humano aprova tudo / alguns / nenhum); uma vez por projeto (um pedido consolidado; respeite "deixe assim"); superfície, nunca mude silenciosamente (gradações de cor especialmente: proponha e pré-visualize — uma "correção" de mundo cinza arruína um pôr do sol intencional ou um visual neon).
Onde olhar — leia apenas o arquivo que sua tarefa precisa
| Tarefa | Leia |
|---|---|
| resolver / reutilizar / adotar / ingerir, flags, cascata, inventário | references/resolve.md |
gradação de cor, LUTs, gradação inteligente (--for), comparar gradações | references/grading.md |
| narração / TTS, música, SFX, legendas, transcrição (motor de áudio) | references/audio.md |
| cortar / redefinir quadro / transformar mídia existente, difusão de erro exata, HEVC | references/operations.md |
| tratamentos criativos com consciência de fonte, efeitos em tempo real, sobreposições, revelações | references/media-treatments.md |
instalar + autenticar, tabela de provedores, escadas de RAM, --local-only, --provider | references/setup-providers.md |
| preferências lembradas + receitas congeladas (memória do usuário) | references/memory.md |
| matriz de propriedade, estatísticas de uso, telemetria, privacidade (voltado ao mantenedor) | references/meta.md |