Starting an Oracle Radio WebSocket Audio Transmission
Send a START message after receiving a talk token to begin an audio transmission.
Permissions and Prerequisites
The WebSocket contract accepts PCM, Opus, AAC, and AMR. The supplied Radio browser application transmits and plays only PCM and Opus. AAC and AMR require a client with the appropriate codec; API acceptance doesn't make a format playable in the browser.
| Requirement | Value |
|---|---|
| Authentication | Complete the supported authentication path for the client before sending this operation. See authentication. |
| Radio permission | radio.audio.transmit |
| Channel access | The user must have talk access to the connection's active channel. The service validates the token and active channel when processing START. |
| Session state | The WebSocket connection must be open. First send REQUEST_TALK and receive GRANTED. Use only the talk token granted to the authenticated user, and don't transfer it to another user or client. |
Request
Send the START message as a JSON text message. The service validates the supplied token for the connection's active channel.
| Name | Data type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
type | string | Yes | None | Must be START. | Identifies the start-transmission operation. |
token | string | Yes | None | UUID. | Valid talk token for the channel. |
timestamp | string | No | None | ISO 8601 date and time. | Client-side transmission start time. |
format | string | No | pcm | pcm, opus, aac, or amr. | Audio codec format. |
sampleRate | integer | No | 8000 | Integer value in hertz. | Audio sample rate. |
channels | integer | No | 1 | 1 for mono or 2 for stereo. | Number of audio channels. |
bitrate | integer | No | 16000 | Integer value in bits per second. | Audio bitrate. |
frameSize | integer | No | 20 | Integer value in milliseconds. | Audio frame duration. |
Note
Encode every binary audio packet by using the values declared in
Encode every binary audio packet by using the values declared in
START. Don't change the audio settings during an active transmission.{
"type": "START",
"token": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": "2024-01-15T10:30:00Z",
"format": "opus",
"sampleRate": 8000,
"channels": 1,
"bitrate": 16000,
"frameSize": 20
}Responses
The following table lists the messages the client can receive and explains their purpose.
| Message type | Kind | Description |
|---|---|---|
TRANSMISSION_START | Asynchronous event | Notifies other subscribed connections that audio transmission started and provides the audio settings needed for decoding. |
ERROR | Direct error | Indicates missing or invalid token, missing Radio permission, denied channel access, or another failure to start. |
INTERRUPTED | Asynchronous event | Indicates that another user took the talk floor. Stop sending binary audio. |
TOKEN_EXPIRED | Asynchronous event | Indicates that the talk token expired. Stop sending binary audio. |
TRANSMISSION_TIMEOUT | Asynchronous event | Indicates that the transmission exceeded its allowed duration and the token was automatically released. |
Note
The initiating session doesn't receive
The initiating session doesn't receive
TRANSMISSION_START. After the WebSocket client reports that it successfully sent START, begin sending binary audio messages. If the service sends ERROR, stop sending audio.TRANSMISSION_START Event for Other Subscribers
The following table describes the event properties, their data types, and whether they are required.
| Name | Data type | Required | Description |
|---|---|---|---|
type | string | Yes | Event type. The value is TRANSMISSION_START. |
channel | string | Yes | Channel receiving the audio transmission. |
user | string | Yes | User transmitting the audio. |
senderDisplayName | string | No | Display name of the sender. |
priority | integer | No | Priority of the talk token. |
timestamp | string | No | Transmission start date and time in ISO 8601 format. |
format | string | No | Audio codec format. |
sampleRate | integer | No | Audio sample rate in hertz. |
channels | integer | No | Number of audio channels. |
bitrate | integer | No | Audio bitrate in bits per second. |
frameSize | integer | No | Audio frame duration in milliseconds. |
{
"type": "TRANSMISSION_START",
"channel": "operations",
"user": "dispatcher1",
"senderDisplayName": "Dispatcher One",
"priority": 50,
"timestamp": "2024-01-15T10:30:00Z",
"format": "opus",
"sampleRate": 8000,
"channels": 1,
"bitrate": 16000,
"frameSize": 20
}