데모 영상 자막 삽입기은(는) 무엇을 하나요?

문제

화면 녹화된 제품 데모는 제품 자체와 무관한 세 가지 이유로 시청자에게 실패합니다. UI 텍스트가 잘못된 언어로 되어 있거나, 너무 작아서 읽기 어렵거나, 영상에 내레이션이 전혀 없는 경우(무음 녹화)입니다. 시청자는 클릭이 발생하는 것을 보지만 그 이유를 따라갈 수 없습니다. 자막이 이 문제를 해결합니다. 하지만 자막이 복잡한 UI 위에서 읽기 쉽도록 스타일링되고, 데모가 진행되는 부분을 가리지 않는 위치에 배치되며, 전환 중에 잘리지 않도록 시간이 맞춰져야만 합니다.

이 스킬은 전체 파이프라인을 제공하며, 특히 어렵게 경험을 통해 배워야 하는 비명백한 실패 모드까지 포함합니다.

사용 시기

"이 데모 영상에 자막을 추가해 줘" / "우리 한국 팀을 위해 이 녹화물에 캡션을 달아 줘"
내레이션이 없는 화면 녹화(.mp4, 오디오 스트림이 없거나 배경 음악만 있는 경우)로, 이야기를 캡션 텍스트 자체로 전달해야 하는 경우
영어 전용 제품 데모를 비영어권 청중에게 보여주는 경우
이미 자막이 있지만 하단 중앙에 위치하여 데모 패널을 가리고 있어 초점 추종 배치가 필요한 경우
비디오 위에서 이야기할 발표자를 위한 읽기 스크립트 생성(참고: "함께 사용")

다음과 같은 경우에는 이 스킬을 사용하지 마십시오: 합성 음성으로 더빙(TTS 파이프라인 해당)하거나, 플랫폼에 이미 존재하는 캡션을 추출하는 경우.

설치 (단일 명령어)

scripts/bootstrap.sh --dry-run          # 검사 전용: 정확히 무엇이 누락되었는지 출력
scripts/bootstrap.sh                    # 누락된 항목 설치 (한 번 질문)
scripts/bootstrap.sh --yes --lang ja    # 무인 설치; 일본어 폰트도 준비

bootstrap.sh는 멱등성(idempotent)을 가집니다. 이미 준비된 머신에서는 아무 작업도 하지 않습니다. 플랫폼을 감지하여 적절한 설치 프로그램(Homebrew / apt / dnf / pacman / winget / scoop)을 선택하고, 패키지 관리자가 없을 경우 정적 ffmpeg를 ~/.local/bin에 다운로드합니다. 캡션을 굽는 모든 세션의 첫 번째 작업으로 실행하십시오. 스킬에는 설치 시간 훅이 없으므로 이 스크립트가 설치 프로그램 역할을 합니다.

사전 요구 사항

먼저 내장 검사를 실행하여 머신을 검사하고 정확히 무엇이 누락되었는지 알려줍니다:

scripts/doctor.sh "Hiragino Sans GB"     # 사용하려는 CJK 폰트 패밀리를 전달

검사 항목과 누락 시 설치 명령어:

요구 사항	이유	설치 방법
libass가 포함된 `ffmpeg`	`.ass` 캡션 굽기 (`-vf ass=...`)	macOS `brew install ffmpeg`; Windows: gyan.dev full 빌드; Debian `apt install ffmpeg`
ffmpeg 빌드에 `--enable-fontconfig` 포함	폰트 패밀리 이름으로 폰트 해석; 없으면 자동 대체 폰트로 전환되어 조용히 실패	위와 동일한 빌드에 포함됨
시스템이 해석할 수 있는 CJK 폰트 패밀리	캡션 텍스트 자체	macOS: Hiragino Sans GB(기본 설치) · Windows: Microsoft YaHei(기본 설치) · Linux: `apt install fonts-noto-cjk`
`python3` (선택 사항)	`export_cues.py` 전용; 표준 라이브러리, pip 설치 필요 없음	macOS: `xcode-select --install`; Linux: `apt install python3`
`bash`, `zip` (선택 사항)	스크립트 및 배포 패키징	모든 곳에 기본 설치됨

Node, ImageMagick, pip 패키지, API 키가 필요하지 않습니다. 시각 인식 모델(에이전트 자체)이 프레임을 읽습니다. 이는 설치할 사항이 아닙니다.

문제를 일으키는 두 가지 환경 관련 주의사항:

ffmpeg를 PATH에 추가하거나 스크립트를 위해 위치를 내보냅니다: FFMPEG=/path/to/ffmpeg scripts/burn.sh ....
Windows: libass는 빌드에 따라 fontconfig/DirectWrite를 통해 폰트를 해석합니다. 캡션이 잘못된 서체로 렌더링되면 fontconfig를 설치하고 (scoop install fontconfig 또는 MSYS2) fc-match "Microsoft YaHei:bold"로 다시 확인합니다.

파이프라인

위에서 아래로 작업하십시오. 2단계를 건너뛰지 마십시오. 이후의 모든 단계는 UI 형상 정보에 의존합니다.

1단계 — 인벤토리 (2분)

scripts/probe.sh INPUT.mp4

기록: 지속 시간, 해상도, fps, 비트레이트, 오디오 스트림 존재 여부. 스크립트 내에서 오디오 검사를 실행합니다(평균 볼륨 + 무음 맵).

오디오 검사 결과에 따른 결정:

오디오 결과	자막 유형
오디오 스트림 없음	내레이션 자막 — 이야기를 직접 작성("무슨 일이 일어나고 있는가 / 왜 중요한가")
오디오는 있지만 음성 없음(음악만)	위와 동일. 10초 분량을 전사하여 확인: 큰 소리에서 비어 있거나 거의 비어 있는 결과를 반환하는 ASR 도구는 음성이 아닌 음악을 의미
음성 있음	대화 자막 — 먼저 타임스탬프와 함께 전사한 후 정리; 카피를 직접 만들지 않음

2단계 — 시각적 분석 및 형상 (사람들이 건너뛰는 단계)

2fps로 프레임 추출(60초 클립 → ~120 프레임; 먼저 모든 4번째 프레임을 검토하여 전체 흐름을 파악한 다음 텍스트에 집중):

scripts/split_frames.sh INPUT.mp4 frames/ 2

단일 캡션을 작성하기 전에 세 가지 아티팩트를 만듭니다:

비트 시트 — | 시간 | 화면 변경 사항 | 화면 내 텍스트 (원문) |. "비트"는 알림이 나타나거나, 패널이 슬라이드 인하거나, 버튼이 클릭되거나, 스크롤이 발생하거나, 페이지 전환이 일어나거나, 트랜지션이 발생하는 등 모든 변경 사항입니다. 전환 유형(흰색 플래시, 컷, 검정)을 기록하십시오. 캡션이 이를 넘어가서는 안 됩니다.
UI 텍스트, 원문, 소스 해상도에서 직접 읽음. 축소된 미리보기 프레임은 작은 UI 텍스트를 흐리게 만들어 잘못 전사하게 됩니다. 원본 파일에서 자르기: ffmpeg -i IN.mp4 -ss 12.5 -frames:v 1 -vf "crop=W:H:X:Y,scale=2*iw:-1" out.jpg (프레임 정확한 추출을 위해 -ss는 -i 뒤에; 함정 참조)
형상 맵 — "라이브" 패널(데모되는 대상)의 픽셀 경계를 소스 픽셀 단위로 측정합니다. 눈대중으로 하지 말고 직접 측정하십시오:
```
scripts/find_edge.sh INPUT.mp4 30 2880 300     # t=30s, x=2880에서부터 300px 너비 스트립 추출
```
그런 다음 반환된 스트립 이미지를 읽고 패널의 왼쪽 가장자리가 스트립 내 어디에 있는지 확인합니다. 그 오프셋을 스트립의 x에 더하여 절대적인 가장자리를 얻습니다. 레이아웃이 변경되는 경우(예: 채팅 패널이 나중에 열리는 경우) 다른 장면에 대해 반복합니다.

형상 맵에서 따라오는 규칙: 캡션은 데모 패널에 인접한 자유 영역에 위치하며, 절대 그 위에 위치하지 않습니다. 5단계 참조.

3단계 — 캡션 카피 작성

두 가지 규칙이 모든 것을 지배합니다:

큐당 하나의 아이디어. 최대 2~3개의 짧은 줄. 큐는 문장이지 단락이 아닙니다.
읽기 속도 예산. CJK: 초당 3.5~~5.5자가 편안함; 6자 이상은 어려움; 3자 미만은 지루함. 라틴: 초당 12~~18자. 계산하고 추측하지 마십시오. scripts/export_cues.py는 .ass 파일이 있으면 큐당 밀도를 출력합니다. 이 숫자를 기준으로 반복 개선하십시오.

큐 타이밍 규칙:

큐는 시각적 비트가 시작되는 순간에 시작하십시오. 알림이 1.0초에 슬라이드 인하면 큐는 1.0초에 시작합니다.
큐는 전환(흰색 플래시/컷) 전에 끝내고, 전환 양쪽에 최소 0.8초의 정적 시간을 남겨둡니다. 전환을 넘어가는 캡션은 결함으로 읽힙니다.
실제 간격을 남겨둡니다. 분당 3~5초의 빈 시간은 영상이 숨 쉴 수 있게 합니다. 벽면 가득한 캡션은 시청자를 지치게 합니다.
내레이션 자막의 경우, 캡션에 이유를 넣으십시오. 기계적인 설명이 아닙니다: "에이전트가 스스로 연락했다"가 "알림이 오른쪽 상단 모서리에 나타났다"보다 낫습니다.

여기서 멈추고 카피의 승인을 받으십시오. 텍스트 승인 → 스타일링. 스타일링 후 텍스트가 거부되면 아무것도 하지 않은 두 번째 렌더링이 발생합니다.

3b단계 — 캡션 언어 선택

파이프라인은 언어에 구애받지 않지만, 스타일링 전에 언어별로 세 가지를 결정해야 합니다.

1. 폰트 패밀리 — 플랫폼이 해석할 수 있는 폰트를 선택하십시오(scripts/doctor.sh <lang>으로 확인):

캡션 언어	macOS	Windows	Linux
중국어 (zh)	Hiragino Sans GB / PingFang SC	Microsoft YaHei	Noto Sans CJK SC
일본어 (ja)	Hiragino Sans	Yu Gothic / Meiryo	Noto Sans CJK JP
한국어 (ko)	Apple SD Gothic Neo	Malgun Gothic	Noto Sans CJK KR
라틴 (en/fr/de/es…)	Helvetica Neue	Segoe UI	Inter / DejaVu Sans

2. 읽기 속도 — 예산은 스크립트에 따라 다릅니다. scripts/export_cues.py가 자동으로 올바른 것을 선택하고(--lang으로 재정의) 초과하는 큐에 플래그를 지정합니다:

스크립트	편안함	너무 빠름으로 플래그
한자 / 가나 (zh, ja)	3.5–5.5 chars/s	> 6.0
한글 (ko)	4.0–6.0 chars/s	> 6.5
라틴	12–18 chars/s	> 19

3. 줄 바꿈 — 중국어와 일본어는 단어 사이에 공백이 없습니다: 구두점(U+FF0C, U+3001, U+3002, U+FF1A)에서 줄을 바꾸고 제품 이름은 절대 분할하지 마십시오. 한국어와 라틴은 공백에서 줄을 바꿉니다. 한국어 조사는 명사에 붙여 둡니다. 줄이 맞지 않으면 글꼴 크기를 줄이기 전에 다시 감싸십시오. 더 작은 서체는 추가 줄보다 가독성을 더 많이 떨어뜨립니다.

4. 스크립트별 줄 너비 — 글리프 너비는 스크립트마다 동일하지 않으므로 동일한 Fontsize가 다른 줄 길이를 제공합니다. 줄 예산을 floor(available_px / (fontsize * k))로 계산합니다. 여기서 k는 한자의 경우 대략 1.0, 한글과 가나의 경우 1.05–1.1(더 넓게 설정됨), 라틴의 경우 평균 0.5입니다(단어에 따라 다름).

4K에서 Fontsize 165로 측정: 한글 13자 ≈ 2,150px(2,450px 슬롯에서 안전), 반면 18자 ≈ 2,970px — 이는 오버플로우되어 줄이 프레임의 왼쪽 가장자리 밖으로 밀려납니다. 줄이 맞지 않으면 다시 감싸고, 맞추기 위해 글꼴 크기를 줄이지 마십시오.

이중 언어 캡션(원본 + 번역): 두 줄이 모두 짧은 경우에만 사용하십시오. 두 언어 줄은 읽기 부담을 두 배로 늘리고, 데모에서는 UI와 경쟁합니다. 클라이언트가 달리 요청하지 않는 한 파일 버전당 하나의 언어를 선호하십시오; 필요한 경우 원본을 위에, 번역을 아래에 쌓고, 전체 블록을 번역의 읽기 속도로 예산을 책정하십시오.

오른쪽에서 왼쪽 스크립트(아랍어, 히브리어): libass는 RTL을 지원하지만, 모양의 품질은 빌드의 harfbuzz에 따라 다릅니다. 커밋하기 전에 미리보기 프레임을 렌더링하십시오. 문자가 올바르게 결합되고 정렬 앵커가 여전히 의미가 있는지 확인하십시오.

글꼴 두께는 스크립트에 따라 다릅니다. 일본어와 한국어 폰트 패밀리는 일반적으로 동일한 Fontsize에서 중국어 폰트 패밀리보다 시각적으로 더 크게 렌더링됩니다. 하나의 미리보기 프레임으로 확인하고 규칙이 아닌 눈으로 조정하십시오.

4단계 — 스타일 (2레이어 글로우)

단일 ASS 스타일로는 "흰색 텍스트에 두꺼운 색상 외곽선과 부드러운 색상 할로우"를 생성할 수 없습니다. Outline은 하나의 링만 그립니다. 두 레이어에 큐당 두 개의 이벤트를 사용하십시오:

레이어	채우기	외곽선	블러	목적
0	투명 (`&HFF000000`)	넓고 반투명 보라색	`\blur` 20–30	할로우
1	흰색	좁고 단색 보라색	없음 / `\blur1`	읽을 수 있는 텍스트

시작점(assets/caption-template.ass 참조). 색상은 &HAABBGGRR 형식입니다. 알파 00은 불투명, FF는 완전 투명이며, 바이트 순서는 BGR입니다:

보라색 RGB(124,46,240)  →  &H00F02E7C
할로우, 35% 불투명     →  &H55F02E7C

취향이 아닌 PlayRes로 크기 조정: 4K 렌더링에서 fontsize 180 / outline 16 / halo 28 / blur 24를 사용했습니다. 1080p에서 동일한 모양은 80 / 7 / 12 / 12입니다. PlayResX/Y를 출력 해상도로 설정하고 ScaledBorderAndShadow: yes를 유지하십시오.

5단계 — 초점을 따르는 배치

데모에서 중앙 하단 배치는 잘못되었습니다. 하단은 일반적으로 UI이고 데모 패널은 항상 보여야 하는 유일한 것입니다. 각 큐를 표시되는 대상에 인접한 자유 영역에 고정하십시오:

이 큐의 초점	앵커	이유
사이드 패널/채팅 패널 열림	`\an6\pos(<panel_left - 40>, <panel_vertical_middle>)`	오른쪽 가장자리가 패널에 밀착, 블록이 왼쪽으로 성장, 너비 변경에 재계산 불필요
오른쪽 상단의 토스트/알림	`\an3\pos(<toast_right>, <toast_bottom + 80>)`	오른쪽 하단 앵커가 블록을 토스트 바로 아래에 배치
전체 너비 페이지, 패널 없음	`\an5\pos(<visual_center_x>, <y between two content blocks>)`	중앙 정렬이지만 측정된 간격에 배치됨 — 기하학적 중심이 아님
큰 내장 텍스트가 있는 타이틀 카드	`\an5\pos(center_x, BELOW the title)`	기하학적 중심이 비디오 자체 제목과 충돌

쓰기 전에 최대 줄 너비를 계산하십시오: max_line_px ≈ fontsize × characters. 줄이 자유 영역을 초과하면 다시 감싸십시오(단일 큐를 위해 글꼴을 절대 줄이지 마십시오) — 구두점에서 분할하고 제품 이름은 분할하지 않은 상태로 유지하십시오.

오른쪽 고정 블록의 경우, 평평한 배경에 수십 픽셀이 넘치는 것은 괜찮고 의도적인 것처럼 보입니다. 데모 패널 위로 넘치는 것은 안 됩니다.

앵커를 프레임 가장자리에서 멀리 유지하십시오. 외곽선과 할로우는 글리프 상자 바깥쪽으로 대략 outline + blur 픽셀만큼 확장됩니다(4K에서 outline 15 / blur 22인 경우 약 40px, 안티앨리어싱 포함). 따라서 오른쪽 가장자리에서 50px 떨어진 곳에 배치된 \an3 앵커는 할로우가 잘려서 깨진 단어처럼 읽힙니다. 앵커를 프레임 안쪽으로 최소 150px 이상 배치하고, 미리보기 프레임에서 결과를 확인하십시오. 클리핑은 .ass 파일에서는 보이지 않지만 화면에서는 명백합니다.

6단계 — 굽기

scripts/burn.sh INPUT.mp4 subs.ass OUT.mp4 [crf]

이것은 -i IN -vf "ass=subs.ass" -c:v libx264 -crf 17~18 -pix_fmt yuv420p -movflags +faststart이며, 원본 오디오 트랙을 유지합니다. 하드 서브타이틀은 데모에 적합한 기본값입니다. 모든 플레이어, 업로드 및 화면 공유에서 살아남습니다. 요청이 있을 경우에만 .ass/.srt를 함께 제공하십시오.

7단계 — 검증

먼저 저렴한 스틸을 렌더링한 다음 인코딩된 파일을 확인하십시오:

scripts/preview_frame.sh INPUT.mp4 subs.ass 16.0 /tmp/check1.jpg

각 프레임을 확인하십시오: 데모 패널 위의 텍스트, 프레임 밖의 텍스트, 예상치 못한 줄 바꿈, 끝났어야 할 큐, 밝은 배경 위에서 진흙이 된 할로우. 그런 다음 완성된 파일에서 3개의 프레임을 다시 추출하고(자막이 굽혀져 있으며 품질이 최종) 다시 확인하십시오.

함정 (각각 발견하는 데 실제 시간이 소요됨)

-ss를 -i 앞에 배치하면 ass 필터가 무력화됩니다. 입력 시킹은 타임스탬프를 0으로 재설정하므로 필터는 모든 프레임에 대해 t≈0에서의 자막 상태를 렌더링합니다. 결과: 비디오에 자막이 전혀 없이 굽혀지고 ffmpeg는 오류를 출력하지 않습니다. 항상 -ss를 -i 뒤에(출력 시킹) 배치하거나 -copyts를 추가하십시오. 번들 스크립트는 이미 이렇게 합니다.
미리보기 프레임 좌표는 거짓말을 합니다. 1280×720으로 축소되었지만 축소되지 않은 좌표로 표시되는 프레임은 UI 텍스트를 충분히 정밀하게 배치하지 못합니다. 항상 -ss를 -i 뒤에 배치하여 소스 해상도에서 자르고 추출하십시오. scripts/find_edge.sh는 이것을 자동으로 처리합니다.
단일 레이어 ASS는 글로우를 렌더링할 수 없습니다. Outline은 하나의 링만 그립니다. \blur를 추가하면 모든 것(텍스트 + 외곽선)이 흐려져 읽을 수 없게 됩니다. 할로우에 대한 투명 채우기와 가독성을 위한 단색 텍스트가 있는 두 번째 레이어를 사용하십시오. 이 스킬의 4단계에 템플릿이 있습니다.
장면 전환을 넘어가는 캡션은 결함처럼 보입니다. 뷰어는 전환 후 ½초 동안 잔상을 봅니다. 캡션이 전환 전에 끝나지 않으면 새로운 장면의 첫 번째 프레임에 겹쳐져서 마치 UI의 일부인 것처럼 보입니다(그렇지 않음). 항상 전환 앞에서 약 0.8초를 남겨두십시오. 이 스킬의 split_frames.sh는 이 작업에 도움이 되는 타임라인을 덤프합니다.
선택하지 않은 폰트 패밀리로 폰트가 대체되는 것은 조용히 발생합니다. scripts/doctor.sh는 폰트 해석이 성공했는지 알려주지만, 개발 중인 시스템(라이브러리가 설치되었지만 글꼴 파일이 없음)에서는 적절한 폰트가 설치되어 있어도 해석되지 않을 수 있습니다. fc-list | grep -i "<family>" 또는 macOS의 system_profiler SPFontsDataType을 사용하여 이중 확인하십시오.
ffmpeg는 알파가 있는 ASS를 지원하지 않습니다. scripts/burn.sh 템플릿은 ASS 스크립트의 알파 채널을 무시합니다. 투명도를 위해 미리 곱해진 알파가 있는 PNG 이미지와 같은 다른 방법이 필요하다면 다른 스킬입니다. 이 스킬은 단색 배경의 자막에 중점을 둡니다.

함께 사용

하나의 스킬은 일반적으로 전체 워크플로를 완료하지 않습니다. 다음은 이 스킬과 함께 사용되는 일반적인 동반 스킬입니다:

이 스킬…	이와 함께…	용도
데모 녹화 및 자막 삽입	이 스킬	하나의 원-샷 데모
데모 녹화, 자막 삽입 및 README 업데이트	`heavenchenggong/demo-video-subtitler` + `heavenchenggong/readme-updater`	새로운 기능에 대한 완전한 게시물

다른 스킬과 함께 사용하는 것이 아니라면, 일반적으로 이 스킬은 원-샷 데모 워크플로의 일부로 사용됩니다.

출력

파일	내용
`OUT.mp4`	자막이 굽혀진 최종 비디오
`subs.ass`	편집 가능한 자막 원본(재사용 또는 조정 가능)
`captions.txt`	동반 내레이션 스크립트용 읽기 가능한 캡션 카피
`frames/`	검사 및 자르기 좌표에 사용되는 추출된 프레임(정리가 필요하면 `rm -rf frames/`)

자주 묻는 질문 (FAQ)

Q: "이것은 [Cursor, Codex, Claude Code 등]에서 작동합니까?" A: 이 스킬은 모든 AI 에이전트 플랫폼에서 작동합니다. 스킬은 AI에게 수행할 단계를 알려주는 마크다운 문서일 뿐입니다. 이 특정 스킬은 파일을 읽고, 스크립트를 실행하고, 벌크 프레임을 검사하는 에이전트에 의존합니다. 파일 I/O, 터미널 액세스 및 시각적 프레임 읽기를 지원하는 모든 AI 에이전트가 이 스킬을 실행할 수 있습니다.

Q: "내 환경에서 실행할 수 있습니까?" A: 이 스킬은 macOS, Windows(WSL 포함) 및 Linux에서 작동합니다. 유일한 요구 사항은 ffmpeg(libass 포함)와 Bash입니다. scripts/bootstrap.sh가 설치를 처리합니다.

Q: "오디오가 있는 비디오는 어떻게 됩니까?" A: 스킬은 오디오 트랙을 그대로 유지합니다. 오디오에 음성이 포함된 경우 대화 자막을 생성합니다. 음성이 없는 경우(음악만) 내레이션 자막 옵션을 제공합니다.

Q: "더빙을 추가할 수 있습니까?" A: 이 스킬은 자막 전용입니다. TTS 더빙을 위해서는 다른 스킬이 필요합니다.

Q: "비용이 얼마나 듭니까?" A: 이 스킬은 모든 로컬 도구를 사용합니다. ffmpeg, Bash 스크립트, 그리고 에이전트 자체의 시각적 기능 외에는 비용이 들지 않습니다. API 키나 클라우드 비용이 없습니다.

Q: "이미지/아이콘과 같은 추가 자산은 어떻습니까?" A: 이 스킬은 텍스트 전용 자막에 중점을 둡니다. 타임라인에 아이콘 또는 이미지를 포함해야 하는 경우, scripts/burn.sh가 생성한 ASS 파일을 편집해야 합니다. 이는 이 스킬의 범위를 벗어납니다.

데모 영상 자막 삽입기