video-captioner — 애니메이션 자막 파이프라인
Whisper로 음성을 텍스트로 변환하고 단어별로 움직이는 애니메이션 자막을 비디오에 입힙니다. 색상 보정 기능은 없습니다. 시각적 개선이 필요하면 먼저 video-enhancer 스킬을 사용하세요.
파이프라인
입력 비디오 → Whisper 변환 → pycaps 자막 렌더링 → 자막이 입혀진 출력 비디오
자막 스타일
세 가지 옵션이 있습니다:
- 기본 (플래그 없음) — pycaps 내장 미니멀 스타일: 흰색 일반 텍스트, 효과 없음.
- 미래지향적 (번들 제공) —
--css scripts/futuristic.css— 금색/마젠타색 자막이 번갈아 나타나며 글로우 효과와 고정폭 글꼴을 사용합니다. 기술, 게임 또는 에너지 넘치는 콘텐츠에 적합합니다. - 사용자 정의 — 사용자가
--css /path/to/custom.css를 통해 CSS 파일 경로를 제공할 수 있습니다.
사용자가 자막 스타일을 언급하지 않았다면 기본 스타일, 미래지향적 스타일, 또는 사용자 정의 CSS 파일 중 무엇을 원하는지 물어보세요.
정적 자막
오디오를 변환하는 대신 특정 타임스탬프에 미리 정의된 텍스트를 추가하려면 --caption을 사용하세요:
--caption "시작-종료: 텍스트"
형식:
- 시간은
M:SS또는MM:SS형식을 사용합니다 (예:0:05= 5초,1:30= 90초) - 여러 자막:
--caption을 여러 번 사용하세요. - 정적 자막과 변환된 자막이 모두 제공되면 정적 자막이 우선합니다.
예시:
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hello world" \
--caption "0:10-0:20: This is a demo" \
--css scripts/futuristic.css
자막 스타일링
스타일링은 JSON 설정 파일을 통해 관리됩니다. 정적 자막을 사용할 때 스타일링이 자동으로 적용됩니다.
기본 스타일링
--style-config가 지정되지 않으면 config.default.json이 사용됩니다:
- 배경: 흰색 (
#FFFFFF) - 텍스트 색상: 파란색 (
#0066FF) - 글꼴:
auto—caption태그가 있는 사용 가능한 브랜드 글꼴을 먼저 사용하고, 없으면 Courier New로 대체합니다. - 패딩:
10px 15px - 여백:
0
스타일 설정 사용하기
설정 파일을 전달하여 스타일을 전환하세요:
# 다크 모드 스타일 사용
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hello" \
--style-config config.dark-mode.json
포함된 설정 파일:
config.default.json— 흰색 배경, 파란색 텍스트, Courier New (기본값)config.dark-mode.json— 어두운 배경, 흰색 텍스트, 더 큰 글꼴
사용자 정의 스타일 설정 만들기
config.default.json을 복사하여 수정하세요:
{
"caption_bg_color": "#000000",
"caption_color": "#FFFFFF",
"caption_font": "auto",
"caption_font_tag": "caption",
"caption_padding": "20px 30px",
"caption_margin": "10px",
"caption_font_size": 48
}
그런 다음 사용하세요:
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Text" \
--style-config my-custom-style.json
CLI 플래그로 설정 덮어쓰기
CLI 플래그는 설정 파일 값보다 우선합니다:
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hello" \
--style-config config.dark-mode.json \
--caption-color "#00FF00" # 설정 파일의 텍스트 색상 덮어쓰기
스타일 설정 참조
| 키 | 유형 | 설명 |
|---|---|---|
caption_bg_color | string | 배경색 (16진수 또는 CSS 색상 이름) |
caption_color | string | 텍스트 색상 (16진수 또는 CSS 색상 이름) |
caption_font | string | auto, 글꼴 패밀리, 또는 .ttf, .otf, .woff, .woff2 파일 경로 |
caption_font_tag | string 또는 null | brand-manager에서 선호할 브랜드 글꼴 태그 (caption, body, heading 등) |
caption_padding | string | CSS 패딩 (예: "10px 15px") |
caption_margin | string | CSS 여백 (예: "0") |
caption_font_size | integer 또는 null | 픽셀 단위 글꼴 크기 (null = 자동 크기 조정) |
사용 가능한 글꼴
시스템 글꼴을 이름으로 지정할 수 있습니다:
DejaVu Sans/DejaVu Sans Bold/DejaVu SerifLiberation Sans/Liberation MonoCourier NewUbuntu Mono- 모든 TTF 파일 경로:
/path/to/font.ttf
또는 skills/brand-manager/brand-assets/asset-manifest.json에서 브랜드 글꼴을 선택하세요.
caption_font가 auto이면, 스킬은 브랜드 매니페스트(또는 설정된 경우 CLAW_BRAND_ASSETS_DIR)를 읽고 caption_font_tag로 태그된 첫 번째 사용 가능한 글꼴을 사용합니다. 태그된 글꼴이 없으면 caption, body, heading, 또는 bold로 태그된 브랜드 글꼴을 시도한 후 Courier New로 대체합니다. 결정된 브랜드 글꼴이 파일 경로이면, 생성된 CSS에 @font-face 규칙이 포함되어 pycaps가 렌더링할 수 있습니다.
실행 방법
의존성 설치 (첫 실행 시에만):
cd "$SKILL_DIR" && uv sync
참고: 첫 번째 실행은 pycaps가 Whisper 음성 인식 모델을 다운로드하기 때문에 느릴 수 있습니다 (잠재적으로 몇 분). 시작하기 전에 이 점을 사용자에게 알리세요.
그런 다음 비디오를 처리하세요:
cd "$SKILL_DIR" && uv run python scripts/caption_service.py \
--input <입력/경로> \
--output <출력/경로> \
[--css scripts/futuristic.css]
일반적인 명령어
# 기본 미니멀 자막 (Whisper 변환)
uv run python scripts/caption_service.py --input ./input --output ./output
# 미래지향적 스타일
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--css scripts/futuristic.css
# 사용자 정의 CSS
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--css /path/to/my.css
# 정적 자막 (기본 스타일: 흰색 배경, 파란색 텍스트, Courier New)
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Subscribe for more" \
--caption "0:10-0:15: Follow us on Instagram"
# 정적 자막 (다크 모드 스타일)
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hello world" \
--caption "0:10-0:20: This is a demo" \
--style-config config.dark-mode.json
# 정적 자막 (사용자 정의 스타일 설정)
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Custom text" \
--style-config my-custom-style.json
# 정적 자막 (CLI 플래그 덮어쓰기)
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hello" \
--style-config config.dark-mode.json \
--caption-color "#00FF00"
# 감시 모드 (10초마다 새 비디오 확인)
uv run python scripts/caption_service.py --input ./input --output ./output --watch
실행 후
사용자에게 다음을 보고하세요:
- 성공적으로 처리된 비디오 수와 실패한 비디오 수.
- 출력 디렉토리의 전체 경로.
- 실패한 비디오가 있으면 해당 비디오 이름을 명시적으로 알리세요.
예외 상황
ffmpeg가 설치되지 않은 경우: 사용자에게 설치하라고 알리세요 (sudo pacman -S ffmpegon Arch/CachyOS,brew install ffmpegon macOS,sudo apt install ffmpegon Ubuntu)uv가 설치되지 않은 경우: https://docs.astral.sh/uv/getting-started/installation/ 로 안내하세요.- 입력 디렉토리가 비어 있는 경우: 조용히 종료하지 않고 명확하게 보고하세요.
- 첫 실행 시 Whisper 모델이 다운로드됩니다 (~140 MB for
tiny, ~1.5 GB forlarge) — 이는 한 번만 발생합니다.
원격 변환
이 스킬은 이제 pycaps 렌더링을 로컬에서 유지하면서 선택적 원격 변환을 지원합니다.
- 기본 동작은 완전히 로컬입니다: pycaps 내부의 Whisper 변환 + 로컬 렌더링
- 원격 모드는 변환 단계만 대체합니다.
- 자막 렌더링, 템플릿 및 CSS 처리는 로컬에 남아 있습니다.
지원되는 제공자
huggingfacereplicate
설정 / CLI 키
| 키 | 기본값 | 참고 |
|---|---|---|
transcription_provider | null | null은 로컬 Whisper-in-pycaps 흐름을 유지합니다 |
remote_model | null | 선택적 제공자별 변환 모델 덮어쓰기 |
hf_token_env | HF_TOKEN | HuggingFace 인증 환경 변수 이름 |
replicate_api_key_env | REPLICATE_API_TOKEN | Replicate 인증 환경 변수 이름 |
remote_timeout_seconds | 300 | 원격 호출 시간 제한 |
예시
# HuggingFace 원격 변환 + 로컬 pycaps 렌더링
export HF_TOKEN=hf_your_token
uv run python scripts/caption_service.py --input ./input --output ./output --transcription-provider huggingface
# Replicate 원격 변환 + 로컬 pycaps 렌더링
export REPLICATE_API_TOKEN=r8_your_token
uv run python scripts/caption_service.py --input ./input --output ./output --transcription-provider replicate --remote-model <replicate-model-slug>
참고
- 원격 인증/설정이 없어도 로컬 모드로의 자동 대체는 없습니다.
- 기존 로컬 CLI 사용법은 계속 유효합니다.
--transcription-provider를 설정하지 않으면 pycaps는 내장 Whisper 흐름을 계속 사용합니다.