Roteiro e voz
A voz é o relógio do vídeo. Cada batida da animação está ancorada a uma palavra da
narração (T[clip] + w(clip, "word") no build.py), então o roteiro e seus clipes vêm antes da
animação, e alterar uma frase regenera um clipe e reajusta o tempo de tudo que vem depois. Na
produção de onde estas skills vêm, trocar o motor TTS inteiro reajustou um vídeo finalizado sem
edições manuais por causa desse design. Animar primeiro e encaixar a voz depois significa
esticar áudio ou arrastar batidas manualmente a cada alteração.
Escreva apenas sob <video_dir>/audio/ (mais a seção de roteiro do BRIEF.md). Toda frase deve
ser respaldada no TRUTH.md e respeitar o CLAIMS.md; se uma frase que você precisa não tem fonte,
peça para ser verificada ou corte-a.
Roteiros, chamados conforme docs/contracts.md:
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
S="$PVS_HOME/skills/script-and-voice/scripts"
"$PVS_HOME/bin/pvs-py" "$S/check_script.py" <video_dir> # lint no lines.tsv
"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir> [--only N3,N4] [--provider say] [--force] [--restore]
"$PVS_HOME/bin/pvs-py" "$S/pronounce_check.py" <video_dir> [--only N3] # o ASR ouviu as palavras da marca?
"$PVS_HOME/bin/pvs-py" "$S/make_sfx.py" <video_dir> [--list] # sfx.tsv, ou lista a biblioteca
1. O roteiro é uma tabela de momentos
Uma gravação do produto é uma referência, não uma linha do tempo: tempos de carregamento reais e mudanças de tela não pertencem ao vídeo. Escreva o roteiro como momentos, cada um com o que acontece na tela, a frase (ou silêncio) e quanto tempo dura. Um momento dura o que for maior entre sua ação e sua frase. Comprima esperas reais: quarenta segundos de carregamento viram cerca de dois segundos de um estado de pensamento.
Adicione a tabela ao BRIEF.md sob ## Script, na ordem dos capítulos:
| Momento | Na tela | Linha | Texto (ou silêncio) | Segura |
|---|---|---|---|---|
| Abertura | Nome do produto sobre o app desfocado | N1 | Este é o Acme Tasks, a lista de tarefas que planeja seu dia. | 0.8 s depois |
| Espera | O plano está sendo construído | (silêncio) | 2.0 s |
Depois escolha o template para o formato do vídeo e siga sua estrutura: leia
references/script-templates.md (pitch, tour, página de docs, tutorial, loop silencioso).
Como escrever as linhas, e por quê:
- Explique os recursos importantes; não os liste. Diga o que um recurso faz para o espectador enquanto a IU o faz. Na produção de onde estas skills vêm, 9 de 26 versões aconteceram porque um vídeo nomeou um recurso sem explicá-lo. COVERAGE.md diz quais recursos devem ser explicados na tela: toda linha marcada como "must explain" precisa de pelo menos uma linha que o explique.
- Explique cada passo para alguém que nunca viu o produto. Quem é o personagem, o que ele pede, o que cada passo faz. Uma abertura rápida e não explicada foi rejeitada na revisão.
- Uma ideia por frase e uma frase por clipe. Uma frase alterada custa então um clipe.
- Nomeie o que o cursor toca no momento em que toca. As batidas ancoram nessas palavras, então o substantivo na tela e a palavra no clipe devem ser os mesmos.
- Use o rótulo real da IU, mesmo quando o revisor usa outra palavra para ele. O vídeo então corresponde ao que o espectador verá no produto.
- Escreva números e horários por extenso ("dez da manhã", "trinta minutos depois"). Motores TTS leem dígitos de forma inconsistente e a comparação de fala para texto compara palavras, não dígitos.
- Deixe ar ao redor de esperas. Cerca de três segundos antes de um telefone tocar, "cerca de um minuto" em vez de um número preciso que ninguém pode verificar.
- Termine com uma frase completa, lida um pouco mais devagar. Um fragmento de slogan como última linha soou cortado na revisão; uma frase completa com o posicionamento do CLAIMS.md não.
- Mantenha a pessoa consistente dentro de um vídeo: primeira pessoa como o usuário fictício ("Primeiro, conecto minha agenda.") ou terceira pessoa sobre ele. Use apenas o elenco fictício de product.yaml, com o mesmo nome em todos os vídeos.
- O posicionamento vem do CLAIMS.md, não dos documentos fonte: um documento fonte pode conter uma frase que a equipe baniu, e a regra vence.
2. lines.tsv
audio/lines.tsv, separado por tabulação, cabeçalho id role speed text, um clipe por linha em
ordem de reprodução, linhas com # são comentários. Formato completo e como o build.py lê o
resultado: references/audio-formats.md.
- id:
N1,N2,N7bpara narração; outras letras para personagens (A1para um agente,C1para um cliente). Inserir uma linha entre N7 e N8 comoN7bmantém todos os outros ids, e todas as âncoras que os usam, estáveis. - role: uma chave de
voice.rolesem product.yaml (narrator,agent,customer, ou uma variante de leitura comonarrator_close, veja seção 3). O papel, não o id, escolhe a voz. - speed: 1.0 por padrão, 0.7 a 1.2. Use 0.9 a 0.96 para as linhas de abertura e fechamento.
- text: exatamente como aparece na tela e nas legendas, com a grafia canônica dos nomes de produtos. Nunca escreva uma respelling aqui; a pronúncia vive em product.yaml.
Antes de alterar linhas de uma versão entregue, copie lines.tsv para lines-v<N>.tsv e
timings.json para timings-v<N>.json, para que a versão anterior possa ser reconstruída.
Execute check_script.py após cada edição. Ele falha em ids duplicados, papéis desconhecidos,
velocidades fora do intervalo, clipes com mais de 40 palavras, termos banidos, frases never_say,
nomes legados e respellings no roteiro, e avisa sobre clipes longos, dígitos e travessões.
Corrija todos os erros antes de vocalizar: uma frase banida que chega ao TTS custa uma tomada,
e uma que chega a um render custa uma versão.
3. Elenco
Leia references/casting-and-pronunciation.md antes de propor vozes. Em resumo:
- Ofereça vozes realistas primeiro. A voz padrão do próprio produto e os modelos mais baratos foram julgados "muito falsos" na revisão; o modelo mais natural disponível vale a pena para personagens.
- Faça audições no contexto: duas linhas consecutivas reais por papel, três a seis candidatos por papel.
- Proponha cada escolha para veto como uma pergunta fechada com um padrão recomendado ("Narrador: voz B, calorosa e sem pressa. Manter?"). Listas abertas de opções ficaram sem resposta por dias.
- Decida o tratamento por papel:
treatment: phonepara alguém em uma chamada,treatment: roompara uma reunião gravada, nada para o narrador. - Uma leitura por linha (mais estável, mais lenta, menos estilo) é uma variante de papel que aponta para a mesma voz com outras configurações, então a escolha está na configuração e sobrevive a uma reexecução.
voice.provider: say (ou --provider say) usa a voz gratuita do macOS e whisper para timings
de palavras. Use para rascunhos, testes e trabalho de timing antes de existir uma chave;
entregue com a voz real.
4. Gere os clipes
"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir>
Para cada linha, ele respella as palavras da marca apenas para o TTS, mantém a tomada intacta em
audio/raw/ (a tomada anterior vai para audio/raw/prev/), corta silêncio, reamostra para 48 kHz
mono, aplica o tratamento do papel, normaliza para voice.clip_lufs (ffmpeg loudnorm, duas
passadas; picos abaixo de -1.5 dBTP), desvanece ambas as bordas e mescla a entrada do clipe
em audio/timings.json.
Por que cada etapa de processamento existe:
- Tomadas brutas são sempre arquivadas e sempre a fonte. Um cliente anterior normalizou a partir de um arquivo bruto desatualizado após um rerender completo; aqui um clipe é sempre reconstruído a partir da tomada que o produziu.
- A cauda é cortada no máximo 0,6 s após a última palavra, com um fade. Uma tomada TTS pode terminar com um clique ou o início de outra frase; um desses cliques foi enviado como um "corte estranho" no áudio.
- Todos os clipes no mesmo volume. Uma voz de personagem saiu 6 dB mais alta que a do narrador antes da normalização.
- Linhas inalteradas são puladas (hash do texto, voz e configurações em
audio/raw/cache.json), então uma execução completa após editar uma linha chama o provedor uma vez. Se apenasclip_lufsou o processamento mudaram, os clipes são reconstruídos a partir das tomadas arquivadas gratuitamente.--forcepede uma nova tomada de qualquer forma.
A chave é lida pelo script do ambiente ou PVS_HOME/.env e nunca é impressa. Nunca leia
.env você mesmo e nunca peça a chave no chat: se estiver faltando, diga ao usuário para
adicionar a linha ao .env ele mesmo, ou mude para say.
Execute pronounce_check.py após qualquer nova tomada. Ele transcreve cada clipe sem
acionar o ASR, sinaliza palavras da marca e do elenco que não foram reconhecidas, nomes
legados que foram ouvidos e vogais que se desviaram (seção 5). Uma sinalização significa
ouvir, não regenerar: ASRs ouvem mal palavras de marca que foram ditas corretamente.
5. Pronúncia
O roteiro e a tela mantêm a grafia real. product.pronounce muda apenas o que é enviado
ao TTS, e tts.py mapeia os timings de volta, então timings.json contém a palavra na tela
em w e a respelling em say ({"w": "Acme", "say": "AK-mee", ...}). Âncoras no build.py
usam a palavra na tela.
product:
pronounce:
Acme: AK-mee # respelling simples
Acme Tasks: {say: AK-mee Tasks, vowel: ae, confusable: ey} # com verificação de primeira vogal
Quando um revisor diz que o nome soa errado, tente três ou quatro respellings em uma linha,
meça-as com a verificação de vogal, mantenha a que passar, depois verifique todas as outras
linhas que têm a palavra: provedores variam por tomada. Detalhes e a tabela de vogais:
references/casting-and-pronunciation.md.
6. Tomadas
- No máximo duas tomadas por linha, a menos que o usuário diga o contrário; as cotas do provedor geralmente são compartilhadas em uma equipe. Diga quantos caracteres uma execução completa custará antes de executá-la.
- Regere apenas a linha que precisa:
tts.py <video_dir> --only N7 --force. - Se a nova tomada for pior,
--only N7 --restorea troca de volta com seus timings. - Para uma nota de tom ("muito hype", "soa como meia frase"), faça duas ou três variantes como variantes de papel ou mudanças de velocidade, e deixe o revisor compará-las no contexto com a linha anterior.
- Alterando uma linha, em ordem: copie os arquivos de versão, edite a linha,
check_script.py,tts.py --only <id>,pronounce_check.py --only <id>, então o compositor reconstrói; tudo depois desse clipe se move sozinho.
7. Efeitos sonoros
Use apenas sons gravados, da biblioteca que acompanha o HyperFrames (make_sfx.py --list).
Digitação sintetizada soou "como um canudo, não um teclado" e um whoosh sintetizado como
"ruído branco" na revisão, então whooshes e risers são recusados pelo script, e nada vai
abaixo da narração como música a menos que o briefing peça. A produção de onde estas skills
vêm foi enviada sem trilha musical e sem ducking, e ninguém sentiu falta.
- Digitação:
typing_track(text, start, cps)constrói uma faixa a partir de teclas individuais extraídas de uma gravação real, com um toque mais forte nos espaços e um ritmo com semente, então é determinística e o mesmo texto sempre soa igual. Faça durar exatamente o tempo da batida que mostra o texto (dur=), e deixe as palavras digitadas coincidirem com as faladas. - Cliques e pops:
library_sfx("click", start)no quadro em que o cursor pressiona. audio/sfx/CREDITS.mdlista cada arquivo da biblioteca usado e carrega a licença da biblioteca.- Níveis sugeridos: narração 1.0, personagens 1.0, cliques 0.35 (0.22 em um arrasto solto), digitação 0.45, pops 0.12 a 0.3. Dois clipes na mesma faixa de áudio nunca devem se sobrepor: inicie um clipe pelo menos 0,02 s após o término do anterior, ou mova-o para outra faixa.
build.py importa as funções; make_sfx.py <video_dir> com um audio/sfx.tsv pré-constrói
os mesmos arquivos a partir da linha de comando (formato no docstring do script).
8. Entrega ao compositor
Entregue, sob <video_dir>/audio/: lines.tsv, clips/<id>.wav, timings.json, e sfx/
com CREDITS.md. Diga ao compositor a que palavras cada batida deve ancorar (o substantivo
que o cursor toca, a palavra em que a digitação chega) e as esperas da tabela de momentos.
Nunca edite timings.json manualmente: ele é regenerado a partir dos clipes, e uma edição
manual é perdida na próxima execução.
Relate ao usuário: as linhas vocalizadas, a duração de cada clipe, quaisquer sinalizações de pronúncia e o que você ouviu, as vozes usadas (com o padrão recomendado para o que ainda estiver em aberto) e os caracteres do provedor gastos.