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. 결과 확인 및 예외 처리
- 먼저 종료 코드를 확인하십시오:
0성공;1결과 없음 (프레임 수 0 / 입력 없음);2매개변수 오류;3종속성 누락;130인터럽트됨. --json사용 시 stdout을 파싱하십시오 (로그는 stderr에 기록됨). 주요 필드:- 프레임 추출:
frames_saved,output_dir,errors - 파이프라인:
frames,outputs.pptx.slides,outputs.pdf.pages,errors
- 프레임 추출:
- 성공 후 출력 파일이 존재하고 크기가 0보다 큰지 확인하고 사용자에게 페이지 수와 절대 경로를 보고하십시오.
- 일반적인 실패:
- 동영상을 열 수 없음: 경로에 특수 문자가 있거나 지원되지 않는 인코딩 때문일 수 있습니다. 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)을 먼저 실행하십시오.
- 동영상을 열 수 없음: 경로에 특수 문자가 있거나 지원되지 않는 인코딩 때문일 수 있습니다. ffmpeg를 사용하여 H.264 MP4로 변환하십시오:
- GUI 버전 매개변수 파일과 상호 작용하지 마십시오. 이 Skill의 스크립트는 모두 GUI가 없으며 반복 실행 가능합니다.
5. 환경 변수
필수 환경 변수는 없습니다. 스크립트에는 하드코딩된 키, 비밀번호 또는 토큰이 포함되어 있지 않으며 네트워크에 액세스하지 않습니다 (처음 종속성을 설치할 때 pip가 인터넷에 연결되는 경우 제외).
선택 사항: OPENBLAS_NUM_THREADS, OMP_NUM_THREADS — 스크립트는 기본적으로 1로 설정하여 일부 Windows 시스템에서 OpenBLAS 스레드 버퍼 할당 실패로 인한 import numpy/cv2 충돌을 방지합니다. 시스템이 정상이면 필요에 따라 값을 늘릴 수 있습니다 (예: 8).