morrimoz/revisión-de-clips-con-presentador

Revisión de clips con presentador

Convierte grabaciones de personas hablando a cámara en selecciones aprobadas sin que nadie tenga que revisarlas manualmente. El agente transcribe, alinea y sugiere. Una persona aprueba todo en una página. El agente ensambla exactamente lo que se aprobó.

La transcripción permanece en la máquina. Los videos fuente nunca se modifican.

Reglas estrictas

• Nunca modifiques, muevas o reexportes los videos fuente. Todo se basa en puntos de entrada/salida y archivos derivados.
• Nunca elimines el material grabado del usuario ni vacíes la Papelera. Si el disco está lleno, indícalo y deja que el usuario lo gestione.
• Trabaja desde una carpeta temporal. Solo las vistas previas, los pósters, la página de revisión y las selecciones van junto a los medios.
• No inventes texto. El texto de los clips proviene de la transcripción. Las correcciones opcionales de frases se almacenan en un mapa JSON pasado con --fix (ver references/term-corrections.example.json). No apliques el archivo de ejemplo.
• Verifica los hechos dichos en cámara (horas, números, "hace 10 minutos") con la grabación real antes de seleccionarlos.
• No incluyas miradas al monitor, golpes de micrófono, clics o ruidos de respiración en un segmento conservado. Vuelve a ejecutar la detección de mirada (paso 5) y escucha cada punto de edición después de cualquier re-edición, no solo en la primera selección. Silencia o corta el ruido, nunca la palabra adyacente.
• Las reposiciones y líneas regrabadas deben coincidir con el tono, nivel y ambiente de la toma principal (mismo micrófono, ganancia, distancia, ecualización y reducción de ruido). Marca una línea que sonará apagada o como si estuviera en una caja en lugar de incluirla.
• Usa guiones, no guiones largos, en todo lo que escribas para el usuario.
• Los límites de palabras son límites estrictos, incluso cuando una indicación pida cortes ajustados o recortes por mirada. Los clips reciben un pre-roll de 0.15 s y una cola de 0.25 s alrededor de los tiempos de palabra de Whisper (sus bordes de palabra suelen ser tempranos o tardíos), sujetos para que nunca se superpongan a una palabra vecina. Los recortes por pausa y mirada solo cortan dentro de los espacios entre palabras y mantienen al menos 0.1 s junto a cada palabra. Si una desviación de la mirada se superpone a una palabra hablada, conserva la palabra y márcala (away_words, borde rojo en el stringout), nunca la cortes. Usa build_review.py --gaze-trim para recortes de borde en lugar de escribir tu propio script de recorte. Los exact_spans establecidos manualmente también se empujan de vuelta a los bordes de palabra.

Configuración (una vez por máquina)

Ejecuta scripts/check_deps.sh. Necesita ffmpeg, ffprobe, python3 y un backend de Whisper. Swift es opcional para el paso de mirada. Pasos de instalación: references/setup.md.

Estructura de carpetas

TRABAJO/                      carpeta temporal, por ejemplo ./talk/
  tx/<toma>.wav|json|txt      audio mono a 16 kHz, JSON de Whisper con palabras, transcripción legible
  picks.json                  beats + candidatos (el agente edita esto)
  picks_resolved.json         spans precisos por palabra, texto, duraciones (generado)
  pose.json                   intervalos de desviación de mirada (opcional, macOS)
REVISION/                     junto a los medios, por ejemplo ./review/
  previews/<toma>.mp4          copias H.264 a 540p para la página
  posters/<beat>-<i>.jpg
  "<Título> - revisión de tomas.html"
  "<Título> - stringout de selecciones (540p).mp4"
SELECTS/                      selects.json, selects.csv, selects.edl, selects.mp4

Nombra el episodio según la pieza, por ejemplo lanzamiento-01. Mantén las claves de las tomas cortas (A, B, C) y mapea los nombres de archivo en picks.json.

Pasos

1. Inventario. ffprobe cada toma (duración, tamaño, fps, rotación). El metraje de teléfono suele ser de frecuencia de cuadros variable y en vertical. Las vistas previas y los renders lo normalizan. Pregunta qué archivos son las exportaciones etalonadas para cortar y cuáles son los originales de cámara para ignorar.
2. Transcripción. python3 scripts/transcribe.py --out TRABAJO/tx TOMA.... Usa el intérprete que check_deps.sh informó si el paquete Whisper no está en el python3 predeterminado. Si los archivos todavía se están exportando, usa --watch CARPETA --expect N en segundo plano: espera hasta que cada archivo haya dejado de crecer durante 30 s. Modelo preferido en Apple Silicon: mlx-community/whisper-large-v3-turbo, marcas de tiempo por palabra, con condition_on_previous_text desactivado. Establece --lang cuando el audio no esté en inglés.
3. Borrador de las selecciones.
   • Modo (a), tomas de un guion: escribe TRABAJO/script.txt con una línea o punto de conversación por línea (id | nombre | texto si quieres ids). Ejecuta python3 scripts/segment.py takes --tx TRABAJO/tx --script TRABAJO/script.txt --out TRABAJO/picks.json A=toma-a B=toma-b .... Encuentra cada intento de cada línea en cada toma (coincidencia difusa por ventana de palabras, por lo que los reinicios aparecen como candidatos separados) y marca previamente el más fluido.
   • Modo (b), un video largo: python3 scripts/segment.py single --tx TRABAJO/tx --out TRABAJO/picks.json A=toma-larga corta en pausas de 1.2 s o más y al final de las frases, en clips de 4-40 s.
   • Luego lee las transcripciones .txt tú mismo. Corrige los puntos de entrada/salida, añade cut: [[a,b]] para reinicios y fallos, fusiona o divide beats, y escribe un why real por candidato (limpio, reinicio, palabra incorrecta, coincide con la grabación de pantalla). Prefiere la toma que se filmó con la grabación de pantalla coincidente. La puntuación automática solo rompe empates.
4. Construir la página. python3 scripts/build_review.py --work TRABAJO --media FUENTE --out REVISION --title "lanzamiento-01" --stringout. Los spans se dividen en espacios entre palabras de más de 0.6 s y se ajustan con silencedetect -35dB / 0.35s. Añade keep_pauses: true en un candidato para omitir eso. Indicadores de relleno: --pre 0.15 --tail 0.25 --guard 0.1. Pasa --fix ruta/a/correcciones.json solo cuando tengas un mapa de frases real. Abre el HTML en el navegador. Los videos se cargan al hacer clic, por lo que la página se abre rápido.
5. Opcional, macOS: mirada. python3 scripts/gaze.py --work TRABAJO --review REVISION, luego vuelve a ejecutar el paso 4 con --stringout --gaze-trim. Los fotogramas con desviación de mirada obtienen un borde rojo en el stringout. Cúbrelos después con metraje de pantalla y conserva el audio.
6. Revisión humana. Dile al usuario qué hacer: Reproducir, Usar/Saltar, notas, luego "Guardar decisiones (JSON)". Descarga `-decisiones.json". "Copiar como texto" es la alternativa. Las tarjetas no tocadas mantienen la sugerencia.
7. Aplicar notas. Lee el JSON de decisiones. Convierte cada nota en ediciones de picks.json: cut, in/out, audio_only: true, grade: "eq=gamma=1.28:brightness=0.03", optional: true. Haz primero una copia de seguridad (cp picks.json picks.before-notes.json). Vuelve a ejecutar el paso 4 y resume cada nota y lo que hiciste.
8. Ensamblar. python3 scripts/assemble.py --work TRABAJO --media FUENTE --decisions /ruta/a/<slug>-decisiones.json --out SELECTS --render. Obtienes un selects.mp4 a resolución completa y con precisión de fotograma, un selects.edl CMX3600 (Premiere, Resolve, Final Cut mediante importación), selects.csv y selects.json con rangos de desviación de mirada y notas.
9. Verificar. Escucha cada punto de edición (sin primera o última sílaba cortada, sin mirada, sin ruido). ffprobe la duración del render contra la suma en selects.json, y haz una hoja de contactos: ffmpeg -i selects.mp4 -vf "fps=1/6,scale=180:-1,tile=10x3" -frames:v 1 sheet.jpg. Mírala, luego informa la duración, qué cambió y qué necesita al usuario.

Formato de picks.json

{"episode":"lanzamiento-01","mode":"takes","takes":{"A":"toma-a","B":"toma-b"},
 "beats":[{"id":"01a","name":"Gancho","script":"...","cands":[
   {"take":"B","in":0.82,"out":21.2,"pick":true,"why":"Limpio, coincide con la pantalla.","cut":[[51.4,53.82]],
    "note":"","audio_only":false,"grade":null,"optional":false,"signals":{"dur":20.1,"wpm":162,"fillers":0,"repeats":0}}]}]}

Consejos

• Verifica cualquier tiempo de palabra con el JSON de transcripción. Un volcado de palabra@inicio-fin alrededor de una nota es la forma más rápida de colocar un corte.
• Si ffmpeg no tiene drawtext, marca los fotogramas con drawbox o hue, no con texto.
• Renders grandes: verifica el espacio disponible en disco primero. Las tomas en 4K se acumulan rápido.