dimastatz/whisper-flow

Whisper Flow – OpenAI Whisper 기반 실시간 전사

기능 – Whisper Flow는 OpenAI Whisper 음성‑텍스트 모델을 얇은 FastAPI 서비스로 감싸서, WebSocket을 통해 실시간 오디오 스트림을 받아 부분 및 최종 전사 결과를 JSON으로 반환합니다. 일반적으로 전체 파일을 처리하는 Whisper를 저지연 스트리밍 ASR 엔진으로 변환합니다.

작동 방식

• 클라이언트는 ws://<host>:8181/ws를 열고 원시 PCM 오디오(16 kHz, 모노, int16)를 바이너리 프레임으로 전송합니다.
• 서버는 들어오는 청크를 버퍼링하고, 시간 창(tumbling windows)으로 그룹화한 후 각 세그먼트에 대해 Whisper를 실행합니다.
• 각 추론 패스 후 JSON 페이로드가 다시 푸시됩니다:

  {"is_partial": true|false, "data": {"text": "…"}, "time": <ms>}
  

  is_partial은 전사가 여전히 변경될 수 있는지 여부를 나타냅니다. 음성 일시 중지, 창 한도 도달 또는 클라이언트가 flush/stop 제어 프레임을 보낼 때 최종 결과가 출력됩니다.
• 작은 HTTP 엔드포인트(GET /ready)는 프로토콜 버전과 사용 가능한 Whisper 모델 파일을 보고합니다.

주요 구성 요소

모듈	역할
whisperflow.transcriber	Whisper 모델(기본적으로 tiny.en.pt)을 로드하고 동기(transcribe_pcm_chunks) 및 비동기(transcribe_pcm_chunks_async) 헬퍼를 제공합니다.
whisperflow.streaming	클라이언트별 상태를 관리하고, 오디오 청크를 버퍼링하고, 트랜스크라이버를 호출하고, JSON 결과를 WebSocket으로 다시 보내는 TranscribeSession을 구현합니다.
FastAPI 서버	WebSocket 엔드포인트, 상태 확인(/health) 및 배치 전사 POST(/transcribe_pcm_chunk)를 노출합니다.

시작하기

1. 설치 – Python 3.8+, PortAudio(PyAudio용), 그런 다음 ./run.sh -local을 실행하면 virtualenv를 만들고 requirements.txt를 설치하고, 포맷, 린트 및 테스트 스위트를 실행합니다.
2. 실행 – ./run.sh -run-server는 포트 8181에서 서비스를 시작합니다. http://localhost:8181/health로 확인하세요.
3. 사용 – PCM 오디오를 스트리밍하는 WebSocket 클라이언트를 연결하거나, 패키지를 설치(pip install whisperflow)하고 README 예제에 표시된 대로 라이브러리를 직접 호출합니다.

성능 – Apple M1(16 GB RAM)에서 LibriSpeech를 사용한 벤치마크는 부분 결과당 평균 지연 시간 ≈ 275 ms, 단어 오류율 약 7 %를 보고하며, 이는 1초 미만의 실시간 목표를 충족합니다.

배포 옵션

• Docker – ./run.sh -docker는 이미지(whisperflow-image)를 빌드하고 포트 8181을 노출하는 컨테이너를 실행합니다.
• Python 패키지 – 라이브러리를 다른 프로젝트에 가져와 사용자 정의 WebSocket 서버 또는 기존 파이프라인과의 통합을 가능하게 합니다.

로드맵 – v1.3은 더 넓은 py‑speech 생태계를 통해 패키지를 노출하는 것을 목표로 합니다.

---

모든 세부 사항은 저장소의 README에서 직접 가져온 것입니다.