# 스트리밍 STT

본 문서는 오디오 스트리밍 입력을 텍스트로 변환할 수 있는 스트리밍 STT API를 구현하는 방식에 대한 가이드를 제공합니다. 스트리밍 STT는 1) gRPC 와 2) WebSocket, 두 가지 방식을 지원하고 있으며, 구체적인 연동 방식은 [스트리밍 STT - gRPC](/docs/stt-streaming/grpc.md), [스트리밍 STT - WebSocket](/docs/stt-streaming/websocket.md) 에서 확인하실 수 있습니다. 스트리밍이 아닌 파일에서 텍스트 변환이 필요할 경우 [일반 STT 가이드 문서](/docs/stt-file.md)를 통해 STT 기능을 사용할 수 있습니다.

주의사항

스트리밍 STT API는 동시채널제한의 영향을 받습니다. 동시에 연결할 수 있는 스트리밍 채널의 최대 개수는 [처리량 제한 정책](/docs/rate_limit.md#streaming-stt-concurrent-channel-limit)을 따릅니다.

Streaming connection을 맺은 뒤 audio chunk를 전혀 전송하지 않은 상태로 60초가 지나면 서버가 connection을 종료할 수 있습니다.

## 오디오 인코딩(Audio Encoding)[​](#audio-encoding "오디오 인코딩(Audio Encoding)에 대한 직접 링크")

스트리밍 STT API는 오디오 코덱 LINEAR16, FLAC, MULAW, ALAW, AMR, AMR\_WB, OGG\_OPUS, OPUS를 지원하고 있습니다.

주의

* LINEAR16, MULAW, ALAW, AMR, AMR\_WB는 raw data 형태로 전송해야 합니다.
* OGG\_OPUS는 OGG 컨테이너에서 OPUS 코덱으로 인코딩된 오디오 프레임 형태로 전송해야 합니다.
* OPUS는 gRPC 방식만 지원하며, OPUS로 연동을 원하시는 경우 별도의 문의를 부탁드립니다.

## 공통 DecoderConfig/Parameter 정보[​](#decoder-config "공통 DecoderConfig/Parameter 정보에 대한 직접 링크")

스트리밍 STT에서 gRPC 방식과 WebSocket 방식에서 사용되는 DecoderConfig 에 대한 상세 정보는 아래 표를 참고하실 수 있습니다.

| 이름                    | Type (gRPC / WebSocket) | 설명                                                                                                                                           | 필수 여부 | 기본값      |
| ----------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- |
| sample\_rate            | int                     | 범위: 8000 \~ 48000, 단위: Hz                                                                                                                  | O         | -           |
| encoding                | AudioEncoding / string  | 인코딩 타입 (참고. [오디오 인코딩](#audio-encoding))                                                                                           | O         | -           |
| model\_name             | string                  | 사용할 언어 모델 (한국어 - sommers\_ko, 일본어 - sommers\_ja, 한국어 성능을 강화한 다국어 모델 - whisper)                                      | X         | sommers\_ko |
| domain                  | string                  | 사용할 도메인, 자세한 내용은 [도메인](#domain) 참고                                                                                            | X         | CALL        |
| use\_itn                | bool                    | 영어/숫자/단위 변환 사용 여부 (참고: [영어/숫자/단위 변환](/docs/stt-file/itn.md))                                                             | X         | true        |
| use\_disfluency\_filter | bool                    | 간투어 필터기능 사용 여부 (참고: [간투어 필터](/docs/stt-file/disfluency.md))                                                                  | X         | false       |
| use\_profanity\_filter  | bool                    | 비속어 필터기능 사용 여부 (참고: [비속어 필터](/docs/stt-file/profanity.md))                                                                   | X         | false       |
| use\_punctuation        | bool                    | 구두점 사용 여부                                                                                                                               | X         | false       |
| keywords                | string\[] / string      | 키워드 부스팅을 위한 값, 자세한 내용은 [키워드 부스팅](#keywords-boosting) 참고                                                                | X         | -           |
| language                | string                  | model\_name이 whisper일 경우 적용 (참고: [지원되는 전체 언어 목록](https://github.com/openai/whisper/blob/main/whisper/tokenizer.py#L10-L111)) | X         | ko          |

## 키워드 부스팅(Keywords Boosting)[​](#keywords-boosting "키워드 부스팅(Keywords Boosting)에 대한 직접 링크")

키워드 부스팅은 스트리밍 STT API에서 특정 단어의 인식률을 높이거나 낮추는 기능입니다.

주의

현재는 `sommers_ko` 모델 또는 `language`를 `ko`로 설정한 `whisper` 모델에서만 사용할 수 있습니다.

### 형식 및 사용법[​](#format-and-usage "형식 및 사용법에 대한 직접 링크")

키워드 부스팅에 사용할 단어와 그에 해당하는 스코어를 지정합니다.

* gRPC 방식에서는 `string[]` 형태로 제공됩니다.
* WebSocket 방식에서는 쉼표로 구분된 단일 `string` 형태로 제공됩니다.

개별 키워드는 다음과 같은 형식으로 제공해야 합니다:

* `"단어"` - 스코어를 지정하지 않은 경우 (기본값 2.0 적용)
* `"단어:스코어"` - 단어와 스코어를 콜론(:)으로 구분

### 키워드 부스팅 규칙[​](#keywords-boosting-rules "키워드 부스팅 규칙에 대한 직접 링크")

* **단어**: 인식률을 높이고 싶은 단어는 반드시 한글발음과 띄어쓰기로만 이루어져야 합니다.

* **스코어**:

  <!-- -->

  * 범위: -5.0부터 5.0까지의 실수 값
  * 양수 값: 해당 단어를 더 잘 인식하도록 함
  * 음수 값: 해당 단어를 덜 인식하도록 함
  * 0 값: 해당 키워드에 score를 부여하지 않습니다. 단, 목록에 포함시키는 것 자체가 다른 키워드의 부스팅에 영향을 줄 수 있으므로, 부스팅이 필요 없는 키워드는 목록에서 제거하세요.

### 예시[​](#example "예시에 대한 직접 링크")

```text
// gRPC 방식
["부스팅", "리턴제로:3.5", "에스티티:-1"]

// WebSocket 방식
"부스팅,리턴제로:3.5,에스티티:-1"

```

주의

* 스코어 값은 반드시 -5.0 이상 5.0 이하여야 합니다.
* 단어는 한글 발음대로 적어야 합니다. (예: STT (X), 에스티티 (O))
* 단어는 한글과 공백으로만 구성되어야 하며 음절이어야 합니다.
* 각 단어의 길이는 20자 이하로 제한되며, 최대 100개까지 지원합니다.
* 다른 키워드의 앞부분을 포함하는 더 긴 단어를 함께 등록하면, 짧은 키워드의 부스팅 효과가 줄어들 수 있습니다. (예: "커피"와 "커피숍"을 함께 등록하는 경우)

## 음성 에이전트(AI Voice Agent)[​](#ai-voice-agent "음성 에이전트(AI Voice Agent)에 대한 직접 링크")

AI Voice Agent나 콜봇이 자체 VAD 또는 turn detector로 사용자 발화의 끝을 판단하는 경우, `FINALIZE` command로 현재 발화를 확정할 수 있습니다. 서버의 end-point detection을 기다리지 않고 final transcript를 받아 다음 응답 생성을 더 빠르게 시작할 수 있습니다.

`FINALIZE`는 streaming connection을 종료하지 않습니다. final transcript를 받은 뒤 같은 connection으로 다음 사용자 턴의 audio를 계속 전송할 수 있습니다. 대화를 종료할 때는 gRPC request stream을 half-close하거나 WebSocket에서 `EOS` text message를 전송합니다. 빈 발화나 연속 `FINALIZE`는 결과를 만들지 않습니다. Protocol별 request는 [gRPC](/docs/stt-streaming/grpc.md)와 [WebSocket](/docs/stt-streaming/websocket.md) 예시를 참고하세요.

주의

`OGG_OPUS`처럼 container를 사용하는 encoding은 `FINALIZE` 이후 새 container header를 포함한 독립적인 stream으로 다음 발화를 시작해야 합니다.

## 도메인 (Domain)[​](#domain "도메인 (Domain)에 대한 직접 링크")

도메인은 사용자의 음성 입력 환경에 따라 STT 모델의 성능을 최적화하는 데 사용됩니다.

### 지원 도메인[​](#supported-domains "지원 도메인에 대한 직접 링크")

* **CALL (기본값)**: 전화 통화나 마이크가 발화자의 입과 가까이 있는 환경에 최적화된 모델

  * 장점:

    <!-- -->

    * 마이크 가까이에서 발화자의 목소리만 선명하게 인식
    * 주변 잡음 및 타인의 음성 유입 최소화
    * 전화 통화, 개인용 헤드셋 및 근접 마이크 환경에 적합

* **MEETING**: 회의실 등 마이크와 발화자 사이에 거리가 있는 환경에 최적화된 모델

  * 장점:

    <!-- -->

    * 다수의 발화자 음성을 명확하게 구분 및 처리
    * 회의실 및 공개적인 장소에서의 원거리 음성 인식에 최적화

도메인을 선택할 때는 실제 음성 입력 환경에 맞게 설정하는 것이 중요합니다.