The SRT C API (defined in srt.h file) is largely based in design on the legacy UDT API, with some important changes. The API contained in udt.h file contains the legacy UDT API plus some minor optional functions that require the C++ standard library to be used. There are a few optional C++ API functions stored there, as there is no real C++ API for SRT. These functions may be useful in certain situations.

There are some example applications so that you can see how the API is being used, including srt-live-transmit, srt-file-transmit and srt-multiplex. All SRT related material is contained in transmitmedia.* files in the common directory which is used by all applications. See SrtSource::Read and SrtTarget::Write as examples of how data are read and written in SRT.

Setup and teardown

Before any part of the SRT C API can be used, the user should call srt_startup() function. Likewise, before the application exits, the srt_cleanup() function should be called. Note that one of the things the startup function does is to create a new thread, so choose the point of execution for these functions carefully.

Creating and destroying a socket

To do anything with SRT, you have to create an SRT socket first. The term “socket” in this case is used because of its logical similarity to system-wide sockets. An SRT socket is not directly related to system sockets, but like a system socket it is used to define a point of communication.

Synopsis

SRTSOCKET srt_socket(int af, int, int); void srt_close(SRTSOCKET s);

The srt_socket function is based on the legacy UDT API except the first parameter. The other two are ignored.

Note that SRTSOCKET is just an alias for int; this is a legacy naming convention from UDT, which is here only for clarity.

Usage

sock = srt_socket(AF_INET, SOCK_DGRAM, 0);

This creates a socket, which can next be configured and then used for communication.

srt_close(sock);

This closes the socket and frees all its resources. Note that the true life of the socket does not end exactly after this function exits - some details are being finished in a separate “SRT GC” thread. Still, at least all shared system resources (such as listener port) should be released after this function exits.

Important Remarks

1. Please note that the use of SRT with AF_INET6 has not been fully tested; use at your own risk. 2. SRT uses the system UDP protocol as an underlying communication layer, and so it uses also UDP sockets. The underlying communication layer is used only instrumentally, and SRT manages UDP sockets as its own system resource as it pleases - so in some cases it may be reasonable for multiple SRT sockets to share one UDP socket, or for one SRT socket to use multiple UDP sockets. 3. The term “port” used in SRT is occasionally identical to the term “UDP port”. However SRT offers more flexibility than UDP (or TCP, if we think about the more logical similarity) because it manages ports as its own resources. For example, one port may be shared between various services.

Binding and connecting

Connections are established using the same philosophy as TCP, using functions with names and signatures similar to the BSD Socket API. What is new here is the _rendezvous_ mode.

Synopsis

int srt_bind(SRTSOCKET u, const struct sockaddr* name, int namelen); int srt_bind_peerof(SRTSOCKET u, UDPSOCKET udpsock);

This function sets up the “sockname” for the socket, that is, the local IP address of the network device (use INADDR_ANY for using any device) and port. Note that this can be done on both listening and connecting sockets; for the latter it will define the outgoing port. If you don’t set up the outgoing port by calling this function (or use port number 0), a unique port number will be selected automatically.

The *_peerof version simply copies the bound address setting from an existing UDP socket.

int srt_listen(SRTSOCKET u, int backlog);

This sets the backlog (maximum allowed simultaneously pending connections) and puts the socket into listening state – that is, incoming connections will be accepted in the call srt_accept.

SRTSOCKET srt_accept(SRTSOCKET u, struct sockaddr* addr, int* addrlen);

This function accepts the incoming connection (the peer should do srt_connect) and returns a socket that is exclusively bound to an opposite socket at the peer. The peer’s address is returned in the addr argument.

int srt_connect(SRTSOCKET u, const struct sockaddr* name, int namelen); int srt_connect_debug(SRTSOCKET u, const struct sockaddr* name, int namelen, int forced_isn);

This function initiates the connection of a given socket with its peer’s counterpart (the peer gets the new socket for this connection from srt_accept). The address for connection is passed in ‘name’. The connect_debug version allows for enforcing the ISN (initial sequence number); this is used only for debugging or unusual experiments.

int srt_rendezvous(SRTSOCKET u, const struct sockaddr* local_name, int local_namelen,
const struct sockaddr* remote_name, int remote_namelen);

A convenience function that combines the calls to bind, setting the SRTO_RENDEZVOUS flag, and connecting to the rendezvous counterpart. For simplest usage, the local_name should be set to INADDR_ANY (or a specified adapter’s IP) and port. Note that both local_name and remote_name must use the same port. The peer to which this is going to connect should call the same function, with appropriate local and remote addresses. A rendezvous connection means that both parties connect to one another simultaneously.

SRT Usage - listener (server)

sockaddr_in sa = { … }; // set local listening port and possibly interface’s IP int st = srt_bind(sock, (sockaddr*)&sa, sizeof sa); srt_listen(sock, 5); while ( !finish ) {

socklen_t sa_len = sizeof sa; newsocket = srt_accept(sock, (sockaddr*)&sa, &sa_len); HandleNewClient(newsocket, sa);

}

SRT Usage - caller (client)

sockaddr_in sa = { … }; // set target IP and port

int st = srt_connect(sock, (sockaddr*)&sa, sizeof sa); HandleConnection(sock);

SRT Usage - rendezvous

sockaddr_in lsa = { … }; // set local listening IP/port sockaddr_in rsa = { … }; // set remote IP/port

srt_setsockopt(m_sock, 0, SRTO_RENDEZVOUS, &yes, sizeof yes); int stb = srt_bind(sock, (sockaddr*)&lsa, sizeof lsa); int stc = srt_connect(sock, (sockaddr*)&rsa, sizeof rsa); HandleConnection(sock);

or simpler

sockaddr_in lsa = { … }; // set local listening IP/port sockaddr_in rsa = { … }; // set remote IP/port

int stc = srt_rendezvous(sock, (sockaddr*)&lsa, sizeof lsa,
(sockaddr*)&rsa, sizeof rsa);

HandleConnection(sock);

Sending and Receiving

The SRT API for sending and receiving is split into three categories: simple, rich, and for files only.

The simple API includes: srt_send and srt_recv functions. They need only the socket and the buffer to send from or receive to, just like system read and write functions.

The rich API includes the srt_sendmsg and srt_recvmsg functions. Actually srt_recvmsg is provided for convenience and backward compatibility, as it is identical to srt_recv. The srt_sendmsg receives more parameters, specifically for messages. The srt_sendmsg2 and srt_recvmsg2 functions receive the socket, buffer, and the SRT_MSGCTRL object, which is an input-output object specifying extra data for the operation.

Functions with the msg2 suffix use the SRT_MSGCTRL object, and have the following interpretation (except flags and boundary that are reserved for future use and should be 0):

  • srt_sendmsg2:
    • msgttl: [IN] maximum time (in ms) to wait in sending buffer before being sent (-1 if unused)
    • inorder: [IN] if false, the later sent message is allowed to be delivered earlier
    • srctime: [IN] timestamp to be used for sending (0 if current time)
    • pktseq: unused
    • msgno: [OUT]: message number assigned to the currently sent message
  • srt_recvmsg2
    • msgttl, inorder: unused
    • srctime: [OUT] timestamp set for this dataset when sending
    • pktseq: [OUT] packet sequence number (first packet from the message, if it spans multiple UDP packets)
    • msgno: [OUT] message number assigned to the currently received message

Please note that the msgttl and inorder arguments and fields in SRT_MSGCTRL are meaningful only when you use the message API in file mode (this will be explained later). In live mode, which is the SRT default, packets are always delivered when the time comes (always in order), where you don’t want a packet to be dropped before sending (so -1 should be passed here).

The srctime parameter is an SRT addition for applications (i.e. gateways) forwarding SRT streams. It permits pulling and pushing of the sender’s original time stamp, converted to local time and drift adjusted. The srctime parameter is the number of usec (since epoch) in local time. If the connection is not between SRT peers or if Timestamp-Based Packet Delivery mode (TSBPDMODE) is not enabled (see Options), the extracted srctime will be 0. Passing srctime = 0 in sendmsg is like using the API without srctime and the local send time will be used (if TSBPDMODE is enabled and receiver supports it).

Synopsis

int srt_send(SRTSOCKET s, const char* buf, int len); int srt_sendmsg(SRTSOCKET s, const char* buf, int len, int msgttl, bool inorder, uint64_t srctime); int srt_sendmsg2(SRTSOCKET s, const char* buf, int len, SRT_MSGCTRL* msgctrl);

int srt_recv(SRTSOCKET s, char* buf, int len); int srt_recvmsg(SRTSOCKET s, char* buf, int len); int srt_recvmsg2(SRTSOCKET s, char* buf, int len, SRT_MSGCTRL* msgctrl);

Usage

Sending a payload:

nb = srt_sendmsg(u, buf, nb, -1, true);

nb = srt_send(u, buf, nb);

SRT_MSGCTL mc = srt_msgctl_default; nb = srt_sendmsg2(u, buf, nb, &mc);

Receiving a payload:

nb = srt_recvmsg(u, buf, nb); nb = srt_recv(u, buf, nb);

SRT_MSGCTL mc = srt_msgctl_default; nb = srt_recvmsg2(u, buf, nb, &mc);

Transmission Modes

Mode settings determine how the sender and receiver functions work. The main socket options (see below for full description) that control it are:

  • SRTO_TRANSTYPE. Sets several parameters in accordance with the selected
mode:
  • SRTT_LIVE (default) the Live mode (for live stream transmissions)
  • SRTT_FILE the File mode (for “no time controlled” fastest data transmission)
  • SRTO_MESSAGEAPI
    • true: (default in Live mode): use Message API
    • false: (default in File mode): use Buffer API

We have then three cases (note that Live mode implies Message API):

  • Live mode (default)

    In this mode, the application is expected to send single pieces of data that are already under sending speed control. Default size is 1316, which is 7 * 188 (MPEG TS unit size). With default settings in this mode, the receiver will be delivered payloads with the same time distances between them as when they were sent, with a small delay (default 120 ms).

  • File mode, Buffer API (default when set SRTT_FILE mode)

    In this mode the application may deliver data with any speed and of any size. The facility will try to send them as long as there is buffer space for it. A single call for sending may send only fragments of the buffer, and the receiver will receive as much as is available and fits in the buffer.

  • File mode, Message API (when SRTO_TRANSTYPE is SRTT_FILE and SRTO_MESSAGEAPI is true)

    In this mode the application delivers single pieces of data that have declared boundaries. The sending is accepted only when the whole message can be scheduled for sending, and the receiver will be given either the whole message, or nothing at all, including when the buffer is too small for the whole message.

The File mode and its Buffer and Message APIs are derived from UDT, just implemented in a slightly different way. This will be explained below in HISTORICAL INFO under “Transmission Method: Message”.

Blocking and Non-blocking Mode

SRT functions can also work in blocking and non-blocking mode, for which there are two separate options for sending and receiving: SRTO_SNDSYN and SRTO_RCVSYN. When blocking mode is used, a function will not exit until the availability condition is satisfied; in non-blocking mode the function always exits immediately, and in case of lack of resource availability, it returns an error with appropriate code. The use of non-blocking mode usually requires using some polling mechanism, which in SRT is EPoll.

Note also that the blocking and non-blocking modes apply not only for sending and receiving. For example, SNDSYN defines blocking for srt_connect and RCVSYN defines blocking for srt_accept. The SNDSYN also makes srt_close exit only after the sending buffer is completely empty.

EPoll (Non-blocking Mode Events)

EPoll is a mechanism to track the events happening on the sockets, both “system sockets” (see SYSSOCKET type) and SRT Sockets. Note that SYSSOCKET is also an alias for int, used only for clarity.

Synopsis

int srt_epoll_update_usock(int eid, SRTSOCKET u, const int* events = NULL); int srt_epoll_update_ssock(int eid, SYSSOCKET s, const int* events = NULL);

SRT Usage

SRT socket being a user level concept, the system epoll (or other select) cannot be used to handle SRT non-blocking mode events. Instead, SRT provides a user-level epoll that supports both SRT and system sockets.

The srt_epoll_update_{u|s}sock() API functions described here are SRT additions to the UDT-derived srt_epoll_add_{u|s}sock() and epoll_remove_{u|s}sock() functions to atomically change the events of interest. For example, to remove EPOLLOUT but keep EPOLLIN for a given socket with the existing API, the socket must be removed from epoll and re-added. This cannot be done atomically, the thread protection (against the epoll thread) being applied within each function but unprotected between the two calls. It is then possible to lose a POLLIN event if it fires while the socket is not in the epoll list.

The SRT EPoll system does not supports all features of Linux epoll. For example, it only supports level-triggered events.

Options

There’s a general method of setting options on a socket in the SRT C API, similar to the system setsockopt/getsockopt functions.

Synopsis

Legacy version:

void srt_getsockopt(SRTSOCKET socket, int level, SRT_SOCKOPT optName, void* optval, int& optlen); void srt_setsockopt(SRTSOCKET socket, int level, SRT_SOCKOPT optName, const void* optval, int optlen);

New version:

void srt_getsockflag(SRTSOCKET socket, SRT_SOCKOPT optName, void* optval, int& optlen); void srt_setsockflag(SRTSOCKET socket, SRT_SOCKOPT optName, const void* optval, int optlen);

(In the legacy version, there’s an additional unused level parameter. It was there in the original UDT API just to mimic the system setsockopt function).

Some options require a value of type bool and some others of type int, which is not the same – they differ in size, and mistaking them may end up with a crash. This must be kept in mind especially in any C wrapper. For convenience, the setting option function may accept both int and bool types, but this is not so in the case of getting an option value.

Almost all options from the UDT library are derived (there are a few deleted, including some deprecated already in UDT), many new SRT options have been added. All options are available exclusively with the SRTO_ prefix. Old names are provided as alias names in the udt.h legacy/C++ API file. Note the translation rules: * UDT_ prefix from UDT options was changed to the prefix SRTO_ * UDP_ prefix from UDT options was changed to the prefix SRTO_UDP_ * SRT_ prefix in older SRT versions was changed to SRTO_

The Binding column should define for these options one of the following statements concerning setting a value:

  • pre: For connecting a socket it must be set prior to calling srt_connect()

and never changed thereafter. For a listener socket it should be set to a binding socket and it will be derived by every socket returned by srt_accept(). * post: This flag can be changed any time, including after the socket is connected. On binding a socket setting this flag is effective only on this socket itself. Note though that there are some post-bound options that have important meaning when set prior to connecting.

This option list is sorted alphabetically. Note that some options can be either only a retrieved (r) or set (w) value.

OptName | Since | Binding | Type | Units | Default | Range | Description |
— | — | — | — | — | — | — | — |
SRTO_CONNTIMEO | 1.1.2 | pre | int | msec | 3000 | tbd | Connect timeout. SRT cannot connect for RTT > 1500 msec (2 handshake exchanges) with the default connect timeout of 3 seconds. This option applies to the caller and rendezvous connection modes. The connect timeout is 10 times the value set for the rendezvous mode (which can be used as a workaround for this connection problem with earlier versions). |
— |
SRTO_EVENT (r) | | n/a | int32_t | | n/a | n/a | Connection epoll flags (see [epoll_ctl](http://man7.org/linux/man-pages/man2/epoll_ctl.2.html)). One or more of the following flags: EPOLLIN | EPOLLOUT | EPOLLERR |
— |
SRTO_FC | | pre | int | pkts | 25600 | 32.. | Flight Flag Size. |
— |
SRTO_INPUTBW | 1.0.5 | post | int64_t | bytes/secs | 0 | 0.. | Sender nominal input rate. Used along with OHEADBW, when MAXBW is set to relative (0), to calculate maximum sending rate when recovery packets are sent along with main media stream (INPUTBW * (100 + OHEADBW) / 100). If INPUTBW is not set while MAXBW is set to relative (0), the actual input rate is evaluated inside the library. |
— |
SRTO_IPTOS | 1.0.5 | pre | int32_t | | (platform default) | 0..255 | IP Type of Service. Applies to sender only. Sender: user configurable, default: 0xB8 |
— |
SRTO_ISN (r) | 1.3.0 | post | int32_t | sequence | n/a | n/a | The value of the ISN (Initial Sequence Number), which is the first sequence number put on a firstmost sent UDP packets carrying SRT data payload. This value is useful for developers of some more complicated methods of flow control, possibly with multiple SRT sockets at a time, not predicted in any regular development. |
— |
SRTO_KMSTATE (r) | 1.0.2 | n/a | int32_t | | n/a | n/a | Receiver Keying Material state. Available on both sender and receiver sides. Values defined in enum SRT_KM_STATE: |
| | | | | | | * SRT_KM_S_UNSECURED: unsecured: data not encrypted |
| | | | | | | * SRT_KM_S_SECURING: securing: waiting for keying material |
| | | | | | | * SRT_KM_S_SECURED: secured: keying material obtained and operational (decrypting received data) |
| | | | | | | * SRT_KM_S_NOSECRET: no secret: no secret configured to handle keying material |
| | | | | | | * SRT_KM_S_BADSECRET: bad secret: invalid secret configured |
— |
SRTO_IPTTL | 1.0.5 | pre | int32_t | hops | (platform default) | 1..255 | IP Time To Live. Applies to sender only. Sender: user configurable, default: 64 |
— |
SRTO_LATENCY | 0.0.0 | pre | int32_t | msec | 0 | positive only | This flag sets both SRTO_RCVLATENCY and SRTO_PEERLATENCY to the same value. Note that prior to version 1.3.0 this is the only flag to set the latency, however this is effectively equivalent to setting SRTO_PEERLATENCY, when the side is sender (see SRTO_SENDER) and SRTO_RCVLATENCY when the side is receiver, and the bidirectional stream sending is not supported. |
— |
SRTO_LINGER | | pre | linger | secs | on (180) | | Linger time on close (see [SO_LINGER](http://man7.org/linux/man-pages/man7/socket.7.html)) SRT recommended value: off (0) |
— |
SRTO_LOSSMAXTTL (writeonly) | 1.2.0 | pre | int | packets | 0 | reasonable | The value up to which the Reorder Tolerance may grow. When Reorder Tolerance is > 0, then packet loss report is delayed until that number of packets come in. Reorder Tolerance increases every time a “belated” packet has come, but it wasn’t due to retransmission (that is, when UDP packets tend to come out of order), with the difference between the latest sequence and this packet’s sequence, and not more than the value of this option. By default it’s 0, which means that this mechanism is turned off, and the loss report is always sent immediately upon experiencing a “gap” in sequences.
— |
SRTO_MAXBW | 1.0.5 | pre | int64_t | bytes/sec | -1 | -1 | 0 | 1.. | Maximum send bandwidth. -1: infinite (CSRTCC limit is 30mbps) =0: relative to input rate (SRT 1.0.5 addition, see SRTO_INPUTBW) >0: absolute limit SRT recommended value: 0 (relative) |
— |
SRTO_MESSAGEAPI (w) | 1.3.0 | pre | bool | boolean | true | | When set, this socket uses the Message API[*], otherwise it uses Buffer API |
— |
SRTO_MINVERSION (writeonly) | 1.3.0 | pre | int32_t | version | 0 | up to current | The minimum SRT version that is required from the peer. A connection to a peer that does not satisfy the minimum version requirement will be rejected. |
— |
SRTO_MSS`| | pre | `int | bytes|1500 | 76.. | Maximum Segment Size. Used for buffer allocation and rate calculation using packet counter assuming fully filled packets. The smallest MSS between the peers is used. This is 1500 by default in the overall internet. This is the maximum size of the UDP packet and can be only decreased, unless you have some unusual dedicated network settings. |
— |
SRTO_NAKREPORT | 1.1.0 | pre | bool | | true | true|false | Receiver will send UMSG_LOSSREPORT messages periodically until the lost packet is retransmitted or intentionally dropped |
— |
SRTO_OHEADBW | 1.0.5 | post | int | % | 25 | 5..100 | Recovery bandwidth overhead above input rate (see SRTO_INPUTBW). Sender: user configurable, default: 25%. *To do: set-only. get should be supported.* |
— |
SRTO_PASSPHRASE (w) | 0.0.0 | pre | string | | [0] | [10..79] | HaiCrypt Encryption/Decryption Passphrase. The passphrase is the shared secret between the sender and the receiver. It is used to generate the Key Encrypting Key using [PBKDF2](http://en.wikipedia.org/wiki/PBKDF2) (Password-Based Key Derivation Function 2). It is used on the sender if PBKEYLEN is non zero. It is used on the receiver only if the received data is encrypted. The configured passphrase cannot be get back (write-only). Sender and receiver: user configurable. |
— |
SRTO_PAYLOADSIZE (w) | 1.3.0 | pre | int | bytes | 1316 (Live) | up to MTUsize-28-16, usually 1456 | Sets the maximum declared size of a single call to sending function in Live mode. Use 0 if this value isn’t used (which is default in file mode)
— |
SRTO_PBKEYLEN | 0.0.0 | pre | int32_t | bytes | 0 | 0 16(128/8) 24(192/8) 32(256/8) | Sender encryption key length. Enable sender encryption if not 0. Not required on receiver (set to 0), key size obtained from sender in HaiCrypt handshake. Sender: user configurable. |
— |
SRTO_PEERLATENCY | 1.3.0 | pre | int32_t | msec | 0 | positive only | The latency value (as described in SRTO_RCVLATENCY) that is set by the sender side as a minimum value for the receiver. |
— |
SRTO_PEERVERSION (r) | 1.1.0 | n/a | int32_t | n/a | n/a | n/a | Peer SRT version. The value 0 is returned if not connected, SRT handshake not yet performed, or if peer is not SRT. See SRTO_VERSION for the version format. |
SRTO_RCVBUF | | pre | int | bytes | 8192 * (1500-28) | 32 * (1500-28) ..FC * (1500-28) | Receive Buffer Size. Receive buffer must not be greater than FC size. *Warning: configured in bytes, converted in packets when set based on MSS value. For desired result, configure MSS first.* |
— |
SRTO_RCVDATA (r) | | n/a | int32_t | pkts | n/a | | Size of the available data in the receive buffer. |
— |
SRTO_RCVKMSTATE (readonly) | 1.2.0 | post | enum | n/a | n/a | KM state on the agent side when it’s a receiver, as per SRTO_KMSTATE |
— |
SRTO_RCVLATENCY | 1.3.0 | pre | int32_t | msec | 0 | positive only | The time that should elapse since the moment when the packet was sent and the moment when it’s delivered to the receiver application in the receiving function. This time should be a buffer time large enough to cover the time spent for sending, unexpectedly extended RTT time, and the time needed to retransmit the lost UDP packet. The effective latency value will be the maximum of this options’ value and the value of SRTO_PEERLATENCY set by the peer side. This option in pre-1.3.0 version is available only as SRTO_LATENCY. |
— |
SRTO_RCVSYN | | pre | bool | | true | true | false | Synchronous (blocking) receive mode |
— |
SRTO_RCVTIMEO | | post | int | msecs | -1 | -1.. | Blocking mode receiving timeout (-1: infinite) |
— |
SRTO_RENDEZVOUS | | pre | bool | | false | true | false | Use Rendez-Vous connection mode (both sides must set this and both must use bind/connect to one another. |
— |
SRTO_REUSEADDR | | pre | | | true | true | false | Reuse existing address (see [SO_REUSEADDR](http://man7.org/linux/man-pages/man7/socket.7.html)) |
— |
SRTO_SENDER | 1.0.4 | pre | int32_t bool? | | false | | Set sender side. The side that sets this flag is expected to be a sender. It’s required when any of two connection sides supports at most HSv4 handshake, and the sender side is the side that initiates the SRT extended handshake (which won’t be done at all, if none of the sides sets this flag). This flag is superfluous, if both parties are at least version 1.3.0 and therefore support HSv5 handshake, where the SRT extended handshake is done with the overall handshake process. This flag is however obligatory if at least one party is SRT below version 1.3.0 and does not support HSv5.
— |
SRTO_SMOOTHER (w) | 1.3.0 | pre | const char* | predefined | “live” | “live” or “file” | The type of Smoother used for the transmission for that socket, which is responsible for the transmission and congestion control. The Smoother type must be exactly the same on both connecting parties, otherwise the connection is rejected. *TODO: might be reasonable to allow an “adaptive” value of the Smoother, which will accept either of the smoother types when the other party enforces it, and rejected if both sides are “adaptive”*
— |
SRTO_SNDBUF | | pre | int | bytes | 8192 * (1500-28) | | Send Buffer Size. *Warning: configured in bytes, converted in packets, when set, based on MSS value. For desired result, configure MSS first.* |
— |
SRTO_SNDDATA (read-only) | | n/a | int32_t | pkts | n/a | n/a | Size of the unacknowledged data in send buffer. |
— |
SRTO_SNDPEERKMSTATE (readonly) | 1.2.0 | post | enum | n/a | n/a | Peer KM state on receiver side for SRTO_KMSTATE |
— |
SRTO_SNDSYN`| | post | `bool | |true | true | false | Synchronous (blocking) send mode |
— |
SRTO_SNDTIMEO`| | post | `int | msecs|-1 | -1.. | Blocking mode sending timeout (-1: infinite) |
— |
SRTO_STATE (r) | | n/a | int32_t | | n/a | n/a | UDT connection state. |
— |
SRTO_STREAMID (rw) | 1.3.0 | pre | const char* | | empty | any string | A string limited to 512 characters that can be set on the socket prior to connecting. This stream ID will be able to be retrieved by the listener side from the socket that is returned from srt_accept and was connected by a socket with that set stream ID. SRT does not enforce any special interpretation of the contents of this string. As this uses internally the std::string type, there are additional functions for it in the legacy/C++ API: UDT::setstreamid and UDT::getstreamid. |
— |
SRTO_TLPKTDROP | 1.0.6 | pre | int32_t bool? | | true | true | false | Too-late Packet Drop. When enabled on receiver, it skips missing packets that have not been delivered in time and delivers the subsequent packets to the application when their time-to-play has come. It also sends a fake ACK to the sender. When enabled on sender and enabled on the receiving peer, sender drops the older packets that have no chance to be delivered in time. It is automatically enabled in sender if receiver supports it. |
— |
SRTO_TRANSTYPE (w) | 1.3.0 | pre | enum | | SRTT_LIVE | alt: SRTT_FILE | Sets the transmission type for the socket, in particular, setting this option sets multiple other parameters to their default values as required for a particular transmission type. |
— |
SRTO_TSBPDMODE | 0.0.0 | pre | int32_t (bool?) | | false | true | false | Timestamp-based Packet Delivery mode. This flag is set to _true_ by default and as a default flag set in live mode. |
— |
SRTO_UDP_RCVBUF | | pre | int | bytes | 8192 * 1500 | MSS.. | UDP Socket Receive Buffer Size. Configured in bytes, maintained in packets based on MSS value. Receive buffer must not be greater than FC size. |
— |
SRTO_UDP_SNDBUF | | pre | int | bytes | 65536 | MSS.. | UDP Socket Send Buffer Size. Configured in bytes, maintained in packets based on SRTO_MSS value. SRT recommended value: 1024*1024 |
— |
SRTO_VERSION (r) | 1.1.0 | n/a | int32_t | | n/a | n/a | Local SRT version. This is the highest local version supported if not connected, or the highest version supported by the peer if connected. The version format in hex is 0xXXYYZZ for x.y.z in human readable form, where x = (“%d”, (version>>16) & 0xff), etc… Set could eventually be supported to test |
— |

Transmission types

SRT has been mainly created for Live Streaming and therefore its main and default transmission type is “live”. SRT supports, however, the modes that the original UDT library supported, that is, file and message transmission.

There are two general modes: Live and File transmission. Inside File transmission mode, there are also two possibilities: Buffer API and Message API. The Live mode uses Message API. However it doesn’t exactly match the description of the Message API because it uses a maximum single sending buffer up to the size that fits in one UDP packet.

There are two options to set a particular type:

  • SRTO_TRANSTYPE: uses the enum value with SRTT_LIVE for live mode
    and SRTT_FILE for file mode. This option actually changes several parameters to their default values for that mode. After this is done, additional parameters, including those that are set here, can be further changed.
  • SRTO_MESSAGEAPI: This sets the Message API (true) or Buffer API (false)

This makes possible a total of three data transmission methods:

  • Live
  • Buffer
  • Message

NOTE THE TERMS used below: * HANGUP and RESUME: “Function HANGS UP” means that it returns an error from the MJ_AGAIN category (see SRT_EASYNC*, SRT_ETIMEOUT and SRT_ECONGEST symbols from SRT_ERRNO enumeration type), if it’s in non-blocking mode. In blocking mode it will block until the condition that caused the HANGUP no longer applies, which is defined as that the function RESUMES. In nonblocking mode, the function RESUMES when the call to it has done something and returned the non-error status. The blocking mode in SRT is separate for sending and receiving and set by SRTO_SNDSYN and SRTO_RCVSYN options respectively * BLIND REXMIT: A situation where packets that were sent are still not acknowledged, either in expected time frame, or when another ACK has come for the same number, but no packets have been reported as lost, or at least not for all still unacknowledged packets. The Smoother class is responsible for the algorithm for taking care of this situation, which is either FASTREXMIT or LATEREXMIT. This will be expained below.

Transmission method: Live

Setting SRTO_TRANSTYPE to SRTT_LIVE sets the following parameters:

  • SRTO_TSBPDMODE = true
  • SRTO_RCVLATENCY = 120
  • SRTO_PEERLATENCY = 0
  • SRTO_TLPKTDROP = true
  • SRTO_MESSAGEAPI = true
  • SRTO_NAKREPORT = true
  • SRTO_PAYLOADSIZE = 1316
  • SRTO_SMOOTHER = “live”

In this mode, every call to a sending function is allowed to send only so much data, as declared by SRTO_PAYLOADSIZE, whose value is still limited to a maximum of 1456 bytes. The application that does the sending is by itself responsible for calling the sending function in appropriate time intervals between subsequent calls. By default, this implies that the receiver uses 120 ms of latency, which is the declared time interval between the moment when the packet is scheduled for sending at the sender side, and when it is received by the receiver application (that is, the data are kept in the buffer and declared as not received, until the time comes for the packet to “play”).

This mode uses the LiveSmoother Smoother class for congestion control, which puts only a slight limitation on the bandwidth, if needed, just to add extra time, if the distance between two consecutive packets would be too short for the defined speed limit. Note that this smoother is not predicted to work with “virtually infinite” ingest speeds (such as, for example, reading directly from a file). Therefore the application is not allowed to stream data with maximum speed – it must take care that the speed of data being sent is in rhythm with timestamps in the live stream. Otherwise the behavior is undefined and might be surprisingly disappointing.

The reading function will always return only a payload that was sent, and it will HANGUP until the time to play has come for this packet (if TSBPD mode is on) or when it is available without gaps of lost packets (if TSBPD mode is off - see SRTO_TSBPDMODE).

You may wish to tweak some of the parameters below: * SRTO_TSBPDMODE: you can turn off controlled latency, if your application uses some alternative and its own method of latency control * SRTO_RCVLATENCY: you can increase the latency time, if this is too short (setting shorter latency than default is strongly discouraged, although in some very specific and dedicated networks this may still be reasonable). Note that SRTO_PEERLATENCY is an option for the sending party, which is the minimum possible value for a receiver. * SRTO_TLPKTDROP: When true (default), it will drop the packets that haven’t been retransmitted on time, that is, before the next packet that is already received becomes ready to play. You can turn this off to always ensure a clean delivery. However, a lost packet can simply pause a delivery for some longer, potentially undefined time, and cause even worse tearing for the player. Setting higher latency will help much more in the case when TLPKTDROP causes packet drops too often. * SRTO_NAKREPORT: Turns on repeated sending of lossreport, when the lost packet was not recovered quickly enough, which raises suspicions that the lossreport itself was lost. Without it, the lossreport will be always reported just once and never repeated again, and then the lost payload packet will be probably dropped by the TLPKTDROP mechanism. * SRTO_PAYLOADSIZE: Default value is for MPEG TS; if you are going to use SRT to send any different kind of payload, such as, for example, wrapping a live stream in very small frames, then you can use a bigger maximum frame size, though not greater than 1456 bytes.

Parameters from the modified for transmission type list, not mentioned in the list above, are crucial for Live mode and shall not be changed.

The BLIND REXMIT situation is resolved using the FASTREXMIT algorithm by LiveSmoother: sending non-acknowledged packets blindly on the premise that the receiver lingers too long before acknowledging them. This mechanism isn’t used (that is, the BLIND REXMIT situation isn’t handled at all) when SRTO_NAKREPORT is set by the peer – the NAKREPORT method is considered so effective that FASTREXMIT isn’t necessary.

Transmission method: Buffer

Setting SRTO_TRANSTYPE to SRTT_FILE sets the following parameters:

  • SRTO_TSBPDMODE = false
  • SRTO_RCVLATENCY = 0
  • SRTO_PEERLATENCY = 0
  • SRTO_TLPKTDROP = false
  • SRTO_MESSAGEAPI = false
  • SRTO_NAKREPORT = false
  • SRTO_PAYLOADSIZE = 0
  • SRTO_SMOOTHER = “file”

In this mode, calling a sending function is allowed to potentially send virtually any size of data. The sending function will HANGUP only if the sending buffer is completely replete, and RESUME if the sending buffers are available for at least one smallest portion of data passed for sending. The sending function need not send everything in this call, and the caller must be aware that the sending function might return sent data of smaller size than was actually requested.

From the receiving function there will be retrieved as many data as the minimum of the passed buffer size and available data; data still available and not retrieved by this call will be available for retrieval in the next call.

There is also a dedicated pair of functions that can only be used in this mode: srt_sendfile and srt_recvfile. These functions can be used to transmit the whole file, or a fragment of it, based on the offset and size.

This mode uses the FileSmoother Smoother class for congestion control, which is a direct copy of the UDT’s CUDTCC congestion control class, adjusted to the needs of SRT’s Smoother framework. This class generally sends the data with maximum speed in the beginning, until the flight window is full, and then keeps the speed at the edge of the flight window, only slowing down in the case where packet loss was detected. The bandwidth usage can be directly limited by SRTO_MAXBW option.

The BLIND REXMIT situation is resolved in FileSmoother using the LATEREXMIT algorithm: when the repeated ACK was received for the same packet, or when the loss list is empty and the flight window is full, all packets since the last ACK are sent again (that’s more or less the TCP behavior, but in contrast to TCP, this is done as a very low probability fallback).

As you can see in the parameters described above, most have false or 0 values as they usually designate features used in Live mode. None are used with File mode. The only option that makes sense to modify after the SRTT_FILE type was set is SRTO_MESSAGEAPI, which is described below.

Transmission method: Message

Setting SRTO_TRANSTYPE to SRTT_FILE and then SRTO_MESSAGEAPI to true implies usage of the Message transmission method. Parameters are set as described above for the Buffer method, with the exception of SRTO_MESSAGEAPI, and FileSmoother is also used in this mode. It differs from the Buffer method, however, in terms of the rules concerning sending and receiving.

HISTORICAL INFO: The library that SRT was based on, UDT, somewhat misleadingly used the terms STREAM and DGRAM, and used the system symbols SOCK_STREAM and SOCK_DGRAM in the socket creation function. The “datagram” in the UDT terminology has nothing to do with the “datagram” term in networking terminology, where its size is limited to as much it can fit in one MTU. In UDT it is actually a message, which may span through multiple UDP packets and has clearly defined boundaries. It’s something rather similar to the SCTP protocol. Also, in UDP the API functions were strictly bound to DGRAM or STREAM mode: UDT::send/UDT::recv were only for STREAM and UDT::sendmsg/UDT::recvmsg only for DGRAM. In SRT this is changed: all functions can be used in all modes, except srt_sendfile/srt_recvfile, and how the functions actually work is controlled by the SRTO_MESSAGEAPI flag.

The message mode means that every sending function sends exactly as much data as it is passed in a single sending function call, and the receiver receives also not less than exactly the number of bytes that was sent (although every message may have a different size). Every message may also have extra parameters: * TTL defines how much time (in ms) the message should wait in the sending buffer for the opportunity to be picked up by the sender thread and sent over the network; otherwise it is dropped. * INORDER, when true, means the messages must be read by the receiver in exactly the same order in which they were sent. In the situation where a message suffers a packet loss, this prevents any subsequent messages from achieving completion status prior to recovery of the preceding message.

The sending function will HANGUP when the free space in the sending buffer does not exactly fit the whole message, and it will only RESUME if the free space in the sending buffer grows up to this size. The call to the sending function also returns with an error, when the size of the message exceeds the total size of the buffer (this can be modified by SRTO_SNDBUF option). In other words, it is not designed to send just a part of the message – either the whole message is sent, or nothing at all.

The receiving function will HANGUP until the whole message is available for reading; if the message spans multiple UDP packets, then the function RESUMES only when every single packet from the message has been received, including recovered packets, if any. When the INORDER flag is set to false and parts of multiple messages are currently available, the first message that is complete (possibly recovered) is returned. Otherwise the function does a HANGUP until the next message is complete. The call to the receiving function is rejected if the buffer size is too small for a single message to fit in it.

Note that you can use any of the sending and receiving functions for sending and receiving messages, except sendfile/recvfile, which are dedicated exclusively for Buffer API.