# `Xai.Realtime`
[🔗](https://github.com/beamlab-xai/xai/blob/main/lib/xai/realtime.ex#L1)

WebSocket client for xAI realtime voice and streaming TTS.

xAI exposes realtime features over WebSocket (not gRPC):
- `wss://api.x.ai/v1/realtime` for full voice agents (bidirectional audio + text)
- `wss://api.x.ai/v1/tts` for bidirectional streaming TTS

This module uses Websockex. It is separate from the gRPC `Xai.Client`
because the transports are different.

## Example: Streaming TTS

    {:ok, pid} = Xai.Realtime.connect_tts(
      api_key: System.get_env("XAI_API_KEY"),
      voice: "eve",
      codec: "mp3",
      on_audio: fn audio_chunk -> play_audio(audio_chunk) end
    )

    Xai.Realtime.send_text(pid, "Hello from Elixir. ")
    Xai.Realtime.send_text(pid, "This is streaming TTS.")
    Xai.Realtime.send_text_done(pid)

For full realtime voice agents, use `connect_realtime/1` and handle events.

# `on_audio`

```elixir
@type on_audio() :: (binary() -> any())
```

# `on_event`

```elixir
@type on_event() :: (map() -> any())
```

# `t`

```elixir
@type t() :: pid()
```

# `close`

Close the connection gracefully.

# `connect_realtime`

```elixir
@spec connect_realtime(keyword()) :: {:ok, t()} | {:error, term()}
```

Connect to the full realtime voice agent endpoint.

Similar options, plus session configuration sent after connect.

# `connect_tts`

```elixir
@spec connect_tts(keyword()) :: {:ok, t()} | {:error, term()}
```

Connect for streaming TTS (text → audio chunks).

Options:
  - `:api_key` (required, or XAI_API_KEY env)
  - `:voice` - default "eve"
  - `:language` - default "en"
  - `:codec` - mp3, wav, pcm, etc.
  - `:sample_rate`
  - `:on_audio` - callback for base64-decoded audio chunks
  - `:on_event` - callback for all JSON events (optional)

# `send_event`

Send raw event (for advanced realtime use).

# `send_text`

Send a text delta for TTS or conversation.

# `send_text_done`

Signal end of text for current utterance (TTS).

# `text_clear`

Builds a text.clear event for barge-in.

# `text_delta`

```elixir
@spec text_delta(String.t()) :: map()
```

Builds a text.delta event. Useful for testing and for users who want raw events.

# `text_done`

Builds a text.done event.

---

*Consult [api-reference.md](api-reference.md) for complete listing*