uvgRTP Documentation

uvgRTP is a C++ library designed for high-efficiency, real-time media delivery over the internet using the Real-Time Transport Protocol (RTP). It provides an intuitive API for transporting various video and audio codecs and supports End-to-End Encryption (E2EE) through SRTP and ZRTP.

Supported Codecs

• Video: Versatile Video Coding (VVC), High Efficiency Video Coding (HEVC), and Advanced Video Coding (AVC/H.264).
• Audio: Opus.

Supported Specifications

• RTP Core: RFC 3350 (RTP Transport), RFC 3551 (Audio/Video Conferences).
• Payload Formats: RFC 7798 (HEVC), RFC 6184 (H.264), RFC 7587 (Opus), and Draft VVC payload format.
• Security: RFC 3711 (SRTP) and RFC 6189 (ZRTP).

The uvgRTP architecture is organized into three main hierarchical levels:

1. uvgrtp::context: The top-level object. It manages IP address bindings and CNAME namespace isolation. Typically, an application only needs one context.
2. uvgrtp::session: Allocated from a context. A session represents communication with a specific peer (local/remote address info) and handles ZRTP synchronization. The number of sessions usually matches the number of unique peers.
3. uvgrtp::media_stream: Contained within a session. Each stream corresponds to a single bi-directional or uni-directional media stream (e.g., one audio stream and one video stream).

If RTCP is enabled on a stream, you can access a uvgrtp::rtcp object from the media stream to send and receive RTCP packets.

To enable End-to-End Encryption (E2EE), use the following flag combinations in create_stream:

• RCE_SRTP | RCE_SRTP_KMNGMNT_ZRTP: Uses ZRTP for key negotiation.
• RCE_SRTP | RCE_SRTP_KMNGMNT_USER: Uses user-provided keys. If using this mode, you must call add_srtp_ctx(key, salt) on the created stream.

// Example for user-managed keys
uvgrtp::media_stream *strm = sess->create_stream(8888, 8888, RTP_FORMAT_GENERIC, RCE_SRTP | RCE_SRTP_KMNGMNT_USER);
strm->add_srtp_ctx(key, salt);

The default MTU size in uvgRTP is 1492 bytes. This accounts for UDP, IP, and RTP headers.

If your traffic passes through tunnels (like VPNs) or uses IPv6 to IPv4 translation, which add extra header overhead, you may need to lower the MTU size to prevent IP-level fragmentation. Conversely, if your network supports larger packets, you can increase it.

When RTCP is enabled (via RCE_RTCP), you can monitor network health using the rtcp_report_block structure.

By inspecting the fraction, lost, and jitter fields within the report block, your application can implement custom congestion control algorithms. Report blocks are generated by all media_stream entities receiving data and are included in both Sender Reports and Receiver Reports.

uvgRTP provides two API levels depending on your build type:

• Core API: A C-style, ABI-stable interface. This is the only API available in shared/dynamic builds (.dll and .so). It is the recommended API for most users.
• Extended API: A C++ interface using features like std::string and std::unique_ptr. This is only available in static builds of uvgRTP.

To begin using uvgRTP, follow these resources:

1. Tutorials: Follow the step-by-step guide in the USAGE.md file.
2. Practical Examples: Explore the examples/ directory for working code illustrating various usage scenarios.
3. API Reference: For a detailed description of all uvgRTP flags and advanced topics, consult the docs/README.md or the official Doxygen documentation.

If you prefer to manage SRTP keys and salts outside of uvgRTP, follow these steps:

1. Enable user management by passing RCE_SRTP | RCE_SRTP_KMNGMNT_USER to create_stream().
2. Immediately after create_stream() is called, you must provide the 128-bit keys and 112-bit salts to the uvgrtp::media_stream object using add_srtp_ctx().

Warning: All other calls to the media_stream object will fail if they are made before add_srtp_ctx() has been called.

// Example workflow for user-managed SRTP
auto stream = create_stream(RCE_SRTP | RCE_SRTP_KMNGMNT_USER);
stream.add_srtp_ctx(keys, salts);
// Subsequent calls are now valid

To prevent memory leaks and properly close connections, you must destroy resources in the reverse order of creation:

1. Destroy the stream using sess->destroy_stream(strm).
2. Destroy the session using ctx.destroy_session(sess).

sess->destroy_stream(strm);
ctx.destroy_session(sess);

Encryption can be enabled by passing specific flags to create_stream.

There are two modes:

1. ZRTP: Use RCE_SRTP | RCE_SRTP_KMNGMNT_ZRTP.
2. User-managed: Use RCE_SRTP | RCE_SRTP_KMNGMNT_USER. This mode requires you to manually provide the key and salt using add_srtp_ctx(key, salt) on the created stream object.

// Using ZRTP
uvgrtp::media_stream *strm = sess->create_stream(8888, 8888, RTP_FORMAT_GENERIC, RCE_SRTP | RCE_SRTP_KMNGMNT_ZRTP);

// Using User-managed keys
uvgrtp::media_stream *strm = sess->create_stream(8888, 8888, RTP_FORMAT_GENERIC, RCE_SRTP | RCE_SRTP_KMNGMNT_USER);
strm->add_srtp_ctx(key, salt);

uvgRTP can automatically negotiate encryption keys using ZRTP. To enable this, you must provide a specific combination of flags to create_stream().

Automatic Negotiation: Provide RCE_SRTP | RCE_SRTP_KMNGMNT_ZRTP to create_stream(). If using Multistream mode, also include RCE_ZRTP_MULTISTREAM_MODE for all relevant streams.

Manual Negotiation: If you want to control when negotiation starts (rather than it happening automatically upon stream creation):

1. Provide RCE_SRTP | RCE_ZRTP_DIFFIE_HELLMAN_MODE or RCE_SRTP | RCE_ZRTP_MULTISTREAM_MODE to create_stream().
2. Configure media stream values (like SSRC) using configure_ctx().
3. Trigger the negotiation manually using start_zrtp().

// Example flag combination for automatic ZRTP
create_stream(RCE_SRTP | RCE_SRTP_KMNGMNT_ZRTP | RCE_ZRTP_MULTISTREAM_MODE);