개요
kajisho5/ffmpeg-skill은 자연어로 받은 영상·오디오 편집 의도를 로컬 FFmpeg/FFprobe 실행으로 연결하는 Python 기반 Agent Skill이다.[1][3]
이번 기록은 main의 pinned commit 6b7188945e2e235553da90add03c8bd01df441f6을 대상으로 한다.[1] 캡처 시점 GitHub metadata에서 기본 브랜치는 main, 주 언어는 Python, 라이선스는 MIT, 관찰된 지표는 stars 152·forks 8·open issues 0·archived false였으며, 이 수치는 이후 변할 수 있다.[2]
저장소의 package version은 0.9.0이지만, 이 점검에서 GitHub published release/tag는 관찰되지 않았다.[10] 따라서 0.9.0을 최신 release라고 부르지 않고 pinned main의 package version으로만 기록한다.[1][10]
무엇을 제공하는가
- cut/trim/join, resize·reframe, speed change, SRT/ASS·animated/karaoke captions, logo·text overlay, lower-third·title, silence removal, multicam·외부 마이크 sync, loudness normalisation, HDR/Dolby Vision→SDR, LUT, background music ducking, platform export, compliance check, scene/highlight detection, contact sheet, declarative whole-edit project를 하나의 local execution skill로 묶는다.[3][4]
- 저장소가 명시한 기본 사용 원칙은 입력마다 먼저
probe,--dry-run --json으로 계획, 산출물 작성 후 검증, 화면이 바뀐 결과는look으로 확인하는 흐름이다.[4] - README는 API key·cloud·추가 dependency 없이
ffmpeg와python3가 PATH에 있으면 동작한다고 설명한다.[3] 이는 저장소의 설계 주장이지, 임의의 운영 환경에서의 보안·성능 보증은 아니다.[3]
실행 계약과 도구 표면
계약은 별도 문서의 수기 목록이 아니라 실행 코드에서 파생되며, contract_version과 skill/package version을 분리한다.[5][6]
| 역할 | 도구 |
|---|---|
| analysis | probe, scenes |
| execution | audio, batch, caption, color, cut, export, fit, graphics, join, multicam, overlay, render |
| analysis_and_execution | loudness, silence, sync |
| verification | check, look, report, verify |
계약 JSON은 총 21개 public tool에 대해 argparse 입력 스키마, canonical tool id, 역할, 필요한 FFmpeg capability, 출력/검증 규칙을 함께 노출한다.[5][6]
필수 런타임은 Python 3.9+, FFmpeg/FFprobe 5.0+이며, node >=16은 npx installer에만 필요하다.[6] 필수 capability에는 encoder:aac, encoder:libx264, filter:loudnorm, filter:scdet, filter:silencedetect, filter:subtitles, filter:tile, filter:xfade 등이 포함된다.[6]
각 입력은 새 산출물로 처리하고 입력을 수정하지 않는 것이 계약의 경계다.[6] subprocess는 python3 scripts/<tool>.py ... 또는 PATH에서 찾은 ffmpeg|ffprobe의 argv list로만 실행하며, shell·arbitrary executable·network access는 계약상 false다.[6][7]
CLI·MCP·installer 구조
각 script는 python3 scripts/<tool>.py [args] [--json] [--dry-run] 형태로 직접 실행할 수 있다.[7] 공통 runner는 FFmpeg 프로세스 실행·stdout/stderr 수집·probe·progress를 모으고, 개별 script는 편집 도메인 로직과 argparse를 담당한다.[7]
mcp/server.py는 별도의 수기 tool table을 유지하지 않는다.[8] tools/list는 contract의 ToolSpec 순서와 input schema에서 만들어지고, initialize·tools/call을 stdio JSON-RPC 2.0으로 제공한다.[5][8]
MCP 호출은 구조화된 arguments를 named script의 argv로 변환하는 표면이며, MCP가 임의 shell command를 실행하는 인터페이스는 아니다.[6] 다만 실제 media 작업의 품질과 파일 권한은 호출하는 host와 FFmpeg 설치에 달려 있다.[6][8]
Node installer의 payload는 SKILL.md, scripts, references, mcp, package.json이며, 기본 Claude Code·Cursor·Codex·project-local·custom directory 대상 설치 경로를 제공한다.[9]
사용 예시
# 저장소 checkout에서 직접 실행
python3 scripts/probe.py input.mp4 --json
python3 scripts/cut.py input.mp4 --start 0 --end 60 --dry-run --json
python3 scripts/cut.py input.mp4 --start 0 --end 60 -o final.mp4 --json
# 계약·host capability 확인
python3 scripts/_contract.py --json
python3 scripts/_contract.py doctor --json
# stdio MCP transport
python3 mcp/server.pypackage가 제공하는 npm 진입점은 npx ffmpeg-skill 계열 installer를 설명하지만, 이번 retrieval에서 published release/tag는 확인하지 않았다.[1] 실제 배포 패키지의 registry availability와 pinned checkout의 일치 여부는 별도 확인 대상이다.[9][10]
이번 pinned checkout에서 실제 확인한 것
| 검사 | 결과 |
|---|---|
checkout vs git ls-remote origin refs/heads/main | 동일한 full SHA 6b7188945e2e235553da90add03c8bd01df441f6 |
| tracked tree | 66 files; Python 34 files (git 기반 count) |
| Python syntax | python3 -m compileall -q scripts mcp evals tests exit 0 |
| contract eval | 10 expected answers agree with the contract, exit 0 |
| full fixture suite | Ran 56 tests in 754.846s — OK, exit 0 |
| contract suite | Ran 27 tests in 44.737s, OK (skipped=1), exit 0 |
| skip boundary | real-device corpus 미다운로드에 따른 1개 skip: tests/corpus.py --fetch 필요 |
| host doctor | ok=true; FFmpeg/FFprobe 6.1.1-3ubuntu5; required missing 0; optional missing external:whisper |
| isolated installer | /tmp/.../parent/ffmpeg-skill에 4개 핵심 파일 설치, contract 21 tools, doctor 성공 |
clean npm pack --dry-run | ffmpeg-skill@0.9.0, 31 files, 95,487 bytes tarball / 310,501 bytes unpacked |
전체 fixture suite는 합성/fixture media를 대상으로 실행한 결과이며, source의 real-device corpus 검증을 의미하지 않는다.[6] 실제 사용자의 카메라·오디오·HDR 원본, 실제 장시간 multicam 녹화, 외부 Whisper engine은 검증하지 않았다.
저장소 CI workflow는 현재 workflow_dispatch만 활성화되어 있고 push/pull request 자동 실행은 주석으로 보류되어 있다. 따라서 이 캡처에는 GitHub Actions의 pinned-commit green 결과를 붙이지 않고 local 실행 결과만 기록한다.[11]
보안·운영 경계
선택한 13개 pinned file과 전체 checkout을 대상으로 direct assignment, fallback literal, query secret, bearer-like token, userinfo URL을 값 없이 검사했으며 5개 matcher 모두 0이었다. 이는 저장소 snapshot에 credential-like literal이 없다는 bounded scan 결과일 뿐, 완전한 security audit은 아니다.
external:whisper는 optional capability이고[6], contract가 AI reasoning·decisions·production plans·approvals·network access·transcription engine을 제공하지 않는다고 명시한다.[6] 따라서 이 저장소는 편집 실행/검증 계층이지, 영상의 의미를 판단하거나 제작 결정을 대신하는 autonomous media agent가 아니다.[4]
필터·encoder availability, FFmpeg build 차이, 폰트와 입력 codec, 산출물에 대한 사람의 시각 검토가 결과에 영향을 준다.[6] doctor의 현재 Linux 결과가 통과했다고 해서 macOS·Windows·실제 배포 장비에서 같은 결과가 보장되지는 않는다.[6]
위키에서의 연결
- moc-multimedia — 영상·오디오 편집 실행 도구와 local media workflow
- moc-mcp — contract-derived stdio MCP server
- moc-ai-coding — Agent Skill·CLI·패키징·검증 표면
- 2026-07-27-github-bradautomates-claude-video — 영상 ingest/전사 중심 agent plugin과의 대비
- 2026-08-08-github-video-db-call-md — MCP 도구 호출형 영상·회의 에이전트와의 대비
핵심 해석
이 저장소의 가장 재사용 가능한 설계는 “자연어 의도 해석”과 “결정론적 media execution”을 분리하고, 하나의 contract에서 CLI·MCP schema·capability·verification metadata를 함께 파생하는 점이다.[5][6]
실무적으로는 probe → dry-run → execute → check/look/report를 강제하는 운영 순서가 단순한 FFmpeg command 모음보다 중요하다.[4] 반대로 --transcribe의 외부 engine, platform별 codec/filter, 실제 원본의 시각 품질은 이 repository snapshot만으로 확정할 수 없다.[4][6]
Sources
[1] https://github.com/kajisho5/ffmpeg-skill — kajisho5/ffmpeg-skill repository
> “Repository API html_url: https://github.com/kajisho5/ffmpeg-skill”
[2] https://api.github.com/repos/kajisho5/ffmpeg-skill — GitHub REST repository metadata
> ""default_branch”: “main”,
“language”: “Python”,”
[3] https://raw.githubusercontent.com/kajisho5/ffmpeg-skill/6b7188945e2e235553da90add03c8bd01df441f6/README.md — Pinned README.md at 6b718894
> “No API keys. No cloud. No dependencies. If ffmpeg and python3 are on your PATH, it works — offline, on any footage you’d rather not upload.”
[4] https://raw.githubusercontent.com/kajisho5/ffmpeg-skill/6b7188945e2e235553da90add03c8bd01df441f6/SKILL.md — Pinned SKILL.md at 6b718894
> “1. Probe first. Run probe.py on every input before touching it.”
[5] https://raw.githubusercontent.com/kajisho5/ffmpeg-skill/6b7188945e2e235553da90add03c8bd01df441f6/docs/contract.md — Pinned contract documentation at 6b718894
> “The contract is derived from the code that runs, not maintained beside it:”
[6] https://raw.githubusercontent.com/kajisho5/ffmpeg-skill/6b7188945e2e235553da90add03c8bd01df441f6/scripts/_contract.py — Pinned contract implementation at 6b718894
> ""subprocess”: “argv list only: [python3, scripts/