YT-Frame-Extractor: frames de vídeo do YouTube, sem os escuros

TL;DR

• É um único arquivo Python, extractor.py, que lê uma lista de links do YouTube em videos.txt, baixa cada vídeo e extrai um número definido de frames como PNG em pastas por vídeo, e no final compacta tudo em ZIP.
• Duas escolhas tornam a saída utilizável como dataset: os frames são tirados ao longo do vídeo inteiro (o primeiro e o último décimo ficam de fora) e um frame é recusado quando a luminância média fica abaixo de 20% de 255, então frame preto não entra no conjunto.
• Os padrões estão fixos em main(): 200 frames por vídeo, raiz de saída frames e videos.txt no diretório de trabalho.
• O README do repositório é só um título — tudo abaixo vem da leitura do extractor.py, então trate como descrição do código, não de documentação.

O que é e para quem

O YT-Frame-Extractor é o tipo de script que a pessoa escreve uma vez e usa sempre: um jeito de montar dataset de imagem a partir de vídeo sem assistir ao vídeo com o dedo na tecla de print. Depende de pytube, OpenCV e NumPy, e é pequeno o suficiente para ler numa sentada.

É para quem tem uma pasta de link do YouTube e quer frames para uma LoRA ou um checkpoint, e para quem já tentou um extrator de frame e recebeu trezentos frames quase idênticos de uma cartela de título.

O que o código faz

• Lê os links de videos.txt, um por linha.
• Baixa cada vídeo com pytube, mantendo o MP4 progressivo de maior resolução disponível, com cinco tentativas e cinco segundos de espera entre elas.
• Divide o vídeo em segmentos iguais e sorteia um frame aleatório por segmento, então a cobertura se espalha pelo tempo todo em vez de se concentrar no começo.
• Descarta o primeiro e o último 10% dos frames, que é o que deixa abertura, logo e crédito final fora do dataset.
• Checa a luminância média em escala de cinza e sorteia de novo quando o frame é mais escuro que 20% de 255 — a resposta concreta para "metade do meu dataset é frame preto".
• Escreve frame_{i}.png com compressão PNG nível 0, uma thread por frame, e compacta o diretório frames no final.

Como usar

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

Depois crie o videos.txt com um link por linha e rode o script:

python extractor.py

A saída vai para frames/<nome-do-video>/frame_0.png em diante, e um ZIP de todo o diretório frames é criado no final. num_frames e output_root são definidos dentro de main() — 200 e frames — então mudar a quantidade significa editar o arquivo, não passar argumento.

O que esperar, com honestidade

Não existe interface de linha de comando, arquivo de configuração nem relatório de progresso além de um print por vídeo. O número de tentativas e o tempo de espera ficam no código, e um vídeo que falha nas cinco tentativas é pulado com mensagem em vez de derrubar a execução.

Como a numeração segue o índice do segmento, frame_0.png não é o primeiro frame do vídeo — é o frame sorteado no primeiro segmento. Isso está ótimo para dataset de treino e confuso para qualquer outra coisa.

O filtro de luminância é um valor médio único, então cena noturna interessante é recusada e frame claro e inútil pode passar. Ele reduz o pior do problema, e não resolve.

Quando usar, quando não usar

Use quando você precisa de centenas de frames de um vídeo longo para dataset de LoRA, quando o vídeo tem abertura e crédito que você não quer, ou quando você quer um script pequeno o suficiente para adaptar a sua própria regra de filtro.

Não use quando você precisa de um instante específico do vídeo — os frames são aleatórios dentro do segmento, então o segundo exato não é recuperável por índice. E não use se pytube quebrou contra uma mudança do YouTube: essa dependência fica fora do script, e o código de 2024 reflete a API daquela época.

Sources

1. YT-Frame-Extractor — repositório — o README do repositório tem só um título, então este artigo lê o extractor.py direto para comportamento, padrões e dependências.
2. extractor.py — retry de download, sorteio por segmento, limiar de luminância, saída PNG e ZIP.

Página do projeto: YT-Frame-Extractor

Para o que fazer com os frames depois, veja criação automática de dataset para treino de LoRA e montar um dataset de treino.

FAQ

Precisa de chave de API do YouTube? Não. Ele baixa o vídeo com pytube, com cinco tentativas e cinco segundos de espera entre elas.

Por que alguns frames são recusados? O script sorteia de novo quando a luminância média em escala de cinza fica abaixo de 20% de 255, o que deixa frame preto fora do dataset.

Que parte do vídeo é usada? Os segmentos cobrem o vídeo todo, mas o primeiro e o último 10% ficam de fora para deixar abertura e crédito longe.

Posso escolher a quantidade de frames? Só no código: num_frames vale 200 por padrão e é definido dentro de main(), porque o script não tem opção de linha de comando.