billsmokes/skill-video-agent

ffmpeg-skill

Local FFmpeg video editor for coding agents: 42 tools (probe, cut, fit, captions and karaoke, loudness, silence, delivery checks) with a probe, edit, check, verify workflow.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/billsmokes/skill-video-agent --skill ffmpeg-skill

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

ffmpeg-skill

Local video editor for agents: 42 FFmpeg tools with a machine-readable contract. Source: kajisho5/ffmpeg-skill (MIT, 7,023 stars), v3.10.1, main @ f1c97cb Audit 17 Nov 2026: CLEAN — no network calls in scripts/ or mcp/ (zero urllib/ requests/socket/curl), no credential reads (only sets an HW-accel env var), all ffmpeg via subprocess.run([...list...]), no shell, no eval/exec; doctor() explicitly fetches nothing; installer only copies files + runs ffmpeg -version. No dependencies (package.json: none). Python stdlib only.

Layout (this install)

SKILL.md here; tools in scripts/ NEXT TO it (upstream plugin layout puts them two levels up — paths below are corrected for this layout). References in references/ (workflow, gotchas, flags, requests, timestamps, report, scripts, devices, ci-platform-pitfalls). Contract: docs/contract.md. Run from the skill directory: python3 scripts/<name>.py (tools live in scripts/ next to this file).

Requirements

  • ffmpeg + ffprobe on PATH (tested with ffmpeg 8.1.2, python 3.12.3).
  • Python 3 standard library only — no extra dependencies.
  • Optional: a local speech engine (faster-whisper, openai-whisper, or parakeet)

for --transcribe. ASR is opt-in only: without an engine installed the tools refuse with install lines; no model is ever auto-downloaded by the skill's own code. If your faster-whisper lives in a venv, use that venv's python for --transcribe.

  • MCP server exists (python3 mcp/server.py, stdio, stdlib only) — the CLI

tools are the interface. Do not npx install.

  • Run python3 scripts/_contract.py doctor to check which capabilities your

ffmpeg build has.

Workflow (probe → plan → run → check → verify → look)

  1. On failure only: python3 scripts/_contract.py doctor.
  2. Probe what you plan from: scripts/probe.py in.mp4 --json (real duration,

fps, resolution, codecs — never assume).

  1. Prefer lossless: no re-encode when a cut/remux/audio-only change suffices.
  2. Plan with --dry-run --json, then run. Trust --json numbers.
  3. Chain: colour → cut → join → silence → fit → caption/overlay → sync →

audio → loudness → export. 3+ steps: a render.py project.

  1. Check: scripts/check.py OUT --platform shorts|reels|youtube — fix FAILs,

mention WARNs. (See LOUDNESS RULE below for the loudness row.)

  1. Verify from the writer's --json probe or probe.py: exit 0 + the

requested numbers, or it failed.

  1. Keep originals: never overwrite a source; --overwrite only for this

job's files.

  1. Look after any picture change: scripts/look.py OUT --tiles 3x2, view

the PNG, name it. This replaces hand-rolled ffmpeg -vf fps=... frame grabs.

⚠️ LOUDNESS RULE — READ BEFORE USING loudness.py / check.py

The skill's standard is −14 LUFS / −1 dBTP (YouTube/Spotify). That may NOT be your target. Do NOT normalize to −14 LUFS unless you have decided it is your target. For example, a YouTube Shorts pipeline targeting ≈ −24 LUFS integrated sits ~10 LU below the skill's −14 standard, and check.py --platform shorts then FAILs only the loudness row (11/12 pass) because of it. The skill itself notes the platform auto-normalises anyway. Recommendation: decide your target first; use loudness.py --measure-only as a MEASUREMENT tool, and run check.py --platform shorts --lufs <your-target> so the check judges against YOUR target. If loudness ever becomes a retention question, A/B-test −14 on ONE video — never switch a whole pipeline on the skill's default alone. Related ffmpeg lesson: amix defaults normalize=1 (cuts ~6 dB) — use normalize=0 in mixes unless you want that.

Recommended workflow (adopt) vs what stays (keep)

ADOPT:

  • probe-first discipline — probe.py before any edit (we used to assume).
  • `check.py` delivery check — 12-row PASS/WARN/FAIL per platform (duration,

aspect, fps, codec, colour, size, audio, loudness, true peak). Run on every finished Shorts/long-form file before delivery.

  • `look.py` contact sheet — one 3x2 PNG with timestamps replaces manual

frame extraction for QA (verified 17 Nov on the Listrik reel).

  • `loudness.py --measure-only` — LUFS/TP/LRA measurement for the audio

log (do not normalise with it by default — see rule above).

  • `silence.py` — silence/jump-cut detection for talking-head or clip trimming.
  • `fit.py` / `cut.py --smart` — reframing + frame-exact cuts with partial-GOP

re-encode when a clip must be trimmed outside Remotion.

  • Platform safe zones (from _platforms.py): reels top 8% / bottom 20% /

left 5% / right 12%; shorts top 6% / bottom 18% — captions/titles must clear these.

  • `sync.py` — drift correction (use alongside your own sync check).

KEEP AS-IS (do not replace):

  • This skill is the ffmpeg FINISHING + QA layer, not a renderer — it

complements your renderer (Remotion, Blender, etc.), it does not replace it.

  • Keep your existing karaoke/caption pipeline if you have one (the skill's

caption karaoke is an alternative path, not a mandatory replacement).

  • Keep your existing sync verification if you have one (the skill's sync.py

is an alternative).

Request → script (most-used)

NeedCommand
What's in this file?probe.py in.mp4 (--analyze, --field duration)
Is this OK to upload?check.py final.mp4 --platform shorts (add --lufs -24 for our target)
Show me what it looks likelook.py out.mp4 --tiles 3x2 → view the PNG
Measure loudness onlyloudness.py in.mp4 --measure-only --json
Cut / trimcut.py in.mp4 --start 1:20 --end 2:05 (--smart = frame-exact)
Make it 9:16 / 60 sfit.py in.mp4 --aspect 9:16 --fit pad / --duration 60
Remove pausessilence.py in.mp4
Burn captions from SRTcaption.py in.mp4 --srt subs.srt (--animate pop --karaoke with --transcribe)
Watermark / logooverlay.py in.mp4 --image logo.png --position top-right
Export for a platform`export.py in.mp4 --preset youtubereelsshorts`
Whole edit as a project`render.py --template reelsshortstiktok in.mp4 --cues cues.txt`
Batch a folderbatch.py FOLDER --recipe batch.json --jobs auto
Machine-readable contractpython3 scripts/_contract.py --json
Capability checkpython3 scripts/_contract.py doctor

Full routing table + variants: upstream SKILL.md at https://github.com/kajisho5/ffmpeg-skill/blob/main/skills/ffmpeg-skill/SKILL.md; per-tool flags: references/scripts.md or --help. Never run raw ffmpeg/ ffprobe when one of the 42 scripts exposes the feature — say so and name the closest option instead.