video-to-shorts

Vídeo Para Shorts

Dependências

/video-understand é um pré-requisito. Execute-o primeiro para que os shorts usem a transcrição fonte validada e a linha do tempo canônica. Antes de começar, verifique se ele está instalado. Se não estiver, avise o usuário que este pré-requisito está faltando e pare antes de processar a mídia.

Requer ffmpeg/ffprobe no PATH e Python com Pillow. Verifique-os antes de processar a mídia.

Escopo

Esta skill tem duas fases de projeto:

1. Planejar antes de renderizar: mapear a transcrição compreendida para o tempo do programa, autorar e aprovar candidatos, e escrever work/shorts/shorts-plan.json. Esta fase não escreve nenhum vídeo final.
2. Finalizar após a renderização: depois que cada edição principal selecionada for aprovada e a entrega principal compartilhada for verificada, execute plan.py novamente para vincular os mesmos intervalos aprovados a essa entrega, e então extrair as saídas horizontais e verticais opcionais.

Ela possui o julgamento de candidatos a short, qualificação determinística, extração horizontal, transcrições relativas a shorts e entrega vertical determinística opcional. Ela não transcreve no modo de projeto, não altera a sequência principal, não adiciona legendas/gráficos, não faz correção de cor, não publica e não realiza rastreamento contínuo de assunto.

Os Shorts entregues são derivados de final/final-video.mp4, mas o planejamento de candidatos precede esse arquivo. Registre a operação no DAG do projeto, mas nunca a adicione a sequences.main.operations; a entrega principal e sua comparação original-vs-final permanecem inalteradas.

Entradas do Projeto

• work/project.json
• a fonte do projeto registrada por project.source.path
• work/understand/transcript.json no tempo da fonte
• work/timeline.json
• revisões ativas da operação principal em cada fase

O planejamento não requer final/final-video.mp4. A finalização e extração exigem essa renderização exata do projeto com render.status: verified.

prepare_transcript.py --timeline chama o projectlib.map_transcript_to_timeline compartilhado. Os tempos de candidatos/extração são, portanto, segundos de programa no vídeo final real. Palavras removidas pela edição principal não estão disponíveis para shorts. Cada palavra retida mantém seus source_range, program_range e clip_id.

Os metadados da transcrição do projeto vinculam a fonte do projeto, a transcrição fonte e a linha do tempo por caminho absoluto, tamanho, hora de modificação e SHA-256. Os quadros de revisão de candidatos mapeiam seus timestamps de programa de volta através de timeline.json para o vídeo fonte. A validação de candidatos recusa uma vinculação alterada.

Estrutura de Saída

work/shorts/
|-- transcript.json
|-- transcript_metadata.json
|-- candidates.json
|-- shorts-plan.json
|-- review/
|   |-- candidate_review.json
|   `-- approved_candidates.json
`-- short-001/
    |-- transcript.json
    |-- extraction-report.json
    `-- vertical-agent/
        |-- agent_vertical_plan.json
        |-- vertical_plan.json
        `-- review/vertical_review.json

work/cache/shorts/                 # quadros/folhas/mídia intermediária descartáveis

review/06-shorts/
|-- candidates-<review-id>.html              # página imutável e autoritativa
|-- candidates-<review-id>-question.md
|-- assets/candidates-<review-id>/            # quadros imutáveis de início/meio/fim
|-- candidates.html                           # alias mais recente não autoritativo
|-- candidates-summary.md
|-- short-001-horizontal.jpg
|-- short-001-vertical-preview.mp4
|-- short-001-vertical-contact-sheet.jpg
|-- short-001-vertical-preview-summary.json
|-- short-001-vertical-preview-probe.json
|-- <short-id>-vertical-review-<review-id>.html # página imutável e autoritativa
|-- <short-id>-vertical-review-<review-id>-question.md
|-- <short-id>-vertical-review.html             # alias mais recente não autoritativo
|-- <short-id>-vertical-review-assets/
|   `-- <review-id>/                             # evidência autoritativa imutável
|       |-- preview.mp4                          # ausente para REVIEW_REQUIRED
|       |-- contact-sheet.jpg                    # ausente para REVIEW_REQUIRED
|       |-- preview-summary.json
|       `-- media-probe.json
`-- shorts-summary.md

final/shorts/
|-- short-001-horizontal.mp4
`-- short-001-vertical.mp4          # somente quando selecionado e aprovado

Transcrição do Programa

Execute a partir da raiz do repositório:

$RepoRoot = (Resolve-Path ".").Path
$SkillRoot = Join-Path $RepoRoot "skills\video-to-shorts"
$ProjectRoot = (Resolve-Path "<project-root>").Path
$Work = Join-Path $ProjectRoot "work"
$ShortsWork = Join-Path $Work "shorts"
$ProjectSource = (Resolve-Path "<project-source-from-work/project.json>").Path
$FinalVideo = Join-Path $ProjectRoot "final\final-video.mp4"
$ShortsReview = Join-Path $ProjectRoot "review\06-shorts"
New-Item -ItemType Directory -Force $ShortsWork,$ShortsReview | Out-Null

python "$SkillRoot\scripts\prepare_transcript.py" $ProjectSource `
  --transcript "$Work\understand\transcript.json" `
  --timeline "$Work\timeline.json" `
  --out $ShortsWork

O modo de linha do tempo do projeto requer a transcrição fornecida canônica. O modo autônomo pode omitir --timeline; ele mantém o tempo relativo à entrada e pode usar o fallback temporário video-understand/scripts/transcribe.py. Nenhuma transcrição é descoberta automaticamente.

Criação de Candidatos

Gere contexto visual do vídeo longo no cache, inspecione cada folha necessária para uma decisão, e crie manualmente o JSON do candidato. O código determinístico valida o julgamento editorial; ele não inventa candidatos ou pontuações.

python "$SkillRoot\scripts\prepare_visual_context.py" $ProjectSource `
  --timeline "$Work\timeline.json" `
  --out "$Work\cache\shorts\candidate-visual" --interval 15

A entrada do candidato permanece shorts-candidates.v2 para compatibilidade. Defina selection.evidence_mode e cada evidence_mode do candidato como text_visual. Cada candidato requer:

• candidate_id, título e tipo de cena estáveis;
• start_time/end_time completos no tempo do programa;
• transcript_excerpt exatamente igual às palavras de transcrição sobrepostas, não segmentos inteiros sobrepostos;
• todas as seis entradas de pontuação e motivos não vazios;
• metadata.editorial_reason não vazio;
• filler_drop_spans revisados opcionais e campos de evidência visual.

Não forneça a score total; o validador adiciona as seis dimensões:

Dimensão	Máximo
hook	20
completeness	20
audience_value	20
emotion_tension	15
quotability	15
pace_editability	10

Prefira um pensamento completo e independentemente compreensível a um fragmento mais curto. Mantenha uma pergunta de entrevistador dependente, premissa, suporte de afirmação, reversão ou desfecho quando for necessário. Os limites devem cair em palavras e pensamentos inteiros.

Valide o arquivo criado:

$CandidateDir = Join-Path $ShortsWork "preview\text_visual"
python "$SkillRoot\scripts\candidates.py" `
  --out $CandidateDir `
  --candidates "$CandidateDir\candidate-input.json" `
  --transcript "$ShortsWork\transcript.json" `
  --project-root $ProjectRoot

Isso escreve os arquivos de preview de compatibilidade, work/shorts/candidates.json durável, e review/06-shorts/candidates.{html,summary.md}.

Modos de Revisão

A seleção de candidatos e o modo de entrega são um único portão vinculado por hash. A entrega é exatamente horizontal_only ou horizontal_and_vertical.

Abra a página interativa vinculada no modo humano:

python "$SkillRoot\scripts\interaction.py" candidate-open --out $ShortsWork --review-out $ShortsReview

O comando imprime uma página autoritativa com escopo de ID de revisão. O recibo vincula essa página, seu JSON de candidato, transcrição, mídia fonte, pergunta fixa e cada quadro extraído por SHA-256. candidates.html é apenas um alias de conveniência não autoritativo para a página mais recente. Abra o caminho autoritativo impresso com o comando nativo do SO atual:

# Windows PowerShell
Start-Process (Resolve-Path -LiteralPath "<printed-authoritative-page>")
# macOS
open "<printed-authoritative-page>"
# Linux
xdg-open "<printed-authoritative-page>"
# Agente: Apresente a página autoritativa e PARE.

Se a abertura falhar, tente novamente o comando nativo e relate a falha se ainda não abrir. Não continue após apresentá-la. A página começa com todas as caixas de seleção de candidatos e ambas as escolhas de entrega inicialmente não selecionadas. O usuário deve selecionar de 1 a 5 candidatos e um modo de entrega. A página vinculada nunca seleciona candidatos silenciosamente.

Para aprovação, copie este resumo estruturado gerado pela página exatamente como está em candidate-answer:

Revisão de candidatos a short
Revisão: <review-id>
Candidatos: text_visual/cand-001, text_visual/cand-002
Entrega: horizontal_and_vertical

Para revisão, copie este resumo estruturado gerado pela página exatamente como está:

Revisão de candidatos a short
Revisão: <review-id>
Decisão: revisar
Alterações: <alterações solicitadas não vazias>

Registre a resposta posterior sem reescrevê-la:

python "$SkillRoot\scripts\interaction.py" candidate-answer `
  --out $ShortsWork --response-file "<verbatim-summary-file>"

Quando o usuário delegar decisões explicitamente:

python "$SkillRoot\scripts\interaction.py" candidate-open `
  --out $ShortsWork --review-out $ShortsReview --decision-mode agent `
  --delegation-note "Usuário delegou seleção de shorts e aprovação vertical."

python "$SkillRoot\scripts\interaction.py" candidate-agent-approve `
  --out $ShortsWork `
  --candidates "text_visual/cand-001" `
  --delivery horizontal_and_vertical `
  --rationale "O intervalo selecionado possui um gancho autocontido, explicação e desfecho."

O Agente abre e inspeciona a mesma página autoritativa, usa referências explícitas de candidatos, um modo de entrega explícito e uma justificativa não vazia. Nunca escreve uma resposta humana falsa ou user_response. Os modos Humano e Agente são mutuamente exclusivos; comandos de resposta humana falham no modo Agente e comandos de aprovação do Agente falham no modo humano. A verificação do recibo revalida a revisão, página e hashes de mídia. Artefatos de fonte, candidato, transcrição, página, pergunta, quadro ou candidato aprovado regenerados invalidam a aprovação.

Plano Canônico

python "$SkillRoot\scripts\plan.py" `
  --out $ShortsWork --project-root $ProjectRoot

work/shorts/shorts-plan.json usa schema_version: 1 inteiro. Ele registra:

• target: derived, timebase: program e timeline_id;
• delivery_status: awaiting_main_render durante o planejamento;
• as vinculações de fonte de projeto e linha do tempo usadas para a revisão de candidatos;
• revisões exatas de depends_on / based_on da sequência principal ativa;
• modo de seleção, justificativa, modo de entrega e ID de revisão;
• IDs de shorts estáveis;
• program_range explícito e source_ranges mapeados;
• evidências de pontuação/editorial, quedas de preenchimento aprovadas e intervalos de manutenção no tempo do programa;
• caminhos da transcrição/relatório de trabalho e caminhos de entrega ../final/shorts/*.mp4.

A primeira execução é o fim da fase de planejamento. Pare aqui e continue as legendas solicitadas, cartões de conteúdo, movimento gráfico e outras operações restantes da sequência principal na ordem canônica. Não execute extract_shorts.py e não crie final.mp4 a partir desta skill.

Após o renderizador compartilhado verificar final/final-video.mp4, execute novamente o mesmo comando plan.py. Ele revalida a fonte aprovada do projeto e a linha do tempo, atualiza as revisões completas da operação ativa, adiciona a impressão digital da renderização principal verificada e define delivery_status: ready. Uma alteração na linha do tempo requer novos candidatos e aprovação; operações apenas de pixel, como cartões de conteúdo e legendas, não.

A qualificação permanece determinística: pontuação de pelo menos 70, completude de pelo menos 15, duração estimada da saída de 20 a 90 segundos, excerto exato válido, nenhuma sobreposição maior que 50% com um short de classificação mais alta e no máximo cinco saídas, a menos que configurado.

Apenas palavras de hesitação isoladas e semanticamente vazias com limites de palavra seguros podem ser aprovadas como quedas de preenchimento. Intervalos rejeitados/inseguros permanecem no plano com motivos. A remoção total não pode exceder 15% e nenhum intervalo de manutenção pode ser menor que 0,15 segundos.

Extração Horizontal

python "$SkillRoot\scripts\extract_shorts.py" `
  --video $FinalVideo --out $ShortsWork `
  --project-root $ProjectRoot

Antes da extração, o script verifica novamente a impressão digital da renderização principal, o status de renderização do projeto, a lista completa de operações principais atuais e revisões, o recibo do candidato, o hash do candidato aprovado e o vídeo fonte. Um plano awaiting_main_render é rejeitado. Cada intervalo de manutenção se torna sua própria entrada -ss/-t/-i buscada; o ffmpeg concatena essas entradas e realiza uma codificação H.264/AAC. Ele não decodifica o vídeo principal completo uma vez por intervalo de manutenção.

A palavra final da transcrição selecionada e o ponto final do corte de mídia são limites separados. A extração preserva pelo menos 0,25 segundos de áudio de liberação após o conteúdo selecionado e visa 0,30 segundos. --no-refine-boundaries desabilita apenas o ajuste de frase semântica; nunca desabilita o identificador de liberação obrigatório. Se a fonte terminar antes que o identificador necessário possa ser preservado, a extração falha em vez de marcar o short como verificado.

A transcrição relativa ao short exclui palavras descartadas, desloca palavras posteriores para um clock contínuo baseado em zero e retém evidências de programa/fonte de entrada. A mídia horizontal vai diretamente para final/shorts; o trabalho contém apenas sua transcrição e relatório.

Planejamento Vertical

A entrega vertical começa a partir da saída horizontal aprovada. Gere evidência visual densa a cada 1 segundo, ou 0,5 segundos quando o movimento exigir. Inspecione cada folha e crie um de:

• STATIC_CROP: um corte fixo estável 9:16.
• SCENE_CROP: cortes fixos limitados por cena, com LETTERBOX apenas para cenas que precisam de informações horizontais completas.
• LETTERBOX: primeiro plano nítido completo sobre um preenchimento desfocado/escurecido.
• REVIEW_REQUIRED: a evidência não pode suportar cortes fixos determinísticos; a renderização formal é bloqueada.

Cenas do apresentador devem manter a cabeça e o tronco estáveis e grandes. Slides, produtos, grupos e diagramas devem reter informações essenciais. Não reivindique rastreamento contínuo. As mudanças de corte pertencem aos limites da cena.

Cada segmento do plano cobre completamente a linha do tempo do short, tem uma estratégia, um quadro de referência, um modo de dimensionamento (largura, altura, preenchimento) e uma tag de confiança. Modos de redimensionamento (por exemplo, CoverScaleDownToFill) garantem que a saída não exceda o retângulo do segmento. Comprimentos de cena muito curtos podem exigir segmentação em escala de tempo mais fina.

Valide e escreva:

python "$SkillRoot\scripts\vertical\vertical_plan.py" `
  --project-root $ProjectRoot --short-id "short-001" `
  --out "$ShortsWork\short-001\vertical-agent"

Isso gera agent_vertical_plan.json com segmentos e um plano de curta-vertical processado. A validação adverte, mas permite, sobreposições de segmento e modos de redimensionamento que estouram. O plano de curta-vertical e a estratégia de segmento são imutáveis; eles são registrados no plano de curta-vertical autoritativo.

Revisão Vertical

Abra ou delegue:

python "$SkillRoot\scripts\vertical\vertical_interaction.py" preview-open `
  --project-root $ProjectRoot --short-id "short-001" `
  --vertical-plan "$ShortsWork\short-001\vertical-agent\agent_vertical_plan.json" `
  --out "$ShortsWork\short-001\vertical-agent" --review-out $ShortsReview

O modo humano abre uma página com um contato visual denso, resumo de preview, preview de vídeo de saída, resultado de sonda de mídia e visualizações de segmento com quadros de referência. O usuário seleciona aprovado ou revisão obrigatória. O modo agente aceita aprovação ou solicita revisão com um motivo não vazio. preview.mp4 e contact-sheet.jpg são omitidos para REVIEW_REQUIRED.

Extração Vertical

python "$SkillRoot\scripts\vertical\extract_vertical.py" `
  --project-root $ProjectRoot --short-id "short-001" `
  --horizontal "$ShortsWork\short-001\short-001-horizontal.mp4" `
  --vertical-plan "$ShortsWork\short-001\vertical-agent\agent_vertical_plan.json" `
  --out "$ShortsWork\short-001"

A extração usa filtros ffmpeg: crop, scale, pad, setpts, fps, drawtext, fade, colorchannelmixer. Em vez de recodificar toda a saída horizontal para cada segmento, ela encadeia filtros para produzir uma passagem de codificação. A sonda de mídia verifica a saída renderizada. As saídas vão para final/shorts/.

Notas de Implementação

• O planejamento e extração de cortes não são operações de sequência principal.
• O script extract_shorts.py valida recibo, hash de candidato e status de renderização.
• A extração vertical requer plano aprovado e usa filtros ffmpeg para cortar/redimensionar.
• Todas as saídas são H.264/AAC em MP4.

Comportamento do Agente

O Agente pode:

• Usar candidate-agent-approve para aprovação delegada.
• Usar vertical_interaction.py para preview e aprovação vertical.
• Não pode misturar modos humano e agente.
• Deve usar caminhos de arquivo literais para abrir páginas de revisão autoritativas.

Exemplo de Fluxo de Trabalho

1. Execute /video-understand.
2. Execute prepare_transcript.py --timeline.
3. Execute prepare_visual_context.py para gerar quadros de preview.
4. Crie candidate-input.json manualmente.
5. Execute candidates.py para validar.
6. Abra a página de revisão e selecione candidatos/entrega.
7. Execute interaction.py candidate-open e candidate-answer.
8. Execute plan.py (primeira execução).
9. Execute as operações restantes da sequência principal.
10. Verifique final/final-video.mp4.
11. Execute plan.py novamente (segunda execução).
12. Execute extract_shorts.py para obter saídas horizontais.
13. Para verticais: vertical_plan.py, vertical_interaction.py, extract_vertical.py.