0% found this document useful (0 votes)
438 views167 pages

Oven Media Engine

OvenMediaEngine is an open-source streaming server that provides low-latency streaming using WebRTC, DASH, and HLS. It can ingest streams via RTMP, WebRTC, and other protocols, and distribute streams via HTTP-based protocols with sub-second latency. The document provides information on OvenMediaEngine's features, supported platforms, and instructions for getting started with the software.

Uploaded by

cephas01
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
438 views167 pages

Oven Media Engine

OvenMediaEngine is an open-source streaming server that provides low-latency streaming using WebRTC, DASH, and HLS. It can ingest streams via RTMP, WebRTC, and other protocols, and distribute streams via HTTP-based protocols with sub-second latency. The document provides information on OvenMediaEngine's features, supported platforms, and instructions for getting started with the software.

Uploaded by

cephas01
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 167

0.12.

9
Introduction

What is OvenMediaEngine?
OvenMediaEngine (OME) is an open-source and streaming server with sub-second latency. OME receives
video via RTMP, MPEG-TS, and RSTP Pull from live encoders such as OBS, FFMPEG, and more. Then
OME transmits video using WebRTC, Low-Latency HTTP (DASH), MPEG-DASH, and HLS. This enables
sub-second latency streaming from OME which plays back seamlessly in your browser without requiring any
plug-ins. Also, we provide OvenPlayer, the most optimized HTML5 player for OME, as an open-source.

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

Features

Ingest
WebRTC Push, RTMP Push, SRT Push, MPEG-2 TS Push, RTSP Pull
WebRTC sub-second streaming
WebRTC over TCP (with embedded TURN server)
Embedded WebRTC Signalling Server (WebSocket based)

ICE (Interactive Connectivity Establishment)

DTLS (Datagram Transport Layer Security)


SRTP (Secure Real-time Transport Protocol)
ULPFEC (Forward Error Correction) with VP8, H.264
In-band FEC (Forward Error Correction) with Opus
Low-Latency MPEG-DASH streaming (Chunked CMAF)

Legacy HLS/MPEG-DASH streaming


Embedded Live Transcoder (VP8, H.264, Opus, AAC, Bypass)
Origin-Edge structure

Monitoring
AccessC
Beta
File Recording
RTMP Push Publishing(re-streaming)
Thumbnail

REST API
Experiment
P2P Traffic Distribution

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

CentOS 7
Fedora 28

Getting Started
Please read Getting Started chapter in tutorials.

For more information

OvenMediaEngine Github
OvenMediaEngine Website
Basic Information, FAQ, and Benchmark
OvenMediaEngine Tutorials
Getting Started, Install, and Configuration
Test Player
Without TLS : http://demo.ovenplayer.com

Based on TLS : https://demo.ovenplayer.com


OvenPlayer Github
OvenPlayer Website
AirenSoft Website
How to Contribute
Please see our Guidelines and Rules.

License
OvenMediaEngine is under the GPLv2 license.

Getting Started

Running with Docker


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

1 docker run -d \
2 -p 1935:1935 -p 4000-4005:4000-4005/udp -p 3333:3333 -p 3478:3478 -p 8080:8080 -p 9000:9000
3 airensoft/ovenmediaengine:0.12.9

You can set the following environment variables.

Ports

Env Default Value

OME_ORIGIN_PORT 9000

OME_RTMP_PROV_PORT 1935

OME_SRT_PROV_PORT 9999/udp

OME_MPEGTS_PROV_PORT 4000-4005/udp

OME_HLS_PUB_PORT 8080

OME_DASH_PUB_PORT 8080

OME_TCP_RELAY_ADDRESS *:3478

OME_ICE_CANDIDATES *:10006-10010/udp

OME_SIGNALLING_PORT 3333
Manual Installation and Execution

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

1 (curl -LOJ https://github.com/AirenSoft/OvenMediaEngine/archive/v0.12.9.tar.gz && tar xvfz


2 OvenMediaEngine-0.12.9/misc/prerequisites.sh

If the prerequisites.sh script fails, proceed with the manual installation.

Build & Run

You can build the OvenMediaEngine source using the following command:

Ubuntu 18

1 sudo apt-get update


2 cd OvenMediaEngine-0.12.9/src
3 make release
4 sudo make install
5 systemctl start ovenmediaengine
6 # If you want automatically start on boot
7 systemctl enable ovenmediaengine.service

Fedora 28

1 sudo dnf update


2 cd OvenMediaEngine-0.12.9/src
3 make release
4 sudo make install
5 systemctl start ovenmediaengine
6 # If you want automatically start on boot
7 systemctl enable ovenmediaengine.service
CentOS 7

1 sudo yum update


2 source scl_source enable devtoolset-7
3 cd OvenMediaEngine-0.12.9/src
4 make release
5 sudo make install
6 systemctl start ovenmediaengine
7 # If you want automatically start on boot
8 systemctl enable ovenmediaengine.service

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

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

Port Purpose

1935/TCP RTMP Input

9999/UDP SRT Input

4000-4005/UDP MPEG-2 TS Input

9000/TCP Origin Server (OVT)

80/TCP HLS & MPEG-Dash Streaming

3333/TCP WebRTC Signalling (both ingest and streaming)

WebRTC TCP relay (TURN Server, both ingest


3478/TCP
and streaming)

10000 - 10010/UDP WebRTC Ice candidate (both ingest and streamin

You can open firewall ports as in the following example:

1 $ sudo firewall-cmd --add-port=80/tcp


2
3 $
$ sudo
sudo firewall-cmd
firewall-cmd --add-port=1935/tcp
--add-port=9999/udp

4 $ sudo firewall-cmd --add-port=4000-4005/udp


5 $ sudo firewall-cmd --add-port=3333/tcp
6 $ sudo firewall-cmd --add-port=3478/tcp
7 $ sudo firewall-cmd --add-port=9000/tcp
8 $ sudo firewall-cmd --add-port=10000-10010/udp

Hello Sub-Second Latency Streaming

Start Streaming

You can live streaming using live encoders such as OBS, XSplit, and OvenStreamEncoder. Please set the
RTMP URL as below:

rtmp://<Server IP>[:<RTMP Port>]/<Application name>/<Stream name>

The meanings of each item are as follows:

<Server IP> : IP address or domain of the OvenMediaEngine server.

<RTMP Port> : You can use <Port> of <Provider> in the above Server.xml file. With the
default configuration, the RTMP default port (1935) is used. Also, by setting the default port, you can
omit the port.

<Application name> : This value corresponds to <Name> of <Application> in


conf/Server.xml . If you use the default configuration, you can use the app .

<Stream name> : Name of the stream you defined.

After you enter the above RTMP URL into the encoder and start publishing, you will have an environment in
which the player can view the live stream.

Example of using OvenLiveKit (OvenStreamEncoder)

OvenLiveKit is a transmission SDK. So, you can easily add broadcast transmission functions to your apps
using this SDK. And OvenStreamEncoder is a sample app that shows you can make and use it with
OvenLiveKit. You can use it by searching OvenStreamEncoder in Google Play.
OvenStreamEncoder supports the mode that implements the streaming of the screen recorded by a camera
and another that performs the streaming of the current screen by capturing it.

So, select the mode along with the broadcasting concept you want and proceed with the optimum setting by
pressing the Setting icon at this right upper position.
After broadcast setting, return to the original screen, press the URL button at right upper, and input RTMP
URL and Stream Key to transmitting.
If all preparation is ready, begin the broadcast by pressing the Recording button at the center bottom.
Also, we ran tests to see how well OvenStreamEnocder is optimized for OvenMediaEngine. If you are
interested, click HERE to check.

Example of using OBS Encoder

The server address in OBS needs to use <Application name> generated in Server.xml . If you use
the default configuration, the app is already created and ready to use.

Install OBS on your PC and run it.

Click "File" in the top menu, then click "Settings" (or press "Settings" on the lower right).

Select the "Stream" tab and enter your stream information.

Press "Service" and select "Custom", your OBS is the same as this image.

Go to the "Output" tab.


Set the following entries.

For lower latency, we recommend using the Hardware Encoder as follows: "NVENC" provides a Low-
Latency preset. It's also important to set "MAX B-frame = 0" to reduce latency.
If Hardware Encoder isn't installed on your PC, it's recommended to set x264 as follows: We highly
recommend setting "bframes = 0" to reduce latency. Then set the "threads" option to 8 or less. Chrome
doesn't handle more than 10 Nal Units. The best way to avoid this is to set "thread = 8".

We recommend checking "Enable new networking code" and "Low latency mode" on Network in Advanced
Settings as follows:
Playback

We have prepared a test player so that you can easily check if OvenMediaEngine is working properly.
Please see the chapter on Test Player for more information.

Please note that WebRTC Signalling URL is similar to the RTMP URL and consists of the following:

ws://<Server IP>:[<Signalling Port>/<Application name>/<Output Stream


name>[?transport=tcp]
<Server IP> : IP address or domain of the OvenMediaEngine server.

<Signalling Port> : You can use the value of <Signalling><ListenPort> in


Server.xml above. If you use the default configuration, the WebRTC Signalling default port
(3333) is used.

<Application name> : This value corresponds to <Name> of <Application> in


conf/Server.xml . If you use the default configuration, you can use the app .

<Output Stream name> : You have to use an output stream name for streaming. If you use the
default configuration, an output stream named <Stream Name> is automatically generated when
the stream is input.

?transport=tcp : You can use this query string to play through webrtc over tcp. Useful in
environments with severe packet loss.

As of version 0.10.4, the default output stream name has been changed from <Input Stream
Name>_o to <Input Stream Name>, and has been updated to use the input stream name as the
output stream name for convenience.

If you use the default configuration, the RTMP publishing URL is


rtmp://192.168.0.1:1935/app/stream

Then the WebRTC URL will be ws://192.168.0.1:3333/app/stream

In addition,
WebRTC over TCP URL will be ws://192.168.0.1:3333/app/stream?transport=tcp

HLS streaming URL will be http://192.168.0.1:8080/app/stream/playlist.m3u8


MPEG-DASH streaming URL will
be http://192.168.0.1:8080/app/stream/manifest.mpd
Low-Latency MPEG-DASH streaming URL will be
http://192.168.0.1:8080/app/stream/manifest_ll.mpd

If you want to build OvenPlayer in your environment, see OvenPlayer QuickStart.

Configuration

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

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

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

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

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

1 # For Origin mode


2 /opt/ovenmediaengine/bin/origin_conf/Server.xml
3 # For Edge mode

4 /opt/ovenmediaengine/bin/edge_conf/Server.xml

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

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


2 <Server version="8">
3 <Name>OvenMediaEngine</Name>
4 <IP>*</IP>
5 <PrivacyProtection>false</PrivacyProtection>
6 <StunServer>stun.l.google.com:19302</StunServer>
7 <Bind>...</Bind>
8 <VirtualHosts>...</VirtualHosts>
9 </Server>

IP

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

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

1 <Bind>
2 <Providers>
3 <RTMP>
4 <Port>1935</Port>
5 </RTMP>
6 <SRT>
7 <Port>9999</Port>
8 </SRT>
9 <MPEGTS>
10 <Port>4000-4003,4004,4005/udp</Port>
11 </MPEGTS>
12 <WebRTC>
13 <Signalling>
14 <Port>3333</Port>
15 </Signalling>
16 <IceCandidates>
17 <TcpRelay>*:3478</TcpRelay>
18 <IceCandidate>*:10000-10005/udp</IceCandidate>
19 </IceCandidates>
20 </WebRTC>
21 </Providers>
22
23 <Publishers>
24 <OVT>
25 <Port>9000</Port>
26 </OVT>
27 <HLS>
28 <Port>80</Port>
29 </HLS>
30 <DASH>
31 <Port>80</Port>
32 </DASH>
33 <WebRTC>
34 <Signalling>
35 <Port>3333</Port>
36 </Signalling>
37 <IceCandidates>
38 <TcpRelay>*:3478</TcpRelay>
39 <IceCandidate>*:10000-10005/udp</IceCandidate>
40 </IceCandidates>
41 </WebRTC>
42 </Publishers>
43 </Bind>

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

Element Description
RTMP RTMP tf i i RTMP t
SRT SRT port for incoming SRT stream

MPEGTS ports for incoming MPEGTS/UDP


MPEG-TS
stream.

Port for WebRTC. If you want more information on


WebRTC the WebRTC port, see the WebRTC Ingest and
WebRTC Streaming chapters.

OVT port for an origin server.


OVT is a protocol defined by OvenMediaEngine f
OVT Origin-Edge communication. For more information
about Origin-Edge, see the Origin-Edge Clusterin
chapter.

HLS HTTP(s) port for HLS streaming.

HTTP(s) port for MPEG-DASH streaming includin


DASH
Low-Latency MPEG-DASH.

HLS and DASH can be set to the same port, but all other protocols have to use different ports. The
ability for all protocols to use the same port will be updated in the future.

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.

VirtualHosts consist of Name , Host , Origins , SignedPolicy , and Applications .

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


2 <Server version="8">
3 <Name>OvenMediaEngine</Name>
4 <VirtualHosts>
5 <VirtualHost>

6 <Name>default</Name>
7 <Host>
8 ...
9 </Host>
10
11 <Origins>
12
13 </Origins>
...
14
15 <SignedPolicy>
16 ...
17 </SignedPolicy>
18
19 <Applications>
20 ...
21 </Applications>
22 </Host>
23 </Hosts>
24 </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.

1 <Host>
2 <Names>
3 <!-- Domain names
4 <Name>stream1.airensoft.com</Name>
5 <Name>stream2.airensoft.com</Name>
6 <Name>*.sub.airensoft.com</Name>
7 -->
8 <Name>*</Name>
9 </Names>
10 </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.

1 <Origins>
2 <Origin>
3 <Location>/app/stream</Location>
4 <Pass>
5 <Scheme>ovt</Scheme>
6 <Urls><Url>origin.com:9000/app/stream_720p</Url></Urls>
7 </Pass>
8 </Origin>
9 <Origin>
10 <Location>/app/</Location>
11 <Pass>
12 <Scheme>ovt</Scheme>
13 <Urls><Url>origin.com:9000/app/</Url></Urls>
14 </Pass>
15 </Origin>
16 <Origin>
17 <Location>/rtsp/stream</Location>
18 <Pass>
19 <Scheme>rtsp</Scheme>
20 <Urls><Url>rtsp-server.com:554/</Url></Urls>
21 </Pass>
22 </Origin>
23 <Origin>
24 <Location>/</Location>
25 <Pass>
26 <Scheme>ovt</Scheme>
27 <Urls><Url>origin2.com:9000/</Url></Urls>
28 </Pass>
29 </Origin>
30 </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.

1 <VirtualHost>
2 ...

3 <Applications>
4 <Application>
5 ...
6 </Application>
7 <Application>
8 ...
9
10 </Applications>
</Application>
11 </VirtualHost>

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

1 <Application>
2 <Name>app</Name>
3 <Type>live</Type>
4 <OutputProfiles> ... </OutputProfiles>
5 <Providers> ... </Providers>
6 <Publishers> ... </Publishers>
7 </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> .

1 <Application>
2 <OutputProfiles>
3 <OutputProfile>
4 <Name>bypass_stream</Name>
5 <OutputStreamName>${OriginStreamName}</OutputStreamName>
6 <Encodes>
7 <Audio>
8 <Bypass>true</Bypass>
9 </Audio>
10 <Video>
11 <Bypass>true</Bypass>
12 </Video>
13 <Audio>
14 <Codec>opus</Codec>
15 <Bitrate>128000</Bitrate>
16 <Samplerate>48000</Samplerate>
17 <Channel>2</Channel>
18 </Audio>
19 <!--
20 <Video>
21 <Codec>vp8</Codec>
22 <Bitrate>1024000</Bitrate>
23 <Framerate>30</Framerate>
24 <Width>1280</Width>
25 <Height>720</Height>
26 </Video>
27
28 </Encodes>
-->
29 </OutputProfile>
30 </OutputProfiles>
31 </Application>

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

Providers

Providers ingest streams that come from a media source.

1 <Application>
2 <Providers>
3 <RTMP/>
4 <WebRTC/>
5 <SRT/>
6 <RTSPPull/>
7 <OVT/>
8 <MPEGTS>
9 <StreamMap>
10 ...
11 </StreamMap>
12 </MPEGTS>
13 </Providers>
14 </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.

1 <Application>
2 <Publishers>
3 <OVT />
4 <HLS />
5 <DASH />
6 <LLDASH />
7 <WebRTC />
8 </Publishers>
9 </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:

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


2
3 <Server version="8">
4 <Name>OvenMediaEngine</Name>
5 <!-- Host type (origin/edge) -->
6 <Type>origin</Type>
7 <!-- Specify IP address to bind (* means all IPs) -->
8 <IP>*</IP>
9
10 <!--
11 To get the public IP address(mapped address of stun) of the local server.
12 This is useful when OME cannot obtain a public IP from an interface, such as AWS or doc
13 If this is successful, you can use ${PublicIP} in your settings.
14 -->
15 <StunServer>stun.l.google.com:19302</StunServer>
16
17 <!-- Settings for the ports to bind -->
18 <Bind>
19 <!-- Enable this configuration if you want to use API Server -->
20 <!--
21 <Managers>
22 <API>
23 <Port>48081</Port>
24 <WorkerCount>1</WorkerCount>
25 </API>
26 </Managers>
27 -->
28
29 <Providers>
30 <RTMP>
31 <Port>1935</Port>
32 <!-- <WorkerCount>1</WorkerCount> -->
33 </RTMP>
34 <SRT>
35 <Port>9999</Port>
36 <!-- <WorkerCount>1</WorkerCount> -->
37 </SRT>
38
39 <MPEGTS>
<!--
40 Listen on port 4000~4005
41 This is just a demonstration to show that you can configure the port in
42 -->
43 <Port>4000-4004,4005/udp</Port>
44 </MPEGTS>
45 <WebRTC>
46 <Signalling>
47 <Port>3333</Port>
48 <!-- If you want to use TLS, specify the TLS port -->
49 <!-- <TLSPort>3334</TLSPort> -->
50 <!-- <WorkerCount>4</WorkerCount> -->
51 </Signalling>
52
53 <IceCandidates>
54 <!--
55 If you want to stream WebRTC over TCP, specify IP:Port for TURN se
56 This uses the TURN protocol, which delivers the stream from the bui
57 For detailed information, refer https://airensoft.gitbook.io/ovenme
58 -->
59 <TcpRelay>*:3478</TcpRelay>
60 <IceCandidate>*:10000-10005/udp</IceCandidate>
61
62 <!--
63 Sets the number of worker threads to use in TcpRelay
64
65 <TcpRelayWorkerCount>4</TcpRelayWorkerCount>
66 -->
67 </IceCandidates>
68 </WebRTC>
69 </Providers>
70
71 <Publishers>
72 <OVT>
73 <Port>9000</Port>
74 <!-- <WorkerCount>1</WorkerCount> -->
75 </OVT>
76 <HLS>
77 <Port>80</Port>
78 <!-- If you want to use TLS, specify the TLS port -->
79 <!-- <TLSPort>443</TLSPort> -->
80 <!-- <WorkerCount>4</WorkerCount> -->
81 </HLS>
82 <DASH>
83 <Port>80</Port>
84 <!-- If you want to use TLS, specify the TLS port -->
85 <!-- <TLSPort>443</TLSPort> -->
86 <!-- <WorkerCount>4</WorkerCount> -->
87 </DASH>
88 <Thumbnail>
89 <Port>80</Port>
90 <!-- If you want to use TLS, specify the TLS port -->
91
92 <!-- <TLSPort>443</TLSPort> -->
<WorkerCount>4</WorkerCount> -->
93 </Thumbnail>
94 <WebRTC>
95 <Signalling>
96 <Port>3333</Port>
97 <!-- If you want to use TLS, specify the TLS port -->
98 <!-- <TLSPort>3334</TLSPort> -->
99 <!-- <WorkerCount>4</WorkerCount> -->
100 </Signalling>
101
102 <IceCandidates>
103 <!--
104 If you want to stream WebRTC over TCP, specify IP:Port for TURN se
105 This uses the TURN protocol, which delivers the stream from the bui
106 For detailed information, refer https://airensoft.gitbook.io/ovenme
107 -->
108 <TcpRelay>*:3478</TcpRelay>
109 <IceCandidate>*:10000-10005/udp</IceCandidate>
110
111 <!--
112 Sets the number of worker threads to use in TcpRelay
113
114 <TcpRelayWorkerCount>4</TcpRelayWorkerCount>
115 -->
116 </IceCandidates>
117 </WebRTC>
118 </Publishers>
119 </Bind>
120
121 <!-- P2P works only in WebRTC -->
122 <!--
123 <P2P>
124 <MaxClientPeersPerHostPeer>2</MaxClientPeersPerHostPeer>
125 </P2P>
126 -->
127
128 <!--
129 Enable this configuration if you want to use API Server
130
131 <AccessToken> is a token for authentication, and when you invoke the API, you must
132 For example, if you set <AccessToken> to "ome-access-token", you must set "Basic b2
133 -->
134 <!--
135 <Managers>
136 <Host>
137 <Names>

138 <Name>*</Name>
139 </Names>
140 <TLS>
141 <CertPath>path/to/file.crt</CertPath>
142 <KeyPath>path/to/file.key</KeyPath>
143 <ChainCertPath>path/to/file.crt</ChainCertPath>
144
145 </TLS>
</Host>
146 <API>
147 <AccessToken>ome-access-token</AccessToken>
148 </API>
149 </Managers>
150 -->
151
152 <VirtualHosts>
153 <!-- You can use wildcard like this to include multiple XMLs -->
154 <VirtualHost include="VHost*.xml" />
155 <VirtualHost>
156 <Name>default</Name>
157
158 <!-- Settings for multi ip/domain and TLS -->
159 <Host>
160 <Names>
161 <!-- Host names
162 <Name>stream1.airensoft.com</Name>
163 <Name>stream2.airensoft.com</Name>
164 <Name>*.sub.airensoft.com</Name>
165 <Name>192.168.0.1</Name>
166 -->
167 <Name>*</Name>
168 </Names>
169 <!--
170 <TLS>
171 <CertPath>path/to/file.crt</CertPath>
172 <KeyPath>path/to/file.key</KeyPath>
173 <ChainCertPath>path/to/file.crt</ChainCertPath>
174 </TLS>
175 -->
176 </Host>
177
178 <!-- Refer https://airensoft.gitbook.io/ovenmediaengine/signedpolicy
179
180 <SignedPolicy>
181 <PolicyQueryKeyName>policy</PolicyQueryKeyName>
182 <SignatureQueryKeyName>signature</SignatureQueryKeyName>
183 <SecretKey>aKq#1kj</SecretKey>
184
185 <Enables>
186 <Providers>rtmp</Providers>
187 <Publishers>webrtc,hls,dash,lldash</Publishers>
188 </Enables>
189 </SignedPolicy>
190
-->
191
192 <!--
193 <Origins>
194
195 <Origin>
196 <Location>/app/stream</Location>
197
197
<Pass>
198 <Scheme>ovt</Scheme>
199 <Urls><Url>origin.com:9000/app/stream_720p</Url></Urls>
200 </Pass>
201 </Origin>
202 <Origin>
203 <Location>/app/</Location>
204 <Pass>
205 <Scheme>ovt</Scheme>
206 <Urls><Url>origin.com:9000/app/</Url></Urls>
207 </Pass>
208 </Origin>
209 <Origin>
210 <Location>/edge/</Location>
211 <Pass>
212 <Scheme>ovt</Scheme>
213 <Urls><Url>origin.com:9000/app/</Url></Urls>
214 </Pass>
215 </Origin>
216 </Origins>
217 -->
218 <!-- Settings for applications -->
219 <Applications>
220 <Application>
221 <Name>app</Name>
222 <!-- Application type (live/vod) -->
223 <Type>live</Type>
224 <OutputProfiles>
225 <OutputProfile>
226 <Name>bypass_stream</Name>
227 <OutputStreamName>${OriginStreamName}</OutputStreamName>
228 <Encodes>
229 <Audio>
230 <Bypass>true</Bypass>
231 </Audio>
232 <Video>
233 <Bypass>true</Bypass>
234 </Video>
235 <Audio>
236 <Codec>opus</Codec>
237 <Bitrate>128000</Bitrate>
238 <Samplerate>48000</Samplerate>
239 <Channel>2</Channel>
240 </Audio>
241 <!--
242 <Video>
243
<Codec>vp8</Codec>
244 <Bitrate>1024000</Bitrate>
245 <Framerate>30</Framerate>
246 <Width>1280</Width>
247 <Height>720</Height>
248 </Video>
249
250 </Encodes>
-->
251 </OutputProfile>
252
253 <!-- For thumbnail -->
254 <!--
255 <OutputProfile>
256 <Name>default_stream</Name>
257 <OutputStreamName>${OriginStreamName}_preview</OutputStreamName
258 <Encodes>
259 <Image>
260 <Codec>png</Codec>
261 <Framerate>1</Framerate>
262 <Width>1280</Width>
263 <Height>720</Height>
264 </Image>
265 </Encodes>
266 </OutputProfile>
267 -->
268 </OutputProfiles>
269 <Providers>
270 <OVT />
271 <WebRTC />
272 <RTMP />
273 <SRT />
274 <MPEGTS>
275 <StreamMap>
276 <!--
277 Set the stream name of the client connected to the port
278 For example, if a client connets to port 4000, OME crea
279 -->
280 <Stream>
281 <Name>stream_${Port}</Name>
282 <Port>4000,4001-4004</Port>
283 </Stream>
284 <Stream>
285 <Name>stream_4005</Name>
286 <Port>4005</Port>
287 </Stream>
288 </StreamMap>
289 </MPEGTS>
290 <RTSPPull />
291 <WebRTC>
292 <Timeout>30000</Timeout>
293 </WebRTC>
294 </Providers>
295 <Publishers>
296
<SessionLoadBalancingThreadCount>8</SessionLoadBalancingThreadCount
297 <OVT />
298 <WebRTC>
299 <Timeout>30000</Timeout>
300 <Rtx>true</Rtx>
301 <Ulpfec>true</Ulpfec>
302
302
</WebRTC>
303 <HLS>
304 <SegmentDuration>5</SegmentDuration>
305 <SegmentCount>3</SegmentCount>
306 <CrossDomains>
307 <Url>*</Url>
308 </CrossDomains>
309 </HLS>
310 <DASH>
311 <SegmentDuration>5</SegmentDuration>
312 <SegmentCount>3</SegmentCount>
313 <CrossDomains>
314 <Url>*</Url>
315 </CrossDomains>
316 </DASH>
317 <LLDASH>
318 <SegmentDuration>5</SegmentDuration>
319 <CrossDomains>
320 <Url>*</Url>
321 </CrossDomains>
322 </LLDASH>
323 <!--
324 <Thumbnail>
325 <CrossDomains>
326 <Url>*</Url>
327 </CrossDomains>
328 </Thumbnail>
329 -->
330 </Publishers>
331 </Application>
332 </Applications>
333 </VirtualHost>
334 </VirtualHosts>
335 </Server>

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:

1 <Server>
2 ...
3 <Bind>
4 <Providers>
5 <RTMP>
6 <Port>1935</Port>
7 </RTMP>
8 </Providers>
9 </Bind>
10 ...
11 <VirtualHosts>
12 <VirtualHost>
13 <Application>
14 <Providers>
15 <RTMP>
16 ...
17 </RTMP>
18 ...
19 </Providers>
20 <Application>
21 </VirtualHost>
22 </VirtualHosts>
23 </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 :

1 <Application>
2 <Providers>
3 <RTMP>
4 <BlockDuplicateStreamName>true</BlockDuplicateStreamName>
5 </RTMP>
6 </Providers>
7 <Application>

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


<BlockDuplicateStreamName> works with the following rules:

Value Description

Default Rejects the new stream inputted as


true
overlap and maintains the existing stream.

Accepts a new stream inputted as overlap and


false
disconnects the existing stream.

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.

Streaming URL

If you use the default configuration, you can stream with the following streaming URLs when you start
broadcasting to OBS:

WebRTC ws://192.168.0.1:3333/app/stream

HLS http://192.168.0.1:8080/app/stream/playlist.m3u8

MPEG-DASH http://192.168.0.1:8080/app/stream/manifest.mpd

WebRTC (Beta)

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

In order for OvenMediaEngine to receive streams through WebRTC, web socket-based signaling port and
ICE candidate must be set. The ICE candidate can configure a TCP relay. WebRTC provider and WebRTC
publisher can use the same port. Ports of WebRTC provider can be set in as follows.

1 <Bind>
2 <Providers>
3 ...
4 <WebRTC>
5 <Signalling>
6 <Port>3333</Port>
7 </Signalling>
8 <IceCandidates>
9 <TcpRelay>*:3478</TcpRelay>
10 <IceCandidate>*:10006-10010/udp</IceCandidate>
11 </IceCandidates>
12 </WebRTC>
13 </Providers>

Application

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

1 <Applications>
2 <Application>
3 <Name>app</Name>
4 <Providers>
5 <WebRTC />

URL Pattern
The signaling url for WebRTC input uses the query string(?direction=send) as follows to distinguish it from
the url for WebRTC playback.

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

When WebRTC transmission starts, a stream is created with under application.

WebRTC over TCP

WebRTC transmission is sensitive to packet loss because it affects all players who access the stream.
Therefore, it is recommended to provide WebRTC transmission over TCP. OvenMediaEngine has a built-in
TURN server for WebRTC/TCP, and receives or transmits streams using the TCP session that the player's
TURN client connects to the TURN server as it is. To use WebRTC/TCP, use transport=tcp query string as in
WebRTC playback. See WebRTC/tcp playback for more information.

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

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


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.

OvenPlayer
The getUserMedia API to access the local device only works in a secure context. So, the WebRTC
Input demo page can only work on the https site https://demo.ovenplayer.com/demo_input.html.
This means that due to mixed content you have to install the certificate in OvenMediaEngine and
use the signaling URL as wss to test this. If you can't install the certificate in OvenMediaEngine,
you can temporarily test it by allowing the insecure content of the demo.ovenplayer.com URL in
your browser.

Custom WebRTC Producer

To create a custom WebRTC Producer, you need to implement OvenMediaEngine's Signaling Protocol. The
protocol is structured in a simple format and uses the same method as WebRTC Streaming.

When the player connects to ws[s]://host:port/app/stream?direction=send through a web socket and sends
a request offer command, the server responds to the offer sdp. If transport=tcp exists in the query string of the
URL, iceServers information is included in offer sdp, which contains the information of OvenMediaEngine's
built-in TURN server, so you need to set this in RTCPeerConnection to use WebRTC/TCP. The player then
setsRemoteDescription and addIceCandidate offer sdp, generates an answer sdp, and responds to the
server

SRT (Beta)

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:

1 <Bind>

2 <Providers>
3 ...
4 <SRT>
5 <Port>9999</Port>
6 <!-- <WorkerCount>1</WorkerCount> -->
7 </SRT>
8 </Providers>

Application

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

1 <Applications>
2 <Application>
3 <Name>app</Name>
4 <Providers>
5 <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]")

The streamid contains the URL format, so it must be percent encoded

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, you
can leave the Stream Key blank.

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

From version 0.10.4, MPEG-2 TS input is supported as a beta version. 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.

This version supports MPEG-2 TS over UDP. MPEG-2 TS over TCP or MPEG-2 TS over SRT will
be supported soon.

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.

1 <Server>
2 ...
3 <Bind>
4 <Providers>
5 <MPEGTS>
6 <!--
7 Listen on port 4000,4001,4004,4005
8 This is just a demonstration to show that you can c
9 -->
10 <Port>4000-4001,4004,4005/udp</Port>
11 </MPEGTS>
12 </Providers>
13 </Bind>
14 ...
15 <VirtualHosts>
16 <VirtualHost>
17 <Application>
18 <Providers>
19 <MPEGTS>
20 <StreamMap>
21 <!--
22 Set the stream name
23 For example, if a c
24 -->
25 <Stream>
26 <Name>stream_${Port
27 <Port>4000-4001,400
28 </Stream>
29 <Stream>
30 <Name>stream_name_f
31 <Port>4005</Port>
32 </Stream>
33 </StreamMap>
34 </MPEGTS>
35 </Providers>
36 <Application>
37 </VirtualHost>
38 </VirtualHosts>
39 </Server>

Publish
This is an example of publishing using FFMPEG.

1 # Video / Audio
2 ffmpeg.exe -re -stream_loop -1 -i <file.ext> -c:v libx264 -bf 0 -x264-params keyint=30:scen
3 # Video only
4 ffmpeg.exe -re -stream_loop -1 -i <file.ext> -c:v libx264 -bf 0 -x264-params keyint=30:scen
5 # Audio only
6 ffmpeg.exe -re -stream_loop -1 -i <file.ext> -vn -acodec aac -pes_payload_size 0 -f mpegts

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.

Streaming URL

If you use the default configuration, you can stream with the following streaming URLs when you start
broadcasting to OBS:
WebRTC ws://192.168.0.1:3333/app/stream_4000

HLS http://192.168.0.1:8080/app/stream_4000/playlist.m3u8

MPEG-DASH http://192.168.0.1:8080/app/stream_4000/manifest.mpd

RTSP Pull

From version 0.10.4, RTSP Pull input is supported as a beta version. The supported codecs are H.264,
AAC(ADTS). Supported codecs will continue to be added.

This function pulls a stream from an external RTSP server and operates as an RTSP client.

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.

1 <VirtualHosts>
2 <VirtualHost include="VHost*.xml" />
3 <VirtualHost>
4 <Name>default</Name>
5
6 <Host>
7 <Names>
8 <!-- Host names
9 <Name>stream1.airensoft.com</Name>
10 <Name>stream2.airensoft.com</Name>
11 <Name>*.sub.airensoft.com</Name>
12 <Name>192.168.0.1</Name>
13 -->
14 <Name>*</Name>
15 </Names>
16 <!--
17 <TLS>
18 <CertPath>path/to/file.crt</CertPath>
19 <KeyPath>path/to/file.key</KeyPath>
20 <ChainCertPath>path/to/file.crt</ChainCertPath>
21 </TLS>
22 -->
23 </Host>
24
25 <Origins>
26 <Origin>
27 <Location>/app_name/rtsp_stream_name</Location>
28 <Pass>
29
29
<Scheme>rtsp</Scheme>
30 <Urls><Url>192.168.0.200:554/</Url></Urls>
31 </Pass>
32 </Origin>
33 </Origins>
34 </VirtualHost>
35 </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.

Publish

The pull-type provider is activated by the publisher's streaming request. And if there is no client playing for
30 seconds, the provider is automatically disabled.

According to the above setting, the RTSP pull provider operates for the following streaming URLs.

Protocol URL

WebRTC ws:://ome.com:3333/app_name/rtsp_stream_nam

http://ome.com:8080/app_name/rtsp_stream_nam
HLS
playlist.m3u8

http://ome.com:8080/app_name/rtsp_stream_nam
DASH
manifest.mpd

http://ome.com:8080/app_name/rtsp_stream_nam
LL DASH
manifest_ll.mpd

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


OvenMediaEngine currently supports the following codecs:

Video Audio
Video Decoding Audio Decoding Image Encoding
Encoding Encoding

H.264
H.264 (Baseline) AAC AAC JPEG
(Baseline)

VP8 Opus PNG

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.

1 <OutputProfiles>
2 <OutputProfile>
3 <Name>bypass_stream</Name>
4 <OutputStreamName>${OriginStreamName}_bypass</OutputStreamName>
5 <Encodes>
6 <Audio>
7 <Bypass>true</Bypass>
8 </Audio>
9 <Video>
10 <Bypass>true</Bypass>
11 </Video>
12 <Audio>
13 <Codec>opus</Codec>
14 <Bitrate>128000</Bitrate>
15 <Samplerate>48000</Samplerate>
16 <Channel>2</Channel>
17 </Audio>
18 </Encodes>
19 </OutputProfile>
20 </OutputProfiles>

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

WebRTC ws://192.168.0.1:3333/app/ stream_bypass

HLS http://192.168.0.1:8080/app/`stream_bypass`/playlist.m3u8
MPEG-DASH http://192.168.0.1:8080/app/`stream_bypass`/manifest.mpd
Low-Latency MPEG-DASH http://192.168.0.1:8080/app/`stream_bypass`/manifest_ll.mpd

Encodes

Video

You can set the video profile as below:

1 <Encodes>
2 <Video>
3 <Codec>vp8</Codec>
4 <Width>1280</Width>
5 <Height>720</Height>
6 <Bitrate>2000000</Bitrate>
7 <Framerate>30.0</Framerate>
8 <Preset>fast</Preset>
9 </Video>
10 </Encodes>

The meaning of each property is as follows:

Property Description

Codec Specifies the vp8 or h264 codec to use

Width Width of resolution

Height Height of resolution

Bitrate Bit per second

Framerate Frames per second

Preset Presets of encoding quality and performance

Table of presets

A table in which presets provided for each codec library are mapped to OvenMediaEngine's 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.

Presets x264/x265 libvpx h264/265 NVC h264/265 QSV

slower slower best hq -

slow slow best llhq -

medium medium good bd -


fast fast realtime hp -

faster *faster *realtime *llhp -

References

https://trac.ffmpeg.org/wiki/Encode/H.264
https://x265.readthedocs.io/en/stable/presets.html

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:

1 <Encodes>
2 <Audio>
3 <Codec>opus</Codec>
4 <Bitrate>128000</Bitrate>
5 <Samplerate>48000</Samplerate>
6 <Channel>2</Channel>
7 </Audio>
8 </Encodes>

The meaning of each property is as follows:

Property Description

Codec Specifies the opus or aac codec to use

Bitrates Bits per second

Samplerate Samples per second

Channel The number of audio channels

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:

1 <Encodes>
2 <Image>
3 <Codec>jpeg</Codec>
4 <Width>1280</Width>
5 <Height>720</Height>
6
7 <Framerate>1</Framerate>
</Image>
8 </Encodes>

The meaning of each property is as follows:

Property Description

Codec Specifies the jpeg or png codec to use

Width Width of resolution

Height Height of resolution

Framerate Frames per second

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:

1 <Video>
2 <Bypass>true</Bypass>
3 </Video>
4 <Audio>
5 <Bypass>true</Bypass>
6 </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.

1 <Encodes>
2 <Video>
3 <Bypass>true</Bypass>
4 </Video>
5 <Audio>
6 <Codec>opus</Codec>
7 <Bitrate>128000</Bitrate>
8 <Samplerate>48000</Samplerate>
9 <Channel>2</Channel>
10 </Audio>
11
11
</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.

1 <Encodes>
2 <Video>
3 <Codec>vp8</Codec>
4 <Bitrate>2000000</Bitrate>
5 </Video>
6 <Audio>
7 <Codec>opus</Codec>
8 <Bitrate>128000</Bitrate>
9 </Audio>
10 <Image>
11 <Codec>jpeg</Codec>
12 </Image>
13 </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.

1 <Encodes>
2 <Video>
3 <Codec>h264</Codec>
4 <Bitrate>2000000</Bitrate>
5 <Width>1280</Width>
6 <!-- Height is automatically calculated as the original video ratio -->
7 <Framerate>30.0</Framerate>
8 </Video>
9 <Video>
10 <Codec>h264</Codec>
11 <Bitrate>2000000</Bitrate>
12 <!-- Width is automatically calculated as the original video ratio -->
13 <Height>720</Height>
14 <Framerate>30.0</Framerate>
15 </Video>
16 </Encodes>
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:

Protocol Supported Codec

WebRTC VP8, H.264, Opus

HLS H.264, AAC

Low-Latency MPEG-Dash H.264, AAC

Therefore, you set it up as shown in the table. If you want to stream using HLS or MPEG-DASH, 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.

Currently, OME doesn't support adaptive streaming on HLS, MPEG-DASH. However, it will be
updated soon.

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.

Reference

Quick Sync Video format support: https://en.wikipedia.org/wiki/Intel_Quick_Sync_Video


Install GPU Driver

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.

1 (curl -LOJ https://github.com/AirenSoft/OvenMediaEngine/archive/master.tar.gz && tar xvfz O


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

1 # Use the samples provided in the Intel Media SDK


2 # Check the list of codecs supported by iGPU
3 /MediaSDK-intel-mediasdk-21.1.2/build/__bin/release/simple_7_codec

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.

1 (curl -LOJ https://github.com/AirenSoft/OvenMediaEngine/archive/master.tar.gz && tar xvfz O


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

1 $ nvidia-smi
2
3 Thu Jun 17 10:20:23 2021
4 +-----------------------------------------------------------------------------+
5 | NVIDIA-SMI 465.19.01 Driver Version: 465.19.01 CUDA Version: 11.3 |
6 |-------------------------------+----------------------+----------------------+
7 | GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC |
8 | Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. |
9 | | | MIG M. |
10 |===============================+======================+======================|
11 | 0 NVIDIA GeForce ... Off | 00000000:01:00.0 Off | N/A |
12 | 20% 35C P8 N/A / 75W | 156MiB / 1997MiB | 0% Default |
13 | | | N/A |
14 +-------------------------------+----------------------+----------------------+

15
16 +-----------------------------------------------------------------------------+
17 | Processes: |
18 | GPU GI CI PID Type Process name GPU Memory |
19 | ID ID Usage |
20 |=============================================================================|
21 | 0 N/A N/A 1589 G /usr/libexec/Xorg 38MiB |
22 | 0 N/A N/A 1730 G /usr/bin/gnome-shell 115MiB |
23 +-----------------------------------------------------------------------------+

Container Toolkit for Docker

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.

Reference : https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/overview.html

1 OvenMediaEngine-master/misc/install_nvidia_docker_container.sh
The NVIDIA Driver must have been previously installed

How to run docker

To use GPU when running Docker, you need to add the --gpus all option.

1 docker run -d \

2 -p 1935:1935 -p 4000-4005:4000-4005/udp -p 3333:3333 -p 3478:3478 -p 8080:8080 -p 9000:9000


3 --gpus all
4 airensoft/ovenmediaengine:dev

Manual Installation

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

Manual Installation

Prerequisites Additional Options


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.

When using NVIDIA Driver

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

When using Intel QuickSync Driver

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

When using Docker container

1 docker build --file Dockerfile.nv -t airensoft/ovenmediaengine:dev .


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.

1 <VirtualHosts>
2 <VirtualHost>
3 <Name>default</Name>
4
5 <!-- Settings for multi domain and TLS -->
6 <Host>
7 ...
8 </Host>
9
10 <!-- Settings for applications -->
11 <Applications>
12 <Application>
13 <Name>app</Name>
14 <Type>live</Type>
15 <OutputProfiles>
16 <!-- Settings to use ha
17 <HardwareAc
18 <OutputProf
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38 </OutputPro
39
40 </OutputProfiles>
41 <Providers>
42 ...
43 </Providers>
44 <Publishers>
45 ...
46 </Publishers>
47 </Application>
48 </Applications>
49 </VirtualHost>
50 </VirtualHosts>

Configuration

Build & Run


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

Ubuntu 18+

1 sudo apt-get update


2 cd OvenMediaEngine-master/src
3 make release
4 sudo make install
5 systemctl start ovenmediaengine
6 # If you want automatically start on boot
7 systemctl enable ovenmediaengine.service

Fedora 28+

1 sudo dnf update


2 cd OvenMediaEngine-master/src
3 make release
4 sudo make install
5 systemctl start ovenmediaengine
6 # If you want automatically start on boot
7 systemctl enable ovenmediaengine.service

CentOS 7+

1 sudo yum update


2 source scl_source enable devtoolset-7
3
3
4 cd OvenMediaEngine-master/src
make release
5 sudo make install
6 systemctl start ovenmediaengine
7 # If you want automatically start on boot
8 systemctl enable ovenmediaengine.service

Getting Started

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.

Device H264 H265 VP8 VP9

QuickSync D/E D/E - -

NVIDIA D/E D/E - -

Docker on
NVIDIA D/E D/E - -
Container Toolkit

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
Manual Installation

Intel QuickSync Driver Installation

Platform Specific Installation

Ubuntu 18/20

1 sudo apt install -y libdrm-dev xorg xorg-dev openbox libx11-dev


2 sudo apt install -y libgl1-mesa-glx libgl1-mesa-dev

CentOS 7

1 # Centos 7 uses the 2.8.x version of cmake by default.


2 # It must be changed to version 3.x or higher.
3 sudo yum remove -y cmake
4 sudo yum install -y cmake3
5 sudo ln -s /usr/bin/cmake3 /usr/bin/cmake
6
7 sudo yum install -y libdrm-devel libX11-devel libXi-devel

CentOS 8

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

Common Installation

LibVA

1 PREFIX=/opt/ovenmediaengine && \
2
2
3 TEMP_PATH=/tmp && \ && \
LIBVA_VERSION=2.11.0
4 DIR=${TEMP_PATH}/libva && \
5 mkdir -p ${DIR} && \
6 cd ${DIR} && \

7 curl -sLf https://github.com/intel/libva/archive/refs/tags/${LIBVA_VERSION}.tar.gz | tar -x


8 ./autogen.sh --prefix="${PREFIX}" && \
9 make -j$(nproc) && \
10 sudo make install && \
11 rm -rf ${DIR})

GMMLIB

1 PREFIX=/opt/ovenmediaengine && \
2 TEMP_PATH=/tmp && \
3 GMMLIB_VERSION=20.4.1 && \
4 DIR=${TEMP_PATH}/gmmlib && \
5 mkdir -p ${DIR} && \
6 cd ${DIR} && \
7 curl -sLf https://github.com/intel/gmmlib/archive/refs/tags/intel-gmmlib-${GMMLIB_VERSION}
8 mkdir -p ${DIR}/build && \
9 cd ${DIR}/build && \
10 cmake -DCMAKE_INSTALL_PREFIX="${PREFIX}" .. && \
11 make -j$(nproc) && \
12 sudo make install && \
13 rm -rf ${DIR}

Intel Media Driver

1 PREFIX=/opt/ovenmediaengine && \
2 TEMP_PATH=/tmp && \
3 INTEL_MEDIA_DRIVER_VERSION=20.4.5 && \
4 DIR_IMD=${TEMP_PATH}/media-driver && \
5 mkdir -p ${DIR_IMD} && \
6 cd ${DIR_IMD} && \
7 curl -sLf https://github.com/intel/media-driver/archive/refs/tags/intel-media-${INTEL_MEDIA
8 DIR_GMMLIB=${TEMP_PATH}/gmmlib && \
9 mkdir -p ${DIR_GMMLIB} && \
10 cd ${DIR_GMMLIB} && \
11 curl -sLf https://github.com/intel/gmmlib/archive/refs/tags/intel-gmmlib-${GMMLIB_VERSION}
12 DIR=${TEMP_PATH}/build && \
13 mkdir -p ${DIR} && \
14 cd ${DIR} && \
15 PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig:${PKG_CONFIG_PATH} cmake \
16 $DIR_IMD \
17 -DBUILD_TYPE=release \
18 -DBS_DIR_GMMLIB="$DIR_GMMLIB/Source/GmmLib" \
19 -DBS_DIR_COMMON=$DIR_GMMLIB/Source/Common \
20 -DBS_DIR_INC=$DIR_GMMLIB/Source/inc \
21
21
-DBS_DIR_MEDIA=$DIR_IMD \
22 -DCMAKE_INSTALL_PREFIX=${PREFIX} \
23 -DCMAKE_INSTALL_LIBDIR=${PREFIX}/lib \
24 -DINSTALL_DRIVER_SYSCONF=OFF \
25 -DLIBVA_DRIVERS_PATH=${PREFIX}/lib/dri && \

26 sudo make -j$(nproc) install && \


27 rm -rf ${DIR} && \
28 rm -rf ${DIR_IMD} && \
29 rm -rf ${DIR_GMMLIB}
30
31 export LIBVA_DRIVERS_PATH=${PREFIX}/lib
32 export LIBVA_DRIVER_NAME=iHD

Intel Media SDK

1 PREFIX=/opt/ovenmediaengine && \
2 TEMP_PATH=/tmp && \
3 INTEL_MEDIA_SDK_VERSION=20.5.1 && \
4 DIR=${TEMP_PATH}/medka-sdk && \
5 mkdir -p ${DIR} && \
6 cd ${DIR} && \
7 curl -sLf https://github.com/Intel-Media-SDK/MediaSDK/archive/refs/tags/intel-mediasdk-${IN
8 mkdir -p ${DIR}/build && \
9 cd ${DIR}/build && \
10 PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig:${PKG_CONFIG_PATH} cmake -DCMAKE_INSTALL_PREFIX="${
11 make -j$(nproc) && \
12 sudo make install && \
13 rm -rf ${DIR}

All libraries are installed, the system must be rebooted.

NVIDIA Driver Installation

Platform Specific Installation

Ubuntu 18/20

1 # Uninstalling a previously installed NVIDIA Driver


2 sudo apt-get remove --purge nvidia-*
3 sudo apt-get -y autoremove
4 sudo apt-get -y update
5
6
7 # Remove the nouveau
USE_NOUVEAU=`sudo driver.
lshw -classIf the nouveau
video driver is in use, the nvidia driver cann
| grep nouveau`
8 if [ ! -z "$USE_NOUVEAU" ]; then
9
10 # Disable nouveau Driver
11 echo "blacklist nouveau" >> /etc/modprobe.d/blacklist.conf
12 echo "blacklist lbm-nouveau" >> /etc/modprobe.d/blacklist.conf
13 echo "options nouveau modeset=0" >> /etc/modprobe.d/blacklist.conf
14 echo "alias nouveau off" >> /etc/modprobe.d/blacklist.conf
15 echo "alias lbm-nouveau off" >> /etc/modprobe.d/blacklist.conf
16 sudo update-initramfs -u
17 echo "Using a driver display nouveau.Remove the driver and reboot.Reboot and
18
19 sleep 5s
20 reboot
21 fi
22
23 # Install Nvidia Driver and Nvidia Toolkit
24 sudo add-apt-repository ppa:graphics-drivers/ppa
25 sudo apt -y update
26 sudo apt-get install -y $(ubuntu-drivers devices | grep recommended | awk '{print $3
27 sudo apt-get install -y nvidia-cuda-toolkit curl make

CentOS 7

1 # Update Kernel
2 yum -y update
3 yum -y groupinstall "Development Tools"
4 yum -y install kernel-devel
5 yum -y install epel-release
6 yum -y install dkms curl
7 echo "Reboot is required to run with a new version of the kernel."
8
9 # Remove the nouveau driver. If the nouveau driver is in use, the nvidia driver cann
10 USE_NOUVEAU=`sudo lshw -class video | grep nouveau`
11 if [ ! -z "$USE_NOUVEAU" ]; then
12
13 # Disable nouveau Driver
14 sed "s/GRUB_CMDLINE_LINUX=\"\(.*\)\"/GRUB_CMDLINE_LINUX=\"\1 rd.driver.black
15 grub2-mkconfig -o /boot/grub2/grub.cfg
16 echo "blacklist nouveau" >> /etc/modprobe.d/blacklist.conf
17 mv /boot/initramfs-$(uname -r).img /boot/initramfs-$(uname -r)-nouveau.img
18 dracut /boot/initramfs-$(uname -r).img $(uname -r)
19
20 echo "Using a driver display nouveau. so, remove the driver and reboot. "
21 echo "After reboot and installation script to rerun the nvidia display the d
22
23 sleep 5s
24 reboot
25 fi
26
27 # Install Nvidia Driver
28 # https://www.nvidia.com/en-us/drivers/unix/
29 systemctl isolate multi-user.target
30 wget -N https://us.download.nvidia.com/XFree86/Linux-x86_64/460.84/NVIDIA-Linux-x86_
31 sh ./NVIDIA-Linux-x86_64-460.84.run --ui=none --no-questions
32
33 # Install Nvidia Toolkit
34 # https://developer.nvidia.com/cuda-downloads
35 wget -N https://developer.download.nvidia.com/compute/cuda/11.3.1/local_installers/c
36 sh cuda_11.3.1_465.19.01_linux.run --silent
37
38 # Configure Envionment Variables
39 echo "Please add the PATH below to the environment variable."
40 echo ""
41 echo "export PATH=${PATH}:/usr/local/cuda/bin/"
42 echo ""
43 export PATH=${PATH}:/usr/local/cuda/bin/

CentOS 8

1 dnf update -y
2 dnf groupinstall -y "Development Tools"
3 dnf install -y elfutils-libelf-devel "kernel-devel-uname-r == $(uname -r)"
4
5 # Remove the nouveau driver. If the nouveau driver is in use, the nvidia driver cann
6 USE_NOUVEAU=`sudo lshw -class video | grep nouveau`
7 if [ ! -z "$USE_NOUVEAU" ]; then
8
9 # Disable nouveau Driver
10 echo "blacklist nouveau" >> /etc/modprobe.d/blacklist.conf
11 mv /boot/initramfs-$(uname -r).img /boot/initramfs-$(uname -r)-nouveau.img
12 dracut /boot/initramfs-$(uname -r).img $(uname -r)
13
14 systemctl set-default multi-user.target
15 systemctl get-default
16
17 echo "Using a driver display nouveau. so, remove the driver and reboot. "
18 echo "After reboot and installation script to rerun the nvidia display the d
19
20 sleep 5s
21 reboot
22 fi
23
24 wget -N https://us.download.nvidia.com/XFree86/Linux-x86_64/460.84/NVIDIA-Linux-x86_
25 sh ./NVIDIA-Linux-x86_64-460.84.run --ui=none --no-questions
26
27 # Install Nvidia Toolkit
28 # https://developer.nvidia.com/cuda-downloads
29 wget -N https://developer.download.nvidia.com/compute/cuda/11.3.1/local_installers/c
30
30
sh cuda_11.3.1_465.19.01_linux.run --silent
31
32 systemctl set-default graphical.target
33 systemctl get-default
34

35 # Configure Envionment Variables


36 echo "Please add the PATH below to the environment variable."
37 echo ""
38 echo "export PATH=${PATH}:/usr/local/cuda/bin/"
39 echo ""
40 export PATH=${PATH}:/usr/local/cuda/bin/

Common Installation

NVCC Headers

1 PREFIX=/opt/ovenmediaengine && \
2 TEMP_PATH=/tmp && \
3 NVCC_HEADERS=11.0.10.1 && \
4 DIR=${TEMP_PATH}/nvcc-hdr && \
5 mkdir -p ${DIR} && \
6 cd ${DIR} && \
7 curl -sLf https://github.com/FFmpeg/nv-codec-headers/releases/download/n${NVCC_HEADERS}/nv-
8 sudo make install && \
9 rm -rf ${DIR}

NVIDIA Container Toolkit Installation

Platform Specific Installation

Ubuntu 18/20

1 # Install Docker 2.x


2 curl https://get.docker.com && sudo systemctl --now enable docker
3
4 # Install NVIDIA Docker Toolkit
5 distribution=$(. /etc/os-release;echo $ID$VERSION_ID) && \
6 curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - && \
7 curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list |
8
9 sudo apt-get update
10 sudo apt-get install -y nvidia-docker2
11
11
12 # Restart Docker
13 sudo systemctl restart docker
14
15 # Test

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

CentOS 7

1 sudo yum install -y yum-utils


2 sudo yum-config-manager --add-repo=https://download.docker.com/linux/centos/docker-c
3 sudo yum repolist -v
4 sudo yum install -y https://download.docker.com/linux/centos/7/x86_64/stable/Package
5 sudo yum install docker-ce -y
6 sudo systemctl --now enable docker
7
8 # Install NVIDIA Docker Toolkit
9 distribution=$(. /etc/os-release;echo $ID$VERSION_ID) && \
10 curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.repo |
11
12 if [[ "${OSVERSION}" == "7" ]]; then
13 sudo yum clean expire-cache
14 sudo yum install -y nvidia-docker2
15 elif [[ "${OSVERSION}" == "8" ]]; then
16 sudo dnf clean expire-cache --refresh
17 sudo dnf install -y nvidia-docker2
18 else
19 fail_exit
20 fi
21
22 # Restart Docker
23 sudo systemctl restart docker
24
25 # Test
26 sudo docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi
27

CentOS 8

1 sudo dnf install -y dnf-utils


2 sudo dnf config-manager --add-repo=https://download.docker.com/linux/centos/docker-c
3 sudo dnf repolist -v
4 sudo dnf install -y https://download.docker.com/linux/centos/7/x86_64/stable/Package
5 sudo dnf install docker-ce -y
6 sudo systemctl --now enable docker
7
8
8
# Install NVIDIA Docker Toolkit
9 distribution=$(. /etc/os-release;echo $ID$VERSION_ID) && \
10 curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.repo |
11
12 if [[ "${OSVERSION}" == "7" ]]; then
13 sudo yum clean expire-cache
14 sudo yum install -y nvidia-docker2
15 elif [[ "${OSVERSION}" == "8" ]]; then
16 sudo dnf clean expire-cache --refresh
17 sudo dnf install -y nvidia-docker2
18 else
19 fail_exit
20 fi
21
22 # Restart Docker
23 sudo systemctl restart docker
24
25 # Test
26 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

Delivery RTP / RTCP

Security DTLS, SRTP

Connectivity ICE

Error Correction ULPFEC (VP8, H.264), In-band FEC (Opus)

Codec VP8, H.264, Opus

Self-Defined Signalling Protocol and Embedded


Signalling
Web Socket-Based Server
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.

1 <Bind>
2 <Publishers>
3 <WebRTC>
4 <Signalling>
5 <Port>3333</Port>
6 </Signalling>
7 <IceCandidates>
8 <TcpRelay>*:3478</TcpRelay>
9 <IceCandidate>*:10000-10005/udp</IceCandidate>
10 </IceCandidates>
11 </WebRTC>
12 </Publishers>
13 </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.

1 <Server version="7">
2 <VirtualHosts>
3 <VirtualHost>
4 <Applications>
5 <Application>
6 <Publishers>
7 <WebRTC>
8 <Timeout>30000</Timeout>
9 <Rtx>false</Rtx>
10 <Ulpfec>false</Ulpfec>
11 <JitterBuffer>false</JitterBuffer>
12 </WebRTC>
13 </Publishers>
14 </Application>
15 </Applications>
16 </VirtualHost>
17 </VirtualHosts>
18 </Server>
Option Description Default

ICE (STUN request/response)


timeout as milliseconds, if there

Timeout is no request or response during 30000


this time, the session is
terminated.

WebRTC retransmission, a
Rtx useful option in WebRTC/udp, false
but ineffective in WebRTC/tcp.

WebRTC forward error


correction, a useful option in
Ulpfec false
WebRTC/udp, but ineffective in
WebRTC/tcp.

Audio and video are interleaved


JitterBuffer and output evenly, see below for false
details

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.

1 <OutputProfiles>
2 <OutputProfile>
3 <Name>bypass_stream</Name>
4 <OutputStreamName>${OriginStreamName}</OutputStreamName>
5 <Encodes>
6 <Audio>
7
7
<Bypass>true</Bypass>
8 </Audio>
9 <Video>
10 <Bypass>true</Bypass>
11 </Video>
12 <Video>
13 <!-- vp8, h264 -->
14 <Codec>vp8</Codec>
15 <Width>1280</Width>
16 <Height>720</Height>
17 <Bitrate>2000000</Bitrate>
18 <Framerate>30.0</Framerate>
19 </Video>
20 <Audio>
21 <Codec>opus</Codec>
22 <Bitrate>128000</Bitrate>
23 <Samplerate>48000</Samplerate>
24 <Channel>2</Channel>
25 </Audio>
26 </Encodes>
27 </OutputProfile>
28 </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:

Protocol URL format

ws://<Server IP>[:<Signalling Port]/<Application


WebRTC Signalling
name>/<Stream name>

wss://<Server IP>[:<Signalling Port]/<Application


Secure WebRTC Signalling
name>/<Stream name>

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.

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.

1 <Server version="8">
2 ...
3 <StunServer>stun.l.google.com:19302</StunServer>
4 <Bind>
5 <Publishers>
6 <WebRTC>
7 ...
8 <IceCandidates>
9 <!-- <TcpRelay>*:3478</TcpRelay> -->
10 <TcpRelay>Relay IP:Port</TcpRelay>
11 <TcpForce>false</TcpForce>
12 <IceCandidate>*:10000-10005/udp</IceCandida
13 </IceCandidates>
14 </WebRTC>
15 </Publishers>
16 </Bind>
17 ...

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.

1 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:

1 myPeerConnection = new RTCPeerConnection({


2 iceServers: [
3 {
4 urls: "turn:Relay IP:Port?transport=tcp",
5 username: "ome",
6 credential: "airen"
7 }
8 ]
9 });

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.

1 candidates: [{candidate: "candidate:0 1 UDP 50 192.168.0.200 10006 typ host", sdpMLineIndex


2 code: 200
3 command: "offer"
4 ice_servers: [{credential: "airen", urls: ["turn:192.168.0.200:3478?transport=tcp"], user_n
5 id: 506764844
6 peer_id: 0
7 sdp: {,…}
Low-Latency DASH and HLS streaming

OvenMediaEngine supports HTTP based streaming protocols such as HLS, MPEG-DASH(Hereafter


DASH), and Low-Latency MPEG-DASH with CMAF(Hereafter LLDASH).

Title Functions

HTTP for HLS and DASH


Delivery
HTTP 1.1 chunked transfer for LLDash

Security TLS (HTTPS)

TS for HLS
Format ISOBMFF for DASH
CMAF for LLDASH

Codec H.264, AAC

OvenMediaEngine will support Low-Latency HLS in the near future. We are always keeping an
eye on the decision from Apple inc.

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

1 <Server version="8">
2 <Bind>
3 <Publishers>
4 <HLS>
5 <Port>80</Port>
6 </HLS>
7 <DASH>
8 <Port>80</Port>
9 </DASH>
10 </Publishers>
11 </Bind>
12 <VirtualHosts>
13 <VirtualHost>
14 <Applications>
15 <Application>
16 <Publishers>
17 <HLS>
18
19 <SegmentDuration>5</SegmentDuration>
<SegmentCount>3</SegmentCount>
20 <CrossDomains>
21 <Url>*<Url>
22 </CrossDomains>
23 </HLS>
24 <DASH>
25 <SegmentDuration>5</SegmentDuration>
26 <SegmentCount>3</SegmentCount>
27 <CrossDomains>
28 <Url>*<Url>
29 </CrossDomains>
30 </DASH>
31 <LLDASH>
32 <SegmentDuration>5</SegmentDuration>
33 <CrossDomains>
34 <Url>*<Url>
35 </CrossDomains>
36 </LLDASH>
37 </Publishers>
38 </Application>
39 </Applications>
40 </VirtualHost>
41 </VirtualHosts>
42 </Server>

Element Decscription

Set the HTTP port to provide HLS and DASH.


LLDASH and DASH are provided on the same
Bind
port, and DASH and HLS can be set to the same
port.

Set the length of the segment in seconds. The


shorter the <SegmentDuration> , the lower
SegmentDuration latency can be streamed, but it is less stable durin
streaming. Therefore, we are recommended to se
to 3 to 5 seconds.

Set the number of segments to be exposed to


*.mpd . The smaller the number of
<SegmentCount> , the lower latency can be
streamed, but it is less reliable during streaming.
SegmentCount
Therefore, it is recommended to set this value to 3
It doesn't need to set SegmentCount for LLDASH
because LLDASH only has one segment on
OvenMediaEngine.

Control the domain in which the player works


CrossDomains through <CorssDomain> . For more information
please refer to the CrossDomain section.
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.

Server.xml
1 <CrossDomains>
2 <Url>*</Url>
3 <Url>*.airensoft.com</Url>
4 <Url>http://*.ovenplayer.com</Url>
5 <Url>https://demo.ovenplayer.com</Url>
6 </CrossDomains>

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

Url Value Description

* Allows requests from all Domains

Allows both HTTP and HTTPS requests from the


domain
specified Domain

http://domain Allows HTTP requests from the specified Domain

https://domain Allows HTTPS requests from the specified Doma

Streaming
LLDASH, DASH, and HLS Streaming are ready when a live source is inputted and a stream is created.
Viewers can stream using OvenPlayer or other players.

Also, you need to set H.264 and AAC in the Transcoding profile because MPEG-DASH and HLS use these
codecs.

1 <OutputProfiles>
2 <OutputProfile>
3 <Name>bypass_stream</Name>
4 <OutputStreamName>${OriginStreamName}</OutputStreamName>
5 <Encodes>
6 <Audio>
7 <Bypass>true</Bypass>
8 </Audio>
9 <Video>
10 <Bypass>true</Bypass>
11 </Video>
12 </Encodes>
13 </OutputProfile>
14 </OutputProfiles>

When you create a stream, as shown above, you can play LLDASH, DASH, and HLS through OvenPlayer
with the following URL:

Protocol URL format

http://<Server IP>[:<DASH
LLDASH Port>]/<Application Name>/<Stream
Name>/manifest_ll.mpd

https://<Domain>[:<DASH
Secure LLDASH TLSPort>]/<Application Name>/<Strea
Name>/manifest_ll.mpd

http://<Server IP>[:<DASH
DASH Port>]/<Application Name>/<Stream
Name>/manifest.mpd

https://<Domain>[:<DASH
Secure DASH TLSPort>]/<Application Name>/<Strea
Name>/manifest.mpd

http://<Server IP>[:<HLS
HLS Port>]/<Application Name>/<Stream
Name>/playlist.m3u8

https://<Domain>[:<HLS
Secure HLS TLSPort>]/<Application Name>/<Strea
Name>/playlist.m3u8

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

https://[OvenMediaEngine IP]:443/app/<stream name>_o/playlist.m3u8

http://[OvenMediaEngine IP]:80/app/<stream name>_o/playlist.m3u8

https://[OvenMediaEngine IP]:443/app/<stream name>_o/manifest.mpd

http://[OvenMediaEngine IP]:80/app/<stream name>_o/manifest.mpd

https://[OvenMediaEngine IP]:443/app/<stream name>_o/manifest_ll.mpd

http://[OvenMediaEngine IP]:80/app/<stream name>_o/manifest_ll.mpd

We have prepared a test player that you can quickly see if OvenMediaEngine is working. Please refer to the
Test Player for more information.

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, only HLS, DASH, and WebRTC Signaling support
TLS.

1 <Bind>
2 ...
3
4 <Publishers>
5 ...
6 <HLS>
7 <Port>80</Port>
8 <TLSPort>443</TLSPort>
9 </HLS>
10 <DASH>
11 <Port>80</Port>
12 <TLSPort>443</TLSPort>
13 </DASH>
14 <WebRTC>
15 <Signalling>
16 <Port>3333</Port>
17 <TLSPort>3334</TLSPort>
18 </Signalling>
19 ...
20 </WebRTC>
21 </Publishers>
22 </Bind>

Add your certificate files to as follows:

1 <Domain>
2 <Names>
3 <Name>*.airensoft.com</Name>
4 </Names>

5 <TLS>
6 <CertPath>path/to/file.crt</CertPath>
7 <KeyPath>path/to/file.key</KeyPath>
8 <ChainCertPath>path/to/file.crt</ChainCertPath>
9 </TLS>
10 </Domain>
To configure HTTPs for HLS, DASH, and WebRTC Signalling servers, the TLS element must be enabled.
The CertPath has to indicate a server certificate and the KeyPath has to indicate a private key file. They can
be set to absolute paths or relative paths from the executable. If the server certificate is issued using an
intermediate certificate, some browsers may complain about a certificate. In this case, you should set a
bundle of chained certificates provided by a Certificate Authority in ChainCertPath
If you set up TLS, you can't set IP or * into <Name>. You can only set Domains that the certificate contains. If
you have a certificate for *.host.com , it means you can set domains such as aaa.host.com ,
bbb.host.com , and *.host.com .

If the certificate settings are completed correctly, WebRTC streaming can be played wss://url with HLS
and DASH streaming https://url .

The current version of OvenMediaEngine doesn't yet support SNI. This means that you can't set
multiple TLS. So currently OvenMediaEngine can only set TLS on the first VirtualHost. We will
support SNI in the next version.

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 SingedPolicy URL cannot access resources other than the provided
URL. This is because the SignedPolicy URL is authenticated.

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

1 scheme://domain.com:port/app/stream?policy=<>&signature=<>

Policy

Policy is in json format and provides the following properties.


1 {
2 "url_activate":1639140752071,
3 "url_expire":1639140776950,
4 "stream_expire":1639140776950,
5 "allow_ip":"192.168.100.5/32"
6 }

Key Value Description

The time the URL expires


url_expire <Number> Milliseconds since
Reject on request after the
(Required) unix epoch
expiration

The time the URL activates


url_activate <Number> Milliseconds since
Reject on request before
(Optional) unix epoch
activation

The time the Stream expires


stream_expire <Number> Milliseconds since
Transmission and playback sto
(Optional) unix epoch
when the time expires

allow_ip Allowed IP address range,


<String> IPv4 CIDR
(Optional) 192.168.0.0/24

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

Signature is generated by HMAC-SHA1 encoding all URLs except signature query string. The generated
Signature is encoded using Base64URL and included as a query string of the existing URL.

1 Base64URL.Encode(
2 HMAC.Encrypt(

3 SHA1,
4 secret_key,
5 "scheme://domain.com:port/app/stream[/file]?policy='encoded policy'>"
6 )
7 )

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 <SingedPolicy> setting in Server.xml under
<VirtualHost>.

1 <VirtualHost>
2 <SignedPolicy>
3 <PolicyQueryKeyName>policy</PolicyQueryKeyName>
4 <SignatureQueryKeyName>signature</SignatureQueryKeyName>
5 <SecretKey>aKq#1kj</SecretKey>
6
7 <Enables>
8 <Providers>rtmp</Providers>
9 <Publishers>webrtc,hls,dash,lldash</Publishers>
10 </Enables>
11 </SignedPolicy>
12 </VirtualHost>

Key Description

The query string key name in the URL pointing to


PolicyQueryKeyName
the policy value

The query string key name in the URL pointing to


SignatureQueryKeyName
the signature value

The secret key used when encoding with HMAC-


SecretKey
SHA1

List of providers and publishers to enable


SignedPolicy. Currently, SingedPolicy supports
Enables rtmp among providers, and among publishers,
WebRTC, HLS, MPEG-DASH, and Low-Latency
MPEG-DASH (LLDASH) are supported.
Make SignedPolicy URL with a script
We provide a script that can easily generate SingedPolicy URL. The script can be found in the path below.

1 /misc/signed_policy_url_generator.sh

Here's how to use this script:

1 ./signed_policy_generator.sh [HMAC_KEY] [BASE_URL] [SIGNATURE_QUERY_KEY_NAME] [POLICY_QUERY

For example, you can use it like this:

Make SingedPolicy URL manually

We hope to provide SignedPolicy URL Generator Library in various languages. If you have
created the SignedPolicy URL Generator Library in another language, please send a Pull Request
to our GITHUB. Thank you for your open source contributions.

Encoding policy

In order to include the policy in the URL, it must be encoded with Base64URL.

Plain {Policy}

1 {"url_expire":1639140776950}

Base64URL Encoded {Policy}


1 eyJ1cmxfZXhwaXJlIjoxMzk5NzIxNTgxfQ

Policy encoded with Base64URL is added as a query string to the existing streaming URL. (The query string
key is set in Server.xml.)
1 ws://192.168.0.100:3333/app/stream?policy=eyJ1cmxfZXhwaXJlIjoxMzk5NzIxNTgxfQ

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.

URL input to signature generation


1 ws://192.168.0.100:3333/app/stream?policy=eyJ1cmxfZXhwaXJlIjoxMzk5NzIxNTgxfQ

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

Base64URL encoded { HMAC-SHA1 <KEY : 1kU^b6> (URL) }


1 dvVdBpoxAeCPl94Kt5RoiqLI0YE

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

URL with signature


1 ws://192.168.0.100/app/stream?policy=eyJ1cmxfZXhwaXJlIjoxMzk5NzIxNTgxfQ&signature=dvVdBpoxA

Usage examples

Applying SignedPolicy in OBS

Generate SingedPolicy 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 (beta)

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.

1 <VirtualHost>
2 <AdmissionWebhooks>
3 <ControlServerUrl>https://192.168.0.161:9595/v1/admission</ControlServerUrl
4 <SecretKey>1234</SecretKey>
5 <Timeout>3000</Timeout>
6 <Enables>
7 <Providers>rtmp,webrtc,srt</Providers>
8 <Publishers>webrtc,hls,dash,lldash</Publishers>
9 </Enables>
10 </AdmissionWebhooks>
11 </VirtualHost>

Key Description

The HTTP Server to receive the query. HTTP and


ControlServerUrl
HTTPS are available.

The secret key used when encrypting with HMAC


SecretKey SHA1
For more information, see Security.

Time to wait for a response after request (in


Timeout
milliseconds)

Enable Providers and Publishers to use


Enables
AdmissionWebhooks

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.

1 POST /configured/tartget/url/ HTTP/1.1


2 Content-Length: 325
3 Content-Type: application/json
4 Accept: application/json
5 X-OME-Signature: f871jd991jj1929jsjd91pqa0amm1
6 {
7
7
"client":
8 {
9 "address": "211.233.58.86",
10 "port": 29291
11 },
12 "request":
13 {
14 "direction": "incoming | outgoing",
15 "protocol": "webrtc | rtmp | srt | hls | dash | lldash",
16 "url": "scheme://host[:port]/app/stream/file?query=value&query2=value2",
17 "time": ""2021-05-12T13:45:00.000Z"
18 }
19 }

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:

Element Sub-Element Description

Information of the client who


client
requested the connection.

address Client's IP address

port Client's Port number

Information about the client's


request
request

incoming : A client requests to


publish a stream
direction
outgoing : A client requests to
play a stream

webrtc, srt, rtmp, hls, dash,


protocol
lldash

url url requested by the client

time requested by the client


time
(ISO8601 format)

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.

Protocol Condition

WebRTC When a client requests Offer SDP

RTMP When a client sends a publish message

SRT When a client send a streamid

HLS Every time a client requests a playlist

DASH Every time a client requests a playlist

LL-DASH Every time a client requests a playlist

Response

Format

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

1 HTTP/1.1 200 OK
2 Content-Length: 102
3 Content-Type: application/json
4 Connection: Closed

5 {
6 "allowed": true,
7 "new_url": "scheme://host[:port]/app/stream/file?query=value&query2=value2",
8 "lifetime": milliseconds,
9 "reason": "authorized"
10 }

Element Description

true or false
allowed (required)
Allows or rejects the client's request.

Redirects the client to a new url. However, the


scheme , port , and file cannot be different
new_url (optional)
from the request. The host can only be changed to
another virtual host on the same server.
The amount of time (in milliseconds) that a client
can maintain a connection (Publishing or
Playback)

lifetime (optional) 0 means infinity

HTTP based streaming (HLS, DASH, LLDASH)


does not keep a connection, so this value does no
apply.

reason (optional) If allowed is false, it will be output to the log.

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.
OvenMediaEngine supports the Origin-Edge structure for cluster configuration and provides scalability. Also,
you can set Origin as Primary and Secondary in OvenMediaEngine for HA.

Origin-Edge Configuration
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.

The OVT is a protocol defined by OvenMediaEngine to relay stream between Origin-Edge and OVT can be
run over SRT and TCP. For more information on the SRT Protocol, please visit the SRT Alliance site.

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 :

1 <Server version="5">
2 <Bind>
3 <Publishers>
4 <OVT>
5 <Port>9000</Port>
6 </OVT>
7 </Publishers>
8 </Bind>
9 <VirtualHosts>
10 <VirtualHost>

11 <Applications>
12 <Application>
13 ...
14 <Publishers>
15 <OVT />
16 </Publishers>
17 </Application>
18 </Applications>
19 </VirtualHost>
20 </VirtualHosts>
21 </Server>

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
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 or RTSP is bypassed without being encoded.

In order to re-encode the stream created by OVT and RTSP, the function to put into an existing
application will be supported in the future.

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

1 <VirtualHosts>
2 <VirtualHost>
3 <Origins>
4 <Properties>
5 <NoInputFailoverTimeout>3000</NoInputFailoverTimeout>
6 <UnusedStreamDeletionTimeout>60000</UnusedStreamDeletionTim
7 </Properties>
8 <Origin>
9 <Location>/app/stream</Location>
10 <Pass>
11 <Scheme>ovt</Scheme>
12 <Urls><Url>origin.com:9000/app/stream_720p</Url></U
13 </Pass>
14 </Origin>
15 <Origin>
16 <Location>/app/</Location>
17 <Pass>
18 <Scheme>OVT</Scheme>
19 <Urls><Url>origin.com:9000/app/</Url></Urls>
20 </Pass>
21 </Origin>
22 <Origin>

23 <Location>/</Location>
24 <Pass>
25 <Scheme>RTSP</Scheme>
26 <Urls><Url>origin2.com:9000/</Url></Urls>
27 </Pass>
28 </Origin>
29 </Origins>
30 </VirtualHost>
31 </VirtualHosts>

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.

The automatically created application by <Origin> enables all providers but if you create an application
yourself, you must enable the provider that matches the setting as follows.
1 <VirtualHosts>
2 <VirtualHost>
3 <Origins>
4 <Properties>
5 <NoInputFailoverTimeout>3000</NoInputFailoverTimeout>
6 <UnusedStreamDeletionTimeout>60000</UnusedStreamDeletionTim
7 </Properties>
8 <Origin>
9 <Location>/this_application/stream</Location>
10 <Pass>
11 <Scheme>OVT</Scheme>
12 <Urls><Url>origin.com:9000/app/stream_720p</Url></U
13 </Pass>
14 </Origin>
15 <Origin>
16 <Location>/this_application/rtsp_stream</Location>
17 <Pass>
18 <Scheme>RTSP</Scheme>
19 <Urls><Url>rtsp.origin.com/145</Url></Urls>
20 </Pass>
21 </Origin>
22 </Origins>
23 <Applications>
24 <Application>
25 <Name>this_application</Name>
26 <Type>live</Type>
27 <Providers>
28 <!-- You have to enable the OVT provider
29 because you used the ovt scheme for configuring Ori
30 <OVT />
31 <!-- If you set RTSP into Scheme,
32 you have to enable RTSPPull provider -->
33 <RTSPPull />
34 </Providers>
35

<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
OVT or RTSP .

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

You can pull the stream from the RTSP server by setting RTSP into 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.

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

1 <Location>/edge_app/</Location>
2 <Pass>
3 <Scheme>ovt</Scheme>
4 <Urls><Url>origin.com:9000/origin_app/</Url></Urls>
5 </Pass>

If a user requests http://edge.com/edge_app/stream, OvenMediaEngine makes an address to ovt:


//origin.com: 9000/origin_app/stream.

Load Balancer
When you are configuring Load Balancer, you need to use third-party solutions such as L4 Switch, LVS, or
GSLB, but we recommend using DNS Round Robin. Also, services such as cloud-based AWS Route53,
Azure DNS, or Google Cloud DNS can be a good alternative.

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.

1 <Bind>
2 <Publishers>
3 ...
4 <Thumbnail>
5 <Port>20080</Port>
6 <!-- If you need TLS support, please uncomment below:
7 <TLSPort>20081</TLSPort>
8 -->
9 </Thumbnail>
10 </Publishers>
11 </Bind>

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.

1 <OutputProfiles>
2 <OutputProfile>
3 <Name>default_stream</Name>
4 <OutputStreamName>${OriginStreamName}_preview</OutputStreamName>
5 <Encodes>
6 <Image>
7 <Codec>jpeg</Codec>
8 <Framerate>1</Framerate>
9 <Width>1280</Width>
10 <Height>720</Height>
11 </Image>
12 <Image>
13 <Codec>png</Codec>
14 <Framerate>1</Framerate>
15 <Width>1280</Width>
16 <Height>720</Height>
17 </Image>
18 </Encodes>
19 </OutputProfile>
20
20
</OutputProfiles>

Publisher

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

1 <Publishers>
2 ...
3 <Thumbnail>
4 <CrossDomains>
5 <Url>*</Url>
6 </CrossDomains>
7 </Thumbnail>
8 </Publishers>

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

Method URL Pattern

http(s)://<ome_host>:
GET <port>/<app_name>/<output_stream_name>/thum
.<jpg|png>

Recording (Beta)

OvenMediaEngine can record live streams. You can start and stop recording the output stream through
REST API. When the recording is complete, a recording information file is created together with the
recorded file so that the user can perform various post-recording processing.

Configuration

File Publisher

To enable recording, add the <FILE> publisher to the configuration file as shown below. <FilePath>
and <InfoPath> are required and used as default values. <FilePath> is the setting for the file path and
file name. <InfoPath> is the setting for the path and name of the XML file that contains information about
the recorded files. If there is no file path value among parameters when requesting recording through API,
recording is performed with the set default value. This may be necessary if for security reasons you do not
want to specify the file path when calling the API to avoid exposing the server's internal path.
< <RootPath> is an optional parameter. It is used when requesting with a relative path is required when
requesting an API. also, it is applied to <FilePath> and <InfoPath> as in the example below.
You must specify .ts or .mp4 at the end of the FilePath string to select a container for the recording file.
We recommend using .ts unless you have a special case. This is because vp8 and opus codecs are not
recorded due to container limitations if you choose .mp4.

1 <Publishers>
2 <FILE>
3 <RootPath>/mnt/shared_volumes</RootPath>
4 <FilePath>/${VirtualHost}/${Application}/${Stream}/${StartTime:YYYYMMDDhhmm
5 <InfoPath>/${VirtualHost}/${Application}/${Stream}.xml</InfoPath>
6 </FILE>
7 </Publishers>

Various macro values are supported for file paths and names as shown below.

Macro Definition

Macro Description

Unique ID for the recording transaction. It is


automatically created when recording starts. and
${TransactionId} released when recording is stopped. In case of sp
recording, it is distinguished that it is the same
transaction.

${Id} User-defined identification ID

Recording start time


YYYY - Year
MM - Month
${StartTime:YYYYMMDDhhmmss} DD - Days
hh : Hours (0~23)
mm : Minutes (00~59)
ss : Seconds (00~59)

Recording end time


YYYY - Year
MM - Month
${EndTime:YYYYMMDDhhmmss} DD - Days
hh : Hours (0~23)
mm : Minutes (00~59)
ss : Seconds (00~59)

${VirtualHost} Virtual host name


${Application} Application name
${SourceStream} Source stream name

${Stream} Output stream name

Sequence value that increases when splitting a fi


${Sequence}
in a single transaction

Start & Stop Recording


For control of recording, use the REST API. Recording can be requested based on the output stream name
(specified in the JSON body), and all/some tracks can be selectively recorded. And, it is possible to
simultaneously record multiple files for the same stream. When recording is complete, an XML file is created
at the path specified in InfoPath. For a sample of the recorded file information XML, refer to Appendix A.

For how to use the API, please refer to the link below.

Recording

Split Recording

Split recording methods provide interval and schedule. The interval method splits files based on the
accumulated recording time. The Schedule method then splits files according to scheduling options based
on system time. The scheduling option is the same as the pattern used in crontab. However, only three
options are used: seconds/minutes/hour.

interval and schedule methods cannot be used simultaneously.

Appendix A. Recorded File Information Specification


The following is a sample of an XML file that expresses information on a recorded file.

1 <?xml version="1.0" encoding="utf-8"?>


2 <files>
3 <file>
4 <transactionId>bcUCyJeKuOGnsah3</transactionId>
5 <id>CTS_ID001</id>
6 <vhost>default</vhost>
7
8 <app>app</app>
<stream>stream_o</stream>
9 <filePath><![CDATA[/home/dev/OvenMediaEngine/records/bcUCyJeKuOGnsah3_default_app_strea
10 <recordBytes>8774737</recordBytes>
11 <recordTime>60011</recordTime>
12 <sequence>0</sequence>
13 <interval>60000</interval>
14 <lastSequence>true</lastSequence>
15 <createdTime>2020-12-04T12:53:51.455+0900</createdTime>
16 <startTime>2020-12-04T12:53:51.612+0900</startTime>
17 <finishTime>2020-12-04T12:54:51.473+0900</finishTime>
18 </file>
19 <file>
20 <transactionId>bcUCyJeKuOGnsah3</transactionId>
21 <id>CTS_ID001</id>
22 <vhost>default</vhost>
23 <app>app</app>
24 <stream>stream_o</stream>
25 <filePath><![CDATA[/home/dev/OvenMediaEngine/records/bcUCyJeKuOGnsah3_default_app_strea
26 <recordBytes>2285797</recordBytes>
27 <recordTime>60012</recordTime>
28 <sequence>0</sequence>
29 <schedule>0 */1 *</schedule>
30 <lastSequence>false</lastSequence>
31 <createdTime>2020-12-04T12:53:00.000+0900</createdTime>
32 <startTime>2020-12-04T12:53:00.000+0900</startTime>
33 <finishTime>2020-12-04T12:54:00.000+0900</finishTime>
34 </file>
35 <file>
36 <transactionId>bcUCyJeKuOGnsah3</transactionId>
37 <id>CTS_ID001</id>
38 <vhost>default</vhost>
39 <app>app</app>
40 <stream>stream_o</stream>
41 <filePath><![CDATA[/home/dev/OvenMediaEngine/records/bcUCyJeKuOGnsah3_default_app_strea
42 <recordBytes>4544626</recordBytes>
43 <recordTime>60000</recordTime>
44 <sequence>1</sequence>
45 <schedule>0 */1 *</schedule>
46 <lastSequence>true</lastSequence>
47 <createdTime>2020-12-04T12:54:00.000+0900</createdTime>
48 <startTime>2020-12-04T12:54:00.000+0900</startTime>
49 <finishTime>2020-12-04T12:55:00.000+0900</finishTime>
50 </file>
51 </files>

Push Publishing (Beta)


OvenMediaEngine supports Push Publishing function that can retransmit live streams to other systems.
The protocol supported for retransmission uses RTMP. Because, most services and products support this
protocol. also, one output stream can be transmitted to multiple destinations at the same time. You can start
and stop pushing the output stream through REST API. Note that the only codecs that can be retransmitted
in RTMP protocol are H264 and AAC

Configuration

RTMPPush Publisher

To use RTMP Push Publishing, you need to declare the <RTMPPush> publisher in the configuration.
There are no other detailed options.

1 <Applications>
2 <Application>
3 ...
4 <Publishers>
5 ...
6 <RTMPPush>
7 </RTMPPush>
8 </Publishers>
9 </Application>

10 </Applications>

Only H264 and AAC are supported codecs.

Start & Stop Push

For control of push, use the REST API. RTMP push can be requested based on the output stream name
(specified in the JSON body), and you can selectively transfer all/some tracks. In addition, you must specify
the URL and Stream Key of the external server to be transmitted. It can send multiple Pushes
simultaneously for the same stream. If transmission is interrupted due to network or other problems, it
automatically reconnects.

For how to use the API, please refer to the link below.

Push
REST API (Beta)

Overview
The REST APIs provided by OME allow you to query or change settings such as VirtualHost and
Application/Stream.

The APIs are currently beta version, so there are some limitations/considerations.
Settings of VirtualHost can only be viewed and cannot be changed or deleted.

If you add/change/delete the settings of the App/Output Profile by invoking the API, the app will
be restarted. This means that all sessions associated with the app will be disconnected.
The API version is fixed with v1 until the experimental stage is complete, and the detailed
specification can be changed at any time.

By default, OvenMediaEngine's APIs are disabled, so the following settings are required to use the API:

Setting up for using the APIs

Port

Set the <Port> to use by the API server. If you omit <Port> , you will use the API server's default port,
port 8081 .

1 <Server version="8">
2 ...
3 <Bind>
4 <Managers>
5 <API>
6 <Port>8081</Port>
7 <!-- If you need TLS support, please uncomment below:
8 <TLSPort>8082</TLSPort>
9 -->
10 </API>
11 </Managers>
12 ...
13 </Bind>
14 ...
15 </Server>

Host and Permissions

<Host> sets the Host name and TLS certificate information to be used by the API server, and
<AccessToken> sets the token to be used for authentication when calling the APIs. You must use this
token to invoke the API of OvenMediaEngine.

1 <Server version="8">
2 ...
3 <Managers>
4 <Host>
5 <Names>
6 <Name>*</Name>
7 </Names>
8 <!--
9 If you want to set up TLS, set it up by referring to the fo
10 <TLS>
11 <CertPath>airensoft_com.crt</CertPath>
12 <KeyPath>airensoft_com.key</KeyPath>
13 <ChainCertPath>airensoft_com_chain.crt</ChainCertPath>
14 </TLS>
15 -->
16 </Host>
17 <API>
18 <AccessToken>your_access_token</AccessToken>
19 </API>
20 </Managers>
21 </Server>

API Request/Response Specification


In this manual, the following format is used when describing the API.

GET http://<OME_HOST>:<API_PORT>/<VERSION>/<API_PATH>[/...]

<VERSION>/<API_PATH>

Here is the description of the API

Request Example:
- Method: GET
- URL: http://1.2.3.4:8081/v1/vhost
- Header:
authorization: Basic b21ldGVzdA==

Parameters

Path

string
Header

authorization string

Basic base64encode(AccessToken)

if you set <AccessToken> to "ome-access-token" in Server.xml , you must set Basic


b21lLWFjY2Vzcy10b2tlbg== in the Authorization header.

Responses

200

<OME_HOST>

This means the IP or domain of the server on which your OME is running.

<API_PORT>

This means the port number of the API you set up in Server.xml . The default value is 8081.

<VERSION>

Indicates the version of the API. Currently, all APIs are v1.

<API_PATH>

Indicates the API path to be called. The API path is usually in the following form:

1 /resource-group[/resource[/resource-group[/resource/...]]][:action]

resource means an item, such as VirtualHost or Application , and action is used to


command an action to a specific resource, such as push or record .

Response

All response results are provided in the HTTP status code and response body, and if there are multiple
response results in the response, the HTTP status code will be 207 MultiStatus . The API response
data is in the form of an array of Response or Response as follows:
1 // Single data request example
2
3 // << Request >>
4 // Request URI: GET /v1/vhosts/default
5 // Header:
6 // authorization: Basic b21lLWFjY2Vzcy10b2tlbg==
7
8 // << Response >>
9 // HTTP Status code: 200 OK
10 // Response Body:
11 {
12 "statusCode": 200,
13 "message": "OK",
14 "response": ... // Requested data
15 }

1 // Multiple data request (Status codes are the same)


2
3 // << Request >>
4 // Request URI: POST /v1/vhost/default/apps
5 // Header:
6 // authorization: Basic b21lLWFjY2Vzcy10b2tlbg==

7 // Request Body:
8 [
9 { ... }, // App information to create
10 { ... }, // App information to create
11 ]
12
13 // << Response >>
14 // HTTP Status code: 200 OK
15 // Response Body:
16 [
17 {
18 "statusCode": 200,
19 "message": "OK",
20 "response": ... // App1
21 },
22 {
23 "statusCode": 200,
24 "message": "OK",
25 "response": ... // App2
26 }
27 ]

1 // Multiple data request (Different status codes)


2
3 // << Request >>
4 // Request URI: POST /v1/vhost/default/apps
5 // Header:
6 // authorization: Basic b21lLWFjY2Vzcy10b2tlbg==
7 // Request Body:
8 [
9 { ... }, // App information to create
10 { ... }, // App information to create
11 ]
12
13 // << Response >>
14 // HTTP Status code: 207 MultiStatus
15 // Response Body:
16 [
17 {
18 "statusCode": 200,
19 "message": "OK",
20 "response": ... // App1
21 },
22 {
23 "statusCode": 404,
24 "message": "Not found"
25 }
26 ]

v1

Data Types

Primitives/Notations

Primitive data types

Type Description Examples

Short 16bits integer 12345

Int 32bits integer 1234941932


Long 64bits integer 391859818923919232311
Float 64bits real number 3.5483

String A string "Hello"

Bool true/false true

Timestamp "2021-01-
A timestamp in ISO8601 format
(String) 01T11:00:00.000+09:00"

TimeInterval A time interval (unit:


349820
(Long) milliseconds)

IP
IP address "127.0.0.1"
(String)

Port numbers with range (it can


contain multiple ports and
protocols) "40000-40005/tcp"
RangedPort start_port[-end_port] "40000-40005"
(String) [,start_port[-end_port]
[,start_port[-
end_port]...]] "40000-
[/protocol] 40005,10000,20000/tcp"

Port A port number "1935/tcp"


(String) start_port[/protocol] "1935"

Enum/Container Notations

Enum< Type > (String)

An enum value named Type

Examples
"value1"

"value2"

List< Type >

An ordered list of Type

Examples
[ Type, Type, ... ]
Map< KeyType ValueType >
An object consisting of Key - Value pairs

Examples
{ Key1: Value1, Key2: Value2 }

Enums

Enum< ApplicationType >

Application type

Examples
"live"

"vod"

Enum< Codec >

Codecs
Examples
"h264"

"h265"

"vp8"

"opus"

"aac"

Enum< StreamSourceType >

A type of input stream


Examples
"Ovt"

"Rtmp"

"Rtspc"

"RtspPull"

"MpegTs"

Enum< MediaType >


type
Examples
"video"

"audio"

Enum< SessionState >

A state of the session

Examples
"Ready"

"Started"

"Stopping"

"Stopped"

"Error"

Enum< AudioLayout >

Audio layout
Examples
"stereo"

"mono"

Classes

Response< [TYPE] >

Type Name Optional Description Examples

Int statusCode N Status code 200

A message
String message N describing the "OK"
value returned

[TYPE] response Y A response data {}

VirtualHost
Type Name Optional Description Examples

A name of Virtual
String name N "default"
Host

Host td Y Host Host

SignedPolic SignedPolic
signedPolicy Y SignedPolicy
y y

SignedToken signedToken Y SignedToken SignedToken

[OriginMap,
List< OriginMa A list of Origin
td Y OriginMap,
p> map
...]

Host

Type Name Optional Description Examples

["airensoft
com",
List<String> td N A list of hosts
"*.test.com
, ...]

Tls td Y TLS TLS

TLS

Type Name Optional Description Examples

String certPath N A path of cert file "a.crt"

A path of private
String keyPath N "a.key"
key file

A path of chain
String chainCertPath Y "c.crt"
cert file

SignedPolicy
Type Name Optional Description Examples

String policyQueryKey N

signatureQueryK
String N
ey

String secretKey N

SignedToken

Type Name Optional Description Examples

String cryptoKey N

String queryStringKey N

OriginMap

Type Name Optional Description Examples

A pattern to map
String location N "/"
origin

What to request
Pass pass N with Origin if the Pass
pattern matches

Pass

Type Name Optional Description Examples

Scheme to
String scheme N distinguish the "ovt"
provider

["origin:90
An address list to 0",
List<String> urls N
pull from provider
"origin2:90

Application

Type Name Optional Description Examples

App name (You


cannot change
String name N "app"
this value after
you create it)

Whether the app


was created
Bool dynamic N using true
PullStream(
)

Enum< Applica
type N App type "live"
tionType >

A list of
Providers providers Y Providers
Provider s

A list of
Publishers publishers Y Publishers
Publisher s

[OutputProf
A list of
List< OutputPr le,
outputProfiles Y OutputProfi
ofile > OutputProfi
le s
e, ...]

Providers

Type Name Optional Description Examples

RtmpProvide RtmpProvide
rtmp Y
r r

RtspPullProv RtspPullPro
rtspPull Y
ider ider

RtspProvide RtspProvide
rtsp Y
r r
OvtProvider ovt Y OvtProvider

MpegtsProvi MpegtsProvi
mpegts Y
der der

RtmpProvider

Type Name Optional Description Examples

(Reserved for
- - -
future use)

RtspPullProvider

Type Name Optional Description Examples

(Reserved for
- - -
future use)

RtspProvider

Type Name Optional Description Examples

(Reserved for
- - -
future use)

OvtProvider

Type Name Optional Description Examples

(Reserved for
- - -
future use)
MpegtsProvider

Type Name Optional Description Examples

[MpegtsStre
List< MpegtsSt MPEG-TS m,
streams Y
ream > Stream map MpegtsStrea
, ...]

MpegtsStream

Type Name Optional Description Examples

A name to
generate when
String name N "stream"
MPEG-TS stream
is received

"40000-
RangedPort port Y MPEG-TS Port
40001/udp"

Publishers

Type Name Optional Description Examples

Number of
Int threadCount N 4
threads

RtmpPushPubl RtmpPushPub
rtmpPush Y
isher isher

HlsPublishe HlsPublishe
hls Y
r r

DashPublish DashPublish
dash Y
er er

LlDashPubli LlDashPubli
llDash Y
sher sher

WebrtcPubli WebrtcPubli
webrtc Y
sher sher
OvtPublishe OvtPublishe
ovt Y
r r

FilePublish FilePublish
file Y
er er

ThumbnailPub ThumbnailPu
thumbnail Y
lisher lisher

RtmpPushPublisher

Type Name Optional Description Examples

(Reserved for
- - -
future use)

HlsPublisher

Type Name Optional Description Examples

Segment count in
Int segmentCount N 3
the playlist.m3u8

Segment
Int segmentDuration N duration (unit: 4
seconds)

Cross domain
List<String> crossDomains Y ["*"]
URLs

DashPublisher

Type Name Optional Description Examples

Segment count in
Int segmentCount N 3
the manifest.mpd

Segment
Int segmentDuration N duration (unit: 4
seconds)
Cross domain
List<String> crossDomains Y ["*"]
URLs

LlDashPublisher

Type Name Optional Description Examples

Segment
Int segmentDuration N duration (unit: 3
seconds)

Cross domain
List<String> crossDomains Y ["*"]
URLs

WebrtcPublisher

Type Name Optional Description Examples

TimeInterva ICE timeout (unit:


timeout Y 30
l seconds)

OvtPublisher

Type Name Optional Description Examples

(Reserved for
- - -
future use)

FilePublisher

Type Name Optional Description Examples

A path to store
recorded file
You can use the
following macros:
${Transactio
nId}: An
identifier
of
transaction
${Id}: An
identifier
to
distinguish
files
${StartTime:
YYYYMMDDhhmm
ss}: Start
time of
recording
${EndTime:YY
YYMMDDhhmmss "/tmp/${Sta
}: End time tTime:YYYYM
String filePath Y
of of DDhhmmss}_$
recording Stream}.mp4
${VirtualHos
t}: A name
of virtual
host
${Applicatio
n}: A name
of
application
${SourceStre
am}: A name
of input
stream
${Stream}: A
name of
output
stream
${Sequence}:
A sequence
number

"/tmp/${Sta
A path of tTime:YYYYM
String fileInfoPath Y recorded files DDhhmmss}_$
Stream}.xml

ThumbnailPublisher

Type Name Optional Description Examples

Cross domain
List<String> crossDomains Y ["*"]
URLs

OutputProfile

Type Name Optional Description Examples

A name of
"bypass_str
String name N OutputProfi
eam"
le

outputStreamNa A name of output "${OriginSt


String N
me stream eamName}"

[Encodes,
Encodes encodes Y Encodes,
...]

Encodes

Type Name Optional Description Examples

[Video,
List< Video > videos Y
Video, ...]

[Audio,
List< Audio > audios Y
Audio, ...]

[Image,
List< Image > images Y
Image, ...]
Video

Type Name Optional Description Examples

Bool bypass Y true

Enum< Codec > codec Conditional Video codec "h264"

Int width Conditional 1280

Int height Conditional 720

bitrate (You can


use "K" or "M" "3000000"
String bitrate Conditional
suffix like 100K , "2.5M"
3M )

Float framerate Conditional 29.997

Audio

Type Name Optional Description Examples

Bool bypass Y true

Enum< Codec > codec Conditional Audio codec "opus"

Int samplerate Conditional 48000

Int channel Conditional 2

bitrate (You can


use "K" or "M" "128000"
String bitrate Conditional
suffix like 128K , "128K"
0.1M )

Image

Type Name Optional Description Examples


Enum< Codec > codec N "jpeg" |
"png"
Int width Conditional 854

Int height Conditional 480

An interval of
Float framerate N 1
image creation

Stream

Type Name Optional Description Examples

String name N A name of stream "stream"

An information of
InputStream input N InputStream
input stream

[OutputStre
List< OutputSt An information of m,
ream > outputs N output streams OutputStrea
, ...]

NewStream

Type Name Optional Description Examples

A name of stream
String name N "stream"
to create

PullStream pull Y pull PullStream

MpegtsStrea Creates a MpegtsStrea


m mpegts Y prestream m

PullStream

Type Name Optional Description Examples

"rtsp://hos
String url N URL to pull .com/resour
e"

InputStream

Type Name Optional Description Examples

A name of "OBS
String agent Y
broadcast tool 12.0.4"

"tcp://192.
URI stream
String from N 68.0.200:33
created
99"

URI represents "rtmp://dev


String to Y connection with airensoft.c
the input m:1935"

A list of tracks in [Track,


List< Track > tracks N
input stream Track, ...]

"2020-10-
Timestamp createdTime N Creation time 30T11:00:00
09:00"

OutputStream

Type Name Optional Description Examples

An name of
String name N OutputStrea "stream_o"
m

A list of tracks in
[Track,
List< Track > tracks N OutputStrea
Track, ...]
m

Track
Type Name Optional Description Examples

Enum< MediaT
type Y Media type "video"
ype >

A configuration of
Video video Conditional Video
video encoding

A configuration of
Audio audio Conditional Audio
audio encoding

VideoTrack

Type Name Optional Description Examples

(Extends
- -
Video )

Timebase timebase Y Timebase Timebase

Timebase

Type Name Optional Description Examples

Int num N Numerator 1

Int den N Denominator 90000

AudioTrack

Type Name Optional Description Examples

(Extends
- - true
Audio )

Timebase timebase Y Timebase Timebase


Record
Type Name Optional Description Examples

String id Y Unique identifier

A combination of
OutputStrea output stream's
streams N
m track name and
track id

Enum< Session
state N Record state
State >

A path of
String filePath N
recorded files

A path of
String fileInfoPath N recorded file
informations

String recordedBytes N Recorded bytes

Int recordedTime N Recorded time

Timestamp startTime N Started time

Timestamp finishTime N Finished time

Int bitrate N Average bitrate

Push

Type Name Optional Description Examples

String id N Unique identifier

A combination of
OutputStrea output stream's
stream Y
m track name and
track id

Enum< StreamS Protocol of input


protocol Y
ourceType > stream

String url Y Destination URL

Stream key of
String streamKey Conditional
destination
Enum< Session
state N Push state
State >

Int sentBytes N Sent bytes

Sent packets
Int sentPackets N
count

Int sentErrorBytes N Error bytes

Error packets
Int sentErrorPackets N
count

Int reconnect N Reconnect count

Timestamp startTime N Started time

Timestamp finishTime N Finished time

Int bitrate N Average bitrate

CommonMetrics

Type Name Optional Description Examples

"2020-10-
Timestamp createdTime N Creation time 30T11:00:00
09:00"

"2020-10-
Timestamp lastUpdatedTime N Modified time 30T11:00:00
09:00"

Long totalBytesIn N Received bytes 3109481213

Long totalBytesOut N Sent bytes 1230874123

Current
Int totalConnections N 10
connections

Max connections
maxTotalConnect
Int N since the stream 293
ions
is created

When the
maximum
"2020-10-
maxTotalConnect number of
Timestamp N 30T11:00:00
ionTime concurrent
connections has 09:00"
been updated.

"2020-10-
Last time data
Timestamp lastRecvTime N 30T11:00:00
was received
09:00"

"2020-10-
Last time data 30T11:00:00
Timestamp lastSentTime N
was sent 09:00"

StreamMetrics

Type Name Optional Description Examples

Includes all fields


(Extends
of
CommonMetri - - CommonMetri
cs )
cs

TimeInterva requestTimeToOr A elapsed time to


Y 1000
l igin connect to Origin

A elapsed time
TimeInterva responseTimeFro from Origin to
Y 10000
l mOrigin respond

VirtualHost

GET http://<OME_HOST>:<API_PORT>/v1/vhosts

/v1/vhosts

Lists all virtual host names

Request Example:
GET http://1.2.3.4:8081/v1/vhosts

Parameters

Header
authorization string
A string for authentication in Basic Base64(AccessToken) format.
For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Responses

200

- Return type: Response<List<string>>


- Description
Returns a list of virtual host names

GET http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}

/v1/vhosts/{vhost_name}

Gets the configuration of the VirtualHost

Request Example:
GET http://1.2.3.4:8081/v1/vhosts/default

Parameters

Path

vhost_name string

A name of VirtualHost

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Responses

200

- Return type: Response<VirtualHost>


- Description
Returns the specified virtual host information

404
- Return type: Response<>
- Description
The specified VirtualHost was not found.

Application

POST http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps

/v1/vhosts/{vhost_name}/apps

Creates Application s in the VirtualHost

Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps
[ { "name": "app", "type": "live", "outputProfiles": { "outputProfile": [ { "name": "bypass_profile",
"outputStreamName": "${OriginStreamName}", "encodes": { "videos": [ { "bypass": true } ], "audios": [ {
"bypass": true } ] } } ] } ]

Parameters

Path

vhost_name string

A name of VirtualHost

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Body

(json body) array

A list of Application

Responses

200

- Return type: List<Response<Application>>


- Description
Returns a list of created application informations

404

- Return type: Response<>


- Description
Not Found

GET http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps

/v1/vhosts/{vhost_name}/apps

Lists all application names in the VirtualHost

Request Example:
GET http://1.2.3.4:8081/v1/vhosts/default/apps

Parameters

Path

vhost_name string

A name of VirtualHost

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Responses

200

- Return type: Response<List<string>>


- Description
Returns a list of application names

404

- Return type: Response<>


- Description
Not Found
GET http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}

/v1/vhosts/{vhost_name}/apps/{app_name}

Gets the configuration of the Application

Request Example:
GET http://1.2.3.4:8081/v1/vhosts/default/apps/app

Parameters

Path

vhost_name string

A name of VirtualHost

app_name string

A name of Application

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Responses

200

- Return type: Response<Application>


- Description
Returns the specified application information

404

- Return type: Response<>


- Description
Not Found

P UT http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}

/v1/vhosts/{vhost_name}/apps/{app_name}
Changes the configuration of the Application

Request Example:
PUT http://1.2.3.4:8081/v1/vhosts/default/apps/app

{
"type": "live"
}

Parameters

Path

vhost_name string

A name of VirtualHost

app_name string

A name of Application

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Body

(json body) object

Application

Responses

200

- Return type: Response<Application>


- Description
Returns the modified application information

404

- Return type: Response<>


- Description
Not Found
DE L E T E http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}

/v1/vhosts/{vhost_name}/apps/{app_name}

Deletes the Application

Request Example:
DELETE http://1.2.3.4:8081/v1/vhosts/default/apps/app

Parameters

Path

vhost_name string

A name of VirtualHost

app_name string

A name of Application

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Responses

200

- Return type: Response<>


- Description
Returns the result

404

- Return type: Response<>


- Description
Not Found

Stream
GET http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}/streams

/v1/vhosts/{vhost_name}/apps/{app_name}/streams

Lists all stream names in the Application

Request Example:
GET http://1.2.3.4:8081/v1/vhosts/default/apps/app/streams

Parameters

Path

vhost_name string

A name of VirtualHost

app_name string

A name of Application

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Responses

200

- Return type: Response<List<string>>


- Description
Returns a list of stream names

404

- Return type: Response<>


- Description
Not Found

http://<OME_HOST>:<API_PORT>
GET
/v1/vhosts/{vhost_name}/apps/{app_name}/streams/{stream_name}

/v1/vhosts/{vhost_name}/apps/{app_name}/streams/{stream_name}
Gets the configuration of the Stream

Request Example:
GET http://1.2.3.4:8081/v1/vhosts/default/apps/app/streams/stream

Parameters

Path

vhost_name string

A name of VirtualHost

app_name string

A name of Application

stream_name string

A name of Stream

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Responses

200

- Return type: Response<Stream>


- Description
Returns the specified stream information

404

- Return type: Response<>


- Description
Not Found

Output Profile

http://<OME_HOST>:<API_PORT>
POST
/v1/vhosts/{vhost_name}/apps/{app_name}/outputProfiles

/v1/vhosts/{vhost_name}/apps/{app_name}/outputProfiles

Creates OutputProfile s in the Application

Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps/app/outputProfiles

[
{
"name": "bypass_profile",
"outputStreamName": "${OriginStreamName}",
"encodes": {
"videos": [
{
"bypass": true
}
],
"audios": [
{
"bypass": true
}
]
}
}
]

Parameters

Path

vhost_name string

A name of VirtualHost

app_name string

A name of Application

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Body
(json body) array
List< OutputProfile >

Responses

200

- Return type: List<Response<OutputProfile>>


- Description
Returns a list of created output profile informations

404

- Return type: Response<>


- Description
Not Found

http://<OME_HOST>:<API_PORT>
GET
/v1/vhosts/{vhost_name}/apps/{app_name}/outputProfiles

/v1/vhosts/{vhost_name}/apps/{app_name}/outputProfiles

Lists all output profile names in the Application

Request Example:
GET http://1.2.3.4:8081/v1/vhosts/default/apps/app/outputProfiles

Parameters

Path

vhost_name string

A name of VirtualHost

app_name string

A name of Application

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .
Responses

200

- Return type: Response<List<string>>


- Description
Returns a list of output profile names

404

- Return type: Response<>


- Description
Not Found

http://<OME_HOST>:<API_PORT>
GET
/v1/vhosts/{vhost_name}/apps/{app_name}/outputProfiles/{profile_name}

/v1/vhosts/{vhost_name}/apps/{app_name}/outputProfiles/{profile_name}

Gets the configuration of the OutputProfile

Request Example:
GET
http://1.2.3.4:8081/v1/vhosts/default/apps/app/outputProfiles/bypass_pr
ofile

Parameters

Path

vhost_name string

A name of VirtualHost

app_name string

A name of Application

profile_name string

A name of OutputProfile

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .
Responses

200

- Return type: Response<OutputProfile>


- Description
Returns the specified output profile information

404

- Return type: Response<>


- Description
Not Found

http://<OME_HOST>:<API_PORT>
P UT
/v1/vhosts/{vhost_name}/apps/{app_name}/outputProfiles/{profile_name}

/v1/vhosts/{vhost_name}/apps/{app_name}/outputProfiles/{profile_name}

Changes the configuration of the OutputProfile

Request Example:
PUT
http://1.2.3.4:8081/v1/vhosts/default/apps/app/outputProfiles/bypass_pr
ofile

{
"outputStreamName": "${OriginStreamName}",
"encodes": {
"videos": [
{
"codec": "h264",
"bitrate": "3M",
"width": 1280,
"height": 720,
"framerate": 30
}
],
"audios": [
{
"bypass": true
}
]
}
}

Parameters

Path

vhost_name string

A name of VirtualHost

app_name string

A name of Application

profile_name string

A name of OutputProfile

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Body

(json body) object

OutputProfile

Responses

200

- Return type: Response<OutputProfile>


- Description
Returns the modified output profile information

404

- Return type: Response<>


- Description
Not Found

http://<OME_HOST>:<API_PORT>
DE L E T E
/v1/vhosts/{vhost_name}/apps/{app_name}/outputProfiles/{profile_name}
/v1/vhosts/{vhost_name}/apps/{app_name}/outputProfiles/{profile_name}

Deletes the OutputProfile

Request Example:
DELETE
http://1.2.3.4:8081/v1/vhosts/default/apps/app/outputProfiles/bypass_pr
ofile

Parameters

Path

vhost_name string

A name of VirtualHost

app_name string

A name of Application

profile_name string

A name of OutputProfile

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Responses

200

- Return type: Response<>


- Description
Returns the result

404

- Return type: Response<>


- Description
Not Found
Recording

http://<OME_HOST>:<API_PORT>
POST
/v1/vhosts/{vhost_name}/apps/{app_name}:startRecord

/v1/vhosts/{vhost_name}/apps/{app_name}:startRecord

This API performs a recording start request operation. for recording, the output stream name must be
specified. file path, information path, recording interval and schedule parameters can be specified as
options.

Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps/app:startRecord
{
"id": "custom_id",
"stream": {
"name": "stream_o",
"tracks": [ 100, 200 ]
},
"filePath" : "/path/to/save/recorded/file_${Sequence}.ts",
"infoPath" : "/path/to/save/information/file.xml",
"interval" : 60000, # Split it every 60 seconds
"schedule" : "0 0 */1" # Split it at second 0, minute 0, every hours.
"segmentationRule" : "continuity"

Parameters

Path

vhost_name string

A name of VirtualHost

app_name string

A name of Application

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token

Body
segmentationRule string

Define the policy for continuously or discontinuously generating timestamp in divided recorded files.

- continuity
- discontinuity (default)

id string

An unique identifier for recording job.

stream string

Output stream.

name string

Output stream name.

tracks array

Default is all tracks. It is possible to record only a specific track using the track Id.

- default is all tracks

schedule string

Schedule based split recording. set only <second minute hour> using crontab method.
It cannot be used simultaneously with interval.

interval number

Interval based split recording. It cannot be used simultaneously with schedule.

filePath string

Set the path of the file to be recorded. same as setting macro pattern in Config file.

infoPath string

Set the path to the information file to be recorded. same as setting macro pattern in Config file.

Responses

200

400
http://<OME_HOST>:<API_PORT>
POST
/v1/vhosts/{vhost_name}/apps/{app_name}:stopRecord

/v1/vhosts/{vhost_name}/apps/{app_name}:stopRecord

This API performs a recording stop request.

Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps/app:stopRecord
{
"id": "custom_id"
}

Parameters

Path

vhost_name string

A name of VirtualHost

app_name string

A name of Application

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Body

id string

An unique identifier for recording job.

Responses

200

400
404

POST http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}:records

/v1/vhosts/{vhost_name}/apps/{app_name}:records

This API performs a query of the job being recorded. Provides job inquiry function for all or custom Id.

Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps/app:records
{
"id" : "custom_id"
}

Parameters

Path

vhost_name string

A name of VirtualHost

app_name string

A name of Application

Header

authorization string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Body

id string

An unique identifier for recording job. If no value is specified, the entire recording job is requested.

Responses

200

204
Push

POST http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}:startPush

/v1/vhosts/{vhost_name}/apps/{app_name}:startPush

This is an action to request a push of a selected stream. Please refer to the "Push" document for
detail setting.

Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps/app:startPush
{
"id": "{UserDefinedUniqueId}",
"stream": {
"name": "output_stream_name",
"tracks": [
101,
102 ]
},
"protocol": "rtmp",
"url":"rtmp://{host}[:port]/{appName}",
"streamKey":"{streamName}"
}

Parameters

Path

vhost_name* string

A name of VirtualHost

app_name* string

A name of Application

Header

authorization* string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token
Body

id* string

Unique identifier for push management. if there is no value, automatically created and returned

stream* string

Output stream for push

name* string

Output stream name

tracks string

Track id for want to push, if there is no value, all tracks are push

protocol* string

Transport protocol [rtmp | mpegts]

url* string

Destination URL

streamKey* object

Destination stream key

Responses

200

Success

400

Invalid Parameters

POST http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}:stopPush

/v1/vhosts/{vhost_name}/apps/{app_name}:stopPush

Request to stop pushing

Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps/app:stopRecord

{
"id": "{userDefinedUniqueId}"
}

Parameters

Path

vhost_name* string

A name of VirtualHost

app_name* string

A name of Application

Header

authorization* string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Body

id* string

Unique identifier for push management

Responses

200

Success

400

Invalid Parameters

404

No content

POST http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}:pushes
/v1/vhosts/{vhost_name}/apps/{app_name}:pushes

Get all push lists for a specific application

Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps/app:pushes

Parameters

Path

vhost_name* string

A name of VirtualHost

app_name* string

A name of Application

Header

authorization* string

A string for authentication in Basic Base64(AccessToken) format.


For example, Basic b21lLWFjY2Vzcy10b2tlbg== if access token is ome-access-token .

Responses

200

Success

204

Not Found

Statistics

Current

GET http://<OME_HOST>:<API_PORT>/v1/stats/current/vhosts/{vhost_name}
/v1/stats/current/vhosts/{vhost_name}

Usage statistics of the VirtualHost

Request Example:
GET http://1.2.3.4:8081/v1/stats/current/vhosts/default

Parameters

Path

vhost_name string

A name of VirtualHost

Query

access_token string

A token for authentication

Responses

200

Returns a statistics of the VirtualHost.

404

Not Found

http://<OME_HOST>:<API_PORT>
GET
/v1/stats/current/vhosts/{vhost_name}/apps/{app_name}

/v1/stats/current/vhosts/{vhost_name}/apps/{app_name}

Usage statistics of the Application

Request Example:
GET http://1.2.3.4:8081/v1/stats/current/vhosts/default/apps/app

Parameters

Path

vhost_name string
A name of VirtualHost

app_name string

A name of Application

Query

access_token string

A token for authentication

Responses

200

Returns a statistics of the Application.

404

Not Found

http://<OME_HOST>:<API_PORT>
GET
/v1/stats/current/vhosts/{vhost_name}/apps/{app_name}/streams/{stream}

/v1/stats/current/vhosts/{vhost_name}/apps/{app_name}/streams/{stream}

Usage statistics of the Stream

Request Example:
GET
http://1.2.3.4:8081/v1/stats/current/vhosts/default/apps/app/streams/{s
tream}

Parameters

Path

vhost_name string

A name of VirtualHost

app_name string

A name of Application

stream_name string
A name of Stream

Query

access_token string

A token for authentication

Responses

200

Returns a statistics of the Stream.

404

Not Found

Performance Tuning

Performance Test
OvenMediaEngine provides a tester for measuring WebRTC performance called OvenRtcTester. It is
developed in Go language and uses the pion/webrtc/v3 and gorilla/websocket modules. Many thanks to the
pion/webrtc and gorilla/websocket teams for contributing this wonderful project.

Getting Started OvenRtcTester

Install GO

Since OvenRtcTester is developed in Go language, Go must be installed on your system. Install Go from the
following URL: https://golang.org/doc/install

OvenRtcTester was tested with the latest version of go 1.17.

Run

You can simply run it like this: -url is required. If the -life option is not used, it will run indefinitely until the
user presses ctrl+c .

1 $ cd OvenMediaEngine/misc/oven_rtc_tester
2 $ go run OvenRtcTester.go
3 -url parameter is required and must be vaild. (input : undefined)
4
5 -cint int
[Optional] PeerConnection connection interval (milliseconds) (default 100)
6 -life int
7 [Optional] Number of times to execute the test (seconds)
8 -n int
9 [Optional] Number of client (default 1)
10 -sint int
11 [Optional] Summary information output cycle (milliseconds) (default 5000)
12 -url string
13 [Required] OvenMediaEngine's webrtc streaming URL (default "undefined")
14

You can also use go build or go install depending on your preference.

OvenRtcTester must test OvenMediaEngine 0.12.4 or higher as the target system.


OvenMediaEngine versions below 0.12.4 have a problem with incorrectly calculating the RTP
timestamp, so OvenRtcTester calculates the Video Delay value incorrectly.

1 $ go run OvenRtcTester.go -url ws://192.168.0.160:13333/app/stream -n 5


2 client_0 connection state has changed checking
3 client_0 has started
4 client_1 connection state has changed checking
5 client_1 has started
6 client_0 connection state has changed connected
7 client_1 connection state has changed connected
8 client_1 track has started, of type 100: video/H264
9 client_0 track has started, of type 100: video/H264
10 client_1 track has started, of type 101: audio/OPUS
11 client_0 track has started, of type 101: audio/OPUS
12 client_2 connection state has changed checking
13 client_2 has started
14 client_2 connection state has changed connected
15 client_2 track has started, of type 100: video/H264
16 client_2 track has started, of type 101: audio/OPUS
17 client_3 connection state has changed checking
18 client_3 has started
19 client_3 connection state has changed connected
20 client_3 track has started, of type 100: video/H264
21 client_3 track has started, of type 101: audio/OPUS
22 client_4 connection state has changed checking
23 client_4 has started
24 client_4 connection state has changed connected
25 client_4 track has started, of type 100: video/H264
26 client_4 track has started, of type 101: audio/OPUS
27 <Summary>
28 Running time : 5s
29 Number of clients : 5
30 ICE Connection State : New(0), Checking(0) Connected(5) Completed(0) Disconnected(0) Failed
31 Avg Video Delay(54.20 ms) Max Video Delay(55.00 ms) Min Video Delay(53.00 ms)
32 Avg Audio Delay(37.00 ms) Max Audio Delay(55.00 ms) Min Audio Delay(26.00 ms)
33
33
Avg FPS(30.15) Max FPS(30.25) Min FPS(30.00)
34 Avg BPS(4.1 Mbps) Max BPS(4.1 Mbps) Min BPS(4.0 Mbps)
35 Total Bytes(11.6 MBytes) Avg Bytes(2.3 MBytes)
36 Total Packets(13897) Avg Packets(2779)
37 Total Packet Losses(0) Avg Packet Losses(0)
38

39 <Summary>
40 Running time : 10s
41 Number of clients : 5
42 ICE Connection State : New(0), Checking(0) Connected(5) Completed(0) Disconnected(0) Failed
43 Avg Video Delay(43.60 ms) Max Video Delay(45.00 ms) Min Video Delay(42.00 ms)
44 Avg Audio Delay(36.60 ms) Max Audio Delay(55.00 ms) Min Audio Delay(25.00 ms)
45 Avg FPS(30.04) Max FPS(30.11) Min FPS(30.00)
46 Avg BPS(4.0 Mbps) Max BPS(4.0 Mbps) Min BPS(4.0 Mbps)
47 Total Bytes(24.3 MBytes) Avg Bytes(4.9 MBytes)
48 Total Packets(28832) Avg Packets(5766)
49 Total Packet Losses(0) Avg Packet Losses(0)
50
51 <Summary>
52 Running time : 15s
53 Number of clients : 5
54 ICE Connection State : New(0), Checking(0) Connected(5) Completed(0) Disconnected(0) Failed
55 Avg Video Delay(36.60 ms) Max Video Delay(38.00 ms) Min Video Delay(35.00 ms)
56 Avg Audio Delay(49.20 ms) Max Audio Delay(68.00 ms) Min Audio Delay(38.00 ms)
57 Avg FPS(30.07) Max FPS(30.07) Min FPS(30.07)
58 Avg BPS(4.0 Mbps) Max BPS(4.0 Mbps) Min BPS(4.0 Mbps)
59 Total Bytes(36.8 MBytes) Avg Bytes(7.4 MBytes)
60 Total Packets(43717) Avg Packets(8743)
61 Total Packet Losses(0) Avg Packet Losses(0)
62
63 ^CTest stopped by user
64 ***************************
65 Reports
66 ***************************
67 <Summary>
68 Running time : 15s
69 Number of clients : 5
70 ICE Connection State : New(0), Checking(0) Connected(5) Completed(0) Disconnected(0) Failed
71 Avg Video Delay(23.60 ms) Max Video Delay(25.00 ms) Min Video Delay(22.00 ms)
72 Avg Audio Delay(11.20 ms) Max Audio Delay(18.00 ms) Min Audio Delay(5.00 ms)
73 Avg FPS(30.07) Max FPS(30.07) Min FPS(30.07)
74 Avg BPS(4.0 Mbps) Max BPS(4.0 Mbps) Min BPS(4.0 Mbps)
75 Total Bytes(38.6 MBytes) Avg Bytes(7.7 MBytes)
76 Total Packets(45662) Avg Packets(9132)
77 Total Packet Losses(0) Avg Packet Losses(0)
78
79 <Details>
80 [client_0]
81 running_time(15s) connection_state(connected) total_packets(9210) packet_loss(0)
82 last_video_delay (22.0 ms) last_audio_delay (52.0 ms)
83 total_bytes(7.8 Mbytes) avg_bps(4.0 Mbps) min_bps(3.6 Mbps) max_bps(4.3 Mbps)
84 total_video_frames(463) avg_fps(30.07) min_fps(28.98) max_fps(31.00)
85
85
86 client_0 connection state has changed closed
87 client_0 has stopped
88 [client_1]
89 running_time(15s) connection_state(connected) total_packets(9210) packet_loss(0)
90 last_video_delay (22.0 ms) last_audio_delay (52.0 ms)
91 total_bytes(7.8 Mbytes) avg_bps(4.0 Mbps) min_bps(3.6 Mbps) max_bps(4.3 Mbps)
92 total_video_frames(463) avg_fps(30.07) min_fps(28.98) max_fps(31.00)
93
94 client_1 has stopped
95 [client_2]
96 running_time(15s) connection_state(connected) total_packets(9145) packet_loss(0)
97 last_video_delay (23.0 ms) last_audio_delay (63.0 ms)
98 total_bytes(7.7 Mbytes) avg_bps(4.0 Mbps) min_bps(3.6 Mbps) max_bps(4.5 Mbps)
99 total_video_frames(460) avg_fps(30.07) min_fps(28.97) max_fps(31.02)
100
101 client_1 connection state has changed closed
102 client_2 has stopped
103 [client_3]
104 running_time(15s) connection_state(connected) total_packets(9081) packet_loss(0)
105 last_video_delay (25.0 ms) last_audio_delay (65.0 ms)
106 total_bytes(7.7 Mbytes) avg_bps(4.0 Mbps) min_bps(3.6 Mbps) max_bps(4.3 Mbps)
107 total_video_frames(457) avg_fps(30.07) min_fps(29.00) max_fps(31.03)
108
109 client_2 connection state has changed closed
110 client_3 has stopped
111 client_3 connection state has changed closed
112 [client_4]
113 running_time(15s) connection_state(connected) total_packets(9016) packet_loss(0)
114 last_video_delay (26.0 ms) last_audio_delay (36.0 ms)
115 total_bytes(7.6 Mbytes) avg_bps(4.0 Mbps) min_bps(3.6 Mbps) max_bps(4.3 Mbps)
116 total_video_frames(454) avg_fps(30.07) min_fps(28.99) max_fps(31.02)
117
118 client_4 has stopped

Performance Tuning

Monitoring the usage of threads

Linux has various tools to monitor CPU usage per thread. We will check the simplest with the top command.
If you issue the top -H -p [pid] command, you will see the following screen.
You can use OvenRtcTester to test the capacity of the server as shown below. When testing the maximum
performance, OvenRtcTester also uses a lot of system resources, so test it separately from the system where
OvenMediaEngine is running. Also, it is recommended to test OvenRtcTester with multiple servers. For
example, simulate 500 players with -n 500 on one OvenRtcTester, and simulate 2000 players with four
servers.

Building and running OvenMediaEngine in debug mode results in very poor performance. Be sure
to test the maximum performance using the binary generated by make release && make install .

1 $ go run OvenRtcTester.go -url ws://192.168.0.160:13333/app/stream -n 100


2 client_0 connection state has changed checking
3 client_0 has started
4 client_0 connection state has changed connected
5 client_0 track has started, of type 100: video/H264
6
7 client_0
client_1 track has started,
connection ofchanged
state has type 101: audio/OPUS
checking
8 client_1 has started
9 client_1 connection state has changed connected
10 client_1 track has started, of type 100: video/H264
11 client_1 track has started, of type 101: audio/OPUS
12 client_2 connection state has changed checking
13 client_2 has started
14 client_2 connection state has changed connected
15 client_2 track has started, of type 100: video/H264
16 client_2 track has started, of type 101: audio/OPUS
17 ....
18 client_94 connection state has changed checking
19 client_94 has started
20 client_94 connection state has changed connected
21 client_94 track has started, of type 100: video/H264
22 client_94 track has started, of type 101: audio/OPUS
23 client_95 connection state has changed checking
24 client_95 has started
25 client_95 connection state has changed connected
26 client_95 track has started, of type 100: video/H264
27 client_95 track has started, of type 101: audio/OPUS
28 client_96 connection state has changed checking
29 client_96 has started
30 <Summary>
31 Running time : 10s
32 Number of clients : 97
33 ICE Connection State : New(0), Checking(1) Connected(96) Completed(0) Disconnected(0) Faile
34 Avg Video Delay(13.51 ms) Max Video Delay(47.00 ms) Min Video Delay(0.00 ms)
35 Avg Audio Delay(22.42 ms) Max Audio Delay(67.00 ms) Min Audio Delay(0.00 ms)
36 Avg FPS(27.20) Max FPS(32.51) Min FPS(0.00)
37 Avg BPS(3.7 Mbps) Max BPS(4.6 Mbps) Min BPS(0bps)
38 Total Bytes(238.7 MBytes) Avg Bytes(2.5 MBytes)
39 Total Packets(285013) Avg Packets(2938)
40 Total Packet Losses(306) Avg Packet Losses(3)

If the OvenMediaEngine's capacity is exceeded, you will notice it in OvenRtcTester's Summary report with
Avg Video Delay and Avg Audio Delay or Packet loss .
On the right side of the above capture screen, we simulate 400 players with OvenRtcTester. <Summary> of
OvenRtcTester shows that Avg Video Delay and Avg Audio Delay are very high, and Avg FPS
is low.

And on the left, you can check the CPU usage by thread with the top -H -p command. This confirms
that the StreamWorker threads are being used at 100%, and now you can scale the server by increasing the
number of StreamWorker threads. If OvenMediaEngine is not using 100% of all cores of the server, you can
improve performance by tuning the number of threads.

This is the result of tuning the number of StreamWorkerCount to 8 in config. This time, we simulated 1000
players with OvenRtcTester, and you can see that it works stably.

Tuning the number of threads

The WorkerCount in <Bind> can set the thread responsible for sending and receiving over the socket.
Publisher's AppWorkerCount allows you to set the number of threads used for per-stream processing such
as RTP packaging, and StreamWorkerCount allows you to set the number of threads for per-session
processing such as SRTP encryption.

1 <Bind>
2 <Providers>
3 <RTMP>
4 <Port>1935</Port>
5
5
<WorkerCount>1</WorkerCount>
6 </RTMP>
7 ...
8 </Providers>
9 ...
10 <Publishers>
11 <WebRTC>
12 <Signalling>
13 <Port>3333</Port>
14 <WorkerCount>1</WorkerCount>
15 </Signalling>
16 <IceCandidates>
17 <TcpRelay>*:3478</TcpRelay>
18 <IceCandidate>*:10000/udp</IceCandidate>
19 <TcpRelayWorkerCount>1</TcpRelayWorkerCount>
20 </IceCandidates>
21 ...
22 </Bind>
23
24 <Application>
25 <Publishers>
26 <AppWorkerCount>1</AppWorkerCount>
27 <StreamWorkerCount>8</StreamWorkerCount>
28 </Publishers>
29 </Application>

Scalable Threads and Configuration

Thread name Element in the configuration

AW-XXX <Application><Publishers><AppWorkerCount>

StreamWorker <Application><Publishers><StreamWorkerCount

<Bind><Provider><WebRTC><IceCandidates>
<TcpRelayWorkerCount>
SPICE-XXX
<Bind><Pubishers><WebRTC><IceCandidates>
<TcpRelayWorkerCount>

<Bind><Provider><WebRTC><Signalling>
<WorkerCount>
SPRtcSignalling
<Bind><Pubishers><WebRTC><Signalling>
<WorkerCount>

<Bind><Pubishers><HLS><WorkerCount>
SPSegPub
<Bind><Pubishers><DASH><WorkerCount>

SPRTMP-XXX <Bind><Providers><RTMP><WorkerCount>

SPMPEGTS <Bind><Providers><MPEGTS><WorkerCount>

SPOvtPub <Bind><Pubishers><OVT><WorkerCount>
SPSRT <Bind><Providers><SRT><WorkerCount>

AppWorkerCount

Type Value

Default 1

Minimum 1

Maximum 72

With AppWorkerCount , you can set the number of threads for distributed processing of streams when
hundreds of streams are created in one application. When an application is requested to create a stream,
the stream is evenly attached to one of created threads. The main role of Stream is to packetize raw media
packets into the media format of the protocol to be transmitted. When there are thousands of streams, it is
difficult to process them in one thread. Also, if StreamWorkerCount is set to 0, AppWorkerCount is
responsible for sending media packets to the session.

It is recommended that this value does not exceed the number of CPU cores.

StreamWorkerCount

Type Value

Default 8

Minimum 0

Maximum 72

It may be impossible to send data to thousands of viewers in one thread. StreamWorkerCount allows
sessions to be distributed across multiple threads and transmitted simultaneously. This means that
resources required for SRTP encryption of WebRTC or TLS encryption of HLS/DASH can be distributed
and processed by multiple threads. It is recommended that this value not exceed the number of CPU cores.

Use-Case

If a large number of streams are created and very few viewers connect to each stream, increase
AppWorkerCount and lower StreamWorkerCount as follows.

1 <Publishers>
2 <AppWorkerCount>32</AppWorkerCount>
3 <StreamWorkerCount>0</StreamWorkerCount>
4 </Publishers>

If a small number of streams are created and a very large number of viewers are connected to each stream,
lower AppWorkerCount and increase StreamWorkerCount as follows.

1 <Publishers>
2 <AppWorkerCount>1</AppWorkerCount>
3 <StreamWorkerCount>32</StreamWorkerCount>
4 </Publishers>

Logs and Statistics

Logs
To monitor the OvenMediaEngine, you can view in real-time the log files generated by itself. You can
configure a log type and level by creating the Logger.xml configuration file in the same location as
Server.xml.

You can set up Logger.xml as shown in the following example: OvenMediaEngine prints logs separated by
many tag names and levels. Set <Tag name=".*" level="debug"> to have OvenMediaEngine print
all logs and read the logs. And then it's better to disable tags that you don't need.

1 <Logger version="2">
2 <!-- Log file location -->
3 <Path>/var/log/ovenmediaengine</Path>
4
5 <!-- Disable some SRT internal logs -->
6 <Tag name="SRT" level="critical" />
7 <Tag name="Monitor" level="critical" />
8
9 <!-- Log level: [debug, info, warn, error, critical] -->
10 <Tag name=".*" level="info" />
11 </Logger>
12

OvenMediaEngine generates log files. If you start OvenMediaEngine by systemctl start


ovenmediaengine , the log file is generated to the following path.

1 /var/log/ovenmediaengine

If you run it directly from the command line, it will be generated to the following location:

1 /<OvenMediaEngine Binary Path>/log/

If you run it in the Docker container, the log file is in the following path:

1 # For Origin mode


2
2
/opt/ovenmediaengine/bin/log/
3 # For Edge mode
4 /opt/ovenmediaengine/bin/log/

Following is the example of real logs.

1 getroot@Jeheon-Main:/var/log/ovenmediaengine$ cat ovenmediaengine.log


2 [03-27 19:59:13.221] I 10996 Config | config_manager.cpp:144 | Trying to set logfile in di
3 [03-27 19:59:13.221] I 10996 Config | config_manager.cpp:47 | Trying to load configuratio
4 [03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:211 | OvenMediaEngine v0.9.5 (v0.9
5 [03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:213 | With modules:
6 [03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:214 | FFmpeg 3.4.2
7 [03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:215 | Configuration: --prefix=
8 [03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:216 | libavformat: 57.83.100
9 [03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:217 | libavcodec: 57.107.100
10 [03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:218 | libavutil: 55.78.100
11 [03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:219 | libavfilter: 6.107.100
12 [03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:220 | libswresample: 2.9.100
13 [03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:221 | libswscale: 4.8.100
14 [03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:222 | SRT: 1.3.3
15 [03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:223 | SRTP: libsrtp2 2.2.0
16 [03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:224 | OpenSSL: OpenSSL 1.1.0g 2
17 [03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:225 | Configuration: compiler
18 [03-27 19:59:13.240] I 10996 Monitor | monitoring.cpp:35 | Create HostMetrics(default) fo
19 [03-27 19:59:13.240] I 10996 OvenMediaEngine | main.cpp:148 | Trying to create a module Me
20 [03-27 19:59:13.240] I 10996 MediaRouter | media_router.cpp:40 | MediaRouter has been sta
21 [03-27 19:59:13.240] I 10996 OvenMediaEngine | main.cpp:151 | Trying to create a module RT
22 [03-27 19:59:13.244] I 10996 RtmpProvider | rtmp_provider.cpp:63 | RTMP Server has starte
23 [03-27 19:59:13.246] I 10996 Provider | provider.cpp:40 | RtmpProvider has been started.
24 [03-27 19:59:13.246] I 10996 OvenMediaEngine | main.cpp:152 | Trying to create a module OV
25 [03-27 19:59:13.248] I 10996 Provider | provider.cpp:40 | OvtProvider has been started.
26 [03-27 19:59:13.248] I 10996 OvenMediaEngine | main.cpp:153 | Trying to create a module RT
27 [03-27 19:59:13.250] I 10996 Provider | provider.cpp:40 | RtspcProvider has been started
28 [03-27 19:59:13.250] I 10996 OvenMediaEngine | main.cpp:154 | Trying to create a module RT
29 [03-27 19:59:13.250] I 10996 RtspProvider | rtsp_provider.cpp:40 | RTSP is disabled in th
30 [03-27 19:59:13.251] I 10996 OvenMediaEngine | main.cpp:157 | Trying to create a module T
31 [03-27 19:59:13.251] I 10996 Transcoder | transcoder.cpp:38 | Transcoder has been started
32 [03-27 19:59:13.251] I 10996 OvenMediaEngine | main.cpp:160 | Trying to create a module We
33 [03-27 19:59:13.251] I 10996 Signalling | rtc_signalling_server.cpp:74 | P2P is disabled
34 [03-27 19:59:13.258] I 10996 Ice | ice_port.cpp:89 | ICE port is bound to 0.0.0.0:10000/U
35 [03-27 19:59:13.260] I 10996 Ice | ice_port.cpp:89 | ICE port is bound to 0.0.0.0:10001/U
36 [03-27 19:59:13.261] I 10996 Ice | ice_port.cpp:89 | ICE port is bound to 0.0.0.0:10002/U
37 [03-27 19:59:13.263] I 10996 Ice | ice_port.cpp:89 | ICE port is bound to 0.0.0.0:10003/U
38 [03-27 19:59:13.264] I 10996 Ice | ice_port.cpp:89 | ICE port is bound to 0.0.0.0:10004/U
39 [03-27 19:59:13.266] I 10996 Ice | ice_port.cpp:89 | ICE port is bound to 0.0.0.0:10005/U
40 [03-27 19:59:13.266] I 10996 Publisher | publisher.cpp:15 | WebRTC Publisher has been sta
41 [03-27 19:59:13.266] I 10996 WebRTC | webrtc_publisher.cpp:89 | WebRTC Publisher has sta
42 [03-27 19:59:13.266] I 10996 Publisher | publisher.cpp:15 | WebRTC Publisher has been sta
43 [03-27 19:59:13.266] I 10996 OvenMediaEngine | main.cpp:161 | Trying to create a module HL
44 [03-27 19:59:13.273] I 10996 Publisher | segment_publisher.cpp:65 | HLS Publisher has sta
45 [03-27 19:59:13.273] I 10996 Publisher | publisher.cpp:15 | HLS Publisher has been starte
46 [03-27 19:59:13.275] I 10996 OvenMediaEngine | main.cpp:162 | Trying to create a module MP
47
47
[03-27 19:59:13.281] I 10996 Publisher | segment_publisher.cpp:65 | DASH Publisher has st
48 [03-27 19:59:13.281] I 10996 Publisher | publisher.cpp:15 | DASH Publisher has been start
49 [03-27 19:59:13.282] I 10996 OvenMediaEngine | main.cpp:163 | Trying to create a module Lo
50 [03-27 19:59:13.289] I 10996 Publisher | segment_publisher.cpp:65 | LLDASH Publisher has
51 [03-27 19:59:13.289] I 10996 Publisher | publisher.cpp:15 | LLDASH Publisher has been sta
52 [03-27 19:59:13.291] I 10996 OvenMediaEngine | main.cpp:164 | Trying to create a module OV
53 [03-27 19:59:13.294] I 10996 OVT | ovt_publisher.cpp:49 | Ovt Publisher has started liste
54 [03-27 19:59:13.294] I 10996 Publisher | publisher.cpp:15 | OVTPublisher has been started
55 [03-27 19:59:13.294] I 10996 OvenMediaEngine | main.cpp:169 | All modules are initialized
56 [03-27 19:59:13.294] I 10996 Orchestrator | orchestrator.cpp:856 | Trying to create an app
57 [03-27 19:59:13.294] I 10996 Monitor | host_metrics.cpp:52 | Create ApplicationMetrics(#d
58 [03-27 19:59:13.297] I 10996 Provider | application.cpp:30 | [#default#app] RTMP Provide
59 [03-27 19:59:13.297] I 10996 Provider | application.cpp:30 | [#default#app] OVT Provider
60 [03-27 19:59:13.297] I 10996 Provider | application.cpp:30 | [#default#app] RTSP Pull Pro
61 [03-27 19:59:13.297] I 10996 Provider | application.cpp:30 | [#default#app] RTSP Provide
62 [03-27 19:59:13.298] I 10996 TranscodeApplication | transcode_application.cpp:36 | [#defa
63 [03-27 19:59:13.300] I 10996 Publisher | application.cpp:26 | [#default#app] WebRTC Publi
64 [03-27 19:59:13.302] I 10996 Publisher | application.cpp:26 | [#default#app] HLS Publishe
65 [03-27 19:59:13.304] I 10996 Publisher | application.cpp:26 | [#default#app] DASH Publish
66 [03-27 19:59:13.305] I 10996 Publisher | application.cpp:26 | [#default#app] LLDASH Publi
67 [03-27 19:59:13.307] I 10996 Publisher | application.cpp:26 | [#default#app] OVT Publishe
68 [03-27 19:59:14.706] I 11002 RtmpProvider | rtmp_server.cpp:126 | A RTMP client has connec
69 [03-27 19:59:14.835] I 11002 RtmpProvider | rtmp_server.cpp:226 | [#default#app/stream] RT
70 [03-27 19:59:14.835] I 11002 MediaRouter.App | media_route_application.cpp:184 | Trying to
71 [03-27 19:59:14.836] I 11002 Monitor | stream.cpp:240 |
72 [Stream Info]
73 id(2921228900), name(stream), SourceType(Rtmp), Created Time (Fri Mar 27 19:59:14 2020)
74
75 Video Track #0: Bypass(false) Bitrate(2.50Mb) codec(1, avc) resolution(1280x720) f
76 Audio Track #1: Bypass(false) Bitrate(160.00Kb) codec(5, aac) samplerate(44.1K) fo
77 [03-27 19:59:14.836] I 11002 Monitor | application_metrics.cpp:56 | Create StreamMetrics
78 [03-27 19:59:14.836] I 11002 TranscodeStream | transcode_stream.cpp:353 | [#default#app/st
79 [03-27 19:59:14.839] I 11002 FFmpeg | third_parties.cpp:115 | [AVCodecContext] using SAR=
80 [03-27 19:59:14.841] I 11002 FFmpeg | third_parties.cpp:115 | [AVCodecContext] using cpu
81 [03-27 19:59:14.846] I 11002 FFmpeg | third_parties.cpp:115 | [AVCodecContext] profile Co
82 [03-27 19:59:14.849] I 11002 FFmpeg | third_parties.cpp:115 | [AVCodecContext] v1.7.0
83 [03-27 19:59:14.864] I 11048 MediaRouter.App | media_route_application.cpp:184 | Trying to
84 [03-27 19:59:14.864] I 11002 TranscodeStream | transcode_stream.cpp:108 | [#default#app/st
85 [03-27 19:59:14.865] I 11048 Monitor | stream.cpp:240 |
86 [Stream Info]
87 id(3169746412), name(stream_medium_o), SourceType(Transcoder), Created Time (Fri Mar 27 19
88 >> Origin Stream Info
89 id(2921228900), name(stream), SourceType(Rtmp), Created Time (Fri Mar 27 19:59:14 2
90
91 Video Track #0: Bypass(false) Bitrate(700.00Kb) codec(2, vp8) resolution(640x360) f
92 Video Track #1: Bypass(false) Bitrate(700.00Kb) codec(1, avc) resolution(640x360) f
93 Audio Track #2: Bypass(false) Bitrate(48.00Kb) codec(7, opus) samplerate(48.0K) fo
94 Audio Track #3: Bypass(false) Bitrate(48.00Kb) codec(5, aac) samplerate(48.0K) form
95 [03-27 19:59:14.865] I 11048 Monitor | application_metrics.cpp:56 | Create StreamMetrics
96 [03-27 19:59:14.865] I 11048 WebRTC | rtc_stream.cpp:181 | Unsupported codec(Audio/AAC) is
97 [03-27 19:59:14.880] I 11048 Publisher | stream.cpp:192 | [stream_medium_o(3169746412)] We
98 [03-27 19:59:14.881] I 11048 Publisher | stream.cpp:192 | [stream_medium_o(3169746412)] HL
99 [03-27 19:59:14.881] I 11048 Publisher | stream.cpp:192 | [stream_medium_o(3169746412)] DA
100
100
[03-27 19:59:14.881] I 11048 Publisher | stream.cpp:192 | [stream_medium_o(3169746412)] LL
101 [03-27 19:59:14.897] I 11048 Publisher | stream.cpp:192 | [stream_medium_o(3169746412)] OV
102 [03-27 19:59:14.898] I 11048 TranscodeCodec | transcode_codec_dec_aac.cpp:49 | [#default#
103 [03-27 19:59:14.985] I 11048 TranscodeCodec | transcode_codec_dec_avc.cpp:48 | [#default#

Statistics
OvenMediaEngine collects the following metrics for each host, application, and stream.

Bytes in/out by protocol

Connections by protocol

Maximum connections and time


Time is taken to connect to origin

You can get the current statistics using the REST API. See Stat API for the statistics REST API.

Files such as webrtc_stat.log and hls_rtsp_xxxx.log that were previously output are deprecated in
the current version. We are developing a formal stats file, which will be open in the future.

Test Player

We provide you our test player to make sure that OvenMediaEngine works well. Most browsers prohibit
access to the TLS-based HTTPS site through unsecured HTTP or WebSocket (WS) for security reasons.
Thus, we have prepared the HTTP or HTTPS based player as follows:

Site URL Description

A player without TLS that can test all streaming


http://demo.ovenplayer.com URLs such as WS:// , WSS:// , HTTP:// ,
HTTPS://

A player with TLS that can only test WSS:// and


https://demo.ovenplayer.com
HTTPS:// based streaming URLs
Delay option for Low-Latency DASH

When playing Low-Latency DASH, you can control the delay time in the player as shown below. Delay time
is closely related to the buffering size. The smaller the value, the shorter the latency, but if it is too small,
there is no buffer and playback may not be smooth. In a typical network environment, it is most stable to give
2 as the delay value.
Troubleshooting
We will update this document as we gather troubleshooting examples. (Written in Nov 04, 2021)

prerequisites.sh Script Failed


If you have problems with the prerequisites.sh the script we have provided, please install it manually
as follows.

Platform Specific Installation

Ubuntu 18
1 sudo apt install -y build-essential nasm autoconf libtool zlib1g-dev tclsh cmake cur

Fedora 28

1 sudo yum install -y gcc-c++ make nasm autoconf libtool zlib-devel tcl cmake

CentOS 7

1 # for downloading latest version of nasm (x264 needs nasm 2.13+ but centos provides
2 sudo curl -so /etc/yum.repos.d/nasm.repo https://www.nasm.us/nasm.repo
3 sudo yum install centos-release-scl
4 sudo yum install -y bc gcc-c++ cmake nasm autoconf libtool glibc-static tcl bzip2 zl
5 source scl_source enable devtoolset-7

Common Installation

Install OpenSSL
1 PREFIX=/opt/ovenmediaengine && \
2 OPENSSL_VERSION=1.1.0g && \
3 DIR=/tmp/openssl && \
4 mkdir -p ${DIR} && \
5 cd ${DIR} && \
6 curl -sLf https://www.openssl.org/source/openssl-${OPENSSL_VERSION}.tar.gz | tar -xz --stri
7 ./config --prefix="${PREFIX}" --openssldir="${PREFIX}" -Wl,-rpath="${PREFIX}/lib" shared no
8 make -j 4 && \
9 sudo make install_sw && \
10 rm -rf ${DIR} && \
11 sudo rm -rf ${PREFIX}/bin

Install SRTP
1 PREFIX=/opt/ovenmediaengine && \
2 SRTP_VERSION=2.2.0 && \
3 DIR=/tmp/srtp && \
4 mkdir -p ${DIR} && \
5 cd ${DIR} && \

6 curl -sLf https://github.com/cisco/libsrtp/archive/v${SRTP_VERSION}.tar.gz | tar -xz --stri


7 ./configure --prefix="${PREFIX}" --enable-shared --disable-static --enable-openssl --with-o
8 make shared_library -j 4 && \
9 sudo make install && \
10 rm -rf ${DIR}
Install SRT
1 PREFIX=/opt/ovenmediaengine && \
2 SRT_VERSION=1.3.3 && \
3 DIR=/tmp/srt && \
4 mkdir -p ${DIR} && \
5 cd ${DIR} && \
6 curl -sLf https://github.com/Haivision/srt/archive/v${SRT_VERSION}.tar.gz | tar -xz --strip
7 PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig:${PKG_CONFIG_PATH} ./configure --prefix="${PREFIX}"
8 make -j 4 && \
9 sudo make install && \
10 rm -rf ${DIR} && \
11 sudo rm -rf ${PREFIX}/bin

Install Opus
1 PREFIX=/opt/ovenmediaengine && \
2 OPUS_VERSION=1.1.3 && \
3 DIR=/tmp/opus && \
4 mkdir -p ${DIR} && \
5 cd ${DIR} && \
6 curl -sLf https://archive.mozilla.org/pub/opus/opus-${OPUS_VERSION}.tar.gz | tar -xz --stri
7 autoreconf -fiv && \
8 ./configure --prefix="${PREFIX}" --enable-shared --disable-static && \
9 make -j 4&& \
10 sudo make install && \
11 sudo rm -rf ${PREFIX}/share && \
12 rm -rf ${DIR}

Install x264
1 PREFIX=/opt/ovenmediaengine && \
2 X264_VERSION=20190513-2245-stable && \
3 DIR=/tmp/x264 && \
4 mkdir -p ${DIR} && \
5 cd ${DIR} && \
6 curl -sLf https://download.videolan.org/pub/videolan/x264/snapshots/x264-snapshot-${X264_VE
7 ./configure --prefix="${PREFIX}" --enable-shared --enable-pic --disable-cli && \
8 make -j 4&& \
9 sudo make install && \
10 rm -rf ${DIR}

Install VPX

1 PREFIX=/opt/ovenmediaengine && \
2 VPX_VERSION=1.7.0 && \
3 DIR=/tmp/vpx && \
4 mkdir -p ${DIR} && \
5
5
cd ${DIR} && \
6 curl -sLf https://codeload.github.com/webmproject/libvpx/tar.gz/v${VPX_VERSION} | tar -xz -
7 ./configure --prefix="${PREFIX}" --enable-vp8 --enable-pic --enable-shared --disable-static
8 make -j 4 && \
9 sudo make install && \
10 rm -rf ${DIR}

Install FDK-AAC
1 PREFIX=/opt/ovenmediaengine && \
2 FDKAAC_VERSION=0.1.5 && \
3 DIR=/tmp/aac && \
4 mkdir -p ${DIR} && \
5 cd ${DIR} && \
6 curl -sLf https://github.com/mstorsjo/fdk-aac/archive/v${FDKAAC_VERSION}.tar.gz | tar -xz -
7 autoreconf -fiv && \
8 ./configure --prefix="${PREFIX}" --enable-shared --disable-static --datadir=/tmp/aac && \
9 make -j 4&& \
10 sudo make install && \
11 rm -rf ${DIR}

Install FFMPEG
1 PREFIX=/opt/ovenmediaengine && \
2 FFMPEG_VERSION=3.4 && \
3 DIR=/tmp/ffmpeg && \
4 mkdir -p ${DIR} && \
5 cd ${DIR} && \
6 curl -sLf https://github.com/AirenSoft/FFmpeg/archive/ome/${FFMPEG_VERSION}.tar.gz | tar -x
7 PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig:${PKG_CONFIG_PATH} ./configure \
8 --prefix="${PREFIX}" \
9 --enable-gpl \
10 --enable-nonfree \
11 --extra-cflags="-I${PREFIX}/include" \
12 --extra-ldflags="-L${PREFIX}/lib -Wl,-rpath,${PREFIX}/lib" \
13 --extra-libs=-ldl \
14 --enable-shared \
15 --disable-static \
16 --disable-debug \
17 --disable-doc \
18 --disable-programs \
19 --disable-avdevice --disable-dct --disable-dwt --disable-error-resilience --disable-lsp --d
20 --disable-everything \
21 --enable-zlib --enable-libopus --enable-libvpx --enable-libfdk_aac --enable-libx264 \
22 --enable-encoder=libvpx_vp8,libvpx_vp9,libopus,libfdk_aac,libx264 \
23 --enable-decoder=aac,aac_latm,aac_fixed,h264 \

24 --enable-parser=aac,aac_latm,aac_fixed,h264 \
25 --enable-network --enable-protocol=tcp --enable-protocol=udp --enable-protocol=rtp --enable
26 --enable-filter=asetnsamples,aresample,aformat,channelmap,channelsplit,scale,transpose,fps
27 make && \
28 sudo make install && \
29 sudo rm -rf ${PREFIX}/share && \
30 rm -rf ${DIR}

Install JEMALLOC
1 PREFIX=/opt/ovenmediaengine && \
2 JEMALLOC_VERSION=5.2.1 && \
3 DIR=${TEMP_PATH}/jemalloc && \
4 mkdir -p ${DIR} && \
5 cd ${DIR} && \
6 curl -sLf https://github.com/jemalloc/jemalloc/releases/download/${JEMALLOC_VERSION}/jemall
7 ./configure --prefix="${PREFIX}" && \
8 make && \
9 sudo make install_include install_lib && \
10 rm -rf ${DIR}

systemctl start ovenmediaengine failed

Check SELinux

If SELinux is running on your system, SELinux can deny the execution of OvenMediaEngine.

1 # Example of SELinux disallow OvenMediaEngine execution


2 $ systemctl start ovenmediaengine
3 ==== AUTHENTICATING FOR org.freedesktop.systemd1.manage-units ====
4 Authentication is required to start 'ovenmediaengine.service'.
5 Authenticating as: Jeheon Han (getroot)
6 Password:
7 ==== AUTHENTICATION COMPLETE ====
8 Failed to start ovenmediaengine.service: Unit ovenmediaengine. service not found.
9 # Check if SELinux is enabled
10 $ sestatus
11 SELinux status: enabled
12 SELinuxfs mount: /sys/fs/selinux
13 SELinux root directory: /etc/selinux
14 Loaded policy name: targeted
15 Current mode: enforcing
16 Mode from config file: enforcing
17 Policy MLS status: enabled
18 Policy deny_unknown status: allowed
19 Memory protection checking: actual (secure)
20 Max kernel policy version: 31
21 # Check if SELinux denies execution
22 $ sudo tail /var/log/messages
23 ...
24 May 17 12:44:24 localhost audit[1]: AVC avc: denied { read } for pid=1 comm="systemd" na
25 May 17 12:44:24 localhost audit[1]: AVC avc: denied { read } for pid=1 comm="systemd" na
26
You can choose between two methods of adding a policy to SELinux or setting SELinux to permissive
mode. To add a policy, you must apply the SELinux policy file for the OvenMediaEngine service to your
system as follows:

1 $ cd <OvenMediaEngine Git Clone Root Path>


2 $ sudo semodule -i misc/ovenmediaengine.pp
3 $ sudo touch /.autorelabel
4 # If you add a policy to SELinux, you must reboot the system.
5 $ sudo reboot

Setting SELinux to permissive mode is as simple as follows. But we don't recommend this method.

1 $ sudo setenforce 0

Streaming is not smooth

1. If you are using Transcoding as Bypass in OvenMediaEngine, and streaming does not work in all
players

WebRTC does not support the b-frame of H.264. However, suppose the encoder you are using is
transmitting a stream with b-frames. In that case, you can solve this problem by changing your encoder
settings,
How to set the option to exclude b-frames in OBS, which is the most used encoder

Or by activating the encoding options in OvenMediaEngine.

Setting up Transcoding options in OvenMediaEngine:


https://airensoft.gitbook.io/ovenmediaengine/transcoding#encodes

2. When streaming does not work in some players

In this case, you are probably trying to stream with UDP in an environment where packet loss is high due to
network performance, connection problems, etc., the interruption during stream playback may more and
more worsen. This problem can be solved simply by playing with WebRTC/TCP.

If you want to monitor packet loss in your Chrome browser, you can access it by typing 'chrome://webrtc-
internals' in the address bar.

Setting up WebRTC over TCP in OvenMediaEngine:


https://airensoft.gitbook.io/ovenmediaengine/streaming/webrtc-publishing#webrtc-over-tcp

Also, if the device's network speed, which is running the player, isn't fast enough to accommodate the
stream's BPS, the stuttering during streaming won't resolve and will eventually drop the connection. In this
case, there is no other way than to speed up your network.

3. When streaming fails due to excessive CPU/Memory/Network usage of Origin in OvenMediaEngine

If the Origin server uses excessive CPU/Memory/Network, all players may experience stuttering during
streaming.

When you see Origin is CPU intensive on your Origin-Edge structure, the transcoding options in the
OvenMediaEngine may be the primary cause. That is, you may have set the quality of the input stream too
high, or the output stream to exceed the capabilities of your hardware significantly. In this case, it can be
solved by enabling the hardware encoder in OvenMediaEngine.

Setting up GPU Acceleration in OvenMediaEngine:


https://airensoft.gitbook.io/ovenmediaengine/transcoding/gpu-usage

4. When streaming fails due to excessive CPU/Memory/Network usage of Edge in OvenMediaEngine

If the edge server excessively uses CPU/Memory/Network, the player connected to that Edge may
experience stuttering during streaming. In this case, it can be solved by expanding Edge.
5. If you have enough CPU/Memory/Network, but streaming is not smooth

5-1. When a specific thread is using the CPU excessively

When you see a specific thread overuses the CPU, the video may not stream smoothly. Please refer to the
manual below for more information on this.

Tuning OvenMediaEngine Performance:


https://airensoft.gitbook.io/ovenmediaengine/performance-tuning#performance-tuning

5-2. Tuning your Linux kernel

The Linux kernel, which is set by default, cannot handle 1Gbps output, so put it as follows:

1 [ec2-user@ip-172-31-56-213 ~]$ cat /etc/sysctl.conf


2 fs.file-max = 100000
3 net.core.somaxconn = 65535
4 net.ipv4.tcp_max_tw_buckets = 1440000
5 net.ipv4.ip_local_port_range = 1024 65000
6 net.ipv4.tcp_fin_timeout = 15
7 net.ipv4.tcp_window_scaling = 1
8 net.ipv4.tcp_max_syn_backlog = 3240000
9 net.core.rmem_max = 16777216
10 net.core.wmem_max = 16777216
11 net.core.rmem_default = 16777216
12 net.core.wmem_default = 16777216
13 net.core.optmem_max = 40960
14 net.ipv4.tcp_rmem = 4096 87380 16777216
15 net.ipv4.tcp_wmem = 4096 65536 16777216
16 net.core.netdev_max_backlog = 50000
17 net.ipv4.tcp_max_syn_backlog = 30000
18 net.ipv4.tcp_max_tw_buckets = 2000000
19 net.ipv4.tcp_tw_reuse = 1
20 net.ipv4.tcp_fin_timeout = 10
21 net.ipv4.tcp_slow_start_after_idle = 0
22
23 [ec2-user@ip-172-31-56-213 ~]$ cat /etc/security/limits.conf
24 * soft nofile 1048576
25 * hard nofile 1048576

5-3. Congestion Control: Change to BBR

The mobile environment used by many people uses a wireless network. It has a high network speed but,
conversely, can cause high packet loss.

Look, CUBIC, the Congestion Control set by default in your Linux, adjusts the TCP Window by packet loss,
so it is not suitable to provide stable streaming in such an environment.
Source: iccrg-bbr-congestion-control-02.pdf (Page 18)

So our suggestion is to use Google's BBR. This setting is even more important if you mainly provide
WebRTC services to mobile users who use a wireless network. Change the Congestion Control from
CUBIC to BBR on your Linux.

Player connection fails

1. Due to the Mixed Contents

If you try to access OvenMediaEngine's WebRTC URL starting with ws:// (Non-TLS) from an HTTPS
(HTTP/TLS) site, the connection may be rejected due to a mixed content problem depending on the
browser.

In this case, you can solve this by installing a certificate in OvenMediaEngine and trying to connect with the
wss:// (WebSocket/TLS) URL.

Setting up TLS Encryption in OvenMediaEngine:


https://airensoft.gitbook.io/ovenmediaengine/streaming/tls-encryption

2. Due to a Cross-Origin Resource Sharing (CORS) Error

As of October 2021, most browsers have enforced the CORS policy, and CORS errors often occur when
requesting access to other domains if it is not a TLS site. In this case, you can solve the problem by
installing a certificate on the site that loads the player.

3. When the message "Too many open files" appears in the log, the player cannot connect
At some point, when the message "Too many open files" is output in your OvenMediaEngine log, it may
not be able to handle any more player connections. In this case, you can solve the problem by setting it as
follows:

1 [ec2-user@ip-172-31-56-213 ~]$ cat /etc/security/limits.conf


2 * soft nofile 1048576
3 * hard nofile 1048576

Player takes a long time first to load while trying to stream

1. Due to the Keyframe Interval

If you use Transcoding as Bypass in OvenMediaEngine and set a long keyframe interval in the encoder,
the WebRTC player cannot start streaming until a keyframe is an input.

In this case, you can solve this by setting the keyframe interval in the encoder to 1-2 seconds,

How to set the keyframe intverval in OBS, which is the most used encoder
Or by enabling the encoding options in OvenMediaEngine

Setting up Transcoding options in OvenMediaEngine:


https://airensoft.gitbook.io/ovenmediaengine/transcoding#encodes

A/V is out of sync

1. When the A/V sync does not match during initial streaming, and it gradually fits

A/V may not be input evenly from the encoder. There are some encoders with policies for reliable streaming
that they decide, for example, sending audio first and video very later, or video first and audio very late.

OvenMediaEngine outputs the input received from the encoder as-is for sub-second latency streaming. The
WebRTC player also streams the received input as-is, so the A/V sync may not match during the initial
playback due to the policy of specific encoders.

However, this can be resolved naturally as the player will sync A/V while streaming based on Timestamp.
Still, if this work looks like an error, you can also solve it by enabling JitterBuffer in OvenMediaEngine.

Also, suppose you are using a transcoder in OvenMediaEngine and trying to input with b-frames of H264.
Audio is encoded fast, but a video is buffered at the decoder because of b-frames. Therefore, there is a time
difference at the start of each encoding, which may cause the A/V to be out of sync. Even in this case,
enabling JitterBuffer will solve this problem.

Setting up WebRTC JitterBuffer in OvenMediaEngine:


https://airensoft.gitbook.io/ovenmediaengine/streaming/webrtc-publishing#publisher

2. Time has passed, but A/V is out of sync

There may be cases where the A/V sync is not corrected even after a certain amount of time has elapsed
after playback. This problem is caused by small internal buffers in some browsers such as Firefox, which
causes the player to give up calibration if the A/V sync differs too much. But this can also be solved by
enabling JitterBuffer.

Setting up WebRTC JitterBuffer in OvenMediaEngine:


https://airensoft.gitbook.io/ovenmediaengine/streaming/webrtc-publishing#publisher

Nevertheless, if the A/V sync is not corrected, you should suspect an error in the original video file, which
can be checked by playing as HLS.

However, if A/V sync is well during streaming with HLS, this is OvenMediaEnigne's bug. If you find any
bugs, please feel free to report them to OvenMediaEngine GitHub Issues.
No audio is output

1. When Opus is not set in the encoding options

WebRTC supports Opus, not AAC, as an audio codec. Because RTMP and other protocols mainly use and
transmit AAC as the audio codec, you may not have set up Opus, but WebRTC cannot output audio without
Opus. This can be solved by setting Opus in OvenMediaEnigne.

Setting up Opus Codec in OvenMediaEngine:


https://airensoft.gitbook.io/ovenmediaengine/transcoding#audio

Not the video quality you want

1. When video encoding is enabled in OvenMediaEngine

If you are using video encoding in OME, the video bitrate may be set low. In this case, the video quality can
be improved by increasing the unit of video bitrate.

However, since OvenMediaEngine has the default to the fastest encoding option for sub-second latency
streaming, the video quality may not be as good as the set video bitrate. In this case, OvenMediaEngine
provides an output profile preset that can control the quality, so you can choose to solve it.

Choosing an Encoding Preset in OvenMediaEngine:


https://airensoft.gitbook.io/ovenmediaengine/transcoding#video

2. If you are using Transcoding as Bypass in OvenMediaEngine

Since the encoder is transmitting video to OvenMediaEngine in low quality, you can solve it by increasing
the input quality in the encoder settings.

P2P Delivery (Experiment)

OvenMediaEngine provides P2P Delivery to be able to distribute Edge Traffic to Player. This feature is
currently the Preview version, and if you want to use it, you need only to use OvenPlayer. Moreover, we plan
to perform more experiments in various real-world and then upgrade it to the full version in
OvenMediaEngine.
First of all, we have rules. The peer that sends the Traffic in the P2P network is called a Host Peer, and the
peer that receives the Traffic from the Host Peer is called a Client Peer. Also, P2P Delivery in
OvenMediaEngine doesn't designate the Client Peer as the Host Peer again. In other words, it only operates
as 1 Depth.

What are the benefits of using P2P Delivery?


According to our experiments so far, P2P Delivery provides the best performance and stability when using 1
Depth to connect between Players and connecting up to two Players to one Player.

In other words, P2P Delivery has distributed two-thirds of existing Traffic. So, this means that it can expand
the Capacity of the Edge Network by three times and reduce Traffic costs by two-thirds.

How does it work?


You can use the P2P function of OvenMediaEngine by adding the <P2P> element as the following
settings:

Server.xml
1 <Server version="...">
2 ...
3 <P2P>
4 <MaxClientPeersPerHostPeer>2</MaxClientPeersPerHostPeer>
5 </P2P>
6 ...
7 </Server>

Also, If you want to use P2P Delivery when your OvenMediaEngine is running in Origin-Edge Cluster-Mode,
you need to apply this setting to all the Edges. You can instantly test P2P Delivery with OvenPlayer.

<MaxClientPeersPerHostPeer> sets the number of Client Peers connecting to one Host Peer.
How does it classify Peers?
When OvenMediaEngine receives a WebRTC connection request from a new player, it determines the Host
Peer or Client Peer according to the following rules:

Qualification for Host Peer Qualification for Client Peer

The device isn't Mobile


One of the Host Peers uses the same kind of
OS isn't Linux
browser
Browser isn't MS Edge Browser
Host Peer is vacant
Browser isn't Unknown Browser

When any Host Peer is disconnected, OvenMediaEngine detects this situation and immediately
reconnects the Client Peer connected to that Host Peer to the Edge to ensure stability.
Also, we are preparing a smarter algorithm based on user location, platform performance, and
network statistical information for classifying Host Peers or Client Peers.

If you have a better idea, we hope that you improve our code and contribute to our project. Please visit
OvenMediaEngine GitHub.

https://github.com/AirenSoft/OvenMediaEngine/blob/master/src/projects/rtc_signalling/p2p/
github.com

You might also like