YT-Frame-Extractor: fotogramas de vídeo de YouTube, sin los oscuros

TL;DR

• Es un único archivo Python, extractor.py, que lee una lista de enlaces de YouTube en videos.txt, descarga cada vídeo y saca un número definido de fotogramas como PNG en carpetas por vídeo, y al final comprime todo en ZIP.
• Dos decisiones hacen la salida utilizable como dataset: los fotogramas se toman a lo largo de todo el vídeo (el primer y el último décimo quedan fuera) y un fotograma se rechaza cuando la luminancia media baja de 20% de 255, así que un fotograma negro no entra.
• Los valores por defecto están fijos en main(): 200 fotogramas por vídeo, raíz de salida frames y videos.txt en el directorio de trabajo.
• El README del repositorio es solo un título — todo lo de abajo sale de leer extractor.py, así que trátalo como descripción del código, no de documentación.

Qué es y para quién

YT-Frame-Extractor es el tipo de script que alguien escribe una vez y usa siempre: una forma de armar un dataset de imagen desde vídeo sin ver el vídeo con el dedo en la tecla de captura. Depende de pytube, OpenCV y NumPy, y es lo bastante pequeño para leerlo de una sentada.

Es para quien tiene una carpeta de enlaces de YouTube y quiere fotogramas para una LoRA o un checkpoint, y para quien ya probó un extractor y recibió trescientos fotogramas casi idénticos de una cartela de título.

Qué hace el código

• Lee los enlaces de videos.txt, uno por línea.
• Descarga cada vídeo con pytube, conservando el MP4 progresivo de mayor resolución disponible, con cinco intentos y cinco segundos de espera entre ellos.
• Divide el vídeo en segmentos iguales y sortea un fotograma aleatorio por segmento, así la cobertura se reparte por todo el metraje en vez de concentrarse al inicio.
• Descarta el primer y el último 10% de los fotogramas, que es lo que deja la apertura, el logo y los créditos finales fuera del dataset.
• Comprueba la luminancia media en escala de grises y sortea de nuevo cuando el fotograma es más oscuro que 20% de 255 — la respuesta concreta a "la mitad de mi dataset son fotogramas negros".
• Escribe frame_{i}.png con compresión PNG nivel 0, un hilo por fotograma, y comprime el directorio frames en un ZIP al final.

Cómo usarlo

git clone https://github.com/artificialguybr/YT-Frame-Extractor.git
cd YT-Frame-Extractor
pip install pytube opencv-python numpy

Después crea videos.txt con un enlace por línea y ejecuta el script:

python extractor.py

La salida va a frames/<nombre-del-vídeo>/frame_0.png en adelante, y al final se crea un ZIP de todo el directorio frames. num_frames y output_root se definen dentro de main() — 200 y frames — así que cambiar la cantidad significa editar el archivo, no pasar un argumento.

Qué esperar, con honestidad

No hay interfaz de línea de comandos, archivo de configuración ni reporte de progreso más allá de un print por vídeo. El número de intentos y el tiempo de espera viven en el código, y un vídeo que falla los cinco intentos se salta con un mensaje en vez de tumbar la ejecución.

Como la numeración sigue el índice del segmento, frame_0.png no es el primer fotograma del vídeo: es el sorteado en el primer segmento. Está bien para un dataset de entrenamiento y confunde para cualquier otra cosa.

El filtro de luminancia es un valor medio único, así que una escena nocturna interesante se rechaza y un fotograma claro e inútil puede pasar. Reduce lo peor del problema y no lo resuelve.

Cuándo usarlo, cuándo no

Úsalo cuando necesites cientos de fotogramas de un vídeo largo para un dataset de LoRA, cuando el vídeo tiene apertura y créditos que no quieres, o cuando quieras un script lo bastante pequeño para adaptar tu propia regla de filtro.

No lo uses cuando necesitas un instante concreto del vídeo — los fotogramas son aleatorios dentro del segmento, así que el segundo exacto no se recupera por índice. Y no lo uses si pytube se rompió contra un cambio de YouTube: esa dependencia queda fuera del script, y el código de 2024 refleja la API de esa época.

Sources

1. YT-Frame-Extractor — repositorio — el README del repositorio es solo un título, así que este artículo lee extractor.py para comportamiento, valores por defecto y dependencias.
2. extractor.py — reintentos de descarga, sorteo por segmento, umbral de luminancia, salida PNG y ZIP.

Página del proyecto: YT-Frame-Extractor

Para qué hacer con los fotogramas después, mira creación automática de dataset para entrenar LoRA y montar un dataset de entrenamiento.

FAQ

¿Necesita clave de API de YouTube? No. Descarga el vídeo con pytube, con cinco intentos y cinco segundos de espera entre ellos.

¿Por qué se descartan algunos fotogramas? El script sortea de nuevo cuando la luminancia media en grises baja de 20% de 255, lo que deja fotogramas negros fuera del dataset.

¿Qué parte del vídeo se usa? Los segmentos cubren todo el metraje, pero el primer y el último 10% quedan fuera para dejar apertura y créditos lejos.

¿Puedo elegir cuántos fotogramas? Solo en el código: num_frames vale 200 por defecto y se define dentro de main(), porque el script no tiene opciones de línea de comandos.