zenstory-ai/video-reference

1. Posicionamento

Esta skill serve para desmontar um vídeo finalizado de alta qualidade sob demanda, extraindo seu ritmo de edição, divisão de áudio e técnicas narrativas em cartões de método e indicadores quantitativos que podem ser usados diretamente na próxima produção. Tudo é executado localmente, gerando apenas dados medidos, anotações de desmontagem e arquivos de referência anonimizados; não chama o MiMo, nem avalia ou bloqueia a linha de produção diária.

O Agente atua como editor de desmontagem: primeiro, registra fielmente "como este vídeo foi editado e mixado" (fatos do vídeo original) e, em seguida, extrai "como adaptar essas técnicas para um novo素材" (métodos transferíveis). Fatos e métodos devem ser rigorosamente separados: fatos que contenham nomes, tramas ou falas específicas do vídeo original ficam apenas no diretório local de desmontagem; o production_reference.json exportado contém apenas métodos genéricos e valores de ritmo medidos.

2. Entrada

• Arquivo de vídeo finalizado a ser desmontado (suporta .mp4 / .mov / .mkv / .webm).
• Diretório U com produtos de compreensão de vídeo gerados especificamente para este vídeo (recomenda-se configurar ASR_SEGMENT_SECONDS=5 na fase de compreensão para estimativas mais precisas da velocidade da narração). Esta skill lê opcionalmente asr_result.json, asr_timing_evidence.json e background_research.json (nomes de personagens, apelidos e falas ASR registrados são incluídos na varredura antivasamento de spoilers); o Agente, ao fazer anotações manuais, deve também consultar o storyboard e o vlm_analysis.json.

Mesmo sem executar a compreensão de vídeo, esta skill pode ser executada de forma independente, mas os campos de velocidade da narração ficarão vazios, a lista de palavras para antivasamento dependerá apenas dos entities escritos manualmente pelo Agente, e o check emitirá avisos correspondentes; nesse caso, use frames --span 0,<duração> --step 2 para extrair quadros e gerar um mosaico para auxiliar na visualização.

Todos os caminhos scripts/... a seguir são relativos ao diretório desta skill.

3. Fluxo de desmontagem

python3 scripts/reference.py measure <vídeo> --work-dir U        # Executa medição real de cortes e loudness com ffmpeg, armazenando em cache por identidade do arquivo
python3 scripts/reference.py frames  <vídeo> --work-dir U --review          # Gera imagens quadro a quadro para revisar janelas de corte suspeitas
python3 scripts/reference.py frames  <vídeo> --work-dir U --longest 5       # Extrai quadros dos 5 planos mais longos para verificar cortes não detectados
python3 scripts/reference.py check   --work-dir U [--json]      # Valida o arquivo de desmontagem e imprime métricas derivadas
python3 scripts/reference.py export  --work-dir U --out <diretório de trabalho da próxima execução>/production_reference.json

1. Medir cortes e loudness (measure): O script gera U/reference_measurements.json (não editar manualmente), registrando pontos de corte, distribuição de duração dos planos, cortes por minuto, curva de densidade de cortes em janela deslizante de 10 segundos, loudness integrada (Integrated LUFS), faixa dinâmica de loudness (LRA), pico verdadeiro e loudness de curto prazo por segundo. Esta etapa requer decodificação completa do vídeo (um vídeo de 5 minutos em 720p leva cerca de 15–70 segundos; 4K leva cerca de 7 minutos); desde que o arquivo de vídeo não mude, o cache será reutilizado diretamente; ajustar --soft-score ou --hard-score não requer nova decodificação.
   • Lógica inicial de detecção de cortes: Quadros com pontuação scdet ≥ 10 são diretamente classificados como cortes; entre 4 e 10, só são classificados como cortes se a pontuação do quadro for pelo menos o dobro da pontuação mais alta dos outros quadros não adjacentes em uma janela de 0,3 segundos antes e depois (ou seja, um pico local isolado). Isso filtra a maioria dos movimentos de câmera instáveis, zooms rápidos e flashes, colocando esses quadros duvidosos na janela de revisão shots.review_windows. Além disso, como a pontuação scdet subtrai a mudança de quadro anterior, ao cortar abruptamente de uma cena de movimento intenso para uma cena estática, a pontuação scdet pode cair para cerca de 1; portanto, a ferramenta também inclui picos na diferença entre quadros (mafd) em shots.review_windows para confirmação manual, mas não os considera cortes automáticos.
2. Revisar cortes visualmente (frames): Qualquer limiar fixo terá falhas em vídeos reais (cortes secos em cenas noturnas escuras podem ter apenas 5–7 pontos, enquanto um plano longo de luta intensa pode gerar picos de 7–8 pontos a cada 0,2 segundos), portanto, a revisão visual é obrigatória. Executar frames --review cria um mosaico de quadros para cada janela de revisão; executar frames --longest 5 extrai 12 quadros uniformemente dos 5 planos mais longos; as imagens são salvas em U/reference_frames/, e o terminal imprime o tempo em segundos de cada quadro. Após a revisão, registre as correções em labels.cut_fixes: add para cortes verdadeiros não detectados pelo algoritmo, remove para falsos positivos (que coincidam com cortes detectados dentro de ±0,1 segundo); se confirmar que tudo está correto, escreva explicitamente "cut_fixes": {}. Atenção: se measure for executado novamente e as janelas de revisão mudarem, as cut_fixes antigas não serão mais válidas; o Agente deve atualizá-las. Após a revisão, todas as estatísticas subsequentes (planos, densidade de cortes nas seções) serão recalculadas com base nos cortes corrigidos.
3. Anotar faixas de áudio e seções (labels): O Agente preenche labels no arquivo U/reference_breakdown.json – incluindo audio_spans (faixas de áudio), sections (seções narrativas), subtitles (estilo de legendas) e basis (fundamentação).
   • Os limites das faixas de áudio devem coincidir com os pontos reais de início/fim do som: Os pontos de transição de audio_spans devem ser baseados no momento exato em que o ouvido humano escuta a fala começar ou terminar, não copiando o momento em que as legendas aparecem ou desaparecem (anotar o final da narração pelo quadro de entrada da legenda resulta, na prática, em um atraso de 0,24–0,42 segundos). Se o diretório U/ já contiver speech_boundary_anchors.json, use seus acoustic_pauses (start é o ponto de término da fala anterior, end é o ponto de início da próxima fala) para alinhar os limites; pois a taxa de sincronização audiovisual switch_on_cut_share só considera erros de ±0,25 segundos em relação ao corte. A narração ou monólogo interno de personagens originais ainda pertencem à faixa de áudio original e devem ser rotulados como original_dialogue; se precisar diferenciar na abordagem, escreva nas seções source_facts e methods.
   • Após preencher labels, execute check para ver os valores derivados derived impressos no terminal (duração de cada faixa de áudio, densidade de cortes por seção, velocidade da narração, proporção de trocas de áudio que coincidem com cortes visuais, distribuição das seções narrativas no tempo structure e a posição relativa da primeira aparição original first_original_at).
4. Extrair fatos e métodos transferíveis (source_facts e methods): Com base nos dados derivados objetivos, continue preenchendo o mesmo reference_breakdown.json com source_facts (devem estar ancorados a intervalos de tempo ou caminhos de medição específicos, e listar explicitamente os nomes próprios envolvidos em entities) e methods (contendo a regra rule, quando se aplica applies_when, condições a evitar avoid_when, arquivos downstream afetados applies_to, evidências de suporte evidence e indicadores de referência targets). Atenção: targets só pode conter caminhos de referência {"from": "<caminho de medição>"}; é estritamente proibido escrever números específicos no corpo da regra; o script de exportação preencherá automaticamente os valores medidos.
5. Validar e exportar (check → export): Após confirmar zero erros com check, execute export para gerar production_reference.json; o exportador realiza uma varredura antivasamento de spoilers em todos os campos do artefato antes de gravá-lo.

Definições completas de campos, listas de enumerações e exemplos de métodos bons/ruins estão em references/reference-schema.md.

4. Regras de validação e antivasamento

reference.py check interrompe com código de saída 1 ao encontrar qualquer um dos seguintes erros:

Regra	Requisito de validação
R1	Níveis superior, labels, fact, method, target, cut_fixes devem usar conjuntos de chaves estritamente fechados e enumerações fechadas; fact não pode conter campos de método, method não pode conter campos de fato; IDs devem ter o formato f1… / m1… e ser globalmente únicos; campo subtitles tem tipo fixo; o motivo de skipped_dimensions deve ser uma string não vazia
R2	audio_spans e sections devem estar em ordem crescente, não se sobrepor, com lacunas adjacentes ≤ 0,5 segundos e cobrir completamente a duração total do vídeo; pontos de tempo de evidência de legenda devem estar dentro da duração do vídeo; cut_fixes.remove deve corresponder a um corte medido; add não pode duplicar cortes existentes
R3	Cada fact deve ter uma âncora de tempo t: [a, b] (dentro da duração do vídeo) ou uma âncora de medição measure: [caminho] (resolvendo para um valor não string em shots / loudness / derived), e deve preencher explicitamente o array entities
R4	Cada method deve ter pelo menos uma evidência de suporte: referenciar um fact ID definido, ou measure:<caminho> (apenas nos mesmos três caminhos raiz)
R5	target só pode conter a chave from, apontando para nós folha numéricos ou objetos derivados na lista branca em shots, loudness ou derived; é estritamente proibido usar índices de lista
R6	Em rule, applies_when, avoid_when e nos motivos de skipped_dimensions, é estritamente proibido: nomes próprios do vídeo original (comparação ignorando espaços), 8 caracteres chineses consecutivos (ignorando pontuação e janelas ASR adjacentes) ou 5 palavras inglesas consecutivas que coincidam exatamente com falas ASR/materiais de fundo/source_facts, códigos de tempo absolutos, “Nésimo segundo” ou “N minutos M segundos” (incluindo números chineses), ou caminhos absolutos locais
R7	Pelo menos um method deve ser extraído para cada uma das cinco dimensões de produção (narrative_structure, pacing, shots_editing, narration_subtitles, audio_visual); se uma dimensão não puder ser extraída, o motivo deve ser explicitado em skipped_dimensions
R8	Ao exportar production_reference.json, execute novamente a varredura R6 em todas as chaves e valores de string; o artefato exportado não pode conter as chaves source_facts, labels, entities, evidence, statement, from, path em nenhum nível

A lista de palavras antivasamento é automaticamente compilada a partir de source_facts[].entities, personagens e apelidos de character_details em background_research.json, entradas de cultural_notes com até 5 caracteres e palavras curtas entre aspas chinesas 「」. Se houver uma coincidência de 8 caracteres consecutivos com source_facts, basta reformular a expressão de edição genérica de um dos lados.

As situações a seguir geram apenas avisos (warning), não bloqueiam a exportação: method sem applies_when, números arábicos no corpo de rule, precisão ASR não AVAILABLE_COARSE, vídeo com diálogo em chinês sem nomes de pessoas nos produtos de compreensão ou base de dados (apenas com entities escritos manualmente), basis vazio, identidade do arquivo de vídeo no produto de compreensão diferente do vídeo atual medido, janelas de corte a revisar sem cut_fixes preenchido.

Nota: R6 só bloqueia coincidências literais, não impede a reescrita da trama original com palavras diferentes; ao escrever method, deve-se resumir “como lidar com determinada característica do素材”, nunca “como editar a cena do protagonista entrando”. Além disso, o validador não verifica se a semântica da linguagem natural coincide com os dados – antes de escrever “que tipo de seção tem cortes mais densos”, é obrigatório verificar os valores medidos de cuts_per_min impressos por check, evitando conclusões contrárias aos dados reais baseadas na memória.

5. Artefato e uso subsequente

O production_reference.json exportado contém apenas: duração total e dimensões do quadro do vídeo, cut_detection (parâmetros de detecção de cortes e número de cortes adicionados/removidos manualmente), profile (indicadores principais de ritmo e loudness, com marca de proveniência provenance: measured para medição puramente algorítmica, reviewed para revisão manual com cut_fixes, labeled para anotações manuais de áudio/seções), distribuição relativa das seções narrativas na linha do tempo (structure), características de estilo de legenda (subtitles), lista de métodos transferíveis (methods) e dimensões puladas (skipped_dimensions).

Como usar: coloque o production_reference.json exportado no work_dir da próxima tarefa de produção (ou vincule-o por meio do template production_reference do repositório de recursos). Quando o estágio de roteiro detectar o arquivo, ele o lerá ativamente e registrará uma decisão de adoção ( adopt / adapt / skip) para cada método no campo opcional reference_methods do recap_story_plan.json. Ao consultar métodos de referência, sempre se baseie nas imagens reais e evidências de fala do novo素材, nunca tratando a densidade de cortes ou proporção de silêncio do vídeo de referência como cotas fixas a serem aplicadas mecanicamente. Nenhum script de produção valida mecanicamente este arquivo; sua presença ou ausência não altera o resultado de nenhuma verificação.

O reference_breakdown.json e os mosaicos de quadros reference_frames/ no diretório U/ contêm fatos e imagens do vídeo original, destinados apenas ao uso local na desmontagem; não os copie para novos projetos ou os submeta a repositórios públicos.

6. Limitações

• Todo o processamento é local, não chama o MiMo ou qualquer modelo grande, não modifica os produtos de compreensão de vídeo upstream e não avalia a qualidade do vídeo finalizado nem calcula a “diferença entre o novo vídeo e o de referência”.
• A detecção de cortes baseia-se na pontuação scdet do ffmpeg mais revisão visual manual: transições lentas (dissolve) não são detectadas automaticamente; dois cortes rápidos consecutivos com intervalo inferior a 0,3 segundos, cortes exatamente no limite do soft_score (versões diferentes do ffmpeg podem dar 4,00 vs 3,989) e cortes secos após movimento intenso (pontuação pode cair para 0,9) não são considerados cortes automáticos, mas são colocados na janela de revisão para cobertura manual. Em um teste real com um vídeo de 5 minutos de análise de série, a detecção inicial encontrou 82 cortes e, em 11 janelas de revisão, capturou todos os 5 cortes verdadeiros perdidos (as outras 7 janelas eram zooms rápidos, viradas de página e planos com movimento); após o revisor visual adicionar esses 5 cortes, houve 100% de concordância com a verdade absoluta manual (27 cortes no total) em três pontos do vídeo (início, cena escura e meio), sem falsos positivos.
• A proporção de narração e a velocidade da fala são de precisão labeled: estimadas a partir de intervalos de áudio anotados manualmente combinados com janelas ASR de granularidade grossa, não alinhadas com timestamps palavra por palavra.
• A varredura antivasamento de spoilers baseia-se em comparação literal de strings; o Agente ainda deve realizar uma autorrevisão ativa ao escrever, garantindo que methods descrevam técnicas de criação genéricas, e não um resumo da trama do vídeo original.

---

Esta skill foi criada por zenstory-ai.