1 of 47

0.16.0 Quick Start

This page provides the fastest way to check playback of WebRTC and LLHLS using OvenMediaEngine. For installation and detailed settings, please refer to other pages.

Run OvenMediaEngine

Run docker with the command below. OME_HOST_IP must be an IP address accessible by the player.

$ docker run --name ome -d -e OME_HOST_IP=Your.HOST.IP.Address \
-p 1935:1935 -p 9999:9999/udp -p 9000:9000 -p 3333:3333 -p 3478:3478 -p 10000-10009:10000-10009/udp \
airensoft/ovenmediaengine:0.16.0

Check Status

You can check the docker container status with the following command:

$ docker ps -f name=ome
CONTAINER ID   IMAGE                              COMMAND                  CREATED              STATUS              PORTS                                                                                                                                                                                                                                                                                                           NAMES
c9dd9e56d7a0   airensoft/ovenmediaengine:latest   "/opt/ovenmediaengin…"   About a minute ago   Up About a minute   0.0.0.0:1935->1935/tcp, :::1935->1935/tcp, 80/tcp, 0.0.0.0:3333->3333/tcp, :::3333->3333/tcp, 3334/tcp, 8080/tcp, 0.0.0.0:3478->3478/tcp, :::3478->3478/tcp, 4000-4005/udp, 8090/tcp, 0.0.0.0:9000->9000/tcp, :::9000->9000/tcp, 10010/udp, 0.0.0.0:9999-10009->9999-10009/udp, :::9999-10009->9999-10009/udp   ome

You can view the log with the command below. This is important because you can check the version of OvenMediaEngine that is running.

$ docker logs ome -f
[2023-03-06 08:01:24.810] I [OvenMediaEngine:1] Config | config_manager.cpp:239  | Trying to set logfile in directory... (/var/log/ovenmediaengine)
[2023-03-06 08:01:24.810] I [OvenMediaEngine:1] Config | config_manager.cpp:261  | Trying to load configurations... (origin_conf/Server.xml)
[2023-03-06 08:01:24.816] I [OvenMediaEngine:1] OvenMediaEngine | banner.cpp:23   | OvenMediaEngine v0.15.1 () is started on [ab3995acafd4] (Linux x86_64 - 5.13.0-44-generic, #49~20.04.1-Ubuntu SMP Wed May 18 18:44:28 UTC 2022)
...

Run OvenPlayer Demo

$ docker run -d -p 8090:80 airensoft/ovenplayerdemo:latest

Check Status

You can access the OvenPlayerDemo docker container with a browser as shown below.

http://Your.Docker.Host.IP:8090/

Publishing

Publish your live stream to OvenMediaEngine using a live encoder like OBS.

Ingest URLs

RTMP - rtmp://Your.Docker.Host.IP:1935/app/stream

SRT - srt://Your.Docker.Host.IP:9999?streamid=srt%3A%2F%2FYour.Docker.Host.IP%3A9999%2Fapp%2Fstream

WHIP - http://Your.Docker.Host.IP:3333/app/stream?direction=whip

The RTMP publishing address is :

Server rtmp://Your.Docker.Host.IP:1935/app

Stream Key stream

The settings below are recommended for ultra-low latency.

Playback

Open the installed OvenPlayer Demo page in your browser.

http://Your.Docker.Host.IP:8090/

WebRTC Playback

Add ws://Your.Docker.Host.IP:3333/app/stream to the Playback URL and click the ADD SOURCE and LOAD PLAYER button to play the live stream with WebRTC.

LLHLS Playback

Add http://Your.Docker.Host.IP:3333/app/stream/llhls.m3u8 to the Playback URL and click the ADD SOURCE and LOAD PLAYER button to play the live stream with LLHLS.

Online Demo

Player & WebRTC Encoder

We provide online demos of OvenPlayer(WebRTC/LLHLS Player) and OvenLiveKit(WebRTC Live Encoder) so that users can easily test out OvenMediaEngine.

To connect to your OvenMediaEngine in the online demo, you will need to install a certificate and use either the HTTPS or WSS protocol. Unsecured HTTP or WS protocols could not work in online demos due to browser security policies.

OvenSpace

OvenSpace offers a fast and easy way to experience the powerful tools of OvenMediaEngine, OvenPlayer, and OvenLiveKit in action.

With OvenSpace, you can quickly and easily stream content with sub-second latency using WebRTC technology, or take advantage of Apple's LLHLS specification to deliver low-latency live streaming. The platform allows you to stream from various sources, including your webcam, microphone, screen, or an external live encoder that supports RTMP and SRT.

OvenSpace is available online, so you can try it out for yourself at https://space.ovenplayer.com/. You'll get a hands-on experience of how OvenMediaEngine, OvenPlayer, and OvenLiveKit work together seamlessly to deliver top-quality streaming, whether you're a developer looking to build a media service or someone who wants to experience sub-second or low-latency streaming firsthand.

OvenSpace is also available on Github as open source. It will be a good reference when developing media services using OvenMediaEngine, OvenPlayer and OvenLiveKit.

Getting Started

Getting Started with Docker Image

OvenMediaEngine provides Docker images from AirenSoft's Docker Hub (airensoft/ovenmediaengine) repository. You can easily use OvenMediaEngine server by using Docker image. See Getting Started with Docker for details.

Getting Started with Source Code

Installing dependencies

OvenMediaEngine can work with a variety of open-sources and libraries. First, install them on your clean Linux machine as described below. We think that OME can support most Linux packages, but the tested platforms we use are Ubuntu 18+, Fedora 28+, and CentOS 7+.

curl -LOJ https://github.com/AirenSoft/OvenMediaEngine/archive/v0.16.0.tar.gz && \
tar xvfz OvenMediaEngine-0.16.0.tar.gz && \
OvenMediaEngine-0.16.0/misc/prerequisites.sh

If the prerequisites.sh script fails, try to run sudo apt-get update and rerun it. If it's not enough proceed with the manual installation.

Building & Running

You can build the OvenMediaEngine source using the following command:

sudo apt-get update
cd OvenMediaEngine-0.16.0/src
make release
sudo make install
systemctl start ovenmediaengine
# If you want automatically start on boot
systemctl enable ovenmediaengine.service

sudo dnf update
cd OvenMediaEngine-0.16.0/src
make release
sudo make install
systemctl start ovenmediaengine
# If you want automatically start on boot
systemctl enable ovenmediaengine.service

sudo yum update
source scl_source enable devtoolset-7
cd OvenMediaEngine-0.16.0/src
make release
sudo make install
systemctl start ovenmediaengine
# If you want automatically start on boot
systemctl enable ovenmediaengine.service

In addition, we recommend that you permanently set environment variables as follows.

$ echo 'source scl_source enable devtoolset-7' >> ~/.bashrc

if systemctl start ovenmediaengine fails in Fedora, SELinux may be the cause. See Check SELinux section of Troubleshooting.

Ports used by default

The default configuration uses the following ports, so you need to open it in your firewall settings.

To use TLS, you must set up a certificate. See TLS Encryption for more information.

You can open firewall ports as in the following example:

$ sudo firewall-cmd --add-port=3333/tcp
$ sudo firewall-cmd --add-port=3334/tcp
$ sudo firewall-cmd --add-port=1935/tcp
$ sudo firewall-cmd --add-port=9999/udp
$ sudo firewall-cmd --add-port=4000/udp
$ sudo firewall-cmd --add-port=3478/tcp
$ sudo firewall-cmd --add-port=9000/tcp
$ sudo firewall-cmd --add-port=10000-10009/udp

Getting Started with Docker

Getting Started with default settings

OvenMediaEngine provides the Docker image from (airensoft/ovenmediaengine) repository. After installing , you can simply run the following command:

If a certificate is not installed in OvenMediaEngine, some functions (WebRTC Ingest, LLHLS playback) may not work due to the browser's security policy. Please refer to section to install the certificate.

You can set the following environment variables.

Environment Variables

Env

Default Value

Getting Started with Complex Configuration

When you need to install a certificate in OME or apply a complex configuration, you can do it by following the procedure below to modify Server.xml inside Docker.

OvenMediaEngine docker container loads configuration files from the following path.

There are many ways to change files inside a Docker container, but this document describes how to change them using Docker's bind mounts.

Setup

Create the directories

Copy the default configurations from Docker container

Copy the certificate files to the directory

Modify Server.xml if necessary

Running

Run Docker Container

The command below will make your OvenMediaEngine docker container run with $OME_DOCKER_HOME/conf/Server.xml and $OME_DOCKER_HOME/conf/Logger.xml files on your host. It will also create $OME_DOCKER_HOME/logs/ovenmediaengine.log file.

Check the log file

Restart Docker Container

Stop and Remove Container

Getting Started with OME Docker Launcher

Overview and Features

The OME Docker Launcher is a tool that simplifies the process of deploying and managing the OvenMediaEngine (OME) application using Docker containers. This tool can be used by developers and system administrators who want to quickly deploy and test the OME application in a Docker environment.

The OME Docker Launcher provides a set of commands that allow users to easily manage the OME Docker container. These commands include:

- This command pulls the OME Docker image(airensoft/ovenmediaengine:latest) from the Docker registry and copies the necessary configuration files to a specified location. This command needs to be run before starting the OME Docker container.
- This command creates and starts the Docker container. Once the container is started, the OME application can be accessed through a web browser using the container's IP address.
- This command launches a bash shell inside the running OME Docker container, allowing users to execute commands and interact with the container.
- This command displays the status of the running OME Docker container, including information such as the container name, and running status.
- This command stops the running OME Docker container.
- This command stops and then starts the OME Docker container.

Using the OME Docker Launcher, you can easily set up and manage an OME Docker container, without having to manually configure and manage the Docker container. This can save time and effort, especially for users who are not familiar with Docker or who do not want to spend time manually setting up and configuring the OME application.

OME Docker Launcher has not been tested in various environments yet. Therefore, sharing any issues that occur while using it is always welcome.

Installation

Run the following command in your Linux shell.

Commands

OME Docker Launcher can be executed in the following format:

`setup`

The setup command pulls the OME Docker image from the Docker registry and copies the necessary configuration files to the host's /usr/share/ovenmediaengine directory. Additionally, it initializes the log path and crash dump path that will be mounted into the container when it is run.

This command prepares the host environment for running the OME Docker container and sets up the necessary directories and configurations for the container to run correctly.

If you run the "setup" command, the following files and directories will be created:

/usr/share/ovenmediaengine/conf
- This directory contains the OME configuration files and is mounted into the container when it is run.
/usr/share/ovenmediaengine/logs
- This directory is the log path for OME and is mounted into the container when it is run. Log files generated by OME will be stored in this directory.
/usr/share/ovenmediaengine/dumps
- This directory is the crash dump path for OME and is mounted into the container when it is run. Crash dumps generated by OME will be stored in this directory.

If you want to change the configuration of OME, you can edit the /usr/share/ovenmediaengine/conf/Server.xml file. This file contains the server configuration settings for OME, such as the server's IP address, port, and SSL settings. Once you have made changes to this file, you will need to restart the OME Docker container for the changes to take effect. You can do this by running the restart command provided by the OME Docker Launcher.

`start`

Once the setup phase is complete, you can use the start command to run the OME Docker container. The start command creates and starts the Docker container, enabling the OME application to receive stream packets using protocols such as RTMP and SRT. Before running the start command, ensure that the necessary configuration files have been copied to the host's /usr/share/ovenmediaengine directory by running the setup command.

The OME Docker Launcher automatically detects a list of port numbers specified in the Server.xml file and passes them to the Docker -p option. However, if you use the include attribute inside the <Providers> or <Publishers> element, the launcher may not detect them correctly.

If you have used an environment variable form like ${env:<ENV_NAME>}, the OME Docker Launcher resolves the value of the <ENV_NAME> environment variable in the current shell. This enables you to dynamically set configuration values using environment variables.

`sh`

The sh command allows you to enter into the shell of the running container. You can use this command for troubleshooting purpose. Once you enter into the container's shell, you can execute any commands just like you do in a normal Linux shell. This allows you to inspect the container's internal state and debug any issues that you might be facing with the container or the application running inside it.

`status`

The status command shows the current execution status of the container. If the container is running, it displays the ID and name of the container. This command helps you to verify whether the container is up and running or not. If the container is not running, you can use the start command to start the container.

`stop`

The stop command stops the running container and removes it from the list of Docker containers.

`restart`

The restart command restarts the container. This is useful when you need to apply changes to the Server.xml.

Troubleshootings

Enable debug log

If you encounter any problems during the execution, try using the -d option in the [OPTIONS] to view detailed logs. This option shows the command sets and their results that are executed internally.

Get the crash dump of OME in the container

If OME terminates abnormally, providing the crash dump to the OME team can be helpful. The crash dump is stored in the /usr/share/ovenmediaengine/dumps directory, which is created during the setup phase. You can find the dump file named crash_<yyyymmdd>.dump in this directory.

Sharing those log and dump file would be greatly appreciated and helpful for the development of OME.

TLS Encryption

Most browsers can't load resources via HTTP and WS (WebSocket) from HTTPS web pages secured with TLS. Therefore, if the player is on an HTTPS page, the player must request streaming through "https" and "wss" URLs secured with TLS. In this case, you must apply the TLS certificate to the OvenMediaEngine.

You can set the port for TLS in TLSPort. Currently, LLHLS and WebRTC Signaling support TLS.

<Bind>
    <!-- For API Server -->
    <Managers>
	    <API>
	    <Port>8081</Port>
	    <TLSPort>8082</TLSPort>
            <WorkerCount>1</WorkerCount>
	</API>
    </Managers>
    <!-- For Providers -->
    <Providers>
        <WebRTC>
	    <Signalling>
		<Port>3333</Port>
		<TLSPort>3334</TLSPort>
		<WorkerCount>1</WorkerCount>
	    </Signalling>
            ...
        </WebRTC>
    </Providers>
    <!- For Publishers -->
    <Publishers>
        <LLHLS>
            <Port>80</Port>
            <TLSPort>443</TLSPort>
        </LLHLS>
        <WebRTC>
            <Signalling>
                <Port>3333</Port>
                <TLSPort>3334</TLSPort>
            </Signalling>
            ...
        </WebRTC>
    </Publishers>
</Bind>

Add your certificate files to as follows:

<!-- For API Server -->
<Managers>
  <Host>
    <Names>
      <Name>*</Name>
    </Names>
    <TLS>
      <CertPath>path/to/file.crt</CertPath>
      <KeyPath>path/to/file.key</KeyPath>
      <ChainCertPath>path/to/file.crt</ChainCertPath>
    </TLS>
  </Host>
  ...
</Managers>

<VirtualHosts>
  <VirtualHost>
    <!-- For Vitual Host -->
    <Host>
        <Names>
            <Name>*</Name>
        </Names>
        <TLS>
          <CertPath>/etc/pki/airensoft.com/_airensoft_com.crt</CertPath>
          <KeyPath>/etc/pki/airensoft.com/_airensoft_com.key</KeyPath>
          <ChainCertPath>/etc/pki/airensoft.com/_airensoft_com.ca-bundle</ChainCertPath>
        </TLS>
    </Host>

To enable HTTP for HLS and WebRTC signaling servers, you must enable the TLS element and install the certificate file in PEM format. This involves indicating a server certificate through the CertPath, as well as a private key file through the KeyPath. These paths can be specified as either absolute or relative paths from the executable. However, if the server certificate was issued using an intermediate certificate, some browsers may raise concerns about the certificate's authenticity. To address this, a bundle of chained certificates provided by a Certificate Authority can be set in the ChainCertPath.

Assuming the certificate settings are correctly configured, WebRTC streaming can then be played via the wss://url protocol, while LLHLS streaming can be accessed via https://url.

IPv6

Starting from version OME v0.15.1, IPv6 is supported.

To use IPv6, you need to change the settings of the Server.xml file as follows:

1. Configuration for listening

You can use /Server/IP to support IPv6. In versions prior to v0.15.0, only one /Server/IP setting could be specified, but in versions after v0.15.1, multiple settings can be specified. That is, if you add an /Server/IP element for IPv6 to the existing configuration as follows, you can accept IPv6 requests from clients:

<Server>
...
	<IP>*</IP>
	<!-- Listening the bind ports on IPv6 interfaces -->
	<IP>::</IP>
...

* means 0.0.0.0(INADDR_ANY) in IPv4, and :: means ::0(in6addr_any) in IPv6.

Of course, you can also specify a specific IP address of an interface instead of ::.

Example 1) IPv4 Only

<Server version="8">
    <Name>OvenMediaEngine</Name>
    <Type>origin</Type>
    <IP>*</IP>

    <Bind>
        <Providers>
            <RTMP>
                <Port>1935</Port>
            </RTMP>
        </Providers>
    </Bind>
</Server>

OME listens to the 1935 port for RTMP as follows:

$ sudo netstat -tulnp | grep "$(pgrep OvenMediaEngine)"
tcp        0      0 0.0.0.0:1935            0.0.0.0:*               LISTEN      xxx/OvenMediaEn

Example 2) IPv6 Only

<Server version="8">
    <Name>OvenMediaEngine</Name>
    <Type>origin</Type>
    <IP>::</IP>

    <Bind>
        <Providers>
            <RTMP>
                <Port>1935</Port>
            </RTMP>
        </Providers>
    </Bind>
</Server>

OME listens to the 1935 port for RTMP as follows:

$ sudo netstat -tulnp | grep "$(pgrep OvenMediaEngine)"
tcp6       0      0 :::1935                 :::*                    LISTEN      xxx/OvenMediaEn

Example 3) IPv4 + IPv6

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
    <Name>OvenMediaEngine</Name>
    <Type>origin</Type>
    <IP>*</IP>
    <IP>::</IP>

    <Bind>
        <Providers>
            <RTMP>
                <Port>1935</Port>
            </RTMP>
        </Providers>
    </Bind>
</Server>

OME listens to the 1935 port for RTMP as follows:

$ sudo netstat -tulnp | grep "$(pgrep OvenMediaEngine)"
tcp        0      0 0.0.0.0:1935            0.0.0.0:*               LISTEN      xxx/OvenMediaEn
tcp6       0      0 :::1935                 :::*                    LISTEN      xxx/OvenMediaEn

2. Configuration for `IceCandidates` (for WebRTC)

When you specify IPv6 interface /Server/IP, most Providers/Publishers will work with IPv6, but WebRTC will not. While the WebSocket server used as the WebRTC Signalling server works well with the above setting, but more setting is required for ICE Candidates that actually transmit/receive data.

To use IPv6 ICE Candidate, you need to add an IPv6 IceCandidate to /Server/Bind/(Providers|Publishers)/WebRTC/IceCandidates.

<Server version="8">
    ...
    <Bind>
        <Providers>
            <WebRTC>
                ...
                <IceCandidates>
                    <IceCandidate>*:10000/udp</IceCandidate>
                    <IceCandidate>[::]:10000/udp</IceCandidate>
                </IceCandidates>
...

To support IPv6 in URL format settings, use [::] instead of ::

The IceCandidate settings for Providers and Publishers are the same.

By setting up as above, OME is ready to use ICE Candidates for IPv6 as well as IPv4. The ICE Candidate generated here can be viewed in the signaling step of the web browser.

3. Configuration for `<Origin>`

Now you can set up the OME edge to look at an origin with an IPv6 IP address. To do this, you can set /Server/VirtualHosts/VirtualHost/Origins/Origin/Pass/Urls/Url as follows:

<Server version="8">
    ...
    <VirtualHosts>
        <VirtualHost>
            <Origins>
                <Origin>
                    <Location>/rtsp/stream</Location>
                    <Pass>
                        <Scheme>rtsp</Scheme>
                        <Urls>
                            <Url>airen:airen@[1:2:3:4:5:6:7:8]:1234/app/stream</Url>
                        </Urls>
                    </Pass>
                </Origin>
            </Origins>
  ...

This configuration creates a stream that refers an RTSP source provided on port 1234 of an origin which has an IPv6 address of 1:2:3:4:5:6:7:8.

4. Configuration for `<AdmissionWebhooks>`

You can also specify an IPv6 address for the server that AdmissionWebhooks is using. To do this, set the value of /Server/VirtualHosts/VirtualHost/AdmissionWebhooks/ControlServerUrl as follows:

<Server version="8">
    ...
    <VirtualHosts>
        <VirtualHost>
            <AdmissionWebhooks>
                <ControlServerUrl>http://[1:2:3:4:5:6:7:8]:7000/a/b/c</ControlServerUrl>

The above configuration asks whether the client has the permission to publish or playback using http://[1:2:3:4:5:6:7:8]:7000/a/b/c.

Live Source

OvenMediaEngine supports multiple protocols for input from various live sources, without compromising basic usability. This allows you to publish a variety of live sources with sub-second latency. See the sub-page for more information.

RTMP

Configuration

Providers ingests streams that come from a media source. OvenMediaEngine supports RTMP protocol. You can set it in the configuration as follows:

<Server>
    ...
    <Bind>
        <Providers>
            <RTMP>
              <Port>1935</Port>
            </RTMP>
        </Providers>
    </Bind>
    ...
    <VirtualHosts>
        <VirtualHost>
            <Application>
                <Providers>
                    <RTMP>
                    ...
                </RTMP>
                ...
                </Providers>
            <Application>
        </VirtualHost>
    </VirtualHosts>
</Server>

When a live source inputs to the <Application>, a stream is automatically created in the <Application>. The created stream is passed to Encoder and Publisher.

RTMP live stream

If you set up a live stream using an RTMP-based encoder, you need to set the following in Server.xml:

<Application>
   <Providers>
      <RTMP>
         <BlockDuplicateStreamName>true</BlockDuplicateStreamName>
      </RTMP>
   </Providers>
<Application>

<BlockDuplicateStreamName> is a policy for streams that are inputted as overlaps.

<BlockDuplicateStreamName> works with the following rules:

To allow the duplicated stream name feature can cause several problems. When a new stream is an input the player may be disconnected. Most encoders have the ability to automatically reconnect when it is disconnected from the server. As a result, two encoders compete and disconnect each other, which can cause serious problems in playback.

Publish

If you want to publish the source stream, you need to set the following in the Encoder:

URL RTMP://<OvenMediaEngine IP>[:<RTMP Listen Port>]/<App Name]>
Stream Key Stream Name

If you use the default configuration, the <RTMP><ListenPort> is 1935, which is the default port for RTMP. So it can be omitted. Also, since the Application named app is created by default in the default configuration, you can enter app in the [App Name]. You can define a Stream Key and use it in the Encoder, and the Streaming URL will change according to the Stream Key.

Moreover, some encoders can include a stream key in the URL, and if you use these encoders, you need to set it as follows:

URL RTMP://<OvenMediaEngine IP>[:<RTMP Listen Port>/<App Name>/<Stream Name>

Example with OvenLiveKit (OvenStreamEncoder)

If you are using the default configuration, press the URL button in the top right corner of OvenStreamEnoder, and enter the URL as shown below:

Also, <App name> and <Stream name> can be changed and used as desired in the configuration.

Example with OBS

If you use the default configuration, set the OBS as follows:

You can set the Stream Key to any name you like at any time.

WebRTC / WHIP

User can send video/audio from web browser to OvenMediaEngine via WebRTC without plug-in. Of course, you can use any encoder that supports WebRTC transmission as well as a browser.

Configuration

Bind

OvenMediaEngine supports self-defined signaling protocol and for WebRTC ingest.

You can set the port to use for signaling in <Bind><Provider><WebRTC><Signaling>. <Port> is for setting an unsecured HTTP port, and <TLSPort> is for setting a secured HTTP port that is encrypted with TLS.

For WebRTC ingest, you must set the ICE candidates of the OvenMediaEnigne server to <IceCandidates>. The candidates set in <IceCandate> are delivered to the WebRTC peer, and the peer requests communication with this candidate. Therefore, you must set the IP that the peer can access. If the IP is specified as *, OvenMediaEngine gathers all IPs of the server and delivers them to the peer.

Application

WebRTC input can be turned on/off for each application. As follows Setting enables the WebRTC input function of the application. The <CrossDomains> setting is used in WebRTC signaling.

URL Pattern

OvenMediaEnigne supports self-defined signaling protocol and WHIP for WebRTC ingest.

Self-defined Signaling URL

The signaling URL for WebRTC ingest uses the query string ?direction=send as follows to distinguish it from the url for WebRTC playback. Since the self-defined WebRTC signaling protocol is based on WebSocket, you must specify ws[s] as the scheme.

ws[s]://<host>[:signaling port]/<app name>/<stream name>?direction=send

WHIP URL

For ingest from the WHIP client, put ?direction=whip in the query string in the signaling URL as in the example below. Since WHIP is based on HTTP, you must specify http[s] as the scheme.

http[s]://<host>[:signaling port]/<app name>/<stream name>?direction=whip

WebRTC over TCP

ws[s]://<host>[:port]/<app name>/<stream name>?direction=send&transport=tcp
http[s]://<host>[:port]/<app name>/<stream name>?direction=whip&transport=tcp

To use WebRTC/tcp, <TcpRelay> must be turned on in <Bind> setting.

If <TcpForce> is set to true, it works over TCP even if you omit the ?transport=tcp query string from the URL.

WebRTC Producer

We provide a demo page so you can easily test your WebRTC input. You can access the demo page at the URL below.

Self-defined WebRTC Ingest Signaling Protocol

SRT

Secure Reliable Transport (or SRT in short) is an open source video transport protocol and technology stack that optimizes streaming performance across unpredictable networks with secure streams and easy firewall traversal, bringing the best quality live video over the worst networks. We consider SRT to be one of the great alternatives to RTMP, and OvenMediaEngine can receive video streaming over SRT. For more information on SRT, please visit the .

SRT uses the MPEG-TS format when transmitting live streams. This means that unlike RTMP, it can support many codecs. Currently, OvenMediaEngine supports H.264, H.265, and AAC codecs received by SRT.

Configuration

Bind

Set the SRT listen port as follows:

Application

SRT input can be turned on/off for each application. As follows Setting enables the SRT input function of the application.

Encoders and streamid

There are various encoders that support SRT such as FFMPEG, OBS Studio, and srt-live-transmit. Please check the specifications of each encoder on how to transmit streams through SRT from the encoder. We describe an example using OBS Studio.

streamid = percent_encoding("srt://{host}[:port]/{app name}/{stream name}[?query=value]")

OBS Studio

srt://ip:port?streamid=srt%3A%2F%2F{domain or IP address}[%3APort]%2F{App name}%2F{Stream name}

SRT Socket Options

You can configure SRT's socket options using <Options>. This is particularly useful when setting the encryption for SRT, and you can specify a passphrase by configuring as follows:

MPEG-2 TS

From version 0.10.4, MPEG-2 TS input is supported. The supported codecs are H.264, AAC(ADTS). Supported codecs will continue to be added. And the current version only supports basic MPEG-2 TS with 188 bytes packet size. Since the information about the input stream is obtained using PAT and PMT, the client must send this table information as required.

Configuration

To enable MPEG-2 TS, you must bind the ports fist and map the bound ports and streams.

Bind

To use multiple streams, it is necessary to bind multiple ports, so we provide a way to bind multiple ports as in the example below. You can use the dash to specify the port as a range, such as Start port-End port, and multiple ports using commas.

Stream mapping

First, name the stream and map the port bound above. The macro ${Port} is provided to map multiple streams at once. Check out the example below.

<Server>
    ...
    <Bind>
        <Providers>
            <MPEGTS>
                <!--
                    Listen on port 4000,4001,4004,4005
                    This is just a demonstration to show that 
                    you can configure the port in several ways
                -->
                <Port>4000-4001,4004,4005/udp</Port>
            </MPEGTS>
        </Providers>
    </Bind>
    ...
    <VirtualHosts>
        <VirtualHost>
            <Application>
                <Providers>
                    <MPEGTS>
                        <StreamMap>
                            <!--
                                Set the stream name of the client connected to the 
                                port to "stream_${Port}"
                                For example, if a client connets to port 4000, 
                                OME creates a "stream_4000" stream
                            -->
                            <Stream>
                                <Name>stream_${Port}</Name>
                                <Port>4000-4001,4004</Port>
                            </Stream>
                            <Stream>
                                <Name>stream_name_for_4005_port</Name>
                                <Port>4005</Port>
                            </Stream>
                        </StreamMap>
                    </MPEGTS>
                </Providers>
            <Application>
        </VirtualHost>
    </VirtualHosts>
</Server>

Publish

This is an example of publishing using FFMPEG.

# Video / Audio
ffmpeg.exe -re -stream_loop -1 -i <file.ext> -c:v libx264 -bf 0 -x264-params keyint=30:scenecut=0  -acodec aac -pes_payload_size 0 -f mpegts udp://<IP>:4000?pkt_size=1316

# Video only
ffmpeg.exe -re -stream_loop -1 -i <file.ext> -c:v libx264 -bf 0 -x264-params keyint=30:scenecut=0  -an -f mpegts udp://<IP>:4000?pkt_size=1316

# Audio only
ffmpeg.exe -re -stream_loop -1 -i <file.ext> -vn  -acodec aac -pes_payload_size 0 -f mpegts udp://<IP>:4000?pkt_size=1316

Giving the -pes_payload_size 0 option to the AAC codec is very important for AV synchronization and low latency. If this option is not given, FFMPEG bundles several ADTSs and is transmitted at once, which may cause high latency and AV synchronization errors.

RTSP Pull

OvenMediaEngine can pull RTSP Stream in two ways. The first way is to use the Stream creation API, and the second way is to use OriginMap or OriginMapStore. The supported codecs are H.264, AAC(ADTS). Supported codecs will continue to be added.

Pulling streams using the Stream Creation API

You can create a stream by pulling an RTSP stream using the Stream Creation API. For more information on using the REST API, check out that chapter.

Pulling streams using the OriginMapStore

If OriginMapStore is configured and Redis Server provides an rtsp URL, OvenMediaEngine pulls the RTSP URL when a playback request comes in. Check out OriginMapStore for more details.

Pulling streams using the OriginMap

Configuration

RTSP Pull is provided through OriginMap configuration. OriginMap is the rule that the Edge server pulls the stream of the Origin server. Edge server can pull a stream of origin with RTSP and OVT (protocol defined by OvenMediaEngine for Origin-Edge) protocol. See the Clustering section for more information about OVT.

<VirtualHosts>
    <VirtualHost include="VHost*.xml" />
    <VirtualHost>
        <Name>default</Name>

        <Host>
            <Names>
                <!-- Host names
                    <Name>stream1.airensoft.com</Name>
                    <Name>stream2.airensoft.com</Name>
                    <Name>*.sub.airensoft.com</Name>
                    <Name>192.168.0.1</Name>
                -->
                <Name>*</Name>
            </Names>
            <!--
            <TLS>
                <CertPath>path/to/file.crt</CertPath>
                <KeyPath>path/to/file.key</KeyPath>
                <ChainCertPath>path/to/file.crt</ChainCertPath>
            </TLS>
            -->
        </Host>
        
        <Origins>
            <Origin>
                <Location>/app_name/rtsp_stream_name</Location>
                <Pass>
                    <Scheme>rtsp</Scheme>
                    <Urls><Url>192.168.0.200:554/</Url></Urls>
                </Pass>
            </Origin>
        </Origins>
    </VirtualHost>
</VirtualHosts>

For example, in the above setup, when a player requests "ws://ome.com/app_name/rtsp_stream_name" to stream WebRTC, it pulls the stream from "rtsp://192.168.0.200:554" and publishes it to WebRTC.

If the app name set in Location isn't created, OvenMediaEngine creates the app with default settings. The default generated app doesn't have an OPUS encoding profile, so to use WebRTC streaming, you need to add the app to your configuration.

Event to trigger pulling

Pulling type providers are activated by streaming requests from publishers. And by default, the provider is automatically disabled after 30 seconds of no client playback. If you want to change this setting, check out the Clustering chapter.

When a playback request comes in from the following URL, RTSP pull starts working according to Origins settings.

ABR and Transcoding

OvenMediaEngine has a built-in live transcoder. The live transcoder can decode the incoming live source and re-encode it with the set codec or adjust the quality to encode at multiple bitrates.

Supported Video, Audio and Image Codecs

Decoders

Type

Codec

Encoders

Type

Codec

Codec of Configuration

OutputProfiles

OutputProfile

The <OutputProfile> setting allows incoming streams to be re-encoded via the <Encodes> setting to create a new output stream. The name of the new output stream is determined by the rules set in <OutputStreamName>, and the newly created stream can be used according to the streaming URL format.

<OutputProfiles>
    <OutputProfile>
        <Name>bypass_stream</Name>
        <OutputStreamName>${OriginStreamName}_bypass</OutputStreamName>
        <Encodes>
            <Video>
                <Bypass>true</Bypass>
            </Video>
            <Audio>
                <Bypass>true</Bypass>
            </Audio>            
            <Audio>
                <Codec>opus</Codec>
                <Bitrate>128000</Bitrate>
                <Samplerate>48000</Samplerate>
                <Channel>2</Channel>
            </Audio>
        </Encodes>
    </OutputProfile>
</OutputProfiles>

According to the above setting, if the incoming stream name is stream, the output stream becomes stream_bypassand the stream URL can be used as follows.

WebRTC ws://192.168.0.1:3333/app/stream_bypass
LLHLS http://192.168.0.1:8080/app/stream_bypass/llhls.m3u8

Encodes

Video

You can set the video profile as below:

<Encodes>
    <Video>
        <Name>h264_hd</Name>
        <Codec>h264</Codec>
        <Width>1280</Width>
        <Height>720</Height>
        <Bitrate>2000000</Bitrate>
        <Framerate>30.0</Framerate>
        <KeyFrameInterval>30</KeyFrameInterval>
        <BFrames>0</BFrames>
        <Preset>fast</Preset>
        <ThreadCount>4</ThreadCount>
    </Video>
</Encodes>

The meaning of each property is as follows:

* required

Table of presets

A table in which presets provided for each codec library are mapped to OvenMediaEngine presets. Slow presets are of good quality and use a lot of resources, whereas Fast presets have lower quality and better performance. It can be set according to your own system environment and service purpose.

References

https://trac.ffmpeg.org/wiki/Encode/VP8
https://docs.nvidia.com/video-technologies/video-codec-sdk/nvenc-preset-migration-guide/

Audio

You can set the audio profile as below:

<Encodes>
    <Audio>
        <Name>opus_128</Name>
        <Codec>opus</Codec>
        <Bitrate>128000</Bitrate>
        <Samplerate>48000</Samplerate>
        <Channel>2</Channel>
    </Audio>
</Encodes>

The meaning of each property is as follows:

* required

It is possible to have an audio only output profile by specifying the Audio profile and omitting a Video one.

Image

You can set the Image profile as below:

<Encodes>
    <Image>
        <Codec>jpeg</Codec>
        <Width>1280</Width>
        <Height>720</Height>
        <Framerate>1</Framerate>
    </Image>
</Encodes>

The meaning of each property is as follows:

The image encoding profile is only used by thumbnail publishers. and, bypass option is not supported.

Bypass without transcoding

You can configure Video and Audio to bypass transcoding as follows:

<Video>
    <Bypass>true</Bypass>
</Video>
<Audio>
    <Bypass>true</Bypass>
</Audio>

You need to consider codec compatibility with some browsers. For example, chrome only supports OPUS codec for audio to play WebRTC stream. If you set to bypass incoming audio, it can't play on chrome.

WebRTC doesn't support AAC, so if video bypasses transcoding, audio must be encoded in OPUS.

<Encodes>
    <Video>
        <Bypass>true</Bypass>
    </Video>
    <Audio>
        <Codec>opus</Codec>
        <Bitrate>128000</Bitrate>
        <Samplerate>48000</Samplerate>
        <Channel>2</Channel>
    </Audio>
</Encodes>

Conditional transcoding

If the codec or quality of the input stream is the same as the profile to be encoded into the output stream. there is no need to perform re-transcoding while unnecessarily consuming a lot of system resources. If the quality of the input track matches all the conditions of BypassIfMatch, it will be Pass-through without encoding

Matching elements in video

* eq: equal to / lte: less than or equal to / gte: greater than or equal to

Matching elements in audio

* eq: equal to / lte: less than or equal to / gte: greater than or equal to

To support WebRTC and LLHLS, AAC and Opus codecs must be supported at the same time. Use the settings below to reduce unnecessary audio encoding.

<Encodes>
	<Video>
                <Bypass>true</Bypass>	
	</Video>
	<Audio>
		<Name>cond_audio_aac</Name>
		<Codec>aac</Codec>
		<Bitrate>128000</Bitrate>
		<Samplerate>48000</Samplerate>
		<Channel>2</Channel>
		<BypassIfMatch>
			<Codec>eq</Codec>
			<Samplerate>lte</Samplerate>
			<Channel>eq</Channel>			
		</BypassIfMatch>
	</Audio>		
	<Audio>
		<Name>cond_audio_opus</Name>
		<Codec>opus</Codec>
		<Bitrate>128000</Bitrate>
		<Samplerate>48000</Samplerate>
		<Channel>2</Channel>
		<BypassIfMatch>
			<Codec>eq</Codec>
			<Samplerate>lte</Samplerate>
			<Channel>eq</Channel>	
		</BypassIfMatch>	
	</Audio>
</Encodes>

If a video track with a lower quality than the encoding option is input, unnecessary upscaling can be prevented. SAR (Storage Aspect Ratio) is the ratio of original pixels. In the example below, even if the width and height of the original video are smaller than or equal to the width and height set in the encoding option, if the ratio is different, it means that encoding is performed without bypassing.

<Encodes>
	<Video>                                                                                                    
		<Name>prevent_upscaling_video</Name>
		<Codec>h264</Codec>
		<Bitrate>2048000</Bitrate>
		<Width>1280</Width>
		<Height>720</Height>
		<Framerate>30</Framerate>
		<BypassIfMatch>
			<Codec>eq</Codec>
			<Width>lte</Width>
			<Height>lte</Height>
			<SAR>eq</SAR>
		</BypassIfMatch>
	</Video>
</Encodes>

Keep the original with transcoding

If you want to transcode with the same quality as the original. See the sample below for possible parameters that OME supports to keep original. If you remove the Width, Height, Framerate, Samplerate, and Channel parameters. then, It is transcoded with the same options as the original.

<Encodes>
    <Video>
        <Codec>vp8</Codec>
        <Bitrate>2000000</Bitrate>
    </Video>
     <Audio>
        <Codec>opus</Codec>
        <Bitrate>128000</Bitrate>
    </Audio>  
    <Image>
        <Codec>jpeg</Codec>
    </Image>
</Encodes>

Rescaling while keep the aspect ratio

To change the video resolution when transcoding, use the values of width and height in the Video encode option. If you don't know the resolution of the original, it will be difficult to keep the aspect ratio after transcoding. Please use the following methods to solve these problems. For example, if you input only the Width value in the Video encoding option, the Height value is automatically generated according to the ratio of the original video.

<Encodes>
    <Video>
        <Codec>h264</Codec>
        <Bitrate>2000000</Bitrate>
        <Width>1280</Width>
        <!-- Height is automatically calculated as the original video ratio -->
        <Framerate>30.0</Framerate>
    </Video>
    <Video>
        <Codec>h264</Codec>
        <Bitrate>2000000</Bitrate>
        <!-- Width is automatically calculated as the original video ratio -->
        <Height>720</Height>
        <Framerate>30.0</Framerate>
    </Video>    
</Encodes>

Adaptive Bitrate Streaming (ABR)

From version 0.14.0, OvenMediaEngine can encode same source with multiple bitrates renditions and deliver it to the player.

As shown in the example configuration below, you can provide ABR by adding <Playlists> to <OutputProfile>. There can be multiple playlists, and each playlist can be accessed with <FileName>.

The method to access the playlist set through LLHLS is as follows.

http[s]://<domain>[:port]/<app>/<stream>/<FileName>.m3u8

The method to access the Playlist set through WebRTC is as follows.

ws[s]://<domain>[:port]/<app>/<stream>/<FileName>

Note that <FileName> must never contain the playlist and chunklist keywords. This is a reserved word used inside the system.

To set up <Rendition>, you need to add <Name> to the elements of <Encodes>. Connect the set <Name> into <Rendition><Video> or <Rendition><Audio>.

In the example below, three quality renditions are provided and the URL to play the abr playlist as LLHLS is https://domain:port/app/stream/abr.m3u8 and The WebRTC playback URL is wss://domain:port/app/stream/abr

<OutputProfile>
	<Name>bypass_stream</Name>
	<OutputStreamName>${OriginStreamName}</OutputStreamName>
	<!--LLHLS URL : https://domain/app/stream/abr.m3u8 --> 
	<Playlist>
		<Name>For LLHLS</Name>
		<FileName>abr</FileName>
		<Options> <!-- Optinal -->
			<!-- 
			Automatically switch rendition in WebRTC ABR 
			[Default] : true
			-->
			<WebRtcAutoAbr>true</WebRtcAutoAbr> 
		</Options>
		<Rendition>
			<Name>Bypass</Name>
			<Video>bypass_video</Video>
			<Audio>bypass_audio</Audio>
		</Rendition>
		<Rendition>
			<Name>FHD</Name>
			<Video>video_1280</Video>
			<Audio>bypass_audio</Audio>
		</Rendition>
		<Rendition>
			<Name>HD</Name>
			<Video>video_720</Video>
			<Audio>bypass_audio</Audio>
		</Rendition>
	</Playlist>
	<!--LLHLS URL : https://domain/app/stream/llhls.m3u8 --> 
	<Playlist>
		<Name>Change Default</Name>
		<FileName>llhls</FileName>
		<Rendition>
			<Name>HD</Name>
			<Video>video_720</Video>
			<Audio>bypass_audio</Audio>
		</Rendition>
	</Playlist> 
	<Encodes>
		<Audio>
			<Name>bypass_audio</Name>
			<Bypass>true</Bypass>
		</Audio>
		<Video>
			<Name>bypass_video</Name>
			<Bypass>true</Bypass>
		</Video>
		<Audio>
			<Codec>opus</Codec>
			<Bitrate>128000</Bitrate>
			<Samplerate>48000</Samplerate>
			<Channel>2</Channel>
		</Audio>
		<Video>
			<Name>video_1280</Name>
			<Codec>h264</Codec>
			<Bitrate>5024000</Bitrate>
			<Framerate>30</Framerate>
			<Width>1920</Width>
			<Height>1280</Height>
			<Preset>faster</Preset>
		</Video>
		<Video>
			<Name>video_720</Name>
			<Codec>h264</Codec>
			<Bitrate>2024000</Bitrate>
			<Framerate>30</Framerate>
			<Width>1280</Width>
			<Height>720</Height>
			<Preset>faster</Preset>
		</Video>
	</Encodes>
</OutputProfile>

Supported codecs by streaming protocol

Even if you set up multiple codecs, there is a codec that matches each streaming protocol supported by OME, so it can automatically select and stream codecs that match the protocol. However, if you don't set a codec that matches the streaming protocol you want to use, it won't be streamed.

The following is a list of codecs that match each streaming protocol:

Therefore, you set it up as shown in the table. If you want to stream using LLHLS, you need to set up H.264 and AAC, and if you want to stream using WebRTC, you need to set up Opus.

Also, if you are going to use WebRTC on all platforms, you need to configure both VP8 and H.264. This is because different codecs are supported for each browser, for example, VP8 only, H264 only, or both.

However, don't worry. If you set the codecs correctly, OME automatically sends the stream of codecs requested by the browser.

Enable GPU Acceleration

OvenMediaEngine supports GPU-based hardware decoding and encoding. Currently supported GPU acceleration devices are Intel's QuickSync and NVIDIA's NVDECODE/NVENCODE. This document describes how to install the video driver for OvenMediaEngine to use the GPU and how to set the Config file. Please check what graphics card you have and refer to the NVIDIA or Intel driver installation guide.

1. Install GPU Driver

Install Intel QuickSync Driver

If you are using an Intel CPU that supports QuickSync, please refer to the following guide to install the driver. The OSes that support installation using the provided scripts are CentOS 7/8 and Ubuntu 18/20 versions. If you want to install the driver on a different OS, please refer to the Manual Installation Guide document.

When the Intel QuickSync driver installation is complete, the OS must be rebooted for normal operation.

(curl -LOJ https://github.com/AirenSoft/OvenMediaEngine/archive/master.tar.gz && tar xvfz OvenMediaEngine-master.tar.gz) 
OvenMediaEngine-master/misc/install_intel_driver.sh

How to check driver installation

After the driver installation is complete, check whether the driver operates normally with the Matrix Monitor program.

# Use the samples provided in the Intel Media SDK
# Check the list of codecs supported by iGPU
/MediaSDK-intel-mediasdk-21.1.2/build/__bin/release/simple_7_codec

Install NVIDIA GPU Driver

If you are using an NVIDIA graphics card, please refer to the following guide to install the driver. The OS that supports installation with the provided script are CentOS 7/8 and Ubuntu 18/20 versions. If you want to install the driver in another OS, please refer to the manual installation guide document.

CentOS environment requires the process of uninstalling the nouveau driver. After uninstalling the driver, the first reboot is required, and a new NVIDIA driver must be installed and rebooted. Therefore, two install scripts must be executed.

(curl -LOJ https://github.com/AirenSoft/OvenMediaEngine/archive/master.tar.gz && tar xvfz OvenMediaEngine-master.tar.gz)
OvenMediaEngine-master/misc/install_nvidia_driver.sh

How to check driver installation

After the driver installation is complete, check whether the driver is operating normally with the nvidia-smi command.

$ nvidia-smi

Thu Jun 17 10:20:23 2021
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 465.19.01    Driver Version: 465.19.01    CUDA Version: 11.3     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|                               |                      |               MIG M. |
|===============================+======================+======================|
|   0  NVIDIA GeForce ...  Off  | 00000000:01:00.0 Off |                  N/A |
| 20%   35C    P8    N/A /  75W |    156MiB /  1997MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+

+-----------------------------------------------------------------------------+
| Processes:                                                                  |
|  GPU   GI   CI        PID   Type   Process name                  GPU Memory |
|        ID   ID                                                   Usage      |
|=============================================================================|
|    0   N/A  N/A      1589      G   /usr/libexec/Xorg                  38MiB |
|    0   N/A  N/A      1730      G   /usr/bin/gnome-shell              115MiB |
+-----------------------------------------------------------------------------+

Manual Installation

If the provided installation script fails, please refer to the manual installation guide.

2. Prerequisites

If you have finished installing the driver to use the GPU, you need to reinstall the open source library using Prerequisites.sh . The purpose is to allow external libraries to use the installed graphics driver.

Using Intel QuickSync GPU

OvenMediaEngine-master/misc/prerequisites.sh --enable-qsv

Using NVIDIA GPU

OvenMediaEngine-master/misc/prerequisites.sh --enable-nvc

Using Docker with NVIDIA GPU

Describes how to enable GPU acceleration for users running OvenMediaEngine in the Docker runtime environment. To use GPU acceleration in Docker, the NVIDIA Driver must be installed on the host OS and the NVIDIA Container Toolkit must be installed. This toolkit includes container runtime libraries and utilities to use NVIDIA GPUs in Docker containers.

OvenMediaEngine-master/misc/install_nvidia_docker_container.sh

The NVIDIA Driver must have been previously installed

3. Configuration

To use hardware acceleration, set the HardwareAcceleration option to true under OutputProfiles. If this option is enabled, a hardware codec is automatically used when creating a stream, and if it is unavailable due to insufficient hardware resources, it is replaced with a software codec.

<VirtualHosts>
   <VirtualHost>
      <Name>default</Name>

      <!-- Settings for multi domain and TLS -->
      <Host>
         ...
      </Host>

      <!-- Settings for applications -->
      <Applications>
         <Application>
            <Name>app</Name>
            <Type>live</Type>
            <OutputProfiles>
               <!-- Settings to use hardware codecs -->
               <HardwareAcceleration>true</HardwareAcceleration>
               <OutputProfile>
                  <Name>bypass_stream</Name>
                  <OutputStreamName>${OriginStreamName}_o</OutputStreamName>
                  <Encodes>
                     <Video>
                        <Codec>h264</Codec>
                        <Width>1920</Width>
                        <Height>1080</Height>
                        <Bitrate>5000000</Bitrate>
                        <Framerate>30</Framerate>
                     </Video>
                     
                     <Video>
                        <Codec>h265</Codec>
                        <Width>1280</Width>
                        <Height>720</Height>
                        <Bitrate>5000000</Bitrate>
                        <Framerate>30</Framerate>
                     </Video> 
                  </Encodes>
               </OutputProfile>

            </OutputProfiles>
            <Providers>
               ...
            </Providers>
            <Publishers>
               ...
            </Publishers>
         </Application>
      </Applications>
   </VirtualHost>
</VirtualHosts>

4. Build & Run

You can build the OvenMediaEngine source using the following command. Same as the contents of Getting Started.

sudo apt-get update
cd OvenMediaEngine-master/src
make release
sudo make install
systemctl start ovenmediaengine
# If you want automatically start on boot
systemctl enable ovenmediaengine.service

sudo dnf update
cd OvenMediaEngine-master/src
make release
sudo make install
systemctl start ovenmediaengine
# If you want automatically start on boot
systemctl enable ovenmediaengine.service

sudo yum update
source scl_source enable devtoolset-7
cd OvenMediaEngine-master/src
make release
sudo make install
systemctl start ovenmediaengine
# If you want automatically start on boot
systemctl enable ovenmediaengine.service

How to build and run docker image

To use Docker, you need to build a new Docker image. To build an OvenMediaEngine image with GPU support, you need to set some parameters. First, check the major version of the NVIDIA driver installed on the host OS

Set the major version as the value of the NVIDIA_DRIVER argument when building docker image.

docker build --file Dockerfile -t airensoft/ovenmediaengine:dev --build-arg GPU=TRUE --build-arg NVIDIA_DRIVER=470

After the build is complete, you must include the --gpus all option when running Docker

docker run -d -p 1935:1935 -p 4000-4005:4000-4005/udp -p 3333:3333 -p 3478:3478 -p 8080:8080 -p 9000:9000 -p 9999:9999/udp -p 10006-10010:10006-10010/udp --gpus all airensoft/ovenmediaengine:dev

Support Format

The codecs available using hardware accelerators in OvenMediaEngine are as shown in the table below. Different GPUs support different codecs. If the hardware codec is not available, you should check if your GPU device supports the codec.

D : Decoding, E : Encoding

Reference

Quick Sync Video Format : https://en.wikipedia.org/wiki/Intel_Quick_Sync_Video
NVIDIA NVDEC Video Format : https://en.wikipedia.org/wiki/Nvidia_NVDEC
NVIDIA NVENV Video Format : https://en.wikipedia.org/wiki/Nvidia_NVENC
CUDA Toolkit Installation Guide : https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#introduction
NVIDIA Container Toolkit : https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/arch-overview.html#arch-overview
Quick Sync Video format support: https://en.wikipedia.org/wiki/Intel_Quick_Sync_Video

Manual Installation

Intel QuickSync Driver Installation

Platform Specific Installation

sudo apt install -y libdrm-dev xorg xorg-dev openbox libx11-dev 
sudo apt install -y libgl1-mesa-glx libgl1-mesa-dev

# Centos 7 uses the 2.8.x version of cmake by default. 
# It must be changed to version 3.x or higher.
sudo yum remove -y cmake
sudo yum install -y cmake3
sudo ln -s /usr/bin/cmake3 /usr/bin/cmake

sudo yum install -y libdrm-devel libX11-devel libXi-devel

sudo yum install -y libdrm-devel libX11-devel libXi-devel

Common Installation

LibVA

PREFIX=/opt/ovenmediaengine && \
TEMP_PATH=/tmp && \
LIBVA_VERSION=2.11.0 && \
DIR=${TEMP_PATH}/libva && \
mkdir -p ${DIR} && \
cd ${DIR} && \
curl -sLf https://github.com/intel/libva/archive/refs/tags/${LIBVA_VERSION}.tar.gz | tar -xz --strip-components=1 && \
./autogen.sh --prefix="${PREFIX}" && \
make -j$(nproc) && \
sudo make install && \
rm -rf ${DIR})

GMMLIB

PREFIX=/opt/ovenmediaengine && \
TEMP_PATH=/tmp && \
GMMLIB_VERSION=20.4.1 && \
DIR=${TEMP_PATH}/gmmlib && \
mkdir -p ${DIR} && \
cd ${DIR} && \
curl -sLf https://github.com/intel/gmmlib/archive/refs/tags/intel-gmmlib-${GMMLIB_VERSION}.tar.gz | tar -xz --strip-components=1 && \
mkdir -p ${DIR}/build && \
cd ${DIR}/build && \
cmake -DCMAKE_INSTALL_PREFIX="${PREFIX}" .. && \
make -j$(nproc) && \
sudo make install && \
rm -rf ${DIR}

Intel Media Driver

PREFIX=/opt/ovenmediaengine && \
TEMP_PATH=/tmp && \
INTEL_MEDIA_DRIVER_VERSION=20.4.5 && \
DIR_IMD=${TEMP_PATH}/media-driver && \
mkdir -p ${DIR_IMD} && \
cd ${DIR_IMD} && \
curl -sLf https://github.com/intel/media-driver/archive/refs/tags/intel-media-${INTEL_MEDIA_DRIVER_VERSION}.tar.gz  | tar -xz --strip-components=1 && \
DIR_GMMLIB=${TEMP_PATH}/gmmlib && \
mkdir -p ${DIR_GMMLIB} && \
cd ${DIR_GMMLIB} && \
curl -sLf https://github.com/intel/gmmlib/archive/refs/tags/intel-gmmlib-${GMMLIB_VERSION}.tar.gz | tar -xz --strip-components=1 && \
DIR=${TEMP_PATH}/build && \
mkdir -p ${DIR} && \
cd ${DIR} && \
PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig:${PKG_CONFIG_PATH} cmake \
    $DIR_IMD \
    -DBUILD_TYPE=release \
    -DBS_DIR_GMMLIB="$DIR_GMMLIB/Source/GmmLib" \
    -DBS_DIR_COMMON=$DIR_GMMLIB/Source/Common \
    -DBS_DIR_INC=$DIR_GMMLIB/Source/inc \
    -DBS_DIR_MEDIA=$DIR_IMD \
    -DCMAKE_INSTALL_PREFIX=${PREFIX} \
    -DCMAKE_INSTALL_LIBDIR=${PREFIX}/lib \
    -DINSTALL_DRIVER_SYSCONF=OFF \
    -DLIBVA_DRIVERS_PATH=${PREFIX}/lib/dri && \
sudo make -j$(nproc) install && \
rm -rf ${DIR} && \
rm -rf ${DIR_IMD} && \
rm -rf ${DIR_GMMLIB}

export LIBVA_DRIVERS_PATH=${PREFIX}/lib
export LIBVA_DRIVER_NAME=iHD

Intel Media SDK

PREFIX=/opt/ovenmediaengine && \
TEMP_PATH=/tmp && \
INTEL_MEDIA_SDK_VERSION=20.5.1 && \
DIR=${TEMP_PATH}/medka-sdk && \
mkdir -p ${DIR} && \
cd ${DIR} && \
curl -sLf https://github.com/Intel-Media-SDK/MediaSDK/archive/refs/tags/intel-mediasdk-${INTEL_MEDIA_SDK_VERSION}.tar.gz  | tar -xz --strip-components=1 && \
mkdir -p ${DIR}/build && \
cd ${DIR}/build && \
PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig:${PKG_CONFIG_PATH} cmake -DCMAKE_INSTALL_PREFIX="${PREFIX}" .. && \
make -j$(nproc) && \
sudo make install && \
rm -rf ${DIR}

All libraries are installed, the system must be rebooted.

NVIDIA Driver Installation

Platform Specific Installation

# Uninstalling a previously installed NVIDIA Driver
sudo apt-get remove --purge nvidia-*
sudo apt-get -y autoremove
sudo apt-get -y update

# Remove the nouveau driver. If the nouveau driver is in use, the nvidia driver cannot be installed.
USE_NOUVEAU=`sudo lshw -class video | grep nouveau`
if [ ! -z "$USE_NOUVEAU" ]; then

        # Disable nouveau Driver
        echo "blacklist nouveau" >> /etc/modprobe.d/blacklist.conf
        echo "blacklist lbm-nouveau" >> /etc/modprobe.d/blacklist.conf
        echo "options nouveau modeset=0" >> /etc/modprobe.d/blacklist.conf
        echo "alias nouveau off" >> /etc/modprobe.d/blacklist.conf
        echo "alias lbm-nouveau off" >> /etc/modprobe.d/blacklist.conf
        sudo update-initramfs -u
        echo "Using a driver display nouveau.Remove the driver and reboot.Reboot and installation script to rerun the nvidia display the driver to complete the installation."

        sleep 5s
        reboot
fi

# Install Nvidia Driver and Nvidia Toolkit
sudo add-apt-repository ppa:graphics-drivers/ppa
sudo apt -y update
sudo apt-get install -y $(ubuntu-drivers devices | grep recommended | awk '{print $3}')
sudo apt-get install -y nvidia-cuda-toolkit curl make

# Update Kernel
yum -y update
yum -y groupinstall "Development Tools"
yum -y install kernel-devel
yum -y install epel-release
yum -y install dkms curl
echo "Reboot is required to run with a new version of the kernel."

# Remove the nouveau driver. If the nouveau driver is in use, the nvidia driver cannot be installed.
USE_NOUVEAU=`sudo lshw -class video | grep nouveau`
if [ ! -z "$USE_NOUVEAU" ]; then

        # Disable nouveau Driver
        sed "s/GRUB_CMDLINE_LINUX=\"\(.*\)\"/GRUB_CMDLINE_LINUX=\"\1 rd.driver.blacklist=nouveau nouveau.modeset=0\"/" /etc/default/grub
        grub2-mkconfig -o /boot/grub2/grub.cfg
        echo "blacklist nouveau" >> /etc/modprobe.d/blacklist.conf
        mv /boot/initramfs-$(uname -r).img /boot/initramfs-$(uname -r)-nouveau.img
        dracut /boot/initramfs-$(uname -r).img $(uname -r)

        echo "Using a driver display nouveau. so, remove the driver and reboot. "
        echo "After reboot and installation script to rerun the nvidia display the driver to complete the installation."

        sleep 5s
        reboot
fi

# Install Nvidia Driver
# https://www.nvidia.com/en-us/drivers/unix/
systemctl isolate multi-user.target
wget -N https://us.download.nvidia.com/XFree86/Linux-x86_64/460.84/NVIDIA-Linux-x86_64-460.84.run
sh ./NVIDIA-Linux-x86_64-460.84.run --ui=none --no-questions

# Install Nvidia Toolkit
# https://developer.nvidia.com/cuda-downloads
wget -N https://developer.download.nvidia.com/compute/cuda/11.3.1/local_installers/cuda_11.3.1_465.19.01_linux.run
sh cuda_11.3.1_465.19.01_linux.run --silent

# Configure Envionment Variables
echo "Please add the PATH below to the environment variable."
echo ""
echo "export PATH=${PATH}:/usr/local/cuda/bin/"
echo ""
export PATH=${PATH}:/usr/local/cuda/bin/

dnf update -y
dnf groupinstall -y "Development Tools" 
dnf install -y elfutils-libelf-devel "kernel-devel-uname-r == $(uname -r)"

# Remove the nouveau driver. If the nouveau driver is in use, the nvidia driver cannot be installed.
USE_NOUVEAU=`sudo lshw -class video | grep nouveau`
if [ ! -z "$USE_NOUVEAU" ]; then

        # Disable nouveau Driver
        echo "blacklist nouveau" >> /etc/modprobe.d/blacklist.conf
        mv /boot/initramfs-$(uname -r).img /boot/initramfs-$(uname -r)-nouveau.img
        dracut /boot/initramfs-$(uname -r).img $(uname -r)

        systemctl set-default multi-user.target
        systemctl get-default

        echo "Using a driver display nouveau. so, remove the driver and reboot. "
        echo "After reboot and installation script to rerun the nvidia display the driver to complete the installation."

        sleep 5s
        reboot
fi

wget -N https://us.download.nvidia.com/XFree86/Linux-x86_64/460.84/NVIDIA-Linux-x86_64-460.84.run
sh ./NVIDIA-Linux-x86_64-460.84.run --ui=none --no-questions

# Install Nvidia Toolkit
# https://developer.nvidia.com/cuda-downloads
wget -N https://developer.download.nvidia.com/compute/cuda/11.3.1/local_installers/cuda_11.3.1_465.19.01_linux.run
sh cuda_11.3.1_465.19.01_linux.run --silent

systemctl set-default graphical.target
systemctl get-default

# Configure Envionment Variables
echo "Please add the PATH below to the environment variable."
echo ""
echo "export PATH=${PATH}:/usr/local/cuda/bin/"
echo ""
export PATH=${PATH}:/usr/local/cuda/bin/

Common Installation

NVCC Headers

PREFIX=/opt/ovenmediaengine && \
TEMP_PATH=/tmp && \
NVCC_HEADERS=11.0.10.1 && \
DIR=${TEMP_PATH}/nvcc-hdr && \
mkdir -p ${DIR} && \
cd ${DIR} && \
curl -sLf https://github.com/FFmpeg/nv-codec-headers/releases/download/n${NVCC_HEADERS}/nv-codec-headers-${NVCC_HEADERS}.tar.gz | tar -xz --strip-components=1 && \
sudo make install && \
rm -rf ${DIR}

NVIDIA Container Toolkit Installation

Platform Specific Installation

# Install Docker 2.x
curl https://get.docker.com && sudo systemctl --now enable docker

# Install NVIDIA Docker Toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID) && \
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - && \
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update
sudo apt-get install -y nvidia-docker2

# Restart Docker
sudo systemctl restart docker

# Test
sudo docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi

sudo yum install -y yum-utils
sudo yum-config-manager --add-repo=https://download.docker.com/linux/centos/docker-ce.repo
sudo yum repolist -v
sudo yum install -y https://download.docker.com/linux/centos/7/x86_64/stable/Packages/containerd.io-1.4.3-3.1.el7.x86_64.rpm
sudo yum install docker-ce -y
sudo systemctl --now enable docker

# Install NVIDIA Docker Toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID) && \
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.repo | sudo tee /etc/yum.repos.d/nvidia-docker.repo

if [[ "${OSVERSION}" == "7" ]]; then
    sudo yum clean expire-cache
    sudo yum install -y nvidia-docker2
elif [[ "${OSVERSION}" == "8" ]]; then
    sudo dnf clean expire-cache --refresh
    sudo dnf install -y nvidia-docker2
else
    fail_exit
fi    

# Restart Docker
sudo systemctl restart docker    

# Test
sudo docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi

sudo dnf install -y dnf-utils
sudo dnf config-manager --add-repo=https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf repolist -v
sudo dnf install -y https://download.docker.com/linux/centos/7/x86_64/stable/Packages/containerd.io-1.4.3-3.1.el7.x86_64.rpm
sudo dnf install docker-ce -y
sudo systemctl --now enable docker

# Install NVIDIA Docker Toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID) && \
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.repo | sudo tee /etc/yum.repos.d/nvidia-docker.repo

if [[ "${OSVERSION}" == "7" ]]; then
    sudo yum clean expire-cache
    sudo yum install -y nvidia-docker2
elif [[ "${OSVERSION}" == "8" ]]; then
    sudo dnf clean expire-cache --refresh
    sudo dnf install -y nvidia-docker2
else
    fail_exit
fi    

# Restart Docker
sudo systemctl restart docker    

# Test
sudo docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi

Streaming

WebRTC Streaming

OvenMediaEngine uses WebRTC to provide sub-second latency streaming. WebRTC uses RTP for media transmission and provides various extensions.

OvenMediaEngine provides the following features:

Title

Functions

Configuration

If you want to use the WebRTC feature, you need to add <WebRTC> element to the <Publishers> and <Ports> in the Server.xml configuration file, as shown in the example below.

<Bind>
    <Publishers>
        <WebRTC>
            <Signalling>
                <Port>3333</Port>
                <TLSPort>3334</TLSPort>
                <WorkerCount>1</WorkerCount>
            </Signalling>
            <IceCandidates>
                <IceCandidate>*:10000-10005/udp</IceCandidate>
                <TcpRelay>*:3478</TcpRelay>
                <TcpForce>true</TcpForce>
                <TcpRelayWorkerCount>1</TcpRelayWorkerCount>
            </IceCandidates>
        </WebRTC>
    </Publishers>
</Bind>

ICE

WebRTC uses ICE for connections and specifically NAT traversal. The web browser or player exchanges the Ice Candidate with each other in the Signalling phase. Therefore, OvenMediaEngine provides an ICE for WebRTC connectivity.

If you set IceCandidate to *: 10000-10005/udp, as in the example above, OvenMediaEngine automatically gets IP from the server and generates IceCandidate using UDP ports from 10000 to 10005. If you want to use a specific IP as IceCandidate, specify a specific IP. You can also use only one 10000 UDP Port, not a range, by setting it to *: 10000.

Signalling

OvenMediaEngine has embedded a WebSocket-based signalling server and provides our defined signalling protocol. Also, OvenPlayer supports our signalling protocol. WebRTC requires signalling to exchange Offer SDP and Answer SDP, but this part isn't standardized. If you want to use SDP, you need to create your exchange protocol yourself.

If you want to change the signaling port, change the value of <Ports><WebRTC><Signalling>.

Signalling Protocol

The Signalling protocol is defined in a simple way:

If you want to use a player other than OvenPlayer, you need to develop the signalling protocol as shown above and can integrate OvenMediaEngine.

Streaming

Publisher

Add WebRTC element to Publisher to provide streaming through WebRTC.

<Server version="7">
    <VirtualHosts>
        <VirtualHost>
            <Applications>
                <Application>
                    <Publishers>
                      <WebRTC>
                            <Timeout>30000</Timeout>
                            <Rtx>false</Rtx>
                            <Ulpfec>false</Ulpfec>
                            <JitterBuffer>false</JitterBuffer>
                        </WebRTC>
                    </Publishers>
                </Application>
            </Applications>
        </VirtualHost>
    </VirtualHosts>
</Server>

WebRTC Publisher's <JitterBuffer> is a function that evenly outputs A/V (interleave) and is useful when A/V synchronization is no longer possible in the browser (player) as follows.

If the A/V sync is excessively out of sync, some browsers may not be able to handle this or it may take several seconds to synchronize.
Players that do not support RTCP also cannot A/V sync.

Encoding

WebRTC Streaming starts when a live source is inputted and a stream is created. Viewers can stream using OvenPlayer or players that have developed or applied the OvenMediaEngine Signalling protocol.

Also, the codecs supported by each browser are different, so you need to set the Transcoding profile according to the browser you want to support. For example, Safari for iOS supports H.264 but not VP8. If you want to support all browsers, please set up VP8, H.264, and Opus codecs in all transcoders.

WebRTC doesn't support AAC, so when trying to bypass transcoding RTMP input, audio must be encoded as opus. See the settings below.

<OutputProfiles>
    <OutputProfile>
        <Name>bypass_stream</Name>
        <OutputStreamName>${OriginStreamName}</OutputStreamName>
        <Encodes>
            <Audio>
                <Bypass>true</Bypass>
            </Audio>
            <Video>
                <Bypass>true</Bypass>
            </Video>
            <Video>
                <!-- vp8, h264 -->
                <Codec>vp8</Codec>
                <Width>1280</Width>
                <Height>720</Height>
                <Bitrate>2000000</Bitrate>
                <Framerate>30.0</Framerate>
            </Video>
            <Audio>
                <Codec>opus</Codec>
                <Bitrate>128000</Bitrate>
                <Samplerate>48000</Samplerate>
                <Channel>2</Channel>
            </Audio>
        </Encodes>
    </OutputProfile>
</OutputProfiles>

Some browsers support both H.264 and VP8 to send Answer SDP to OvenMediaEngine, but sometimes H.264 can't be played. In this situation, if you write the VP8 above the H.264 code line in the Transcoding profile setting, you can increase the priority of the VP8.

Using this manner so that some browsers, support H.264 but can't be played, can stream smoothly using VP8. This means that you can solve most problems with this method.

Playback

If you created a stream as shown in the table above, you can play WebRTC on OvenPlayer via the following URL:

If you use the default configuration, you can stream to the following URL:

ws://[OvenMediaEngine IP]:3333/app/stream
wss://[OvenMediaEngine IP]:3333/app/stream

We have prepared a test player to make it easy to check if OvenMediaEngine is working. Please see the Test Player chapter for more information.

Adaptive Bitrates Streaming (ABR)

OvenMediaEnigne provides adaptive bitrates streaming over WebRTC. OvenPlayer can also play and display OvenMediaEngine's WebRTC ABR URL.

Create Playlist for WebRTC ABR

You can provide ABR by creating a playlist in <OutputProfile> as shown below. The URL to play the playlist is ws[s]://domain[:port]/<app name>/<stream name>/<playlist file name>

<Playlist><Rendition><Video> and <Playlist><Rendition><Audio> can connected using <Encodes><Video><Name> or <Encodes><Audio><Name>.

It is not recommended to use a <Bypass>true</Bypass> encode item if you want a seamless transition between renditions because there is a time difference between the transcoded track and bypassed track.

If <Options><WebRtcAutoAbr> is set to true, OvenMediaEngine will measure the bandwidth of the player session and automatically switch to the appropriate rendition.

Here is an example play URL for ABR in the playlist settings below. wss://domain:13334/app/stream/abr

Streaming starts from the top rendition of Playlist, and when Auto ABR is true, the server finds the best rendition and switches to it. Alternatively, the user can switch manually by selecting a rendition in the player.

<OutputProfiles>
<OutputProfile>
    <Name>default</Name>
    <OutputStreamName>${OriginStreamName}</OutputStreamName>

    <Playlist>
        <Name>for Webrtc</Name>
        <FileName>abr</FileName>
        <Options>
            <WebRtcAutoAbr>false</WebRtcAutoAbr> 
        </Options>
        <Rendition>
            <Name>1080p</Name>
            <Video>1080p</Video>
            <Audio>opus</Audio>
        </Rendition>
        <Rendition>
            <Name>480p</Name>
            <Video>480p</Video>
            <Audio>opus</Audio>
        </Rendition>
        <Rendition>
            <Name>720p</Name>
            <Video>720p</Video>
            <Audio>opus</Audio>
        </Rendition>
    </Playlist>

    <Playlist>
        <Name>for llhls</Name>
        <FileName>llhls_abr</FileName>
        <Rendition>
            <Name>480p</Name>
            <Video>480p</Video>
            <Audio>bypass_audio</Audio>
        </Rendition>
        <Rendition>
            <Name>720p</Name>
            <Video>720p</Video>
            <Audio>bypass_audio</Audio>
        </Rendition>
    </Playlist>
    
    <Encodes>
        <Video>
            <Name>bypass_video</Name>
            <Bypass>true</Bypass>
        </Video>
        <Video>
            <Name>480p</Name>
            <Codec>h264</Codec>
            <Width>640</Width>
            <Height>480</Height>
            <Bitrate>500000</Bitrate>
            <Framerate>30</Framerate>
        </Video>
        <Video>
            <Name>720p</Name>
            <Codec>h264</Codec>
            <Width>1280</Width>
            <Height>720</Height>
            <Bitrate>2000000</Bitrate>
            <Framerate>30</Framerate>
        </Video>
        <Video>
            <Name>1080p</Name>
            <Codec>h264</Codec>
            <Width>1920</Width>
            <Height>1080</Height>
            <Bitrate>5000000</Bitrate>
            <Framerate>30</Framerate>
        </Video>
        <Audio>
            <Name>bypass_audio</Name>
            <Bypass>True</Bypass>
        </Audio>
        <Audio>
            <Name>opus</Name>
            <Codec>opus</Codec>
            <Bitrate>128000</Bitrate>
            <Samplerate>48000</Samplerate>
            <Channel>2</Channel>
        </Audio>
    </Encodes>
</OutputProfile>
</OutputProfiles>

See the Adaptive Bitrates Streaming section for more details on how to configure renditions.

Multiple codec support in Playlist

WebRTC can negotiate codecs with SDP to support more devices. Playlist can set rendition with different kinds of codec. And OvenMediaEngine includes only renditions corresponding to the negotiated codec in the playlist and provides it to the player.

If an unsupported codec is included in the Rendition, the Rendition is not used. For example, if the Rendition's Audio contains aac, WebRTC ignores the Rendition.

In the example below, it consists of renditions with H.264 and Opus codecs set and renditions with VP8 and Opus codecs set. If the player selects VP8 in the answer SDP, OvenMediaEngine creates a playlist with only renditions containing VP8 and Opus and passes it to the player.

<Playlist>
    <Name>for Webrtc</Name>
    <FileName>abr</FileName>
    <Options>
        <WebRtcAutoAbr>false</WebRtcAutoAbr> 
    </Options>
    <Rendition>
        <Name>1080p</Name>
        <Video>1080p</Video>
        <Audio>opus</Audio>
    </Rendition>
    <Rendition>
        <Name>480p</Name>
        <Video>480p</Video>
        <Audio>opus</Audio>
    </Rendition>
    <Rendition>
        <Name>720p</Name>
        <Video>720p</Video>
        <Audio>opus</Audio>
    </Rendition>
    
    <Rendition>
        <Name>1080pVp8</Name>
        <Video>1080pVp8</Video>
        <Audio>opus</Audio>
    </Rendition>
    <Rendition>
        <Name>480pVp8</Name>
        <Video>480pVp8</Video>
        <Audio>opus</Audio>
    </Rendition>
    <Rendition>
        <Name>720pVp8</Name>
        <Video>720pVp8</Video>
        <Audio>opus</Audio>
    </Rendition>
</Playlist>

WebRTC over TCP

There are environments where the network speed is fast but UDP packet loss is abnormally high. In such an environment, WebRTC may not play normally. WebRTC does not support streaming using TCP, but connections to the TURN (https://tools.ietf.org/html/rfc8656) server support TCP. Based on these characteristics of WebRTC, OvenMediaEngine supports TCP connections from the player to OvenMediaEngine by embedding a TURN server.

Turn on TURN server

You can turn on the TURN server by setting <TcpRelay> in the WebRTC Bind.

Example : <TcpRelay>*:3478</TcpRelay>

OME may sometimes not be able to get the server's public IP to its local interface. (Environment like Docker or AWS) So, specify the public IP for Relay IP. If * is used, the public IP obtained from <StunServer> and all IPs obtained from the local interface are used. Port is the tcp port on which the TURN server is listening.

<Server version="8">
    ...
    <StunServer>stun.l.google.com:19302</StunServer>
    <Bind>
        <Publishers>
            <WebRTC>
                ...
                <IceCandidates>
                    <!-- <TcpRelay>*:3478</TcpRelay> -->
                    <TcpRelay>Relay IP:Port</TcpRelay>
                    <TcpForce>false</TcpForce>
                    <IceCandidate>*:10000-10005/udp</IceCandidate>
                </IceCandidates>
            </WebRTC>
        </Publishers>
    </Bind>
    ...
</Server>

If * is used as the IP of TcpRelay and IceCandidate, all available candidates are generated and sent to the player, so the player tries to connect to all candidates until a connection is established. This can cause delay in initial playback. Therefore, specifying the ${PublicIP} macro or IP directly may be more beneficial to quality.

WebRTC over TCP with OvenPlayer

WebRTC players can configure the TURN server through the iceServers setting.

You can play the WebRTC stream over TCP by attaching the query transport=tcp to the existing WebRTC play URL as follows.

ws(s)://host:port/app/stream?transport=tcp

OvenPlayer automatically sets iceServers by obtaining TURN server information set in <TcpRelay> through signaling with OvenMediaEngine.

If <TcpForce> is set to true, it will force a TCP connection even if ?transport=tcp is not present. To use this, <TcpRelay> must be set.

Custom player

If you are using custom player, set iceServers like this:

myPeerConnection = new RTCPeerConnection({
  iceServers: [
    {
      urls: "turn:Relay IP:Port?transport=tcp",
      username: "ome",
      credential: "airen"
    }
  ]
});

When sending Request Offer in the signaling phase with OvenMediaEngine, if you send the transport=tcp query string, ice_servers information is delivered as follows. You can use this information to set iceServers.

candidates: [{candidate: "candidate:0 1 UDP 50 192.168.0.200 10006 typ host", sdpMLineIndex: 0}]
code: 200
command: "offer"
ice_servers: [{credential: "airen", urls: ["turn:192.168.0.200:3478?transport=tcp"], user_name: "ome"}]
id: 506764844
peer_id: 0
sdp: {,…}

Low-Latency HLS

Apple supports Low-Latency HLS (LLHLS), which enables low-latency video streaming while maintaining scalability. LLHLS enables broadcasting with an end-to-end latency of about 2 to 5 seconds. OvenMediaEngine officially supports LLHLS as of v0.14.0.

LLHLS is an extension of HLS, so legacy HLS players can play LLHLS streams. However, the legacy HLS player plays the stream without using the low-latency function.

Title

Descriptions

Configuration

To use LLHLS, you need to add the <LLHLS> elements to the <Publishers> in the configuration as shown in the following example.

HTTP/2 outperforms HTTP/1.1, especially with LLHLS. Since all current browsers only support h2, HTTP/2 is supported only on TLS port. Therefore, it is highly recommended to use LLHLS on the TLS port.

Adaptive Bitrates Streaming (ABR)

LLHLS can deliver adaptive bitrate streaming. OME encodes the same source with multiple renditions and delivers it to the players. And LLHLS Player, including OvenPlayer, selects the best quality rendition according to its network environment. Of course, these players also provide option for users to manually select rendition.

CrossDomain

Most browsers and players prohibit accessing other domain resources in the currently running domain. You can control this situation through Cross-Origin Resource Sharing (CORS) or Cross-Domain (CrossDomain). You can set CORS and Cross-Domain as <CrossDomains> element.

You can set it using the <Url> element as shown above, and you can use the following values:

Streaming

LLHLS is ready when a live source is inputted and a stream is created. Viewers can stream using OvenPlayer or other players.

When you create a stream, as shown above, you can play LLHLS with the following URL:

http[s]://domain[:port]/<app name>/<stream name>/llhls.m3u8

If you use the default configuration, you can start streaming with the following URL:

https://domain:3334/app/<stream name>/llhls.m3u8

Live Rewind

You can create as long a playlist as you want by setting <DVR> to the LLHLS publisher as shown below. This allows the player to rewind the live stream and play older segments. OvenMediaEngine stores and uses old segments in a file in <DVR><TempStoragePath> to prevent excessive memory usage. It stores as much as <DVR><MaxDuration> and the unit is seconds.

ID3v2 Timed Metadata

Dump

TargetStreamName

The name of the stream to dump to. You can use * and ? to filter stream names.

Playlists

The name of the master playlist file to be dumped together.

OutputPath

The folder to output to. In the OutputPath you can use the macros shown in the table below. You must have write permission on the specified folder.

DRM (beta)

OvenMediaEngine supports Widevine and Fairplay in LLHLS with simple setup since version 0.16.0.

Currently, DRM is only supported for H.264 and AAC codecs. Support for H.265 will be added soon.

To include DRM information in your LLHLS Publisher configuration, follow these steps. You can set the InfoFile path as either a relative path, starting from the directory where Server.xml is located, or as an absolute path.

The separation of the DRMInfoFile is designed to allow dynamic changes to the file. Any modifications to the DRMInfoFile will take effect when a new stream is generated.

Here's how you should structure your DRM Info File:

Multiple <DRM> can be set. Specify the VirtualHost, Application, and StreamName where DRM should be applied. StreamName supports wildcard regular expressions.

Currently, CencProtectScheme only supports "cbcs" since FairPlay also supports only cbcs. There may be limited prospects for adding other schemes in the near future.

KeyId, Key, Iv and Pssh values are essential and should be provided by your DRM provider. FairPlayKeyUrl is only need for FairPlay and if you want to enable FairPlay to your stream, it is required. It will be also provided by your DRM provider.

OvenPlayer now includes DRM-related options. Enable DRM and input the License URL. Your content is now securely protected.

Low-Latency DASH and Legacy HLS streaming

From OvenMediaEngine v0.14.0, updates to legacy HLS, DASH, and LLDASH are now discontinued. These will be deprecated.

LLHLS, released from v0.14.0, is superior to Dash and LLDASH in all aspects of compatibility, performance and function, and also support legacy HLS players. Therefore, we decided not to update legacy HLS, DASH and LLDASH anymore. With the energy that was used to maintain these features, we will focus on more wonderful features in the future.

For legacy HLS, DASH, and LLDASH, refer to the old version manual.

Access Control

SignedPolicy

Overview

SignedPolicy is a module that limits the user's privileges and time. For example, operators can distribute RTMP URLs that can be accessed for 60 seconds to authorized users, and limit RTMP transmission to 1 hour. The provided URL will be destroyed after 60 seconds, and transmission will automatically stop after 1 hour. Users who are provided with a SignedPolicy URL cannot access resources other than the provided URL. This is because the SignedPolicy URL is authenticated.

SignedPolicy URL consists of the query string of the streaming URL with Policy and Signature as shown below. If SignedPolicy is enabled in the configuration of OvenMediaEngine, access to URLs with no signature or invalid signature is not allowed. Signature uses HMAC-SHA1 to authenticate all URLs except signature.

Policy

Policy is in json format and provides the following properties.

Key

Value

Description

url_expire means the time the URL is valid, so if you connect before the URL expires, you can continue to use it, and sessions that have already been connected will not be deleted even if the time expires. However, stream_expire forcibly terminates the session when the time expires even if it is already playing.

Signature

The URL entered into HMAC to generate the Signature must include :port.

When creating a signature, you cannot omit the default port such as http port 80, https port 443, or rtmp port 1935. This is because when OvenMediaEngine creates a signature for checking the signature, it is created by putting the port value.

When using SignedPolicy with SRT providers, only use the streamid portion of the URL, e.g. srt://myserver:9999?streamid=srt://myserver:9999/app/stream?policy=abc123

Configuration

To enable SignedPolicy, you need to add the following <SignedPolicy> setting in Server.xml under <VirtualHost>.

Make SignedPolicy URL with a script

We provide a script that can easily generate SignedPolicy URL. The script can be found in the path below.

Here's how to use this script:

For example, you can use it like this:

Make SignedPolicy URL manually

Encoding policy

Policy encoded with Base64URL is added as a query string to the existing streaming URL. (The query string key is set in Server.xml.)

Signature

Signature hashes the entire URL including the policy in HMAC (SHA-1) method, encodes it as Base64URL, and includes it in the query string.

Create a hash using the secret key (1kU^b6 in the example) and the URL above using HMAC-SHA1.

If you include it as a signature query string (query string key is set in Server.xml), the following SignedPolicy URL is finally generated.

Usage examples

Applying SignedPolicy in OBS

Generate SignedPolicy URL with the script.

Separate the URL based on "app" as shown in the example below and enter all the parts under the stream in the Stream Key.

AdmissionWebhooks

Overview

AdmissionWebhooks are HTTP callbacks that query the control server to control publishing and playback admission requests.

Users can use the AdmissionWebhook for a variety of purposes, including customer authentication, tracking published streams, hide app/stream names, logging and more.

Configuration

AdmissionWebhooks can be set up on VirtualHost, as shown below.

Request

Format

AdmissionWebhooks send HTTP/1.1 request message to the configured user's control server when an encoder requests publishing or a player requests playback. The request message format is as follows.

Here is a detailed explanation of each element of Json payload:

Security

The control server may need to validate incoming http requests for security reasons. To do this, the AdmissionWebhooks module puts the X-OME-Signature value in the HTTP request header. X-OME-Signature is a base64 url safe encoded value obtained by encrypting the payload of an HTTP request with the HMAC-SHA1 algorithm using the secret key set in <AdmissionWebhooks><SecretKey> of the configuration.

Conditions that triggers the request

As shown below, the trigger condition of request is different for each protocol.

Response for closing status

The engine in the closing state does not need any parameter in response. To the query just answer with empty json object.

Response for opening status

Format

ControlServer must respond with the following Json format. In particular, the "allowed" element is required.

User authentication and control

new_url redirects the original request to another app/stream. This can be used to hide the actual app/stream name from the user or to authenticate the user by inserting additional information instead of the app/stream name.

For example, you can issue a WebRTC streaming URL by inserting the user ID as follows: ws://domain.com:3333/user_id It will be more effective if you issue a URl with the encrypted value that contains the user ID, url expiration time, and other information.

After the Control Server checks whether the user is authorized to play using user_id, and responds with ws://domain.com:3333/app/sport-3 to new_url, the user can play app/sport-3.

If the user has only one hour of playback rights, the Control Server responds by putting 3600000 in the lifetime.

Clustering

OvenMediaEngine supports clustering and ensures high availability (HA) and scalability. For this we provide the OriginMap and OriginMapStore features. is a method of configuring Origin server information in each Edge server, and is a method for Origin servers and Edge servers to dynamically share information through Redis Server.

OriginMap

The OvenMediaEngine running as edge pulls a stream from an external server when a user requests it. The external server could be another OvenMediaEngine with OVT enabled or another stream server that supports RTSP.

Origin

OvenMediaEngine provides OVT protocol for passing streams from the origin to the edge. To run OvenMediaEngine as Origin, OVT port, and OVT Publisher must be enabled as follows :

Edge

The role of the edge is to receive and distribute streams from an origin. You can configure hundreds of Edge to distribute traffic to your players. As a result of testing, a single edge can stream 4-5Gbps traffic by WebRTC based on AWS C5.2XLarge. If you need to stream to thousands of people, you can configure and use multiple edges.

The edge supports OVT and RTSP to pull stream from an origin. In the near future, we will support more protocols. The stream pulled through OVT is bypassed without being encoded.

To run OvenMediaEngine as Edge, you need to add Origins elements to the configuration file as follows:

The <Origin>is a rule about where to pull a stream from for what request.

The <Origin>has the ability to automatically create an application with that name if the application you set in <Location> doesn't exist on the server. If an application exists in the system, a stream will be created in the application.

<Properties>

NoInputFailoverTimeout (default 3000)

NoInputFailoverTimeout is the time (in milliseconds) to switch to the next URL if there is no input for the set time.

UnusedStreamDeletionTimeout (default 60000)

UnusedStreamDeletionTimeout is a function that deletes a stream created with OriginMap if there is no viewer for a set amount of time (milliseconds). This helps to save network traffic and system resources for Origin and Edge.

<Origin>

For a detailed description of Origin's elements, see:

Location

Origin is already filtered by domain because it belongs to VirtualHost. Therefore, in Location, set App, Stream, and File to match except domain area. If a request matches multiple Origins, the top of them runs.

Pass

Pass consists of Scheme and Url.

<Scheme> is the protocol that will use to pull from the Origin Stream. It currently can be configured as OVTor RTSP.

If the origin server is OvenMediaEngine, you have to set OVTinto the <Scheme>.

You can pull the stream from the RTSP server by setting RTSPinto the<Scheme>. In this case, the <RTSPPull> provider must be enabled. The application automatically generated by Origin doesn't need to worry because all providers are enabled.

Urls is the address of origin stream and can consist of multiple URLs.

ForwardQueryParams is an option to determine whether to pass the query string part to the server at the URL you requested to play.(Default : true) Some RTSP servers classify streams according to query strings, so you may want this option to be set to false. For example, if a user requests ws://host:port/app/stream?transport=tcp to play WebRTC, the ?transport=tcp may also be forwarded to the RTSP server, so the stream may not be found on the RTSP server. On the other hand, OVT does not affect anything, so you can use it as the default setting.

Rules for generating Origin URL

The final address to be requested by OvenMediaEngine is generated by combining the configured Url and user's request except for Location. For example, if the following is set

OriginMapStore

OriginMapStore is designed to make it easier to support autoscaling within a cluster. All Origin Servers and Edge Servers in the cluster share stream information and origin OVT URLs through Redis. That is, when a stream is created on the Origin server, the Origin server sets the app/stream name and OVT url to access the stream to the Redis server. Edge gets the OVT url corresponding to the app/stream from the Redis server when the user's playback request comes in.

This means that existing settings do not need to be updated when extending Origin servers and Edge servers. Therefore, all Origins can be grouped into one domain, and all Edges can be bundled with one domain. OriginMapStore allows you to expand Origins or Edges within a cluster without any additional configuration.

OriginMapStore functionality has been tested with Redis Server 5.0.7. You can enable this feature by adding the following settings to Server.xml of Origin and Edge. Note that must be set in Server.xml of the Origin server. This is used when Origin registers its own OVT url, so you just need to set a domain name or IP address that can be accessed as an OVT publisher.

Dynamic Application

It is either impossible or very cumbersome for edge servers to pre-configure all applications. So OriginMap and OriginMapStore have the ability to dynamically create an application if the application does not exist when creating the stream. They create a new application by copying the application configuration with <Name>*</Name>. That is, the special application with the name * is a dynamic application template.

Load Balancer

Thumbnail

OvenMediaEngine can generate thumbnails from live streams. This allows you to organize a broadcast list on your website or monitor multiple streams at the same time.

Configuration

Bind

Thumbnails are published via HTTP(s). Set the port for thumbnails as follows. Thumbnail publisher can use the same port number as HLS and DASH.

Encoding

In order to publish thumbnails, an encoding profile for thumbnails must be set. JPG and PNG are supported as codec. And framerate and resolution can be adjusted. Framerate is the number of thumbnails extracted per second. We recommend 1 as the thumbnail framerate. Thumbnail encoding uses a lot of resources. Therefore, if you increase this value excessively, it can cause a failure due to excessive use of system resources. The resolution can be set as desired by the user, and if the ratio is different from the input image, it is stretched. We plan to support various ratio modes in the future.

Publisher

Declaring a thumbnail publisher. Cross-domain settings are available as a detailed option.

Get thumbnails

When the setting is made for the thumbnail and the stream is input, you can view the thumbnail through the following URL.

Statistics

Configuration

OvenMediaEngine has an XML configuration file. If you start OvenMediaEngine with systemctl start ovenmediaengine, the config file is loaded from the following path.

/usr/share/ovenmediaengine/conf/Server.xml

If you run it directly from the command line, it loads the configuration file from:

/<OvenMediaEngine Binary Path>/conf/Server.xml

If you run it in Docker container, the path to the configuration file is:

# For Origin mode
/opt/ovenmediaengine/bin/origin_conf/Server.xml
# For Edge mode
/opt/ovenmediaengine/bin/edge_conf/Server.xml

Server

The Server is the root element of the configuration file. The versionattribute indicates the version of the configuration file. OvenMediaEngine uses this version information to check if the config file is a compatible version.

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
    <Name>OvenMediaEngine</Name>
    <IP>*</IP>
    <PrivacyProtection>false</PrivacyProtection>
    <StunServer>stun.l.google.com:19302</StunServer>
    <Bind>...</Bind>
    <VirtualHosts>...</VirtualHosts>
</Server>

IP

    <IP>*</IP>

The IP address is OvenMediaEngine will bind to. If you set *, all IP addresses of the system are used. If you enter a specific IP, the Host uses that IP only.

PrivacyProtection

PrivacyProtection is an option to comply with GDPR, PIPEDA, CCPA, LGPD, etc. by deleting the client's personal information (IP, Port) from all records. When this option is turned on, the client's IP and Port are converted to xxx.xxx.xxx.xxx:xxx in all logs and REST APIs.

StunServer

OvenMediaEngine needs to know its public IP in order to connect to the player through WebRTC. The server must inform the player of the IceCandidates and TURN server addresses when signaling, and this information must be the IP the player can connect to. However, in environments such as Docker or AWS, public IP cannot be obtained through a local interface, so a method of obtaining public IP using stun server is provided (available from version 0.11.1).

If OvenMediaEngine obtains the public IP through communication with the set stun server, you can set the public IP by using * or ${PublicIP} in IceCandidate and TcpRelay.

<StunServer>stun.l.google.com:19302</StunServer>

Bind

The Bind is the configuration for the server port that will be used. Bind consists of Providers and Publishers. The Providers are the server for stream input, and the Publishers are the server for streaming.

<!-- Settings for the ports to bind -->
<Bind>
    <!-- Enable this configuration if you want to use API Server -->
    <!--
    <Managers>
        <API>
            <Port>8081</Port>
            <WorkerCount>1</WorkerCount>
        </API>
    </Managers>
    -->

    <Providers>
        <!-- Pull providers -->
        <RTSPC>
            <WorkerCount>1</WorkerCount>
        </RTSPC>
        <OVT>
            <WorkerCount>1</WorkerCount>
        </OVT>
        <!-- Push providers -->
        <RTMP>
            <Port>1935</Port>
            <WorkerCount>1</WorkerCount>
        </RTMP>
        <SRT>
            <Port>9999</Port>
            <WorkerCount>1</WorkerCount>
        </SRT>
        <MPEGTS>
            <!--
                Listen on port 4000~4005 (<Port>4000-4004,4005/udp</Port>)
                This is just a demonstration to show that you can configure the port in several ways
            -->
            <Port>4000/udp</Port>
        </MPEGTS>
        <WebRTC>
            <Signalling>
                <Port>3333</Port>
                <TLSPort>3334</TLSPort>
                <WorkerCount>1</WorkerCount>
            </Signalling>

            <IceCandidates>
                <IceCandidate>*:10000/udp</IceCandidate>
                <!-- 
                    If you want to stream WebRTC over TCP, specify IP:Port for TURN server.
                    This uses the TURN protocol, which delivers the stream from the built-in TURN server to the player's TURN client over TCP. 
                    For detailed information, refer https://airensoft.gitbook.io/ovenmediaengine/streaming/webrtc-publishing#webrtc-over-tcp
                -->
                <TcpRelay>*:3478</TcpRelay>
                <!-- TcpForce is an option to force the use of TCP rather than UDP in WebRTC streaming. (You can omit ?transport=tcp accordingly.) If <TcpRelay> is not set, playback may fail. -->
                <TcpForce>true</TcpForce>
                <TcpRelayWorkerCount>1</TcpRelayWorkerCount>
            </IceCandidates>
        </WebRTC>
    </Providers>

    <Publishers>
        <OVT>
            <Port>9000</Port>
            <WorkerCount>1</WorkerCount>
        </OVT>
        <LLHLS>
            <!-- 
            OME only supports h2, so LLHLS works over HTTP/1.1 on non-TLS ports. 
            LLHLS works with higher performance over HTTP/2, 
            so it is recommended to use a TLS port.
            -->
            <Port>3333</Port>
            <!-- If you want to use TLS, specify the TLS port -->
            <TLSPort>3334</TLSPort>
            <WorkerCount>1</WorkerCount>
        </LLHLS>
        <WebRTC>
            <Signalling>
                <Port>3333</Port>
                <TLSPort>3334</TLSPort>
                <WorkerCount>1</WorkerCount>
            </Signalling>
            <IceCandidates>
                <IceCandidate>*:10000-10005/udp</IceCandidate>
                <!-- 
                    If you want to stream WebRTC over TCP, specify IP:Port for TURN server.
                    This uses the TURN protocol, which delivers the stream from the built-in TURN server to the player's TURN client over TCP. 
                    For detailed information, refer https://airensoft.gitbook.io/ovenmediaengine/streaming/webrtc-publishing#webrtc-over-tcp
                -->
                <TcpRelay>*:3478</TcpRelay>
                <!-- TcpForce is an option to force the use of TCP rather than UDP in WebRTC streaming. (You can omit ?transport=tcp accordingly.) If <TcpRelay> is not set, playback may fail. -->
                <TcpForce>true</TcpForce>
                <TcpRelayWorkerCount>1</TcpRelayWorkerCount>
            </IceCandidates>
        </WebRTC>
    </Publishers>
</Bind>

The meaning of each element is shown in the following table:

Element

Description

Virtual Host

VirtualHosts are a way to run more than one streaming server on a single machine. OvenMediaEngine supports IP-based virtual host and Domain-based virtual host. "IP-based" means that you can separate streaming servers into multiples by setting different IP addresses, and "Domain-based" means that even if the streaming servers use the same IP address, you can split the streaming servers into multiples by setting different domain names.

VirtualHostsconsist of Name, Host, Origins, SignedPolicy, and Applications.

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
    <Name>OvenMediaEngine</Name>
    <VirtualHosts>
        <VirtualHost>
            <Name>default</Name>
            <Host>
            ...
            </Host>

            <Origins>
            ...
            </Origins>

            <SignedPolicy>
            ...
            </SignedPolicy>

            <Applications>
            ...
            </Applications>
        </Host>
    </Hosts>
</Server>

Host

The Domain has Names and TLS. Names can be either a domain address or an IP address. Setting * means it allows all domains and IP addresses.

<Host>
        <Names>
            <!-- Domain names
            <Name>stream1.airensoft.com</Name>
            <Name>stream2.airensoft.com</Name>
            <Name>*.sub.airensoft.com</Name>
            -->
            <Name>*</Name>
        </Names>
	<TLS>
	    <CertPath>path/to/file.crt</CertPath>
	    <KeyPath>path/to/file.key</KeyPath>
	    <ChainCertPath>path/to/file.crt</ChainCertPath>
	</TLS>
</Host>

SignedPolicy

SignedPolicy is a module that limits the user's privileges and time. For example, operators can distribute RTMP URLs that can be accessed for 60 seconds to authorized users, and limit RTMP transmission to 1 hour. The provided URL will be destroyed after 60 seconds, and transmission will automatically stop after 1 hour. Users who are provided with a SingedPolicy URL cannot access resources other than the provided URL. This is because the SignedPolicy URL is authenticated. See the SignedPolicy chapter for more information.

Origins

Origins (also we called OriginMap) are a feature to pull streams from external servers. It now supports OVT and RTSP for the pulling protocols. OVT is a protocol defined by OvenMediaEngine for Origin-Edge communication. It allows OvenMediaEngine to relay a stream from other OvenMediaEngines that have OVP Publisher turned on. Using RTSP, OvenMediaEngine pulls a stream from an RTSP server and creates a stream. RTSP stream from external servers can stream by WebRTC, HLS, and MPEG-DASH.

The Origin has Location and Pass elements. Location is a URI pattern for incoming requests. If the incoming URL request matches Location, OvenMediaEngine pulls the stream according to a Pass element. In the Pass element, you can set the origin stream's protocol and URLs.

To run the Edge server, Origin creates application and stream if there isn't those when user request. For more learn about Origin-Edge, see the Live Source chapter.

<Origins>
    <Origin>
        <Location>/app/stream</Location>
        <Pass>
            <Scheme>ovt</Scheme>
            <Urls><Url>origin.com:9000/app/stream_720p</Url></Urls>
        </Pass>
    </Origin>
    <Origin>
        <Location>/app/</Location>
        <Pass>
            <Scheme>ovt</Scheme>
            <Urls><Url>origin.com:9000/app/</Url></Urls>
        </Pass>
    </Origin>
    <Origin>
        <Location>/rtsp/stream</Location>
        <Pass>
            <Scheme>rtsp</Scheme>
            <Urls><Url>rtsp-server.com:554/</Url></Urls>
        </Pass>
    </Origin>
    <Origin>
        <Location>/</Location>
        <Pass>
            <Scheme>ovt</Scheme>
            <Urls><Url>origin2.com:9000/</Url></Urls>
        </Pass>
    </Origin>
</Origins>

Application

<Application> consists of various elements that can define the operation of the stream, including Stream input, Encoding, and Stream output. In other words, you can create as many <Application> as you like and build various streaming environments.

<VirtualHost>
    ...
    <Applications>
        <Application>
            ...
        </Application>
        <Application>
            ...
        </Application>
    </Applications>
</VirtualHost>

<Application> needs to set <Name> and <Type> as follows:

<Application>
    <Name>app</Name>
    <Type>live</Type>
    <OutputProfiles> ... </OutputProfiles>
    <Providers> ... </Providers>
    <Publishers> ... </Publishers>
</Application>

<Name> is used to configure the Streaming URL.
<Type> defines the operation of <Application>. Currently, there is only a live type.

OutputProfiles

<OutputProfile> is a configuration that creates an output stream. Output stream name can be set with <OutputStreamName>, and transcoding properties can be set through <Encodes>. If you want to stream one input to multiple output streams, you can set multiple <OutputProfile>.

<Application>
    <OutputProfiles>
            <OutputProfile>
                <Name>bypass_stream</Name>
                <OutputStreamName>${OriginStreamName}</OutputStreamName>
                <Encodes>
                    <Audio>
                        <Bypass>true</Bypass>
                    </Audio>
                    <Video>
                        <Bypass>true</Bypass>
                    </Video>
                    <Audio>
                        <Codec>opus</Codec>
                        <Bitrate>128000</Bitrate>
                        <Samplerate>48000</Samplerate>
                        <Channel>2</Channel>
                    </Audio>
                    <!--                             
                    <Video>
                        <Codec>vp8</Codec>
                        <Bitrate>1024000</Bitrate>
                        <Framerate>30</Framerate>
                        <Width>1280</Width>
                        <Height>720</Height>
                    </Video>                                
                    -->
                </Encodes>
            </OutputProfile>
        </OutputProfiles>
</Application>

For more information about the OutputProfiles, please see the Transcoding chapter.

Providers

Providers ingest streams that come from a media source.

<Application>
   <Providers>
      <RTMP/>
      <WebRTC/>
      <SRT/>
      <RTSPPull/>
      <OVT/>
      <MPEGTS>
         <StreamMap>
            ...
         </StreamMap>
      </MPEGTS>
   </Providers>
</Application>

If you want to get more information about the <Providers>, please refer to the Live Source chapter.

Publishers

You can configure the Output Stream operation in <Publishers>. <ThreadCount> is the number of threads used by each component responsible for the <Publishers> protocol.

You need many threads to transmit streams to a large number of users at the same time. So it's better to use a higher core CPU and set <ThreadCount> equal to the number of CPU cores.

<Application>
   <Publishers>
      <OVT />
      <HLS />
      <DASH />
      <LLDASH />
      <WebRTC />
   </Publishers>
</Application>

OvenMediaEngine currently supports WebRTC, Low-Latency DASH, MEPG-DASH, and HLS. If you don't want to use any protocol then you can delete that protocol setting, the component for that protocol isn't initialized. As a result, you can save system resources by deleting the settings of unused protocol components.

If you want to learn more about WebRTC, visit the WebRTC Streaming chapter. And if you want to get more information on Low-Latency DASH, MPEG-DASH, and HLS, refer to the chapter on HLS & MPEG-DASH Streaming.

Configuration Example

Finally, Server.xml is configured as follows:

<?xml version="1.0" encoding="UTF-8"?>

<Server version="8">
    <Name>OvenMediaEngine</Name>
    <!-- Host type (origin/edge) -->
    <Type>origin</Type>
    <!-- Specify IP address to bind (* means all IPs) -->
    <IP>*</IP>
    <PrivacyProtection>false</PrivacyProtection>

    <!-- 
    To get the public IP address(mapped address of stun) of the local server. 
    This is useful when OME cannot obtain a public IP from an interface, such as AWS or docker environment. 
    If this is successful, you can use ${PublicIP} in your settings.
    -->
    <StunServer>stun.l.google.com:19302</StunServer>

    <Modules>
        <!-- 
        Currently OME only supports h2 like all browsers do. Therefore, HTTP/2 only works on TLS ports.			
        -->
        <HTTP2>
            <Enable>true</Enable>
        </HTTP2>

        <LLHLS>
            <Enable>true</Enable>
        </LLHLS>

        <!-- P2P works only in WebRTC and is experiment feature -->
        <P2P>
            <!-- disabled by default -->
            <Enable>false</Enable>
            <MaxClientPeersPerHostPeer>2</MaxClientPeersPerHostPeer>
        </P2P>
    </Modules>

<!-- Settings for the ports to bind -->
<Bind>
    <!-- Enable this configuration if you want to use API Server -->
    <!--
    <Managers>
        <API>
            <Port>8081</Port>
            <TLSPort>8082</TLSPort>
            <WorkerCount>1</WorkerCount>
        </API>
    </Managers>
    -->

    <Providers>
        <!-- Pull providers -->
        <RTSPC>
            <WorkerCount>1</WorkerCount>
        </RTSPC>
        <OVT>
            <WorkerCount>1</WorkerCount>
        </OVT>
        <!-- Push providers -->
        <RTMP>
            <Port>1935</Port>
            <WorkerCount>1</WorkerCount>
        </RTMP>
        <SRT>
            <Port>9999</Port>
            <WorkerCount>1</WorkerCount>
        </SRT>
        <MPEGTS>
            <!--
                Listen on port 4000~4005 (<Port>4000-4004,4005/udp</Port>)
                This is just a demonstration to show that you can configure the port in several ways
            -->
            <Port>4000/udp</Port>
        </MPEGTS>
        <WebRTC>
            <Signalling>
                <Port>3333</Port>
                <TLSPort>3334</TLSPort>
                <WorkerCount>1</WorkerCount>
            </Signalling>

            <IceCandidates>
                <IceCandidate>*:10000/udp</IceCandidate>
                <!-- 
                    If you want to stream WebRTC over TCP, specify IP:Port for TURN server.
                    This uses the TURN protocol, which delivers the stream from the built-in TURN server to the player's TURN client over TCP. 
                    For detailed information, refer https://airensoft.gitbook.io/ovenmediaengine/streaming/webrtc-publishing#webrtc-over-tcp
                -->
                <TcpRelay>*:3478</TcpRelay>
                <!-- TcpForce is an option to force the use of TCP rather than UDP in WebRTC streaming. (You can omit ?transport=tcp accordingly.) If <TcpRelay> is not set, playback may fail. -->
                <TcpForce>true</TcpForce>
                <TcpRelayWorkerCount>1</TcpRelayWorkerCount>
            </IceCandidates>
        </WebRTC>
    </Providers>

    <Publishers>
        <OVT>
            <Port>9000</Port>
            <WorkerCount>1</WorkerCount>
        </OVT>
        <LLHLS>
            <!-- 
            OME only supports h2, so LLHLS works over HTTP/1.1 on non-TLS ports. 
            LLHLS works with higher performance over HTTP/2, 
            so it is recommended to use a TLS port.
            -->
            <Port>3333</Port>
            <!-- If you want to use TLS, specify the TLS port -->
            <TLSPort>3334</TLSPort>
            <WorkerCount>1</WorkerCount>
        </LLHLS>
        <WebRTC>
            <Signalling>
                <Port>3333</Port>
                <TLSPort>3334</TLSPort>
                <WorkerCount>1</WorkerCount>
            </Signalling>
            <IceCandidates>
                <IceCandidate>*:10000-10005/udp</IceCandidate>
                <!-- 
                    If you want to stream WebRTC over TCP, specify IP:Port for TURN server.
                    This uses the TURN protocol, which delivers the stream from the built-in TURN server to the player's TURN client over TCP. 
                    For detailed information, refer https://airensoft.gitbook.io/ovenmediaengine/streaming/webrtc-publishing#webrtc-over-tcp
                -->
                <TcpRelay>*:3478</TcpRelay>
                <!-- TcpForce is an option to force the use of TCP rather than UDP in WebRTC streaming. (You can omit ?transport=tcp accordingly.) If <TcpRelay> is not set, playback may fail. -->
                <TcpForce>true</TcpForce>
                <TcpRelayWorkerCount>1</TcpRelayWorkerCount>
            </IceCandidates>
        </WebRTC>
    </Publishers>
</Bind>

    <!--
        Enable this configuration if you want to use API Server
        
        <AccessToken> is a token for authentication, and when you invoke the API, you must put "Basic base64encode(<AccessToken>)" in the "Authorization" header of HTTP request.
        For example, if you set <AccessToken> to "ome-access-token", you must set "Basic b21lLWFjY2Vzcy10b2tlbg==" in the "Authorization" header.
    -->
    <!--
    <Managers>
        <Host>
            <Names>
                <Name>*</Name>
            </Names>
            <TLS>
                <CertPath>path/to/file.crt</CertPath>
                <KeyPath>path/to/file.key</KeyPath>
                <ChainCertPath>path/to/file.crt</ChainCertPath>
            </TLS>
        </Host>
        <API>
            <AccessToken>ome-access-token</AccessToken>

            <CrossDomains>
                <Url>*.airensoft.com</Url>
                <Url>http://*.sub-domain.airensoft.com</Url>
                <Url>http?://airensoft.*</Url>
            </CrossDomains>
        </API>
    </Managers>
    -->

    <VirtualHosts>
        <!-- You can use wildcard like this to include multiple XMLs -->
        <VirtualHost include="VHost*.xml" />
        <VirtualHost>
            <Name>default</Name>
            <!--Distribution is a value that can be used when grouping the same vhost distributed across multiple servers. This value is output to the events log, so you can use it to aggregate statistics. -->
            <Distribution>ovenmediaengine.com</Distribution>

            <!-- Settings for multi ip/domain and TLS -->
            <Host>
                <Names>
                    <!-- Host names
                        <Name>stream1.airensoft.com</Name>
                        <Name>stream2.airensoft.com</Name>
                        <Name>*.sub.airensoft.com</Name>
                        <Name>192.168.0.1</Name>
                    -->
                    <Name>*</Name>
                </Names>
                <!--
                <TLS>
                    <CertPath>path/to/file.crt</CertPath>
                    <KeyPath>path/to/file.key</KeyPath>
                    <ChainCertPath>path/to/file.crt</ChainCertPath>
                </TLS>
                -->
            </Host>

            <!-- 	
            Refer https://airensoft.gitbook.io/ovenmediaengine/signedpolicy
            <SignedPolicy>
                <PolicyQueryKeyName>policy</PolicyQueryKeyName>
                <SignatureQueryKeyName>signature</SignatureQueryKeyName>
                <SecretKey>aKq#1kj</SecretKey>

                <Enables>
                    <Providers>rtmp,webrtc,srt</Providers>
                    <Publishers>webrtc,hls,llhls,dash,lldash</Publishers>
                </Enables>
            </SignedPolicy>
            -->

            <!--
            <AdmissionWebhooks>
                <ControlServerUrl></ControlServerUrl>
                <SecretKey></SecretKey>
                <Timeout>3000</Timeout>
                <Enables>
                    <Providers>rtmp,webrtc,srt</Providers>
                    <Publishers>webrtc,hls,llhls,dash,lldash</Publishers>
                </Enables>
            </AdmissionWebhooks>
            -->

            <!-- <Origins>
                <Properties>
                    <NoInputFailoverTimeout>3000</NoInputFailoverTimeout>
                    <UnusedStreamDeletionTimeout>60000</UnusedStreamDeletionTimeout>
                </Properties>
                <Origin>
                    <Location>/app/stream</Location>
                    <Pass>
                        <Scheme>ovt</Scheme>
                        <Urls><Url>origin.com:9000/app/stream_720p</Url></Urls>
                    </Pass>
                    <ForwardQueryParams>false</ForwardQueryParams>
                </Origin>
                <Origin>
                    <Location>/app/</Location>
                    <Pass>
                        <Scheme>ovt</Scheme>
                        <Urls><Url>origin.com:9000/app/</Url></Urls>
                    </Pass>
                </Origin>
                <Origin>
                    <Location>/edge/</Location>
                    <Pass>
                        <Scheme>ovt</Scheme>
                        <Urls><Url>origin.com:9000/app/</Url></Urls>
                    </Pass>
                </Origin>
            </Origins> -->
            
            <!-- Settings for applications -->
            <Applications>
                <Application>
                    <Name>app</Name>
                    <!-- Application type (live/vod) -->
                    <Type>live</Type>
                    <OutputProfiles>
                        <!-- Enable this configuration if you want to hardware acceleration using GPU -->
                        <HardwareAcceleration>false</HardwareAcceleration>
                        <OutputProfile>
                            <Name>bypass_stream</Name>
                            <OutputStreamName>${OriginStreamName}</OutputStreamName>
                            <Encodes>
                                <Audio>
                                    <Bypass>true</Bypass>
                                </Audio>
                                <Video>
                                    <Bypass>true</Bypass>
                                </Video>
                                <Audio>
                                    <Codec>opus</Codec>
                                    <Bitrate>128000</Bitrate>
                                    <Samplerate>48000</Samplerate>
                                    <Channel>2</Channel>
                                </Audio>
                                <!-- 							
                                <Video>
                                    <Codec>vp8</Codec>
                                    <Bitrate>1024000</Bitrate>
                                    <Framerate>30</Framerate>
                                    <Width>1280</Width>
                                    <Height>720</Height>
                                    <Preset>faster</Preset>
                                </Video>
                                -->
                            </Encodes>
                        </OutputProfile>
                    </OutputProfiles>
                    <Providers>
                        <OVT />
                        <WebRTC />
                        <RTMP />
                        <SRT />
                        <MPEGTS>
                            <StreamMap>
                                <!--
                                    Set the stream name of the client connected to the port to "stream_${Port}"
                                    For example, if a client connects to port 4000, OME creates a "stream_4000" stream
                                    <Stream>
                                        <Name>stream_${Port}</Name>
                                        <Port>4000,4001-4004</Port>
                                    </Stream>
                                    <Stream>
                                        <Name>stream_4005</Name>
                                        <Port>4005</Port>
                                    </Stream>
                                -->
                                <Stream>
                                    <Name>stream_${Port}</Name>
                                    <Port>4000</Port>
                                </Stream>
                            </StreamMap>
                        </MPEGTS>
                        <RTSPPull />
                        <WebRTC>
                            <Timeout>30000</Timeout>
                        </WebRTC>
                    </Providers>
                    <Publishers>
                        <AppWorkerCount>1</AppWorkerCount>
                        <StreamWorkerCount>8</StreamWorkerCount>
                        <OVT />
                        <WebRTC>
                            <Timeout>30000</Timeout>
                            <Rtx>false</Rtx>
                            <Ulpfec>false</Ulpfec>
                            <JitterBuffer>false</JitterBuffer>
                        </WebRTC>
                        <LLHLS>
                            <ChunkDuration>0.2</ChunkDuration>
                            <SegmentDuration>6</SegmentDuration>
                            <SegmentCount>10</SegmentCount>
                            <CrossDomains>
                                <Url>*</Url>
                            </CrossDomains>
                        </LLHLS>
                    </Publishers>
                </Application>
            </Applications>
        </VirtualHost>
    </VirtualHosts>
</Server>