O que video2ppt faz?
Extrai quadros de slides de vídeos e os transforma em PPTX (uma imagem por slide) ou PDF. Três capacidades podem ser usadas separadamente ou em um único pipeline:
| Script | Função | Cenário típico |
|---|---|---|
scripts/video2ppt.py | Pipeline único: vídeo → quadros → PPTX/PDF | O usuário só quer o PPT/PDF final (priorizar este) |
scripts/video_to_frames.py | Extrai quadros inteligentes do vídeo, gerando sequência de imagens | O usuário precisa de capturas de tela, ou quer selecionar manualmente antes de compor |
scripts/images_to_pptx.py | Pasta de imagens → PPTX | Já tem capturas/imagens e quer gerar uma apresentação |
scripts/images_to_pdf.py | Pasta de imagens → PDF | Já tem capturas/imagens e quer gerar um PDF |
Todos os comandos devem ser executados no diretório raiz desta Skill (diretório que contém este arquivo); os scripts também escrevem logs no stderr e podem usar --json para ler um resumo legível por máquina no stdout.
0. Preparação do ambiente (primeiro uso)
python scripts/check_env.py
- Código de saída 0 indica dependências completas; código 3 indica dependências obrigatórias ausentes.
- Para instalar dependências faltantes:
python -m pip install -r scripts/requirements.txt - Obrigatórias:
opencv-python,numpy,python-pptx,Pillow; opcionais avançadas:scikit-image(desduplicação SSIM),img2pdf(fusão de PDF em streaming; fallback automático para Pillow quando ausente). - Os scripts não leem nenhuma API Key ou variável de ambiente, não contêm credenciais codificadas.
1. Pipeline único (entrada recomendada)
python scripts/video2ppt.py -i <arquivo/diretório/curinga do vídeo> [-o <diretório de saída>] --formats pptx,pdf --json
-o pode ser omitido: a saída padrão é o diretório do primeiro vídeo (não se mistura com o diretório raiz da Skill).
Exemplos:
# Vídeo inteiro → PPT + PDF
python scripts/video2ppt.py -i lecture.mp4 -o ./out --json
# Apenas 00:05:00 ~ 00:40:00, saída mantendo proporção sem deformação
python scripts/video2ppt.py -i lecture.mp4 -o ./out --start 00:05:00 --end 00:40:00 --fit fit
# Processar em lote todos os vídeos de um diretório, gerar apenas PPTX
python scripts/video2ppt.py -i ./videos -o ./out --formats pptx
Artefatos: <outdir>/frames/ (quadros extraídos), <outdir>/<nome>.pptx, <outdir>/<nome>.pdf.
--name pode especificar o nome base do arquivo de saída; o padrão é o nome do primeiro vídeo. Por exemplo, video/2_1.mp4 sem -o gera saída em video/frames/, video/2_1.pptx, video/2_1.pdf.
2. Execução passo a passo
2.1 Extração de quadros do vídeo
python scripts/video_to_frames.py -i <vídeo/diretório> [-o <diretório de quadros>] [parâmetros] --json
-opode ser omitido; o padrão é o diretórioframes/dentro do diretório do primeiro vídeo.- Parâmetros chave:
--start/--end(segundos ouHH:MM:SS),--similarity(padrão 0.8),--skip(padrão 15),--crop all(remover bordas pretas). - Nomes de arquivo de saída no formato
<nome_do_vídeo>_ppt_001_frame_000123.png, ordenados naturalmente por número de página.
2.2 Imagens → PPTX
python scripts/images_to_pptx.py -i <diretório de imagens> -o <saída.pptx> --fit fit --json
--fit stretch(padrão, estica para tela cheia) ou--fit fit(mantém proporção, centralizado com margens).- Opcional:
--title NomeDoCurso,--slide-width/--slide-height(polegadas, padrão 16×9),--bg 255,255,255.
2.3 Imagens → PDF
python scripts/images_to_pdf.py -i <diretório de imagens> -o <saída.pdf> --json
- Compressão ativada por padrão (
--max-width 1920,--jpeg-quality 85); use--no-compresspara manter qualidade original. --max-width 0significa sem redimensionamento.
3. Guia de ajuste de parâmetros
| Problema | Ajuste |
|---|---|
| Poucas páginas extraídas | Aumentar --similarity (0.8 → 0.85~0.9), diminuir --skip e --min-interval |
| Muitas páginas repetidas | Diminuir --similarity (0.8 → 0.7~0.75), aumentar --skip / --min-interval |
| Quadros de transição/borrados | Aumentar --delay-frames (ex.: 8~12), manter verificação de estabilidade ativa |
| Quadro considerado instável | Diminuir --stable-threshold (0.95 → 0.9) ou usar --no-stable-check |
| Saída com bordas pretas | --crop all; se ruído atrapalhar detecção, usar --crop-mode fixed com parâmetros de margem |
| Conteúdo 4:3 deformado | Usar --fit fit na composição |
| PDF muito grande | Manter compressão ativa, reduzir --jpeg-quality (85→60) ou --max-width (1920→1280) |
| Processamento lento | Aumentar --skip (ex.: 25), reduzir --resize (480→320), desligar --verbose |
Tabela completa de parâmetros em references/parameters.md (leia apenas se precisar de ajustes finos).
4. Verificação de resultados e tratamento de exceções
- Verifique primeiro o código de saída:
0sucesso;1nenhum resultado (0 quadros / entrada vazia);2erro de parâmetros;3dependência ausente;130interrompido. - Ao usar
--json, analise o stdout (logs no stderr); campos principais:- Extração:
frames_saved,output_dir,errors - Pipeline:
frames,outputs.pptx.slides,outputs.pdf.pages,errors
- Extração:
- Após sucesso, confirme que os arquivos de saída existem e têm tamanho > 0, e informe ao usuário o número de páginas e o caminho absoluto.
- Falhas comuns:
- Não foi possível abrir o vídeo: caminho com caracteres especiais ou codificação não suportada. Use ffmpeg para transcodificar para H.264 MP4:
ffmpeg -i in.mov -c:v libx264 -c:a aac out.mp4. - frames_saved = 0: Aumente a sensibilidade da similaridade conforme a Seção 3 e tente novamente.
- Erro OpenBLAS / alocação de memória ao importar cv2/numpy: O script já define
OPENBLAS_NUM_THREADS/OMP_NUM_THREADScomo 1 para evitar falhas comuns de alocação de buffer de thread; se o erro persistir, recrie o ambiente virtual (python -m venv .venve reinstalerequirements.txt), ou executepython -m pip install --force-reinstall numpy opencv-python. Ocheck_env.pye o script de extração já usam isolamento de subprocesso para detectar o problema e reportá-lo com código de saída 3, em vez de travar diretamente. - Caminhos/logs em chinês com caracteres ilegíveis: O script já força saída UTF-8; se o terminal ainda exibir caracteres estranhos, execute
export PYTHONIOENCODING=utf-8(Windows:set PYTHONIOENCODING=utf-8).
- Não foi possível abrir o vídeo: caminho com caracteres especiais ou codificação não suportada. Use ffmpeg para transcodificar para H.264 MP4:
- Não interaja com arquivos de parâmetros de versão GUI; todos os scripts desta Skill são sem interface gráfica e repetíveis.
5. Variáveis de ambiente
Nenhuma variável de ambiente é obrigatória. Os scripts não contêm chaves, senhas ou tokens codificados, nem acessam a rede (apenas a instalação inicial de dependências via pip requer internet).
Opcionais: OPENBLAS_NUM_THREADS, OMP_NUM_THREADS — o script define ambos como 1 por padrão para evitar falhas de alocação de buffer de thread no OpenBLAS em algumas máquinas Windows que causam travamento ao importar numpy/cv2; se a máquina for estável, pode-se aumentar (ex.: 8).