WebRTC Signaling
Last update：2025-08-14 16:08:28
WebRTC signaling is the process of exchanging metadata to coordinate communication. A core part of this is the Session Description Protocol (SDP), which allows peers to negotiate session parameters like codecs, network paths, and media types. Our service supports two signaling methods: the industry-standard WHIP (WebRTC-HTTP Ingestion Protocol) and WHEP (WebRTC-HTTP Egress Protocol), and a custom HTTP/JSON-based protocol. This guide details the specifics of our custom HTTP/JSON protocol.
Core Principle: Offer/Answer Model
The signaling process relies on the standard WebRTC offer/answer model. The client initiates a session by sending an offer SDP, and the server finalizes the negotiation by returning an answer SDP.
To differentiate between publishing (pushing) and playback (pulling) a stream, our service inspects the attributes within the client’s offer SDP.
- To Publish a Stream (Push): The client’s
offerSDP must include the attributea=sendonly. This indicates that the client intends to send media but not receive it. The server will then respond with ananswerSDP containinga=recvonly. - To Play a Stream (Pull): The client’s
offerSDP must include the attributea=recvonly. This indicates that the client intends to receive media but not send it. The server will respond with ananswerSDP containinga=sendonly.
Important Note:
Sessions with the attribute a=sendrecv (indicating a two-way stream) are not supported. Please ensure your client is configured for either push-only or pull-only operations.
Signaling Endpoint
All signaling communication occurs through a single HTTP endpoint, with the URL specifying the target stream.
URL Format
http://domain/appName/streamName.sdp?params=xxx
| Parameter | Description |
|---|---|
domain |
The domain you configured on Low Latency Streaming (e.g., stream.cdnetworks.com). |
appName |
The application or publishing point name (e.g., live). |
streamName |
The unique name of the stream (e.g., channel_001). |
params |
(Optional) Any additional query parameters (e.g., userid=123). |
This format is intentionally similar to RTMP (rtmp://...) and HTTP-FLV (... .flv) URLs, with the key difference being the .sdp suffix.
API Specification
Request
- Method: POST
- Content-Type:
application/json
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
version |
String | Yes | The API version. Must be the fixed value "v1.0". |
sessionId |
String | No | A client-generated unique ID to identify the session. While optional, it is highly recommended for logging and debugging purposes. |
localSdp |
Object | Yes | An object containing the client’s SDP information. |
Response
Response Body
| Parameter | Type | Required | Description |
|---|---|---|---|
code |
Integer | Yes | The status code of the response. See Status Codes. |
message |
String | Yes | A message describing the status of the response. |
remoteSdp |
Object | Yes | An object containing the server’s answer SDP. |
SDP Object Definition
The localSdp (in the request) and remoteSdp (in the response) objects share the same structure.
| Parameter | Type | Required | Description |
|---|---|---|---|
type |
String | Yes | The SDP type. The client’s request must use "offer". The server’s response will use "answer". |
sdp |
String | Yes | The full, standards-compliant SDP content as a string (see RFC 4566). |
Status Codes
| Code | Message | Description |
|---|---|---|
200 |
success |
The request was successful. |
400 |
body error |
The request body is not valid JSON. |
401 |
parameter error |
One or more required parameters are missing or invalid. |
402 |
information error |
The information provided in the parameters is incorrect. |
403 |
authentication failure |
Authentication failed. |
404 |
stream not found |
The requested stream does not exist. |
600 |
RTC not supported |
The server does not support RTC for this stream; the client must downgrade to another protocol. |
Examples
{
"sessionId": "123456789",
"version": "v1.0",
"localSdp": {
"type": "offer",
"sdp": "v=0\r\no=- 12345 67890 IN IP4 192.0.2.1\r\ns=-\r\nt=0 0\r\na=sendonly\r\nm=video 9 UDP/TLS/RTP/SAVPF 100\r\n..."
}
}
{
"code": 200,
"message": "success",
"remoteSdp": {
"type": "answer",
"sdp": "v=0\r\no=- 98765 43210 IN IP4 198.51.100.1\r\ns=...\r\nt=0 0\r\na=recvonly\r\nm=video 9 UDP/TLS/RTP/SAVPF 100\r\n..."
}
}