Communitygithub.com

top110341/ffmpeg

자연어 요청으로 로컬 FFmpeg를 사용해 동영상과 오디오를 편집합니다. 자르기, 다듬기, 합치기, 크기/프레임 변경(9:16, 1:1), 속도 변경, 자막(SRT/ASS, 애니메이션, 가라오케), 로고 및 텍스트 오버레이, 하단 서드와 타이틀, 무음 제거, 멀티캠 및 외부 마이크 싱크, 음량 정규화, HDR/돌비 비전을 SDR로 변환, LUT, 배경음악(덕킹), 플랫폼 내보내기(YouTube, Reels, TikTok, X), 규격 검사, 장면 감지 및 하이라이트 릴, 연락처 시트(결과 확인), 전체 편집 프로젝트 파일을 지원합니다.

ffmpeg란 무엇인가요?

이 FFmpeg 기반 AI 스킬은 개발자와 AI 에이전트가 자연어 요청만으로 고급 비디오 및 오디오 편집을 수행할 수 있도록 설계되었습니다. 로컬에서 실행되며 별도의 클라우드 API나 키가 필요 없고, Python 3.9 표준 라이브러리만 사용합니다. 자르기, 합치기, 크기 조정(세로/가로/정사각형), 속도 변경, 자막(SRT/ASS, 애니메이션, 가라오케), 로고 및 텍스트 오버레이, 하단 서드, 무음 제거, 멀티캠/외부 마이크 싱크, 음량 정규화(LUFS), HDR에서 SDR로 변환, LUT 적용, 배경음악 덕킹 등 42개의 스크립트를 제공합니다. 또한 YouTube, Reels, TikTok, X 등 플랫폼별 내보내기 템플릿과 규격 검사, 장면 감지, 하이라이트 릴 생성, 연락처 시트 기능을 포함합니다. MCP(모델 컨텍스트 프로토콜)를 통해 기본 12개 도구를 노출하며, 전체 42개 도구는 이름으로 호출할 수 있습니다. 사용자가 '60초', '세로', '크게', '자막 넣어줘'와 같은 표현을 사용할 때, 또는 파일(mp4, mov, mkv, wav, m4a)을 언급할 때 자동으로 관련 스크립트를 추천합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/top110341/ffmpeg/tree/HEAD/.claude/skills/ffmpeg-skill

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

ffmpeg-스킬

스크립트는 이 파일과 같은 디렉토리의 scripts/에 있습니다. python3 <스킬-디렉토리>/scripts/<이름>.py로 실행하고, 배송 템플릿은 templates/에 있습니다. 이 파일만으로 작업을 수행할 수 있습니다. 아래 표는 요청을 라우팅하고, 실행할 스크립트의 --help가 가장 저렴한 전체 플래그 목록입니다. 참조 파일은 이 파일과 동일한 비용이 듭니다. 질문이 있을 때만 엽니다: references/scripts.md (42개 스크립트의 모든 플래그), references/devices.md (iPhone HDR, GoPro, DJI, 화면 녹화, Zoom), references/gotchas.md (마지막에 있는 한 줄 규칙의 상세 버전). MCP: tools/list는 기본적으로 핵심 12개만 표시하며, 나머지 30개(이 표 기준)는 tools/call로 이름을 통해 호출할 수 있고, contract --json으로 설명합니다. 모든 42개를 표시하려면 FFMPEG_SKILL_MCP_FULL=1을 설정하세요.

모든 스크립트에 공유되는 플래그: --dry-run; --json (출력 경로, 출력 프로브, 실행된 명령어); --json-brief (상태/출력/확인 + summary; 작성 단계에서 선호); --fast (미리보기 품질); --progress; --timeout SECONDS (kind: timeout, 기본값 1800); --overwrite (7단계); --plan FILE (dry run을 render.py FILE이 나중에 실행할 계획으로 만듦; 입력이 변경되면 거부). 재인코딩 도구는 --codec h264|hevc|av1|prores와 --quality N을 사용하며, 설정하지 않으면 SDR은 x264, HDR은 x265 Main10입니다. prores는 -o NAME.mov가 필요하고, h264는 HDR을 거부합니다(color.py --to-sdr 먼저 실행).

작성 도구는 --dry-run에서 아무것도 실행하지 않습니다. 측정 도구(probe, check, sync, multicam, scenes, cropdetect, report, silence, loudness, stabilize)는 여전히 ffmpeg/ffprobe를 실행할 수 있으며, 아티팩트/사이드 파일(--edl, --sheet, 생성된 .ass)을 건너뜁니다. verify는 플래그를 무시합니다. 도구별: contract --json dry_run.

워크플로우 (이 순서로)

  1. 환경, 실패 시에만. doctor로 작업을 시작하지 마십시오. 고장난 머신은 kind: missing_tool 또는 필터/인코더를 명명하는 ffmpeg 오류와 함께 실패합니다. 이러한 실패 후 또는 머신이 무엇을 할 수 있는지 물을 때 python3 <스킬-디렉토리>/scripts/_contract.py doctor(또는 npx ffmpeg-skill doctor)를 실행하십시오: ok/usable을 읽고 누락된 기능을 보고합니다. contract --json의 도구 스키마는 이 워크플로우가 아닌 계획 에이전트를 위한 것입니다.
  2. 계획을 세우기 위해 프로브할 대상을 정합니다. 각 입력에 대해 probe.py를 실행하여 지속 시간, fps, 해상도, 코덱, 채널, variable_frame_rate_suspected를 확인하고, 사용자가 파일에 대해 물을 때마다 실행합니다. 모든 편집 전에 별도로 프로브할 필요는 없습니다. 모든 작성 도구의 --json은 이미 입력과 출력 프로브를 포함합니다. 추정이 아닌 실제 숫자로 계획하십시오.
  3. 무손실을 선호합니다. 재인코딩 없이 요청을 충족할 수 있는 경우(키프레임에서의 일반 컷, 리먹싱, 오디오 전용 변경) 재인코딩하지 마십시오. cut.py와 loudness.py는 기본적으로 비디오를 스트림 복사합니다. cut.py의 --accurate는 프레임 정확한 컷에만 사용합니다.
  4. --dry-run --json으로 계획을 세운 후 실행합니다. 계획의 숫자에 대해 dry run의 요약 줄이 아닌 --json을 신뢰하십시오(차원은 플레이스홀더일 수 있음). 긴 인코딩 전에 사실을 보고하는 데 사용하십시오. --fast는 미리보기 품질이고, --progress는 stderr에 백분율/ETA를 출력합니다. 사용자가 교체를 요청하지 않는 한 이 작업에서 생성하지 않은 파일을 -o로 지정하지 마십시오. 그럴 때만 --overwrite를 전달하십시오.
  5. 합리적인 순서로 체인을 구성합니다. 다른 편집이 없는 배송 요청은 수동으로 구축한 체인이 아니라 하나의 템플릿 실행(render.py --template NAME INPUT)입니다. 그렇지 않은 경우: 색상(HDR→SDR / LUT) → 컷 → 조인 → 무음 → 맞춤 → 자막/오버레이 → 싱크 → 오디오 → 음량 → 내보내기. 자막 전에 프레임을 변경하여 텍스트가 최종 프레임에 맞게 크기가 조정되도록 합니다. 가능한 한 적게 재인코딩하십시오: 중간 파일은 CRF 18, export.py는 마지막입니다. 세 단계 이상: render.py와 project.json을 사용하십시오.
  6. 산출물을 확인합니다. 보고하기 전에, 명명된 대상에 대해 check.py OUTPUT --platform X를 실행하십시오(템플릿 실행은 이미 수행합니다). 형식 행(코덱, 픽셀 형식, 크기, 실제 피크, 색상 태그, VFR)은 수정해도 안전합니다. 판단 행은 내용을 변경합니다: 지속 시간(컷은 자료를 잃음), 종횡비(크롭은 가장자리를 잃음), fps(모션을 떨어뜨림), 음량(앰비언스를 부스트해서는 안 됨) — 요청이 답을 암시하는 경우에만 수정하고, 그렇지 않으면 선택과 비용을 명시하십시오. WARN을 언급하되 쫓지 마십시오.
  7. 출력을 검증합니다. 작성 도구의 --json/--json-brief 프로브 또는 probe.py를 통해 지속 시간, 해상도, fps 및 오디오가 요청과 일치하는지 확인하고 해당 숫자를 보고합니다(

관련 스킬