# Web STT (mp3/m4a 업로드 → 텍스트 변환)

## 구성
- **백엔드**: FastAPI (업로드/검증/STT 수행)
- **STT 엔진**: `faster-whisper` (Whisper 모델)
- **프론트**: 단일 HTML (파일 선택 → 전사 → 결과 표시/다운로드)

## 동작 개요 (pseudocode)

```text
UI:
  onSelect(file):
    validate client-side (extension)
    enable "전사" 버튼

  onClickTranscribe():
    POST /api/transcribe (multipart/form-data, file, options)
    show progress (업로드 중 / 처리 중)
    render returned text + segments
    allow download as .txt

API:
  POST /api/transcribe:
    if no file -> 400
    validate mime/ext in allowed audio types -> 415 if not
    save to temp file
    run STT(model, language, vad_filter, beam_size, ...)
    return { text, segments[], detected_language, duration_sec }
    cleanup temp file
```

## 실행

### 1) miniconda `ncue` 환경 준비

이미 `ncue`가 있다면:
```bash
conda activate ncue
pip install -r requirements.txt
```

`ncue`가 없다면(권장):
```bash
conda env create -f environment.yml
conda activate ncue
```

### 2) ffmpeg
`environment.yml`로 설치하면 자동 포함됩니다. (수동 설치 시 아래)

macOS (Homebrew):
```bash
brew install ffmpeg
```

### 3) 서버 실행
```bash
uvicorn app.main:app --reload --host 127.0.0.1 --port 8025
```

브라우저에서 `http://127.0.0.1:8025` 접속.

## 옵션
- **모델**: 기본 `small` (정확도/속도 균형). `APP_WHISPER_MODEL=base|small|medium|large-v3` 등으로 변경 가능
- **디바이스**: 기본 CPU. Apple Silicon에서 Metal은 `faster-whisper` 단독으로는 제한이 있어 CPU 기본값을 권장