개요

kajisho5/ffmpeg-skill은 Claude Code·Cursor·Codex 같은 코딩 에이전트나 MCP 클라이언트가 로컬 FFmpeg로 영상·오디오를 편집하고, 자기 산출물을 직접 검증하게 해 주는 Agent Skill이다. 클라우드와 API 키가 필요 없고 Python 표준 라이브러리만 쓴다. npx ffmpeg-skill 한 줄로 설치한다.

2026-09-04 첫 캡처(v0.9.0, 도구 21개, stars 152) 이후 두 달 사이에 급성장했다. 2026-11-03 캡처 기준 v3.1.1, 도구 42개, stars 4,431, forks 350, MIT, 기본 브랜치 main(HEAD 1ce2c186)이다. 수치는 시점 값이다. v3.0.0·v3.1.0·v3.1.1이 모두 2026-10-31 하루에 올라왔다.

핵심 설계

README가 내세우는 원칙은 “에이전트가 FFmpeg를 안다고 해도 여전히 추측한다”는 문제를 없애는 것이다. 프레임레이트를 짐작하고, 컨테이너가 못 담는 코덱을 고르고, 스트림 복사로 충분한 파일을 재인코딩하고, 결과를 열어 보지 않은 채 “완료”라고 보고하는 실수를 구조로 막는다.

  • Probe first — 모든 작업은 probe로 측정한 길이·fps(VFR 감지)·해상도·HDR·오디오 레이아웃에서 시작한다.
  • Lossless when possible — cut·loudness는 건드리지 않는 스트림을 복사하고, 프레임 정확도·필터·포맷 변경이 필요할 때만 재인코딩한다.
  • Plan before render — 모든 도구가 --dry-run, --plan FILE(계획을 저장해 render가 나중에 실행, 입력이 바뀌면 거부), --json, --timeout, --overwrite를 갖는다.
  • 구조화된 도구, 셸 문자열 아님 — 원시 ffmpeg 인자나 filter_complex는 어떤 도구도 받지 않는다. 플래그는 argparse 파서이고, 그 파서에서 계약과 MCP inputSchema가 실행 시점에 파생된다(저자는 이를 SPEC, Self-Producing Execution Contract라 부른다). CI가 드리프트를 막는다.
  • 실행 뒤 검증 — 결과를 다시 probe하고, 목적지 규격으로 check하고, 화면이 바뀌었으면 look의 컨택트 시트로 눈으로 확인한다. 측정하지 못한 값은 통과가 아니라 not_measured 실패다. 이것이 도구가 42개나 되는 이유로 제시된다. 작업마다 약속이 다르고 도구가 그 약속을 사후에 측정하기 때문이다.
  • doctor — ffmpeg -encoders/-filters/-bsfs를 읽어 필요한 구성요소가 이 빌드에 있는지 작업 전에 보고한다. GPU 인코더 컴파일 여부와 FFmpeg CVE 표 대조(ffmpeg_security)도 포함한다.

도구 42개

구분도구
분석·점검probe, scenes, look
편집cut, join, silence, fit, crop, cropdetect, deinterlace, denoise, redact, sphere, straighten, insert, background, reverse, stabilize, sequence, waveform, freeze, pad, speedramp, loop, broll, metadata, grid
오디오audio, sync, loudness
화면caption, overlay, graphics, color
전달export, proxy, check, report
오케스트레이션render, batch, multicam, verify

v0.9.0의 21개에서 두 배가 된 증가분은 주로 단일 목적 편집 도구(crop·denoise·deinterlace·redact·speedramp·broll 등)와 전달·점검 도구(proxy·cropdetect)다. 오디오 파일도 wav·flac·mp3·m4a·ogg·opus를 영상과 같은 명령으로 처리하고, 화면 도구는 오디오 입력을 “입력에 비디오 스트림 없음”으로 거부한다.

도구의 경계는 의도적으로 좁다. 예컨대 redact는 주어진 사각형만 가리고 얼굴·번호판을 찾지 않으며, cropdetect --motion-centre는 9:16 리프레임용 모션 중심을 보고만 하고 크롭 결정은 에이전트에 맡긴다. multicam --switch energy는 마이크 음량을 말하는 사람의 대용으로 쓸 뿐 화자 식별은 없다.

플랫폼 납품

render.py --template이 tiktok·reels·shorts·youtube·x·linkedin·facebook·podcast·audiogram 템플릿을 채운다. 예를 들어 --template tiktok --cues cues.txt는 9:16 크롭, 플랫폼 UI를 피한 단어별 팝 캡션, -14 LUFS, 내보내기 프리셋, check --platform tiktok을 한 번에 수행한다. --template all은 영상 목적지 7곳을 같은 편집에서 렌더하고 결과 표 <name>_pack.md를 쓴다.

MCP·설치

  • mcp/server.py는 stdio JSON-RPC이고 자체 도구 표가 없다. tools/list가 계약에서 만들어진다.
  • 기본 노출은 핵심 12개(render, look, caption, export, check, fit, cut, audio, loudness, graphics, silence, probe)뿐이다. 클라이언트 컨텍스트를 아끼기 위해서이고 나머지 30개는 이름으로 tools/call하면 된다. FFMPEG_SKILL_MCP_FULL=1이면 42개를 모두 나열한다.
  • prompts capability로 워크플로 레시피 5개(reel, podcast, multicam, delivery_check, hdr)를 이름으로 불러 쓸 수 있다.
  • npx ffmpeg-skill이 ~/.claude/skills/에 설치하고(--cursor, --codex, --all), 설치본은 자동 갱신되지 않아 재실행해야 한다.
  • 자막 전사(caption --transcribe, silence --filler --transcribe)는 선택 사항이다. Parakeet·faster-whisper·openai-whisper 중 하나를 따로 설치하며 오디오는 업로드되지 않지만 모델 가중치는 첫 실행 때 내려받을 수 있다.

버전 변화(0.9.0 → 3.x)

이전 요약의 “릴리스 없음, package version 0.9.0”은 더는 맞지 않는다. 지금은 릴리스 v3.1.1이 Latest다.

v3.0.0(2026-10-31)은 도구를 늘리지 않은 호환성 정리 릴리스다.

  • 요구 사양 상향: FFmpeg 5.x와 Python 3.9 지원을 제거했다. 이제 FFmpeg ≥6.1, Python ≥3.10이며 더 낮은 FFmpeg는 ffmpeg_unsupported로 명시적으로 거부한다.
  • cut 기본값 변경: 단일 .mp4/.mov 스트림 복사가 edit list를 유지해 화면이 --start에서 정확히 시작한다. SDR HEVC 소스는 기본적으로 HEVC로 재인코딩한다. --vfr-guard 기본값은 sampled가 됐다. 2.x 동작은 각각 --no-edit-list, --no-keep-hevc로 되돌린다.
  • probe가 시작 타임코드를 보고한다(OTIO/EDL 연동 요청에 따른 추가).

cut 기본값이 바뀌었으므로 2.x 기준으로 짠 스크립트나 프롬프트를 쓰는 곳은 결과가 달라질 수 있다.

생태계 위치

저자 kajisho5는 이 저장소를 영상 제작 생태계의 “hands”(자르고·측정하고·내보내고 JSON으로 보고)로 규정한다. 무엇을 자를지, 납품물을 승인할지, 캡션에 무슨 문구를 쓸지는 “brain”(video-production-agent, AI-video-production-OS)의 몫이고 이 저장소는 그것을 하지 않으며 의존은 한 방향이다. 설계 규율은 같은 저자의 논문 What Is Verification-Driven Coding?(Zenodo)에 정리돼 있는데, 논문은 ffmpeg-skill을 그 규율에 “부분 적합”으로 평가한다.

이번에 검증하지 않은 것

  • 2026-11-03 캡처는 README와 릴리스 노트, GitHub 메타데이터를 읽은 것이다. v3.1.1을 설치하거나 테스트 스위트를 다시 돌리지 않았다.
  • 2026-09-04에 v0.9.0 pinned checkout에서 본 결과(fixture 56개 테스트 OK, 계약 21개 도구, 자격 증명성 리터럴 0건)는 현재 버전에는 적용되지 않는다. 그 시점 CI workflow는 workflow_dispatch만 활성화돼 있었고, 현재 상태는 확인하지 않았다.
  • README의 “FFmpeg 6.1/7.1/8/9 CI 테스트”, “tools 42개”, “의존성 없음”은 저장소의 자기 주장이다. 실제 카메라·HDR 원본이나 장시간 multicam, 외부 Whisper 엔진은 검증하지 않았다.
  • stars 4,431은 사이트 인기 지표이고 품질 보증이 아니다. 급성장 직후라 추세 해석은 시간이 지나야 한다.

위키에서의 연결

핵심 해석

가장 재사용할 만한 설계는 “의도 해석”과 “결정론적 미디어 실행”을 분리하고, 한 계약에서 CLI·MCP 스키마·capability·검증 메타데이터를 함께 파생하는 점이다. 도구가 늘어도 스키마가 코드와 어긋나지 않는다. 운영 순서 probe → dry-run → execute → check/look을 강제하는 것이 FFmpeg 명령 모음보다 더 큰 가치다.

반대로 이 저장소는 영상의 의미를 판단하지 않는다. 컷 포인트·하이라이트·캡션 문구는 호출하는 에이전트의 몫이고, 하이라이트 제안(scenes --rank-by)도 “가장 좋은 장면”이 아니라 음량·길이 대용값이다.


Sources

[1] https://github.com/kajisho5/ffmpeg-skill — README, 릴리스 v3.0.0, GitHub 메타데이터 (2026-11-03 캡처, main 1ce2c186) > “Give your coding agent a video editor.” [2] 이전 캡처: raw/articles/2026-09-04-github-kajisho5-ffmpeg-skill.md (v0.9.0, main 6b718894) — 위 “버전 변화”의 비교 기준