Crontab 파이썬 스크립트 실행 안될 때 환경변수 PATH 문제 해결 완벽 정리

날짜:
0

Python moviepy ffprobe not found 에러 및 동영상 인코딩 오류 완벽 해결 가이드

날짜:

Python moviepy로 영상 편집을 시도하다 'ffprobe not found', 'must be real number, not NoneType', 'ModuleNotFoundError' 등의 에러를 마주한 경험이 있습니까? 이 문제들은 FFmpeg 환경 설정 미비와 라이브러리 의존성 충돌에서 비롯됩니다. 이 글에서는 moviepy 동영상 처리 시 발생하는 주요 에러의 원인과 검증된 해결 방법을 단계별로 제시합니다.


FFmpeg환경변수설정과moviepyModuleNotFoundError해결실전가이드



1. moviepy와 FFmpeg의 관계: 왜 ffprobe 에러가 발생하는가

moviepy는 내부적으로 FFmpeg와 ffprobe를 호출하여 동영상 디코딩/인코딩 작업을 처리합니다. Python 라이브러리만 설치하고 FFmpeg 바이너리가 시스템에 없거나 PATH 환경변수에 등록되지 않았다면 다음과 같은 에러가 발생합니다.

  • ffprobe not found: moviepy가 영상 메타데이터를 읽을 수 없음
  • FFMPEG_BINARY not found: 인코딩 작업 실행 불가
  • OSError: [WinError 2] 지정된 파일을 찾을 수 없습니다 (Windows 환경)

핵심 원인: moviepy 패키지는 FFmpeg 실행 파일을 포함하지 않습니다. 별도 설치 및 환경변수 설정이 필수입니다.

2. FFmpeg 설치 및 환경변수 설정 (OS별 가이드)

Windows 환경

  1. FFmpeg 다운로드: 공식 사이트에서 Static Build 다운로드 (예: ffmpeg-release-essentials.zip)
  2. 압축 해제: C:\ffmpeg 경로에 압축 해제 (bin 폴더 내에 ffmpeg.exe, ffprobe.exe 확인)
  3. 환경변수 등록:
    • 시스템 속성 → 고급 → 환경 변수
    • Path 변수에 C:\ffmpeg\bin 추가
    • CMD 재시작 후 ffmpeg -version 명령으로 설치 확인

Linux/Mac 환경

  • Ubuntu/Debian: sudo apt update && sudo apt install ffmpeg
  • Mac (Homebrew): brew install ffmpeg
  • 설치 후 which ffmpeg로 경로 확인

주의사항: pip install ffmpeg는 Python wrapper일 뿐 실제 FFmpeg 바이너리를 설치하지 않습니다. 반드시 시스템 레벨에서 FFmpeg를 설치해야 합니다.

3. moviepy 주요 에러 해결 케이스

Case 1: 'must be real number, not NoneType'

mp3 파일을 mp4로 변환하거나 concatenate_videoclips 사용 시 발생하는 에러입니다. 원인은 FFmpeg 버전 호환성 문제입니다.

해결 방법:

  • FFmpeg 패키지 업그레이드: pip install ffmpeg-python --upgrade
  • moviepy 재설치: pip uninstall moviepy && pip install moviepy
  • imageio-ffmpeg 명시적 설치: pip install imageio-ffmpeg

이 에러는 moviepy가 비디오 클립의 duration 속성을 None으로 받아올 때 발생합니다. FFmpeg가 올바르게 메타데이터를 파싱하지 못한 경우이므로, imageio-ffmpeg (moviepy의 FFmpeg 바이너리 래퍼)를 최신 버전으로 유지하는 것이 핵심입니다.

Case 2: 'ModuleNotFoundError: No module named moviepy.editor'

pip list에 moviepy가 있는데도 import 실패하는 경우입니다. 주요 원인은 다음과 같습니다.

  • 파일명 충돌: 작업 디렉토리에 moviepy.py 파일이 있는 경우 (Python이 해당 파일을 패키지로 인식)
  • 가상환경 불일치: 설치한 환경과 실행 환경이 다른 경우
  • Python 버전 문제: moviepy는 Python 3.7+ 지원, 2.x에서는 작동하지 않음

해결 절차:

  1. 작업 디렉토리에서 moviepy.py 파일 삭제 또는 이름 변경
  2. 가상환경 활성화 확인: which python (Linux/Mac) 또는 where python (Windows)
  3. moviepy 재설치: pip uninstall moviepy && pip install moviepy
  4. import 테스트: python -c "from moviepy.editor import VideoFileClip"

4. 동영상 처리 시 알아야 할 코덱과 포맷 개념

moviepy로 본격적인 영상 편집을 하려면 코덱(Codec)과 컨테이너 포맷의 차이를 이해해야 합니다.

  • 컨테이너 포맷 (Container): mp4, avi, mkv 등 - 비디오/오디오 스트림을 담는 '그릇'
  • 비디오 코덱: H.264, H.265, VP9 등 - 실제 영상 압축 방식
  • 오디오 코덱: AAC, MP3, FLAC 등 - 음성 압축 방식

moviepy의 write_videofile() 메서드는 기본적으로 libx264 코덱 + AAC 오디오를 사용합니다. 다른 코덱을 사용하려면 다음과 같이 명시합니다.

clip.write_videofile("output.mp4", codec="libx264", audio_codec="aac", bitrate="5000k")

인코딩 최적화 팁:

  • 해상도가 높은 영상은 threads 파라미터로 멀티코어 활용: threads=4
  • 프리뷰 작업 시 preset="ultrafast" 설정으로 인코딩 속도 향상
  • 최종 배포용은 preset="slow" + 적절한 bitrate로 품질 확보

5. 실전 디버깅 체크리스트

moviepy 작업 중 에러 발생 시 다음 순서로 점검합니다.

  1. FFmpeg 설치 확인: ffmpeg -version 및 ffprobe -version 실행 가능 여부
  2. 환경변수 등록 확인: echo %PATH% (Windows) 또는 echo $PATH (Linux/Mac)에서 FFmpeg 경로 포함 여부
  3. moviepy 버전 확인: pip show moviepy (1.0.3 이상 권장)
  4. 의존성 패키지 확인: pip list | grep -E "imageio|decorator|proglog"
  5. 입력 파일 무결성: FFmpeg로 직접 재생 테스트 ffplay input.mp4

특히 ImageMagick이 필요한 텍스트 오버레이 작업 시에는 별도로 ImageMagick 설치 후 moviepy config 파일에 경로를 지정해야 합니다. (~/.config/moviepy/moviepy.conf)

요약 및 Action Item

moviepy 동영상 처리 에러의 90%는 FFmpeg 환경 설정 문제입니다. ffprobe not found 에러는 시스템에 FFmpeg를 설치하고 PATH 등록으로 해결되며, 'must be real number' 에러는 imageio-ffmpeg 업그레이드로 해결됩니다. ModuleNotFoundError는 파일명 충돌과 가상환경 불일치를 먼저 의심해야 합니다.

지금 당장 실행할 Action Item: 터미널에서 ffmpeg -version을 실행하여 FFmpeg 설치 여부를 확인하고, 없다면 OS에 맞는 설치 방법으로 FFmpeg를 설치한 뒤 환경변수를 등록하십시오. 이후 pip install moviepy imageio-ffmpeg --upgrade로 의존성을 최신화하면 대부분의 인코딩 에러가 해결됩니다.




# 함께 보면 좋은 글

댓글

댓글 쓰기