글로벌 테크 허브시장 · 기술 · 실전 정보
개발2026.10.15

ffmpeg drawtext 자막이 갑자기 실패하는 이유: % 기호와 작은따옴표

사진 몇 장과 대본으로 짧은 영상을 자동으로 만드는 파이프라인을 운영하고 있습니다. 사진에 천천히 확대·이동하는 효과를 주고, 음성 합성으로 나레이션을 만들고, 화면 아래에 자막을 얹는 구조입니다. 자막은 별도 자막 파일 없이 ffmpeg의 drawtext 필터로 영상에 직접 새깁니다.

잘 돌던 파이프라인이 어떤 날은 멀쩡하고 어떤 날은 실패했습니다. 에러는 매번 비슷했습니다.

[Parsed_drawtext_0 @ ...] Stray % near '...'
Error initializing filter 'drawtext' with args '...'
Error reinitializing filters!
Failed to inject frame into filter network: Invalid argument

ffmpeg가 -22(Invalid argument)로 죽는 모습이라 처음엔 영상 파일이나 코덱 문제인 줄 알았습니다. 원인은 자막 글자 자체였습니다.

함정 1: 자막에 % 가 들어가면 실패한다

drawtext는 자막 안에서 %{...} 형태의 확장 문법을 지원합니다. %{pts}로 현재 시간을, %{localtime}으로 시각을 찍는 식입니다. 그래서 자막에 그냥 %가 있으면 확장 문법이 시작되는 줄 알고 해석하려다 실패합니다.

대본을 AI가 쓰다 보니 “할인율 32%” 같은 문장이 자연스럽게 들어갔고, 그런 날만 실패했던 겁니다.

해결 방법은 두 가지입니다.

  • 대본에서 %를 “퍼센트”로 풀어 쓴다.
  • drawtext에 expansion=none을 줘서 확장 문법 자체를 끈다.

저는 뒤의 방법을 택했습니다. 대본 쪽에서 막으면 언젠가 또 새어 들어오고, 자막에 시간 같은 동적 값을 쓸 일이 없었기 때문입니다.

drawtext=fontfile=/fonts/NanumGothicBold.ttf:expansion=none:text='할인율 32%':...

함정 2: 작은따옴표는 \’ 로 이스케이프되지 않는다

두 번째는 타로 카드 영상을 만들 때였습니다. 대본에 '여사제' 카드가 나왔습니다처럼 카드 이름을 작은따옴표로 감싼 문장이 있었습니다. drawtext의 text 값은 작은따옴표로 감싸기 때문에 안의 따옴표를 처리해야 합니다. 보통 하듯이 \'로 바꿨는데도 똑같이 -22로 실패했습니다.

ffmpeg 필터그래프는 따옴표 안에서 백슬래시 이스케이프를 받지 않습니다. 작은따옴표로 감싼 구간 안에서는 모든 문자가 그대로 취급되기 때문에, 따옴표를 닫고, 이스케이프한 따옴표를 넣고, 다시 여는 방식을 써야 합니다.

시도 변환 결과 결과
그대로 text=''여사제' 카드' 실패
백슬래시 text='\'여사제\' 카드' 실패
닫고-넣고-열기 text=''\''여사제'\'' 카드' 성공

파이썬 코드로는 한 줄입니다.

def esc_drawtext(s: str) -> str:
    return s.replace("'", "'\\''")

필터 문자열에서는 :와 \도 특별한 의미가 있어서, 자막에 콜론이 들어갈 수 있다면 따로 이스케이프해야 합니다. 저는 자막을 파이썬에서 만들 때 이 함수 하나로 모아서 처리합니다.

덤: 자막을 억지로 두 줄에 맞추지 말 것

처음에는 자막이 길면 두 줄까지만 보여주고 나머지는 “…”로 잘랐습니다. 화면이 깔끔해 보여서요. 그런데 나레이션은 문장을 끝까지 읽는데 자막은 중간에 끊기니, 보는 사람 입장에서는 소리와 글자가 안 맞는 영상이 됐습니다. 지금은 긴 문장을 여러 자막 조각으로 나눠서 나레이션 길이에 맞춰 차례로 보여줍니다.

같이 겪은 성능 문제

이건 drawtext와는 별개지만 같은 파이프라인에서 겪은 일입니다. 영상 한 편은 여러 장면으로 나뉘고, 장면마다 배경 사진을 씁니다. 사진이 한두 장뿐인 경우 같은 사진을 여러 장면에서 반복해 쓰는데, 처음엔 장면마다 사진을 새로 내려받게 짜여 있었습니다. 사진을 주는 외부 서버가 느린 날에는 렌더링 전체가 그만큼 느려졌습니다. URL 기준으로 한 번 받은 사진을 캐시하도록 바꾸니 해결됐습니다. 같은 사진만 반복되면 지루하니, 장면 번호에 따라 확대·이동 구도를 다섯 가지로 돌려가며 쓰게 했습니다.

정리

  • Stray % 에러 → expansion=none
  • 작은따옴표 → '를 '\''로 치환
  • -22 Invalid argument가 뜨면 영상 파일보다 필터 문자열을 먼저 의심

자막 텍스트를 사람이 직접 쓸 때는 잘 안 겪는 문제입니다. AI나 외부 데이터가 만든 텍스트를 그대로 넣는 자동화라면, 어떤 문자가 들어올지 모른다는 전제로 이스케이프를 한곳에서 처리해두는 게 안전합니다. drawtext 옵션 전체는 ffmpeg 필터 문서에 있고, 따옴표 규칙은 같은 문서의 “Notes on filtergraph escaping” 부분에 설명돼 있습니다.