# Claude로 영상에 자막 넣기
id: video-subtitles · 종류: 워크플로 · 상태: 검수 대기 (사람 확인 전) · 주제: 글쓰기
주소: https://opencurrent.ai/w/video-subtitles
기준일: 2026-11-17 (여기서 고친 날)
도구: Claude Code, whisper.cpp, ffmpeg
써 본 모델: Claude Code (Fable 5.2) (2026-11), whisper.cpp 1.9.5 · large-v3-turbo-q5_0 (2026-11)
걸리는 시간: 약 15분
평가 점수: 32/100 (확인 없음 · 검수 대기)

영상 파일만 건네면 말소리를 받아 적어 자막을 만들고 영상에 입혀 주어, 직접 듣고 타이핑하는 일이 없어집니다.

달라진 점: 22초 한국어 영상의 말소리가 다섯 개의 두 줄 자막으로 정리돼 영상에 입혀짐. 받아쓰기 원본의 긴 자막과 틀린 표기 고쳐짐 (결과물로 확인)
- whisper.cpp의 역할: 영상의 말소리를 시간과 함께 받아 적기
- Claude Code의 역할: 명령 실행, 틀린 낱말 고치기, 문장 단위로 자막 묶기, 결과 장면 점검
- ffmpeg의 역할: 소리 뽑기, 자막을 영상에 입히기

결과물 (샘플 데이터로 실행 · OpenCurrent 편집 에이전트 (Claude Code) · macOS 음성 합성(say, 유나)으로 만든 22초 한국어 음성에 배경을 붙인 샘플 영상):
- 다듬은 자막: 파란 배경 영상 아래쪽에 '그다음 Claude Code가 틀린 낱말과 띄어쓰기를 고칩니다.' 자막이 두 줄로 입혀진 장면 (/results/video-subtitles/after-burned-captions.jpg)
- 다듬기 전: 같은 장면에 받아쓰기 원본을 그대로 입힌 모습. 세 문장이 한 자막에 묶여 화면 폭을 가득 채우고 'ffm팩'으로 잘못 적힘 (/results/video-subtitles/before-raw-captions.jpg)

설명: Claude Code에게 영상 파일을 알려 주면 내 컴퓨터에서 말소리를 받아 적어 자막 파일(SRT)을 만듭니다. Claude가 틀린 낱말을 고치고 문장 단위로 끊은 뒤, 자막을 입힌 새 영상과 자막 파일을 함께 돌려줍니다. 영상은 외부로 올라가지 않고 원본도 그대로 남습니다.

준비물: Claude Code를 쓸 수 있는 Mac · Homebrew (없으면 Claude Code에게 설치 요청) · 저장 공간 1GB 안팎 (받아쓰기 모델 파일 약 574MB 포함) · 말소리가 들어 있는 영상 파일 (mp4, mov 등)

입력값 (프롬프트의 {{이름}}에 넣는다):
- {{video_path}} 영상 파일 (필수) 예: ~/Movies/휴가 브이로그.mp4
- {{terms}} 자주 나오는 이름·용어 (선택) 예: Claude Code, ffmpeg, 오픈커런트

단계:
1. [AI에게 · Claude Code] 도구 세 가지 준비 — 영상이 있는 폴더에서 Claude Code를 열고 아래 요청 전달. 받아쓰기 도구(whisper.cpp), 자막을 입히는 ffmpeg, 받아쓰기 모델 파일을 한 번에 준비. 이미 있으면 건너뜀. 모델 내려받기는 처음 한 번
   프롬프트:
   > 영상에 자막을 넣을 준비를 해 줘.
   > 1. `whisper-cli`가 없으면 `brew install whisper-cpp`로 설치.
   > 2. `ffmpeg -filters | grep subtitles`로 subtitles 필터가 있는지 확인. 없으면 `brew install ffmpeg-full`로 설치하고, 앞으로 자막을 입힐 때는 `$(brew --prefix ffmpeg-full)/bin/ffmpeg`를 사용.
   > 3. 받아쓰기 모델이 없으면 내려받기: `mkdir -p ~/whisper-models && curl -L -o ~/whisper-models/ggml-large-v3-turbo-q5_0.bin https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo-q5_0.bin`
   > 끝나면 세 가지가 각각 어디에 있는지 한 줄씩 알려 줘. 설치 전에 무엇을 설치하는지 먼저 말해 줘.
   기대 결과: whisper-cli 위치, subtitles 필터가 있는 ffmpeg 위치, 모델 파일(약 574MB) 위치 세 줄
   확인 방법: `ls -la ~/whisper-models`에서 ggml-large-v3-turbo-q5_0.bin 크기가 574,041,195바이트인지 확인
2. [AI에게 · whisper.cpp] 말소리 받아 적기 — 영상에서 소리만 뽑아(16kHz 모노 WAV) 받아 적기. whisper-cli는 mp4를 바로 읽지 못해 WAV 변환이 먼저. `-ml 16 -sow`는 자막을 짧은 조각으로 끊어 조각마다 시간을 받는 옵션, `--prompt`는 틀리기 쉬운 낱말을 미리 알려 주는 자리
   프롬프트:
   > {{video_path}} 영상의 말소리를 받아 적어 줘. 원본 영상은 건드리지 말고 같은 폴더에 `subtitle-work` 폴더를 만들어 그 안에서 작업해.
   > 1. 소리 뽑기: `ffmpeg -y -i "{{video_path}}" -ar 16000 -ac 1 -c:a pcm_s16le subtitle-work/audio.wav`
   > 2. 받아 적기: `whisper-cli -m ~/whisper-models/ggml-large-v3-turbo-q5_0.bin -f subtitle-work/audio.wav -l ko -ml 16 -sow --prompt "{{terms}}" -osrt -of subtitle-work/pieces`
   > ({{terms}}가 비어 있으면 --prompt 옵션은 빼.)
   > 끝나면 subtitle-work/pieces.srt의 조각 수, 마지막 조각의 끝 시간, 영상 길이를 알려 줘.
   기대 결과: subtitle-work/pieces.srt 생성. 조각마다 시작·끝 시간과 짧은 글
   확인 방법: 마지막 조각의 끝 시간이 영상 길이와 비슷한지 확인. 크게 짧으면 뒷부분이 빠진 것
   결과 이름: {{raw_srt}} (뒤 단계에서 이어 쓴다)
3. [AI에게 · Claude Code] 자막 다듬기 — 받아 적은 조각을 Claude가 문장 단위 자막으로 다시 묶고 틀린 낱말을 고치는 단계. 시간은 새로 짓지 않고 조각의 시간을 그대로 이어 붙임
   프롬프트:
   > subtitle-work/pieces.srt를 읽고 보기 좋은 자막 subtitle-work/final.srt를 만들어 줘.
   > 기준:
   > - 문장이 끝나는 곳에서 자막을 끊기. 한 자막은 두 줄까지, 한 줄은 20자 안쪽, 뜻이 이어지는 곳에서 줄바꿈.
   > - 시간은 지어내지 말 것. 묶은 자막의 시작은 첫 조각의 시작 시간, 끝은 마지막 조각의 끝 시간 그대로.
   > - 한 자막이 7초를 넘으면 둘로 나누기.
   > - 잘못 받아 적은 낱말, 띄어쓰기, 문장부호 고치기. 다음 낱말은 이 표기로 통일: {{terms}}
   > - 말한 내용을 줄이거나 보태지 말 것. 무슨 말인지 확신이 없는 곳은 고치지 말고 따로 표시.
   > 끝나면 (1) 고친 낱말 목록을 '전 → 후'로, (2) 확신이 없는 곳을 시간과 함께 알려 줘.
   기대 결과: subtitle-work/final.srt 생성, 고친 낱말 목록, 확신 없는 곳 목록
   확인 방법: final.srt의 자막 번호가 1부터 이어지는지, 시간이 서로 겹치지 않는지 확인
   결과 이름: {{final_srt}} (뒤 단계에서 이어 쓴다)
4. [사람이] 이름·숫자 직접 확인 — Claude가 알려 준 '고친 낱말'과 '확신 없는 곳'을 훑어보기. 사람 이름, 제품 이름, 숫자, 금액은 해당 시간의 영상을 직접 들어 확인. 틀린 곳은 Claude에게 "3번 자막의 ○○을 △△로 고쳐 줘"처럼 요청
   기대 결과: 이름과 숫자가 맞는 final.srt
   확인 방법: 확신 없는 곳 목록의 항목을 모두 들어 봤는지 확인
5. [AI에게 · ffmpeg] 영상에 자막 입히기 — 자막을 영상에 구워 넣은 새 파일 만들기. 원본은 그대로. 글꼴 크기는 화면 방향에 따라 다름: 가로 영상은 22, 세로 영상(쇼츠·릴스)은 12가 두 줄에 맞는 크기
   프롬프트:
   > subtitle-work/final.srt를 {{video_path}} 영상에 입혀 줘. 원본은 덮어쓰지 말고 같은 폴더에 파일 이름 끝에 `-자막`을 붙여 저장.
   > 명령(1단계에서 찾은 subtitles 필터가 있는 ffmpeg 사용):
   > `ffmpeg -i "{{video_path}}" -vf "subtitles=subtitle-work/final.srt:force_style='FontName=Apple SD Gothic Neo,FontSize=22,Outline=1.5,Shadow=0,MarginV=28'" -c:v libx264 -crf 18 -c:a copy "출력 파일"`
   > - 영상이 세로면 FontSize=12, MarginV=40으로.
   > - 자막 파일 경로에 띄어쓰기나 한글이 있으면 경로를 작은따옴표로 감싸기.
   > - 실행 기록에 'Glyph ... not found'가 보이면 알려 줘.
   기대 결과: 자막이 입혀진 새 영상 파일. 길이는 원본과 같음
   확인 방법: `ffprobe`로 본 새 영상의 길이가 원본과 같은지 확인
6. [AI에게 · Claude Code] 자막이 보이는 장면 확인 — Claude가 자막이 나오는 장면을 그림으로 뽑아 직접 보고 점검. 그 뒤 사람이 영상을 처음·중간·끝 한 번씩 재생해 말과 자막이 맞는지 확인
   프롬프트:
   > 자막을 입힌 영상에서 첫 자막, 가운데 자막, 가장 긴 자막이 나오는 시간의 장면을 한 장씩 그림(png)으로 뽑아서 직접 열어 보고 점검해 줘.
   > - 한글이 네모(□)로 깨지지 않았는지
   > - 글자가 화면 좌우 밖으로 나가거나 세 줄 이상으로 늘어나지 않았는지
   > - 자막이 화면의 원래 글자나 얼굴을 가리지 않는지
   > 문제가 있으면 글꼴 크기나 줄바꿈을 고쳐 다시 입히고, 없으면 결과 영상과 final.srt의 위치를 알려 줘.
   기대 결과: 점검 결과 세 줄과 결과 파일 위치 (자막 입힌 영상, final.srt)
   확인 방법: 영상을 재생해 자막이 말보다 눈에 띄게 빠르거나 늦지 않은지 확인
7. [AI에게 · ffmpeg] 끌 수 있는 자막으로 받기 (선택) — 자막을 화면에 굽지 않고 켜고 끌 수 있는 자막으로 넣는 방법. 화질 손실 없이 바로 끝남. 유튜브에는 이 단계 없이 final.srt를 자막 파일로 올리는 길도 있음
   프롬프트:
   > {{video_path}} 영상에 subtitle-work/final.srt를 켜고 끌 수 있는 자막으로 넣어 줘. 다시 인코딩하지 말고 파일 이름 끝에 `-자막트랙`을 붙여 저장.
   > `ffmpeg -i "{{video_path}}" -i subtitle-work/final.srt -c copy -c:s mov_text -metadata:s:s:0 language=kor "출력 파일.mp4"`
   기대 결과: 자막 트랙이 들어간 mp4 파일
   확인 방법: `ffprobe`에서 subtitle 줄(mov_text)이 보이는지 확인

최종 결과 예시:
입력:
> video_path: sample.mp4 (22초, 1280x720, 한국어 음성)
> terms: Claude Code, ffmpeg, 유튜브
```
1
00:00:00,000 --> 00:00:04,640
안녕하세요. 오늘은 영상에
자막을 넣는 방법을 알아보겠습니다.

2
00:00:04,640 --> 00:00:08,500
먼저 영상에서 말소리를 받아 적어
자막 파일을 만듭니다.

3
00:00:08,500 --> 00:00:12,650
그다음 Claude Code가
틀린 낱말과 띄어쓰기를 고칩니다.

4
00:00:12,650 --> 00:00:16,730
마지막으로 ffmpeg로
자막을 영상에 입히면 끝입니다.

5
00:00:16,730 --> 00:00:21,260
자막 파일은 따로 저장되니
유튜브에 그대로 올릴 수도 있습니다.
```

주의:
- Homebrew의 기본 ffmpeg(9.0.2)에는 subtitles 필터가 없어 'Error parsing filterchain'으로 실패. ffmpeg-full을 따로 설치하고 그 안의 ffmpeg(`$(brew --prefix ffmpeg-full)/bin/ffmpeg`)로 실행
- whisper-cli에 mp4를 바로 넣으면 'input file(s) failed'. 16kHz 모노 WAV로 먼저 변환
- 모델 기본 설정으로 받아 적으면 자막 하나가 8~12초, 60자 넘게 묶여 화면 아래를 두 줄 가득 채움. `-ml 16 -sow`로 잘게 받은 뒤 문장 단위로 다시 묶기
- `-ml`만 쓰고 `-sow`를 빼면 낱말 중간에서 끊김(해 본 예: 'f / fm팩으로')
- `-ml` 값만 키워 길이를 맞추면 다음 문장의 첫 낱말('먼저', '마지막으로')이 앞 자막 끝에 매달림. 문장 단위 묶기는 Claude 단계에서
- 작은 모델(base)은 한국어 오류가 많음(해 본 예: '안뇽하세요', '받아 저거', '들린 난말'). large-v3-turbo 계열 권장
- 영어 낱말을 한글 소리로 받아 적음(해 본 예: 'ffmpeg' → 'ffm팩', 'Claude Code' → '클로드 코드'). `--prompt`에 낱말을 넣으면 줄지만 다 고쳐지지 않으므로 다듬기 단계에서 표기 통일
- `--prompt`를 넣으면 다른 곳이 바뀌기도 함(해 본 예: '안녕하세요.'가 '안녕하세요?'로). 문장부호도 다듬기 단계에서 확인
- 글꼴을 지정하지 않으면 한글이 없는 Arial이 먼저 잡힘. Mac에서는 한글 글꼴로 자동 대체돼 깨지지 않았지만, 다른 환경에서는 네모로 나올 수 있어 FontName에 한글 글꼴 지정
- 가로 영상에 맞춘 FontSize=22를 세로 영상에 쓰면 글자가 너무 커져 네 줄로 늘어남. 세로 영상은 12 안팎
- AI가 고친 자막도 틀릴 수 있음. 사람 이름·숫자·금액은 사람이 직접 듣고 확인
- Mac(Apple Silicon)에서만 확인. Windows는 설치 명령과 글꼴 이름이 달라 Claude Code에게 환경에 맞게 바꿔 달라고 요청 필요

출처:
- whisper.cpp README (모델 내려받기, WAV 변환, --max-len) https://github.com/ggml-org/whisper.cpp/blob/master/README.md
- whisper.cpp 변환 모델 저장소 (Hugging Face) https://huggingface.co/ggerganov/whisper.cpp
- Homebrew ffmpeg-full (libass 포함 빌드) https://formulae.brew.sh/formula/ffmpeg-full
- How I subtitle videos with Claude Code (2026-07, Keanan Koppenhaver) https://claudecodeformarketers.com/blog/subtitle-videos-with-claude-code/
- 영상 자막 추출-교정-삽입 Claude Code 스킬 제작 후기 (지피터스) https://www.gpters.org/dev/post/creation-claude-code-skills-DvK8nqN3N1BdE8T