vstoos/vlog-film

Vlog film

Convierte una carpeta con el metraje del usuario en un vídeo de YouTube acabado, y luego itera con las notas del usuario hasta que quede satisfecho. El pipeline se creó con "Adiós Yaris" (24 min, voz en ucraniano, iPhone + Sony dashcam); references/example_yaris.py es el archivo completo de proyecto de esa película, la mejor guía de cómo es una edición finalizada.

Antes de empezar

• Configuración. <skill>/config.json contiene las rutas de la máquina (ffmpeg, melt, Python con WhisperX, modelo de matrículas, carpeta de música, codificador, idioma del habla). Si falta o un script falla por una herramienta ausente, ejecuta python <skill>/setup/setup.py (solo comprueba) y muestra al usuario qué falta; con su aprobación ejecuta python <skill>/setup/setup.py --install. Ejecuta todos los scripts de abajo con el Python de config.json ("python"), porque ahí es donde están instalados WhisperX y torch.
• El usuario. Si existe <skill>/user.md, léelo: dice quién es el usuario, en qué idioma responder y sus preferencias habituales. Sin él: responde en el idioma del usuario, mantén las respuestas cortas, nombra los tiempos del vídeo como mm:ss para cualquier cosa que deba mirar.
• En los comandos siguientes, $K es <skill>/scripts y python es el Python configurado.

Estructura del proyecto

El metraje se queda donde lo puso el usuario; el mp4 final, la descripción de YouTube, la miniatura y los subtítulos van también allí, porque es donde el usuario busca. Los archivos de trabajo van en una carpeta de proyecto (por ejemplo C:/Data/<nombre>-video/):

<nombre>-video/
  project.py        rutas, EDL, HOOK, música, encuadre, make_stills()   (copia references/project_template.py)
  transcripts/      <clip>.json de transcribe_all.py
  film/             inserciones renderizadas, <clip>_blur.mov, <nombre>.mlt, <nombre>.mp4
  film_check/       hojas de contacto, wavs de prueba, fotogramas de verificación (borrador)
  edit_notes.md     las notas de revisión del usuario y lo que se hizo con cada una
  subs/, thumbnail/, route/

Flujo de trabajo

1. Inventario

1. python $K/scan_meta.py <metraje> film_check/meta.json: hora, duración, GPS de cada archivo. Ordenados por hora, este es el orden de la historia.
2. Mira antes de decidir: python $K/contact_sheet.py <salida.png> 6 <clips...> para clips, una hoja en mosaico para fotos; visualiza las imágenes tú mismo. Anota clips verticales (rotación -90/90), clips que muestran matrículas, archivos de dashcam, grabaciones de pantalla. Eventos de Tesla dashcam / Sentry de las fechas del viaje: references/teslacam.md (encontrar el incidente, color mediante teslacam_grade.py).
3. python $K/transcribe_all.py <metraje> transcripts: transcripción con tiempos por palabra de WhisperX de cada clip hablado (reanudable, idioma desde configuración). Léelos todos; son la materia prima de la historia.

2. Historia y EDL

Propón al usuario la estructura en unas pocas líneas antes de construir: el teaser, las partes, qué fotos, mapas o imágenes fijas ilustran cada charla. Forma típica:

• Teaser (HOOK): 4-6 frases cortas y contundentes de todo el viaje, cada una un pensamiento completo.
• Cartel de título sobre metraje de carretera, luego bloques de charla separados por inserciones de carretera de 4-10 s con música.
• Inserciones donde la charla menciona algo: el recibo cuando se menciona el combustible, el puesto de inspección cuando se habla de la inspección, un mapa de ruta al inicio de cada tramo.
• Imágenes sobre la voz (b-roll, capturas de pantalla del móvil, subtítulos mientras el hablante sigue hablando): intégralas en el clip hablado con burn_in.py, antes de filmkit (muestra un clip hablado solo mientras habla). Una imagen vertical (captura de pantalla, clip vertical, foto vertical) se coloca a toda la altura del fotograma en el lado libre de la cara del hablante, encontrada mediante detección facial, para que la cara permanezca visible; el reloj y los botones del teléfono llenan la parte superior e inferior de todas formas. Una imagen apaisada cubre el fotograma.
• Las inserciones de carretera deben mostrar lo que la historia necesita en ese momento (la salida hacia la gasolinera antes de "nos paramos", el parking del aeropuerto antes de la escena en el aeropuerto), no solo cualquier autovía: mira una hoja de contacto del clip de carretera alrededor del momento adecuado.
• Tarjeta final: 20 s sobre metraje de carretera, texto arriba, el centro libre para los mosaicos finales de YouTube; un enlace de referencia aquí si el usuario tiene uno.

Escribe project.py desde references/project_template.py; los tipos de elemento EDL, subtítulos, claves de música y opciones por clip están documentados allí. Los rangos de charla vienen de los tiempos de la transcripción.

3. Construir y renderizar

python $K/blur_plates.py <metraje> <proyecto>/film [--faces] IMG_0089 ...   # matrículas; --faces: también personas
python $K/burn_in.py film/IMG_0089_blur.mov film/IMG_0089_over.mov spec.json   # imágenes sobre voz, si las hay
python $K/filmkit.py <proyecto>/project.py                        # renderiza inserciones, escribe film/<nombre>.mlt
python $K/render_final.py <proyecto>/film <nombre> <metraje>/<Nombre>_HLG.mp4   # largo: ejecutar en segundo plano

Antes de un trabajo pesado de GPU (render, WhisperX, doblaje) ejecuta nvidia-smi: los números de tarjeta cambian entre sesiones y difieren entre herramientas, y otros trabajos pueden ocupar una tarjeta (references/lessons.md, "GPUs y codificadores hardware"). filmkit.py --no-media solo reescribe el .mlt (segundos). El render imprime sonoridad, duración, etiquetas de códec/HDR y un recuento de fotogramas verdes: espera aproximadamente -14 LUFS, Main 10, arib-std-b67, bt2020, 0 fotogramas verdes.

4. Verificar antes de decir al usuario que está listo

Escucha con WhisperX en lugar de confiar en la EDL: para cada corte nuevo o modificado, recorta los mismos segundos del mp4 terminado y transcríbelos (python $K/transcribe_window.py <wav> <offset>). Las transcripciones de primera pasada a menudo se equivocan sobre dónde termina una frase, especialmente con números, por lo que los cortes hechos a partir de ellas cortan el final ("не 144, а 147" perdió "а 147"). También mide la sonoridad de las secciones vecinas (ffmpeg -ss A -t N -i film.mp4 -af ebur128 -f null -) y mira un fotograma de cada nueva inserción. Las otras trampas y sus soluciones: references/lessons.md.

5. Rondas de revisión

El usuario mira y envía notas con los tiempos del vídeo. Para cada nota:

1. python $K/timeline.py film/<nombre>.mlt 12:22 nombra el clip y el segundo de origen.
2. Verifica la fuente (transcribe una ventana, mide sonoridad, mira fotogramas). Dile al usuario lo que realmente hay, citando las palabras originales; su memoria a veces difiere de la grabación.
3. Cambia la EDL y regístralo en edit_notes.md (tiempo del vídeo, clip y segundos, lo que se dijo, cambio).

Mientras el usuario sigue viendo, recoge notas y no reconstruyas: una construcción al final ahorra renders largos. Cuando diga que construya, reconstruye una vez, verifica cada punto cambiado como en el paso 4, actualiza los capítulos.

6. Entregables

references/youtube.md: descripción con capítulos (timeline.py), miniatura (make_thumb.py), subtítulos (make_subs.py sobre el vídeo terminado, corregidos a mano, luego traducidos señal por señal, más los textos en pantalla traducidos como sus propias señales con onscreen_subs.py), doblaje automático de YouTube. El usuario puede ver los renders en un teléfono a través de python $K/media_server.py --port 8765 <metraje> <proyecto>/film (solo LAN/VPN; solo lectura; también en github.com/vstoos/media-server).

7. Pistas de audio dobladas

Para un idioma que el usuario quiere oír, no leer: references/dubbing.md. La voz es Higgs TTS 3 (por defecto desde el 06.11.2026) con la referencia guardada del usuario en ese idioma (C:/Data/voices, pasa -); cada descripción de vídeo con una pista Higgs acredita "Boson AI's Higgs Audio". Los subtítulos pasan por dub.py gen, dub_check.py detecta los fallos del modelo toma por toma, dub_regen.py reemplaza lo que falló, y dub.py mix construye la pista e imprime qué escuchar. Corrige la pronunciación en say.json. La voz en off para metraje silencioso (clips de dashcam) sigue la misma ruta en ucraniano, escritos como subtítulos. No des un doblaje por limpio solo con las comprobaciones: el oído del usuario es el último paso.

Privacidad

Matrículas: el usuario no difumina el tráfico normal (Polonia; el recuadro flotante estropea las tomas de carretera). Difumina una matrícula solo donde el clip muestre una posible infracción de ese conductor o un casi accidente, para que el vídeo no pueda alimentar una denuncia contra una persona; las inserciones de carretera van tal cual mediante CLIP_SRC en el proyecto. Difumina las caras del personal, transeúntes y niños (blur_plates.py --faces; revisa los fotogramas, los reflejos en la pintura del coche pueden engañarlo); empieza los mapas de ruta en un lugar público, nunca en casa del usuario; no pongas caras de otras personas (niños sobre todo) en las miniaturas a menos que se pida.

Archivos de referencia

• references/project_template.py: archivo de proyecto anotado para copiar; sintaxis EDL.
• references/example_yaris.py: el vídeo Yaris terminado, con todas las funciones en uso.
• references/lessons.md: HDR, audio, trampas de corte y encuadre, con las soluciones que funcionaron.
• references/teslacam.md: clips de Tesla dashcam / Sentry (HW3): encontrar el incidente en un evento guardado y la corrección de color (scripts/teslacam_grade.py).
• references/youtube.md: descripción, capítulos, miniatura, subtítulos, doblaje, pantalla final.
• references/dubbing.md: pistas de audio propias con la voz clonada del usuario y comprobaciones automáticas de fallos.
• references/example_make_route.py: mapa de ruta animado (teselas Sentinel-2 + carreteras OSRM) del vídeo Yaris; adapta sus constantes (límites, ciudades, pines, tramos) para un nuevo viaje.