transcribe

transcribe — 로컬 오디오 전사

Apple Silicon 네이티브 mlx-whisper(Whisper large-v3-turbo)로 로컬 오디오 파일을 한국어 텍스트로 전사한다.

플로우

1. 파일 경로 확인

사용자가 제공한 오디오 파일 경로를 확인한다. 상대경로면 현재 작업 디렉토리 기준 절대경로로 변환한다.

지원 포맷: m4a 기본, mp3/wav/mp4 등 ffmpeg이 디코딩 가능한 포맷 모두 동작.

2. 도메인 힌트 구성

현재 대화 맥락에서 다음 카테고리를 적극적으로 끌어모아 한국어 한두 문장으로 조합해 --initial-prompt에 넣는다. 맥락이 있으면 가능한 한 풍부하게 채운다(없는 정보를 지어내지는 않는다).

수집할 카테고리:

• 참석자/화자 이름 (가능하면 전부)
• 회사명·제품명·서비스명
• 자주 쓰일 영문 약어·전문용어의 한글 표기 예시 (예: "토스페이먼츠를 'TPay'로도 부른다", "API를 '에이피아이'로 발음한다")
• 도메인 키워드 5~20개

예시:

• 대화에서 "최수민, 바이브마피아클럽, 구글, B2B 제안서"가 언급되었다면
  • --initial-prompt "이 녹음은 바이브마피아클럽 최수민과 구글의 B2B 제안 회의다. 등장 용어: 바이브마피아클럽(VMC), 구글, B2B 제안서, 견적, 라이선스."

맥락이 전혀 없으면 이 단계는 건너뛴다. 단, 사용자에게 "전사 품질을 올리려면 등장 인물·고유명사를 알려주세요"라고 한 번 권유한다.

3. 오디오 전처리

작은 목소리 화자 누락과 볼륨 편차로 인한 환각을 줄이기 위해 ffmpeg loudnorm으로 정규화한 뒤 전사한다. 이 단계는 항상 수행한다(추가 비용 거의 없음, 효과 큼).

NORMALIZED="$(mktemp -t transcribe_norm).wav"
ffmpeg -y -i "<AUDIO_PATH>" \
  -af loudnorm=I=-16:TP=-1.5:LRA=11 \
  -ar 16000 -ac 1 \
  "$NORMALIZED"

• -ar 16000 -ac 1: Whisper 내부 표현(16kHz 모노)에 맞춰 미리 변환. 모델 입력 변환 비용 절감.
• 사용자가 "잡음이 심하다", "BGM 깔려 있다"고 명시한 경우에만 추가로 demucs(음성 분리) 또는 arnndn(RNNoise) 단계를 적용한다. 기본 플로우에는 넣지 않는다 — 모델 다운로드/실행 비용이 크고 깨끗한 녹음에선 오히려 음성을 깎는다.

4. 전사 실행

임시 출력 디렉토리에 txt 포맷으로 내보낸다. 환각 방지 플래그를 기본 적용한다.

OUTDIR="$(mktemp -d -t transcribe)"
ORIG_BASE="$(basename "<AUDIO_PATH>")"; ORIG_BASE="${ORIG_BASE%.*}"
mlx_whisper \
  --model mlx-community/whisper-large-v3-turbo \
  --language ko \
  --output-format txt \
  --output-dir "$OUTDIR" \
  --output-name "$ORIG_BASE" \
  --condition-on-previous-text False \
  --temperature 0 \
  --no-speech-threshold 0.6 \
  --verbose False \
  [--initial-prompt "<DOMAIN_HINT>"] \
  "$NORMALIZED"

환각 방지 플래그 의도:

• --condition-on-previous-text False: 한 번 잘못 인식한 텍스트가 뒤 구간으로 전염되는 문제 차단. 회의 녹음에선 거의 항상 이득.
• --temperature 0: 샘플링 무작위성 제거. 동일 입력에 동일 출력 보장.
• --no-speech-threshold 0.6: 무음/BGM 구간에서 "구독과 좋아요 부탁드립니다" 같은 환각 생성 방지. 기본값(0.6)을 명시적으로 박아둔다.