WebSocket 프로토콜

​

세션과 연결은 어떻게 구분되나요?

• 세션이 ENDED가 되면 되돌릴 수 없어요. 계속 전사하려면 새 세션을 만드세요.
• 연결이 끊겨도 세션은 OPEN으로 남아요. 같은 wsUrl과 streamToken으로 다시 연결하세요.
• 세션이 끝나는 사유는 endReason으로 받아요. 값은 session.ended에 정리했어요.

​

연결

• wsUrl은 받은 그대로 쓰세요. 지금은 wss://<host>/v1/external/realtime-transcriptions/{id}/stream 모양이지만 호스트와 경로는 바뀔 수 있어요.
• 토큰은 Authorization 헤더로만 받아요. 쿼리 문자열, 쿠키, API Key로는 연결할 수 없어요. 그래서 헤더를 넣을 수 없는 브라우저 WebSocket API로는 연결할 수 없어요.
• Origin 헤더는 검사하지 않아요.
• streamToken은 그 세션에만 쓸 수 있고, 세션이 OPEN인 동안 다시 연결할 때도 같은 토큰을 써요. 세션 생성 응답에서만 받을 수 있고 다시 발급하는 API는 없어요. 토큰을 잃어버렸다면 세션을 닫고 새 세션을 만드세요.

​

오디오 프레임

​

오디오 선행량은 어떻게 계산하나요?

• 쉬는 동안에는 여유가 쌓이지 않아요. 1분 동안 아무것도 보내지 않았다가 2분 분량을 한 번에 보내도 60초를 넘어요.
• 재접속하면 직전 연결의 선행량을 이어받아요. 재접속으로 한도를 다시 받을 수는 없어요.
• 60초를 넘으면 error(audio_rate_exceeded)의 retryAfterMs에 넘친 양이 담겨요. 그 시간 이상 기다린 뒤 다시 연결하고 실시간 속도로 보내세요.

​

메시지

​

session.end

{ "type": "session.end" }

​

session.started

{ "type": "session.started", "id": "Rt7Yq2PbX9cDk", "resumed": false, "audioOffsetMs": 0 }

​

transcript

{
  "type": "transcript",
  "segmentId": "Ab3kZ9qLm2XyW-1-17",
  "isFinal": true,
  "text": "오늘 회의는 일정 점검부터 하겠습니다.",
  "locale": "ko_KR"
}

• 같은 segmentId의 isFinal: false 메시지가 오면 그 segment의 텍스트를 통째로 바꾸세요.
• isFinal: true는 segment마다 정확히 한 번 와요. 그 뒤로 그 segment의 메시지는 오지 않아요.
• isFinal: false 없이 isFinal: true만 올 수도 있어요.
• segment 크기는 Tiro가 정하고 약속하지 않아요. 지금은 발화가 끝나는 지점에서 나뉘어요.

​

translation

{
  "type": "translation",
  "translationId": "t3-9",
  "isFinal": true,
  "locale": "en_US",
  "text": "Today's meeting will start with a schedule review.",
  "sourceSegmentId": null
}

• 교체 규칙은 transcript와 같아요. 같은 translationId의 isFinal: false는 이전 텍스트를 통째로 바꾸고, isFinal: true는 한 번만 와요.
• 번역 조각은 원문 segment와 1:1로 짝지어지지 않아요. 조각 하나가 여러 segment를 덮거나, segment 하나가 여러 조각으로 나뉠 수 있어요.
• 확정된 조각의 text를 도착한 순서대로 구분자 없이 이어 붙이면 번역문이 돼요. 조각은 단어 중간에서 나뉠 수 있으니 조각 사이에 공백을 넣지 마세요. 공백만 있는 확정 조각은 띄어쓰기라서 그대로 이어 붙이세요.
• 번역은 원문 확정보다 늦게 올 수도, 원문의 isFinal: false보다 먼저 올 수도 있어요.
• 자동 감지 세션에서 transcript.locale이 translationLocale과 같은 segment는 번역하지 않아요. 언어를 지정한 세션에서도 번역 대상 언어로 말한 구간은 번역이 빠질 수 있어요.

​

session.ended

{
  "type": "session.ended",
  "id": "Rt7Yq2PbX9cDk",
  "endReason": "CLIENT_REQUESTED",
  "audioDurationMs": 3605120,
  "endedAt": "2026-11-05T10:01:30Z"
}

​

error

{
  "type": "error",
  "reason": "audio_frame_too_large",
  "message": "Audio frame exceeds 6400 bytes",
  "retryable": false,
  "fatal": true,
  "maxFrameBytes": 6400,
  "receivedBytes": 32000
}

​

종료

​

타임아웃

• 텍스트 메시지는 오디오 없음 타이머를 초기화하지 않아요.
• 음소거하는 동안 연결을 유지한 채 전송을 멈춰도 돼요. 15분 안에 다시 보내면 세션이 이어져요.
• Tiro는 타임아웃 시점보다 늦게 세션을 끝낼 수 있어요. 연결이 있는 세션은 최대 1분, 연결이 없는 세션은 최대 3분쯤 늦어요.

​

재접속

1. session.ended를 받았으면 세션이 끝난 거예요. 다시 연결하지 마세요.
2. 연결을 닫은 error(fatal: true)가 retryable: false면 다시 연결하지 마세요. 연결이 유지되는 오류(fatal: false, 예: invalid_message)는 이 판단에 넣지 마세요.
3. 그 밖의 경우에는 다시 연결하세요. retryable: true인 error를 받았거나 메시지 없이 끊긴 경우예요. close 1012는 서버 재시작이라 바로 다시 연결하고, 나머지는 백오프하세요.

​

끊긴 동안의 오디오는 어떻게 다시 보내나요?

• 연결이 끊긴 동안 최근 오디오를 최대 60초까지 모아 두세요. 그보다 오래된 앞부분은 버리세요.
• 재접속하면 session.started의 audioOffsetMs를 확인하세요. 이 값은 Tiro가 처리를 마친 오디오 길이라서, 직전 연결로 실제 보낸 길이보다 짧을 수 있어요. Tiro가 직전 연결이 끊긴 것을 알기 전에 새 연결이 기존 연결을 대체하면 0일 수도 있어요.
• 세션 타임라인에서 audioOffsetMs 이후에 해당하는 오디오를 버퍼에서 먼저 보내고, 이어서 실시간 오디오를 보내세요. 이렇게 보내도 오디오 선행량 60초 안이에요.
• Tiro는 다시 보낸 오디오가 이미 받은 오디오인지 판단하지 않아요.
• close 1012는 메시지 없이 닫혀서 직전에 보낸 프레임 일부가 Tiro에 닿지 않았을 수 있어요. 이때도 audioOffsetMs 이후 오디오를 다시 보내세요.
• 끊기기 직전까지 isFinal: false였던 segment와 번역 조각은 버리세요. Tiro가 새 연결에서 다시 보내지 않아요.

​

같은 세션에 두 번 연결하면 어떻게 되나요?

• 기존 연결은 error(connection_replaced, retryable: false)를 받고 close 4409로 닫혀요. 기존 연결의 클라이언트는 다시 연결하지 마세요.
• 새 연결은 session.started를 resumed: true로 받고 세션을 이어 가요.

​

WebSocket 에러

​

close code

​

REST 에러