프로젝트 소개

## 개요 ChatGPT Subtitle Translator는 OpenAI ChatGPT API(또는 로컬 Ollama 인스턴스를 포함한 모든 OpenAI 호환 채팅 완성 엔드포인트)를 기반으로 하는 번역 유틸리티입니다. 줄 단위 번역, 특히 SRT 자막에 초점을 맞추며, 입력과 출력 줄의 대응을 유지하여 자막 타이밍을 보존하는 것이 중요합니다. ## 작동 방식 토큰 사용량을 줄이기 위해 SRT 인덱스와 타임스탬프는 모델에 전송되기 전에 제거되거나 단순화됩니다. 줄은 하나의 프롬프트 안에서 배치로 그룹화되어 항목별 반복 부가 정보를 제거하고, 과도한 토큰 소비 없이 임의로 긴 파일을 번역할 수 있습니다. 기본 시스템 지시문은 최소한의 `Translate to <language>`입니다. `--structured`를 통해 다섯 가지 구조화 모드를 선택할 수 있습니다: - `array`(기본값): 줄이 JSON 배열로 전송되고 모델이 일치하는 배열을 반환합니다. - `object`: 소스 줄이 응답 스키마의 키가 되므로 별도의 사용자 메시지가 전송되지 않습니다. - `timestamp`: 배치 오프셋과 항목별 오프셋/길이(밀리초)를 사용하는 압축 Toon 형식으로 텍스트와 함께 타이밍이 보존됩니다. 모델이 인접 항목을 병합할 수 있습니다. 출력 시간 범위 경계가 입력과 일치하지 않을 때만 재시도합니다. - `agent`: 기본 옵션이 적용된 agent 하위 명령의 별칭입니다. - `none`: 구조화 출력이 없는 레거시 모드입니다. ## 기능 - 웹 UI(GitHub Pages 호스팅) 및 CLI - Structured Output 지원, 두 인터페이스 모두에서 기본 활성화 - Prompt Caching 지원, `-c, --context`로 제어(CLI 전용) - 모든 OpenAI API 호환 제공자와 작동, 예: 로컬 Ollama - 컨텍스트 토큰 예산에서 자동으로 산출되는 배치 크기를 사용한 줄 기반 배칭 - 거부 가능성이 높은 요청에 토큰을 낭비하지 않도록 하는 선택적 OpenAI Moderation 검사(`--use-moderator`, CLI 전용) - 스트리밍 프로세스 출력 - 분당 요청 속도 제한 - 진행 재개(CLI 전용) - 스트리밍 중 반복 루프 감지(`--guard-repetition`) ## Agent 모드 `agent` 하위 명령은 번역 전에 여러 패스를 실행합니다. 개요 패스는 파일을 샘플링하여 콘텐츠, 길이, 장르/어조, 캐릭터 이름을 식별하고 소스 언어를 감지합니다. 계획 패스는 토큰 한도로 나눈 창에서 파일을 스캔하여 배치 요약을 생성하고, 이를 정제된 번역 지시문으로 통합합니다. 그런 다음 번역 패스에서 강화된 지시문을 사용하고 첫 배치 후 대상 언어를 검증합니다. 옵션에는 `--no-refine`, `--no-fitting`, `--context-summary`가 있습니다. ## 설정 및 사용법 Node.js >= 20이 필요합니다. 복제 후 `npm install`을 실행하고, `cli/translator.mjs`를 실행 가능하게 만들고, `.env.example`을 `.env`로 복사한 뒤 API 키를 추가합니다. 일반적인 호출에는 `cli/translator.mjs --input subtitles.srt --from Japanese --to English`, `--plain-text`를 통한 일반 텍스트 입력, `--system-instruction`을 통한 사용자 지정 지시문이 포함됩니다. 모델, temperature, top_p, 페널티, logit bias는 표준 OpenAI 매개변수를 통해 구성할 수 있습니다.