STT 배치 모드 연동 — 녹음 파일 전사

AI Hub 음성을 파일 단위로 전사하는 경로를 붙인다. 실시간 스트리밍은 3주차다.

전제는 이미 끝났다 — 결제 계정·키·할당량(w1-stt-billing-quota), 연결 확인, scripts/test_stt.py.

왜 배치가 먼저인가

반복 실험을 스트리밍으로 돌리면 할당량(600초/일)을 금방 태운다. 배치 모드로 전사해 결과를 저장해두면 같은 오디오를 몇 번이고 다시 쓸 수 있다(리스크 비용 항목).

할 것

• 파일 목록을 받아 전사 → 결과를 재사용 가능한 형태로 저장
• 실패·재시도 처리 (긴 파일에서 끊기는 경우)
• 사용한 오디오 초를 로그에 남겨 할당량 소진을 눈으로 볼 수 있게

완료 조건

같은 명령으로 재실행하면 이미 전사된 파일은 건너뛰고, 사용량이 로그에 남는다.

2026-08-26 — 스크립트 작성 완료, 실행 검증은 남음

scripts/transcribe_batch.py.

할당량을 태우지 않는 것이 이 티켓의 핵심이라 두 장치를 넣었다.

• COST-1 애플리케이션 가드 — data/processed/stt-usage.json 에 날짜별 사용 초를 누적하고, .env 의 STT_MAX_SECONDS_PER_DAY(600)·_MONTH(3600)를 넘길 파일은 요청을 보내지 않고 건너뛴다. 중간에 죽지 않고 나머지 파일은 계속 처리한다. GCP 콘솔 쿼터(1차)에 이은 2차 방어선이다
• 내용 해시 캐시 — 같은 오디오는 다시 전사하지 않는다(경로가 바뀌어도 동일 판정). 검색·트리거·마스킹 실험에서 같은 전사 결과를 반복해 쓰기 위한 것이다
• --dry-run 으로 쓰기 전에 몇 초를 쓸지 먼저 볼 수 있다

발화 종료 시각이 골든셋 스펙에 필요해 enable_word_time_offsets 를 켜고 단어별 start_ms/end_ms 를 저장한다.

검증한 것 (합성 wav 로): 대상 없음 → exit 1, --dry-run 초 계산, 900초 파일이 일 한도 600초에 걸려 건너뛰어지고 5초 파일은 계속 처리됨, 캐시된 파일 재전사 안 함.

검증하지 못한 것 — 실제 API 호출 경로. 이 머신에 data/raw/ 오디오도 google-cloud-speech 도 없다. 오디오가 있는 머신에서 --dry-run 으로 먼저 확인한 뒤 소량(5~10건)으로 실행해야 한다.

출력은 data/processed/stt/ (gitignore 대상). 전사 원문에는 개인정보가 그대로 들어 있으므로 커밋하지 않는다 — 마스킹(C-5)은 별도 모듈의 책임이다.

2026-08-28 — 결함 3건 수정. 실행 검증은 아직 못 했다

류준 님이 「다산콜DB 6,614건 전사」를 요청하면서 이 티켓의 실행 검증을 겸하자고 했다. 전사 범위는 미결로 넘겼고, 여기서는 스크립트 쪽만 정리한다.

고친 것 (합성 wav 84개로 --dry-run 검증)

• 샘플레이트·채널을 wav 헤더에서 읽는다. 전에는 --sample-rate 기본값 8000 을 무조건 보냈다. data/README.md 의 「1.3G」와 류준 님이 잰 45,853초가 안 맞는다 — 8kHz 16bit 모노면 734MB 여야 하므로 실제 파일은 16kHz 거나 스테레오다. 그 상태로 8000 을 보내면 요금은 나가고 전사는 깨진다. 이제 헤더 조합을 요약에 찍어 첫 실행에서 바로 드러난다. --sample-rate 는 재정의용으로만 남겼다
• 60초 초과 파일을 거른다. V1 동기 recognize() 는 60초·10MB 상한이라 넘으면 요청이 실패한다
• --dry-run 이 캡을 시뮬레이션한다. charge() 를 안 하니 캡이 영원히 0 이라 캡을 무시한 전체 초를 「새로 쓸 초」로 찍고 있었다. 실제 실행이 하루 600초에서 멈춘다는 사실이 가려졌다. 이제 전체 길이(남의 계산과 대조용)와 이번 실행의 실제 소진분을 둘 다 찍는다

여전히 검증하지 못한 것 — 실제 API 경로. 이 머신에 data/raw/ 오디오도 .venv 도 없다. 오디오가 있는 머신에서 --dry-run 으로 헤더·초를 확인한 뒤 소량(5~10건)으로 실행해야 한다. 그때까지 이 티켓은 in-progress 로 둔다.

전량 전사는 이 티켓의 완료 조건이 아니다. 완료 조건은 “재실행 시 캐시가 먹고 사용량이 로그에 남는다”이고, 그건 5~10건으로 확인된다.