kajisho5/ffmpeg-skill

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

ffmpeg‑skill이란 무엇인가요?

ffmpeg‑skill은 FFmpeg을 위한 로컬 에이전트 친화적 래퍼로, AI 코딩 에이전트(Claude Code, Cursor, Codex 또는 모든 MCP 클라이언트)가 미디어를 클라우드로 전송하지 않고도 비디오 및 오디오 파일을 편집할 수 있게 해줍니다. 이 도구는 각각 타입이 지정된 명령줄 인터페이스와 입력, 출력, 필요한 FFmpeg 기능을 설명하는 기계 판독 가능한 계약을 노출하는 42개의 소형 파이썬 도구(예: cut.py, fit.py, loudness.py, caption.py) 모음을 제공합니다.

이 스킬은 엄격한 워크플로우를 따릅니다:

프로브 (Probe): probe.py를 사용하여 소스의 정확한 메타데이터(길이, fps, 해상도, 색 공간, 오디오 레이아웃, HDR 등)를 가져옵니다.
편집 (Edit): 가능한 경우 무손실(스트림 복사)로 편집하고, 필터나 정밀한 자르기가 필요한 경우에만 재인코딩합니다.
검증 (Verify): 다시 프로브하여 결과를 검증하고, 선택적으로 PNG 연락 시트(look.py)를 생성합니다.
보고 (Report): 호출하는 에이전트가 구문 분석할 수 있는 구조화된 JSON 보고서를 반환합니다.

이 모든 과정은 오프라인에서 실행되며, FFmpeg, ffprobe 및 Python 3(표준 라이브러리만 사용)만 있으면 됩니다. API 키나 외부 서비스가 필요 없으며, 음성 인식(ASR)은 로컬 ASR 엔진이 설치된 경우에만 작동합니다.

주요 기능

기능	중요성
에이전트 준비 계약 (`contract --json`)	에이전트는 JSON 스키마를 읽어 전달하는 플래그가 기본 `argparse` 정의와 일치함을 보장할 수 있어 문서와 코드 간의 불일치를 방지합니다.
42개의 집중 도구	각 작업(자르기, 결합, 무음 제거, 자막, HDR→SDR, 음량 정규화 등)은 타입이 지정된 인수를 가진 별도의 스크립트이므로 LLM이 올바른 도구를 호출하기 쉽습니다.
무손실 우선 워크플로우	편집 시 재인코딩이 필요하지 않은 경우 도구는 스트림 복사(`-c copy`)를 시도하여 품질을 유지하고 시간을 절약합니다.
드라이런 및 계획 (`--dry-run`, `--plan FILE`)	에이전트는 파일이 작성되기 전에 정확한 FFmpeg 명령줄을 미리 보거나 나중에 실행할 수 있는 재현 가능한 계획을 생성할 수 있습니다.
검증 단계 (`look.py`, `check.py`)	편집 후 출력을 다시 프로브하며, 시각적 내용이 변경된 경우 PNG 시트가 생성되어 에이전트가 결과를 "확인"할 수 있습니다.
기능 감지 (`doctor`)	작업을 실행하기 전에 로컬 FFmpeg 빌드에 필요한 인코더/필터(예: `libass`, `zscale`, `loudnorm`)가 포함되어 있는지 확인합니다.
외부 의존성 없음	순수 Python 3.9+ 표준 라이브러리; 선택적 로컬 ASR 엔진(Parakeet‑mlx, faster‑whisper, openai‑whisper)은 존재하는 경우에만 사용됩니다.
템플릿 기반 전달 (`render.py --template tiktok`)	TikTok, Reels, Shorts 등 플랫폼을 위한 사전 구축된 JSON 템플릿이 화면 비율, 자막 스타일, 음량 목표 및 내보내기 사전 설정을 자동으로 설정합니다.
교차 저장소 생태계	더 큰 AI 비디오 제작 OS의 "손" 역할을 하도록 설계되었으며, 다른 스킬(미디어 분석, 전사, 자막, 색 보정)이 이 계약을 호출할 수 있습니다.

시작하기

# 스킬 설치 (Claude의 스킬 디렉토리에 추가)
npx ffmpeg-skill

# 머신에 필요한 FFmpeg 구성 요소가 있는지 확인
npx ffmpeg-skill doctor

# JSON 계약 검사 (에이전트나 사용자 정의 도구에 유용)
npx ffmpeg-skill contract --json | head -40

명령줄에서 직접 도구를 실행할 수도 있습니다. 예:

python3 ~/.claude/skills/ffmpeg-skill/scripts/cut.py input.mp4 \
    --segments 0:45-3:10,5:00-6:30 --dry-run

또는 전체 플랫폼별 패키지를 렌더링하려면:

python3 $HOME/.claude/skills/ffmpeg-skill/scripts/render.py talk.mp4 \
    --template tiktok --cues cues.txt

AI 에이전트의 일반적인 사용 사례 흐름

사용자 요청 – "interview.mp4에서 최고의 하이라이트를 사용하여 60초짜리 Reel을 만들어줘."
에이전트가 SKILL.md를 읽고 워크플로우를 이해합니다.
프로브 – probe.py가 정확한 메타데이터를 반환합니다.
자르기 결정 – 에이전트는 scenes.py를 호출하여 하이라이트 제안을 받고, 선택한 세그먼트로 cut.py를 실행합니다.
맞춤 및 형식 지정 – fit.py로 9:16 비율을 강제하고, export.py --preset reels로 올바른 코덱/비트레이트를 설정합니다.
확인 – check.py --platform reels로 길이, 음량 등을 검증합니다.
보기 – look.py가 연락 시트를 생성하고, 에이전트가 PNG를 검사하여 시각적 결과를 확인합니다.
보고 – 스킬은 상태, 출력 경로, 프로브 요약 및 PNG를 가리키는 Look: 라인이 포함된 JSON 객체를 반환합니다.

누가 사용하나요?

AI 기반 비디오 편집기를 구축하는 개발자: 신뢰할 수 있는 오프라인 FFmpeg 백엔드가 필요한 경우.
프롬프트 엔지니어: 원시 셸 문자열을 작성하지 않고 LLM 에이전트가 미디어를 조작하게 하려는 경우.
콘텐츠 제작자: 플랫폼별 빠른 편집을 위해 로컬 및 개인정보 보호 우선 워크플로우를 선호하는 경우.
연구원: 비디오 편집 결과를 "확인"해야 하는 멀티모달 에이전트를 실험하는 경우.

제한 사항

이 스킬은 무엇을 자를지, 어떤 자막을 쓸지, *어떤 하이라이트가 "흥미로운지"*를 결정하지 않습니다. 해당 로직은 호출하는 AI 두뇌의 몫입니다.
로컬 FFmpeg 빌드에 의존합니다. 필터가 누락되면 해당 도구를 사용할 수 없습니다(doctor가 보고함).
음성 전사는 선택 사항이며 지원되는 로컬 ASR 엔진이 설치된 경우에만 작동합니다.

라이선스

MIT – 자유롭게 사용, 수정 및 다른 프로젝트에 포함할 수 있습니다.