Communitygithub.com

video2ppt

동영상/화면 녹화에서 PPT 화면 프레임을 지능적으로 추출하여 PPTX(슬라이드 한 장당 하나의 이미지) 또는 PDF로 변환합니다.

video2ppt란 무엇인가요?

이 스킬은 동영상(강의 녹화, 회의 녹화, 화면 녹화 등)에서 슬라이드 프레임을 자동으로 추출하여 PPTX 또는 PDF 파일로 변환합니다. SSIM 기반 중복 프레임 제거, 지연 캡처, 선명도 기반 최적 프레임 선택, 검은 테두리 자르기, PDF 압축 등 다양한 고급 기능을 제공합니다. 사용자는 하나의 명령으로 전체 파이프라인을 실행하거나, '동영상 → 프레임 추출', '이미지 → PPTX', '이미지 → PDF' 단계를 개별적으로 실행할 수 있습니다. 시간 범위 지정, 프레임 유사도 임계값 조정, 이미지 해상도 제어 등 세부 매개변수를 통해 결과물의 품질을 미세 조정할 수 있습니다. 이 스킬은 로컬에서 실행되며 별도의 API 키나 네트워크 연결이 필요하지 않습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/knoyuuki/skills-video2ppt/tree/HEAD/video2ppt

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

video2ppt은(는) 무엇을 하나요?

동영상에서 슬라이드 화면을 이미지로 추출한 후 PPTX(슬라이드 한 장당 하나의 이미지) 또는 PDF로 합성합니다. 세 가지 기능을 각각 사용하거나 하나의 파이프라인으로 연결할 수 있습니다:

스크립트기능일반적인 사용 예
scripts/video2ppt.py원클릭 파이프라인: 동영상 → 프레임 → PPTX/PDF사용자가 최종 PPT/PDF만 원할 때 (우선 사용)
scripts/video_to_frames.py동영상에서 지능적으로 프레임 추출, 이미지 시퀀스 출력사용자가 스크린샷을 원하거나 수동 선별 후 합성할 때
scripts/images_to_pptx.py이미지 폴더 → PPTX이미 스크린샷/이미지가 있고 프레젠테이션을 생성하려는 경우
scripts/images_to_pdf.py이미지 폴더 → PDF이미 스크린샷/이미지가 있고 PDF를 생성하려는 경우

모든 명령은 이 Skill의 루트 디렉터리(이 파일이 포함된 디렉터리)에서 실행해야 합니다. 스크립트는 로그를 stderr에 기록하며, --json 옵션을 사용하면 stdout에서 기계가 읽을 수 있는 요약을 얻을 수 있습니다.

0. 환경 설정 (최초 사용)

python scripts/check_env.py
  • 종료 코드 0: 모든 종속성이 설치됨; 종료 코드 3: 필수 종속성이 누락됨.
  • 종속성 누락 시 설치: python -m pip install -r scripts/requirements.txt
  • 필수: opencv-python, numpy, python-pptx, Pillow; 선택적 추가: scikit-image(SSIM 중복 제거), img2pdf(PDF 스트리밍 병합, 누락 시 Pillow로 자동 대체).
  • 스크립트는 API 키나 환경 변수를 읽지 않으며 하드코딩된 자격 증명이 없습니다.

1. 원클릭 파이프라인 (권장 진입점)

python scripts/video2ppt.py -i <동영상 파일/디렉터리/와일드카드> [-o <출력 디렉터리>] --formats pptx,pdf --json

-o는 생략 가능합니다. 기본값은 첫 번째 동영상이 있는 디렉터리로 설정됩니다(Skill 루트 디렉터리와 혼합되지 않음).

예:

# 전체 동영상 → PPT + PDF
python scripts/video2ppt.py -i lecture.mp4 -o ./out --json

# 00:05:00 ~ 00:40:00 만 처리, 비율 유지하여 변형 없이 출력
python scripts/video2ppt.py -i lecture.mp4 -o ./out --start 00:05:00 --end 00:40:00 --fit fit

# 디렉터리 내 모든 동영상 일괄 처리, PPTX만 생성
python scripts/video2ppt.py -i ./videos -o ./out --formats pptx

산출물: <outdir>/frames/ (추출된 화면), <outdir>/<name>.pptx, <outdir>/<name>.pdf. --name을 사용하여 출력 파일 기본 이름을 지정할 수 있습니다. 기본값은 첫 번째 동영상의 파일 이름입니다. 예: video/2_1.mp4에서 -o를 생략하면 출력은 video/frames/, video/2_1.pptx, video/2_1.pdf가 됩니다.

2. 단계별 실행

2.1 동영상 프레임 추출

python scripts/video_to_frames.py -i <동영상/디렉터리> [-o <프레임 디렉터리>] [매개변수] --json
  • -o는 생략 가능하며, 기본값은 첫 번째 동영상이 있는 디렉터리 아래의 frames/입니다.
  • 주요 매개변수: --start / --end (초 또는 HH:MM:SS), --similarity (기본값 0.8), --skip (기본값 15), --crop all (검은 테두리 제거).
  • 출력 파일 이름 형식: <동영상명>_ppt_001_frame_000123.png, 페이지 번호 순으로 자연 정렬됩니다.

2.2 이미지 → PPTX

python scripts/images_to_pptx.py -i <이미지 디렉터리> -o <출력.pptx> --fit fit --json
  • --fit stretch (기본값, 전체 화면 늘이기) 또는 --fit fit (비율 유지, 중앙 정렬 여백).
  • 선택 사항: --title 과정명, --slide-width/--slide-height (인치, 기본값 16×9), --bg 255,255,255.

2.3 이미지 → PDF

python scripts/images_to_pdf.py -i <이미지 디렉터리> -o <출력.pdf> --json
  • 기본적으로 압축이 활성화됩니다 (--max-width 1920, --jpeg-quality 85); --no-compress를 사용하면 원본 화질을 유지합니다.
  • --max-width 0은 크기 조정 없음을 의미합니다.

3. 매개변수 조정 가이드

문제조정 방법
추출된 페이지 수가 너무 적음--similarity 증가 (0.8 → 0.85~0.9), --skip 및 --min-interval 감소
중복 페이지가 너무 많음--similarity 감소 (0.8 → 0.7~0.75), --skip / --min-interval 증가
전환 애니메이션/흐린 프레임 캡처--delay-frames 증가 (예: 8~12), 안정성 검사 유지
화면이 계속 불안정하다고 판단됨--stable-threshold 감소 (0.95 → 0.9) 또는 --no-stable-check 추가
출력에 검은 테두리 있음--crop all; 노이즈로 인한 감지 오류 시 --crop-mode fixed와 여백 매개변수 함께 사용
동영상이 4:3 비율인데 출력이 변형됨합성 시 --fit fit 사용
PDF 크기가 너무 큼압축 유지, --jpeg-quality 감소 (85→60) 또는 --max-width 감소 (1920→1280)
처리 속도가 너무 느림--skip 증가 (예: 25), --resize 감소 (480→320), --verbose 비활성화

전체 매개변수 표는 references/parameters.md을 참조하십시오 (세밀한 조정이 필요할 때만 읽으십시오).

4. 결과 확인 및 예외 처리

  1. 먼저 종료 코드를 확인하십시오: 0 성공; 1 결과 없음 (프레임 수 0 / 입력 없음); 2 매개변수 오류; 3 종속성 누락; 130 인터럽트됨.
  2. --json 사용 시 stdout을 파싱하십시오 (로그는 stderr에 기록됨). 주요 필드:
    • 프레임 추출: frames_saved, output_dir, errors
    • 파이프라인: frames, outputs.pptx.slides, outputs.pdf.pages, errors
  3. 성공 후 출력 파일이 존재하고 크기가 0보다 큰지 확인하고 사용자에게 페이지 수와 절대 경로를 보고하십시오.
  4. 일반적인 실패:
    • 동영상을 열 수 없음: 경로에 특수 문자가 있거나 지원되지 않는 인코딩 때문일 수 있습니다. ffmpeg를 사용하여 H.264 MP4로 변환하십시오: ffmpeg -i in.mov -c:v libx264 -c:a aac out.mp4.
    • frames_saved = 0: 섹션 3에 따라 유사도 민감도를 높인 후 다시 시도하십시오.
    • OpenBLAS / 메모리 할당 오류 (cv2/numpy 임포트 시): 스크립트는 기본적으로 OPENBLAS_NUM_THREADS / OMP_NUM_THREADS를 1로 설정하여 일반적인 스레드 버퍼 할당 실패를 방지합니다. 계속 오류가 발생하면 가상 환경을 다시 만드십시오(python -m venv .venv 후 requirements.txt 재설치) 또는 python -m pip install --force-reinstall numpy opencv-python을 실행하십시오. check_env.py와 프레임 추출 스크립트는 하위 프로세스 격리를 통해 이 문제를 보고하며 충돌 없이 종료 코드 3을 반환합니다.
    • 중국어 경로/로그 깨짐: 스크립트는 UTF-8 출력을 강제합니다. 터미널에서 여전히 깨져 보이면 export PYTHONIOENCODING=utf-8 (Windows: set PYTHONIOENCODING=utf-8)을 먼저 실행하십시오.
  5. GUI 버전 매개변수 파일과 상호 작용하지 마십시오. 이 Skill의 스크립트는 모두 GUI가 없으며 반복 실행 가능합니다.

5. 환경 변수

필수 환경 변수는 없습니다. 스크립트에는 하드코딩된 키, 비밀번호 또는 토큰이 포함되어 있지 않으며 네트워크에 액세스하지 않습니다 (처음 종속성을 설치할 때 pip가 인터넷에 연결되는 경우 제외).

선택 사항: OPENBLAS_NUM_THREADS, OMP_NUM_THREADS — 스크립트는 기본적으로 1로 설정하여 일부 Windows 시스템에서 OpenBLAS 스레드 버퍼 할당 실패로 인한 import numpy/cv2 충돌을 방지합니다. 시스템이 정상이면 필요에 따라 값을 늘릴 수 있습니다 (예: 8).

관련 스킬