Communitygithub.com

ffmpeg-captions-subtitles

FFmpeg 7.1 LTS 및 8.0.1(최신 안정 버전)을 위한 완벽한 자막 및 캡션 시스템입니다. 자막 하드코딩, 소프트 자막 트랙 추가, 자막 추출, 형식 변환, 스타일 캡션, CEA-608/708 폐쇄 캡션, drawtext 텍스트 오버레이, Whisper AI 자동 전사 및 배치 처리를 지원합니다.

ffmpeg-captions-subtitles란 무엇인가요?

이 스킬은 FFmpeg를 사용한 자막 및 캡션 작업의 모든 측면을 다루는 완전한 가이드입니다. 개발자와 AI 에이전트 사용자는 이 스킬을 통해 SRT, ASS, WebVTT, CEA-608/708 등 다양한 자막 형식을 다루는 방법을 빠르게 찾을 수 있습니다. 자막 하드코딩(비디오에 자막을 영구적으로 입히기), 소프트 자막 트랙 추가, 자막 추출 및 형식 변환, ASS 스타일 매개변수를 이용한 글꼴, 색상, 윤곽선 및 그림자 설정 등의 고급 스타일링을 지원합니다. 또한 drawtext 필터를 사용한 동적 텍스트 오버레이와 Whisper AI를 이용한 자동 음성 전사(FFmpeg 8.0+ 필요) 기능을 제공합니다. 각 작업에 대한 즉시 사용 가능한 명령어 예제, 형식 참조 표, 스타일링 매개변수 가이드, 위치 정렬 차트, 배치 처리 스크립트 및 접근성 모범 사례를 포함하여 전문적인 캡션 제작을 보장합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Biel-developer/skills-videos/tree/HEAD/skills/ffmpeg-captions-subtitles

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

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

문서

중요 지침

Windows 파일 경로 요구 사항

필수: Windows에서 파일 경로에는 항상 백슬래시(\)를 사용해야 합니다.

Edit 또는 Write 도구를 Windows에서 사용할 때는 반드시 백슬래시(\)를 사용하고, 슬래시(/)는 사용하지 마십시오.

문서 지침

사용자가 명시적으로 요청하지 않는 한 새 문서 파일을 절대 생성하지 마십시오.


빠른 참조

작업명령어
SRT 하드코딩ffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4
ASS 하드코딩ffmpeg -i video.mp4 -vf "ass=subs.ass" output.mp4
소프트 자막 추가ffmpeg -i video.mp4 -i subs.srt -c copy -c:s mov_text output.mp4
자막 추출ffmpeg -i video.mkv -map 0:s:0 output.srt
스타일 지정 자막-vf "subtitles=s.srt:force_style='FontSize=24,PrimaryColour=&HFFFFFF'"
텍스트 오버레이-vf "drawtext=text='Hello':x=10:y=10:fontsize=24:fontcolor=white"
형식확장자최적 용도
SRT.srt단순, 범용
ASS.ass스타일 지정, 애니메이션, 애니메이션
VTT.vtt웹/HTML5 비디오

이 스킬을 사용해야 하는 경우

자막 및 캡션 작업에 사용하십시오.

  • 비디오에 자막 하드코딩(영구 입히기)
  • 컨테이너에 소프트 자막 트랙 추가
  • MKV/MP4에서 자막 추출
  • 캡션 스타일 지정(글꼴, 색상, 위치)
  • 동적 텍스트 오버레이

FFmpeg 자막 및 캡션 (2025)

FFmpeg를 사용하여 자막, 폐쇄 캡션 및 텍스트 오버레이를 작업하기 위한 완전한 가이드입니다.

자막 형식 참조

지원되는 형식

형식확장자기능사용 사례
SubRip.srt간단한 타임라인 + 텍스트범용, 웹
Advanced SubStation Alpha.ass/.ssa풍부한 스타일링, 위치 지정, 효과애니메이션, 스타일 자막
WebVTT.vtt웹 표준, 큐, 스타일링HTML5 비디오
TTML/DFXP.ttml/.dfxp방송, 접근성스트리밍 서비스
MOV Text.mov (내장)QuickTime 네이티브Apple 생태계
DVB Subtitle(내장)비트맵 기반유럽 방송
PGS.sup블루레이 비트맵 자막블루레이
CEA-608/708(내장)폐쇄 캡션미국 방송, 스트리밍

형식 특성

SRT (SubRip):
- 간단한 텍스트 기반 형식
- 기본 HTML 태그 지원 (<b>, <i>, <u>)
- 폭넓은 호환성
- 위치 지정 또는 고급 스타일링 없음

ASS/SSA:
- 고급 스타일링 (글꼴, 색상, 윤곽선)
- 화면 내 정밀 위치 지정
- 애니메이션 및 효과 지원
- 노래방 타이밍

WebVTT:
- HTML5 표준 형식
- CSS 유사 스타일링
- 위치 지정을 위한 큐 설정
- 화자 식별

자막 하드코딩 (Hardcoding)

기본 자막 입히기

# SRT 자막 입히기
ffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4

# ASS/SSA 자막 입히기 (스타일 유지)
ffmpeg -i video.mp4 -vf "ass=subs.ass" output.mp4

# MKV 컨테이너에서 자막 입히기
ffmpeg -i video.mkv -vf "subtitles=video.mkv" output.mp4

# 특정 자막 트랙 (인덱스 0)
ffmpeg -i video.mkv -vf "subtitles=video.mkv:si=0" output.mp4

# 스트림 인덱스로 자막 입히기
ffmpeg -i video.mkv -vf "subtitles=video.mkv:stream_index=1" output.mp4

스타일 지정 자막 입히기

# 스타일 강제 적용 (자막 스타일 재정의)
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='FontName=Arial,FontSize=24,PrimaryColour=&HFFFFFF,OutlineColour=&H000000,Outline=2,Shadow=1'" \
  output.mp4

# 검은색 윤곽선이 있는 노란색 자막
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='FontSize=28,PrimaryColour=&H00FFFF,OutlineColour=&H000000,Outline=3'" \
  output.mp4

# 접근성을 위한 더 큰 글꼴
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='FontSize=36,Bold=1'" \
  output.mp4

ASS 스타일 매개변수

매개변수설명예시
FontName글꼴 패밀리FontName=Arial
FontSize포인트 크기FontSize=24
PrimaryColour텍스트 색상 (AABBGGRR)PrimaryColour=&HFFFFFF
SecondaryColour노래방 색상SecondaryColour=&H00FFFF
OutlineColour윤곽선/테두리 색상OutlineColour=&H000000
BackColour그림자/배경 색상BackColour=&H80000000
Bold굵게 (0/1)Bold=1
Italic기울임꼴 (0/1)Italic=1
Underline밑줄 (0/1)Underline=1
Outline윤곽선 두께Outline=2
Shadow그림자 깊이Shadow=1
Alignment위치 (숫자패드 스타일)Alignment=2
MarginL/R/V픽셀 단위 여백MarginV=50

색상 형식 (ASS)

ASS는 &HAABBGGRR 형식을 사용합니다 (알파, 파랑, 초록, 빨강):
- 흰색: &HFFFFFF 또는 &H00FFFFFF
- 검정색: &H000000 또는 &H00000000
- 노란색: &H00FFFF (00-파랑, FF-초록, FF-빨강)
- 빨간색: &H0000FF
- 파란색: &HFF0000
- 50% 투명 검정: &H80000000

자막 트랙 추가하기 (소프트 자막)

SRT를 트랙으로 포함

# MP4에 SRT 추가 (MOV 텍스트)
ffmpeg -i video.mp4 -i subs.srt \
  -c copy -c:s mov_text \
  output.mp4

# MKV에 SRT 추가
ffmpeg -i video.mp4 -i subs.srt \
  -c copy -c:s srt \
  output.mkv

# WebM에 SRT 추가 (WebVTT)
ffmpeg -i video.webm -i subs.srt \
  -c copy -c:s webvtt \
  output.webm

여러 자막 트랙

# 여러 언어 추가
ffmpeg -i video.mp4 -i subs_en.srt -i subs_es.srt -i subs_fr.srt \
  -map 0:v -map 0:a -map 1 -map 2 -map 3 \
  -c copy -c:s mov_text \
  -metadata:s:s:0 language=eng -metadata:s:s:0 title="English" \
  -metadata:s:s:1 language=spa -metadata:s:s:1 title="Spanish" \
  -metadata:s:s:2 language=fra -metadata:s:s:2 title="French" \
  output.mp4

# MKV에 ASS 자막 추가 (스타일 유지)
ffmpeg -i video.mp4 -i styled.ass \
  -map 0 -map 1 \
  -c copy -c:s ass \
  output.mkv

기본 자막 트랙 설정

# 자막을 기본값으로 설정
ffmpeg -i video.mp4 -i subs.srt \
  -c copy -c:s mov_text \
  -disposition:s:0 default \
  output.mp4

# 강제 자막 설정 (항상 표시)
ffmpeg -i video.mp4 -i forced.srt \
  -c copy -c:s mov_text \
  -disposition:s:0 forced \
  output.mp4

자막 추출하기

외부 파일로 추출

# 첫 번째 자막 트랙을 SRT로 추출
ffmpeg -i video.mkv -map 0:s:0 output.srt

# 특정 자막 스트림 추출
ffmpeg -i video.mkv -map 0:s:1 output.srt

# ASS 형식으로 추출
ffmpeg -i video.mkv -map 0:s:0 output.ass

# WebVTT 형식으로 추출
ffmpeg -i video.mkv -map 0:s:0 output.vtt

# 모든 자막 트랙 추출
ffmpeg -i video.mkv -map 0:s subs_%d.srt

사용 가능한 자막 트랙 목록 보기

# 자막을 포함한 모든 스트림 표시
ffprobe -v error -show_entries stream=index,codec_name,codec_type:stream_tags=language,title \
  -of csv=p=0 video.mkv

# 자막 스트림만 표시
ffprobe -v error -select_streams s \
  -show_entries stream=index,codec_name:stream_tags=language,title \
  -of csv=p=0 video.mkv

자막 형식 변환

# SRT를 ASS로 변환
ffmpeg -i subs.srt subs.ass

# ASS를 SRT로 변환 (스타일 손실)
ffmpeg -i subs.ass subs.srt

# SRT를 WebVTT로 변환
ffmpeg -i subs.srt subs.vtt

# WebVTT를 SRT로 변환
ffmpeg -i subs.vtt subs.srt

drawtext 오버레이 및 Whisper AI 통합

drawtext 오버레이(글꼴, 위치 지정, 이스케이프, 시간 표현, 박스, 윤곽선, 애니메이션 텍스트) 및 Whisper AI 전사/자막 생성 워크플로우에 대한 자세한 예제는 references/drawtext-and-whisper.md에 있습니다. 입혀진 텍스트 그래픽을 만들거나 음성에서 자막을 생성할 때 해당 참조를 불러오십시오.

CEA-608/708 폐쇄 캡션

폐쇄 캡션 추출

# ATSC 스트림에서 CEA-608 캡션 추출
ffmpeg -f lavfi -i "movie=broadcast.ts[out0+subcc]" -map 0:1 captions.srt

# 내장 CC가 있는 비디오에서 추출
ffmpeg -i video_with_cc.mp4 \
  -filter_complex "[0:v]format=yuv420p[v];[0:v]crop=1:1:0:0[c]" \
  -map "[c]" -c:v libx264 -f null - 2>&1 | grep -A 1 "Closed caption"

CEA-608 캡션 추가

# CEA-608 캡션 포함 (eia608 라인 필요)
ffmpeg -i video.mp4 -i captions.scc \
  -c:v libx264 -c:a copy \
  -vf "movie=captions.scc[captions];[0:v][captions]overlay" \
  output.mp4

자막 위치 지정

ASS 정렬 값

7 (상단-왼쪽)     8 (상단-중앙)     9 (상단-오른쪽)
4 (중간-왼쪽)     5 (중간-중앙)     6 (중간-오른쪽)
1 (하단-왼쪽)     2 (하단-중앙)     3 (하단-오른쪽)

위치 예시

# 상단 중앙 자막
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='Alignment=8,MarginV=20'" \
  output.mp4

# 왼쪽 정렬 자막
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='Alignment=1,MarginL=50,MarginV=30'" \
  output.mp4

# 화자 식별을 위한 오른쪽
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:force_style='Alignment=3,MarginR=50'" \
  output.mp4

여러 자막 위치

# 두 개의 자막 트랙을 다른 위치에
ffmpeg -i video.mp4 \
  -vf "[in]subtitles=speaker1.srt:force_style='Alignment=1,MarginL=50'[tmp];\
       [tmp]subtitles=speaker2.srt:force_style='Alignment=3,MarginR=50'" \
  output.mp4

배치 처리

여러 비디오에 자막 입히기

#!/bin/bash
# burn_subs_batch.sh

for video in *.mp4; do
    base="${video%.mp4}"
    if [ -f "${base}.srt" ]; then
        ffmpeg -i "$video" \
          -vf "subtitles=${base}.srt:force_style='FontSize=24,Outline=2'" \
          -c:a copy \
          "output/${base}_subbed.mp4"
    fi
done

자막 형식 일괄 변환

#!/bin/bash
# convert_subs.sh

for srt in *.srt; do
    base="${srt%.srt}"
    ffmpeg -i "$srt" "${base}.vtt"
done

문제 해결

일반적인 문제

"적절한 출력 형식을 찾을 수 없습니다"

# 출력 형식 명시적으로 지정
ffmpeg -i video.mkv -map 0:s:0 -f srt output.srt

자막에 깨진 문자가 표시됨

# UTF-8 인코딩 강제
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:charenc=UTF-8" \
  output.mp4

글꼴을 찾을 수 없음

# 글꼴 디렉토리 지정
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:fontsdir=/path/to/fonts" \
  output.mp4

# 사용 가능한 글꼴 목록
fc-list : family | sort | uniq

자막 타이밍 오프셋

# 자막을 2초 지연
ffmpeg -i video.mp4 \
  -vf "subtitles=subs.srt:itsoffset=2" \
  output.mp4

# 또는 setpts를 사용하여 조정
ffmpeg -i subs.srt -itsoffset 2 delayed.srt

고해상도 비디오에서 자막이 표시되지 않음

# 자막 렌더링을 비디오 해상도에 맞게 조정
ffmpeg -i video_4k.mp4 \
  -vf "subtitles=subs.srt:force_style='FontSize=48,Outline=3'" \
  output.mp4

확인 명령어

# 자막이 있는지 확인
ffprobe -v error -select_streams s -show_entries stream=codec_name -of default=nw=1 video.mp4

# 자막 줄 수 세기
grep -c "^[0-9]" subs.srt

# SRT 형식 유효성 검사
ffmpeg -i subs.srt -f null -

모범 사례

접근성

  1. 대비가 높은 색상 사용 (어두운 배경에 흰색, 어두운 배경에 노란색)
  2. 표준 비디오의 경우 최소 글꼴 크기 24pt
  3. 여러 화자가 있는 경우 화자 식별 포함
  4. 중요한 시각적 콘텐츠를 가리지 않도록 자막 배치
  5. 줄 길이를 짧게 유지 (줄당 최대 42자)
  6. 표시 시간: 캡션당 최소 1초, 최대 7초

품질

  1. 스타일이 있는 자막(애니메이션, 뮤직 비디오)에는 ASS 형식 사용
  2. 간단한 대화에는 SRT 사용
  3. 웹 전달에는 WebVTT 사용
  4. 가능하면 원래 스타일 유지
  5. 배포 전 대상 기기에서 테스트

성능

  1. 필요한 경우(스트리밍, 호환성)에만 자막 입히기
  2. 보관 및 유연성을 위해 소프트 자막 선호
  3. 대용량 파일에 자막을 입힐 때 하드웨어 인코딩 사용
  4. 배치 작업 시 병렬 처리

이 가이드는 FFmpeg 자막 및 캡션 작업을 다룹니다. 도형 및 그래픽이 포함된 텍스트 오버레이에 대해서는 shapes-graphics 스킬을 참조하십시오.

관련 스킬