uso-de-midia
O sistema operacional de mídia para HyperFrames: resolver · gerar · operar · lembrar — cada tipo de mídia, uma habilidade, zero ruído de contexto.
Primeira execução: instale e faça login na CLI heygen (o caminho de uso gratuito) e depois verifique com npx hyperframes media-use resolve --doctor. Configuração e provedores: references/setup-providers.md.
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 o ruído de pesquisa permanece em disco.
| Tipo | Intenção em uma linha |
|---|---|
bgm | música de fundo (catálogo HeyGen, 10k+ faixas) |
sfx | efeitos sonoros (biblioteca integrada de 19 arquivos + catálogo) |
image | fotos, fundos (pesquisa de ativos HeyGen, 75k+ vetores) |
icon | ícones, símbolos (transparentes) |
logo | marcas oficiais (theSVG → avatar do GitHub → favicon; nunca redesenhado) |
voice | narração TTS (caminho de uso gratuito HeyGen; Kokoro local opcional) |
grade | candidato a 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 do zero, liste candidatos reutilizáveis com --candidates e julgue você mesmo a adequação — regras de reutilização, todas as flags, ingestão (--from) e adoção estão em references/resolve.md.
Tratar 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
mencione gradação de cor ou um efeito. Inspecione o <img>/<video> real,
escolha uma intenção primária e use persistência e verificação determinísticas.
Use uma receita correspondente como semente testada opcional, ou inspecione
hyperframes media-treatment --capabilities --json e solicite uma família/efeito relevante
com --capability <id> e monte um tratamento personalizado a partir de
controles canônicos. Nunca carregue --all para criação comum. Um tratamento pode
compor correção, uma predefinição, 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 apenas para fazer o resultado parecer
mais sofisticado. Persista o payload final combinado com
hyperframes media-treatment.
Use um fluxo de trabalho progressivamente escalonado. Para vídeo, inspecione uma folha de contato rotulada de início/meio/fim em vez de ler frames separadamente. Aplique um candidato e inspecione uma folha posterior para correção ou polimento comum. Escalone para frames 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 comum, persista o JSON de predefinição/ajuste final do tratamento.
Não gere um LUT .cube meramente para codificar exposição, sombras, contraste ou
calor. Use um LUT apenas quando o usuário fornecer um ou o tratamento selecionado
explicitamente possuir um. 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 de vinheta, granulação, desfoque, pixelização, cor ou tratamento
suportados com sobreposições CSS/SVG; isso ignora os controles do Studio e o caminho
canônico de shader de pré-visualização/renderização.
Seja proativo — execute uma passagem de oportunidade de mídia
O humano geralmente não consegue dizer qual mídia melhoraria a peça. Você consegue. Ao construir ou revisar uma composição, faça uma varredura fundamentada e depois pergunte uma vez — não adicione silenciosamente e não incomode por ativo.
Ofereça uma oportunidade apenas quando um sinal concreto estiver presente:
| Sinal detectado | Oferecer |
|---|---|
| Texto na tela / um roteiro sem narração | Narração TTS (mecanismo de áudio) |
Emoji ou uma <div> estilizada como ícone | resolver icons reais |
| Imagem que é um placeholder, miniatura ou com aparência de upscaled | uma image melhor (e/ou upscale — veja references/operations.md) |
| Cortes de cena / transições sem som | sfx de transição |
| Uma peça com mais de ~10s sem base musical | bgm |
| Filmagem que parece super/subexposta ou com dominante 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 | uma predefinição ou tratamento personalizado específico e adequado à fonte, com o alvo pretendido nomeado |
| Uma entrada/revelação de mídia significativa que parece estática | uma animação de tratamento compatível com busca; preserve a cor, a menos que a solicitação também justifique uma predefinição |
Regras que mantêm isso como uma ajuda, não um incômodo: fundamentado, não genérico (nenhum sinal → nenhuma 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 como está"); superfície, nunca mude silenciosamente (especialmente gradações de cor: 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 | Ler |
|---|---|
| resolver / reutilizar / adotar / ingerir, flags, cascata, inventário | references/resolve.md |
gradação de cor, LUTs, gradação inteligente (--for), comparar gradação | references/grading.md |
| narração / TTS, música, SFX, legendas, transcrição (mecanismo de áudio) | references/audio.md |
| cortar / reenquadrar / transformar mídia existente, difusão de erro exata, HEVC | references/operations.md |
| tratamentos criativos conscientes da fonte, efeitos em tempo real, sobreposições, revelações | references/media-treatments.md |
instalar + autenticação, 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 (para mantenedores) | references/meta.md |