aminmzadev/ffmpeg-pipeline

ffmpeg-pipeline은(는) 무엇을 하나요?

접착 스킬입니다. 생성된 (또는 제공된) 정지 이미지를 내레이션이 포함된 움직이는 MP4로 변환하고, 에이전트가 자주 직면하는 일상적인 미디어 작업을 처리합니다.

ffmpeg + ffprobe가 필요합니다. 프롬프트 모드에는 anon-image가 필요하고, --narration에는 anon-audio가 필요합니다. 둘 다 형제 자원으로 자동 발견되며, --images / --audio를 직접 전달하면 선택 사항입니다.

명령

명령	설명
video	정지 이미지 (생성 또는 --images로 제공) → zoompan 모션 + 크로스페이드, 선택적 내레이션 및 배경 음악이 포함된 MP4
slideshow	기존 이미지 → MP4
mux	비디오에 오디오 트랙을 추가하고, 반복/패딩하여 길이 맞춤
frames	N초마다 정지 프레임 추출
sheet	콘택트 시트 (타임스탬프가 포함된 N개의 균등 간격 프레임)
gif	모든 구간에서 잘라낸, 팔레트 최적화 GIF
normalize	오디오를 −16 LUFS로 라우드니스 노멀라이제이션
speed	피치 변환 없이 오디오 속도 변경 (연결된 atempo)
info	한 줄 ffprobe 요약
probe	종속성 확인

빠른 시작

# 한 번의 호출로 전체 파이프라인: 생성된 3장의 사진, 각 4초, 내레이션 포함
vidkit.py video "일몰에 현무암 절벽 위의 등대, 영화처럼" -o story.mp4 \
  --shots 3 --seconds 4 --ratio 16:9 \
  --narration "차가운 해안 어딘가에서 등대가 경계를 지키고 있습니다." \
  --voice en-GB-RyanNeural

# 이미 가지고 있는 사진 재사용
vidkit.py video --images shots/ -o out.mp4 --seconds 3 --music bed.mp3

# 미디어 수술
vidkit.py mux clip.mp4 voiceover.mp3 -o final.mp4
vidkit.py sheet final.mp4 -o preview.jpg --cols 4 --count 8
vidkit.py gif final.mp4 -o teaser.gif --start 1 --dur 2.5 --width 480
vidkit.py normalize voiceover.mp3 -o clean.mp3
vidkit.py info final.mp4

시간 계산 (출력 예측 가능하도록)

N개의 샷이 각각 S초이고 크로스페이드가 0.8초인 경우:

지속 시간 = N*S - (N-1)*0.8

3 × 4 초 → 10.4 초. 내레이션이 그림보다 길면 비디오가 반복되어 커버합니다 (-stream_loop). 짧으면 오디오가 무음으로 패딩되어 끝이 잘리지 않습니다. 두 경우 모두 처리되므로 직접 -shortest를 추가하지 마세요.

결정 규칙

• 비율: YouTube/웹은 16:9, Shorts/Reels/TikTok은 9:16, 피드 및 썸네일은 1:1을 사용합니다. 모든 이미지는 커버 스케일링 후 크롭되므로 원본 이미지의 모양에 관계없이 레터박스 없이 표시됩니다.
• 샷당 초: 정지 이미지에는 3–4초가 적절합니다. 정적 이미지가 6초를 넘으면 정체된 느낌을 줍니다. 런타임이 더 필요하면 초 수를 늘리지 말고 샷 수를 늘리세요.
• 배경 음악: --music을 전달하면 음성이 12% 볼륨으로 믹스됩니다. 두 개의 큰 소리를 섞지 말고, 먼저 노멀라이즈하세요.
• GIF: 너비를 ≤ 480, 지속 시간을 ≤ 3초로 유지하지 않으면 파일이 채팅 제한을 초과할 수 있습니다.

실패 모드

증상	원인	해결책
missing dependency: ffmpeg	설치되지 않음	apt install ffmpeg (또는 brew install ffmpeg)
ffmpeg failed: … Invalid argument on zoompan	소스 크기가 홀수	필터가 이미 W*2로 스케일링합니다. 직접 편집했다면 짝수로 유지하세요.
출력이 무음	내레이션 파일이 없거나 비어 있음	경로를 확인하세요. --narration은 텍스트 또는 오디오 경로를 모두 허용합니다.
출력이 예상보다 훨씬 짧음	오디오가 비디오보다 짧고 누군가 -shortest를 추가함	제거하세요. vidkit.py가 대신 패딩합니다.
contact sheet needs Pillow	Pillow 없음	pip install pillow를 실행하거나 frames 명령과 직접 만든 시트를 사용하세요.

에이전트 참고 사항

• 사용자가 더 높은 해상도를 요청하지 않는 한 720p로 렌더링하세요. 4배 더 빠르며 노트북 화면에서는 아무도 차이를 알아채지 못합니다.
• 최종 결과물에 항상 info를 실행하고 실제 지속 시간, 해상도, 크기를 사용자에게 알려주세요. 이렇게 하면 조용한 실패를 잡을 수 있습니다.
• MP4 경로를 전달하세요. 임베드하지 마세요. 파일이 결과물입니다.