DOCSEARCHbyAlgolia
Submit Docs

Secure Reliable Transport (SRT) Documentation

repository·master·Indexed 25 days ago

https://github.com/haivision/srt

An open-source protocol for low-latency, high-reliability live video and audio streaming over unpredictable networks. This documentation covers the SRT C API, build instructions for Linux, Windows, macOS, iOS, and Android, and advanced features such as AES encryption, ARQ/FEC error recovery, Connection Bonding via socket groups, and Access Control using Stream IDs. It also includes guides for the packet filter API and sample applications like srt-live-transmit and srt-file-transmit.

Tokens
65.7K
Snippets
65
Records
346
Agent score
86%

What's inside SRT

  1. Overview of Secure Reliable Transport (SRT)

    master

    Secure Reliable Transport (SRT) is a transport protocol designed for ultra-low (sub-second) latency live video and audio streaming, as well as generic bulk data transfer. It is payload-agnostic, meaning it can transport any video format, codec, resolution, or frame rate by acting as a network transport wrapper.

    Key characteristics:

    • Secure: Implements AES encryption (128/192/256-bit) to protect media payloads.
    • Reliable: Recovers from severe packet loss and jitter using mechanisms like Automatic Repeat reQuest (ARQ), Forward Error Correction (FEC), and Connection Bonding.
    • Transport: Dynamically adapts to changing network conditions to maintain constant end-to-end latency.

  2. Explore SRT features and capabilities

    master

    SRT provides several advanced features for reliable and secure transport:

    • Connection Bonding: Includes Quick Start guides, introductions to bonded connections, socket group descriptions, and Main/Backup mode.
    • Access Control: Guidelines for using Stream IDs for access control.
    • Encryption: Details on the SRT encryption mechanism.
    • Handshake: Description of the SRT handshake mechanism.
    • Live Streaming: Best practices and configuration tips for live streaming.
    • Packet Filtering & FEC: Description of the packet filtering mechanism, including Forward Error Correction (FEC).

  3. Understand SRT Latency Definition

    master
    In SRT, latency is specifically defined as the delay introduced by sending over the network. It is the time interval between the execution of srt_sendmsg2 at the sender side and the execution of srt_recvmsg2 at the receiver side. This differs from general live streaming latency, which includes encoding, multiplexing, and decoding times.

  4. Understand SRT Handshake Versions (HSv4 vs HSv5)

    master

    SRT uses two handshake versions to establish connections:

    • HSv4 (UDT Legacy): The original handshake mechanism. Extended SRT operations are performed after the HSv4 handshake is established. In HSv4, roles are determined by the SRTO_SENDER socket option: the party with SRTO_SENDER set to true is the Initiator, and the party with false (default) is the Responder.
    • HSv5 (Integrated Handshake): Introduced in SRT version 1.3.0. It integrates extended handshake operations (like encryption exchange) into the initial connection process. In HSv5, roles are determined by the connection mode: for Caller-Listener connections, the Caller is the Initiator and the Listener is the Responder. HSv5 connections are always bidirectional, and the SRTO_SENDER flag is unused.

  5. Understand SRT Connection Bonding and Groups

    master

    A Group is an entity that binds multiple sockets to establish a "bonded connection". Groups allow for link redundancy (using broadcast or backup types) or bandwidth load sharing (using balancing groups).

    Key characteristics:

    • A group is considered connected as long as at least one member-socket connection is alive.
    • Groups are fully flexible: you can add or remove links while transmission is active.
    • Broken connections are not automatically reestablished; the application is responsible for tracking connection states and calling srt_connect to revive them.
    • To achieve true redundancy or balancing, every member link must be routed through a different network path (different target addresses on the caller side and different network devices on the listener side).

  6. Understand the SRT Handshake (HSv4 vs HSv5)

    master

    The SRT handshake process occurs after a connection is established. It uses 'SRT Extended Messages' (major type UMSG_EXT) to negotiate settings like latency and encryption.

    Key Differences:

    • HSv4: Uses extended messages sent over the established connection. It is unidirectional (Sender sends HSREQ, Receiver responds with HSRSP). It only supports 'Live' mode.
    • HSv5: Uses an integrated handshake within the initial connection setup. It is bidirectional, allowing separate latency settings for each direction (Sender and Receiver). It supports both 'Live' and 'Stream' (file) modes.

    Important Implementation Note:

    Handshake messages are sent as UDP packets and are subject to packet loss. They are sent 'stubbornly' (with retries) until a response is received.

    Warning: The first data packet is sent immediately after the handshake request, not waiting for the handshake to complete. This means:

    1. Latency Delay: Packets may be delivered immediately before TSBPD (Time Stamp Based Packet Delivery) is active.
    2. Encryption Delay: If encryption is used, the first few packets might be sent encrypted but cannot be decrypted by the receiver until SRT_CMD_KMREQ is processed, causing them to be dropped.

  7. Understand SRT Encryption Mechanism

    master

    SRT uses AES in counter mode (AES-CTR) to encrypt media streams. This approach allows for random access (decryption from any point in the stream) and provides resilience against packet loss.

    Key components of the mechanism include:

    • Stream Encrypting Key (SEK): A short-lived, pseudo-random key (128, 192, or 256 bits) used to encrypt the actual media payload. It is regenerated every time a stream starts and is periodically refreshed to prevent counter exhaustion.
    • Key Encrypting Key (KEK): A longer-term key used to wrap (encrypt) the SEK during transmission. The KEK is derived from a shared secret (such as a pre-shared password) using the PBKDF2 derivation function.
    • Salt: A value used to derive the Initialization Vector (IV) and the KEK, ensuring that even with the same shared secret, different streams have unique encryption parameters.
    • Keying Material message (KMmsg): A custom SRT control packet used to transport the SEK and Salt in-band, wrapped with the KEK.

  8. Explore the SRT C API documentation

    master

    The SRT C API documentation provides detailed technical references for integrating the Secure Reliable Transport protocol into your applications. Key resources include:

    • SRT API: Detailed description of the core C API.
    • SRT API Functions: A reference document for all available SRT API functions.
    • SRT API Socket Options: Instructions and a list of socket options available for the SRT API.
    • SRT Rejection Codes: A list of error/rejection codes returned by the API.
    • SRT Statistics: Documentation on how to use socket and socket group statistics.
    • Configuration Guidelines: Guidance on how to properly configure SRT buffers.

  9. Understand SRT Rejection Code Ranges

    master

    SRT uses rejection (error) codes to indicate why a connection was refused. These codes are used in the SRT API and are transmitted over the wire within Handshake packets. The codes are categorized into three main ranges defined by preprocessor constants:

    • SRT Internal (SRT_REJC_INTERNAL = 0): Reserved for SRT system-level errors (range 0 - 999). Applications cannot use these to report their own reasons.
    • Predefined Application Level (SRT_REJC_PREDEFINED = 1000): Standardized error codes, including those adopted from HTTP (range 1000 - 1999). These are typically set by an application via a listener callback.
    • User Defined (SRT_REJC_USERDEFINED = 2000): Custom codes that can be freely defined by an application for proprietary error reporting (range 2000 - 2999).

    Note on Wire Transmission: When sent over the network, the API value is incremented by 1000 to become the Handshake Type field value.

  11. Understand SRT Main/Backup Sensitivity Levels

    master

    The Main/Backup switching mode utilizes sensitivity levels to determine when to transition between links:

    • Preemptive Switch (Implemented): The system identifies an unstable main path and switches to a backup path before the main link actually breaks. This predictive approach aims to minimize packet loss by preparing the backup link in advance.
    • Handover Switch (Future/Planned): A mode where the switch occurs only after the link is confirmed broken. This reduces processing overhead but results in a discontinuity (data loss) during the switch, making it suitable only for applications where low latency and zero packet loss are not critical.

  12. Understand SRT project structure

    master

    The SRT repository is organized into the following directories:

    • srtcore: The main source code of the SRT library.
    • apps: Contains sample applications (srt-live-transmit, srt-file-transmit, srt-tunnel).
    • examples: Example applications (enabled via -DENABLE_EXAMPLES=ON).
    • test: Unit tests for the library.
    • testing: Development applications (e.g., srt-test-live, srt-test-file), enabled via -DENABLE_TESTING=ON.
    • docs: Documentation in Markdown format.
    • haicrypt: Encryption-related code.
    • scripts: CMake and TCL scripts.
    • common: Platform-dependent code.