FFmpeg 비디오 편집기
ffmpeg과 fftools.py 헬퍼 스크립트를 사용하여 터미널에서 비디오, 오디오, 이미지를 편집합니다.
CLI 도구
모든 작업은 헬퍼 스크립트를 통해 수행됩니다. 리포지토리를 클론한 위치 또는 다음 경로에서 찾을 수 있습니다:
SCRIPT="~/.claude/skills/ffmpeg/scripts/fftools.py"
모든 출력은 JSON입니다.
명령어 참조
# INFO — 파일 세부 정보 확인 (길이, 해상도, 코덱, 크기)
python3 $SCRIPT info input.mp4
# CUT — 구간 추출
python3 $SCRIPT cut input.mp4 output.mp4 --start 00:01:30 --end 00:02:45
python3 $SCRIPT cut input.mp4 output.mp4 --start 00:01:30 --duration 30
# MERGE — 여러 비디오 연결
python3 $SCRIPT merge video1.mp4 video2.mp4 video3.mp4 -o merged.mp4
python3 $SCRIPT merge video1.mp4 video2.mp4 -o merged.mp4 --reencode # 다른 코덱
# EXTRACT AUDIO — 오디오 트랙 추출
python3 $SCRIPT extract-audio input.mp4 output.mp3
python3 $SCRIPT extract-audio input.mp4 output.opus --bitrate 128k
# SUBTITLES — 비디오에 자막 굽기
python3 $SCRIPT subtitles input.mp4 output.mp4 --srt subs.srt
# RESIZE — 해상도 변경
python3 $SCRIPT resize input.mp4 output.mp4 --width 1280 --height 720
python3 $SCRIPT resize input.mp4 output.mp4 --width 1920 --height -1 # 자동 높이
# GIF — 비디오를 애니메이션 GIF로 (2패스, 고품질)
python3 $SCRIPT gif input.mp4 output.gif --fps 15 --width 480
python3 $SCRIPT gif input.mp4 output.gif --start 00:00:05 --duration 3
# THUMBNAIL — 단일 프레임 추출
python3 $SCRIPT thumbnail input.mp4 thumb.jpg --time 00:00:30
# THUMBNAILS — N개의 균등 간격 프레임 추출
python3 $SCRIPT thumbnails input.mp4 --count 10 --output-dir ./thumbs/
# COMPRESS — 파일 크기 줄이기
python3 $SCRIPT compress input.mp4 output.mp4 --crf 28 --preset medium
python3 $SCRIPT compress input.mp4 small.mp4 --crf 32 --preset fast # 적극적 압축
# SPEED — 재생 속도 변경
python3 $SCRIPT speed input.mp4 fast.mp4 --factor 2.0 # 2배 빠르게
python3 $SCRIPT speed input.mp4 slow.mp4 --factor 0.5 # 절반 속도 (슬로우 모션)
# WATERMARK — 이미지 오버레이 추가
python3 $SCRIPT watermark input.mp4 output.mp4 --watermark logo.png --position bottom-right
# TEXT — 텍스트 오버레이 굽기
python3 $SCRIPT text input.mp4 output.mp4 --text "1장" --position center --size 72 --border
python3 $SCRIPT text input.mp4 output.mp4 --text "할인!" --position top-left --start 5 --end 15
# CONVERT — 형식 변환
python3 $SCRIPT convert input.avi output.mp4
python3 $SCRIPT convert input.mp4 output.webm --video-codec libvpx-vp9
# FRAMES — 프레임을 이미지로 추출
python3 $SCRIPT frames input.mp4 --output-dir ./frames/
python3 $SCRIPT frames input.mp4 --output-dir ./frames/ --every 30 # 30프레임마다
# AUDIO REPLACE — 오디오 트랙 교체
python3 $SCRIPT audio-replace input.mp4 output.mp4 --audio music.mp3
# VOLUME — 오디오 레벨 조정
python3 $SCRIPT volume input.mp4 output.mp4 --level 2.0 # 볼륨 두 배
python3 $SCRIPT volume input.mp4 output.mp4 --level 0.5 # 볼륨 절반
python3 $SCRIPT volume input.mp4 output.mp4 --level 10dB # 10dB 증가
# FADE — 페이드 인/아웃 효과 추가
python3 $SCRIPT fade input.mp4 output.mp4 --fade-in 2 --fade-out 3
# STABILIZE — 흔들린 영상 보정 (vidstab 필터 필요)
python3 $SCRIPT stabilize input.mp4 output.mp4 --shakiness 7 --smoothing 15
# TRANSCRIBE — 화자 레이블이 포함된 음성-텍스트 변환 (오프라인; 자세한 내용은 Transcription 섹션 참조)
python3 $SCRIPT transcribe meeting.mp4 # → meeting.json/.srt/.txt
python3 $SCRIPT transcribe meeting.mp4 --speakers 3 # 화자 수 지정
python3 $SCRIPT transcribe meeting.mp4 --no-diarize # 화자 구분 없이 텍스트만
Transcription 및 분석 — 비디오에서 말한 내용 이해하기
transcribe 명령어를 사용하여 회의 녹음, 인터뷰 또는 모든 음성 비디오/오디오를 화자 레이블이 포함된 타임스탬프 기반 텍스트로 변환합니다. "무슨 내용이 논의되었나요?", "누가 뭐라고 말했나요?", "이 회의 요약", "X에 대해 이야기한 부분 찾기" 같은 질문에 사용하는 도구입니다.
100% 로컬 및 오프라인으로 실행되며, 오디오가 기기를 벗어나지 않고 클라우드 API가 필요 없습니다. 내부적으로는 WhisperX (large-v3)를 사용한 음성 인식 및 단어 수준 타임스탬프와 sherpa-onnx를 사용한 화자 분할(토큰 불필요, 오픈 ONNX 모델)을 수행합니다.
일회성 설정 (최초 한 번 네트워크 필요)
/setup-transcribe 슬래시 명령어를 실행하거나 직접 다음을 실행하세요:
bash ~/.claude/skills/ffmpeg/scripts/install-transcribe.sh
기본적으로 GitHub 릴리스에서 사전 빌드된 번들을 가져와(빠름: 모델 게이트 없음, torch 빌드 없음) 완전히 오프라인에서 설치합니다. 만약 사용할 수 없는 경우(릴리스 누락 또는 플랫폼 휠이 일치하지 않는 경우) 자동으로 처음부터 빌드하는 방식으로 대체됩니다. 이 스크립트는 격리된 Python 3.12 가상 환경(uv 사용)과 모든 모델을 생성하며, 이후 transcribe 명령은 네트워크가 필요 없습니다. 명령어가 가상 환경이 없다고 보고하면 이 명령을 실행하세요.
필요시 특정 모드를 강제할 수 있습니다:
bash install-transcribe.sh --release # 사전 빌드된 릴리스 번들만
bash install-transcribe.sh --build # 처음부터 빌드만 (HF + PyPI)
HF_TOKEN=hf_xxx bash install-transcribe.sh --build # --diarizer pyannote도 활성화
네트워크가 차단된 환경 / HuggingFace 접근 불가? 연결된 머신에서 한 번 자체 포함 번들을 빌드하고, 어디에든 호스팅한 후 HF/PyPI 접근 없이 설치하세요:
# install-transcribe.sh가 이미 실행된 머신에서:
bash ~/.claude/skills/ffmpeg/scripts/make-bundle.sh ffmpeg-transcribe-bundle.tar.gz
번들은 모든 코드, 모델, 모델 캐시 및 Python 휠을 포함합니다. 2GB를 초과하면 호스팅/업로드 제한에 맞게 자동으로 <name>.part-aa, <name>.part-ab, ... (각각 2GB 미만)으로 분할됩니다. 그런 다음 대상 머신(uv, ffmpeg, python3.12만 필요)에서:
# 단일 파일 번들:
bash install-transcribe.sh --bundle https://your.server/ffmpeg-transcribe-bundle.tar.gz
# 분할 번들 — 순서대로 부분 전달 (자동으로 연결됨):
bash install-transcribe.sh --bundle \
https://your.server/ffmpeg-transcribe-bundle.tar.gz.part-aa \
https://your.server/ffmpeg-transcribe-bundle.tar.gz.part-ab
(수동으로 다시 조합하려면: cat ffmpeg-transcribe-bundle.tar.gz.part-* > ffmpeg-transcribe-bundle.tar.gz)
사용법
# 전체 텍스트 + 화자 레이블 (meeting.json, meeting.srt, meeting.txt 파일 생성)
python3 $SCRIPT transcribe meeting.mp4
# 옵션
python3 $SCRIPT transcribe interview.mp4 --speakers 2 # 알려진 화자 수 → 정확도 향상
python3 $SCRIPT transcribe call.m4a --language en # 언어 강제 지정 (자동 감지 건너뛰기)
python3 $SCRIPT transcribe lecture.mp4 --format txt # .txt만 출력
python3 $SCRIPT transcribe long.mp4 --model medium # 더 빠르고 덜 정확함
python3 $SCRIPT transcribe q4.mp4 --diarizer pyannote # 더 높은 품질의 화자 분할 (HF 토큰 필요)
python3 $SCRIPT transcribe notes.mp4 --no-diarize # 화자 분할 없이 텍스트만
python3 $SCRIPT transcribe raw.wav -o ./out/session # 사용자 지정 출력 기본 경로
출력 형식
.txt— 사람이 읽기 쉬우며 화자 발화 단위로 그룹화됨. 내용을 이해하려면 이 파일을 읽으세요:[00:03:12] SPEAKER_01: ....srt— 화자 태그가 포함된 자막. 다시 비디오에 굽기(subtitles명령어)에 사용.json— 전체 구조화된 데이터: 모든 세그먼트 및 단어의 시작/종료 시간과 화자 정보. 프로그래매틱 분석(검색, 타임라인, 타임스탬프 인용)에 사용
회의 분석 워크플로우
# 1. 화자 레이블과 함께 텍스트 변환
python3 $SCRIPT transcribe meeting.mp4
# 2. 내용 분석을 위해 텍스트 읽기
# (meeting.txt를 읽거나 meeting.json을 파싱하여 타임스탬프 확인)
# 3. 여기서 요약, 작업 항목 추출, 누가 무엇을 말했는지 확인, 또는 특정 시점으로 이동:
# JSON 타임스탬프를 cut/thumbnail과 연결
python3 $SCRIPT cut meeting.mp4 clip.mp4 --start 00:12:30 --end 00:14:00
참고:
- 음성 인식은 CPU에서 실행됩니다 (CTranslate2에는 Apple Silicon에서 GPU 경로가 없음). 따라서 large-v3 모델은 대략 실시간의 1
2배 속도입니다. 1시간 회의는 처리에 약 3060분이 소요됩니다 — 백그라운드에서 실행하기 적합합니다. 속도를 위해--model medium또는distil-large-v3를 사용하세요. --speakers N을 전달하면 (화자 수를 알고 있을 때) 화자 분할이 눈에 띄게 개선됩니다.
표준 워크플로우
단계 1 — 입력 분석
항상 파일 정보를 얻는 것으로 시작하세요:
python3 $SCRIPT info input.mp4
이 명령은 길이, 해상도, 코덱, 파일 크기를 알려줍니다. 이 정보를 사용하여 출력 설정을 현명하게 결정하세요.
단계 2 — 작업 수행
적절한 명령어를 사용하세요. 복잡한 편집의 경우 여러 작업을 연결하세요 — 한 작업의 출력을 다음 작업의 입력으로 사용하세요.
단계 3 — 결과 확인
작업 후 출력을 검사하여 제대로 작동했는지 확인하세요:
python3 $SCRIPT info output.mp4
단계 4 — 결과 표시
Read 도구를 사용하여 이미지(썸네일, 프레임)를 표시하세요. 비디오의 경우 사용자에게 출력 경로와 파일 크기를 알려주세요.
원시 ffmpeg — 고급 작업용
헬퍼 스크립트가 지원하지 않는 경우 ffmpeg을 직접 사용하세요:
# Picture-in-picture
ffmpeg -y -i main.mp4 -i overlay.mp4 \
-filter_complex "[1:v]scale=320:-1[pip];[0:v][pip]overlay=W-w-10:H-h-10" \
-c:v libx264 -c:a copy output.mp4
# 좌우 비교
ffmpeg -y -i left.mp4 -i right.mp4 \
-filter_complex "[0:v]pad=iw*2:ih[bg];[bg][1:v]overlay=W/2:0" \
-c:v libx264 output.mp4
# 그리드/모자이크 (2x2)
ffmpeg -y -i a.mp4 -i b.mp4 -i c.mp4 -i d.mp4 \
-filter_complex "[0:v]scale=640:360[v0];[1:v]scale=640:360[v1];
[2:v]scale=640:360[v2];[3:v]scale=640:360[v3];
[v0][v1]hstack[top];[v2][v3]hstack[bot];[top][bot]vstack" \
-c:v libx264 grid.mp4
# 역재생
ffmpeg -y -i input.mp4 -vf reverse -af areverse reversed.mp4
# 특정 오디오 채널 추출
ffmpeg -y -i input.mp4 -af "pan=mono|c0=FL" left_channel.wav
# 잡음 제거
ffmpeg -y -i input.mp4 -af "afftdn=nf=-25" denoised.mp4
# 색상 보정 (밝기, 대비, 채도)
ffmpeg -y -i input.mp4 -vf "eq=brightness=0.1:contrast=1.2:saturation=1.3" corrected.mp4
# 크로마 키 (그린 스크린 제거)
ffmpeg -y -i greenscreen.mp4 -i background.mp4 \
-filter_complex "[0:v]chromakey=0x00FF00:0.3:0.1[fg];[1:v][fg]overlay" \
-c:v libx264 composited.mp4
# 이미지 시퀀스로 타임랩스 만들기
ffmpeg -y -framerate 30 -i frame_%04d.jpg -c:v libx264 -pix_fmt yuv420p timelapse.mp4
# 단일 이미지 + 오디오로 비디오 만들기
ffmpeg -y -loop 1 -i cover.jpg -i audio.mp3 -c:v libx264 -tune stillimage \
-c:a aac -shortest output.mp4
# 두 비디오 사이 크로스페이드 (1초)
ffmpeg -y -i first.mp4 -i second.mp4 \
-filter_complex "xfade=transition=fade:duration=1:offset=FIRST_DURATION_MINUS_1" \
-c:v libx264 crossfade.mp4
CRF 품질 가이드
| CRF | 품질 | 사용 사례 |
|---|---|---|
| 18 | 시각적 무손실 | 보관, 전문 편집 |
| 23 | 고품질 | 기본 ffmpeg, 대부분의 용도에 적합 |
| 28 | 좋은 품질 | 공유용 권장, 더 작은 파일 |
| 32 | 허용 가능 | 소셜 미디어, 적극적 압축 |
| 38+ | 낮은 품질 | 미리보기, 썸네일 |
CRF가 낮을수록 = 파일 크기가 크고 품질이 좋습니다. 6 증가할 때마다 파일 크기가 약 절반으로 줄어듭니다.
형식 빠른 참조
| 컨테이너 | 비디오 코덱 | 오디오 코덱 | 사용 사례 |
|---|---|---|---|
.mp4 | H.264 (libx264) | AAC | 범용 호환성 |
.webm | VP9 (libvpx-vp9) | Opus | 웹, 작은 파일 |
.mkv | H.265 (libx265) | Opus | 최대 압축 |
.mov | ProRes | PCM | 전문 편집 |
.gif | — | — | 애니메이션, 오디오 없음 |
오류 처리
- "No such file" — 입력 경로 확인, 절대 경로 사용
- "Unknown encoder" — 코덱이 컴파일되지 않음.
ffmpeg -encoders확인 - "Permission denied" — 출력 경로에 쓰기 권한 없음
- "Avi header too large" — 손상된 입력, 입력 앞에
-fflags +genpts시도 - Timeout — 비디오가 매우 김. 타임아웃 증가 또는
--preset ultrafast사용 - Out of memory — 먼저 해상도 줄인 후 처리