동영상에 자막 추가하기
사용자가 말하는 동영상을 제공합니다. 자막 스타일 카탈로그에서 선택하며, 각 스타일은 사용자의 동영상에 미리 보여지고, 최종적으로 자막이 포함된 MP4를 전달합니다. 모든 작업은 HyperFrames를 사용하여 로컬에서 실행됩니다. After Effects는 필요하지 않습니다.
도구: 스튜디오 저장소 내 .claude/skills/caption-video/kit/ 폴더에 있습니다. 프로젝트는 videos/captions/<이름>/에 생성되고 최종 동영상은 out/captions/<이름>.mp4에 저장됩니다(모두 스튜디오 루트 기준).
스튜디오 루트에서 K="$PWD/.claude/skills/caption-video/kit"를 설정하고 python3 "$K/caption.py" …를 실행합니다(경로는 따옴표로 묶으세요. 폴더에 공백이 있을 수 있습니다). 시스템 Python에 numpy/scipy가 없으면 스튜디오 가상 환경 Python(.venv/bin/python)을 사용하세요. setup/setup.sh가 생성합니다.
절차
1. 동영상 가져오기
동영상 경로가 주어지지 않으면 사용자에게 요청하세요. 동영상이 존재하고 말하는 사람이 있는지 확인하세요. 실행:
python3 "$K/caption.py" new "<동영상 경로>" <짧은-이름>
이 명령은 동영상을 복사하고 H.264로 다시 인코딩한 후 WhisperX로 단어 단위로 전사합니다. 오랜만에 처음 실행하면 1분 정도 걸릴 수 있습니다. 긴 동영상은 대략 실제 시간 ÷ 4 정도 소요됩니다.
2. 자막 보여주기
명령 출력에서 자막을 읽기 쉬운 블록으로 출력하세요. 특히 브랜드 이름과 전문 용어(제품명, "HyperFrames", 약어)에서 발생할 수 있는 오류를 지적하고 사용자에게 확인하거나 수정하도록 요청하세요. 수정 사항은 빌드 시 --fix "wrong=right,…"에 전달합니다. 자막이 횡설수설하거나 오디오에 음성이 없으면 중단하고 알리세요. 만들어진 단어에는 자막을 추가하지 마세요.
3. 모든 스타일을 사용자의 동영상에 보여주기
python3 "$K/caption.py" styles를 실행하여 목록을, python3 "$K/caption.py" preview <이름>을 실행하여 시각적 시트를 확인하세요. 시트는 videos/captions/<이름>/previews/styles.png에 있습니다. 직접 확인한 후 SendUserFile로 전송하세요(render 표시). 옆에 각 스타일의 "best for" 설명과 함께 번호 목록을 제공하세요:
- 라임 훅(Lime Hook): 템플릿 느낌(Anton 대문자, 라임 색상 말하는 단어)
- 노래방 팝(Karaoke Pop): 큰 2단어 버스트, 노란색 말하는 단어
- 한 단어(One Word): 한 번에 하나의 큰 단어
- 클린 박스(Clean Box): 흰색 카드 위의 어두운 텍스트, 말하는 단어에 하이라이터
- 에디토리얼(Editorial): 차분한 문장 케이스, 핵심 단어는 이탤릭 세리프
- 서브타이틀(Subtitle): 작은 전체 문장 자막
- 네온(Neon): 말하는 단어에 청록색 글로우
콘텐츠에 따라 한 줄로 하나를 추천하세요: 과장 또는 소셜 → 1 또는 2, 설명 또는 광고 → 4, 창업자 스토리 또는 프리미엄 → 5, 인터뷰 또는 팟캐스트 → 6, 기술 또는 AI → 7. 그런 다음 사용자에게 번호를 선택하도록 요청하세요. caption.py의 카탈로그가 변경된 경우 이 복사본 대신 styles가 출력하는 목록을 사용하세요.
4. 훅 (선택 사항)
화자가 실제로 말한 내용에서 3개의 훅을 제안하세요. 가장 놀라운 숫자, 결과 또는 모순으로 시작하고 4~8단어를 사용하며 페이오프는 하나의 큰 단어로 유지하세요. 각각을 훅 구문으로 포맷한 후 AskUserQuestion으로 질문하세요: 세 가지 훅 옵션과 "훅 없음"(사용자가 직접 입력할 수도 있음).
훅 구문은 |로 구분된 한 줄이며, 각 줄은 스타일로 시작합니다:
s:이탤릭 세리프 인트로 ("How", "Why")c:흰색 압축 대문자 설정b:큰 원형 페이오프 단어 또는 숫자 (1–2단어)l:라임 색상 대문자 트위스트r:작은 이탤릭 태그
예시: s:How|c:I reached|b:300k+|l:without ads|r:views. 훅은 동영상의 처음 10초 안에 전달하는 내용과 일치해야 합니다.
4b. 후반 작업 (제공하고, 사용자가 그레이딩, 더 깨끗한 오디오, 트리밍 또는 음악을 요청하면 실행)
python3 "$K/polish.py" <이름> [--grade clean|cinematic|none] [--music calm|none] [--music-level 1.0] [--denoise 100]
- 트리밍: 첫 단어 이전과 마지막 단어 이후의 무음 공간을 자릅니다(각각 0.3초와 0.9초 유지), 자막도 일치하도록 이동합니다.
- 그레이딩:
clean(기본값)은 따뜻하고 건강한 피부톤, 부드러운 대비와 부드러운 비네트를 제공합니다.cinematic은 더 깊고 차갑습니다. 선택하기 전에 각각의 한 프레임을 원본과 비교하여 확인하세요. - 음성: DeepFilterNet3 노이즈 제거(
~/.venvs/dfn, setup.sh로 생성됨, 전역에 설치하지 마세요. numpy<2 필요), 하이패스, 프레즌스 부스트, 디에서서, 부드러운 압축. - 음악: 합성된 차분한 피아노와 패드 배경. 레벨 1에서는 음성 일시 정지 시 약 20dB 아래, 말하는 동안 약 25dB 아래에 위치합니다. 더 조용하게 하려면
--music-level 0.6, 더 두드러지게 하려면1.5를 사용하세요. - 원본은
source_orig.mp4/transcript_orig.json으로 유지되므로 어떤 설정으로든 후반 작업을 다시 실행할 수 있습니다. 후반 작업 후build와render를 다시 실행하세요. - 시작 부분에서 더듬거나 잘못 시작한 부분("at the present, at the moment…")을 언급하세요. 자르면 작은 점프 컷이 발생하므로 실행하기 전에 확인하세요.
5. 빌드, 확인, 렌더링
python3 "$K/caption.py" build <이름> --style <키> [--hook "…"] [--hot "단어,단어"] [--fix "a=b"]
cd "videos/captions/<이름>" && npx --yes [email protected] check
python3 "$K/caption.py" render <이름>
--hot는 강조 색상으로 유지할 단어를 나열합니다. 2~5개의 페이오프 단어를 선택하세요. 숫자는 자동으로 hot 처리됩니다.check에서 훅 페이드 아웃 순간의 대비 경고는 예상된 것입니다. 렌더링 전에 실제 오류를 수정하세요.- 훅을 렌더링하기 전에 스냅샷을 찍고(
npx --yes [email protected] snapshot . --at 1.6 --no-end --describe false) 얼굴을 가리지 않는지 확인하세요. 얼굴이 프레임 상단에 있을 때(앉거나 미드샷),--hook-y 0.43으로 훅을 가슴 쪽으로 이동하세요. 그림자도 자동으로 따라갑니다. - 전송하기 전에
out/captions/<이름>.mp4에서 3~4프레임을 추출하여 확인하세요. 자막이 입이나 눈을 가리면 안 됩니다. 그런 경우--cap-y(높을수록 화면 아래쪽)로 다시 빌드하세요. - 옆으로 촬영된 영상(회전 메타데이터 없이 카메라를 옆으로 돌린 경우)은 연락처 시트에서 사람이 옆으로 누워 있는 것처럼 보입니다. 먼저
videos/_caption-inputs/로 회전(ffmpeg -vf transpose=2= 반시계 방향 90°,transpose=1= 시계 방향, 한 프레임 확인)한 후 해당 파일에 대해new를 실행하세요. - MP4를
SendUserFile로 보내고 경로를 링크로 제공하세요.
6. 수정
설정은 videos/captions/<이름>/caption.json에 유지되므로 수정은 build <이름> --<옵션> … 후 render <이름>을 실행하면 됩니다. 일반적인 요청:
- 다른 스타일:
--style. - 더 크거나 작게:
--size 1.2. - 더 높거나 낮게:
--cap-y 0.7. - 자막당 단어 수 줄이기:
--words 2. - 다른 색상:
--accent "#FF4D3D". - 훅 변경:
--hook;--hook ""는 제거합니다. - 훅 길이:
--hook-dur 3.5.
사용자는 cd videos/captions/<이름> && npm run dev를 사용하여 HyperFrames Studio에서 직접 열 수도 있습니다.
설정 정보 (문제 발생 시)
- 음성 인식은
HYPERFRAMES_ROOT=~/.hyperframes-root와 함께~/.claude/skills/embedded-captions/scripts/transcribe.cjs를 호출하며, HyperFrames CLI 0.8.147 설치와packages/cli/dist/cli.js심볼릭 링크가 필요합니다. 둘 중 하나라도 없으면 다시 설치하세요:npx hyperframes skills update embedded-captions, 그런 다음~/.hyperframes-root를 다시 빌드하세요([email protected]npm 설치 및node_modules/hyperframes/dist/cli.js를packages/cli/dist/cli.js로 심볼릭 링크). - 글꼴은
kit/fonts/에 있으며(모두 SIL OFL), 각 프로젝트로 복사됩니다. setup/doctor.sh가 모든 하위 요소를 확인하고setup/setup.sh가 복구합니다.- 사람 뒤에 오는 자막은
/embedded-captions워크플로우로 가능하지만 훨씬 느리고(10초당 약 4분)HYPERFRAMES_ROOT설정이 필요합니다. 요청 시에만 제공하세요.