AutoPulse Captions은(는) 무엇을 하나요?

파이프라인: video → Whisper (단어 타임스탬프) → Mini-ML 교정 (EN/ID) → 마이크로 청크 .ass (활성 단어 강조) → 선택적 미리보기 편집기 → FFmpeg burn-in.

PROJECT_DIR (generate_captions.py와 gpu_check.py가 있는 폴더) 찾기:

generate_captions.py가 이 SKILL.md와 같은 디렉토리에 있으면 PROJECT_DIR은 이 디렉토리입니다.
이 SKILL.md가 .agents/skills/autopulse-captions/ 안에 있으면 PROJECT_DIR은 저장소 루트(../../..)입니다.
그 외에는 기본값 C:\Users\Evan\.gemini\antigravity\scratch\autopulse-captions를 사용합니다.

아래 모든 명령어는 PROJECT_DIR에서 실행합니다. Python 실행 파일 (PY): Windows의 경우 PROJECT_DIR/.venv/Scripts/python.exe, macOS/Linux의 경우 PROJECT_DIR/.venv/bin/python.

0. 첫 설정 (`.venv/` 또는 `hardware_profile.json`이 없을 때만)

먼저 하드웨어 확인 (설치 불필요, 네트워크 불필요): python gpu_check.py — 어떤 Whisper 모델이 적합한지 보여줍니다 (예: RTX 3060 → large-v3, GTX 1650 Ti 4 GB → large-v3-turbo, GPU 없음 → CPU large-v3-turbo/small).
Python 3.10–3.12로 venv 생성 (3.13까지 가능; 3.14는 CTranslate2 휠 없음): py -3.11 -m venv .venv (Windows) / python3.11 -m venv .venv.
하드웨어에 맞는 의존성 설치 (네트워크 필요): PY install.py --download-model (Windows에서 FFmpeg가 없으면 --install-ffmpeg 추가). NVIDIA GPU가 발견된 경우에만 CUDA 12 런타임 라이브러리를 설치하고, GPU 스모크 테스트를 수행하며, hardware_profile.json을 작성합니다.
확인: 설치 프로그램이 SELESAI -> Whisper: <model> / <device> / <compute>로 끝납니다.

1. 실행 전 질문 (필수)

새 동영상을 텍스트로 변환하기 전에, 항상 먼저 사용자에게 질문하세요 (ask_question 사용, 프롬프트에 명시되지 않았으면 일반 텍스트로) — 추측하지 마세요:

캡션 언어:
1. 영어 (--lang en)
2. 인도네시아어 (--lang id)
3. 인도네시아어 오디오 → 영어 캡션 (--lang id --translate)
4. 자동 감지 (--lang auto)
불명확한 경우에만: 동영상에 입힐지 (--burn) 아니면 .ass만 생성할지.

에이전트가 스크립트를 실행할 때는 항상 --lang을 명시적으로 전달하세요 (스크립트 자체의 대화형 프롬프트는 실제 대화형 터미널에서만 나타납니다).

2. 캡션 생성

PY generate_captions.py "<video>" --lang en --burn --output-video "<out>.mp4"

모델/장치/컴퓨트는 기본값 auto (gpu_check.py에서)이며, 메모리 부족 또는 CUDA 오류 시 자동 대체됩니다 (예: large-v3 → large-v3-turbo → CPU). 사용자가 요청하지 않으면 --model을 재정의하지 마세요.
방향(세로 / 가로 / 정사각형)은 ffprobe를 통해 감지되며, 글꼴 크기, 여백 및 줄 길이가 자동으로 조정됩니다.
모델의 첫 실행은 Hugging Face에서 다운로드합니다 (네트워크 필요).
입력 파일 옆에 출력: <name>.ass, <name>_raw_words.json, <name>_captioned.mp4; 또한 last_run.json과 업데이트된 preview_player.html.

확인: 종료 코드 0, 로그 줄 model dipakai: ..., 출력된 동영상 파일 존재. 사용자에게 사용된 모델과 스크립트가 출력한 의심스러운 단어 목록을 보고하세요.

3. 검토 및 수정 (의심스러운 단어가 있거나 사용자가 변경을 원할 때)

브라우저에서 PROJECT_DIR/preview_player.html을 엽니다 (--open-preview가 이 작업을 수행합니다). 사용자가 단어/타임스탬프를 편집하고, 누락된 단어를 추가하며 (➕ Kata), 💾 Simpan words.json을 클릭합니다 (words_revised.json 다운로드).
수정된 JSON에서 다시 렌더링 — 이로 인해 Mini-ML이 학습됩니다 (learned_memory.json, 별도의 en/id 프로필) — 마지막 원시 Whisper 출력과 비교하여 차이를 계산:
```
PY generate_captions.py "<path>/words_revised.json" --burn --output-video "<out>.mp4"
```
소스 동영상은 last_run.json에서 가져옵니다 (--video로 재정의 가능).

4. 동영상 생성 후 연속 작업

다른 단계에서 동영상(예: draft.mp4)이 생성된 경우, 언어 질문을 한 후 해당 파일에 대해 2단계를 --output-video final.mp4로 실행합니다.

문제 해결

증상	해결 방법
`No module named faster_whisper`	`.venv`의 `PY`를 사용하거나 0단계 실행
모든 GPU 옵션이 실패하고 CPU로 대체됨	NVIDIA 드라이버 업데이트, `PY install.py` 재실행
CPU에서 느림	예상됨 (~1× 실시간). 초안용으로 `--model small` 권장
`ffmpeg tidak ditemukan`	`winget install Gyan.FFmpeg` / `brew install ffmpeg` / `apt install ffmpeg`
잘못된 단어 / 속어 / 이름	편집기 사용 (3단계)하여 Mini-ML이 학습하도록 함; 또는 `--hotwords "이름1 이름2"`
번역 품질 낮음	`--translate`는 turbo를 사용하지 않음 (번역 학습 안 됨); `large-v3`에 ~3.6 GB 이상의 여유 VRAM 필요

전체 플래그 참조: references/cli.md · Mini-ML 작동 방식: references/mini-ml.md

AutoPulse Captions