video-to-shorts

De Video a Cortos (Video To Shorts)

Dependencias

/video-understand es un requisito previo. Ejecútalo primero para que los cortos usen la transcripción fuente validada y la línea de tiempo canónica. Antes de comenzar, verifica que esté instalado. Si no lo está, advierte al usuario que falta este requisito previo y detente antes de procesar los medios.

Requiere ffmpeg/ffprobe en PATH y Python con Pillow. Verifícalos antes de procesar los medios.

Alcance

Esta habilidad tiene dos fases de proyecto:

1. Planificar antes de renderizar: mapea la transcripción entendida al tiempo de programa, autoriza y aprueba candidatos, y escribe work/shorts/shorts-plan.json. Esta fase no escribe ningún video final.
2. Finalizar después de renderizar: después de que cada edición seleccionada de la secuencia principal esté aprobada y la entrega principal compartida esté verificada, vuelve a ejecutar plan.py para vincular los mismos rangos aprobados a esa entrega, luego extrae las salidas horizontales y verticales opcionales.

Es responsable del juicio de candidatos a cortos, la calificación determinista, la extracción horizontal, las transcripciones relativas a cortos y la entrega vertical determinista opcional. No transcribe en modo proyecto, no cambia la secuencia principal, no agrega subtítulos/gráficos, no etiqueta, no publica ni realiza seguimiento continuo del sujeto.

Los Cortos entregados son derivados de final/final-video.mp4, pero la planificación de candidatos precede a ese archivo. Registra la operación en el DAG del proyecto, pero nunca la agregues a sequences.main.operations; la entrega principal y su comparación original vs final permanecen sin cambios.

Entradas del Proyecto

• work/project.json
• la fuente del proyecto registrada por project.source.path
• work/understand/transcript.json en tiempo fuente
• work/timeline.json
• las revisiones activas de la operación principal en cada fase

La planificación no requiere final/final-video.mp4. La finalización y extracción requieren ese render exacto del proyecto con render.status: verified.

prepare_transcript.py --timeline llama a projectlib.map_transcript_to_timeline compartido. Los tiempos de candidato/extracción son, por lo tanto, segundos de programa en el video final real. Las palabras eliminadas por la edición principal no están disponibles para los cortos. Cada palabra conservada mantiene sus source_range, program_range y clip_id.

Los metadatos de la transcripción del proyecto vinculan la fuente del proyecto, la transcripción fuente y la línea de tiempo por ruta absoluta, tamaño, tiempo de modificación y SHA-256. Los fotogramas de revisión de candidatos mapean sus marcas de tiempo de programa de vuelta a través de timeline.json al video fuente. La validación de candidatos rechaza un enlace cambiado.

Diseño de Salida

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/                 # fotogramas/hojas/medios intermedios desechables

review/06-shorts/
|-- candidates-<review-id>.html              # página autoritativa inmutable
|-- candidates-<review-id>-question.md
|-- assets/candidates-<review-id>/            # fotogramas inm. inicio/medio/fin
|-- candidates.html                           # alias no autoritativo más reciente
|-- 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 autoritativa inmutable
|-- <short-id>-vertical-review-<review-id>-question.md
|-- <short-id>-vertical-review.html             # alias no autoritativo más reciente
|-- <short-id>-vertical-review-assets/
|   `-- <review-id>/                             # evidencia autoritativa inmutable
|       |-- 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          # solo cuando está seleccionado y aprobado

Transcripción del Programa

Ejecutar desde la raíz del repositorio:

$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

El modo de línea de tiempo del proyecto requiere la transcripción canónica suministrada. El modo independiente puede omitir --timeline; mantiene el tiempo relativo a la entrada y puede usar la alternativa temporal video-understand/scripts/transcribe.py. No se descubre automáticamente ninguna transcripción.

Creación de Candidatos

Generar contexto visual del video largo en caché, inspeccionar cada hoja necesaria para una decisión y redactar manualmente el JSON de candidatos. El código determinista valida el juicio editorial; no inventa candidatos ni puntuaciones.

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

La entrada de candidatos sigue siendo shorts-candidates.v2 para compatibilidad. Establece selection.evidence_mode y cada evidence_mode del candidato en text_visual. Cada candidato requiere:

• candidate_id, título y tipo de escena estables;
• start_time/end_time completos en tiempo de programa;
• transcript_excerpt exactamente igual a las palabras de transcripción superpuestas, no segmentos superpuestos completos;
• las seis entradas de puntuación y razones no vacías;
• metadata.editorial_reason no vacío;
• filler_drop_spans opcional revisado y campos de evidencia visual.

No proporciones la score total; el validador agrega las seis dimensiones:

Dimensión	Máximo
hook	20
completeness	20
audience_value	20
emotion_tension	15
quotability	15
pace_editability	10

Prefiere un pensamiento completo e independientemente comprensible sobre un fragmento más corto. Mantén una pregunta de entrevistador dependiente, premisa, apoyo de afirmación, reversión o resultado cuando sea necesario. Los límites deben recaer en palabras y pensamientos completos.

Validar el archivo creado:

$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

Esto escribe los archivos de vista previa de compatibilidad, work/shorts/candidates.json duradero y review/06-shorts/candidates.{html,summary.md}.

Modos de Revisión

La selección de candidatos y el modo de entrega son una puerta enlazada por hash. La entrega es exactamente horizontal_only o horizontal_and_vertical.

Abrir la página interactiva enlazada en modo humano:

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

El comando imprime una página autoritativa con alcance de ID de revisión. El recibo vincula esa página, su JSON de candidatos, transcripción, medio fuente, pregunta fija y cada fotograma extraído por SHA-256. candidates.html es solo un alias de conveniencia no autoritativo para la última página. Abre la ruta autoritativa impresa con el comando nativo del sistema operativo actual:

# Windows PowerShell
Start-Process (Resolve-Path -LiteralPath "<printed-authoritative-page>")
# macOS
open "<printed-authoritative-page>"
# Linux
xdg-open "<printed-authoritative-page>"
# Agente: Presentar la página autoritativa y DETENERSE.

Si la apertura falla, reintentar el comando nativo e informar del fallo si aún no se abre. No continuar después de presentarla. La página comienza con todas las casillas de verificación de candidatos y ambas opciones de entrega inicialmente sin seleccionar. El usuario debe seleccionar de 1 a 5 candidatos y un modo de entrega. La página enlazada nunca selecciona candidatos silenciosamente.

Para aprobación, copiar este resumen estructurado exacto generado por la página sin cambios en candidate-answer:

Revisión de candidatos a cortos
Revisión: <review-id>
Candidatos: text_visual/cand-001, text_visual/cand-002
Entrega: horizontal_and_vertical

Para revisión, copiar este resumen estructurado exacto generado por la página sin cambios:

Revisión de candidatos a cortos
Revisión: <review-id>
Decisión: revise
Cambios: <cambios solicitados no vacíos>

Registrar la respuesta posterior sin reescribirla:

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

Cuando el usuario delega explícitamente las decisiones:

python "$SkillRoot\scripts\interaction.py" candidate-open `
  --out $ShortsWork --review-out $ShortsReview --decision-mode agent `
  --delegation-note "Usuario delegó selección de cortos y aprobación vertical."

python "$SkillRoot\scripts\interaction.py" candidate-agent-approve `
  --out $ShortsWork `
  --candidates "text_visual/cand-001" `
  --delivery horizontal_and_vertical `
  --rationale "El rango seleccionado tiene un gancho, explicación y resultado autónomos."

El Agente abre e inspecciona la misma página autoritativa, utiliza referencias explícitas de candidatos, un modo de entrega explícito y una justificación no vacía. Nunca escribe una respuesta humana falsa o user_response. Los modos Humano y Agente son mutuamente excluyentes; los comandos de respuesta humana fallan en modo Agente y los comandos de aprobación del Agente fallan en modo humano. La verificación del recibo vuelve a verificar la revisión, la página y los hashes de los medios. Los artefactos regenerados de fuente, candidato, transcripción, página, pregunta, fotograma o candidato aprobado invalidan la aprobación.

Plan Canónico

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

work/shorts/shorts-plan.json usa schema_version: 1 entero. Registra:

• target: derived, timebase: program y timeline_id;
• delivery_status: awaiting_main_render durante la planificación;
• los enlaces de fuente y línea de tiempo del proyecto utilizados para la revisión de candidatos;
• revisiones exactas de depends_on / based_on de la secuencia principal activa;
• modo de selección, justificación, modo de entrega e ID de revisión;
• IDs de cortos estables;
• program_range explícito y source_ranges mapeados;
• evidencia de puntuación/editorial, caídas de relleno aprobadas y rangos conservados en tiempo de programa;
• rutas de transcripción/informe de trabajo y rutas de entrega ../final/shorts/*.mp4.

La primera ejecución es el final de la fase de planificación. Detente aquí y continúa con los subtítulos, tarjetas de contenido, movimiento gráfico y otras operaciones restantes de la secuencia principal solicitadas en orden canónico. No ejecutes extract_shorts.py y no crees final.mp4 a partir de esta habilidad.

Después de que el renderizador compartido verifique final/final-video.mp4, vuelve a ejecutar el mismo comando plan.py. Revalida la fuente y línea de tiempo del proyecto aprobadas, actualiza las revisiones completas de la operación activa, agrega la huella digital del render principal verificado y establece delivery_status: ready. Un cambio en la línea de tiempo requiere nuevos candidatos y aprobación; las operaciones solo de píxeles, como tarjetas de contenido y subtítulos, no.

La calificación sigue siendo determinista: puntuación al menos 70, integridad al menos 15, duración estimada de salida 20-90 segundos, extracto exacto válido, sin superposición mayor al 50% con un corto de mayor rango y como máximo cinco salidas a menos que se configure.

Solo las palabras de vacilación aisladas y semánticamente vacías con límites de palabra seguros pueden aprobarse como caídas de relleno. Los tramos rechazados/inseguros permanecen en el plan con razones. La eliminación total no puede exceder el 15% y ningún tramo conservado puede ser más corto de 0,15 segundos.

Extracción Horizontal

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

Antes de la extracción, el script vuelve a verificar la huella digital del render principal, el estado del render del proyecto, la lista completa de operaciones principales actuales y sus revisiones, el recibo del candidato, el hash del candidato aprobado y el video fuente. Se rechaza un plan con awaiting_main_render. Cada rango conservado se convierte en su propia entrada -ss/-t/-i buscada; ffmpeg concatena esas entradas y realiza una codificación H.264/AAC. No decodifica el video principal completo una vez por rango conservado.

La palabra final seleccionada de la transcripción y el punto final del corte de medios son límites separados. La extracción conserva al menos 0,25 segundos de audio de liberación después del contenido seleccionado y apunta a 0,30 segundos. --no-refine-boundaries deshabilita solo el encaje de frases semánticas; nunca deshabilita el identificador de liberación obligatorio. Si la fuente termina antes de que se pueda conservar el identificador requerido, la extracción falla en lugar de marcar el corto como verificado.

La transcripción relativa al corto excluye las palabras eliminadas, desplaza las palabras posteriores a un reloj continuo basado en cero y conserva la evidencia de programa/fuente de entrada. Los medios horizontales van directamente a final/shorts; el trabajo contiene solo su transcripción e informe.

Planificación Vertical

La entrega vertical comienza desde la salida horizontal aprobada. Genera evidencia visual densa a 1 segundo, o 0,5 segundos cuando el movimiento lo requiere. Inspecciona cada hoja y crea uno de:

• STATIC_CROP: un recorte fijo estable 9:16.
• SCENE_CROP: recortes fijos delimitados por escena, con LETTERBOX solo para escenas que necesitan información horizontal completa.
• LETTERBOX: primer plano nítido completo sobre un relleno borroso/oscurecido.
• REVIEW_REQUIRED: la evidencia no puede respaldar recortes fijos deterministas; el render formal está bloqueado.

Las escenas del presentador deben mantener la cabeza y el torso estables y grandes. Las diapositivas, productos, grupos y diagramas deben retener información esencial. No afirmes seguimiento continuo. Los cambios de recorte pertenecen a los límites de la escena.

Cada segmento del plan cubre completamente la línea de tiempo del corto, tiene una estrategia...