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)을 명시적으로 박아둔다.

기타:

• 첫 실행 시 모델(~1.5GB)이 HuggingFace에서 자동 다운로드된다. 사용자에게 미리 알린다.
• 60분 오디오 기준 M 시리즈 Mac에서 3~8분 소요 예상.
• 출력 파일명은 {원본 오디오 basename}.txt 형태로 $OUTDIR 아래에 생성된다 (--output-name 덕분에 정규화 임시파일 이름이 새지 않음).

5. 결과 미리보기 + 저장 위치 확인

생성된 txt 파일을 읽어 사용자에게 미리보기를 제시한다 (긴 경우 앞/뒤 일부만).

그다음 저장 위치를 사용자에게 반드시 질의한다. 저장 위치 후보:

• 원본 오디오 파일과 같은 디렉토리에 {basename}.txt
• logs/transcripts/YYYY-MM-DD_{slug}.md (frontmatter 포함)
• meeting-logs/YYMMDD_{title}.md (전사 후 회의록 가공까지 요청한 경우)
• projects/{project_id}/meeting-logs/... (프로젝트 관련 녹음)
• 저장하지 않고 화면 출력만

사용자가 저장 위치를 지정하면 해당 위치로 이동(mv) 또는 복사(cp)한다. 마크다운으로 저장하는 경우 ## Document Frontmatter 규칙에 따른 frontmatter를 추가한다.

6. 정리

임시 출력 디렉토리($OUTDIR)와 정규화된 임시 오디오 파일($NORMALIZED)은 저장 완료 후 삭제한다.

rm -rf "$OUTDIR" "$NORMALIZED"

화자 분리 요청 처리

사용자가 "화자 구분", "누가 말했는지", "speaker diarization" 등을 명시적으로 요청하면:

현재 skill은 화자 분리를 지원하지 않습니다. 추가하려면 pyannote.audio + HuggingFace 토큰 설정이 필요합니다. 진행하시겠습니까?

라고 안내하고 사용자 결정을 기다린다. 임의로 진행하지 않는다.

Invariants

• 언어는 한국어(ko) 고정. 다른 언어 요청 시 사용자에게 확인 후 --language 변경.
• 모델은 기본 mlx-community/whisper-large-v3-turbo. 품질 불만 시에만 whisper-large-v3 (turbo 아님, 더 느리고 품질 살짝 높음) 로 교체.
• 결과 저장 위치는 항상 사용자에게 확인한다. 임의로 리포지토리 안에 커밋될 파일을 만들지 않는다.
• 원본 오디오 파일은 절대 수정/삭제하지 않는다.

의존성

사전 설치 완료된 상태를 가정한다:

• mlx_whisper (uv tool install mlx-whisper)
• ffmpeg (brew install ffmpeg)

둘 중 하나라도 없으면 사용자에게 설치 필요함을 알리고 중단한다.