ffmpeg-skill: 코딩 에이전트가 로컬 FFmpeg로 영상을 편집하게 해 주는 스킬
ffmpeg-skill은 Claude Code, Cursor, Codex 같은 코딩 에이전트가 내 컴퓨터의 FFmpeg로 영상을 자르고 자막을 입히고 플랫폼 규격에 맞춰 내보내게 해 주는 스킬 겸 MCP 서버예요. 클라우드나 API 키 없이 로컬에서 돌고, 결과를 다시 측정해 확인하는 절차까지 정해 둔 점이 특징이에요. 다만 하루에도 여러 번 버전이 올라갈 만큼 변화가 빨라서 버전을 고정해 쓰는 편이 좋아요.
무엇을 해 주나요
저장소 설명에 따르면 FFmpeg를 감싼 Python 도구 42개와, 그 도구들의 입력 형식을 기계가 읽을 수 있게 적은 “계약(contract)”을 함께 제공해요. 에이전트는 SKILL.md에 적힌 순서대로 측정 → 가능하면 무손실 편집 → 규격 검사 → 결과 검증을 거치게 돼요. 도구는 셸을 거치지 않고 ffmpeg·ffprobe를 직접 호출하며, 호출하는 쪽이 임의의 필터 그래프를 넘기는 것은 받지 않는다고 해요.
- 측정(probe.py): 길이, 프레임 레이트(가변 프레임 포함), 해상도, HDR 형식, 색 태그, 오디오 스트림을 먼저 재요. 이후 단계는 이 값을 기준으로 판단해요.
- 자르기(cut.py): 먼저 재인코딩 없는 스트림 복사로 자르고, 프레임 단위 정확도가 필요할 때만 다시 인코딩해요.
- 무음 제거(silence.py): 말이 없는 구간을 찾아 지우되, 말소리 앞뒤로 남길 여유 시간을 정할 수 있어요.
- 자막(caption.py): SRT·ASS 자막을 영상에 입히고, 노래방식 단어 강조와 플랫폼별 안전 영역을 지원해요. 음성 받아쓰기는 선택 기능이고 로컬 엔진으로 돌아요.
- 내보내기와 검사: render.py는 플랫폼 템플릿(예: tiktok)을 채워 영상을 만들고, export.py는 릴스 같은 프리셋을 적용하고, check.py는 결과물이 플랫폼 규격에 맞는지 채점해요.
- 눈으로 확인(look.py): 프레임을 모은 밀착 인화 이미지를 만들어 에이전트가 화면을 직접 보고 판단하게 해요.
- MCP 서버와 점검: mcp/server.py가 계약을 바탕으로 도구 목록을 만들어요. 기본은 핵심 12개만 보이고, FFMPEG_SKILL_MCP_FULL=1을 주면 42개가 모두 보여요. doctor 명령은 설치된 FFmpeg의 인코더·필터 목록을 읽어 도구별로 쓸 수 있는지 알려 줘요.
설치와 사용
FFmpeg 6.1 이상(그 아래 버전은 거부)과 Python 3.10 이상이 필요하고, Python은 표준 라이브러리만 써요. npx 설치기를 쓰려면 Node 16 이상이 있어야 해요. README의 기본 설치 순서는 이래요.
sudo apt install ffmpeg
npx ffmpeg-skill # Claude Code (--cursor, --codex, --all)
npx ffmpeg-skill doctor
npx ffmpeg-skill contract --json | head -40
설치 뒤에는 에이전트에게 말로 시키거나, 스크립트를 직접 부를 수도 있어요.
S=~/.claude/skills/ffmpeg-skill/scripts
python3 $S/probe.py input.mp4 --compact
python3 $S/fit.py input.mp4 --duration 60 --aspect 9:16 --dry-run
python3 $S/export.py input.mp4 --preset reels --json
MCP 클라이언트에서는 설정 파일의 mcpServers 항목에 python3와 설치된 mcp/server.py 경로를 적어 연결해요. 받아쓰기를 쓰려면 faster-whisper 같은 음성 엔진을 따로 설치해야 해요.
숫자는 어떻게 읽어야 하나요
저장소 설명에 따르면 0.8.0 버전에서 리눅스와 로컬 FFmpeg 6.1로 실제 기기 영상 10개를 돌려 검증 단계 92개를 모두 통과했고, 음성 싱크 맞추기는 40건 모두 10ms 안, 장면 전환 감지는 53개 컷에서 F1 0.97이었다고 해요. 에이전트 평가는 0.8.4에서 프롬프트 24개로 72회를 돌려 모두 통과했고, 채점은 별도 모델이 했다고 해요. 모두 개발자가 직접 잰 값이고 지금 버전(3.10.x)보다 훨씬 이전 버전 기준이라는 점을 감안해야 해요. 표본도 크지 않아요.
README는 불리한 결과도 적어 두었어요. 애플 VideoToolbox 하드웨어 인코딩은 M4 Max에서 x264·x265보다 2~7배 빨랐지만, 같은 화질(SSIM)에서는 파일이 1.1~2.9배 컸다고 해요. 한 시간짜리 영상을 youtube 프리셋으로 내보내다 기본 제한 시간 1,800초에 걸려 아무것도 저장되지 않은 사례와, 한 번 실행에 약 7만 2천 토큰이 든다는 점도 밝혀 두었어요.
누구에게 쓸모 있나요
강의나 인터뷰 영상에서 무음을 빼고 자막을 입혀 쇼츠·릴스용 세로 영상으로 바꾸는 일을 자주 하는 사람에게 잘 맞아요. FFmpeg 옵션을 외우지 않아도 에이전트에게 말로 시킬 수 있고, 결과를 다시 재서 확인하니 “됐다고 했는데 실제로는 아닌” 상황을 줄여 줘요. 영상 파일을 외부로 올리고 싶지 않은 경우에도 쓸 만해요.
쓰기 전에 알아 둘 점
- 데이터 전송: PRIVACY.md에 따르면 텔레메트리나 사용 데이터를 보내지 않고, 도구 자체는 네트워크를 쓰지 않아요. 예외는 받아쓰기로, 따로 설치한 음성 엔진이 처음 실행할 때 모델을 내려받을 수 있어요.
- 안 되는 것: 얼굴이나 제품을 찾는 기능이 없어서 세로 자르기는 기본적으로 가운데 기준이에요. 립싱크와 화자 구분도 없고, 로고 지우기는 테두리를 섞는 수준이지 지우고 채우는 방식이 아니에요.
- 정확도와 시간: 스트림 복사로 자르면 시작점이 GOP 하나만큼 앞당겨질 수 있고, 긴 재인코딩은 –timeout을 늘려야 해요.
- 플랫폼 차이: 윈도우에서는 실제 기기 검증을 전부 돌리지 않았고, macOS 기본 ffmpeg에는 자막·drawtext·zscale이 빠져 있을 수 있어요. GPU 인코딩은 Apple Silicon의 VideoToolbox만 지원해요.
- 변화 속도: 11월 15일 하루에만 3.9.1부터 3.10.1까지 다섯 번 릴리스됐고, 열린 이슈에도 copy 모드 자르기 길이 오류, HDR 색 변환 문제 같은 항목이 있어요. 저장소 설명에 따르면 3.x 안에서는 도구 이름·인자·JSON 키를 바꾸지 않는다고 해요.
저장소 상태
- 별 7.3k, 포크 664 (GitHub 표시값)
- 열린 이슈 27개, 열린 PR 8개, 닫힌 PR 399개
- 언어: Python (GitHub 트렌딩 페이지 표시 기준. 저장소 페이지의 언어 비율 막대는 읽히지 않았어요). README는 Python 표준 라이브러리로 만들었다고 설명해요.
- 라이선스: MIT
- 마지막 커밋: 2026년 11월 15일 (3.10.1 버전 올림), 커밋 수 590개
- 최신 릴리스: v3.10.1 (11월 15일)
- 최상위 폴더: skills/ffmpeg-skill, mcp, scripts, tests, evals, templates, docs 등. README가 말하는 MCP 서버, 평가, 템플릿 폴더가 실제로 있어요.
확인 범위
2026년 11월 17일에 GitHub 웹 페이지로 확인(API 미사용)했어요. 저장소 첫 페이지와 README 전체, 커밋 목록, 릴리스 페이지, 이슈 목록 첫 페이지, PR 목록, PRIVACY.md를 읽었어요. 이슈 목록 두 번째 페이지와 개별 이슈 본문, docs 폴더 문서는 읽지 않았어요. 코드 분석과 설치·실행은 하지 않았어요.