182 lines
14 KiB
HTML
182 lines
14 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
|
|
<meta name="generator" content="Doxygen 1.10.0"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>uvgRTP: uvgRTP</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<script type="text/javascript" src="clipboard.js"></script>
|
|
<script type="text/javascript" src="cookie.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr id="projectrow">
|
|
<td id="projectalign">
|
|
<div id="projectname">uvgRTP<span id="projectnumber"> 3.1.1</span>
|
|
</div>
|
|
<div id="projectbrief">An open-source library for RTP/SRTP media delivery</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.10.0 -->
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
|
/* @license-end */
|
|
</script>
|
|
<script type="text/javascript" src="menudata.js"></script>
|
|
<script type="text/javascript" src="menu.js"></script>
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(function() {
|
|
initMenu('',true,false,'search.php','Search');
|
|
$(function() { init_search(); });
|
|
});
|
|
/* @license-end */
|
|
</script>
|
|
<div id="main-nav"></div>
|
|
</div><!-- top -->
|
|
<!-- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
</div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<div id="MSearchResults">
|
|
<div class="SRPage">
|
|
<div id="SRIndex">
|
|
<div id="SRResults"></div>
|
|
<div class="SRStatus" id="Loading">Loading...</div>
|
|
<div class="SRStatus" id="Searching">Searching...</div>
|
|
<div class="SRStatus" id="NoMatches">No Matches</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div><div class="header">
|
|
<div class="headertitle"><div class="title">uvgRTP </div></div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p><a class="anchor" id="md_html_2_i_n_d_e_x"></a> uvgRTP is an <em>Real-Time Transport Protocol (RTP)</em> library written in C++ with a focus on simple to use and high-efficiency media delivery over the Internet. It features an intuitive and easy-to-use <em>Application Programming Interface (API)</em>, built-in support for transporting <em>Versatile Video Coding (VVC)</em>, <em>High Efficiency Video Coding (HEVC)</em>, <em>Advanced Video Coding (AVC)</em> encoded video and Opus encoded audio. uvgRTP also supports <em>End-to-End Encrypted (E2EE)</em> media delivery using the combination of <em>Secure RTP (SRTP)</em> and ZRTP. uvgRTP has been designed to minimize memory operations to reduce its CPU usage and latency.</p>
|
|
<p>uvgRTP is licensed under the permissive BSD 2-Clause License. This cross-platform library can be run on both Linux and Windows operating systems. Mac OS is also supported, but the support relies on community contributions. For SRTP/ZRTP support, uvgRTP uses the <a href="https://www.cryptopp.com/">Crypto++ library</a>.</p>
|
|
<p>Currently supported specifications:</p><ul>
|
|
<li><a href="https://datatracker.ietf.org/doc/html/rfc3550">RFC 3550: RTP: A Transport Protocol for Real-Time Applications</a></li>
|
|
<li><a href="https://datatracker.ietf.org/doc/html/rfc3551">RFC 3551: RTP Profile for Audio and Video Conferences</a></li>
|
|
<li><a href="https://datatracker.ietf.org/doc/html/rfc6184">RFC 6184: RTP Payload Format for H.264 Video</a></li>
|
|
<li><a href="https://datatracker.ietf.org/doc/html/rfc7798">RFC 7798: RTP Payload Format for High Efficiency Video Coding (HEVC)</a></li>
|
|
<li><a href="https://datatracker.ietf.org/doc/html/rfc9328">RFC 9328: RTP Payload Format for Versatile Video Coding (VVC)</a></li>
|
|
<li><a href="https://datatracker.ietf.org/doc/html/rfc7587">RFC 7587: RTP Payload Format for the Opus Speech and Audio Codec</a></li>
|
|
<li><a href="https://datatracker.ietf.org/doc/draft-ietf-avtcore-rtp-v3c/">RFC draft: RTP Payload Format for Visual Volumetric Video-based Coding (V3C)</a></li>
|
|
<li><a href="https://datatracker.ietf.org/doc/html/rfc3711">RFC 3711: The Secure Real-time Transport Protocol (SRTP)</a></li>
|
|
<li><a href="https://datatracker.ietf.org/doc/html/rfc6189">RFC 6189: ZRTP: Media Path Key Agreement for Unicast Secure RTP</a></li>
|
|
</ul>
|
|
<h1><a class="anchor" id="autotoc_md1"></a>
|
|
Notable features</h1>
|
|
<ul>
|
|
<li>AVC/HEVC/VVC video streaming, including packetization</li>
|
|
<li>V3C Atlas streaming, including packetization</li>
|
|
<li>Ready support for many formats which don't need packetization, including Opus</li>
|
|
<li>Delivery encryption with SRTP</li>
|
|
<li>Encryption key negotiation with ZRTP</li>
|
|
<li>UDP firewall hole punching</li>
|
|
<li>Simple to use API</li>
|
|
<li>Working examples</li>
|
|
<li>Permissive license</li>
|
|
</ul>
|
|
<h1><a class="anchor" id="autotoc_md2"></a>
|
|
Tutorial</h1>
|
|
<p>You can either include files individually from the include-folder or use <a class="el" href="lib_8hh_source.html">lib.hh</a> to include all necessary files with one line:</p>
|
|
<div class="fragment"><div class="line">#include <uvgrtp/lib.hh></div>
|
|
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md3"></a>
|
|
Step 1: Create context</h2>
|
|
<p>When using uvgRTP, you must always first create the <a class="el" href="classuvgrtp_1_1context.html" title="Provides CNAME isolation and can be used to create uvgrtp::session objects.">uvgrtp::context</a> object:</p>
|
|
<div class="fragment"><div class="line">uvgrtp::context ctx;</div>
|
|
</div><!-- fragment --> <h2><a class="anchor" id="autotoc_md4"></a>
|
|
Step 2: Create session</h2>
|
|
<p>Next, you will use the <a class="el" href="classuvgrtp_1_1context.html" title="Provides CNAME isolation and can be used to create uvgrtp::session objects.">uvgrtp::context</a> object to create <a class="el" href="classuvgrtp_1_1session.html" title="Provides ZRTP synchronization and can be used to create uvgrtp::media_stream objects.">uvgrtp::session</a> objects. The <a class="el" href="classuvgrtp_1_1session.html" title="Provides ZRTP synchronization and can be used to create uvgrtp::media_stream objects.">uvgrtp::session</a> object contains all media streams you are sending/receiving to/from single IP address. Broadcast addresses should also work. There are two options for creating this: 1) specify one address, role of which can be determined with RCE_SEND_ONLY or RCE_RECEIVE_ONLY flag later:</p>
|
|
<div class="fragment"><div class="line">uvgrtp::session *sess = ctx.create_session("10.10.10.2");</div>
|
|
</div><!-- fragment --><p> or 2) specify both remote and local addresses:</p>
|
|
<div class="fragment"><div class="line">uvgrtp::session *sess = ctx.create_session("10.10.10.2", "10.10.10.3");</div>
|
|
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md5"></a>
|
|
Step 3: Create media_stream</h2>
|
|
<p>To send/receive actual media, a <a class="el" href="classuvgrtp_1_1media__stream.html" title="The media_stream is an entity which represents one RTP stream.">uvgrtp::media_stream</a> object has to be created. The first parameter is the local port from which the sending happens and the second port is the port where the data is sent to (note that these are in the reverse order compared to creating the session). The third parameter specifies the RTP payload format which will be used for the outgoing and incoming data. The last parameter holds the flags that can be used to modify the behavior of created <a class="el" href="classuvgrtp_1_1media__stream.html" title="The media_stream is an entity which represents one RTP stream.">uvgrtp::media_stream</a>. The flags can be combined using bitwise OR-operation(|). These flags start with prefix <code>RCE_</code> and the explanations can be found in docs folder of repository. RTCP can be enabled with <code>RCE_RTCP</code>-flag.</p>
|
|
<div class="fragment"><div class="line">uvgrtp::media_stream *strm = sess->create_stream(8888, 8888, RTP_FORMAT_GENERIC, RCE_NO_FLAGS);</div>
|
|
</div><!-- fragment --><p>One port version of this also exists, to be used with RCE_SEND_ONLY and RCE_RECEIVE_ONLY flags: </p><div class="fragment"><div class="line">uvgrtp::media_stream *strm = sess->create_stream(8888, RTP_FORMAT_GENERIC, RCE_RECEIVE_ONLY);</div>
|
|
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md6"></a>
|
|
Step 3.1: Encryption (optional)</h2>
|
|
<p>The encryption can be enabled by specifying <code>RCE_SRTP | RCE_SRTP_KMNGMNT_ZRTP</code> or <code>RCE_SRTP | RCE_SRTP_KMNGMNT_USER</code> in the flags parameter of create_stream. The <code>RCE_SRTP_KMNGMNT_USER</code> requires calling <code>add_srtp_ctx(key, salt)</code> for the created <a class="el" href="classuvgrtp_1_1media__stream.html" title="The media_stream is an entity which represents one RTP stream.">uvgrtp::media_stream</a>.</p>
|
|
<h2><a class="anchor" id="autotoc_md7"></a>
|
|
Step 3.2: Configure media_stream (optional)</h2>
|
|
<p>Some of the <a class="el" href="classuvgrtp_1_1media__stream.html" title="The media_stream is an entity which represents one RTP stream.">uvgrtp::media_stream</a> functionality can be configured after the stream has been created: </p><div class="fragment"><div class="line">strm->configure_ctx(RCC_MTU_SIZE, 2312);</div>
|
|
</div><!-- fragment --><p>The flags start with prefix <code>RCC_</code> and the rest of the flags can be found in the docs folder. Also, see the configuration example for more details.</p>
|
|
<h2><a class="anchor" id="autotoc_md8"></a>
|
|
Step 4: Sending data</h2>
|
|
<p>Sending can be done by simple calling push_frame()-function on created <a class="el" href="classuvgrtp_1_1media__stream.html" title="The media_stream is an entity which represents one RTP stream.">uvgrtp::media_stream</a>:</p>
|
|
<div class="fragment"><div class="line">strm->push_frame((uint8_t *)message, msg_len, RTP_NO_FLAGS);</div>
|
|
</div><!-- fragment --><p> See the sending example for more details. uvgRTP does not take ownership of the memory unless the data is provided with std::unique_ptr.</p>
|
|
<h2><a class="anchor" id="autotoc_md9"></a>
|
|
Step 5: Receiving data</h2>
|
|
<p>There are two alternatives to receiving data. Using pull_frame()-function: </p><div class="fragment"><div class="line">auto frame = strm->pull_frame();</div>
|
|
</div><!-- fragment --><p>or function callback based approach (I would recommend this to minimize latency):</p>
|
|
<div class="fragment"><div class="line">strm->install_receive_hook(nullptr, rtp_receive_hook);</div>
|
|
</div><!-- fragment --><p>If you use classes, you can give a pointer to your class in the first parameter and call it in your callback function (an std::function API does not exist yet). In both versions of receiving, the user will be responsible for releasing the memory with the following function: </p><div class="fragment"><div class="line">uvgrtp::frame::dealloc_frame(frame);</div>
|
|
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md10"></a>
|
|
Step 6: Cleanup</h2>
|
|
<p>Cleanup can be done with following functions: </p><div class="fragment"><div class="line">sess->destroy_stream(strm);</div>
|
|
<div class="line">ctx.destroy_session(sess);</div>
|
|
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md11"></a>
|
|
Simple sending example (non-working)</h2>
|
|
<div class="fragment"><div class="line">#include <uvgrtp/lib.hh></div>
|
|
<div class="line"> </div>
|
|
<div class="line">/* g++ main.cc -luvgrtp -lpthread && ./a.out */</div>
|
|
<div class="line"> </div>
|
|
<div class="line">int main(void)</div>
|
|
<div class="line">{</div>
|
|
<div class="line"> uvgrtp::context ctx;</div>
|
|
<div class="line"> uvgrtp::session *sess = ctx.create_session("127.0.0.1");</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> uvgrtp::media_stream *strm = sess->create_stream(8888, 8888, RTP_FORMAT_GENERIC, RCE_NO_FLAGS);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> strm->configure_ctx(RCC_MTU_SIZE, 2312);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> char *message = (char *)"Hello, world!";</div>
|
|
<div class="line"> size_t msg_len = strlen(message) + 1;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> for (;;) {</div>
|
|
<div class="line"> strm->push_frame((uint8_t *)message, msg_len, RTP_NO_FLAGS);</div>
|
|
<div class="line"> auto frame = strm->pull_frame();</div>
|
|
<div class="line"> fprintf(stderr, "Message: '%s'\n", frame->payload);</div>
|
|
<div class="line"> uvgrtp::frame::dealloc_frame(frame);</div>
|
|
<div class="line"> }</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> sess->destroy_stream(strm);</div>
|
|
<div class="line"> ctx.destroy_session(sess);</div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --> </div></div><!-- PageDoc -->
|
|
<a href="doxygen_crawl.html"/>
|
|
</div><!-- contents -->
|
|
<!-- start footer part -->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.10.0
|
|
</small></address>
|
|
</body>
|
|
</html>
|