{"id":"video-subtitles","kind":"workflow","example":{"input":"video_path: sample.mp4 (22초, 1280x720, 한국어 음성)\nterms: Claude Code, ffmpeg, 유튜브","output":"1\n00:00:00,000 --> 00:00:04,640\n안녕하세요. 오늘은 영상에\n자막을 넣는 방법을 알아보겠습니다.\n\n2\n00:00:04,640 --> 00:00:08,500\n먼저 영상에서 말소리를 받아 적어\n자막 파일을 만듭니다.\n\n3\n00:00:08,500 --> 00:00:12,650\n그다음 Claude Code가\n틀린 낱말과 띄어쓰기를 고칩니다.\n\n4\n00:00:12,650 --> 00:00:16,730\n마지막으로 ffmpeg로\n자막을 영상에 입히면 끝입니다.\n\n5\n00:00:16,730 --> 00:00:21,260\n자막 파일은 따로 저장되니\n유튜브에 그대로 올릴 수도 있습니다.","format":"text"},"testedWith":[{"model":"Claude Code (Fable 5.2)","at":"2026-11"},{"model":"whisper.cpp 1.9.5 · large-v3-turbo-q5_0","at":"2026-11"}],"durationMin":15,"url":"https://opencurrent.ai/w/video-subtitles","title":"Claude로 영상에 자막 넣기","summary":"영상 파일만 건네면 말소리를 받아 적어 자막을 만들고 영상에 입혀 주어, 직접 듣고 타이핑하는 일이 없어집니다.","category":"글쓰기","categoryId":"writing","domain":"content","domainLabel":"콘텐츠·미디어","capabilities":[{"id":"video","label":"영상 생성"},{"id":"audio","label":"음성·전사"}],"topics":[{"id":"writing","label":"글쓰기"}],"tools":["Claude Code","whisper.cpp","ffmpeg"],"whenToUse":"Claude Code에게 영상 파일을 알려 주면 내 컴퓨터에서 말소리를 받아 적어 자막 파일(SRT)을 만듭니다. Claude가 틀린 낱말을 고치고 문장 단위로 끊은 뒤, 자막을 입힌 새 영상과 자막 파일을 함께 돌려줍니다. 영상은 외부로 올라가지 않고 원본도 그대로 남습니다.","prerequisites":["Claude Code를 쓸 수 있는 Mac","Homebrew (없으면 Claude Code에게 설치 요청)","저장 공간 1GB 안팎 (받아쓰기 모델 파일 약 574MB 포함)","말소리가 들어 있는 영상 파일 (mp4, mov 등)"],"inputs":[{"name":"video_path","label":"영상 파일","description":"자막을 넣을 영상 파일의 위치","example":"~/Movies/휴가 브이로그.mp4","required":true},{"name":"terms","label":"자주 나오는 이름·용어","description":"영상에 나오는 사람 이름, 제품 이름, 전문 용어. 받아쓰기가 틀리기 쉬운 낱말","example":"Claude Code, ffmpeg, 오픈커런트","required":false}],"howToFollow":"1. 입력값(inputs)을 사용자에게 받아 프롬프트의 {{이름}} 자리에 넣을 것. 필수값이 없으면 먼저 물어볼 것.\n2. 단계를 순서대로 진행할 것. kind가 \"ai\"면 프롬프트를 실행하고, \"command\"면 사용자의 허락을 받고 명령을 실행하고, \"human\"이면 사용자에게 할 일을 안내하고 끝났는지 물을 것. tool이 있으면 그 도구·모델로 할 것.\n3. 단계에 output(결과 이름)이 있으면 그 단계 결과를 뒤 단계 프롬프트의 {{output}} 자리에 넣을 것.\n4. 단계마다 expected(기대 결과)와 check(확인 방법)로 제대로 됐는지 확인하고, 다르면 다음 단계로 넘어가지 말고 사용자에게 알릴 것. 끝나면 example.output(있으면)과 비교할 것.\n5. 검증 상태가 verified가 아니면 그 사실을 사용자에게 먼저 알릴 것. 답에 url을 출처로 밝힐 것.","steps":[{"n":1,"kind":"ai","title":"도구 세 가지 준비","body":"영상이 있는 폴더에서 Claude Code를 열고 아래 요청 전달. 받아쓰기 도구(whisper.cpp), 자막을 입히는 ffmpeg, 받아쓰기 모델 파일을 한 번에 준비. 이미 있으면 건너뜀. 모델 내려받기는 처음 한 번","prompt":"영상에 자막을 넣을 준비를 해 줘.\n1. `whisper-cli`가 없으면 `brew install whisper-cpp`로 설치.\n2. `ffmpeg -filters | grep subtitles`로 subtitles 필터가 있는지 확인. 없으면 `brew install ffmpeg-full`로 설치하고, 앞으로 자막을 입힐 때는 `$(brew --prefix ffmpeg-full)/bin/ffmpeg`를 사용.\n3. 받아쓰기 모델이 없으면 내려받기: `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`\n끝나면 세 가지가 각각 어디에 있는지 한 줄씩 알려 줘. 설치 전에 무엇을 설치하는지 먼저 말해 줘.","expected":"whisper-cli 위치, subtitles 필터가 있는 ffmpeg 위치, 모델 파일(약 574MB) 위치 세 줄","check":"`ls -la ~/whisper-models`에서 ggml-large-v3-turbo-q5_0.bin 크기가 574,041,195바이트인지 확인","tool":"Claude Code"},{"n":2,"kind":"ai","title":"말소리 받아 적기","body":"영상에서 소리만 뽑아(16kHz 모노 WAV) 받아 적기. whisper-cli는 mp4를 바로 읽지 못해 WAV 변환이 먼저. `-ml 16 -sow`는 자막을 짧은 조각으로 끊어 조각마다 시간을 받는 옵션, `--prompt`는 틀리기 쉬운 낱말을 미리 알려 주는 자리","prompt":"{{video_path}} 영상의 말소리를 받아 적어 줘. 원본 영상은 건드리지 말고 같은 폴더에 `subtitle-work` 폴더를 만들어 그 안에서 작업해.\n1. 소리 뽑기: `ffmpeg -y -i \"{{video_path}}\" -ar 16000 -ac 1 -c:a pcm_s16le subtitle-work/audio.wav`\n2. 받아 적기: `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`\n({{terms}}가 비어 있으면 --prompt 옵션은 빼.)\n끝나면 subtitle-work/pieces.srt의 조각 수, 마지막 조각의 끝 시간, 영상 길이를 알려 줘.","expected":"subtitle-work/pieces.srt 생성. 조각마다 시작·끝 시간과 짧은 글","check":"마지막 조각의 끝 시간이 영상 길이와 비슷한지 확인. 크게 짧으면 뒷부분이 빠진 것","tool":"whisper.cpp","output":"raw_srt"},{"n":3,"kind":"ai","title":"자막 다듬기","body":"받아 적은 조각을 Claude가 문장 단위 자막으로 다시 묶고 틀린 낱말을 고치는 단계. 시간은 새로 짓지 않고 조각의 시간을 그대로 이어 붙임","prompt":"subtitle-work/pieces.srt를 읽고 보기 좋은 자막 subtitle-work/final.srt를 만들어 줘.\n기준:\n- 문장이 끝나는 곳에서 자막을 끊기. 한 자막은 두 줄까지, 한 줄은 20자 안쪽, 뜻이 이어지는 곳에서 줄바꿈.\n- 시간은 지어내지 말 것. 묶은 자막의 시작은 첫 조각의 시작 시간, 끝은 마지막 조각의 끝 시간 그대로.\n- 한 자막이 7초를 넘으면 둘로 나누기.\n- 잘못 받아 적은 낱말, 띄어쓰기, 문장부호 고치기. 다음 낱말은 이 표기로 통일: {{terms}}\n- 말한 내용을 줄이거나 보태지 말 것. 무슨 말인지 확신이 없는 곳은 고치지 말고 따로 표시.\n끝나면 (1) 고친 낱말 목록을 '전 → 후'로, (2) 확신이 없는 곳을 시간과 함께 알려 줘.","expected":"subtitle-work/final.srt 생성, 고친 낱말 목록, 확신 없는 곳 목록","check":"final.srt의 자막 번호가 1부터 이어지는지, 시간이 서로 겹치지 않는지 확인","tool":"Claude Code","output":"final_srt"},{"n":4,"kind":"human","title":"이름·숫자 직접 확인","body":"Claude가 알려 준 '고친 낱말'과 '확신 없는 곳'을 훑어보기. 사람 이름, 제품 이름, 숫자, 금액은 해당 시간의 영상을 직접 들어 확인. 틀린 곳은 Claude에게 \"3번 자막의 ○○을 △△로 고쳐 줘\"처럼 요청","expected":"이름과 숫자가 맞는 final.srt","check":"확신 없는 곳 목록의 항목을 모두 들어 봤는지 확인"},{"n":5,"kind":"ai","title":"영상에 자막 입히기","body":"자막을 영상에 구워 넣은 새 파일 만들기. 원본은 그대로. 글꼴 크기는 화면 방향에 따라 다름: 가로 영상은 22, 세로 영상(쇼츠·릴스)은 12가 두 줄에 맞는 크기","prompt":"subtitle-work/final.srt를 {{video_path}} 영상에 입혀 줘. 원본은 덮어쓰지 말고 같은 폴더에 파일 이름 끝에 `-자막`을 붙여 저장.\n명령(1단계에서 찾은 subtitles 필터가 있는 ffmpeg 사용):\n`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 \"출력 파일\"`\n- 영상이 세로면 FontSize=12, MarginV=40으로.\n- 자막 파일 경로에 띄어쓰기나 한글이 있으면 경로를 작은따옴표로 감싸기.\n- 실행 기록에 'Glyph ... not found'가 보이면 알려 줘.","expected":"자막이 입혀진 새 영상 파일. 길이는 원본과 같음","check":"`ffprobe`로 본 새 영상의 길이가 원본과 같은지 확인","tool":"ffmpeg"},{"n":6,"kind":"ai","title":"자막이 보이는 장면 확인","body":"Claude가 자막이 나오는 장면을 그림으로 뽑아 직접 보고 점검. 그 뒤 사람이 영상을 처음·중간·끝 한 번씩 재생해 말과 자막이 맞는지 확인","prompt":"자막을 입힌 영상에서 첫 자막, 가운데 자막, 가장 긴 자막이 나오는 시간의 장면을 한 장씩 그림(png)으로 뽑아서 직접 열어 보고 점검해 줘.\n- 한글이 네모(□)로 깨지지 않았는지\n- 글자가 화면 좌우 밖으로 나가거나 세 줄 이상으로 늘어나지 않았는지\n- 자막이 화면의 원래 글자나 얼굴을 가리지 않는지\n문제가 있으면 글꼴 크기나 줄바꿈을 고쳐 다시 입히고, 없으면 결과 영상과 final.srt의 위치를 알려 줘.","expected":"점검 결과 세 줄과 결과 파일 위치 (자막 입힌 영상, final.srt)","check":"영상을 재생해 자막이 말보다 눈에 띄게 빠르거나 늦지 않은지 확인","tool":"Claude Code"},{"n":7,"kind":"ai","title":"끌 수 있는 자막으로 받기 (선택)","body":"자막을 화면에 굽지 않고 켜고 끌 수 있는 자막으로 넣는 방법. 화질 손실 없이 바로 끝남. 유튜브에는 이 단계 없이 final.srt를 자막 파일로 올리는 길도 있음","prompt":"{{video_path}} 영상에 subtitle-work/final.srt를 켜고 끌 수 있는 자막으로 넣어 줘. 다시 인코딩하지 말고 파일 이름 끝에 `-자막트랙`을 붙여 저장.\n`ffmpeg -i \"{{video_path}}\" -i subtitle-work/final.srt -c copy -c:s mov_text -metadata:s:s:0 language=kor \"출력 파일.mp4\"`","expected":"자막 트랙이 들어간 mp4 파일","check":"`ffprobe`에서 subtitle 줄(mov_text)이 보이는지 확인","tool":"ffmpeg"}],"pitfalls":["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에게 환경에 맞게 바꿔 달라고 요청 필요"],"sources":[{"title":"whisper.cpp README (모델 내려받기, WAV 변환, --max-len)","url":"https://github.com/ggml-org/whisper.cpp/blob/master/README.md"},{"title":"whisper.cpp 변환 모델 저장소 (Hugging Face)","url":"https://huggingface.co/ggerganov/whisper.cpp"},{"title":"Homebrew ffmpeg-full (libass 포함 빌드)","url":"https://formulae.brew.sh/formula/ffmpeg-full"},{"title":"How I subtitle videos with Claude Code (2026-07, Keanan Koppenhaver)","url":"https://claudecodeformarketers.com/blog/subtitle-videos-with-claude-code/"},{"title":"영상 자막 추출-교정-삽입 Claude Code 스킬 제작 후기 (지피터스)","url":"https://www.gpters.org/dev/post/creation-claude-code-skills-DvK8nqN3N1BdE8T"}],"verification":{"status":"pending","label":"검수 대기","detail":"사람 확인 전","verifiedBy":0,"lastVerifiedAt":null},"quality":{"score":32,"components":{"result":0.5,"trust":0,"freshness":0.4},"explanation":"확인 없음 · 검수 대기"},"workedFor":0,"trials":{"summary":"","lastAt":null,"total":0,"worked":0,"partial":0,"failed":0,"recent":[]},"asOf":{"date":"2026-11-17T10:00:00+00:00","basis":"updated"},"updatedAt":"2026-11-17T10:00:00+00:00","goals":[{"id":"writing","title":"글쓰기"}],"uses":17,"likes":0,"evidence":{"outcome":"22초 한국어 영상의 말소리가 다섯 개의 두 줄 자막으로 정리돼 영상에 입혀짐. 받아쓰기 원본의 긴 자막과 틀린 표기 고쳐짐","basis":"shown","basisLabel":"결과물로 확인","result":{"type":"images","images":[{"src":"/results/video-subtitles/after-burned-captions.jpg","alt":"파란 배경 영상 아래쪽에 '그다음 Claude Code가 틀린 낱말과 띄어쓰기를 고칩니다.' 자막이 두 줄로 입혀진 장면","label":"다듬은 자막"},{"src":"/results/video-subtitles/before-raw-captions.jpg","alt":"같은 장면에 받아쓰기 원본을 그대로 입힌 모습. 세 문장이 한 자막에 묶여 화면 폭을 가득 채우고 'ffm팩'으로 잘못 적힘","label":"다듬기 전"}]},"run":{"by":"OpenCurrent 편집 에이전트 (Claude Code)","input":"macOS 음성 합성(say, 유나)으로 만든 22초 한국어 음성에 배경을 붙인 샘플 영상","mode":"sample","modeLabel":"샘플 데이터로 실행"},"toolRoles":[{"tool":"whisper.cpp","role":"영상의 말소리를 시간과 함께 받아 적기"},{"tool":"Claude Code","role":"명령 실행, 틀린 낱말 고치기, 문장 단위로 자막 묶기, 결과 장면 점검"},{"tool":"ffmpeg","role":"소리 뽑기, 자막을 영상에 입히기"}]}}