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+, Rocky Linux 9+, and AlmaLinux 9+.

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

Building & Running

You can build the OvenMediaEngine source using the following command:

sudo apt-get update
cd OvenMediaEngine-0.16.8/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.8/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.8/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.8/src
make release
sudo make install
systemctl start ovenmediaengine
# If you want automatically start on boot
systemctl enable ovenmediaengine.service

Ports used by default

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

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 default settings

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

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.8

You can set the following environment variables.

Environment Variables

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

export OME_DOCKER_HOME=/opt/ovenmediaengine
sudo mkdir -p $OME_DOCKER_HOME/conf
sudo mkdir -p $OME_DOCKER_HOME/logs

# Set permissions for the created directory if necessary.
sudo chgrp -R docker $OME_DOCKER_HOME 
sudo chmod -R 775 $OME_DOCKER_HOME

# If you want to use OME_HOME permanently, add the following line to the ~/.profile file for bash, for other shells, you can do it accordingly.
echo "export OME_DOCKER_HOME=/opt/ovenmediaengine" >> ~/.profile

Copy the default configurations from Docker container

docker run -d --name tmp-ome airensoft/ovenmediaengine:0.16.7
docker cp tmp-ome:/opt/ovenmediaengine/bin/origin_conf/Server.xml $OME_DOCKER_HOME/conf
docker cp tmp-ome:/opt/ovenmediaengine/bin/origin_conf/Logger.xml $OME_DOCKER_HOME/conf
docker rm -f tmp-ome

Copy the certificate files to the directory

Copy your PEM certificate files to the path below if you need to enable TLS. The destination file names must match if using the default configuration. If you want to change the file name, you can do so by editing the Server.xml configuration file. See TLS Encryption for details.

cp /your/server_certificate_file.crt $OME_DOCKER_HOME/conf/cert.crt
cp /your/certificate_key_file.key $OME_DOCKER_HOME/conf/cert.key
cp /your/ca_bundle_file.ca-bundle $OME_DOCKER_HOME/conf/cert.ca-bundle

Modify Server.xml if necessary

vi $OME_DOCKER_HOME/conf/Server.xml

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.

docker run -d -it --name ome -e OME_HOST_IP=Your.HOST.IP.Address \
-v $OME_DOCKER_HOME/conf:/opt/ovenmediaengine/bin/origin_conf \
-v $OME_DOCKER_HOME/logs:/var/log/ovenmediaengine \
-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.7

Check the log file

tail -f $OME_DOCKER_HOME/logs/ovenmediaengine.log

Restart Docker Container

docker restart ome

Stop and Remove Container

docker stop ome
docker rm ome

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.

What is OvenMediaEngine?

OvenMediaEngine (OME) is a Sub-Second Latency Live Streaming Server with Large-Scale and High-Definition. With OME, you can create platforms/services/systems that transmit high-definition video to hundreds-thousand viewers with sub-second latency and be scalable, depending on the number of concurrent viewers.

OvenMediaEngine can receive a video/audio, video, or audio source from encoders and cameras such as OvenLiveKit, OBS, XSplit, and more, to WebRTC, SRT, RTMP, MPEG-2 TS, and RTSP as Input. Then, OME transmits this source using LLHLS (Low Latency HLS) and WebRTC as output. Also, we provide OvenPlayer, an Open-Source and JavaScript-based WebRTC/LLHLS Player for OvenMediaEngine.

Our goal is to make it easier for you to build a stable broadcasting/streaming service with sub-second latency.

Features

• Ingest

  • Push: WebRTC, WHIP, SRT, RTMP, MPEG-2 TS

  • Pull: RTSP

  • Scheduled Channel (Pre-recorded Live)

  • Multiplex Channel (Duplicate stream / Mux tracks)

• Adaptive Bitrate Streaming (ABR) for HLS, LLHLS and WebRTC

• Low-Latency Streaming using LLHLS

  • DVR (Live Rewind)

  • Dump for VoD

  • ID3v2 timed metadata

  • DRM (Widevine, Fairplay)

• Sub-Second Latency Streaming using WebRTC

  • WebRTC over TCP (with embedded TURN server)

  • Embedded WebRTC Signaling Server (WebSocket based)

  • Retransmission with NACK

  • ULPFEC (Uneven Level Protection Forward Error Correction)

    • VP8, H.264

  • In-band FEC (Forward Error Correction)

    • Opus

• HLS (version 3) Streaming support for legacy devices

  • MPEG-2 TS Container

  • Audio/Video Muxed

  • DVR (Live Rewind)

• Embedded Live Transcoder

  • Video: VP8, H.264, H.265(Hardware encoder only), Pass-through

  • Audio: Opus, AAC, Pass-through

• Clustering (Origin-Edge Structure)

• Monitoring

• Access Control

  • AdmissionWebhooks

  • SignedPolicy

• File Recording

• Push Publishing using SRT, RTMP and MPEG2-TS (Re-streaming)

• Thumbnail

• REST API

Supported Platforms

We have tested OvenMediaEngine on platforms, listed below. However, we think it can work with other Linux packages as well:

• Docker (https://hub.docker.com/r/airensoft/ovenmediaengine)

• Ubuntu 18+

• Rocky Linux 9+

• AlmaLinux 9+

• Fedora 28+

Getting Started

Please read Getting Started chapter in the tutorials.

How to Contribute

Thank you so much for being so interested in OvenMediaEngine.

We need your help to keep and develop our open-source project, and we want to tell you that you can contribute in many ways. Please see our Guidelines, Rules, and Contribute.

• Finding Bugs

• Reviewing Code

• Sharing Ideas

• Testing

• Improving Documentation

• Spreading & Use Cases

• Recurring Donations

We always hope that OvenMediaEngine will give you good inspiration.

For more information

• OvenMediaEngine GitHub

• OvenMediaEngine Website

• OvenMediaEngine Tutorial Source

• Test Player

  • Without TLS: http://demo.ovenplayer.com

  • With TLS: https://demo.ovenplayer.com

• OvenPlayer Github

• AirenSoft Website

License

OvenMediaEngine is licensed under the AGPL-3.0-only. However, if you need another license, please feel free to email us at contact@airensoft.com.

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.8

$ 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

$ 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

Publishing

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

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.

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.

Add your certificate files to as follows:

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.

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.

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.

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.

Installation

Run the following command in your Linux shell.

Below is an example of execution:

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.

Certificate Installation

To install a certificate in OvenMediaEngine, copy the certificate files to /usr/share/ovenmediaengine/conf with the following names:

If you want to change the file names, you can modify Server.xml.

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.

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.

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

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>
...

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>
...

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.

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 Alliance website.

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:

<Bind>
    <Providers>
        ...
        <SRT>
            <Port>9999</Port>
            <!-- <WorkerCount>1</WorkerCount> -->
        </SRT>
    </Providers>

Application

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

<Applications>
    <Application>
        <Name>app</Name>
        <Providers>
            <SRT/>

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.

OvenMediaEngine classifies each stream using SRT's streamid. This means that unlike MEPG-TS/udp, OvenMediaEngine can receive multiple SRT streams through one port. For more information on streamid, see Haivision's official documentation.

Therefore, in order for the SRT encoder to transmit a stream to OvenMediaEngine, the following information must be included in the streamid as percent encoded.

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

OBS Studio

OBS Studio 25.0 or later supports SRT. Please refer to the OBS official documentation for more information. Enter the address of OvenMediaEngine in OBS Studio's Server as follows: When using SRT in OBS, leave the Stream Key blank.

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

The streamid has to be the urlencoded address of the server name as specified in the ome server configuration plus the app name and the stream name, each separated by /. The latency configures the size of the server-side recive buffer and the time limit for SRT in nanoseconds. Typical value for latency are 150000 (150ms) for stremaing to a server in the local network, 600000 (600ms) for streaming to a server over the internet in the local region, and 2000000 (2 seconds) when stremaing over long distance.

Blackmagic Web Presenter

For configuring a Blackmagic Web Presenter, ATEM Mini Pro or similar device to stream to OvenMediaEngine over SRT, choose the "Custom URL H264/H265" platform option with the following syntax:

Server: srt://your-server-domain.com:<SRT_PORT>
Key: <PERCENT_ENCODED_STREAM_ID>

The default streaming profiles work well, and there are more advanced configuration options available if you edit the streaming.xml settings file

SRT Socket Options

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

<Server>
    <Bind>
        <Providers>
            <SRT>
                ...
                <Options>
                    <Option>
                        <Key>SRTO_PBKEYLEN</Key>
                        <Value>16</Value>
                    </Option>
                    <Option>
                        <Key>SRTO_PASSPHRASE</Key>
                        <Value>thisismypassphrase</Value>
                    </Option>
                </Options>
            </SRT>
...

For more information on SRT socket options, please refer to https://github.com/Haivision/srt/blob/master/docs/API/API-socket-options.md#list-of-options.

Configuration

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

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:

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

<BlockDuplicateStreamName> works with the following rules:

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.

TranscodeWebhook allows OvenMediaEngine to use OutputProfiles from the Control Server's response instead of the OutputProfiles in the local configuration (Server.xml). OvenMediaEngine requests OutputProfiles from the Control Server when streams are created, enabling the specification of different profiles for each individual stream.

Configuration

Enable (required) You can enable or disable TranscodeWebhook settings.

ControlServerUrl (required) It's the URL of the Control Server, and it supports both HTTP and HTTPS.

SecretKey (optional) This is the Secret Key used to pass authentication for the Control Server. To pass security authentication, an HMAC-SHA1 encrypted value of the HTTP Payload is added to the HTTP Header's X-OME-Signature. This Key is used for generating this value.

Timeout (optional, default: 1500) This is the Timeout value used when connecting to the Control Server.

UseLocalProfilesOnConnectionFailure(optional, default: true) This determines whether to use the OutputProfiles from Local settings in case of communication failure with the Control Server. If it's set to "false," a communication failure with the Control Server will result in a failure to create the Output stream.

UseLocalProfilesOnServerDisallow (optional, default: false) When the Control Server responds with a 200 OK, but "allowed" is set to "false," this policy is followed.

UseLocalProfilesOnErrorResponse (optional, default: false) When the Control Server responds with error status codes such as 400 Bad Request, 404 Not Found, 500 Internal Error, OvenMediaEngine follows this policy.

Protocol

Request (OME → Control Server)

OvenMediaEngine sends requests to the Control Server in the following format.

Response (Control Server → OME)

The Control Server responds in the following format to specify OutputProfiles for the respective stream.

The "outputProfiles" in the JSON is identical to the configuration in Server.xml, and the format is as follows.

OvenMediaEngine supports GPU-based hardware decoding and encoding. Currently supported GPU acceleration devices are Intel's QuickSync and NVIDIA. This article explains how to install the drivers for OvenMediaEngine and set up the configuration to use your GPU.

1. Install Drivers

2. Build & Run

Please refer to the link for how to build and run.

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.

Appendix. 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

Now with Multiplex Channel, you can configure ABR by combining multiple input streams into one, or duplicate external streams and send them to other applications.

Multiplex Channel takes tracks from other local streams and organizes them into its own tracks. This will pull in tracks that have already been encoded, which can be useful if you want to change codecs or adjust the quality once again. And the Multiplex Channel is sent to the publisher, unconditionally bypassing the encoder.

Configuration

To use this feature, enable Multiplex Provider in Server.xml.

Multiplex Channels are created through .mux files or API. MuxFilesDir is the path where the .mux files are located and can be set to an absolute system path or relative to the path where the Server.xml configuration is located.

The Multiplex Provider monitors the MuxFilesDir path, and when a mux file is created, it parses the file and creates a multiplex channel. When the mux file is modified, the channel is deleted and created again, and when the mux file is deleted, the channel is deleted.

Mux file format

mux files can be created or deleted while the system is running. This works dynamically. The mux file has the format below.

OutputStream This is information about the stream to be newly created. It must be the same as the file name. <stream name>.mux

SourceStreams Specifies the internal stream to be muxed. You can also load streams from other VHosts or applications in the format stream://<vhost name>/<app name>/<stream name>. Because multiple streams are muxed into one stream, track names may be duplicated. Therefore, it is necessary to change the Track name for each SourceStream through <TrackMap>. <SourceTrackName> is either <OutputProfile><Encodes><Video><Name> or <OutputProfile><Encodes><Audio><Name>.

Playlist The same format as <OutputProfile> must be used, and the Playlist must be constructed using the newly mapped Track name in SourceStreams' TrackMap. The Playlist configured here exists only in this stream. The Playlist's FileName must be unique throughout the application.

REST API

MultiplexChannel can also be controlled via API. Please refer to the page below.

Scheduled Channel that allows you to create a live channel by scheduling pre-recorded files has been added to OvenMediaEngine. Other services or software call this Pre-recorded Live or File Live, but OvenMediaEngine plans to expand the function to organize live channels as a source, so we named it Scheduled Channel.

Getting Started

To use this feature, activate Schedule Provider as follows.

MediaRootDir Root path where media files are located. If you specify a relative path, the directory where the config file is located is root.

ScheduleFileDir Root path where the schedule file is located. If you specify a relative path, the directory where the config file is located is root.

Schedule Files

Scheduled Channel creates/updates/deletes streams by creating/editing/deleting files with the .sch extension in the ScheduleFileDir path. Schedule files (.sch) use the following XML format. When a <Stream Name>.sch file is created in ScheduleFileDir, OvenMediaEngine analyzes the file and creates a Schedule Channel with <Stream Name>. If the contents of <Stream Name>.sch are changed, the Schedule Channel is updated, and if the file is deleted, the stream is deleted.

Stream (required) This is the stream information that the Channel needs to create.

Stream.Name (optional) It's the stream's name. This is a reference value extracted from the file name for usage. It's recommended to set it same for consistency, although it's for reference purposes.

Stream.BypassTranscoder (optional, default: false) Set to true if transcoding is not desired.

Stream.VideoTrack (optional, default: true) Determines whether to use the video track. If VideoTrack is set to true and there's no video track in the Item, an error will occur.

Stream.AudioTrack (optional, default: true) Determines whether to use the audio track. If AudioTrack is set to true and there's no audio track in the Item, an error will occur.

FallbackProgram (optional) It is a program that switches automatically when there is no program scheduled at the current time or an error occurs in an item. If the program is updated at the current time or the item returns to normal, it will fail back to the original program. Both files and live can be used for items in FallbackProgram. However, it is recommended to use a stable file.

Program (optional) Schedules a program. The name is an optional reference value. If not set, a random name will be assigned. Set the start time in ISO8601 format in the scheduled attribute. Decide whether to repeat the Items when its playback ends.

Program.Item (optional) Configures the media source to broadcast.

The url points to the location of the media source. If it starts with file://, it refers to a file within the MediaRootDir directory. If it starts with stream://, it refers to another stream within the same OvenMediaEngine. stream:// has the following format: stream://vhost_name/app_name/stream_name

For 'file' cases, the start attribute can be set in milliseconds to indicate where in the file playback should start. duration indicates the playback time of that item in milliseconds. After the duration ends, it moves to the next item. Both 'start' and 'duration' are optional. If not set, start defaults to 0, and duration defaults to the file's duration; if not specified, the media file will be played until its full duration.

Application : Persistent Live Channel

This function is a scheduling channel, but it can be used for applications such as creating a permanent stream as follows.

This channel normally plays default/app/input, but when live input is stopped, it plays the file in FallbackProgram. This will last forever until the .sch file is deleted. One trick was to set the origin program's schedule time to year 2000 so that this stream would play unconditionally.

REST API

ScheduledChannel can also be controlled via API. Please refer to the page below.

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

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

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

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.

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.

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:

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.

<Application>
   <Publishers>
      <OVT />
	  <LLHLS />
      <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,llhls</Publishers>
                </Enables>
            </SignedPolicy>
            -->

            <!--
            <AdmissionWebhooks>
                <ControlServerUrl></ControlServerUrl>
                <SecretKey></SecretKey>
                <Timeout>3000</Timeout>
                <Enables>
                    <Providers>rtmp,webrtc,srt</Providers>
                    <Publishers>webrtc,llhls</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>

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.

<VirtualHost>
	<AdmissionWebhooks>
		<ControlServerUrl>https://192.168.0.161:9595/v1/admission</ControlServerUrl>
		<SecretKey>1234</SecretKey>
		<Timeout>3000</Timeout>
		<Enables>
			<Providers>rtmp,webrtc,srt</Providers>
			<Publishers>webrtc,llhls,thumbnail</Publishers>
		</Enables>
	</AdmissionWebhooks>
</VirtualHost>

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.

POST /configured/target/url/ HTTP/1.1
Content-Length: 325
Content-Type: application/json
Accept: application/json
X-OME-Signature: f871jd991jj1929jsjd91pqa0amm1
{
  "client": 
  {
    "address": "211.233.58.86",
    "port": 29291,
    "real_ip": "192.0.2.43",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36"
  },
  "request":
  {
    "direction": "incoming | outgoing",
    "protocol": "webrtc | rtmp | srt | llhls | thumbnail",
    "status": "opening | closing",
    "url": "scheme://host[:port]/app/stream/file?query=value&query2=value2",
    "new_url": "scheme://host[:port]/app/new_stream/file?query=value&query2=value2",
    "time": ""2021-05-12T13:45:00.000Z"
  }
}

The message is sent in POST method and the payload is in application/json format. X-OME-Signature is a base64 url safe encoded value obtained by encrypting the payload with HMAC-SHA1 so that the ControlServer can validate this message. See the Security section for more information on X-OME-Signature.

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.

HTTP/1.1 200 OK
Content-Length: 5
Content-Type: application/json
Connection: Closed
{
}

Response for opening status

Format

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

HTTP/1.1 200 OK
Content-Length: 102
Content-Type: application/json
Connection: Closed
{
  "allowed": true,
  "new_url": "scheme://host[:port]/app/stream/file?query=value&query2=value2",
  "lifetime": milliseconds,
  "reason": "authorized"
}

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.

HLS based on MPEG-2 TS containers is still useful because it provides high compatibility, including support for older devices. Therefore, OvenMediaEngine decided to officially support HLS version 7+ based on fragmented MP4 containers, called LL-HLS, as well as HLS version 3+ based on MPEG-2 TS containers.

Configuration

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

Playback

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

HLS Publisher basically creates a playlist.m3u8 Playlist using the first video track and the first audio track. When you create a stream, as shown above, you can play HLS with the following URL:

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

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

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

Adaptive Bitrates Streaming (ABR)

HLS can deliver adaptive bitrate streaming. OME encodes the same source with multiple renditions and delivers it to the players. And HLS 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.

HLS Publisher basically creates a playlist.m3u8 Playlist using the first video track and the first audio track. If you want to create a new playlist for ABR, you can add it to Server.xml as follows:

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:

Live Rewind

You can create as long a playlist as you want by setting <DVR> to the HLS 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.

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.

Signature

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.