Exportar (vídeo final)
Esta é a última etapa da cadeia, o único lugar em todo o produto onde pixels são realmente desenhados.
Antes dela, tudo são anotações: o "livro-razão" registra quais palavras são ditas, as legendas registram o que aparece na tela, os visuais registram quais camadas são sobrepostas, e a pré-visualização combina esses três elementos em tempo real para o usuário ver, sem gravar em disco. A exportação os combina em um único arquivo.
Requer edit-list.json (obrigatório), subtitles.json, visuals.json + modules/
Produz video_final.mp4
Pré-requisito: Google Chrome na máquina (para renderizar legendas e animações como imagens). O FFmpeg / FFprobe instalado via área de trabalho já está nos diretórios gerenciados pelo Product com o App; a instalação apenas via CLI ainda requer ffmpeg ≥ 6 no sistema. A falta do Chrome resultará em um erro claro. Não tente contornar isso — sem ele, não há camada de legenda nem camada de animação.
Primeiro, leia e execute a seção "Nível de Conclusão" do Contrato de Estágio de Skill de Negócio. A exportação não entra na máquina de estado de edição: ela não altera nenhum arquivo de projeto, não faz gravação CAS, não avança estágios; a saída é um novo arquivo, e executá-la novamente sobrescreve o anterior. Portanto, não requer um cartão de confirmação.
0. Pronto
Primeiro, execute a Verificação de Prontidão — se as skills estão atualizadas e o Runtime é compatível; a raiz do plugin também é localizada lá (todos os comandos <raiz_do_plugin> neste texto devem ser substituídos pelo caminho literal). Continue apenas se o resultado for "pronto"; para "Nova sessão necessária" ou "Parar", siga as ações determinadas (incluindo a proibição de "interfaces de substituição caseiras"); a Skill de Negócio não possui lógica de ambiente própria.
Se o resultado de prontidão for runtime.kind=desktop-managed, reutilize diretamente as ferramentas CLI estáveis, ferramentas de mídia e o mesmo serviço launchd/windows-task instalados pelo App de área de trabalho; não analise caminhos Electron, instale outro FFmpeg/Bun ou inicie um segundo Runtime.
Comandos
node "<raiz_do_plugin>/scripts/ensure-running.cjs" --json
node "<raiz_do_plugin>/scripts/videocut-cli.cjs" export <projeto> --dry-run --json # Ver plano primeiro, sem codificar
node "<raiz_do_plugin>/scripts/videocut-cli.cjs" export <projeto> --json # Produzir vídeo final (padrão: 2x, taxa de quadros original)
node "<raiz_do_plugin>/scripts/videocut-cli.cjs" export <projeto> --out /caminho/video_final.mp4 --json
node "<raiz_do_plugin>/scripts/videocut-cli.cjs" export <projeto> --scale 1 --json # Apenas tamanho original
node "<raiz_do_plugin>/scripts/videocut-cli.cjs" export <projeto> --keep-work --json # Manter arquivos intermediários e PNGs quadro a quadro para depuração
Se ensure-running encontrar incompatibilidade de identidade, conflito de porta ou serviço não saudável, pare imediatamente; não é permitido usar um processo em primeiro plano temporário para continuar a exportação.
Duas etapas, não pule para a segunda
① --dry-run primeiro relata o plano Duração, quadros, número de quadros de legenda, número de camadas visuais, segmentos de zoom, tamanho de saída
Leia para o usuário. Se os números estiverem errados, o problema está a montante; dez minutos de codificação não vão corrigi-lo
② Executar de verdade assemble → overlay → compose → verify, quatro estágios de progresso
Os warnings em --dry-run devem ser relatados exatamente como estão. Eles relatam apenas um tipo de coisa: algumas palavras de certos quadros de legenda ou camadas visuais já foram cortadas, portanto não aparecerão no vídeo final. Isso é uma decisão a montante, não algo que a exportação deva engolir.
Nitidez: o vídeo original é o teto; verifique o original antes de ampliar
Antes de exportar, verifique a resolução do original (o campo source do --dry-run já contém):
Largura original ≥2560 (gravação de tela Retina nativa) → --scale 1, a saída terá pixels nativos; este é o melhor caso
Largura original <1920 (ex.: 960×720) → Pare primeiro: pergunte ao usuário se existe uma exportação de alta definição da mesma gravação.
Ferramentas de gravação de tela geralmente podem reexportar a mesma gravação em 3x a resolução;
trocar o vídeo original é mais eficaz do que qualquer pós-processamento (veja próxima seção). Se realmente não houver → --scale 2
Por que --scale 2 é útil para origens de baixa resolução: ampliar o quadro não o torna mais nítido, mas legendas e animações são redesenhadas no tamanho de saída — é nisso que o público realmente presta atenção; quando a plataforma comprime novamente, quadros maiores recebem mais taxa de bits.
Não ajuste --fps para "melhorar a nitidez". A taxa de quadros segue o vídeo original; alterá-la fará com que a amostragem das animações e a gravação de tela não correspondam.
Troca de vídeo original: quando o usuário fornecer uma versão de alta definição da mesma gravação
Isso não faz parte do fluxo de exportação — a exportação em si é apenas leitura. A troca é uma operação de material independente após o consentimento explícito do usuário; depois de concluída, volte à exportação normal.
Primeiro, determine se é a mesma gravação (as duas primeiras condições já são suficientes):
ffprobe -v error -show_entries format=duration -of csv=p=0 <dois_arquivos> # Duração igual ao milissegundo
ffmpeg -v error -i <arquivo> -map 0:a:0 -c copy -f md5 - # Fluxo de áudio idêntico bit a bit
# Em seguida, extraia dois ou três quadros para comparar o conteúdo visual, confirme visualmente
Áudio idêntico bit a bit = Linha do tempo idêntica: O script palavra por palavra, o livro-razão, as legendas e as camadas visuais estão todos vinculados a IDs de palavras; nenhum precisa ser alterado. É exatamente isso que "vincular por palavra, não por segundo" significa na prática para a troca de vídeo original.
Quatro etapas para trocar o vídeo original (executado uma vez em 29/07/2026; a etapa ③ foi perdida na época, e a pré-visualização de edição relatou imediatamente "Falha na geração" — a impressão digital não está em um único lugar; pesquise todas as impressões digitais antigas com grep antes de agir):
① Trocar arquivo input/source.mp4 e uploads/source.mp4 são um par de hard links —
Delete ambos, copie o novo arquivo para input/ e crie um hard link de volta para uploads/
(macOS: ln; Windows: New-Item -ItemType HardLink)
② Atualizar impressão digital O source.sha256 em project.json deve ser alterado para a do novo arquivo
③ Verificar outro local workbench.json também armazena a impressão digital sourceSha256;
o pipeline de validação da pré-visualização de edição verifica exatamente este —
perdê-lo fará com que a pré-visualização se recuse a ser gerada
(Este é o comportamento correto do produto: se a impressão digital não corresponder, falhe, não use uma pré-visualização antiga para enganar)
④ Reexportar --scale 1 — A troca é para pixels nativos, não amplie novamente
Abordagem segura: Use sua ferramenta de busca para encontrar os primeiros 8 caracteres da impressão digital antiga em todos os arquivos *.json no <diretório_do_projeto>; processe cada ocorrência encontrada (registros de cache como preview-edited/current.json serão recalculados automaticamente, não é necessário alterá-los manualmente).
Se o áudio for diferente (regravado, cortado, duração diferente), não é uma troca de vídeo original, é um novo projeto: a transcrição palavra por palavra precisa ser retranscrita, todas as anotações são invalidadas. Não force a situação.
Aceitação: Três itens, faltando um a exportação não é considerada concluída
① Comando retorna com sucesso O produto verifica o tamanho, quadros e trilhas de áudio do vídeo final, comparando item por item com o plano.
Se houver divergência, um erro readback_mismatch é gerado, o arquivo permanece no disco como evidência,
e a exportação não é considerada concluída
② Extrair quadros para inspeção visual Extraia quadros do vídeo final e inspecione visualmente. Cubra pelo menos: um segmento de zoom,
um segmento de animação em tela cheia, um segmento apenas com legendas e uma borda entre camadas
③ Verificação auditiva humana Ninguém realmente ouviu, sempre registre como human listening UNVERIFIED
② Não é permitido usar capturas de tela da pré-visualização como substituto. Pré-visualização e vídeo final são dois pipelines de renderização diferentes; a aceitação deve verificar se eles correspondem — usar uma imagem da pré-visualização como evidência do vídeo final é assumir a própria coisa que está sendo verificada.
Para avaliar o zoom, procure marcos discriminatórios; a impressão geral pode enganar (experimentado em 29/07/2026): uma tela ampliada 1.6x ainda parece "uma página inteira" e, em miniatura, é quase indistinguível da visão geral — já causei uma falsa interpretação de "zoom perdido", perdendo meia hora e reexportando duas vezes. A maneira correta é procurar evidências que só o corte pode causar: elementos cortados pela metade (bolhas de diálogo partidas ao meio), elementos de borda desaparecidos (barra lateral, barra de título). Compare com o quadro do mesmo momento do vídeo original para uma decisão instantânea.
Para extrair quadros, use o ffmpeg:
ffmpeg -v error -ss 8.84 -i video_final.mp4 -frames:v 1 -y frame.png
Onde verificar se houver problemas
--keep-work deixará três tipos de itens em .chengfeng-videocut/export/ do projeto, separando diretamente "qual metade está errada":
assembled.mkv Apenas a edição, sem nenhuma sobreposição. Se estiver errado = erro no livro-razão ou na segmentação
overlay/*.png Apenas as sobreposições, fundo transparente. Se estiver errado = erro no estilo de legenda ou no módulo
spans/*.mp4 Segmentos após a composição. Se estiver errado = erro no zoom ou no alinhamento
Tabela de correspondência:
Vídeo final sem legenda/animação O overlay PNG está totalmente transparente? O módulo não respondeu ao seek?
Animação parada no primeiro quadro O módulo não implementou seek, ou a timeline do GSAP não está paused
Bloco inteiro branco na tela O módulo está sem `:root { color-scheme: dark }`
Caixa de zoom desalinhada O viewBox do módulo e o zoom da camada não são do mesmo conjunto de números
Vídeo final mais curto que o plano Algum span tem quadros insuficientes; veja o erro na fase compose
Borda da camada pisca com pedaço do original Captura de tela do overlay obsoleta (validação de marcação de quadro falhou). O produto depende da barra de marcação de quadro no topo da página para provar a qual quadro cada captura pertence; se recorrente, primeiro confirme se o overlay
PNG tem a barra de marcação no topo e se o compose a cortou
Chrome não encontrado Instale o Google Chrome, não altere o pipeline de renderização
O que não fazer
- Não diga "exportação bem-sucedida" como "aceitação aprovada" — o retorno bem-sucedido do comando significa apenas que o produto se corresponde, não que o visual está correto
- Não use capturas de tela da pré-visualização, DOM ou logs para substituir a extração de quadros do vídeo final
- Não registre human listening PASS se ninguém ouviu
- Não modifique arquivos do projeto (alterar legendas, excluir camadas, mexer no livro-razão) para permitir que a exportação seja concluída. A exportação é somente leitura, não escreve
- Não realize tarefas a montante dentro da exportação: se faltam legendas, vá escrevê-las; se faltam visuais, vá criá-los; não invente uma solução temporária nesta etapa