swei99386-alt/video-to-text-skill

비디오/오디오에서 "말로 나온 내용"을 텍스트로 변환합니다. 여기에는 피와 눈물로 얻은 고정된 절차가 있습니다. 순서를 엄격히 따르고, 0단계를 무시하지 마세요.

철칙 (가장 중요하니 먼저 기억하세요)

언제나 "기존 자막"을 먼저 찾으세요. 정말 없을 때만 "받아쓰기"를 사용합니다. 대부분의 공식 강연, 컨퍼런스, 팟캐스트는 YouTube에 업로드되며, YouTube는 거의 항상 자막을 제공합니다 — 명령어 하나로 몇 초 만에 자막을 가져올 수 있으며, 무료이고, 전체 동영상을 다운로드하지 않으며, GPU를 사용하지 않습니다. 예전에 이 지름길을 사용하지 않고 450MB 동영상을 통째로 다운로드하여 CPU로 30분 동안 받아쓰기를 실행해 엉망인 결과를 얻었습니다. 이 실수를 반복하지 마세요.

0단계: 링크를 받으면 먼저 두 가지를 구분하고 순서를 결정하세요

텍스트 변환 (해당 영상의 대본을 얻는 것)과 출처 확인 (누가 말했는지, 원본이 언제인지, 전체 버전인지)은 별개의 작업입니다. 함께 묶지 마세요. 이전 버전처럼 무조건 "X 링크면 YouTube부터 본다"는 잘못된 접근입니다 — X도 자체 자막을 제공하는 경우가 많으므로 YouTube를 거칠 필요가 없습니다.

텍스트 변환: 항상 현재 링크에서 먼저 자막을 확인하세요. YouTube를 기본으로 돌지 마세요.

1. grab.py를 직접 실행 — 스크립트가 해당 링크의 자막을 먼저 가져옵니다 (X는 종종 en/es 등 자막 제공). 자막을 찾으면 끝입니다. 이것이 가장 빠른 지름길입니다.
2. 다음 두 경우에만 YouTube 원본을 찾으러 가세요:
   • X에 자막이 전혀 없는 경우 (YouTube에는 있을 가능성이 높음);
   • X가 클립 조각인 경우 — 내용이 더 긴 영상을 언급하지만 X 조각은 1-2분에 불과할 때 (짧은 조각만 얻으므로 전체 영상이 필요하면 원본을 찾으세요). 찾는 방법: "발표자 + 주제/제목 + 행사명"으로 검색하여 YouTube 원본을 찾고, 그것으로 1단계를 진행하세요.

길이가 곧 지표입니다: 먼저 yt-dlp --no-download --print "%(duration_string)s"를 실행하여 길이를 확인하세요. X 조각이 설명과 비슷한 길이면 ("28분"이라고 하면 27분 정도) = 전체 영상이므로 그냥 가져오면 됩니다; 훨씬 짧으면 = 클립 조각이므로 원본을 찾아야 합니다.

출처 확인 (누가/언제 말했는지/완전한지)은 별개의 작업입니다. 사용자가 요청할 때만 수행하며, 텍스트 변환의 필수 단계가 아닙니다. 필요한 정보를 얻으면 그만하세요. 사용자가 요청하지 않은 정확한 날짜나 공식 원본 버전까지 계속 찾지 마세요 (2026-07-22에 이 실수를 했습니다).

1단계: 스크립트 한 번 실행 (자막/받아쓰기 자동 판단)

python "C:/Users/Administrator/.claude/skills/비디오를텍스트로/scripts/grab.py" "<링크 또는 로컬 파일>" "출력폴더명" [언어]

세 번째 인수 【언어】 선택 사항: 중국어 비디오는 zh (중국어+간체 강제), 영어는 en, 생략 시 자동 판단. 스크립트 내부 로직 (고정됨):

• 먼저 기존 자막 가져오기 → 성공하면 즉시 완전텍스트.txt 출력, 종료.
• 자막이 없으면 → 자동으로 오디오 추출 후 GPU로 받아쓰기 실행 (CPU 사용 안 함).
• 모든 결과물은 바탕화면 <출력폴더명> 폴더에 저장됨: 완전텍스트.txt (깔끔한 텍스트) + 원본 자막/자막 파일.

실행 후 완전텍스트.txt의 위치와 단어 수를 사용자에게 알려주기만 하면 됩니다.

Bilibili / 중국 사이트 (YouTube와 다르니 별도로 기억하세요)

• 다운로드 가능: 다운로드 도구가 Bilibili 및 여러 중국 사이트를 지원하므로 영상/오디오 다운로드는 문제없습니다.
• 하지만 "기존 자막 가져오기" 무료 지름길은 거의 불가능: Bilibili에는 YouTube 같은 전사이트 기계 자막이 없습니다. 소수의 업로더가 수동으로 CC 자막을 올린 경우에만 가져올 수 있습니다. 탄막(彈幕)은 자막이 아닙니다 (탄막은 시청자의 떠다니는 댓글이지 대사가 아닙니다). 탄막을 가져오지 마세요.
• 따라서 Bilibili 영상은 대부분 직접 "GPU 받아쓰기"를 사용합니다. 중국어 비디오는 세 번째 인수에 zh를 전달하세요:

  python ".../grab.py" "<Bilibili 링크>" "출력폴더명" zh
  

• 중국어 정확도 참고: 현재 small 모델을 사용 중이며, 중국어는 "대략적인 이해"만 가능하여 오타가 발생하기 쉽습니다. 더 정확하려면 medium 모델 (약 1.5G, 일회성 다운로드, 현재 미설치)로 교체해야 합니다. 사용자가 2026-07-21에 "일단 small로 버티고" 결정했습니다. 더 정확한 결과가 필요하면 medium을 설치하고 스크립트의 --model small을 medium으로 변경하세요.
• 로그인: Bilibili 회원 전용/고화질/로그인 필요한 영상은 다운로드 시 계정 쿠키가 필요합니다. 이런 경우 먼저 사용자에게 물어보고, 함부로 계정에 접근하지 마세요.

링크로 접근 불가능한 영상 (위챗 비디오 / 유료 암호화 페이지 / 화면에서만 재생 가능한 모든 것) → 화면 소리 녹음

다운로드 도구가 이러한 영상에 접근할 수 없습니다 (위챗 비디오는 앱 안에 갇혀 있고, 유료 페이지는 암호화되어 있습니다). 유일한 방법: 영상을 재생하는 동안 컴퓨터 사운드를 녹음한 후 텍스트로 변환합니다. 이 기기는 내부 녹음 기능이 이미 설치되어 있습니다 (soundcard 라이브러리, 드라이버/설정 불필요).

세 단계:

1. 녹음 시작 (백그라운드 실행, 중지할 때까지 녹음):

   python "C:/Users/Administrator/.claude/skills/비디오를텍스트로/scripts/record.py" "출력폴더명"
   

2. 영상을 처음부터 끝까지 재생 (실시간 녹음, 3시간 영상은 3시간 재생 필요, 빨리 감기 불가).
3. 녹음 프로세스 중지 (에이전트가 백그라운드 작업을 중단시켜도 문제없음). 그런 다음 녹음.pcm 파일을 grab.py에 직접 전달하여 텍스트 변환 (pcm 인식 가능; 중국어는 zh 추가):

   python "C:/Users/Administrator/.claude/skills/비디오를텍스트로/scripts/grab.py" "<바탕화면 경로>/<폴더>/녹음.pcm" "<폴더>" zh
   

• 디스크에 실시간으로 기록되므로 중간에 강제 종료되어도 데이터가 손실되지 않습니다 (pcm은 항상 존재하며, "마무리" 단계가 필요하지 않음).
• 링크를 얻을 수 있다면 녹음을 사용하지 마세요: 다운로드는 몇 분이면 끝나지만, 녹음은 전체 재생 시간을 기다려야 합니다. 화면 녹음은 정말 링크를 얻을 수 없는 경우에만 사용하세요.

2단계: 받아쓰기를 사용한 경우에만 신경 쓸 사항

• 반드시 GPU 사용: 이 기기에는 NVIDIA GTX 1060 (5G VRAM)이 있으며, 스크립트가 자동으로 GPU를 우선 사용합니다. 만약 로그에 "CPU"라고 표시되면 "GPU를 사용하는 torch"가 CPU 버전으로 되돌아간 것입니다. 아래 [GPU 기반] 섹션을 참고하여 수리하세요.
• 길이가 긴 경우 (>20분): 처리 속도가 느린 것은 정상이지만, GPU 사용 시 분 단위로 완료되어야 합니다. 30분처럼 느리면 CPU로 되돌아간 것입니다.
• 받아쓰기는 오타/누락이 불가피: "대략적인 이해"이므로 원본 자막만큼 정확하지 않습니다. 자막을 얻을 수 있다면 받아쓰기를 사용하지 마세요.

GPU 기반 (받아쓰기에 필수; 고장 시 이 방법으로 수리)

받아쓰기가 GPU를 사용하려면 "GPU 지원" torch가 설치되어 있어야 합니다. 자가 진단:

C:/Users/Administrator/portable-python311/runtime/python.exe -c "import torch;print(torch.__version__, torch.cuda.is_available())"

• ...+cu126 True = 정상, GPU 사용 가능.
• ...+cpu False = CPU만 사용 중. 재설치:

C:/Users/Administrator/portable-python311/runtime/python.exe -m pip install --force-reinstall torch==2.11.0 --index-url https://download.pytorch.org/whl/cu126

(driver CUDA 12.6 → cu126 소스 사용. 이 5G GPU는 음성 인식/OCR/중소형 모델에 충분; 8G VRAM부터 필요한 대형 모델은 실행 불가.)

자주 사용하는 수동 명령어 (스크립트 외부 참고용)

• 자막 언어 확인: yt-dlp --no-download --list-subs "<url>"
• 동영상 없이 영어 자막만 다운로드: yt-dlp --skip-download --write-auto-subs --sub-langs "en-orig,en.*" --convert-subs srt -o "%(title)s.%(ext)s" "<url>"
• 길이/업로드 날짜 확인: yt-dlp --no-download --print "%(title)s | %(duration_string)s | %(upload_date)s" "<url>"