zenstory-ai/video-recap

1. Posicionamento e Fluxo

Esta skill é uma skill autossuficiente de produção de narração e edição de vídeo, que converge compreensão de vídeo, definição de história, edição de cenas, redação de roteiros, síntese de voz e mixagem de áudio e vídeo em um único fluxo de trabalho contínuo. Cada etapa compartilha os mesmos artefatos JSON e MP4 sob o diretório de trabalho work_dir:

understand.py (compreensão de vídeo)─▶ Agente define plano de história/áudio-vídeo e escreve clip_plan.json ou narration.json ─▶ [cut.py (edição e reextração de storyboard)] ─▶ validate.py (verificação local de segurança) ─▶ voiceover.py (TTS) ─▶ assemble.py (mixagem e renderização de legendas)

Para uso diário, pode-se chamar diretamente a entrada principal scripts/recap.py para executar automaticamente todo o fluxo e pausar nos pontos de criação, ou chamar individualmente as entradas de cada etapa em scripts/ (understand.py, cut.py, validate.py, voiceover.py, assemble.py).

A decomposição de um vídeo finalizado em uma referência de produção (production_reference.json) não faz parte do fluxo de produção padrão. Quando o usuário solicitar a análise de um vídeo de exemplo: primeiro execute understand.py no vídeo de amostra (é recomendado definir ASR_SEGMENT_SECONDS=5), depois use a skill independente de análise para executar sequencialmente medição (measure), anotação, verificação (check) e exportação (export). Copie o production_reference.json exportado para o work_dir da próxima execução, ou registre-o como um template production_reference na biblioteca de recursos e vincule-o via --project. O fluxo principal não executa a análise automaticamente, nem compara mecanicamente o novo vídeo finalizado com o de referência.

Todo o fluxo suporta retomada a partir de um ponto de interrupção: depois que o Agente escreve clip_plan.json ou narration.json, basta executar o mesmo comando recap.py novamente para continuar. Ao retomar, o script verifica o caminho do vídeo de origem, tamanho do arquivo, hora da modificação e parâmetros de execução registrados em recap_run_manifest.json. Se o diretório de trabalho for de outro vídeo ou com parâmetros diferentes, a reutilização é rejeitada diretamente; o cache de compreensão de vídeo só é utilizado quando o vídeo de origem e a configuração são exatamente idênticos. O comando de retomada impresso no terminal a cada pausa mantém a chamada original, mas converte automaticamente os parâmetros de vídeo e caminho para caminhos absolutos, completa --work-dir, e pode ser copiado e colado em qualquer diretório para execução.

O fluxo de vídeo (--edit-mode full|cut) e a estratégia de áudio (--audio-mode narration|source-mix) são independentes: narration segue a cadeia padrão de narração e dublagem; source-mix não gera narração, mas mistura diretamente o áudio original com música de fundo opcional. O sistema suporta apenas as cinco rotas legais listadas na tabela abaixo; outras combinações são bloqueadas com erro na inicialização:

Entrada	--edit-mode	--audio-mode	Pausa do Agente	Fluxo	Detalhes
Vídeo único	full	narration	1 vez: escrever narration.json	Compreensão → Roteiro → Verificação → Dublagem -> Síntese	§4
Vídeo único	cut	narration	2 vezes: primeiro escrever clip_plan.json, depois de editar, escrever narration.json para o vídeo final	Compreensão → Edição -> Reextração de storyboard de saída -> Roteiro → Verificação → Dublagem -> Síntese	§4
Múltiplos vídeos	cut	narration	2 vezes: o mesmo que acima, e cada clipe deve ter source_id	Compreensão individual → Edição → Roteiro → Verificação → Dublagem -> Síntese	§4.5
Vídeo único	full	source-mix	Sem pausa	Sintetizar diretamente o vídeo completo atual (sem compreensão ou TTS)	§4.7
Único / Múltiplos vídeos	cut	source-mix	1 vez: escrever clip_plan.json	Compreensão → Edição -> Síntese (sem escrever narração)	§4.7

2. Responsabilidades Criativas

O poder de decisão criativa é totalmente do Agente. Antes de começar, determine o modo de controle criativo da rodada (CREATE criação aberta / DIRECTED criação direcionada / REVISION revisão final, independente de --edit-mode), e antes de entrar na dublagem e renderização, como um único cérebro criativo, execute cinco julgamentos em sequência:

1. Decisão de Direção: Esclareça por que o público clicou para assistir, de quem é o ponto de vista (POV) durante todo o vídeo, qual é o mistério central, onde a emoção começa e termina, e qual carta é guardada para o final.
2. Edição da História: Cada batida (beat) deve explicar "qual mudança substancial na situação ocorreu", nunca escreva resumos de cena superficiais.
3. Edição de Imagem: Selecione as ações mais marcantes, reações faciais e os melhores pontos de entrada e saída, eliminando transições desnecessárias.
4. Som / Narração: Primeiro, decida para cada batida se a imagem, o diálogo original, o som de ação, o silêncio ou a narração serão o elemento principal. Depois, escreva o texto seguindo o princípio "apoia meia frase, cede meia frase, completa meia frase".
5. Revisão do Público: Coloque-se na perspectiva de um espectador que está assistindo pela primeira vez e realize três verificações: assistir à imagem sem narração, fechar os olhos e ouvir apenas o som, e verificar se o início e o fim cumprem o que foi prometido.

A divisão de trabalho dos três modos de controle, as regras de bloqueio sem reversão no modo REVISION, as técnicas específicas de edição e escrita, e os formatos de recap_story_plan.json, visual_audio_board.json e style_card.json estão detalhados em references/creative-editing-playbook.md. Esses JSONs são usados para consolidar decisões criativas que podem ser revisadas, garantindo que a seleção de cenas, o silêncio do áudio original e o texto da narração estejam alinhados com a mesma intenção narrativa do início ao fim.

3. Ambiente e Notas sobre Chamadas Remotas

# ffmpeg: brew install ffmpeg | apt install ffmpeg | choco install ffmpeg
export MIMO_API_KEY=***

Uma única MIMO_API_KEY é suficiente para acionar toda a cadeia padrão. Para garantir a transparência do fluxo de dados, as etapas que envolvem chamadas de rede remota são explicadas abaixo:

• Compreensão de Vídeo (understand.py): Envia janelas de áudio segmentadas para o MiMo ASR (mimo-v2.5-asr) e frames JPEG extraídos, juntamente com um resumo de background_research.json, para o MiMo VLM (mimo-v2.5). Se o diretório de trabalho já tiver artefatos de análise completos, passar --brief-only ou --edited-storyboard-only executa puramente localmente, sem iniciar nenhuma requisição de rede.
• Narração por Voz (voiceover.py): Envia o texto da narração para o serviço TTS correspondente de acordo com --tts-provider (padrão auto prioriza MiMo configurado, depois Fish Audio, nunca seleciona index-tts automaticamente):
  • mimo-tts: Envia para o MiMo TTS (mimo-v2.5-tts); se --voice-ref <audio> for passado explicitamente, um segmento desse áudio de referência também é enviado para mimo-v2.5-tts-voiceclone (certifique-se de ter a autorização de voz antes de usar).
  • fish-audio: Requer FISH_API_KEY configurada. Envia cada segmento de texto de narração e FISH_TTS_REFERENCE_ID para FISH_TTS_API_URL (padrão https://api.fish.audio/v1/tts).
  • index-tts: Ativado apenas quando --tts-provider index-tts é especificado explicitamente. Envia o texto e INDEX_TTS_VOICE para o INDEX_TTS_ENDPOINT auto-hospedado pelo usuário (veja references/index-tts.md para detalhes).
• Verificação de Narração (validate.py), Edição de Vídeo (cut.py, shot_review.py) e Síntese de Áudio e Vídeo (assemble.py): Lógica determinística local e chamadas a ffmpeg / ffprobe, não iniciam nenhuma requisição de rede.

Chaves de Token Plan que começam com tp- são enviadas para o cluster da China por padrão. É possível alternar o cluster através de MIMO_TOKEN_PLAN_CLUSTER. A lista completa de itens de configuração está em references/config-playbook.md. Os formatos de todos os artefatos intermediários estão em references/data-schema.md. Os scripts/... mencionados abaixo são relativos ao diretório desta skill.

4. Fluxo de Criação e Edição Fluente

4.1 Pesquisa de Contexto e Compreensão de Vídeo

Se for possível identificar o nome do filme, série ou tópico educacional a partir do nome do arquivo ou instrução do usuário, antes de iniciar, pesquise as relações dos personagens e o contexto anterior de acordo com references/research-guide.md e escreva em work_dir/background_research.json. Assim, ao analisar as imagens posteriormente, os nomes dos personagens podem ser chamados corretamente e as entrelinhas compreendidas, evitando descrições genéricas como "homem de preto" ou "jovem mulher". Para edição de múltiplos vídeos, escreva também no diretório raiz do projeto work_dir, e o script sincronizará automaticamente para os subdiretórios de origem sources/<source_id>/.

Em seguida, inicie a entrada de compreensão e organização:

python3 scripts/recap.py <video> --work-dir <work_dir> --context "contexto"

Após a extração de áudio, detecção de âncoras de pausa silenciosa e de fim de frase (speech_boundary_anchors.json), segmentação de cenas, análise de frames VLM e transcrição ASR, o script gera o mosaico do storyboard storyboard/storyboard_*.jpg e o resumo criativo agent_narration_brief.md, e pausa automaticamente.

4.2 Intenção de Direção e Plano de Seleção de Cenas (Primeira Etapa do cut)

Após ler agent_narration_brief.md e visualizar diretamente as imagens extraídas do storyboard, escreva primeiro recap_story_plan.json (listando pelo menos 2 planos candidatos e selecionando o POV principal, o gancho de abertura, o arco emocional e a carta na manga) e visual_audio_board.json (especificando para cada batida qual instante escolher, por que entrar e sair, e quem domina o som).

Na primeira etapa do modo cut, em seguida, escreva o work_dir/clip_plan.json baseado na linha do tempo do vídeo original (SOURCE) (não escreva narration.json ainda):

{
  "target_duration": "3m",
  "clips": [
    {
      "start": 12.0,
      "end": 38.0,
      "reason": "b01 | hook | knowledge: unknown→threat | POV=沈曼 | Encontra o noivo abraçando a herdeira falando sobre casamento arranjado | Ponto de entrada=abre a porta e vê a ação dos dois | Ponto de saída=se vira e aperta o livro de registro familiar"
    }
  ],
  "required_evidence": {
    "nodes": [
      {"id": "e1", "source": "/abs/source.mp4", "start": 14.2, "end": 18.6, "track": "video", "content": "Abre a porta e encontra os dois se abraçando"}
    ],
    "before": []
  }
}

A seleção de cenas e os pontos de corte devem respeitar rigorosamente as seguintes regras de segurança:

• Estrutura de reason em sete partes: Escreva sequencialmente id_da_batida | função narrativa | mudança no estado da situação (A→B) | POV=personagem | ponto crucial real deste segmento | ponto de entrada=ação específica/âncora de áudio original | ponto de saída=reação específica/ponto de chegada, forçando cada segmento de imagem a servir ao avanço da história.
• Evidências de imagem e áudio originais obrigatórias (required_evidence): As ações de destaque, momentos de mudança facial ou perguntas e respostas-chave do áudio original que devem ser mantidos são registrados em required_evidence de nível superior (nodes registra id/source caminho absoluto/start/end/track/content, before registra pares de ordem imutável); se a atração de borda cortar qualquer intervalo obrigatório ou alterar a ordem, o script irá parar com erro.
• Entrada tardia e escolha de cenas: Por padrão, siga a ordem temporal "entrada tardia" (entre diretamente no conflito, no contraste absurdo ou na ação-chave, eliminando introduções lentas como entrar em uma sala ou cumprimentar); apenas quando o conflito em ordem cronológica aparecer muito tarde, é permitido extrair uma cena de suspense de abertura de <= 2.5s, e ela deve ser compreensível sem contexto, não repetir o mesmo ângulo da cena principal, e apenas criar suspense sem revelar o resultado da reviravolta. Quando a narração abaixa o volume do áudio original, priorize reações de ouvintes, detalhes de ação ou planos estáveis, evitando colocar imagens de personagens falando efusivamente de frente e sendo silenciados sob a narração; não repita o mesmo plano de aceno ou olhar vazio mais de duas vezes.
• Pontos de corte seguros no final da frase e respiro final: O ponto de corte deve cair no início/fim do vídeo original, em âncoras de pausa de fim de frase ou em janelas de silêncio, ou ser uma transição suave entre segmentos adjacentes da mesma fonte; ao atrair para o final da frase, reserve automaticamente no máximo 0.30s para reação/respiro dentro da janela de pausa e nunca cruze um ponto de corte brusco. A duração mínima do segmento não é inferior a 0.8s. O último batida do vídeo deve deixar 1.5–2.5s de resquício emocional após a conclusão da ação ou fala final, e terminar de forma limpa antes de passar para a próxima cena. Pisar no meio de uma fala original aciona o bloqueio unsafe_clip_sentence_boundary e fornece nearest_safe; se ao recuar a atração brusca da borda expuser simultaneamente quadros flash <= 0.20s e cortar a fala, isso aciona diretamente o bloqueio shot_speech_conflict.
• Edição rápida de alta frequência e verificação de fragmentos: Após cut.py renderizar edited_source.mp4, ele chama automaticamente shot_review.py para gerar shot_review.json e bloqueia diretamente quadros flash muito curtos (flash_slivers) com duração <= 0.20s (cerca de 1–5 quadros). Ao lidar com cenas de ação ou planos de contraplano densos, pode-se executar manualmente ffmpeg -i <video> -vf "select='gt(scene,0.35)',showinfo" -f null - ou a ferramenta somente leitura scripts/shot_review.py (uso em references/shot-review.md) para localizar pontos de corte de alta pontuação, mas é necessário distinguir entre cortes nativos do vídeo original e cortes artificiais criados pela edição atual. Se os cortes forem cortes de curta duração nativos do vídeo original que são excluídos completamente ou se o ponto de corte for movido para fora do cluster de cortes rápidos; se forem cortes artificiais criados pela edição atual (como alguns quadros de uma cena adjacente na borda de um corte brusco, planos de contraplano fragmentados), expanda o ponto de entrada/saída ou mescle segmentos adjacentes da mesma fonte. É estritamente proibido usar transições para disfarçar.

Depois de escrever clip_plan.json, execute recap.py novamente. O script chama cut.py para concluir três etapas de atração de borda (atração para corte brusco de cena → atração para silêncio de fim de frase e respiro → alinhamento à grade de quadros), renderiza edited_source.mp4 com taxa de quadros constante e realiza a verificação de quadros flash. Em seguida, remapeia os pontos de ancoragem ASR, VLM e de fim de frase para a linha do tempo de saída do vídeo finalizado (speech_boundary_anchors_output.json, storyboard/edited_storyboard.*), e pausa novamente aguardando a escrita do roteiro.

4.3 Criação de Roteiro e Silêncio do Áudio Original (Segunda Etapa do full / cut)

Ao entrar na fase de escrita do roteiro (modo full na primeira pausa, modo cut na segunda pausa após a edição de edited_source.mp4), primeiro visualize o storyboard editado, complete visual_audio_board.json com o tempo de saída do vídeo finalizado e, se necessário, escreva style_card.json. Em seguida, escreva work_dir/narration.json:

[
  {
    "start": 0.2,
    "end": 5.0,
    "narration": "Depois de cinco anos juntos, segurando o livro de registro para pedir em casamento, Shen Man abre a porta e encontra o noivo abraçando a herdeira, falando sobre um casamento arranjado.",
    "pause_after_ms": 250,
    "overlaps_speech": true
  }
]

Nota: No modo cut, narration.json deve preencher diretamente os timestamps OUTPUT do vídeo finalizado (0 .. duração total do vídeo finalizado) (ao chamar o validador separadamente, passe validate.py --mode cut_output). Ao escrever, siga as nove regras fundamentais de escrita (detalhes e exemplos positivos/negativos em references/creative-editing-playbook.md):

1. Nos primeiros 2,5 segundos, mostre o gancho ou o destaque do áudio original, apresentando diretamente uma ação contrastante específica ou o mistério central. Não escreva biografias de personagens, anúncios de data ou aberturas de cortesia; uma abertura fria com mais de 2.5s sem narração ou diálogo original aciona o bloqueio weak_cold_open_silence.
2. Explique o contexto, as relações dos personagens e a causa e efeito, controle a densidade de nomes próprios, recuse "descrição do que se vê": Quando background_research.json já fornecer nomes de personagens, é estritamente proibido usar termos genéricos como "homem de preto" ou "jovem mulher" (violação gera o bloqueio generic_character_label); em clipes de até 60 segundos, nomeie no máximo 1–2 personagens principais (no máximo 1 pessoa na primeira frase, esclarecendo a identidade). Os personagens secundários restantes devem ser chamados por relação/identidade (por exemplo, "ex-namorada", "chefe dela", "médico imperial"), e cada frase deve progredir em torno de "situação → ação → consequência imediata".
3. Sincronização áudio-visual "apoia meia frase, cede meia frase, completa meia frase" e forte visual deve estar em sincronia: Diálogos originais de destaque, sons de tapa, mudanças faciais silenciosas: ceda o lugar decisivamente antes, e após o áudio original terminar, complete com meia frase para revelar a entrelinha. Quando a imagem mostrar ações visuais fortes como beijo, tapa, ajoelhar, desmaio, mostrar um objeto de confiança, a causa e efeito devem ser explicados pelo áudio original preservado ou pela narração adjacente. É proibido que cada um fale sobre si. É estritamente proibido ter janelas vazias de mais de 5.0s consecutivas sem narração ou diálogo original (violação aciona o bloqueio excessive_dead_air).
4. Respeite rigorosamente as linhas vermelhas de entrada e retorno do áudio original: Ao abaixar o volume do áudio original para entrar com a narração (overlaps_speech: true), start deve estar próximo a uma âncora de fim de frase ou zona de silêncio (violação aciona o bloqueio interrupts_source_sentence); ao restaurar o volume do áudio original após a narração terminar, não o faça no meio da fala de um personagem (violação aciona os bloqueios unsafe_source_release / unsafe_source_handoff nas fases de verificação e síntese, respectivamente).
5. Controle rigoroso do orçamento de palavras por janela de tempo, mantenha velocidade de fala natural e finalize com frase completa: Cada parágrafo deve terminar com pontuação final de frase completa (frase incompleta gera bloqueio incomplete_sentence). Use a contagem de palavras enxuta para se ajustar à janela de tempo, em vez de contar com uma velocidade muito alta para encaixar. No modo full, exceder o orçamento em 1,25 vezes aciona diretamente o bloqueio over_budget. O validador nunca remove palavras para o Agente.
6. Elimine tom de comentário editorial e tom telegráfico, deixe o final ser representado pelas imagens: Escreva frases longas e curtas naturais e coerentes, não escreva frases fragmentadas de uma palavra só. É estritamente proibido escrever comentários editoriais e clichês de conclusão como "Isso significa...", "Esta é uma batalha sobre...", "Deixe o poder e o orgulho de lado", "A engrenagem do destino" (isso aciona o alerta editorial_commentary_tone). O desfecho da história deve ser representado pelas imagens e pelo áudio original. É estritamente proibido adicionar uma narração conclusiva redundante após o desfecho, e também não se deve arrastar uma cauda de áudio original que repita o mesmo resultado após a narração final.
7. Ancore-se em evidências de imagem específicas e disciplina de música instrumental: Use olhares, adereços e detalhes de ação que possam ser vistos. Não invente atividades psicológicas para os personagens fora da tela. Se usar música de fundo externa (BGM_PATH), deve ser puramente instrumental (zero vocais). Quando o vídeo original já tiver uma música de fundo com vocais altos e inevitáveis, não adicione música de fundo externa, para evitar conflito de múltiplas faixas de voz.
8. Revise as legendas de áudio originais: Quando a máscara de legenda do vídeo original estiver ativada e houver parágrafos de áudio original de destaque sendo mantidos, escreva sincronizadamente em work_dir/original_subtitles.json as falas originais revisadas de acordo com o tempo do vídeo finalizado, corrigindo erros de homofonia do ASR.
9. Após escrever, faça três auto-verificações: Primeiro, leia o texto completo para ver se a linha da história está coerente e se os fatos correspondem ao vídeo original. Depois, verifique em relação às janelas de tempo se há fala sobreposta ou excesso de palavras. Finalmente, execute validate.py (ou simplesmente execute recap.py novamente). Se precisar escrever títulos promocionais externos, frame de capa e texto gráfico (packaging_plan.json), execute após o bloqueio da história principal, de acordo com references/promotional-copy.md.

4.4 Síntese de Voz e Renderização de Mixagem de Áudio e Vídeo

Depois de escrever narration.json, execute o mesmo comando recap.py novamente:

1. Verificação Determinística Local (validate.py): Gera narration_lint.json. Realiza verificações rigorosas para: sobreposição de tempo, extrapolação, orçamento de palavras excedido, frases incompletas, abertura fria, janela de silêncio morto superior a 5 segundos, interrupção de fala original, retorno de áudio original no meio de uma frase, referências genéricas a personagens e vazamento de placeholders. Se houver um erro, a execução é interrompida imediatamente.
2. TTS (voiceover.py): Sintetiza voz para cada segmento e escreve em tts_segments/ e tts_meta.json. O cache é acionado precisamente pelo texto, timbre, modelo e impressão digital do áudio de referência. Se a duração de áudio de um segmento estiver abaixo do limite inferior da velocidade de fala normal (TTS_MIN_SPEECH_RATE), suspeitando de alucinação do modelo, ele tenta novamente automaticamente e mantém *.rejected.wav sem adicionar ao cache.
3. Síntese de Áudio e Vídeo (assemble.py): Mistura e renderiza o vídeo final MP4, incluindo: imagem, narração segmentada, áudio original com volume reduzido e restaurado no final da frase (veja a descrição de source_handoff_status em references/data-schema.md), BGM opcional (BGM_PATH), efeitos sonoros de transição opcionais e embalagem visual sofisticada (work_dir/packaging_plan.json: suporta moldura vertical 9:16 com linhas douradas duplas para palco/série, moldura 16:9 com carimbo de cinema e faixa de legenda em papel branco, sobreamostragem @2x para placas de identificação de personagens, cartões de dados e letras caligráficas, e iluminação suave de dupla camada para palavras-chave destacadas; ou packaging_layers.json para imagens estáticas), e fade out suave no final (padrão 350ms). Também gera timeline.json independente do backend (passe --export-jianying para exportar simultaneamente o rascunho do Jianying).

Se qualquer segmento de narração não couber na janela de tempo disponível mesmo dentro do limite de micro-aceleração permitido, o sintetizador reporta o bloqueio no_safe_fit, nunca corta a cauda do áudio da narração. Mais modos de áudio, roteamento de áudio e especificações de embalagem visual externa estão em references/audio-modes.md, references/audio-routing.md e references/packaging.md, respectivamente.

4.5 Edição de Múltiplos Vídeos e Biblioteca de Recursos

A entrada de múltiplos vídeos suporta apenas o modo cut. O resumo de nível de projeto lista o source_id fixo para cada vídeo. Ao escrever clip_plan.json, cada segmento deve indicar o source_id ao qual pertence:

python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --target-duration 10m --work-dir work_dir_multi_ep

Se quiser armazenar os resultados da compreensão de um episódio em um diretório local para reutilização entre episódios, ative a biblioteca de materiais de arquivo leve (--material-library-dir .video-materials --save-materials e --use-materials), e use diretamente grep para pesquisar arquivos JSON/MD. No mesmo diretório raiz da biblioteca, também é possível registrar recursos de produção reutilizáveis (BGM, efeitos sonoros, timbres, fontes, texturas), modelos com registro de adoção (subtitle_style, packaging, production_reference) e vídeos de amostra. Consulte com scripts/library.py check|list|show, e vincule com --project recap_project.json para a execução atual. Após cada síntese, os recursos realmente usados e seu status de autorização são registrados em work_dir/resource_lock.json. Veja references/resource-library.md para detalhes.

Para medir o intervalo de pixels verticais de legendas duras em um vídeo original para ativar a máscara precisa, execute tools/measure_subtitle.py <video> no repositório de código-fonte completo, ou meça os limites superior e inferior diretamente nas imagens extraídas, e então passe --subtitle-y-top e --subtitle-y-bot.

4.6 Visualização Final e Revisão de Entrega

Nenhum indicador de script, pontuação de ponto de corte, mosaico de quadros extraídos ou relatório de QC automático substitui a visualização com os próprios olhos e a audição com os próprios ouvidos. Antes de cada entrega, é obrigatório abrir o arquivo de vídeo final que será entregue ao usuário nesta rodada e realizar uma revisão em cinco etapas:

1. Assista uma vez em velocidade normal: Do início ao fim, sem acelerar ou pular, anotando todos os lugares que chamam a atenção ou travam.
2. Examine cada ponto de corte individualmente: Veja 0.5-1 segundo antes e depois de cada ponto de corte, procurando por quadros flash, dissolves incompletos, jump cuts e meias frases de áudio original cortadas.
3. Feche os olhos e ouça uma vez: Sem olhar para a imagem, apenas ouça o som. Verifique se a narração está fragmentada em um tom telegráfico aos trancos e barrancos, se o som nas transições é suave e se as falas originais principais estão claras.
4. Examine três pontos cruciais separadamente: Veja novamente o gancho de abertura dos primeiros 5 segundos, o ponto de explosão emocional do meio e a última cena final. Confirme se o timing de entrada, a permanência emocional e o resquício final são todos convincentes.
5. Conciliação de revisão e verificação de especificações: No modo REVISION, primeiro confirme item por item "o que foi especificamente solicitado para ser alterado foi realmente alterado, o que não foi mencionado permanece intocado". Finalmente, verifique a integridade da decodificação, duração total, varredura de quadros residuais e especificações de codificação de áudio e vídeo em final_qc.json (--require-final-qc está ativado por padrão, itens de bloqueio determinam o código de saída diretamente; passe --no-require-final-qc apenas para depuração).

Ao entregar o vídeo finalizado, certifique-se de verificar metadata.warnings em final_qc.json. Se não estiver vazio (por exemplo, após ativar a tolerância parcial, partial_tts com segmentos faltando, ou o ffmpeg local sem libass acionando subtitle_burn_degraded com downgrade para .srt externo), informe o usuário honestamente, não apenas diga "renderização bem-sucedida".

4.7 Vídeo Finalizado com Áudio Original sem Narração

# Mistura e sintetiza diretamente a entrada de vídeo completa atual; não executa compreensão, ASR ou TTS implicitamente
python3 scripts/recap.py locked_picture.mp4 --work-dir source_work --audio-mode source-mix
# Gera um plano de edição seguindo o fluxo cut, edita e sintetiza o vídeo finalizado com áudio original, sem pausar para narration.json
python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --work-dir cut_work --audio-mode source-mix

source-mix passa pela mixagem completa, fade out suave no final e re-codificação de áudio. Ao alternar o modo de áudio, use um diretório de trabalho novo. Veja references/audio-routing.md para detalhes.

5. Auto-Verificação e Painel Somente Leitura

python3 scripts/doctor.py
python3 scripts/dashboard_server.py --root <diretório> [--port 0] [--open]

doctor.py verifica a conectividade do ffmpeg / ffprobe local, filtros de legenda e chaves de serviços remotos; dashboard_server.py inicia um painel de revisão de vídeo estritamente somente leitura em 127.0.0.1 (responde apenas a GET e HEAD), escaneia automaticamente os diretórios de trabalho de vídeo finalizado e library.json sob --root, e exibe de forma intuitiva a reprodução do vídeo finalizado, a narração e a sincronização do storyboard, bem como a pré-visualização da biblioteca de materiais.

6. Saída e Parâmetros

Entregáveis principais:

• recap_<video>.mp4: Vídeo finalizado com narração ou áudio original.
• subtitles.srt / subtitles.ass: Arquivos de legenda gerados.
• work_dir/: Conjunto completo de artefatos de análise, planos e verificação intermediários. O contrato de campos está em references/data-schema.md.
• work_dir/recap_story_plan.json e visual_audio_board.json: Decisões de intenção de direção e storyboard/áudio do Agente.

A lista completa de parâmetros de linha de comando é fornecida por python3 scripts/recap.py --help e pela saída --help de cada script de etapa. --style é um requisito de texto livre que é passado diretamente para o Agente de roteiro, não é uma predefinição fixa ou chave de enumeração.

7. Limites de Capacidade

• A verificação de segurança local determinística (quadros residuais/quebrados, corte de fala, narração sobrepondo fala, limite rígido de palavras por janela de tempo, corte de cauda muito longo, perda de evidência obrigatória, vazamento de placeholder, especificações de decodificação e empacotamento) sempre opera como uma barreira rigorosa; o script é responsável apenas pela execução mecânica e pela garantia do piso de engenharia.
• A qualidade semântica e narrativa, como arco da história, gancho de abertura, respiração áudio-visual e consistência factual, não possui barreiras de pontuação de modelo. O Agente deve controlar de forma autônoma, com base nas evidências de imagem, na linha do tempo do áudio original e em references/creative-editing-playbook.md, e concluir a revisão audiovisual antes da entrega.