# Voice agent qua WebSocket

Stream chữ từ LLM vào, nhận audio PCM ra theo từng câu, trên một kết nối.

Với voice agent, LLM sinh chữ từng mảnh và người dùng không muốn chờ cả câu trả lời. Mở một WebSocket tới `wss://api.example.com/v1/audio/speech/stream`, gửi chữ ngay khi có, và phát audio ngay khi nhận.

Đặc tả đầy đủ của giao thức: [`/asyncapi.yaml`](/asyncapi.yaml) (AsyncAPI 3.0).

## Sơ đồ message

```text
Client                                         Sota Voice
  │  GET /v1/audio/speech/stream (upgrade)          │
  │  Authorization: Bearer sk_live_... hoặc ?token= │
  │ ───────────────────────────────────────────────▶│
  │ ◀─────────────────────────── 101 Switching ─────│
  │                                                 │
  │  {"type":"session.config","session":{...}}      │
  │ ───────────────────────────────────────────────▶│
  │ ◀──────────── {"type":"session.configured",...} │
  │                                                 │
  │  {"type":"input.text","text":"Xin chào, "}      │
  │ ───────────────────────────────────────────────▶│
  │  {"type":"input.text","text":"tôi là Sota."}    │
  │ ───────────────────────────────────────────────▶│
  │ ◀──────────────────────── {"type":"audio.start"}│
  │ ◀────────────────────────────── [binary audio] │  (nhiều frame)
  │ ◀───────────────────────── {"type":"audio.done"}│  (hết một câu)
  │                                                 │
  │  {"type":"input.commit"}   (hết lượt, giữ kết nối)
  │ ───────────────────────────────────────────────▶│
  │ ◀────── ... audio còn lại ... {"type":"input.committed"}
  │                                                 │
  │  {"type":"input.done"}     (kết thúc phiên)     │
  │ ───────────────────────────────────────────────▶│
  │ ◀────── ... audio còn lại ... {"type":"session.done"}
  │ ◀─────────────────────────── close 1000 ────────│
```

1. Gửi `session.config` trước tiên và chờ `session.configured`.
2. Gửi bao nhiêu `input.text` cũng được. Server tự tách câu; với mỗi đoạn được sinh, bạn nhận `audio.start`, các frame audio nhị phân, rồi `audio.done`.
3. Gửi `input.commit` để đọc hết phần chữ đã gửi mà vẫn giữ kết nối (server trả `input.committed` khi audio của phần đó xong), hoặc `input.done` để đọc hết và kết thúc: server gửi `session.done` rồi đóng kết nối.

## Message client gửi

Mọi message là JSON object trong text frame. Chỉ có bốn `type`, phân biệt hoa thường:

| `type` | Field | Ý nghĩa |
|---|---|---|
| `session.config` | `session` | Cấu hình giọng và định dạng. Gửi đầu tiên. |
| `input.text` | `text` | Chữ cần đọc, tính phí theo ký tự. |
| `input.commit` | (không có) | Đọc hết phần đã gửi, giữ kết nối. |
| `input.done` | (không có) | Đọc hết phần đã gửi rồi kết thúc phiên. |

Field của `session`: `voice` (giọng có sẵn hoặc `name` giọng đã nhân bản, mặc định `default`), `response_format` (`pcm` mặc định, hoặc `mp3`, `wav`, `opus`, `aac`, `flac`), `stream_audio` (gửi frame ngay khi sinh thay vì cả đoạn), `split_granularity` (`sentence` mặc định hoặc `clause`; giá trị khác: lỗi `invalid_request`), `literal_punctuation`.

Server kiểm tra từng message trước khi chuyển đi:

- `type` khác bốn giá trị trên: sự kiện `error` với `code: invalid_request` (`unsupported message type`).
- Chỉ nhận đúng các field đã liệt kê. Field lạ, field lặp lại, hoặc field chỉ khác chữ hoa thường (`Voice`) đều bị từ chối.
- Message bị từ chối không được gửi đi, không bị tính phí, và phiên vẫn mở.
- Client không được gửi binary frame: kết nối bị đóng với mã `1003` (`binary_not_supported`).

## Message server gửi

| Message | Ý nghĩa |
|---|---|
| `session.configured` | Cấu hình đã nhận (`session_id`, `response_format`, `stream_audio`, `split_granularity`). Bắt đầu gửi chữ. |
| `audio.start` | Bắt đầu audio của một đoạn. |
| binary frame | Audio theo `response_format`. Với `pcm`: 16-bit có dấu little-endian, mono, 44,1 kHz. Ghép các frame theo thứ tự. |
| `audio.done` | Hết audio của đoạn. |
| `input.committed` | Toàn bộ chữ đến `input.commit` đã đọc xong. |
| `session.done` | Sau `input.done`; server đóng kết nối (1000). |
| `error` | Có lỗi, xem bảng dưới. |

## Lỗi và đóng kết nối

Lỗi trước khi upgrade là lỗi JSON HTTP thường (`401 unauthorized`, `402 insufficient_credit`, `429 rate_limited`, `503 upstream_unavailable`), không mở WebSocket. Sau khi mở, lỗi đến dưới dạng sự kiện `error`. Lỗi của gateway có `code`; lỗi từ dịch vụ giọng nói chỉ có `message`.

| `code` | Khi nào | Sau đó |
|---|---|---|
| `insufficient_credit` | Hết credit giữa phiên | Đóng kết nối, mã `1008` |
| `voice_not_found` | `session.voice` không tồn tại | Phiên vẫn mở; gửi lại `session.config` đúng |
| `input_too_long` | Một `input.text` vượt giới hạn mỗi message (mặc định 5.000 ký tự) | Phiên vẫn mở; chữ không được gửi, không tính phí |
| `invalid_request` | Text frame không phải JSON object hợp lệ, hoặc sai field | Phiên vẫn mở |
| `rate_limited` | Quá số phiên đồng thời (thường đã trả `429` trước upgrade) | Thử lại sau |
| `upstream_unavailable` | Dịch vụ giọng nói lỗi hoặc ngắt phiên | Đóng kết nối, mã `1013` |
| `internal_error` | Lỗi gateway ngoài dự kiến | Đóng kết nối, mã `1011` |

Lý do đóng khác: `idle_timeout` (mã `1000`, không có `input.text` trong 5 phút) và `binary_not_supported` (mã `1003`).

## Tính phí

Mỗi `input.text` tốn số ký tự của `text` (code point NFC, tính cả khoảng trắng và dấu câu). Phiên cần số dư lớn hơn 0 để mở. Credit được giữ trước theo lô 1.000 ký tự; số dư có thể âm tối đa một lô trong một phiên, và phần giữ chưa dùng được trả lại khi phiên kết thúc. Chữ đã chuyển đi vẫn bị tính phí dù bạn ngắt kết nối.

## Ví dụ: voice agent bằng Python

Server-side, dùng khóa API. LLM ở đây là một API chat bất kỳ có stream; mỗi mảnh chữ được gửi ngay thành một `input.text`.

```python
import asyncio
import json
import os

import websockets  # pip install websockets
from openai import AsyncOpenAI  # LLM của bạn, ví dụ dùng API chat tương thích OpenAI

URL = "wss://api.example.com/v1/audio/speech/stream"
llm = AsyncOpenAI()  # đọc OPENAI_API_KEY của nhà cung cấp LLM

async def speak_turn(ws, question: str) -> None:
    stream = await llm.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": question}],
        stream=True,
    )
    async for chunk in stream:
        delta = chunk.choices[0].delta.content if chunk.choices else None
        if delta:
            await ws.send(json.dumps({"type": "input.text", "text": delta}))
    # Hết lượt: đọc nốt phần còn lại nhưng giữ kết nối cho lượt sau.
    await ws.send(json.dumps({"type": "input.commit"}))

async def receive(ws, out) -> None:
    async for msg in ws:
        if isinstance(msg, bytes):
            out.write(msg)  # PCM s16le, mono, 44.1 kHz: đưa vào bộ phát của bạn
            continue
        event = json.loads(msg)
        if event["type"] == "input.committed":
            print("đã đọc xong một lượt")
        elif event["type"] == "error":
            print("lỗi:", event.get("code"), event["message"])
        elif event["type"] == "session.done":
            return

async def main() -> None:
    headers = {"Authorization": f"Bearer {os.environ['SOTA_API_KEY']}"}
    async with websockets.connect(URL, additional_headers=headers) as ws:
        await ws.send(json.dumps({
            "type": "session.config",
            "session": {"voice": "default", "response_format": "pcm", "stream_audio": True},
        }))
        configured = json.loads(await ws.recv())
        assert configured["type"] == "session.configured", configured

        with open("agent.pcm", "wb") as out:
            receiver = asyncio.create_task(receive(ws, out))
            await speak_turn(ws, "Giới thiệu ngắn về Hà Nội.")
            await ws.send(json.dumps({"type": "input.done"}))
            await receiver

asyncio.run(main())
```

Nghe thử file PCM: `ffplay -f s16le -ar 44100 -ch_layout mono agent.pcm`.

## Từ trình duyệt

Trang web không được giữ khóa API. Server của bạn cấp token ngắn hạn (xem [Xác thực](/docs-md/authentication.md#browser-token)), trang mở WebSocket với `?token=`. Token sống 5 phút và chỉ dùng cho route này; origin của trang phải được deployment cho phép.

```js
const SAMPLE_RATE = 44100; // PCM s16le, mono
const JITTER_SEC = 0.2; // bộ đệm chống giật: 150-300 ms

// Gọi từ một thao tác của người dùng (click) để trình duyệt cho phép phát âm thanh.
export async function speak(textChunks) {
  // Endpoint của server bạn, gọi POST /v1/tokens bằng khóa API.
  const { token } = await (await fetch('/sota-token', { method: 'POST' })).json();
  const ws = new WebSocket(
    `wss://api.example.com/v1/audio/speech/stream?token=${encodeURIComponent(token)}`,
  );
  ws.binaryType = 'arraybuffer';

  const ctx = new AudioContext({ sampleRate: SAMPLE_RATE });
  let playAt = 0;
  let carry = null; // byte lẻ cuối frame trước (một mẫu có thể bị cắt giữa hai frame)

  function play(bytes) {
    if (carry !== null) {
      const joined = new Uint8Array(bytes.length + 1);
      joined[0] = carry;
      joined.set(bytes, 1);
      bytes = joined;
      carry = null;
    }
    if (bytes.length % 2) {
      carry = bytes[bytes.length - 1];
      bytes = bytes.subarray(0, bytes.length - 1);
    }
    const samples = bytes.length / 2;
    if (!samples) return;
    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.length);
    const buffer = ctx.createBuffer(1, samples, SAMPLE_RATE);
    const channel = buffer.getChannelData(0);
    for (let i = 0; i < samples; i++) channel[i] = view.getInt16(i * 2, true) / 32768;

    const source = ctx.createBufferSource();
    source.buffer = buffer;
    source.connect(ctx.destination);
    // Lần đầu, hoặc khi bộ đệm cạn: lùi thời điểm phát thêm JITTER_SEC để tích đủ dữ liệu.
    if (playAt < ctx.currentTime) playAt = ctx.currentTime + JITTER_SEC;
    source.start(playAt);
    playAt += buffer.duration;
  }

  ws.onopen = () =>
    ws.send(JSON.stringify({
      type: 'session.config',
      session: { voice: 'default', response_format: 'pcm', stream_audio: true },
    }));

  ws.onmessage = async (event) => {
    if (typeof event.data !== 'string') return play(new Uint8Array(event.data));
    const msg = JSON.parse(event.data);
    if (msg.type === 'session.configured') {
      for await (const text of textChunks) ws.send(JSON.stringify({ type: 'input.text', text }));
      ws.send(JSON.stringify({ type: 'input.done' }));
    } else if (msg.type === 'error') {
      console.error(msg.code ?? 'speech_error', msg.message);
    }
  };
}
```

`textChunks` là bất kỳ iterable (đồng bộ hoặc async) nào trả về chuỗi, ví dụ các mảnh chữ từ LLM.

## Mẹo cho realtime

- **Bộ đệm chống giật (jitter buffer) 150-300 ms.** Audio đến theo từng frame qua mạng, khoảng cách giữa các frame không đều. Hãy đệm 150-300 ms trước khi bắt đầu phát, và đệm lại khi bộ đệm cạn, như ví dụ trên. Ít hơn dễ bị ngắt quãng; nhiều hơn làm agent trả lời chậm.
- Dùng `response_format: "pcm"` và `stream_audio: true` cho độ trễ thấp nhất; không cần giải mã.
- Gửi chữ ngay khi LLM sinh ra, đừng gom cả câu: server tự tách câu (`split_granularity`). `clause` tách cả ở dấu phẩy, chắc hơn nhưng ngữ điệu kém liền mạch và tốn GPU hơn.
- Một kết nối cho cả cuộc hội thoại: dùng `input.commit` giữa các lượt, `input.done` khi kết thúc. Phiên tự đóng sau 5 phút không có `input.text`.
- Mỗi tài khoản có giới hạn số phiên/request realtime đồng thời; vượt quá thì nhận `429 rate_limited` ngay, không xếp hàng. Xem [Giới hạn tốc độ](/docs-md/rate-limits.md).

