ffmpeg-skill 공개: 코딩 에이전트와 MCP를 위한 42종 로컬 영상 편집 도구

개발자 kajisho5가 코딩 에이전트와 Model Context Protocol(MCP) 클라이언트를 위한 오픈소스 영상 편집 도구인 ffmpeg-skill을 공개했습니다. 이 도구는 별도의 외부 클라우드 서비스나 API 키 없이, 로컬 환경에 설치된 FFmpeg와 파이썬(Python) 표준 라이브러리만을 활용해 구동되는 비디오 편집 엔진입니다.

이미지 출처: https://github.com/kajisho5/ffmpeg-skill

기존 코딩 에이전트가 영상 파일을 다룰 때 불필요한 재인코딩 명령을 생성하거나 존재하지 않는 옵션을 임의로 추측해 실행 오류를 내던 한계를 해결하기 위해, 엄격한 실행 규격과 검증 절차를 내장한 것이 특징입니다.

42종 비디오 편집 도구와 무손실 우선 워크플로우

ffmpeg-skill은 로컬 CLI와 스크립트로 동작하는 42종의 세부 편집 도구를 제공합니다. 단순 컷 편집과 영상 이어붙이기(join)부터 무음 구간 감지 및 제거(silence removal), 화면비 및 재생 시간 맞춤(fit), 자막 및 노래방 하이라이트 생성, 오디오 라우드니스 정규화(loudness normalization), 멀티캠 동기화까지 영상 후반 작업에 필요한 전 기능을 아우릅니다.

• 체계적인 4단계 워크플로우: 모든 작업은 미디어 특성을 측정하는 probe로 시작하여, 가능한 경우 스트림 복사(-c copy) 기반의 무손실 편집을 우선 수행합니다. 이후 출력 사양과의 적합성을 확인하는 check, 변형된 프레임을 시각적으로 대조하는 verify 과정을 순차적으로 거칩니다.
• 타입 기반 CLI 인자 구성: 임의의 셸 문자열이나 검증되지 않은 복잡한 필터그래프를 그대로 실행하지 않고, 파이썬 표준 라이브러리의 argparse로 정의된 타입 검증 인자만을 사용해 안전한 실행을 보장합니다.

축약형 12종 기본 노출과 전체 42종 MCP 서버 연동

에이전트 연동 측면에서는 Claude Code, Cursor, Codex 등 주요 코딩 어시스턴트 환경을 공식 지원합니다. npx ffmpeg-skill 단일 명령으로 로컬 스킬 설치가 완료되며, npx ffmpeg-skill doctor를 통해 시스템 내 ffmpeg, ffprobe 및 세부 컴포넌트의 설치 상태를 즉시 진단할 수 있습니다.

• MCP 컨텍스트 최적화: MCP 서버로 구동될 때 tools/list 요청에는 기본적으로 핵심 12종 도구만 노출되어 에이전트의 프롬프트 컨텍스트 낭비를 줄입니다. 전체 42종 도구를 모두 노출해야 할 때는 환경변수 FFMPEG_SKILL_MCP_FULL=1을 설정하여 확장할 수 있으며, 도구 이름을 직접 지정하는 tools/call 호출은 기본 상태에서도 42종 전 도구에 접근할 수 있습니다.
• 자체 생성 실행 규격(SPEC): CLI 플래그 정의와 MCP 도구 스키마 간의 불일치를 막기 위해, 런타임에 파서로부터 직접 머신 가독형 JSON 규약(contract --json)을 추출하여 동기화합니다.

로컬 음성 엔진 의존성과 긴 렌더링 타임아웃 주의점

도구 도입 및 자동화 파이프라인 구성 시 사전에 점검해야 할 기술적 제약 사항도 명확히 정의되어 있습니다.

• 로컬 전사 엔진 요구: 음성 자막 생성(caption.py) 및 발화 기반 무음 정리(silence.py --transcribe) 기능을 활용하기 위해서는 Whisper나 Parakeet 등 로컬에 설치된 별도 음성 인식(ASR) 엔진이 필요합니다. 엔진이 없는 환경에서는 기존 전사 텍스트 파일을 직접 입력받아 처리합니다.
• 장시간 렌더링 타임아웃: 전체 영상 렌더링 시 기본 타임아웃은 1800초(30분)로 제한되어 있습니다. 1시간 분량의 고해상도 영상을 전체 재인코딩할 때는 타임아웃 오류를 방지하기 위해 --timeout 0 옵션을 명시하거나 고속 렌더링 옵션(--fast)을 지정해야 합니다.

출처

• GitHub 저장소: kajisho5/ffmpeg-skill