Legendas
Isto é uma ação, não uma etapa de um fluxo. Deve ser executada quando o usuário a solicitar – pode ser feita logo após a edição, ou novamente após ele ter removido algumas falas.
Tem apenas um pré-requisito: o livro-razão já deve existir. Não porque vem depois da edição, mas porque, sem ele, não é possível saber quais falas permanecem e em que segundo do vídeo final cada uma se encontra.
Entrada edit-list.json (livro-razão), transcript.json (transcrição palavra por palavra)
Saída subtitles.json
Ao terminar, pare. Não oriente o usuário para o próximo passo.
Primeiro, leia e execute o contrato de fase do Skill de negócio. Critérios de julgamento conforme Regras de correção de legendas. Para grafia de termos específicos, consulte o Dicionário de termos de IA.
Quem decide o quê
Esta é a base do que se segue; todo o resto deriva daqui.
Edição de narração decide "quais falas ficam e em que momento" ← única verdade temporal
Legendas decide "que texto aparece na tela" ← única verdade de exibição
Uma tela de legenda armazena uma lista de IDs de palavras + texto exibido, não armazena segundos. O tempo é calculado a partir do livro-razão a cada execução. Assim, não há uma segunda linha do tempo que possa divergir. Falhas podem ser localizadas com precisão por tela: "as palavras das telas 7 e 12 foram cortadas", em vez de uma imprecisa "legendas podem estar desatualizadas".
A legenda armazena seu próprio texto intencionalmente. A transcrição responde "o que ele disse", a legenda responde "o que se mostra para as pessoas" – pontuação, vícios de linguagem removidos, grafia formal de termos próprios, tudo isso deve ser diferente. Forçar uma única string a fazer ambos os trabalhos impede, por exemplo, a adição de vírgulas.
0. Prontidão
Execute primeiro a "verificação de prontidão" de Verificar atualizações – se os skills estão atualizados e o Runtime é compatível; a raiz do plugin também é localizada ali (substitua <raiz-do-plugin> nos comandos abaixo pelo caminho literal). Prossiga somente se o status for "pronto"; para "requer nova sessão" ou "parar", siga as instruções (incluindo a proibição de "interfaces substitutas customizadas"). O Skill de negócio não contém lógica de ambiente.
Se o resultado da prontidão for runtime.kind=desktop-managed, reutilize diretamente a CLI estável já instalada pelo aplicativo desktop e o mesmo serviço launchd/windows-task; não analise caminhos do Electron, instale dependências adicionais ou inicie um segundo Runtime.
1. Validação de entrada
node "<raiz-do-plugin>/scripts/ensure-running.cjs" --json
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" inspect "<diretório-do-projeto>" --json
| Validação | Se falhar |
|---|---|
edit-list.json existe e contém segmentos | Informe que o livro-razão está faltando e peça ao usuário para executar a edição da narração. Não corte você mesmo. |
transcript.json existe | O projeto não está pronto; pare. Não crie uma transcrição você mesmo. |
Não valide a existência de source_cut.mp4 nem realize transcrição. A legenda não precisa de nenhum dos dois – veja a próxima seção.
2. Correção de texto: primeiro dicionário, depois script
Não é necessário retranscrever. A transcrição palavra por palavra já contém os timestamps; o livro-razão sabe quais trechos permanecem – em que segundo do vídeo final cada palavra cai é calculado, não obtido por nova audição:
O segundo da palavra no vídeo original está na transcrição
Quais trechos permanecem está no livro-razão
O segundo da palavra no vídeo final calcula-se a partir dos dois
Enviar novamente para ASR é apenas reouvir a mesma fala: custa dinheiro, tempo e, pior, o resultado é inferior – os termos próprios precisarão ser corrigidos novamente. (transcript retranscribe é um resquício do design anterior, quando a legenda dependia da transcrição do vídeo editado para obter a linha do tempo. Com a legenda ancorada por IDs de palavras, esse problema desapareceu. Não o use ao fazer legendas.)
Duas ferramentas diferentes, ambas devem ser usadas.
# Dicionário: grafia fixa para este falante, sem necessidade de evidências
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" transcript dictionary "<diretório-do-projeto>" --dictionary "<raiz-do-plugin>/references/ai-term-dictionary.md" --json
# Script: somente se o autor tiver o roteiro em mãos; cada correção exige evidência
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" transcript align "<diretório-do-projeto>" --script "<arquivo-do-roteiro>" --json
Dicionário sempre escreva assim ignora contexto, corrige diretamente, lista as alterações
Script só escreva assim se o contexto exige evidência para cada ocorrência; se não confirmar,
corresponder reporta "incerto", sem adivinhar
Por que o dicionário é obrigatório e o script sozinho não basta: as narrações podem ser regravadas. Em projetos reais, a mesma frase foi gravada quatro vezes; assim, contextos como "conector X" e "X é" aparecem várias vezes. O align só pode reportar "incerto" – ele não adivinha, porque errar um nome é pior do que ouvir errado. De três ocorrências de "X", ele só corrige uma. O dicionário não tem esse problema: na obra deste falante, "X" é "X".
Há apenas um dicionário, no nível do plugin: references/ai-term-dictionary.md. Ele corrige a transcrição, e tanto a edição da narração quanto as legendas consomem a mesma transcrição. Não crie outro dicionário neste skill.
Após a correção, revise a lista. O dicionário ignora contexto, portanto também pode corrigir erroneamente – por exemplo, normalizar "Skills" (Claude Skills, nome próprio no plural) para "Skill". Se vir algo errado, corrija o dicionário; não aplique remendos no comando.
transcript align apenas reporta; não aplica. Para aplicar suas propostas, converta corrections em [{wordId, text}] e execute:
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" transcript correct "<diretório-do-projeto>" --file "<arquivo-de-correção>" --json
Após corrigir a transcrição, as telas de legenda que referenciam essas palavras são automaticamente atualizadas na mesma etapa, retornando subtitles.updated. As que não puderem ser alteradas (porque a linha foi reescrita manualmente) vão para needsAttention; reporte-as para revisão humana, sem adivinhar.
Quando nem o dicionário nem o script confirmam uma grafia correta, não adivinhe. Reporte para o usuário adicionar ao dicionário – uma vez adicionado, o próximo vídeo estará automaticamente correto; adivinhar agora exigirá nova adivinhação na próxima vez.
3. Divisão em telas
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" subtitle build "<diretório-do-projeto>" --json
Quatro regras, em ordem:
① Fala removida aqui Se os lados do trecho removido estão adjacentes na linha do tempo
e não têm relação de sentido. "Remover silêncio" não conta – cortar
uma pausa no meio de uma frase não deve quebrar a frase.
② Pontuação Qualquer pontuação fornecida pelo ASR, incluindo ponto final e vírgula –
**mesma granularidade da divisão da edição da narração**, a quebra
ocorre no mesmo ponto. A pontuação é mais forte que qualquer evidência
temporal: o falante pode dizer duas frases sem pausa, ou pausar no meio
de uma frase.
③ Limite de parágrafo + pausa **Use somente quando a palavra não tiver pontuação.** É "quando
não há pontuação, assume-se que o parágrafo terminou". Se houver
pontuação, a regra ② e a vírgula devem gerenciar – elas consideram
se a tela é longa o suficiente; a regra ③ não. (Aplicar ③ em limites
com pontuação, em projeto real, aumentou de 40 para 43 telas,
criando mais telas curtas.)
④ Pausa longa para o público Para quebrar dentro de uma frase, o silêncio precisa ser mais
longo.
A edição da narração e a legenda consomem a mesma pontuação, com a mesma granularidade: uma vírgula = um segmento / uma tela.
Fragmentos (uma ou duas palavras) são mesclados, mas não entre pontos finais – "Você vê" inicia uma nova frase, não é o final da anterior; mesclar resultaria em "...chamar Grok CLI você vê", duas frases coladas.
Frases curtas ditas rapidamente permanecem (em projeto real, "Toda manhã" e "Executar tarefa" duravam 0,6 segundos cada). Isso é como ele realmente fala; não alerte. Uma vírgula por tela naturalmente produz essas telas; alertar equivaleria a alertar sobre fala normal – com muitos alertas, ninguém os lê.
As telas restantes, mais longas que o ideal, são divididas uniformemente em várias telas, uma tela por linha. Se aparecerem fragmentos de uma ou duas palavras, significa que o limite ② não era um ponto final; mescle o fragmento de volta à tela anterior.
O comando retorna quatro itens, todos devem ser revisados:
stale Telas alteradas pela edição – informe exatamente o número da tela e quais palavras foram perdidas
tooFast Muitas palavras, tempo insuficiente para leitura
transcriptMoved A transcrição não é mais a original
Quando já existem legendas – pare e pergunte aqui
Sem a opção --replace, o comando se recusará a executar. Este é o único ponto neste skill onde é necessário obter consentimento do usuário, pois --replace descarta o trabalho humano de divisão e redação, irrecuperável pelo produto.
O usuário quer alterar algumas palavras Não execute build. Deixe-o editar diretamente no Studio
ou informe quais telas alterar.
O usuário quer recomeçar do zero Após confirmação, adicione --replace.
4. Revisão: tela por tela no Studio
node "<raiz-do-plugin>/scripts/videocut-cli.cjs" open "<diretório-do-projeto>" --json
Após abrir, vá para a guia "Legendas" na barra lateral esquerda. Uma linha por tela: à esquerda, o número da tela e o tempo; à direita, o texto. Clique para editar diretamente.
- Enter = inicia uma nova tela a partir do cursor
- Backspace no início da linha = mescla com a tela anterior
- Na barra lateral direita, em "Parâmetros → Legendas", escolha um dos quatro predefinidos; um estilo para todo o vídeo
- Na tela, a legenda é exibida diretamente; posição e tamanho da fonte são proporcionais à imagem – a prévia e o vídeo final usam os mesmos valores
Durante a revisão, pelo menos confirme com o usuário: os termos próprios estão corretos? Há palavras engolidas? A quebra de linha soa natural? O tempo de exibição é suficiente para a leitura?
5. Até subtitles.json
Esta etapa está concluída. Não faça corte físico, storyboard, animação nem renderização do vídeo final. Também não apresse o usuário para o próximo passo.
O relatório deve ser separado: o readback estruturado do Produto é API/readback PASS; a revisão dos quadros reais do navegador no mesmo projeto é visual frame PASS; se ninguém tiver verificado visualmente se as legendas correspondem às imagens, o status deve ser human listening UNVERIFIED. Não substitua por DOM, captura de tela ou detecção de arquivo.
Limite: gravação na imagem não faz parte desta etapa
O formato de saída definido é gravação na imagem, e a imagem é gerada durante a exportação. A saída da legenda é subtitles.json – todas as dimensões são porcentagens da imagem; a exportação as converte em pixels de acordo com a resolução de saída. Ambos os lados usam os mesmos valores.
O mp4 exportado hoje não contém legendas, pois essa etapa ainda não foi realizada. Deixe claro no relatório essa consequência; não se limite a dizer "legendas prontas" – o usuário pode pensar que o vídeo final as contém.
Recuperação e falhas
subtitles_exist: Já existem legendas. Pergunte primeiro, não use--replacediretamente.revision_conflict: Outra instância também está escrevendo. Releia, não sobrescreva automaticamente.- Dicionário reporta "Linha N não pôde ser interpretada": é uma linha de tabela mal formatada. A regra reconhece apenas linhas de tabela (
| grafia correta | erro comum de reconhecimento |); prosa e listas são ignoradas silenciosamente. transcript correctreporta "must not change any word id, time or gap flag": a proposta de correção de texto incluiu alterações de tempo. Corrija apenas o texto.runtime_unhealthy: Não reinstale em loop.- Em caso de falha, nunca descreva "transcrição concluída" como "legendas prontas". O resultado do ASR é matéria-prima, não produto final.