Narração
npm run tts vocaliza cada linha de src/timeline.ts em public/audio/<lang>/<key>.wav, com os timestamps de palavras da Cartesia em <key>.words.json, e reescreve src/audio.generated.ts com as durações reais das linhas. As linhas são armazenadas em cache por motor, voz, modelo, velocidade e texto: apenas linhas novas ou editadas são vocalizadas novamente. npm run tts -- en ou -- es limita a execução a um idioma.
Configuração da Cartesia
- As configurações estão em
video.config.mjs(tts): modelosonic-3.6-2026-08-27, velocidade1. - Voz EN:
5568a7df-e5ab-4442-9fae-2e9ba1b15ad8(en-GB). CARTESIA_API_KEYé buscada nesta ordem:- variável de ambiente;
- arquivo
.envna pasta do vídeo (ignorado pelo git; copie de.env.example); ~/Documents/repos/.env.
- Nunca imprima a chave, exiba-a ou faça commit dela. Verifique se ela existe sem mostrá-la, por exemplo
test -n "$CARTESIA_API_KEY" && echo set.
Motores e fallback Kokoro
tts.engine em video.config.mjs:
auto(padrão): Cartesia quando uma chave é encontrada e o serviço responde; caso contrário, todo o idioma é vocalizado com Kokoro (local, gratuito) e um aviso é exibido. Um idioma nunca é uma mistura de duas vozes: se a Cartesia falhar no meio do processo, todo o idioma é refeito com Kokoro, e na próxima execução com a Cartesia de volta, ele é refeito novamente.cartesia: falha em vez de usar fallback.kokoro: permanece offline. Vozes:af_bella(EN),ef_dora(ES). Kokoro não fornece timestamps de palavras, portanto as legendas são temporizadas proporcionalmente.
Um aviso sobre Kokoro na saída significa que o vídeo não tem a voz da Cartesia: informe isso ao entregar o vídeo.
Voz em espanhol
voices.es é null até que uma versão em espanhol seja criada. Escolha uma voz em espanhol da biblioteca de vozes da Cartesia, ouça uma amostra de linha do script, registre seu ID em video.config.mjs (es: { id: '<voice-id>', language: 'es' }) e adicione 'es' a SETTINGS.voices (e a SETTINGS.subtitles se legendas em espanhol forem desejadas).
Pronúncia
O TTS lê o texto da narração; as legendas mostram o texto escrito. Quando o TTS lê errado um número ou símbolo, forneça à linha uma forma falada como quarto argumento de say, e mantenha a forma escrita do artigo como legenda:
say(0.3, 'It solved 14/20 tasks.', 'Resolvió 14/20 tareas.', {
en: 'It solved fourteen out of twenty tasks.',
es: 'Resolvió catorce de veinte tareas.',
})
- O TTS vocaliza a forma falada (e o cache re-vocaliza a linha quando ela muda); a duração da linha vem dela.
- A legenda mostra o texto escrito, temporizado proporcionalmente sobre a linha (os timestamps de palavras pertencem às palavras faladas, portanto não são usados para essa linha).
- Escreva a linha de forma simples ("14/20", "83 %", "p = 0.0018") e adicione uma forma falada apenas quando uma audição mostrar que o TTS erra.
- Barras, strings de versão ("gpt-5.6"), nomes de arquivo e siglas são os problemas mais comuns. Ouça cada linha que contenha um deles.
QA de áudio
npm run audio-qa (escreve out/audio-qa.md):
- normaliza cada linha para o mesmo volume (uma vez por versão do arquivo);
- marca uma linha como clipping quando seu pico de origem atinge -0.1 dBFS;
- marca uma linha como muito longa quando sua duração excede 1,6x a estimativa baseada no comprimento do texto: um sinal de fala distorcida ou repetida. Ouça cada linha marcada e re-vocalize-a (edite o texto ligeiramente ou exclua seu arquivo wav) se estiver errada;
- após
npm run render, mede cada mix emout/contra -16 LUFS integrado, ±1 LU (pico verdadeiro -1.5 dBTP) e sai com código 1 se algum estiver fora do alvo.
Após narrar, execute npm run lint novamente: as durações reais substituem as estimativas e podem empurrar o vídeo para fora de sua duração alvo ou uma legenda para mais de 17 caracteres/s.
Trilha sonora suave
Uma trilha sonora suave é gerada localmente (npm run music, feita automaticamente por npm run render quando ausente; precisa de python3 com numpy, ou uv). Ela é reduzida para 30% do seu volume enquanto uma linha é reproduzida. Defina SETTINGS.music como null para nenhuma música.