넷 다 바라던 에러 메시지엔 안 나옵니다. 매번 제 버그처럼 보이다가, 밑에 깔린 ffmpeg 특유의 모서리를 찾고서야 풀렸습니다.
1. overlay엔 alpha= 옵션이 없다
배경 위로 레이어를 페이드인하고 싶었습니다. 당연한 추측 — overlay 필터의 alpha — 은 존재하지 않습니다. overlay는 합성만 하지, 입력의 불투명도를 소유하지 않습니다.
해결은 오버레이하기 전에 소스를 fade의 alpha 플래그로 페이드하는 것:
# 틀림: overlay엔 alpha= 없음
# [bg][fg]overlay=alpha=...
# 맞음: 소스의 alpha를 페이드한 뒤 오버레이
[fg]format=yuva420p,fade=t=in:st=0:d=0.4:alpha=1[fgf];
[bg][fgf]overlay필터 그래프에 없는 대칭을 있을 거라 넘겨짚고 한 시간 날렸습니다.
2. drawtext는 비ASCII·공백 폰트 경로에서 깨진다
다국어 자막을 위해 drawtext를 CJK 시스템 폰트로 겨눴습니다. 렌더에 실패했습니다 — 폰트 경로에 공백·비ASCII 문자가 있고, drawtext의 fontfile= 파싱이 이를 못 다룹니다.
해결: 폰트를 평범한 ASCII 이름 파일로 복사하고 drawtext가 그 복사본을 가리키게.
cp "/System/.../Hiragino Sans W4.ttc" ./fonts/hiragino_w4.ttc
# 그다음: drawtext=fontfile=./fonts/hiragino_w4.ttc:...그러면 일본어·한국어가 두부박스 대신 깔끔하게 렌더됩니다.
3. 시스템 ffmpeg가 조용히 망가져 있었다
렌더가 아무 쓸모 없는 방향을 가리키며 실패했습니다. 원인은 공유 라이브러리 soname 드리프트 — 시스템 ffmpeg가 더 이상 맞지 않는 라이브러리 버전에 링크된 채 남아 있었습니다. 제 파이프라인은 멀쩡했고, 바이너리 자체가 문제였습니다.
4. 최신 파이썬에선 static ffmpeg에 걸어라
#3의 반사적 해결은 "ffmpeg 재설치"지만, 흔한 static 빌드 미러가 제 네트워크에서 DNS 차단됐고, 아주 최신 파이썬(3.14)에선 미디어 관련 wheel의 프리빌트 바이너리가 늘 있진 않아 pip가 컴파일을 시도하다 실패합니다. imageio-ffmpeg 패키지로 검증된 static 바이너리를 당겨와 파이프라인이 그걸 가리키게 해서 전부 우회했습니다.
import imageio_ffmpeg
FFMPEG = imageio_ffmpeg.get_ffmpeg_exe() # 고정된 static 바이너리솔직한 부분
넷 중 셋은 애플리케이션 버그처럼 보였지만 실은 환경 또는 필터 그래프의 사실이었습니다. ffmpeg에서 계속 다시 배우는 교훈: 렌더가 이상하면 그래프를 디버깅하기 전에 내 그래프와 바이너리·그 입력을 분리하세요. static 바이너리를 고정하고, 폰트 경로를 ASCII로 정규화하고, 있을 거라 가정한 그 옵션을 필터 문서에서 확인하세요 — 절반은 없으니까요.