Legendas no Remotion: SRT, tempos por palavra e exportação de legendas

Imagine uma demonstração hipotética de um produto. A transcrição está correta, mas o destaque acompanha uma frase inteira e a legenda permanece na tela durante uma pausa. Acrescentar animações não resolverá nenhum dos dois problemas. Um exige tempos por palavra; o outro exige uma decisão sobre quando o texto desaparece.

Escolha o comportamento das legendas antes do estilo. Este guia, baseado na documentação, aborda legendas fornecidas para o Remotion e formatos de saída de legendas. Seus dados de exemplo e plano de inspeção são ilustrativos e não foram executados; não constituem uma aplicação testada nem evidências de uma implantação da Optijara.

Escolha legendas por segmento ou legendas com tempos reais por palavra

Use SRT quando a exibição do segmento inteiro se adequar ao vídeo

O destaque de palavras deve ter uma razão para existir. Em uma gravação de tela com narração, uma frase completa pode dar aos espectadores tempo para ler enquanto observam a execução de um comando.

A referência de parseSrt do Remotion converte os segmentos SRT fornecidos em itens Caption, retornados no array captions de um objeto. Cada frase do exemplo mantém o intervalo de seu segmento. O analisador não descobre quando cada palavra foi pronunciada.

Use tempos por palavra quando palavras individuais precisarem de destaque

Use dados por palavra quando o destaque ajudar alguém a acompanhar a explicação, por exemplo, quando o narrador disser um termo técnico. Dividir uma frase em palavras com durações iguais produz uma programação de animação, não evidências sobre a fala.

A estrutura Caption aceita ambas as granularidades, portanto o tipo não resolve essa questão. Pergunte ao fornecedor se cada intervalo corresponde a um segmento ou a uma palavra.

Para contextualizar o uso de React em vídeo, o exemplo histórico de vídeo programático da Mux mostra um fluxo de visualização voltado a desenvolvedores. Ele não é uma referência para as APIs atuais de legendas nem para a precisão das legendas.

Importe legendas sem perder informações de texto ou tempo

Confira os campos de Caption e a convenção de espaços em branco

Leia os campos documentados literalmente. text contém a legenda, enquanto startMs e endMs delimitam seu intervalo. timestampMs contém uma única marca de tempo ou null; confidence contém um número de 0 a 1 ou null. Uma marca de tempo representativa não pode substituir um limite de intervalo.

Mantenha os espaços nos dados por palavra, de preferência antes das palavras subsequentes. Os utilitários são sensíveis a espaços em branco: remover os espaços de todos os tokens pode eliminar os separadores necessários para um texto legível. Preserve essa convenção em qualquer adaptador, sem esperar que o utilitário insira espaços.

A referência de Caption recomenda white-space: pre para preservá-los durante a renderização. Frases técnicas longas ainda precisam de uma verificação de layout nas dimensões previstas para o vídeo. Preservar os espaços em branco não significa que o texto cabe na tela.

Trate falhas de carregamento e validações dependentes da versão

O guia de importação usa staticFile() para referenciar um SRT em public, busca seu texto e o passa para parseSrt. Seu padrão assíncrono suspende a renderização com useDelayRender(), chama continueRender(handle) após o carregamento bem-sucedido e chama cancelRender(error) em caso de falha.

Confira response.ok antes de ler a resposta e depois valide se as legendas esperadas chegaram. A MDN explica que fetch não rejeita uma requisição apenas por um código de erro HTTP. Uma requisição resolvida ainda pode conter uma resposta de legendas inutilizável. Encaminhe também as falhas de análise e validação para o cancelamento, em vez de liberar uma renderização com legendas acidentalmente vazias.

A referência do analisador documenta strict: true a partir da versão 4.0.530. O padrão é false, para uma análise tolerante. O modo estrito rejeita arquivos malformados ou vazios com informações sobre o segmento e a linha. Confira a versão instalada antes de adicioná-lo.

O confidence: 1 do exemplo vem do analisador. Não é uma pontuação medida de precisão do reconhecimento de fala. O texto ainda precisa ser revisado com o áudio. Da mesma forma, pageBreakAfter, disponível a partir de 4.0.517, força uma quebra sem alterar os tempos, como explica a referência de Caption.

O roteiro Segmento, Relógio, Corte para a visibilidade das legendas

Segmento, Relógio, Corte é o roteiro editorial original deste artigo. Ele separa o agrupamento do mapeamento da linha do tempo e da visibilidade. Não é um recurso do Remotion nem uma metodologia de desempenho validada.

Segmento: agrupe o texto sem inventar alinhamento

createTikTokStyleCaptions transforma dados com espaçamento correto em páginas. combineTokensWithinMilliseconds controla a duração do agrupamento. Quando uma página ultrapassa essa duração, a próxima legenda que começa com um espaço inicia uma nova página. Essa configuração não fornece tempos por palavra ausentes nem detecta silêncio no áudio; também não é um controle exato da quantidade de palavras.

Estes dados de exemplo com tipagem mostram a convenção de espaçamento. Seus tokens em minúsculas nomeiam as etapas do roteiro em inglês, e seus intervalos foram inventados para fins didáticos. O fragmento não foi executado e não é uma aplicação completa nem uma transcrição real.

import type {Caption} from '@remotion/captions';

const illustrativeCaptions: Caption[] = [
  {text: 'cue', startMs: 1000, endMs: 1300, timestampMs: null, confidence: null},
  {text: ' clock', startMs: 1300, endMs: 1500, timestampMs: null, confidence: null},
  {text: ' cut', startMs: 1500, endMs: 1900, timestampMs: null, confidence: null},
];

Os espaços iniciais importam. Os intervalos separados também. A formatação preserva as informações fornecidas; não comprova que os tempos estão corretos.

Relógio: compare marcas de tempo no mesmo sistema de coordenadas

Os tokens de página contêm valores absolutos de fromMs e toMs na linha do tempo das legendas fornecidas. O guia de exibição compara esses valores com o tempo calculado a partir dos quadros. Antes de copiar o exemplo, defina onde começa a linha do tempo das legendas.

Em uma Sequence simples, apenas com deslocamento, useCurrentFrame() é deslocado por from, e sequências aninhadas acumulam os deslocamentos, de acordo com a referência de Sequence. Recortes, mudanças na velocidade de reprodução, repetições ou congelamentos exigem seu próprio mapeamento. Mapeie o quadro local resultante para o tempo das legendas uma única vez. Aplicar o deslocamento duas vezes cria um novo erro de sincronização.

Considere um cálculo ilustrativo a 30 fps. Suponha que a sequência comece no quadro 30 da composição, as legendas usem o tempo da composição, a velocidade de reprodução não mude e não haja aninhamento, recorte, repetição ou congelamento. O quadro local 0 corresponde a 1000 ms. O quadro local 8 corresponde a aproximadamente 1266.67 ms, e o quadro local 9, a 1300 ms. Com uma comparação que inclui o início e exclui o fim, a primeira palavra dos dados de exemplo fica inativa na última posição. Esses valores são resultados aritméticos, não saídas observadas do Remotion.

Para limites entre quadros, a convenção de inspeção proposta arredonda para cima o resultado da multiplicação dos milissegundos por fps, dividido por 1000. Registre a convenção. Recalcule o mapeamento sempre que uma edição alterar a linha do tempo de origem.

O guia de exibição usa Sequence, embora a referência atual já não recomende seu uso direto em código novo. Componentes mais recentes podem expor propriedades de tempo diretamente ou usar Interactive.withSchema(). Confira o suporte da versão antes de escolher um dos padrões.

Corte: decida o que permanece visível durante edições e pausas

Uma quebra de página não significa que o texto desaparece. A referência de agrupamento documenta breakOnSilenceAfterMilliseconds a partir de 4.0.514. Esse recurso compara lacunas entre as marcas de tempo das legendas, sem analisar o áudio. A página anterior permanece até o início da próxima, inclusive durante a pausa.

Escolha se essa página deve persistir após seu último token falado. Defina os limites de renderização para o comportamento escolhido, incluindo os cortes de cena e o fim da composição. O guia de exibição aplica seu próprio limite de duração; o agrupamento por si só não toma essa decisão.

Na demonstração hipotética, marque a frase falada e a ação correspondente na tela. Se o narrador mencionar um botão enquanto o cursor aponta para outro lugar, revise imagem e áudio juntos. Corrija o corte ou os tempos, ou mantenha a frase inteira visível. Não altere as instruções faladas para corresponder a uma revisão posterior da interface.

Mantenha intactas as legendas fornecidas e edite uma cópia separada. Registre se os tempos se referem à gravação ou à composição final. Documente o mapeamento depois de remover fala ou inserir uma captura de tela. Anote por que cada frase questionada foi corrigida; uma nota de correção não comprova que a reprodução foi inspecionada.

Antes de acrescentar mais animações, siga esta lista de verificação:

• Registre a origem da linha do tempo das legendas e qualquer mapeamento de edição.
• Confira se a entrada tem tempos por segmento ou por palavra; mantenha seus espaços.
• Escolha a duração do agrupamento independentemente do destaque.
• Converta o tempo dos quadros para o tempo das legendas exatamente uma vez.
• Decida quando as legendas desaparecem durante as pausas e nos cortes, incluindo o segmento final.
• Escolha o formato de saída para o destino e planeje as inspeções dos limites.

{"playbook":"cue-clock-cut","cue":"preserve-granularity-and-spaces","clock":"map-caption-time-once","cut":"bound-visibility","inspectionStatus":"proposed-unexecuted"}

Erros comuns das equipes: defeitos nas legendas e correções específicas

Separe problemas de entrada de problemas de agrupamento e relógio

Corrija a etapa responsável pelo sintoma. Mudar uma fonte não cria alinhamento por palavra. Ajustar o agrupamento não desfaz um deslocamento duplicado.

A issue 10476 do GitHub ilustra essa confusão em um caso histórico. A pessoa que relatou o problema usava @remotion/captions@4.0.441. O mantenedor confirmou a sensibilidade a espaços em branco como comportamento estabelecido, reconheceu erros distintos e encerrou a issue como concluída. Os nomes de opções propostos nela não são instruções da API atual, e seus defeitos encerrados não devem ser apresentados como não resolvidos.

Use um plano proposto de verificação dos limites em vez de confiar na prévia

Inspecione posições vizinhas em torno de limites representativos. Para o exemplo aritmético, as verificações propostas são nos quadros 29, 30, 38 e 39 da composição. Elas abrangem a entrada e a saída da primeira palavra sob essas premissas. Nenhum teste de renderização foi realizado.

Este plano não contém resultados medidos. Repita as verificações após as edições, mesmo que uma prévia anterior parecesse correta. Informações sobre os falantes também não substituem os tempos por palavra. O guia de transferência de informações dos falantes para a transcrição explica essa distinção para diarização e ASR. Uma faixa de atividade não corresponde a palavras alinhadas.

Escolha legendas incorporadas ao vídeo, um SRT separado ou ambos

Renderize legendas visíveis no vídeo

O guia de exportação descreve as legendas incorporadas como componentes de legenda renderizados no vídeo. Sua aparência passa a fazer parte dos pixels. Verifique se isso atende ao destino e mantém visível o conteúdo importante da tela.

Uma faixa de legendas selecionável é uma entrega separada. Se você precisa de um vídeo estilizado e de legendas gerenciadas separadamente, planeje as duas saídas.

Serialize os segmentos e emita um artefato de legendas separado

O mesmo guia documenta serializeSrt() com Artifact para emitir um arquivo de legendas durante a renderização. Este artigo não gerou nenhum arquivo.

A referência de serialização define lines como um array bidimensional: os itens externos são segmentos, e os itens internos são concatenados sem a inserção de espaços. Cada segmento começa no startMs de seu primeiro item e termina no endMs de seu último item. Mantenha a ordem e os delimitadores intactos.

Uma quebra de linha em text cria linhas visuais dentro de um único segmento. Nas versões compatíveis, pageBreakAfter inicia outro segmento. Nenhum dos dois cria alinhamento com a fala. Ao converter tokens de páginas agrupadas de volta em legendas, mantenha seus intervalos originais; a duração de exibição de uma página não deve substituir o fim da última palavra.

Revise o SRT emitido junto com o vídeo no destino pretendido. A serialização por si só não indica que o envio foi bem-sucedido nem que há suporte à reprodução de legendas.

Limitações: legendas legíveis ainda precisam de revisão do áudio e da saída

A qualidade dos tempos depende dos dados fornecidos e das edições

Não houve instalação do Remotion, transcrição, execução dos dados de exemplo ou renderização para este guia. Não houve chamadas a APIs pagas nem acesso a mídia privada. Os exemplos numéricos são apenas aritméticos.

Compare a transcrição com o áudio real, prestando atenção aos nomes técnicos e aos trechos editados. A bancada de testes de IA de fala multilíngue oferece um exemplo relacionado, específico de idioma, de verificação de nomes e da utilidade do fluxo de trabalho. Não é uma recomendação de fornecedor neste artigo.

Privacidade, layout e acessibilidade exigem decisões separadas

Antes de compartilhar áudio com um serviço externo, confira a permissão e o tratamento de dados documentado pelo serviço. Reserve orçamento para adaptação e revisão sem presumir economia. Verifique frases longas nas dimensões pretendidas, especialmente onde as legendas possam ocultar a interface demonstrada.

Legendas atraentes não comprovam conformidade de acessibilidade. Revise o texto e os tempos, inclua informações relevantes que não sejam fala e avalie a legibilidade e o formato de entrega. Para vídeos assistidos por IA, a proveniência de conteúdo visual responde a uma questão diferente sobre evidências. Mantenha os registros de origem e edição separados da revisão do áudio, com cada um sustentando apenas o que de fato comprova.