Exportar (Arquivo Final)
Esta é a última etapa da cadeia e o único lugar em todo o produto onde os pixels são realmente renderizados.
Antes disso, tudo são anotações: o diário registra "quais palavras falar", as legendas registram "o que escrever na tela", as cenas registram "qual camada sobrepor", e a prévia combina esses três em tempo real para o usuário ver, sem salvar em disco. A exportação queima tudo em um único arquivo.
Requer edit-list.json (obrigatório), subtitles.json, visuals.json + modules/
Produz arquivo_final.mp4
Pré-requisitos: A máquina deve ter o Google Chrome (para renderizar legendas e animações como imagens). O FFmpeg / FFprobe instalado com a versão desktop já está no diretório gerenciado do Produto; instalações apenas via CLI ainda exigem ffmpeg ≥ 6 no sistema. Se o Chrome estiver faltando, um erro claro será exibido — não tente contornar: sem ele, não há camada de legenda ou animação.
Primeiro, leia e execute a seção "Nível de Conclusão" do Contrato de Fase do Skill de Negócio. A exportação não entra na máquina de estado de edição: ela não modifica nenhum arquivo de projeto, não faz gravação CAS, não avança estágio; a saída é um novo arquivo, e executá-la novamente o substitui. Portanto, não precisa de cartão de confirmação.
0. Pronto
Execute primeiro a Verificação de Prontidão do skill de verificação de atualizações — se os skills estão atualizados, se o Runtime é compatível; a raiz do plugin também é localizada ali (todos os comandos <raiz_do_plugin> abaixo devem ser substituídos pelo caminho literal). Só continue se o resultado for "pronto"; se for "necessária nova sessão" ou "parar", siga as instruções de ação (incluindo a proibição de "proibir interface substituta caseira"), e o 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 o CLI estável, as ferramentas de mídia e o serviço launchd/windows-task já instalados pelo App desktop; não analise caminhos do Electron, não instale novamente 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 # Veja o plano primeiro, sem codificar
node "<raiz_do_plugin>/scripts/videocut-cli.cjs" export <projeto> --json # Gera o arquivo final (padrão: 2x, taxa de quadros da fonte)
node "<raiz_do_plugin>/scripts/videocut-cli.cjs" export <projeto> --out /caminho/arquivo_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 # Mantém arquivos intermediários e PNGs quadro a quadro para depuração
Se o ensure-running falhar por identidade incorreta, conflito de porta ou serviço não saudável, pare imediatamente; não é permitido usar foreground temporário para substituir e continuar a exportação.
Duas etapas, não pule a primeira
① --dry-run relata o plano Duração, quadros, número de telas de legenda, número de camadas de cena, segmentos com zoom, tamanho de saída.
Leia para o usuário. Se os números estiverem errados, o problema está nas etapas anteriores — dez minutos de codificação não vão corrigi-lo.
② Execução real assemble → overlay → compose → verify (quatro estágios de progresso)
Os warnings (avisos) de --dry-run devem ser transmitidos exatamente como estão. Eles relatam apenas uma coisa: certas telas de legenda ou camadas de cena tiveram suas palavras cortadas, então não aparecerão no arquivo final. Isso é uma decisão das etapas anteriores, não algo que a exportação deva engolir.
Nitidez: O vídeo fonte é o teto; veja a fonte antes de ampliar
Antes de exportar, verifique a resolução da fonte (o campo source de --dry-run já mostra):
Largura da fonte ≥2560 (gravação nativa Retina) → --scale 1, a saída é em pixels nativos, este é o melhor caso
Largura da fonte <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 a fonte é mais eficaz do que qualquer pós-processamento (veja próxima seção). Se realmente não houver → --scale 2
Por que --scale 2 ajuda em fontes de baixa resolução: ampliar o vídeo base não o torna mais nítido, mas legendas e animações são redimensionadas com base no tamanho de saída — é isso que o público realmente lê; quando a plataforma comprime novamente, imagens maiores recebem mais taxa de bits.
Não ajuste --fps para "mais nitidez". A taxa de quadros segue a fonte; alterá-la fará com que a amostragem da animação e a gravação de tela fiquem dessincronizadas.
Troca de fonte: Quando o usuário fornece 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 é sempre somente leitura. A troca de fonte é uma operação de material independente, feita após o consentimento explícito do usuário; depois disso, 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 exata em milissegundos igual
ffmpeg -v error -i <arquivo> -map 0:a:0 -c copy -f md5 - # Fluxo de áudio idêntico byte a byte
# Em seguida, extraia dois ou três quadros e compare visualmente o conteúdo
Áudio idêntico byte a byte = linha do tempo idêntica: cada palavra do roteiro, diário, legenda e camada de cena está vinculada ao ID da palavra, nenhuma precisa ser alterada. É exatamente isso que "vincular por palavra, não por segundo" significa na prática, ao trocar a fonte.
Quatro etapas para trocar a fonte (executado uma vez em 2026-07-29; a etapa ③ foi perdida na época, e a prévia de edição imediatamente reportou "falha na geração" — a impressão digital não está em um único lugar, use grep para encontrar todas as ocorrências da impressão digital antiga 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 recrie o hard link de volta para uploads/
(macOS: ln; Windows: New-Item -ItemType HardLink)
② Atualizar impressão digital source.sha256 em project.json para a do novo arquivo
③ Verificar outro local sourceSha256 em workbench.json também armazena a impressão digital do vídeo fonte,
e é exatamente este que o pipeline de prévia de edição valida — se faltar, a prévia se recusa a gerar
(Este é o comportamento correto do produto: se a impressão digital não corresponder, falhe, não finja com uma prévia antiga)
④ Reexportar --scale 1 — a troca de fonte é para pixels nativos, não amplie novamente
Prática segura: use sua ferramenta de busca para encontrar todos os primeiros 8 caracteres da impressão digital antiga em todos os arquivos *.json no diretório do projeto; processe cada ocorrência (registros de cache como preview-edited/current.json serão recalculados automaticamente, não precisam ser alterados manualmente).
Se o áudio for diferente (regravado, editado, duração diferente), não é uma troca de fonte — é um novo projeto: o roteiro palavra por palavra precisa ser retranscrito, todas as anotações são invalidadas. Não force a situação.
Validação: Três itens; se um faltar, a exportação não está completa
① Comando retornou com sucesso O produto verifica o tamanho, quadros, trilha de áudio do arquivo final e compara item por item com o plano.
Se não corresponder, reporta readback_mismatch, o arquivo fica no disco como evidência,
e a exportação não é considerada concluída.
② Extraia quadros e verifique pixels Extraia quadros do arquivo final e veja com os olhos. Pelo menos cubra: um segmento com zoom,
um segmento com animação em tela cheia, um segmento apenas com legendas, e a borda entre camadas.
③ Escuta humana Ninguém realmente ouviu; sempre registre como human listening UNVERIFIED
② Não use capturas de tela da prévia como substituto. Prévia e arquivo final são duas rotas de renderização; a validação deve verificar se elas correspondem — usar uma imagem da prévia como evidência do arquivo final é assumir a própria coisa que precisa ser verificada.
Para julgar se o zoom foi aplicado, procure marcos distintivos; a impressão geral engana (realmente aconteceu em 2026-07-29): após zoom de 1.6x, a tela parece ainda ser "uma página inteira"; em miniaturas, quase não difere da visão geral — uma vez, um quadro de zoom correto foi erroneamente julgado como "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 (uma bolha de texto interrompida no meio), elementos de borda desaparecidos (barra lateral, barra de título). Compare com o quadro do mesmo momento da fonte para decidir num instante.
Para extrair quadros, use ffmpeg:
ffmpeg -v error -ss 8.84 -i arquivo_final.mp4 -frames:v 1 -y frame.png
Onde investigar problemas
--keep-work deixará três coisas no diretório .chengfeng-videocut/export/ do projeto,
que separam diretamente "qual metade deu errado":
assembled.mkv Apenas a edição, sem nada sobreposto. Se der errado = problema no diário ou nos clipes.
overlay/*.png Apenas o que foi sobreposto, fundo transparente. Se der errado = problema no estilo da legenda ou no módulo.
spans/*.mp4 Segmentos após a composição. Se der errado = problema no zoom ou no alinhamento.
Tabela de referência:
Arquivo final sem legendas/animaçã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 GSAP não estava paused
Tela inteira branca Módulo faltando `:root { color-scheme: dark }`
Caixa de zoom desalinhada O viewBox do módulo e o zoom da camada não são o mesmo conjunto de números
Arquivo final mais curto que o plano Algum span tem quadros insuficientes; veja o erro na fase compose
Borda entre camadas pisca com trecho original As capturas de overlay estão desatualizadas (validação do marcador de quadro falhou). O produto depende da barra de marcadores de quadro no topo da página para provar a qual quadro cada captura pertence; se ocorrer novamente, primeiro confirme se o PNG de overlay tem a barra de marcadores no topo e se o compose cortou essa barra
Chrome não encontrado Instale o Google Chrome; não mude para outra rota de renderização
O que NÃO fazer
- Não diga "exportação bem-sucedida" como sinônimo de "validação aprovada" — o comando retornar sucesso significa apenas que o produto conseguiu se alinhar, não que a imagem está correta.
- Não use capturas de tela da prévia, DOM ou logs para substituir a extração de quadros do arquivo final.
- Não registre "human listening PASS" se ninguém ouviu.
- Não modifique arquivos de projeto (alterar legendas, excluir camadas, mexer no diário) para fazer a exportação funcionar. Exportação é somente leitura, não gravação.
- Não tente compensar o trabalho das etapas anteriores na exportação: se faltarem legendas, vá escrevê-las; se faltarem cenas, vá criá-las; não improvise nada nesta etapa.