Public API: Audio | Arcules Knowledge Base

Overview

The WebRTC APIs provide functionality for securely obtaining credentials for WebRTC media communication and initiating audio talkdown (audio-out) sessions. These APIs integrate with the Arcules platform to facilitate real-time communication, such as live streaming and two-way audio, via WebRTC protocols. These endpoints are essential in scenarios where low-latency audio streaming, and communication, is required, especially in security and surveillance systems.

Key Use Cases:

Enable seamless audio communication for remote monitoring and security operations.
Facilitate live audio streaming for events and real-time alerts.
Use TURN servers for secure and reliable audio transmission in restrictive network environments.

Prerequisites

Devices related to the API features covered in this article must first be registered with an Arcules gateway appliance.
Gateway appliance(s) should be online and have an active internet connection.
Users must have the following roles assigned in the Arcules web portal:
- API User Role: To be able to use Audio functionalities through our API.

API Endpoint

Endpoint 1: WebRTC Credentials

HTTP Method: GET

URL: https://msapi.arcules.com/v1/media/webrtc/creds?transport={any|cloud|local}

Authentication: OAuth 2.0 Bearer Token

Request Parameters

Parameter	Type	Description	Required
transport	string	Type of transport (e.g., any, cloud, local).	Yes

Sample Request

GET /v1/media/webrtc/creds?transport=any/cloud/local
Host: msapi.arcules.com
Authorization: Bearer {token}

Sample Response

{
  "creds": {
    "username": "1726........",
    "password": "o1O/UNNA.....=",
    "uris": [
      "turn:turn2.arcules.com:443"
    ],
    "ttl": 300000000000
  }
}

Endpoint 2: Audio Talkdown

HTTP Method: POST

URL: https://msapi.arcules.com/v1/media/webrtc/audio/{audioChannelId}/talkdown?transport={any|cloud|local}

Authentication: OAuth 2.0 Bearer Token

Request Parameters

Parameter	Type	Description	Required
audioChannelId	string	The unique ID of the device where audio talkdown (audio-out) is initiated.	Yes
transport	string	Type of transport (e.g., any, cloud, local).	Yes
X-TurnCred	string	TURN credentials (in JSON format) for secure WebRTC connection.	Yes
X-SessionDescription	string	SDP (Session Description Protocol) for initiating audio communication (Base64 encoded).	Yes

Sample Request

POST /v1/media/webrtc/audio/51ecfd92-c3c8-4c5e-a823-c17e455ce972/talkdown?transport=any/cloud/local
Host: msapi.arcules.com
Authorization: Bearer {token}
X-TurnCred: {"username":"1724444...","password":"8I0..","uris":["turn:turn.arcules.com:443"],"ttl":300000000000} 
X-SessionDescription: eyJ0eXBlIjoi...

Sample Response

{
  "transportType": "any/cloud/local",
  "sdp": "eyJ0eXBlIjoi..."
}

Error Handling

Error Code	Message	Description
200	OK	The request was successful.
400	Bad Request	The request was invalid or cannot be processed.
401	Unauthorized	Missing or invalid JWT.
403	Forbidden	API users lack the necessary permissions.
404	Not Found	The requested resource could not be found.
429	Too Many Requests	API rate limit has been exceeded.
5xx	Server Error	The server encountered an issue processing the request.

Additional Resources

FAQ

Q: How do I authenticate?

A: Use your OAuth 2.0 Bearer Token in the request header. See the Authentication Guide for more details.

Q: How can I obtain the audioChannelId value?

A: You can retrieve the audioChannelId values from the response of the /v1/devices endpoint.

Q: What is the purpose of the TURN credentials?

A: TURN credentials enable secure media communication over WebRTC. They are required to establish a connection for both video and audio sessions.

Q: How long are the WebRTC credentials valid?

A: WebRTC credentials are valid for the duration specified in the ttl field of the response. Typically, this value is in nanoseconds, and a common value like 300000000000 nanoseconds translates to 5 minutes. For security reasons, it’s recommended to re-request credentials before they expire to ensure continuous communication.

Q: What transport types are supported for WebRTC communication?

A: The API supports any, cloud, and local as transport types. The any option allows the system to automatically choose the best available transport. local is preferred over cloud if available.

Q: What should I do if my session description (SDP) is rejected?

A: If the X-SessionDescription is rejected, ensure that the SDP is correctly formatted and base64-encoded. The SDP must be compatible with WebRTC standards. Refer to the WebRTC Protocol Overview for further details.

Q: Can I initiate multiple audio talkdown (audio-out) sessions simultaneously?

A: Yes, you can initiate multiple audio talkdown sessions, but each session must be tied to a unique device ID. Ensure you have valid TURN credentials and session descriptions for each session.

Q: What audio codecs are supported for WebRTC talkdown sessions?

A: The WebRTC talkdown (audio-out) sessions support the G.711 audio codec, which is the expected codec format. The media payload format is raw G.711, ensuring compatibility with various audio communication needs.

Q: Can I use WebRTC in low bandwidth environments?

A: Yes, WebRTC is optimized for real-time communication in low bandwidth environments. However, performance may vary depending on network conditions, and it is recommended to use the cloud transport option for more stable connections.