---
name: opencurrent-video-subtitles
description: "영상 파일만 건네면 말소리를 받아 적어 자막을 만들고 영상에 입혀 주어, 직접 듣고 타이핑하는 일이 없어집니다. 이럴 때 사용: Claude Code에게 영상 파일을 알려 주면 내 컴퓨터에서 말소리를 받아 적어 자막 파일(SRT)을 만듭니다. Claude가 틀린 낱말을 고치고 문장 단위로 끊은 뒤, 자막을 입힌 새 영상과 자막 파일을 함께 돌려줍니다. 영상은 외부로 올라가지 않고 원본도 그대로 남습니다. 도구: Claude Code, whisper.cpp, ffmpeg."
metadata:
  source: "https://opencurrent.ai/w/video-subtitles"
  opencurrent-id: "video-subtitles"
  verification: "pending"
  exported-at: "2026-11-21T11:20:58.299Z"
---

# Claude로 영상에 자막 넣기

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

> OpenCurrent에서 사람들이 다듬는 워크플로. 원문: https://opencurrent.ai/w/video-subtitles
> 검증 상태: 검수 대기 (사람 확인 전). 내려받은 뒤에 바뀌었을 수 있으니, 가능하면 원문이나 MCP의 get_workflow("video-subtitles")로 최신 상태를 확인할 것.
> 주의: 검수 대기 상태. 사용자에게 이 사실을 알리고, 결과를 함께 확인하면서 진행할 것.

## 따라 하는 방법

1. 입력값(inputs)을 사용자에게 받아 프롬프트의 {{이름}} 자리에 넣을 것. 필수값이 없으면 먼저 물어볼 것.
2. 단계를 순서대로 진행할 것. kind가 "ai"면 프롬프트를 실행하고, "command"면 사용자의 허락을 받고 명령을 실행하고, "human"이면 사용자에게 할 일을 안내하고 끝났는지 물을 것. tool이 있으면 그 도구·모델로 할 것.
3. 단계에 output(결과 이름)이 있으면 그 단계 결과를 뒤 단계 프롬프트의 {{output}} 자리에 넣을 것.
4. 단계마다 expected(기대 결과)와 check(확인 방법)로 제대로 됐는지 확인하고, 다르면 다음 단계로 넘어가지 말고 사용자에게 알릴 것. 끝나면 example.output(있으면)과 비교할 것.
5. 검증 상태가 verified가 아니면 그 사실을 사용자에게 먼저 알릴 것. 답에 url을 출처로 밝힐 것.

## 언제 쓰나

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

## 준비물

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

## 입력값

시작하기 전에 사용자에게 받아서 프롬프트의 `{{이름}}` 자리에 넣을 것.

- `{{video_path}}` 영상 파일 (필수): 자막을 넣을 영상 파일의 위치
  - 예: ~/Movies/휴가 브이로그.mp4
- `{{terms}}` 자주 나오는 이름·용어 (선택): 영상에 나오는 사람 이름, 제품 이름, 전문 용어. 받아쓰기가 틀리기 쉬운 낱말
  - 예: Claude Code, ffmpeg, 오픈커런트

써 본 모델: Claude Code (Fable 5.2) (2026-11), whisper.cpp 1.9.5 · large-v3-turbo-q5_0 (2026-11)

## 단계

### 1. 도구 세 가지 준비 (AI에게 · Claude Code)

영상이 있는 폴더에서 Claude Code를 열고 아래 요청 전달. 받아쓰기 도구(whisper.cpp), 자막을 입히는 ffmpeg, 받아쓰기 모델 파일을 한 번에 준비. 이미 있으면 건너뜀. 모델 내려받기는 처음 한 번

프롬프트:

```text
영상에 자막을 넣을 준비를 해 줘.
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`는 틀리기 쉬운 낱말을 미리 알려 주는 자리

프롬프트:

```text
{{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가 문장 단위 자막으로 다시 묶고 틀린 낱말을 고치는 단계. 시간은 새로 짓지 않고 조각의 시간을 그대로 이어 붙임

프롬프트:

```text
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가 두 줄에 맞는 크기

프롬프트:

```text
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가 자막이 나오는 장면을 그림으로 뽑아 직접 보고 점검. 그 뒤 사람이 영상을 처음·중간·끝 한 번씩 재생해 말과 자막이 맞는지 확인

프롬프트:

```text
자막을 입힌 영상에서 첫 자막, 가운데 자막, 가장 긴 자막이 나오는 시간의 장면을 한 장씩 그림(png)으로 뽑아서 직접 열어 보고 점검해 줘.
- 한글이 네모(□)로 깨지지 않았는지
- 글자가 화면 좌우 밖으로 나가거나 세 줄 이상으로 늘어나지 않았는지
- 자막이 화면의 원래 글자나 얼굴을 가리지 않는지
문제가 있으면 글꼴 크기나 줄바꿈을 고쳐 다시 입히고, 없으면 결과 영상과 final.srt의 위치를 알려 줘.
```

기대 결과: 점검 결과 세 줄과 결과 파일 위치 (자막 입힌 영상, final.srt)

확인 방법: 영상을 재생해 자막이 말보다 눈에 띄게 빠르거나 늦지 않은지 확인

### 7. 끌 수 있는 자막으로 받기 (선택) (AI에게 · ffmpeg)

자막을 화면에 굽지 않고 켜고 끌 수 있는 자막으로 넣는 방법. 화질 손실 없이 바로 끝남. 유튜브에는 이 단계 없이 final.srt를 자막 파일로 올리는 길도 있음

프롬프트:

```text
{{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)이 보이는지 확인

## 최종 결과 예시

입력:

```text
video_path: sample.mp4 (22초, 1280x720, 한국어 음성)
terms: Claude Code, ffmpeg, 유튜브
```

```text
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)

## 끝나면

결과가 좋았거나 단계가 낡았으면 https://opencurrent.ai/w/video-subtitles 에서 알릴 것. 다음 사람이 더 정확한 방법을 쓸 수 있도록.
