Communitygithub.com

shushuitie2017/claude-video

영상 전사 및 번역: 외국어 영상 → 중국어 자막 영상 + 중국어 문서. 전체 파이프라인 = 다운로드 → 로컬 Whisper 단어 수준 전사 → 번역 및 다듬기 → 자막 입히기(선택 사항: 이중 언어, 워터마크) → 마크다운 문서 출력.

claude-video란 무엇인가요?

이 스킬은 Claude Code에서 영상의 음성을 텍스트로 전사하고, 이를 중국어로 번역하여 자막이 포함된 영상과 마크다운 문서를 생성하는 완전 자동화 파이프라인을 제공합니다. 사용자가 '영상 번역', '자막 추가', '전사', '문서 생성' 등과 같은 특정 명령어를 입력하면, 스킬은 URL 또는 로컬 파일을 입력받아 자동으로 다운로드, 오디오 추출, Whisper 기반 단어 수준 전사, 번역 및 다듬기, 자막 입히기, 최종 문서 생성까지 전체 과정을 실행합니다. 특히 번역 파이프라인은 반드시 자막이 포함된 영상을 출력해야 하며, 문서만 생성하는 것은 허용되지 않습니다. 이 스킬은 Windows, macOS, Linux를 모두 지원하며, CLI 도구와 Python 스크립트로 구성되어 있어 사용자 환경에 맞게 유연하게 실행됩니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/shushuitie2017/claude-video/tree/HEAD/skills/video-translate

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

/video-translate — 영상 번역 및 전사

능력 및 의도 식별 (반드시 엄격히 준수)

  • 전사하여 문서 생성: 자막 또는 오디오 전사 → 마크다운 문서 출력 (자막이 있으면 우선, 빠르고 무료).
  • 영상 번역: 전사 → 번역 및 다듬기 → 중국어 자막 입히기 → 자막이 포함된 영상 파일 + 마크다운 문서 출력.

판단 규칙:

  • 사용자가 "전사", "텍스트로 변환", "문서 생성", "마크다운으로 변환"이라고 말할 경우 → 마크다운 문서만 생성 ("문서만 생성"流程).
  • 사용자가 "번역", "영상 번역", "자막 추가", "자막 넣기"라고 말할 경우 → 반드시 전체 번역 파이프라인을 실행 (오디오 추출 → Whisper 전사 SRT → 번역 및 다듬기 → 자막을 영상에 입히기 → 동시에 마크다운 생성), 문서만 출력하고 종료하면 안 됨.
  • 입력이 URL인 경우 → 먼저 다운로드 후 처리; 로컬 파일 경로인 경우 → 직접 처리.

Python 인터프리터: 이 스킬의 모든 명령은 Windows에서는 python을 사용합니다. macOS/Linux에서는 python3으로 바꿔주세요.

SKILL_DIR 파싱 (명령 실행 전에 먼저 수행)

SKILL_DIR을 방금 읽은 이 SKILL.md 파일이 있는 디렉토리의 절대 경로로 설정하고, 스크립트는 항상 SKILL_DIR/scripts/에 있습니다. 먼저 가드:

SKILL_DIR="<방금 읽은 SKILL.md 파일이 있는 디렉토리의 절대 경로>"
if [ ! -f "$SKILL_DIR/scripts/transcribe_srt.py" ]; then
  echo "ERROR: SKILL_DIR=$SKILL_DIR에서 스크립트를 찾을 수 없습니다" >&2
  exit 1
fi

단계 -1: 출력 루트 파싱 (⛔ 강제, 모든 것보다 먼저)

명령을 실행하거나 파일을 쓰기 전에, 먼저 설정을 읽어 output_dir을 <출력 루트>로 가져와야 합니다:

python -c "import sys; sys.path.insert(0, r'${SKILL_DIR}/scripts'); import config; c = config.load_translate_config(); config.ensure_output_root(c['output_dir']); print(c['output_dir'])"
  • 설정 파일은 ~/.config/video-skills/translate.json에 있습니다 (처음 실행 시 python "${SKILL_DIR}/scripts/setup.py"를 실행하여 템플릿 생성).
  • output_dir은 절대 경로이거나 ~로 시작해야 합니다. 누락되었거나 유효하지 않은 경우 위 명령이 오류를 출력합니다—즉시 중단하고, 사용자에게 해당 파일을 편집하여 절대 경로를 입력하도록 안내하며, 기본값을 자동으로 채워서 진행하지 마십시오.
  • 중간 산출물은 항상 <출력 루트>/tmp/에 쓰고, 최종 산출물(영상, 마크다운)은 <출력 루트>/data/에 씁니다.
  • ⛔ 문서의 모든 <출력 루트>/...는 실행 전에 실제 절대 경로로 대체되어야 합니다; 플레이스홀더를 그대로 명령에 포함시키지 마십시오 (현재 디렉토리에 기록되어 "임의 저장"으로 이어짐).
  • 사용자가 명시적으로 "절대 경로 출력 위치"를 제공하고 확인한 경우에만 사용자가 지정한 경로에 쓸 수 있습니다.

동시에 환경 사전 점검을 한 번 실행합니다 (/watch와 공유, 조용히 통과):

python "${SKILL_DIR}/scripts/setup.py" --check

실패 시 python "${SKILL_DIR}/scripts/setup.py"를 실행하여 의존성을 설치합니다 (ffmpeg/yt-dlp 자동 설치; 전사 엔진은 pip install faster-whisper). 더 자세한 설치 세부 사항은 오류 발생 시 references/설치 가이드.md를 참조하세요.

파이프라인 개요

입력 (URL / 로컬 파일)
   │
   ▼
단계 0  자막 유형 게이트 (번역 파이프라인은 먼저 확인해야 함: 중국어 / 이중 언어)
단계 1  다운로드 + 오디오 추출            → <출력 루트>/tmp/
단계 2  Whisper 단어 수준 전사로 원본 SRT 생성  → <출력 루트>/tmp/<이름>.srt
단계 3  번역 및 다듬기 (당신이 직접 수행, 8가지 규칙) → <이름>-zh.srt (이중 언어일 경우 항목당 두 줄 포함)
단계 4  자막 입히기 (+선택적 워터마크)        → <출력 루트>/data/<제목>-중국어자막.mp4
단계 4.5 프레임 캡처 확인 (≥2 프레임)
단계 5  마크다운 문서 생성          → <출력 루트>/data/

문서만 생성하는 시나리오는 단계 0/3/4를 건너뛰고 "문서만 생성" 섹션을 따릅니다.


단계 0: 자막 유형 확인 (⛔ 게이트, 번역 파이프라인은 반드시 먼저 실행)

  • 중국어 자막: 중국어 번역만 표시 (화면이 깔끔함).
  • 중국어-영어 이중 자막: 중국어 위 (큰 글꼴), 영어 아래 (작은 글꼴).

사용자가 대화에서 자막 유형을 명확히 지정한 경우 (직접 "중국어", "이중 언어", "중영", "bilingual" 등이라고 말한 경우) → 사용자 지정에 따라 실행. 그 외 모든 경우 → 반드시 AskUserQuestion을 사용하여 옵션을 표시해야 함:

AskUserQuestion(
  question="자막 유형 선택",
  options=["중국어 자막 (중국어만 표시)", "중국어-영어 이중 자막 (중국어 위, 영어 아래)"]
)

⛔ 우회 금지: ARGUMENTS에 포함된 자막 유형은 사용자 지정으로 간주하지 않음—오직 사용자가 대화에서 직접 말한 것만 유효합니다. 옵션을 표시하지 않고 단계 1을 시작하는 것은流程 오류입니다. translate.json의 subtitle_type은 기본값일 뿐이며, 사용자 확인을 대체할 수 없습니다.

단계 1: 다운로드 + 오디오 추출

URL 소스 (스크립트를 통일하여 사용—내장 브라우저 쿠키가 자동으로 fallback되어 YouTube 403/SABR/PO-token 및 Bilibili 로그인 장벽을 처리):

# 전체 영상 (번역 파이프라인은 자막을 입히기 위해 영상 본체 필요)
python "${SKILL_DIR}/scripts/download.py" "<영상URL>" "<출력 루트>/tmp/dl"
# 문서만 생성하고 입히지 않아도 되는 경우 → 오디오만, 더 빠름
python "${SKILL_DIR}/scripts/download.py" "<영상URL>" "<출력 루트>/tmp/dl" --audio
  • 스크립트는 JSON을 출력합니다 (video_path / subtitle_path / info.title).
  • 처음 시도는 쿠키 없이 진행; 산출물이 저장되지 않으면 자동으로 --cookies-from-browser chrome으로 재시도합니다. 일반적인 브라우저가 Chrome이 아닌 경우: --browser firefox / --browser edge를 추가하세요.
  • 여전히 실패하는 경우 (더 강력한 리스크 관리) → 사용자에게 프록시를 변경하도록 안내한 후 (--proxy http://127.0.0.1:7890) 재시도하도록 하고, 무한 재시도하지 마십시오.
  • 긴 영상 (>10분)의 경우 yt-dlp의 --download-sections를 사용하지 마십시오 (전체 영상을 먼저 다운로드한 후 자르므로 매우 느림); 전체 영상을 직접 다운로드하고, 필요한 부분만 ffmpeg -ss로 자릅니다.

오디오 추출 (로컬 파일 또는 다운로드된 영상 → mp3):

ffmpeg -y -i "<영상 파일>" -vn -acodec libmp3lame -q:a 2 "<출력 루트>/tmp/<파일명>.mp3"

단계 2: Whisper 단어 수준 전사로 원본 SRT 생성

⛔ 철칙: 자막을 입힐 원본 SRT는 오직 Whisper 단어 수준 전사로만 생성되어야 하며, 플랫폼 자동 자막(yt-dlp --write-auto-subs)을 시간 소스로 사용하는 것은 금지됩니다. 이유: YouTube 자동 자막은 롤링 오버레이 형식(각 항목이 이전 항목의 텍스트를 포함)이므로, 깨끗한 문장별 텍스트와 정확한 타임스탬프를 추출할 수 없어, 입히면 반드시 동기화가 맞지 않습니다. 단어 수준 타임스탬프가 유일하게 신뢰할 수 있는 시간 소스입니다.

python "${SKILL_DIR}/scripts/transcribe_srt.py" "<출력 루트>/tmp/<파일명>.mp3" \
  --output "<출력 루트>/tmp/<파일명>.srt"
# 언어를 잘못 감지하거나 다중 언어 트랙이 섞인 경우 강제 지정: --language en (또는 zh/ja/… 등) 추가
  • 기본 엔진 = 로컬 faster-whisper (단어 수준 타임스탬프, API 비용 없음, 처음 실행 시 자동으로 HuggingFace에서 모델 다운로드).
  • faster-whisper를 설치할 수 없는 경우 → GROQ_API_KEY/OPENAI_API_KEY를 설정하고 --engine api를 추가 (API 단어 수준 fallback, 로컬 경로와 동일한 문장 분할 로직 공유). API가 단어 수준 타임스탬프를 반환하지 않으면 스크립트는 세그먼트 수준으로 다운그레이드되고 stderr에 "자막 정밀도 저하"를 명시합니다—이 점을 사용자에게 전달하세요.
  • ⛔ 대화에서 Python 전사 코드를 직접 작성하지 마십시오—스크립트는 '문장+일시 중지'로 분할 (세그먼트를 기준으로 하고 6초 초과 시에만 단어로 분할 / 400ms 미만일 때만 병합)하므로, 스크립트를 우회하여 직접 탐욕적으로 분할하면 A문장 꼬리와 B문장 머리가 같은 프레임에 들어갈 수 있습니다 (실전에서 경험한 문제를 근본적으로 해결).
  • --max-line-ms는 단일 항목의 최대 시간을 제어합니다 (기본값 6000ms).
  • --pause-ms는 문장 분할 일시 중지 임계값을 제어합니다 (기본값 500ms).

단계 3: 번역 및 다듬기 (당신이 직접 수행—이것은 LLM 작업이며, 스크립트가 없습니다)

단계 2의 원본 SRT를 읽고, 항목별로 번역 및 다듬기를 수행하고, 다듬은 SRT를 <출력 루트>/tmp/<파일명>-zh.srt에 출력합니다. 당신의 역할: 전문 자막 편집자이며, 중국어 글쓰기, 구어체 복원 및 자막 형식 규범에 능숙합니다.

다듬기 8가지 규칙 (핵심)

  1. ASR 인식 오류 수정: 동음이의어/유사음 문자, 고유명사 철자 (예: Claude가 cloud로, MCP가 NCP로 인식됨), 숫자/약어/단위. 영상 화면을 참조하여 보조 판단 가능.
  2. 구두점 및 문어체화: 먼저 구두점을 완성하여 구어를 문어체로 변환 (화자의 어투 유지), 단, 최종 출력 자막 텍스트에서는 모든 구두점을 제거 (쉼표, 마침표, 물음표, 느낌표 모두 제거); 영어와 중국어 사이에 영어 공백 하나 추가 (예: 这是 Google 的产品).
  3. 중복 제거: 정보 가치가 없는 구어체, 반복, 감탄사 ("那个", "呃", "就是说")를 제거하고, 의미적 연속성을 유지하며 핵심 정보를 놓치지 않음. 약간의 중복은 허용하되, 의미를 잃지 않도록 함.
  4. 타임스탬프 정렬 (엄격): 원본 타임스탬프를 엄격히 유지하며, 임의로 이동하지 않음. 절대 수동으로 start time을 앞당기지 않음 (자막이 화자보다 앞서 표시됨). 초장시간 화면 표시 자르기: 한 항목의 시간 범위가 >6초이고 텍스트가 짧은 경우 = Whisper가 음성 후의 무음/BGM을 동일한 세그먼트로 계산한 것임, ffmpeg 무음 감지를 사용하여 음성 종료 지점을 정확히 찾고, 공식 추정을 사용하지 마십시오:
    ffmpeg -i <오디오> -ss <start> -to <end> -af silencedetect=n=-30dB:d=0.5 -f null - 2>&1 | grep silence_start
    
    첫 번째 silence_start (start 오프셋을 다시 추가)를 자른 후의 end로 사용; 전체 세그먼트에 소리가 있으면 자르지 않음. 한 항목이 >8초이고 텍스트가 긴 경우 여러 항목으로 분할 가능, 타임스탬프는 원래 범위 내에서 합리적으로 할당. 인접 항목 병합은 금지되며, 분할만 허용됨; 분할 후 다시 연속적으로 번호를 매김; 타임스탬프 중복 금지.
  5. 문장 분할 및 단락: 핵심 원칙 분할 가능, 병합 불가. 하나의 원본 항목은 하나의 번역 항목에 해당하며, 12자를 초과하면 의미적 중단점에서 두 항목으로 분할 (타임스탬프는 비율에 따라 할당). 단일 행을 주로 사용하며, 각 행은 ≤12자 중문 (공백 및 영어 포함)이고, 어조의 중단점에서 분할하며, 완전한 구절을 두 항목으로 나누지 않음. 여러 개의 짧은 항목으로 분할하는 것이 여러 행을 화면에 쌓는 것보다 나음.
  6. 고유명사: 인명/지명/회사/제품은 원본 유지 (첫 글자 대문자); 기술 용어는 영어 유지 (API, GPU, AI, ASR); 널리 알려진 브랜드는 번역하지 않음 (Google, iPhone, YouTube); 생소한 용어는 처음 나올 때 간단한 중국어 해설을 첨부할 수 있음.
  7. 언어 스타일: 현대 젊은이의 언어 사용 습관에 부합하며, 인터넷 용어/속어는 자연스럽고 현실감 있게 번역하고, 번역체를 피함 ("이것은 매우 흥미진진합니다" → "이거 진짜 멋져요"). 나레이션은 간결한 문어체를 사용하고, 대화/가사는 구어체 느낌을 유지.
  8. 가사: ♪로 감싸기 (♪ 가사 ♪), 의역과 운율에 중점을 두고 단어 단위 직역을 피하며, 나레이션과 번갈아 나올 때 시청자가 구분할 수 있도록 함.

출력 형식 (엄격한 SRT)

1
00:00:00,000 --> 00:00:03,500
첫 번째 자막 내용

2
00:00:03,500 --> 00:00:07,200
두 번째 자막 내용

번호는 1부터 연속; 타임스탬프 HH:MM:SS,mmm (쉼표로 밀리초 구분); 텍스트에 구두점 없음; 중영 간에 공백 있음; 항목 사이에 빈 줄; 파일 끝에 빈 줄.

이중 언어 모드 (사용자가 단계 0에서 이중 언어를 선택한 경우)

'이중 언어 SRT' 생성: 각 항목은 두 줄—중국어 위, 영어 (원본) 아래, 타임스탬프는 원본 SRT 문장과 완전히 정렬 (다시 분할하지 않고, 병합하지 않음; 원본이 어떻게 분할되었는지에 따라 중국어가 정렬됨). 중국어 행은 평소대로 구두점을 제거하고 용어를 규범화; 영어 행은 원본 유지 (ASR 인식 오류만 수정):

1
00:00:19,239 --> 00:00:21,239
大家好吗
Hello everyone, how are you?

긴 영상 (>10분) 분할 병렬 처리

자막 항목 수가 많을 때 분할하여 병렬 번역: 각 세그먼트는 약 500개 항목, developer가 병렬 하위 작업으로 번역하고, 번역이 완료되면 병합하여 번호를 다시 매깁니다. 병합 후 전역 검증: 타임스탬프 중복 및 점프 없음, 번호 연속, 의미 일관성, 형식 준수.

⛔ 파이프라인이 멈추지 않음: 다듬기가 완료되면 즉시 단계 4 (입히기)를 실행하고, 중간 보고서를 출력하지 않으며, 사용자 확인을 기다리지 않음. 전체 파이프라인은 최종 산출물 (영상 + 마크다운)이 모두 완료된 후에만 한 번 보고합니다.

단계 4: 자막 입히기 (+선택적 워터마크)

통일하여 burn.py 사용—수동으로 ffmpeg 명령을 조합하지 마십시오. 스크립트는 집중적으로 처리: Windows 경로의 필터 이스케이프 (C:\a.srt → 'C\:/a.srt', 수동으로 하면 10번 중 9번은 잘못됨), 오디오 강제 AAC 변환 (yt-dlp의 Opus 오디오 트랙은 X/WeChat/Weibo 업로드를 실패하게 만듦, ⛔ -c:a copy 금지), 워터마크 fontfile 파싱 및 시간 분포, 자막 + 워터마크 동일한 -vf로 한 번에 인코딩 (이차 화질 손실 방지).

중국어 단일 (SRT 직접 입히기):

python "${SKILL_DIR}/scripts/burn.py" "<영상 파일>" \
  --subs "<출력 루트>/tmp/<파일명>-zh.srt" \
  --output "<출력 루트>/data/<영상 제목>-중국어자막.mp4"

중국어-영어 이중 언어 (먼저 ASS로 변환한 후 입히기—⛔ 반드시 ASS 사용):

python "${SKILL_DIR}/scripts/bilingual_ass.py" "<출력 루트>/tmp/<파일명>-zh.srt" \
  --output "<출력 루트>/tmp/<파일명>-zh.ass" [--cn-size N] [--height 영상 높이]
python "${SKILL_DIR}/scripts/burn.py" "<영상 파일>" \
  --subs "<출력 루트>/tmp/<파일명>-zh.ass" \
  --output "<출력 루트>/data/<영상 제목>-중국어자막.mp4"
  • ⛔ 이중 언어에 ASS가 필요한 이유: subtitles 필터의 force_style FontSize는 전체 항목에 균일하게 적용되므로, 하나의 항목 안에서 중국어는 크고 영어는 작게 할 수 없습니다; SRT의 인라인 {\fsN}은 ffmpeg의 srt 디코더에 의해 제거됩니다 (실제 테스트에서 세 가지 글꼴 크기로 입혔을 때 md5가 모두 동일함). 오직 진정한 ASS를 libass에 공급해야만 하나의 항목 안에서 \N 줄바꿈 + 인라인 글꼴 크기 전환이 가능합니다. bilingual_ass.py가 바로 이것을 수행하므로, 수동으로 ASS를 작성하지 마십시오.
  • 글꼴 크기: 사용자가 대화에서 명확히 중국어 글꼴 크기를 지정한 경우 (예: "글꼴 크기 24") → --cn-size 24를 전달하고, 영어는 자동으로 중국어 / 1.7로 계산됨; 지정되지 않은 경우 → 스크립트가 해상도에 따라 기본값을 선택합니다. 중국어 : 영어 ≈ 1.7은 실제 테스트에서 깔끔한 대비 비율입니다.
  • ⛔ ASS FontSize/MarginV는 PlayResY=288에 대한 상대값이며 픽셀이 아닙니다. libass는 영상 해상도에 따라 자동으로 크기를 조정하므로, 해상도에 비례하여 글꼴 크기를 선형적으로 확대하지 마십시오 (1080p의 17에 2를 곱하여 4K로 가면 화면 절반을 차지함); 1080p에서 MarginV=N은 실제로 ≈ N×3.75px 밑에서부터의 거리 (MarginV=110 ≈ 화면 중앙, 110px가 아님)이므로, 픽셀 직관으로 조정하지 마십시오.

워터마크 (기본적으로 꺼져 있음; translate.json의 settings.watermark_enabled: true 또는 사용자 요청 시 켜짐):

python "${SKILL_DIR}/scripts/burn.py" "<영상 파일>" --subs <자막> \
  --watermark-text "<워터마크 텍스트>" --output <출력>

시간 분포는 시간에 따라 자동으로 분산 (<30분 3회 4초 / 30-60분 5회 5초 / >60분 15분마다 1회 10초; 처음과 끝 고정), 투명도 0.28, 0.5초 페이드 인/아웃, 왼쪽 위. 매개변수는 --watermark-opacity/--watermark-fontsize 등으로 재정의 가능; 대화에서 지정된 매개변수가 설정 파일보다 우선함.

원본 영상 하단에 이미 하드 자막이 있는 경우 회피: 새 자막은 위로 이동해야 하며, 원본 자막을 가리면 안 됨:

# 단일 행 하드 자막
python "${SKILL_DIR}/scripts/burn.py" <영상> --subs <자막> --avoid-hardsub single ...
# 두 행 또는 동적으로 변하는 행 (한 문장 1행, 한 문장 2행) → 두 행으로 회피; 1행 구간에서 중국어가 약간 더 높아지는 것은 허용 가능한 비용
python "${SKILL_DIR}/scripts/burn.py" <영상> --subs <자막> --avoid-hardsub double ...

회피 수준 (single=MarginV 42/FontSize 19, double=MarginV 60/FontSize 19)은 경험값이며, 프레임 캡처 검증이 통과되지 않으면 --margin-v ±3-5로 미세 조정하여 다시 입힙니다.

최종 명령이 확실하지 않으면 먼저 --dry-run으로 명령을 출력하여 검토한 후 실제로 실행합니다.

단계 4.5: 프레임 캡처 검증 (⛔ 필수, ≥2 프레임)

입힌 후 반드시 프레임을 캡처하여 Read로 확인: 자막이 완전히 표시되고, 기존 하드 자막을 가리지 않으며, 이중 언어 글꼴 크기 대비가 명확하고, 중국어에 깨짐(글꼴 누락)이 없는지 확인:

ffmpeg -y -i "<출력 영상>" -ss <시간점1> -vframes 1 "<출력 루트>/tmp/check1.jpg"
ffmpeg -y -i "<출력 영상>" -ss <시간점2> -vframes 1 "<출력 루트>/tmp/check2.jpg"

회피가 필요한 경우 두 프레임은 각각 원본 자막의 1행 및 2행 시점을 선택해야 하며, 두 프레임 모두 가리지 않아야 통과로 간주됨. 한 프레임만 보고 전달하는 것은 이미 경험한 함정입니다. 문제가 있으면 --margin-v/--font-size를 조정하여 다시 입히고 재검증합니다.

단계 5: 마크다운 문서 생성

일반 규칙 (모든 시나리오):

  • 전사 텍스트 읽기 (SRT에서 번호와 타임스탬프 행을 제거하거나, vtt_to_text.py로 정리한 텍스트), 원본 텍스트의 증감 및 수정을 엄격히 금지하며, 구두점 처리, 문장 병합, 단락 나누기만 수행합니다. 모든 내용을 포괄해야 하며, 누락이 있어서는 안 됨.
  • 중국어 내용: 짧은 문장 병합, 구두점 규범화, 의미에 따라 단락 나누기 → 1개 파일 <출력 루트>/data/<영상 제목>-중국어.md 출력. ⛔ 중국어 내용은 번역 규칙을 사용하는 것을 엄격히 금지합니다.
  • 비중국어 내용: 먼저 원본 언어로 <출력 루트>/data/<영상 제목>-원본.md 생성 (마찬가지로 증감 및 수정 금지), 그런 다음 references/심층 문서 규칙.md를 읽고 그 규칙에 따라 <출력 루트>/data/<영상 제목>-중국어.md를 생성 (심층 기사 형식, 문장 단위 직역 아님).
  • Front matter는 title, source_url만 포함합니다.

문서만 생성 시나리오 (사용자가 전사/문서만 원하고, 자막을 입히지 않음)

  1. 자막이 있는 영상은 자막을 우선 캡처 (무료이며 가장 빠름; ⛔ 문서 생성에만 해당—자막 입히기에는 이 경로를 사용할 수 없음, 단계 2 철칙 참조):
    python "${SKILL_DIR}/scripts/download.py" "<영상URL>" "<출력 루트>/tmp/dl" --captions-only
    python "${SKILL_DIR}/scripts/vtt_to_text.py" "<출력 루트>/tmp/dl/<자막>.vtt" --output "<출력 루트>/tmp/cleaned.txt"
    
    정리된 순수 텍스트는 토큰을 약 절반으로 절약합니다. cleaned.txt를 읽고 단계 5에 따라 문서를 생성합니다.
  2. 자막 없음 → 오디오 다운로드 (--audio) → transcribe_srt.py 전사 → SRT에서 번호와 타임스탬프를 제거하여 순수 텍스트 얻음 → 단계 5에 따라 문서 생성.

임시 파일 및 정리

  • 중간 산출물 (오디오, SRT, ASS, 캡처 프레임)은 모두 <출력 루트>/tmp/에 있으며, 처리 후 정리 가능; 최종 산출물은 <출력 루트>/data/에 있어 영향을 받지 않음.
  • 전사 SRT는 디버깅을 위해 보관 가능; 사용자는 언제든지 수동으로 tmp/를 비울 수 있음.

오류 처리

증상처리
다운로드 실패 (403/리스크 관리/로그인 장벽)스크립트가 이미 자동으로 쿠키 재시도; 여전히 실패하면 --browser firefox/edge로 변경하거나, 사용자에게 프록시 설정을 권장; 지역 잠금/유료 콘텐츠로 확인되면 바로 알림
faster-whisper가 설치되지 않음pip install faster-whisper; 설치할 수 없으면 --engine api 사용 (API 키 필요)
전사 언어 잘못 감지--language en (또는 해당 언어)을 추가하여 강제 재전사
입힌 후 중국어가 깨짐글꼴 누락—burn.py는 기본적으로 플랫폼에 따라 선택 (Windows YaHei/macOS PingFang/Linux Noto CJK), Linux는 sudo apt install fonts-noto-cjk 필요; --font-name으로 지정 가능
자막이 기존 하드 자막을 가림`--avoid-hardsub single
디스크 공간 부족<출력 루트>/tmp/ 정리
의존성 관련 오류references/설치 가이드.md를 읽고 안내에 따라 설치한 후 메인流程으로 돌아가기

의존성 확인 원칙: 메인流程을 직접 실행하고, 오류 발생 시 확인—시간을 낭비하며 미리 모든 의존성을 항목별로 확인하지 마십시오. 기본 환경이 이미 구성되어 있습니다 (단계 -1의 --check가 기본 항목을 이미 포함).

관련 스킬