Publishing and Receiving Audio

You can publish audio, receive translated audio, and control the translation through either transport:

• WebRTC — best for client applications (browsers, mobile apps). Handled by LiveKit.
• WebSockets — convenient for server-side integrations. Authenticate with your API Key directly — see Translation management API for the connection details.

For WebRTC (or if you manage sessions yourself), create a session on your backend with POST /session-storage/v2/sessions. Set intent: "s2s" and the appropriate connection_type:

Purpose	Response body field	Use
Authentication	data.token	Opaque session token for the selected product and transport
WebRTC connection	data.webrtc.url	Room connection URL; present for connection_type: "webrtc" only
WebRTC room	data.webrtc.room_name	Room name; present for connection_type: "webrtc" only
Cleanup	data.id	ID for inspecting or deleting the session

For WebSockets, use the product endpoint with data.token; v2 sessions do not return a ws_url. For browser or mobile clients, see Temporary Sessions.

info

Regardless of the transport, you control the translation by sending JSON text messages — through the WebRTC data channel or the WebSocket connection respectively. See the Translation management API.

If you choose WebSockets as the audio transport, the audio chunks you push must match the format / sample_rate / channels declared in your set_task command.

Using the WebRTC Transport

Use any LiveKit client library to publish your audio track, then create a translation task using the Translation management API. Palabra will publish a translated audio track for each target language.

Before sending set_task, wait for a participant whose identity starts with palabra_translator_, checking existing participants and later joins. Register your response handler first, then send the command over the default (empty-topic) data channel with reliable delivery (reliable: true in JavaScript).

The translator's presence does not guarantee that its data channel or command handler is ready. Repeat the same complete set_task after about 1–1.25 seconds with capped backoff until task_status confirms data.command: "set_task" and data.task_status: "running". Stop retries on confirmation, a server error, cancellation, disconnection, or an overall timeout. Successful publication alone does not confirm startup, and an unchanged acknowledgement is valid after a retry.

See Step 6 of the WebRTC Quick Start for the helper and cleanup, and Step 3 for version compatibility. Over WebSockets, send set_task once the connection is open and wait for its acknowledgement before streaming audio chunks.

• LiveKit Python SDK
• LiveKit Golang SDK
• LiveKit JS SDK
• See other SDKs here.

Code Examples

See the WebRTC Quick Start for publishing original audio (Step 4) and receiving translated audio (Step 5).

Using the WebSocket Transport

Connect to the WebSocket endpoint using your API Key (or use a v2 session token with intent: "s2s" and connection_type: "ws" — see Translation management API), create a translation task, then start sending and receiving audio chunks as described below.

Publishing

Send base64-encoded audio chunks over the WebSocket. The chunks must match the format, sample_rate, and channels declared in your set_task command. The optimal chunk length is 320 ms.

Message format example:

{
  "message_type": "input_audio_data",
  "data": {
    "data": "base64 encoded data"
  }
}

Receiving

Palabra sends TTS audio chunks as output_audio_data messages over the same WebSocket connection. The chunks are base64-encoded; the default format is 24 kHz 16-bit mono PCM (can be changed with the set_task command).

Message format example:

{
  "message_type": "output_audio_data",
  "data": {
    "transcription_id": "190983855fe3404e",
    "language": "es",
    "last_chunk": false,
    "data": "base64 string"
  }
}