- typed-ffmpeg는 Python과 TypeScript에서 FFmpeg를 타입 안전하게 다루는 인터페이스로, 복잡한 필터 그래프에 대한 상세 타입과 문서를 제공함
ffmpeg-python에서 영감을 받았지만, IDE 자동완성, 포괄적 타입 지정, 필터 그래프 JSON 직렬화, 자동 FFmpeg 검증 같은 기능을 추가함- v4는 FFmpeg 5.x~8.x별 PyPI 패키지를 제공하며, 기본
typed-ffmpeg는 최신 FFmpeg 8.x 바인딩을 설치함
- Python 패키지는 표준 라이브러리만으로 동작하지만, 그래프 시각화와 CLI 파싱은 각각
[graph], [parse] 옵션 extra로 설치해야 함
- 브라우저에서 필터와 명령을 실험하고 실시간으로 그래프를 볼 수 있는 Interactive Playground가 제공되어 로컬 환경 없이 학습과 프로토타이핑이 가능함
typed-ffmpeg가 제공하는 FFmpeg 인터페이스
- typed-ffmpeg는 FFmpeg용 현대적 타입 안전 인터페이스를 Python과 TypeScript에 제공함
- 복잡한 필터에 대한 상세 타입과 문서를 지원하며,
ffmpeg-python의 일반적 한계로 든 IDE 통합 부족과 포괄적 타입 부재를 보완함
- 새 기능으로 필터 그래프 JSON 직렬화와 자동 FFmpeg 검증을 제공함
- 문서는 Documentation에서 확인할 수 있음
주요 기능
- Zero Dependencies: Python 표준 라이브러리만으로 구성되어 호환성과 보안을 높임
- Pythonic 인터페이스로 필터 그래프 구성을 단순화함
- 대부분의 FFmpeg 필터를 기본 지원하며, IDE 자동완성을 제공함
- 인라인 docstring으로 필터 사용법을 바로 참조할 수 있음
- 정적·동적 타입 검사를 제공해 코드 신뢰성과 개발 경험을 개선함
- 필터 그래프를 JSON 형식으로 저장하고 다시 불러올 수 있음
graphviz를 활용한 그래프 시각화로 이해와 디버깅을 돕음- 필터 그래프 오류 식별과 수정 보조 기능을 제공함
- 입력·출력 옵션, 추가 코덱과 포맷을 포함하는 더 포괄적인 인터페이스를 제공함
- 부분 평가를 통해 필터 그래프를 모듈식으로 구성하고 재사용할 수 있음
- FFmpeg의
ffprobe를 이용한 미디어 파일 분석을 내장 지원하며, 딕셔너리와 dataclass 인터페이스로 메타데이터를 추출함
FFmpeg 버전별 패키지 구조
- typed-ffmpeg v4는 FFmpeg 주 버전별로 별도 PyPI 패키지를 제공함
typed-ffmpeg: 최신 버전, FFmpeg 8.x 바인딩typed-ffmpeg-v5: FFmpeg 5.x 바인딩typed-ffmpeg-v6: FFmpeg 6.x 바인딩typed-ffmpeg-v7: FFmpeg 7.x 바인딩typed-ffmpeg-v8: FFmpeg 8.x 바인딩ffmpeg-core: 공유 런타임이며 자동 설치됨
- 모든 패키지는 같은
ffmpeg 네임스페이스를 노출하므로, 어떤 버전 패키지를 설치해도 코드 형태는 동일함
- 설치된 FFmpeg 버전에 맞추려면
ffmpeg -version | head -1로 버전을 확인한 뒤 대응하는 패키지를 설치함
- v4 패키지 구조는 v4 Package Architecture 문서에서 확인할 수 있음
- typed-ffmpeg 3.x에서 업그레이드할 때는 Migration Guide를 참고함
설치와 옵션 extra
- 최신 FFmpeg 8.x 바인딩은 다음 명령으로 설치함
pip install typed-ffmpeg
- 특정 FFmpeg 버전용 바인딩은 별도 패키지로 설치함
pip install typed-ffmpeg-v5 # FFmpeg 5.x
pip install typed-ffmpeg-v6 # FFmpeg 6.x
pip install typed-ffmpeg-v7 # FFmpeg 7.x
pip install typed-ffmpeg-v8 # FFmpeg 8.x
- 선택 기능은 extra로 설치함
[graph]: Graphviz 기반 그래프 시각화[parse]: CLI 파싱과 compile_as_python() 지원
[parse] extra는 ffmpeg.compile.compile_cli.parse()가 FFmpeg 명령줄에서 필터 그래프를 재구성하는 데 필요한 버전별 캐시 데이터 ffmpeg-data-v5부터 ffmpeg-data-v8까지를 설치함- 대부분의 사용자는
[parse] extra가 필요하지 않음
- 시스템에 FFmpeg가 설치되어 있어야 함
ffmpeg-python과 동시에 설치해야 할 경우 typed-ffmpeg-compatible을 설치해 모듈명 충돌을 피하고, import typed_ffmpeg as ffmpeg를 사용함
TypeScript 바인딩과 사용 예시
- TypeScript 바인딩은 실험적 기능으로, FFmpeg 주 버전별 npm 패키지를 제공함
@typed-ffmpeg/core: Node.js와 브라우저 ESM용 코어 런타임@typed-ffmpeg/v5: FFmpeg 5.x 바인딩@typed-ffmpeg/v6: FFmpeg 6.x 바인딩@typed-ffmpeg/v7: FFmpeg 7.x 바인딩@typed-ffmpeg/v8: FFmpeg 8.x 바인딩
- 최신 FFmpeg 바인딩은 다음 명령으로 설치함
npm install @typed-ffmpeg/core @typed-ffmpeg/v8
- TypeScript API는 Python API를 반영하되, 키워드 인자 대신 옵션 객체 같은 TypeScript 관용 패턴을 사용함
import { input } from "@typed-ffmpeg/v8";
const cmd = input("input.mp4")
.video
.scale({ w: 1280, h: 720 })
.output("output.mp4")
.overwriteOutput()
.compile();
// => ["-i", "input.mp4", "-filter_complex", "...", "output.mp4"]
@typed-ffmpeg/core는 CJS, ESM, 브라우저 안전 ESM 번들을 포함하며, exports 필드로 자동 선택됨- 각 버전 패키지는 FFmpeg 버전별 필터 가용성을 나타내는 JSDoc 주석을 포함함
Python 사용 흐름과 플레이그라운드
- 기본 사용 예시는
ffmpeg.probe()로 미디어 파일을 분석하고, input.mp4를 수평 반전해 output.mp4로 출력하는 흐름임
- 복잡한 예시는
trim, concat, overlay, drawbox를 조합해 필터 그래프를 구성함
- 더 많은 예시는 Usage 문서에서 확인할 수 있음
- Interactive Playground는 브라우저에서 typed-ffmpeg를 직접 실행해볼 수 있는 환경을 제공함
- FFmpeg 필터와 명령 실험
- 필터 그래프 실시간 시각화
- 입력·출력 구성 테스트
- 인터랙티브 예제로 학습
- 필터 그래프 공유
- 플레이그라운드는 로컬 환경 설정 없이 FFmpeg 필터 체인을 학습하고 프로토타이핑하는 데 적합함
개발 방식과 배경
- 초기 아이디어는 GPT-3로 FFmpeg 문서에서 FFmpeg 필터 SDK를 직접 생성하는 것이었음
- 개발 과정에서 GPT-3만으로 작업을 완전 자동화하는 데 한계가 있었고, SDK 완성을 위해 전통적인 코드 생성 방식으로 전환함
- GitHub Copilot과 GPT-3는 개발 속도를 높이고 시간을 절약하는 데 도움을 줌
ffmpeg-python 프로젝트의 API 스타일과 설계 아이디어가 typed-ffmpeg 개발에 영향을 줌- 개발 의존성은
pyproject.toml과 uv.lock으로 관리되며, 개발 환경은 다음 명령으로 설치함
uv pip install --group dev