Connecting over SRT

View as Markdown

Realtime Media Streams (RTMS) can deliver media and data over Secure Reliable Transport (SRT) connections instead of WebSocket connections. This topic explains how to connect directly to the RTMS server over SRT, without the RTMS SDK. Signaling stays on a secure WebSocket. SRT replaces the transport for data connections only.

Protocol V2 or later is required. You also need an SRT endpoint returned by a successful signaling handshake. The examples use a Zoom Meetings stream with audio and video available.

The signaling connection is a WebSocket connection, so it must use TLS 1.2 or 1.3. The SRT data connections aren't affected. For details, see TLS requirements.

Connection flow

Each data connection uses two handshakes:

  • The SRT transport connection.
  • The RTMS data handshake.

A successful SRT connection doesn't authorize or start media delivery on its own.

Sequence diagram of an SRT connection. The app completes the signaling handshake over WebSocket, connects over SRT, completes a length-prefixed data handshake, sends CLIENT_READY_ACK, receives media, and exchanges keep-alives on both connections.

The diagram shows the order of the handshakes, connections, and messages. Each step is described in the sections below.

Keep the WebSocket signaling connection open for the whole session. Use the same message format, JSON or protobuf, for signaling and for all data connections. The transport can differ: WebSocket for signaling, SRT for data.

Prerequisites

Before you connect, make sure you have:

  • An active RTMS stream, its instance identifier for your product, and the signature required by the RTMS authentication protocol.
  • An SRT client with encryption and caller-mode support, with access to the UDP host and port that RTMS returns.
  • Binary-safe handling for credentials, and the length-prefixed framing described in SRT message framing. A general-purpose SRT player doesn't implement the RTMS handshake or message format.

Negotiate SRT credentials on signaling

The signaling handshake returns the SRT endpoint and passphrase. Send the handshake over WebSocket, and read the endpoint and passphrase from the response.

JSON signaling example

Send this signaling handshake request over WebSocket.

{
    "msg_type": 1,
    "protocol_version": 2,
    "meeting_uuid": "meeting-123",
    "rtms_stream_id": "stream-123",
    "signature": "<RTMS authentication signature>",
    "sequence": 1001
}

A successful response that offers SRT looks like this.

{
    "msg_type": 2,
    "protocol_version": 2,
    "status_code": 0,
    "reason": "OK",
    "sequence": 1001,
    "media_server": {
        "server_urls": {
            "audio": "wss://rtms.example:443,srt://rtms.example:9000",
            "video": "wss://rtms.example:443,srt://rtms.example:9000"
        }
    },
    "srt_passphrase": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=",
    "srt_pbkey_length": 32,
    "payload_encrypted": false
}

Both the signaling and data handshakes must include exactly one non-empty instance identifier for your product: meeting_uuid for Zoom Meetings, webinar_uuid for Zoom Webinars, session_id for the Video SDK, engagement_id for Zoom Contact Center, or call_id for Zoom Phone. Use the same instance identifier and rtms_stream_id on both connections. The SRT passphrase doesn't replace the RTMS signature.

Validate the response and select an endpoint

Continue only if status_code is 0 and the negotiated protocol version is at least 2. For each required media type, do the following:

  1. Read its value in media_server.server_urls.
  2. Split that value on commas, and select the srt:// URL. A field can contain more than one transport option, so don't pass the whole comma-separated string to an SRT library.
  3. Use the hostname and UDP port from that URL. Don't assume the SRT port matches the WebSocket port, or that different media types use different ports.
  4. Confirm that srt_passphrase and srt_pbkey_length are present and supported. For JSON, Base64-decode the passphrase once. For protobuf, use the bytes as they are. The passphrase is 32 opaque bytes.

The following table maps each returned media field to the media_type you send in the data handshake and the msg_type you receive on that connection:

Returned fieldmedia_typemsg_type
audio114
video215
deskshare416
transcript817
chat1618

Open a separate data connection for each media type you need. Even if two fields return the same SRT URL, each media type needs its own data handshake.

Keep these rules in mind:

  • V2 rejects media_type 32 (ALL). Request only the media types that the stream grants.
  • If RTMS doesn't return an SRT URL for a required media type, SRT isn't available for that stream.
  • You can use a returned WebSocket URL only if your application's transport policy allows it.
  • Treat missing or malformed credentials as setup errors. Never substitute an empty passphrase.

Open the SRT connection

The client is the SRT caller, and it connects to the RTMS endpoint from the signaling handshake response. RTMS uses AES-256-CTR encryption by default, the standard SRT mode for this flow.

Set these SRT socket options  before you connect. The stream ID, passphrase, and key length must match the values from the signaling handshake response, or the SRT connection can't set up encryption.

OptionRequired client behavior
SRTO_TRANSTYPESRTT_FILE. This flow uses SRT stream mode, even though it carries real-time media.
SRTO_STREAMIDThe exact rtms_stream_id, such as stream-123. Don't use the meeting UUID, a media name, or a structured #!::... stream ID.
SRTO_PASSPHRASEThe raw passphrase bytes that RTMS returned, with their exact byte length.
SRTO_PBKEYLENThe srt_pbkey_length value, in bytes, not bits. The AES-256-CTR profile uses 32, not 256.
SRTO_ENFORCEDENCRYPTIONRTMS keeps this enabled by default (true). Don't allow an unencrypted fallback. Clients don't need to set it.

Keep the socket bidirectional. The client must send its RTMS handshake and keep-alive replies on the same socket, even when media only flows downstream. Don't send an HTTP upgrade request or WebSocket frames over the SRT connection.

Your application must:

  1. Call srt_startup() before connecting.
  2. Resolve the returned endpoint into peer.
  3. Pass the decoded passphrase bytes and srt_pbkey_length to connect_rtms_srt().
  4. Call srt_close() to close each socket.
  5. Call srt_cleanup() when libsrt is no longer in use.

This C++ helper uses the public libsrt API.

#include <srt/srt.h>
#include <stdexcept>
#include <string>
#include <vector>

SRTSOCKET connect_rtms_srt(const sockaddr* peer, int peer_len,
                           const std::string& stream_id,
                           const std::vector<unsigned char>& passphrase,
                           int pbkey_length) {
    if (stream_id.empty() || stream_id.size() > 512 ||
        passphrase.size() != 32 ||
        (pbkey_length != 16 && pbkey_length != 24 && pbkey_length != 32)) {
        throw std::invalid_argument("Invalid SRT connection credentials");
    }
    SRTSOCKET sock = srt_create_socket();
    if (sock == SRT_INVALID_SOCK) {
        throw std::runtime_error(srt_getlasterror_str());
    }
    try {
        auto set = [&](SRT_SOCKOPT name, const void* value, int size) {
            if (srt_setsockflag(sock, name, value, size) == SRT_ERROR) {
                throw std::runtime_error(srt_getlasterror_str());
            }
        };
        SRT_TRANSTYPE type = SRTT_FILE;
        set(SRTO_TRANSTYPE, &type, sizeof(type));
        set(SRTO_STREAMID, stream_id.data(), static_cast<int>(stream_id.size()));
        set(SRTO_PASSPHRASE, passphrase.data(), static_cast<int>(passphrase.size()));
        set(SRTO_PBKEYLEN, &pbkey_length, sizeof(pbkey_length));
        if (srt_connect(sock, peer, peer_len) == SRT_ERROR) {
            throw std::runtime_error(srt_getlasterror_str());
        }
        return sock;
    } catch (...) {
        srt_close(sock);
        throw;
    }
}

Complete the RTMS data handshake

After the SRT connection opens, send the RTMS data handshake as the first message on that socket. Each message is framed as described in SRT message framing.

JSON audio example

Send this UTF-8 JSON body, prefixed with its length.

{
    "msg_type": 3,
    "protocol_version": 2,
    "meeting_uuid": "meeting-123",
    "rtms_stream_id": "stream-123",
    "signature": "<RTMS authentication signature>",
    "media_type": 1,
    "sequence": 2001,
    "media_params": {
        "audio": {
            "content_type": 2,
            "codec": 1,
            "sample_rate": 1,
            "channel": 1,
            "data_opt": 2,
            "send_rate": 20
        }
    }
}

RTMS responds with a handshake response that also has the length prefix.

{
    "msg_type": 4,
    "protocol_version": 2,
    "status_code": 0,
    "reason": "OK",
    "sequence": 2001,
    "connection_id": "conn-audio-1",
    "payload_encrypted": false,
    "media_params": {
        "audio": {
            "content_type": 2,
            "codec": 1,
            "sample_rate": 1,
            "channel": 1,
            "data_opt": 2,
            "send_rate": 20
        }
    }
}

This example requests L16 audio (codec: 1) at 16 kHz (sample_rate: 1), mono (channel: 1), with a separate audio stream for each user (data_opt: 2). Decode the audio using the media_params in the response.

Before you treat the connection as ready, check the data handshake response:

  • status_code is 0.
  • The protocol version is the one you expect.
  • payload_encrypted matches the signaling response.

A data handshake can't change the signaling version or turn on payload encryption on its own. Don't add srt_passphrase or srt_pbkey_length to the RTMS data request. Those values belong to the transport setup.

Repeat the SRT connection and the RTMS handshake for each other media type you need, with that media type's endpoint and parameters. All data connections for a stream use the same signaling credentials. The connection_id identifies a data connection. It isn't the SRT SRTO_STREAMID value. If you need a connection-specific video subscription, send it on the signaling connection and include that data connection's connection_id.

Signal readiness and receive media

After every required data handshake succeeds, send a CLIENT_READY_ACK message over the WebSocket signaling connection.

{
    "msg_type": 7,
    "rtms_stream_id": "stream-123"
}

RTMS responds with a STREAM_STATE_UPDATE message on the same connection. It reports the stream as active.

{
    "msg_type": 8,
    "rtms_stream_id": "stream-123",
    "state": 1,
    "timestamp": 1780000000000
}

Process each complete SRT record according to its msg_type. The media format depends on the message encoding:

PayloadJSON bodyProtobuf body
Audio, video, or deskshare without application-layer encryptionBase64 media in content.dataRaw media bytes in content.data
Transcript or chat without application-layer encryptionText stringUTF-8 text in bytes
Application-layer encrypted media or textBase64 encryption envelopeRaw encryption envelope bytes

This JSON example is an audio message with two sample bytes.

{
    "msg_type": 14,
    "content": {
        "user_id": 10001,
        "user_name": "Ada",
        "source": 1,
        "data": "AAA=",
        "length": 2,
        "timestamp": 1780000000000
    }
}

Send the message body with the SRT length prefix in front of it. For the framing rules, see SRT message framing. The packet size in this example is illustrative. Real audio packet sizes depend on the negotiated format and delivery cadence.

content.length is the number of decoded media bytes in content.data. When application-layer encryption is on, it's the number of encryption envelope bytes instead. It doesn't include the serialized message or the length prefix.

SRT transport encryption and payload_encrypted are separate settings. The signaling and data handshake examples use encrypted SRT transport with payload_encrypted set to false. Application-layer encryption is negotiated during the signaling handshake. For details, see Signaling handshake request. The SRT passphrase isn't an application-layer media key.

Respond to keep-alives

RTMS sends keep-alive requests on the signaling connection and on each active data connection. Respond to every request to keep the connections open. A keep-alive request in JSON has this format.

{
    "msg_type": 12,
    "sequence": 7,
    "timestamp": 1780000001000
}

Your reply uses the same message format.

{
    "msg_type": 13,
    "sequence": 7,
    "timestamp": 1780000001000
}

Follow these rules when you reply.

  • Reply on the same connection that sent the request. For the message fields, see Keep-alive request and Keep-alive response.
  • Echo the timestamp and sequence from the request. Don't generate a new timestamp.
  • Add the SRT length prefix to replies on SRT. Send replies on WebSocket as ordinary WebSocket messages.
  • Keep processing keep-alives when no media is arriving. Don't block the receive loop on media decoding or storage.

SRT's own transport keep-alives don't replace these RTMS messages.

Reconnect and end the session

If a connection drops, use the table below to decide what to do next.

SituationClient action
A data connection drops while signaling is still activeReopen the SRT connection for that media type with the current endpoint and credentials, then repeat the RTMS data handshake. Reconnect promptly while the stream is still active.
Signaling drops, or a new signaling handshake succeedsTreat the earlier data setup as obsolete. Complete signaling again, use the new endpoints and passphrase, and rebuild the required data connections before you send readiness.
A replacement data response returns a new connection_idReplace the old connection_id. Re-establish any connection-specific video subscription on signaling with the new ID.
The stream is terminated with a stop_reason of 10–19 or 24Restart the entire RTMS connection process from the beginning.
The stream is terminated with any other stop_reasonClose the data and signaling connections, and don't restart the stream. For example, stop_reason 8 (stream revoked) requires you to delete assets immediately.

A data-only reconnect doesn't negotiate a new SRT passphrase or application-layer key. A new successful signaling handshake returns a new SRT credential, so don't reuse a credential from an earlier handshake.

Start each replacement data connection with an empty framing buffer. Reconnecting doesn't guarantee that media lost during the interruption is delivered again. Follow stream state and interruption events on signaling.

To end the whole stream, send STREAM_CLOSE_REQ (msg_type: 21) with the rtms_stream_id over signaling, and handle the STREAM_CLOSE_RESP (msg_type: 22). Release the SRT sockets and credentials when the stream ends.

Troubleshoot

Transport failures happen before the RTMS data handshake, so they may not produce an RTMS error response. Record the SRT error separately from RTMS status codes. Don't include credentials or authentication signatures in logs.

Symptom or statusCheck and client action
No SRT endpoint or credential in the signaling responseConfirm protocol V2 and status_code 0. Use only the returned endpoints, and use WebSocket only if your transport policy allows it.
SRT connection times outCheck DNS, the returned UDP port, firewall and NAT reachability, and that signaling is still active.
SRT encryption or key-management failureCheck the exact SRTO_STREAMID, the latest passphrase, Base64 decoding for JSON or raw bytes for protobuf, the explicit byte length, and that SRTO_PBKEYLEN is in bytes. Keep enforced encryption on.
SRT rejects the modeUse SRTT_FILE and SRTO_MESSAGEAPI set to false. Don't use the library's default live or message mode.
SRT connects, but no RTMS handshake response arrivesSend the msg_type 3 handshake right after connecting, with a 4-byte big-endian body length. Check the JSON or protobuf body format, partial writes, and the instance identifier and signature.
RTMS status 2 (INVALID_RTMS_STREAM_ID)Verify the stream ID and that the stream hasn't ended. The SRT stream ID and the RTMS handshake stream ID must refer to the same stream.
RTMS status 3 (INVALID_SIGNATURE)Provide the valid RTMS authentication signature. The SRT passphrase isn't a signature.
RTMS status 4 (INVALID_PAYLOAD)Check the required handshake fields, exactly one instance identifier, and the message body structure.
RTMS status 16 (DUPLICATE_MEDIA_DATA_CONNECTION)Check for an existing or pending connection for that media type. Avoid starting duplicate reconnect attempts at the same time.
RTMS statuses 17 to 39 (media parameter errors)Correct the media-specific parameters and enum values. For example, sample rate is an enum, not a value in Hz.
RTMS status 48 (MEDIA_DATA_TYPE_ALL_NOT_SUPPORTED)Open a separate connection for each media type, and remove media_type 32.
RTMS status 50 (PROTOBUF_V2_REQUIRED)Request protocol V2 or later for protobuf signaling.
RTMS status 51 (DATA_HANDSHAKE_REQUIRES_ACTIVE_SIGNAL)Complete the signaling handshake successfully before the data handshakes.
RTMS status 52 (HANDSHAKE_MESSAGE_FORMAT_MISMATCH)Use the same JSON or protobuf format on the data connection as on signaling. The transport can differ.
Connections succeed, but no media arrivesComplete the required data handshakes, send readiness on signaling, check the stream state, and keep processing both connections. Some media only appears when related activity occurs.
Connection drops even though media is arrivingRespond to RTMS keep-alives on every connection. Receiving media doesn't replace the required replies.