# `PhoenixKitAI.Realtime.Session`
[🔗](https://github.com/BeamLabEU/phoenix_kit_ai/blob/0.19.3/lib/phoenix_kit_ai/realtime/session.ex#L1)

Owns one xAI realtime WebSocket connection (`Xai.Realtime`) on behalf of a
single Playground LiveView, forwarding audio chunks and events to it as
plain messages.

Runs under `PhoenixKitAI.Realtime.Supervisor` (a `DynamicSupervisor`
contributed via `PhoenixKitAI.children/0`) with `restart: :temporary` — a
dead session is not auto-restarted, the LiveView re-triggers "start voice"
itself.

## Cleanup

`Xai.Realtime.connect_tts/1` is called from `init/1`, so the WebSockex
connection links to *this* process, not the owning LiveView — a socket
crash only takes down the session. The reverse direction (LiveView goes
away) is handled by monitoring `live_view_pid`: LiveView's own
`terminate/2` isn't reliably called without `trap_exit`, so closing the
connection is driven from here via the `:DOWN` message instead.

# `start_opts`

```elixir
@type start_opts() :: [
  live_view_pid: pid(),
  api_key: String.t(),
  voice: String.t(),
  language: String.t(),
  codec: String.t(),
  sample_rate: pos_integer(),
  realtime_module: module()
]
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `close`

```elixir
@spec close(pid()) :: :ok
```

Close the realtime connection and stop the session.

# `finish`

```elixir
@spec finish(pid()) :: :ok
```

Signal end of the current utterance.

# `send_text`

```elixir
@spec send_text(pid(), String.t()) :: :ok
```

Send text to be spoken.

# `start_link`

```elixir
@spec start_link(start_opts()) :: GenServer.on_start()
```

---

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