Kit de Vídeo para Lançamento SaaS (HyperFrames Audio)

Instalação de plugins: Antes dos comandos de configuração ou atualização, siga as regras de execução de plugins quando este skill estiver dentro de um plugin HyperFrames. Instalações independentes mantêm as instruções de atualização abaixo.

HyperFrames Audio

Uma mixagem é um conjunto de relacionamentos, não uma pilha de processadores. Duas faixas que soam bem sozinhas podem ser inaudíveis juntas, e a correção quase nunca é "abaixar uma" — é encontrar aquilo pelo qual elas estão competindo e dar para aquela que mais precisa. Cada ferramenta aqui existe para expressar um desses relacionamentos.

Os efeitos residem no elemento como data-fx-chain, e a visualização e a renderização executam o mesmo grafo de Web Audio — o estúdio em um contexto ao vivo, o motor em um offline dentro do navegador que ele já dirige. Há uma única implementação de cada efeito, então o que você ouve ao depurar é o que é gravado. Você nunca ajusta duas vezes.

A temporização de clipes permanece com /hyperframes-core: cortes de áudio/vídeo e intervalos de origem usam data-start, data-duration e data-media-start, e crossfades sobrepõem clipes em faixas diferentes. Este skill é responsável por fade-in/fade-out de faixas posicionadas, envelopes de crossfade, ganho/volume de faixa, automação de volume e efeitos, ducking/escultura de narração e a cadeia de efeitos. /media-use é responsável por sourcing, geração e pré-processamento.

A constante data-playback-rate (0.1..10) é segura para renderização de imagem e som com preservação de tom quando elementos de áudio/vídeo correspondentes usam a mesma temporização, deslocamento de origem e taxa. Uma rampa de velocidade é uma pista rate em data-automation (veja docs/reference/speed-ramps); ela prevalece sobre a constante e mantém o tom na visualização e na renderização. HyperFrames não fornece sincronização automática de forma de onda ou correção de deriva. Para receitas copiáveis de corte/crossfade/re-temporização, use /hyperframes-core → references/creator-editing-recipes.md.

Três atributos carregam tudo, no próprio elemento de áudio/vídeo — ou, para os dois primeiros, em um barramento <hf-audio-group> (veja "Um barramento para muitas faixas"):

Atributo	Contém
data-fx-chain	os efeitos, em ordem de sinal
data-automation	envelopes no volume desta faixa ou em seus parâmetros de efeito
data-fx-carve	as configurações da própria escultura, para que possa ser re-derivada

As famílias de efeitos fornecidas são ganho, EQ (passa-altas, passa-baixas, pico, prateleiras), compressor, limitador, gate, saturar, delay, reverb, chorus, phaser e bitcrush.

JSON exato para cada um, e as regras que uma pista deve satisfazer: references/attributes.md. Cada efeito com seus parâmetros, intervalos e unidades: references/fx-registry.md. Como descobrir o que há de errado com um arquivo que você não pode ouvir: references/diagnosis.md. Predefinições, trabalhos nomeados e perfis de um botão, além de uma tabela de sintoma para correção: references/presets.md — leia isso antes de construir uma cadeia manualmente, porque uma das predefinições ou trabalhos nomeados geralmente já nomeia o problema.

Como tudo se encaixa

Duas superfícies de autoria escrevem esses atributos; dois tempos de execução os leem através dos mesmos construtores. Esse meio compartilhado é o motivo pelo qual a visualização prevê a renderização.

flowchart TB
  voice["faixa de voz<br/>arquivo de mídia"]
  bed["fundo musical<br/>arquivo de mídia"]

  subgraph AUTORIA["Autoria — as únicas coisas que escrevem atributos"]
    panel["Studio<br/>Controle de escultura de narração"]
    script["scripts/carve.mjs<br/>detecta o par, dinâmico por padrão"]
    analysis["core/audioCarve.ts<br/>carveProfile · analyseCarveBands<br/>analyseCarveDuck · analyseCarveDynamics"]
    panel --> analysis
    script --> analysis
  end

  voice --> analysis
  bed --> analysis

  subgraph ATRIBUTOS["Escrito no elemento do fundo musical"]
    carveAttr["data-fx-carve<br/>source · strength · dynamic"]
    chainAttr["data-fx-chain<br/>peaking xN + gain, marcado fromCarve"]
    autoAttr["data-automation<br/>uma pista por parâmetro esculpido"]
  end

  analysis --> carveAttr
  analysis --> chainAttr
  analysis --> autoAttr

  subgraph COMPARTILHADO["Uma implementação, lida por ambos"]
    build["audioFxGraph.ts · buildFxChain"]
    sched["audioFxAutomation.ts · scheduleChainAutomation"]
  end

  chainAttr --> build
  autoAttr --> sched

  build --> preview["Visualização<br/>AudioContext ao vivo<br/>attachElementFxChain"]
  sched --> preview
  build --> render["Renderização<br/>OfflineAudioContext no navegador headless<br/>applyAudioFxChain"]
  sched --> render

  preview --> ouvido["o que você ouve enquanto depura"]
  render --> wav["WAV processado<br/>+ chainTailSeconds para que a mixagem deixe passar a cauda"]
  wav --> mix["motor · audioMixer<br/>pista de volume integrada no PCM aqui, não no grafo"]
  mix --> saida["a mixagem renderizada"]

  edit["editar o atributo durante a reprodução"] -.->|MutationObserver| preview

As configurações da própria escultura nunca são lidas durante a reprodução — a cadeia e as pistas que ela produziu são o que é reproduzido. data-fx-carve existe para que a força possa ser alterada em uma escultura existente, em vez de ser adivinhada de volta a partir dos filtros.

Dentro de um fundo musical esculpido, o sinal passa primeiro pelas reduções, depois pelo ajuste de nível, e depois por tudo que você mesmo construiu — razão pela qual um limitador que você adiciona ainda atua como o último teto:

flowchart LR
  src["fundo musical decodificado"] --> p1["pico<br/>400 Hz"]
  p1 --> p2["pico<br/>1 kHz"]
  p2 --> p3["pico<br/>1.6 kHz"]
  p3 --> g["ganho<br/>ajuste de nível"]
  g --> mao["seus próprios efeitos<br/>ex. limitador"]
  mao --> dest["ganho da faixa, então saída"]

  l1["pista fx.n1.gain"] -.->|"envelope do nível<br/>da voz nessa banda"| p1
  l4["pista fx.n4.gain"] -.->|"o quanto o fundo<br/>abaixa no geral"| g

Uma escultura estática é o mesmo grafo com valores fixos e nenhuma pista.

Primeiro, descubra o que está errado

A tabela abaixo parte de "soa encorpado" — o que pressupõe que alguém já ouviu e disse isso. Recebendo um arquivo e "conserta isso", você não tem essa frase e não pode ouvir, então você tem que medir. Uma regra governa tudo:

O espectro absoluto de uma única voz desconhecida não pode ser diagnosticado. Formantes são ±10 dB, fundamentais variam de 85–255 Hz, e as frases caem 5–6 dB conforme terminam. Cada um desses sinais parece um defeito por si só, e todos eles são o falante.

Então compare, e compare com algo dentro do mesmo arquivo: o original limpo se existir, caso contrário, as pausas — o que for audível em um silêncio é aditivo, e o espectro do silêncio é o canal, não a voz. Comparar com um espectro médio publicado ou uma voz de controle sintetizada não funciona: dois falantes diferem mais do que a maioria dos defeitos, e ambas as respostas erradas na avaliação por trás desta orientação vieram exatamente disso.

Quando não há original nem silêncio utilizável, um defeito tonal estático é genuinamente subdeterminado. Diga isso e ofereça as leituras que se encaixam, em vez de escolher uma e construir uma cadeia nela.

Comandos, armadilhas e receitas práticas: references/diagnosis.md. Leia-o antes de diagnosticar um arquivo que ninguém descreveu.

Comece pelo sintoma

Depois de saber a banda e o tipo, nomeie o que está errado com o áudio. A maioria dos áudios ruins é um ou dois destes, e cada um tem uma resposta fornecida:

Soa como	Use
Zumbido ou pulsação por baixo	rumble-cut, ou um highpass a 80 Hz
Encorpado, peito	Tame Boominess job (200 Hz)
Abafado, atrás de papelão	Reduce Mud job (250 Hz)
Palavras difíceis de entender	Add Clarity job (3 kHz), ou esculpa o fundo
Áspero e cansativo	Soften Harshness job (3.2 kHz)
Algumas palavras muito mais altas	Evenness em um compressor, ou Even Out Levels
Tom da sala entre as frases	room-gate
Voz e música competindo	Escultura de narração — não um EQ em nenhum
Seco, gravado em lugar nenhum	room-tight ou room-natural
Apenas "amador"	voice-clean, que é quatro dos acima em ordem

Catálogo completo, o que cada predefinição contém, o vocabulário de bandas e o que é deliberadamente NÃO COBERTO (de-essing, remoção de ruído, correspondência de tom): references/presets.md.

Subtraia antes de adicionar, nivele depois de filtrar, relacionamentos depois do nível, caráter e teto por último. Cada passo muda o que o próximo ouve — um compressor configurado antes de um passa-altas gasta seu tempo perseguindo ruído de baixa frequência.

Use uma família pelo problema, não pelo nome

Filtros (highpass, lowpass, peaking, lowshelf, highshelf) decidem quais frequências uma faixa pode ocupar. Esta é a primeira ferramenta para duas fontes colidindo, porque as colisões acontecem em bandas: um fundo e uma voz querem ambos 1–3 kHz, e tirar isso do fundo custa muito menos ao fundo do que abaixar tudo custa à mixagem. Um passa-altas em uma voz é a correção padrão para ruído de baixa frequência; um passa-baixas escurece ou abafa deliberadamente.

Dinâmicas (gain, compressor, limiter, gate) decidem como o nível de uma faixa se comporta ao longo do tempo. A compressão reduz a distância entre o alto e o baixo para que as partes baixas possam subir. Um limitador é um teto — ele não molda nada, ele garante que nada ultrapasse. Um gate remove o que está abaixo de um limite, que é como você silencia o tom da sala entre as frases. gain é um estágio de nível simples, e é o que uma pista de automação usa quando uma faixa precisa sair do caminho.

Não lineares (saturate, bitcrush) mudam a forma da forma de onda, o que adiciona harmônicas que não estavam lá. Use quando uma faixa precisa de caráter ou aspereza em vez de correção — e lembre-se de que é generativo: torna uma fonte fina mais densa, não mais limpa.

Tempo (delay, reverb, chorus, phaser) coloca uma faixa em um espaço ou dá largura a ela. Estes são os que mais facilmente estragam uma mixagem, porque uma cauda ou uma cópia desafinada ocupa o mesmo espaço que uma voz precisa. Use-os na coisa que deve ficar atrás de outra coisa, e mantenha a quantidade de efeito mais baixa do que soa correto isoladamente.

A cadeia é serial: cada efeito processa o que o anterior produziu. Portanto, a filtragem corretiva vai no início, o caráter no meio, e um limitador por último, onde pode realmente atuar como um teto.

Escultura de narração

O problema que resolve. Um fundo musical sob uma voz torna a voz difícil de acompanhar. O reflexo é abaixar todo o fundo, o que funciona, mas custa ao fundo toda a sua presença — a música fica letárgica durante toda a narração. Mas a voz não precisa de todo o espectro. Ela precisa das poucas bandas que realmente ocupa. A escultura tira apenas essas, e o fundo mantém seus graves e agudos, então ainda é música enquanto a voz ainda é inteligível.

É um relacionamento, não um efeito. As configurações residem no fundo — a faixa que é processada — e nomeiam as vozes para ouvir, exatamente como um compressor sidechain faz: você seleciona a faixa que fica mais baixa e escolhe o que a torna mais baixa. Nunca coloque uma escultura em uma faixa de voz. Uma voz esculpida contra si mesma é um bug, não uma escolha sutil de mixagem.

Todas as vozes, não apenas uma. sources é uma lista, porque um fundo geralmente roda sob uma sequência inteira — um narrador, uma resposta de entrevista, um segundo apresentador. Eles são somados no relógio do próprio fundo antes que qualquer coisa seja medida (mixCarveSources), então uma análise cobre todos eles: as bandas vêm de toda a fala que existe, e os envelopes sobem onde quer que qualquer uma delas esteja acontecendo. Vozes que nunca tocam enquanto o fundo está são deixadas de fora; elas não podem mascará-lo.

Uma escultura contra mais de um id de clipe está errada. Agrupe os clipes e esculpa contra o grupo. Isso é um invariante, não uma dica. Nomear clipes um por um tem que estar exaustivamente correto e permanece correto apenas até a próxima edição — um quarto clipe de narração adicionado posteriormente toca fora do conhecimento da escultura, e o fundo falha em abaixar silenciosamente sob ele. Nomear o grupo resolve a associação no momento da análise, então um clipe adicionado ao grupo posteriormente é coberto sem tocar em sources:

<!-- agrupe a narração, depois esculpa o fundo contra o grupo -->
<audio id="vo-intro" data-audio-group="voiceover" …></audio>
<audio id="vo-middle" data-audio-group="voiceover" …></audio>
<audio id="vo-outro" data-audio-group="voiceover" …></audio>

<audio id="music" data-fx-carve='{"enabled":true,"sources":["voiceover"],"strength":0.8}' …></audio>

Uma lista sources nomeando dois ou mais ids de clipe simples em vez de um grupo é capturada pela regra de lint audio_carve_ungrouped_sources — ainda funciona, mas é a versão que apodrece silenciosamente quando um clipe é adicionado.

Mantenha o grupo de escultura um grupo de voz: sem fundo, sem SFX, sem música. Um id de grupo em sources resolve para cada membro atual em cada análise, então o grupo que você nomeia é o grupo que você obtém depois — não as faixas que foram medidas quando foi escrito. Duas maneiras que isso prejudica:

• O fundo em seu próprio grupo de origem. Ele é entregue a si mesmo como uma voz e esculpido contra seu próprio conteúdo — a regra "nunca esculpir uma faixa contra si mesma" chegando uma re-análise depois.
• Um clipe de SFX ou música no grupo de voz. Ele entra no sidechain na próxima análise e o fundo começa a abaixar sob um assobio, mesmo que a execução que escreveu o atributo nunca o tenha medido.

Ambos são invisíveis no momento em que a escultura é escrita: a análise soma as vozes que detectou e nunca percorre a resolução do grupo, então a primeira passagem é genuinamente correta e apenas a próxima é errada. Portanto, dê a cada função seu próprio grupo — music para o fundo, voiceover para a narração, sfx para os efeitos — e mantenha o grupo nomeado em sources contendo apenas vozes.

carve.mjs recusa-se a escrever a forma de grupo quando vê qualquer um dos casos, registra ids de clipe e diz

...