Voice live
The Voice live screen lets you open a realtime voice session, talk through your microphone and follow the
transcript and the usage of the session. Portal path: /multimodal/voice. Developers use it to test the voice
pipeline before an agent uses it.
What the screen shows
The page title is Voice live tester. The Realtime session section holds:
- Pipeline: Echo (loopback) (
echo, default) or Speech to text (stt); - Voice:
alloy(default),verse,aria,sage; - the Start button while idle; once a session is open, Mute (or Unmute) and End;
- a status badge: Idle, Connecting or Connected;
- the session id after the start, and the last error if any.
The Transcript section shows the lines of You and Agent as they arrive ("The transcript appears here while you talk." before the first line), then the usage of the session (units and cost) when the server sends it.
The browser receives a LiveKit token, publishes your microphone (echo cancellation and noise suppression on) and plays the agent audio. A control WebSocket carries the transcript and usage events; when it closes unexpectedly, the portal reconnects a bounded number of times with a new single use token.
Actions
| Button or action | What it does | API call | Roles |
|---|---|---|---|
| Start | Creates the session with the pipeline and the voice, joins the LiveKit room, opens the control socket | POST /v1/realtime/sessions | tenant_admin, developer, agent |
| Automatic reconnection | Asks a new WebSocket token for the open session | POST /v1/realtime/sessions/{session_id}/token | tenant_admin, developer, agent |
| Mute / Unmute | Turns the microphone off or on in the room (no API call) | none | the session owner |
| End | Closes the socket and the room, then ends the session and records its usage | POST /v1/realtime/sessions/{session_id}/end | tenant_admin, developer, agent |
Roles
The portal shows every button. In services/control-plane/src/eai/domains/realtime/__init__.py creating, renewing the
token and ending a session need tenant_admin, developer or agent, and the creation goes through the policy
decision realtime.session.create. A user opens a session on their own behalf only.
Typical tasks
Check the audio path with the echo pipeline
-
Start a session. The echo pipeline plays back what you say, without any model. Keep Pipeline on Echo (loopback), click Start and allow the microphone in the browser.
Expected result: the badge goes to Connected and the session id appears.
If it fails: an error under the buttons gives the code; refused microphone access stops the start.
-
End it. Click End.
Expected result: the badge goes back to Idle and the usage of the session appears under the transcript.
If it fails: the session is ended by the server anyway when it is already closed.
Test speech to text
-
Record the consent. Outside the dev and test environments, transcription needs an active consent of the participant. Start a session, copy its id and record the consent in Voice consents.
Expected result: a consent with Transcription allowed set.
If it fails: see the voice consents page.
-
Talk. Choose Pipeline Speech to text, click Start and speak.
Expected result: lines of You appear in Transcript.
If it fails:
consent_requiredmeans no active consent covers the transcription.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
forbidden (403) on Start | You are not tenant_admin, developer or agent | Ask for the developer role |
invalid_request (400) with pipeline | Unknown pipeline | Use echo or stt |
| Error 503 on Start outside dev and test | The LiveKit credentials are missing or weak | Set strong LiveKit credentials on the Control Plane |
livekit_unavailable (502) | The LiveKit server cannot be reached or refused the call | Check the LiveKit service and the egress rules |
| "The realtime event socket failed" | The control WebSocket could not open | Check that the WebSocket route of the Control Plane is reachable |
| "The realtime event socket closed and could not reconnect" | The reconnection attempts are exhausted | Click End, then Start again |
session_ended (409) on reconnection | The session was ended | Start a new session |
consent_required (403) | No active consent for the transcription or the recording | Record it in Voice consents |
stt_failed (502) | The speech to text adapter failed on an audio chunk | Retry; check the speech model |