Vídeo de letra animado
O vídeo é um trecho de música, uma pequena história desenhada que segue a letra, e a letra exibida linha por linha sob a animação com a palavra cantada destacada. O shell (src/kit/LyricVideo.tsx) gerencia áudio, cabeçalho, letras, créditos, handles sociais e fades. Sua função é o trecho, os tempos e a história. Responda no idioma do usuário.
0. Entradas
Obtenha apenas o que está faltando, nada mais:
- Arquivo de áudio e o texto da letra. Se o usuário fornecer apenas um título, peça os arquivos. Não baixe músicas.
- Artista, título da música, linha de crédito (ex.: "Letra e música: …"), handles sociais opcionais (
{network: 'instagram' | 'youtube', handle}). - Duração máxima. Padrão de 60 s se não for especificada.
Trabalhe apenas com músicas que o usuário possui ou tem permissão para usar. Nunca faça upload ou publique nada.
1. Crie a música
npm run new-song -- <kebab-id> --audio <arquivo> --title "…" --artist "…" --credit "…"
Isso cria src/songs/<id>/ (config, letras, cenas), copia o áudio para public/ e registra a composição <id>.
2. Letras, transcrição, alinhamento
- Escreva
src/songs/<id>/lyrics.txt: uma linha de tela por linha, na ordem cantada, repetindo refrões. 2–7 palavras por linha funcionam bem; divida linhas mais longas em uma pausa natural. python scripts/transcribe.py public/<audio> src/songs/<id>/transcription.json --language <código>- Escolha o trecho e defina
start/endemconfig.ts:- Fique dentro da duração máxima;
- Comece 2–3 s antes da primeira linha cantada que você mantiver (espaço para uma cena de capa);
- Termine após uma frase completa, idealmente uma linha de refrão, mais ~1,5 s para o fade (o shell desvanece áudio e imagem nos últimos ~1,8 s);
- Use os tempos dos segmentos em
transcription.jsonpara encontrar limites de frases.
python scripts/align.py src/songs/<id>e leia seu relatório:- "not heard: timing estimated": Whisper pulou a linha; o tempo é um palpite. Tente um modelo maior (
--model mlx-community/whisper-large-v3-mlxou--model large-v3) ou corrija manualmente emlyrics.ts. - "Dropped": linhas fora do trecho. Esperado se o usuário colou a música inteira.
- As palavras do Whisper geralmente estão erradas; a letra do usuário prevalece. Nunca "corrija" a letra do usuário para corresponder ao Whisper. Se a gravação cantar palavras diferentes claramente, informe o usuário e pergunte qual versão mostrar.
- "not heard: timing estimated": Whisper pulou a linha; o tempo é um palpite. Tente um modelo maior (
3. Escreva a história antes do código
Faça um breve roteiro: uma batida por linha (ou por par de linhas), com seu tempo de início de lyrics.ts. Em seguida, transforme as batidas em cenas.
Regras de estilo. São o que fazem os vídeos funcionarem; siga-as:
- Sugira, não ilustre palavra por palavra. Sem palavras na tela ou onomatopeias que repitam a letra: sem placas, rótulos, destinos, balões de fala, "AU", "shhh", "∞". Conte com ação, objetos, luz, clima, cor e motivos recorrentes. Se uma linha nomear algo (um trem, um cachorro, uma ligação), pergunte o que significa na história e mostre isso, ou mostre a coisa sem nomeá-la.
- Uma história, um elenco. Mantenha os mesmos personagens e alguns cenários e adereços recorrentes, para que o vídeo pareça uma história, não um slideshow.
- Acerte as palavras-chave. Cronometre pops, impactos e mudanças para o início da palavra importante (
pop(t, word.start),sacudida(t, word.start)). - Sempre em movimento. Nenhum quadro deve ficar parado por mais de cerca de um segundo.
- Respeite o layout. Desenhe a cena entre y≈300 e y≈1100 na tela 1080x1920. O cabeçalho fica acima, as letras começam em y≈1150.
- As cenas mudam cerca de 0,3–0,5 s antes da linha que ilustram; o shell faz crossfade por 0,12 s.
- A primeira cena é uma capa (artista e título, antes dos vocais). O cabeçalho aparece quando a segunda cena começa.
4. Codifique as cenas
Edite src/songs/<id>/scenes.tsx. Uma cena é um componente que recebe t, o tempo da música em segundos, e desenha dentro de <Lienzo>:
const Encontro: Escena = ({t}) => {
const k = u(t, 31.2, 33.0); // 0→1 entre dois segundos da música
return (
<Lienzo>
<FondoPuerto t={t} id="encontro-ceu" pal={PAL.noite} />
<Casal x={540} y={CAIS_Y} s={1.45} k={k} t={t} />
<Coracao x={540} y={420} s={pop(t, 33.0)} />
</Lienzo>
);
};
export const SCENES = [
{at: CONFIG.start, C: Capa},
{at: 30.9, C: Encontro},
];
Referência do kit (nomes em espanhol; README.md tem um glossário). Navegue por cada peça na composição kit-gallery.
- Auxiliares de tempo (
kit.tsx):u(t, a, b)progresso 0→1;lerp,lerp2; easingseo(out),ei(in),eio(in-out),back(overshoot);pop(t, at)aparecimento elástico;sacudida(t, at)tremor amortecido;rnd(i)aleatório determinístico. Nunca useMath.random(). - Personagens:
<Persona tipo="el" | "ella" x y s mira pose enMano>.x, ysão os pés.mira1 vira à direita, -1 à esquerda.pose:bd/btbraço frontal/traseiro[ombro°, cotovelo°](0 para baixo, 90 para frente, 180 para cima),paso+zancada(andar),inclina(inclinar),cabeza(inclinação da cabeça),ojo: 'cerrado',beso,sonrojo(corar).ikBrazo(...)aponta uma mão para um ponto;puntoMano,puntoCabezaretornam pontos no canvas.<Casal k>: 0 separados, 1 se beijando.<Cachorro>. - Cenários:
FondoPuerto(porto, paletasPAL.noite | ocaso | alba),FondoHuerto(pomar),FondoTejados(telhados),FachadaFundo+FachadaFrente(sacada; desenhe personagens entre elas),FondoBar,FondoInferno,FondoTapia(parede caiada),FondoEstacao(estação, passe umtrem),FondoDescampado(terreno baldio à noite). O chão é y=985 na maioria deles (CAIS_Y,PLATAFORMA_Y); piso da sacadaSACADA_Y, ruaRUA_Y. - Objetos:
Barco,Trem+Fumaca,Carro(vidros embaçados, coração desenhado no embaçado),Casa,Arvore,Banco,Mala,Polaroide,Coracao,Labios,Flor,Maca,Anel,NeonTaça,Gaivota,Brilho,Explosao(explosão de corações e lábios),Flutuantes(corações flutuantes),Lembranca(tom de memória),Lua,Estrelas,Mar,Ceu.
Regras práticas: cada id de gradiente/clip deve ser único em todo o vídeo (prefixe com o nome da cena); calcule tudo a partir de t (sem estado); desenhe de trás para frente.
Novas peças vão em src/kit/, no mesmo estilo: cores chapadas, sem contornos, desenhadas em torno de sua própria origem, com uma propriedade de escala s. Adicione-as em Gallery.tsx.
5. Verifique os quadros
npm run typecheck
npm run stills -- <id> <segundo> <segundo> …
Peça quadros no início e meio de cada cena e em cada palavra-chave. Ele escreve out/stills/<id>/sheet.jpg; olhe e corrija antes de renderizar: legibilidade, nada cobrindo rostos, nada na área do cabeçalho ou letras, mesmos personagens em todo o vídeo, nenhum rótulo literal, a letra mostrada corresponde ao momento do áudio.
6. Renderize e relate
npm run render -- <id>
Saída: out/<id>.mp4, 1080x1920, 30 fps, H.264 + AAC. Verifique sua duração com ffprobe e relate ao usuário: caminho do arquivo, duração, o trecho usado, a história em duas ou três frases, e cada tempo que você estimou ou dúvida de letra que encontrou. Diga que você verificou quadros estáticos, não o vídeo em reprodução.