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

Run OvenMediaEngine

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

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

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

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

Run OvenPlayer Demo

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

Publishing

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

The RTMP publishing address is :

Server rtmp://{Your Docker Host}:1935/app

Stream Key stream

The settings below are recommended for ultra-low latency.

Playback

Open the installed OvenPlayer Demo page in your browser.

http://{Your Docker Host}:8090/

WebRTC Playback

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

LLHLS Playback

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

What is OvenMediaEngine?

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

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

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

Features

• Ingest

  • Push: WebRTC, WHIP (Simulcast), SRT, RTMP, E-RTMP, MPEG-2 TS

  • Pull: RTSP

  • Scheduled Channel (Pre-recorded Live)

  • Multiplex Channel (Duplicate stream / Mux tracks)

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

• Low-Latency Streaming using LLHLS

  • DVR (Live Rewind)

  • Dump for VoD

  • ID3v2 timed metadata

  • DRM (Widevine, Fairplay)

• Sub-Second Latency Streaming using WebRTC

  • WebRTC over TCP (with embedded TURN server)

  • Embedded WebRTC Signaling Server (WebSocket based)

  • Retransmission with NACK

  • ULPFEC (Uneven Level Protection Forward Error Correction)

    • VP8, H.264, H.265

  • In-band FEC (Forward Error Correction)

    • Opus

• HLS (version 3) Streaming support for legacy devices

  • MPEG-2 TS Container

  • Audio/Video Muxed

  • DVR (Live Rewind)

• Sub-Second Latency Streaming using SRT

  • Secure Reliable Transport

  • MPEG-2 TS Container

  • Audio/Video Muxed

• Enhanced RTMP (E-RTMP) for Advanced Codec Support

  • H.264, H.265, AAC

  • More codec support will be added continuously

• Embedded Live Transcoder

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

  • Audio: Opus, AAC, Pass-through

• Clustering (Origin-Edge Structure)

• Monitoring

• Access Control

  • AdmissionWebhooks

  • SignedPolicy

• File Recording

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

• Thumbnail

• REST API

Supported Platforms

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

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

• Ubuntu 18+

• Rocky Linux 9+

• AlmaLinux 9+

• Fedora 28+

Getting Started

Please read Getting Started chapter in the tutorials.

How to Contribute

Thank you so much for being so interested in OvenMediaEngine.

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

• Finding Bugs

• Reviewing Code

• Sharing Ideas

• Testing

• Improving Documentation

• Spreading & Use Cases

• Recurring Donations

We always hope that OvenMediaEngine will give you good inspiration.

For more information

• OvenMediaEngine GitHub

• OvenMediaEngine Website

• OvenMediaEngine Tutorial Source

• Test Player

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

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

• OvenPlayer Github

• AirenSoft Website

License

OvenMediaEngine is licensed under the AGPL-3.0-only. However, if you need another license, please feel free to email us at [email protected].

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.

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.

CrossDomain settings are available for HTTP-based APIs, HLS, LLHLS, and Thumnail.

<CrossDomains>
    <Url>*</Url>
    <Url>*.airensoft.com</Url>
    <Url>http://*.ovenplayer.com</Url>
    <Url>https://demo.ovenplayer.com</Url>
    <Header>
        <Key>Access-Control-Expose-Headers</Key>
        <Value>Date, Server, Content-Type, Content-Length</Value>
    </Header>
    <Header>
        <Key>custom-header</Key>
        <Value>airensoft</Value>
    </Header>
</CrossDomains>

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

You can respond with custom HTTP headers via <CrossDomains>. You can use them by adding multiple <Header>/<Key> and <Header>/<Value> as in the example above.

Player & WebRTC Encoder

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

OvenSpace

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

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

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

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

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:

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:

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

For live streaming of certain events, it may be necessary to immediately stop the HLS live stream and switch to VoD after the HLS live broadcast ends. This API transitions to VoD by stopping segment updates for LL-HLS and HLS streams and inserting #EXT-X-ENDLIST. By using this API with a , you can implement additional application services.

Request

Responses

OvenMediaEngine supports Live Transcoding for Adaptive Bitrate(ABR) streaming and protocol compatibility. Each protocol supports different codecs, and ABR needs to change resolution and bitrate in different ways. Using OutputProfile, codecs, resolutions, and bitrates can be converted, and ABR can be configured as a variety of sets using a Playlist.

This document explains how to configure encoding settings, set up playlists.

Transcoding

This section explains how to define output streams, change the codec, bitrate, resolution, frame rate, sample rate, and channels for video/audio, as well as how to use the bypass method.

Adaptive Bitrate (ABR) Stream

This section explains how to use a Playlist to assemble ABR streams by selecting tracks encoded in various qualities.

TranscodeWebhook

The transcoding webhook feature is used when dynamic changes to encoding and ABR configuration are needed based on the type or quality of the input stream.

Support Codecs

These are the types of supported decoding and encoding codecs.

Hardware accelerators

These are the types of hardware accelerators officially supported.

• NVIDIA GPU

• Xilinx Alveo U30 MA

• NILOGAN (experiment)

• Quick Sync Video (deprecated)

Adaptive Bitrate Streaming (ABR)

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

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

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

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

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

http[s]://<domain>[:port]/<app>/<stream>/<FileName>.m3u8?format=ts

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

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

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

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

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

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

Supported codecs by streaming protocol

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

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

Therefore, you set it up as shown in the table. If you want to stream using LLHLS, you need to set up H.264, H.265 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.

Getting Started with Docker Image

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

Getting Started with Source Code

Installing dependencies

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

Building & Running

You can build the OvenMediaEngine source using the following command:

Ports used by default

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

You can open firewall ports as in the following example:

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.

Docker

To link certificates from your Docker host, uncomment the example in the Docker compose file or manually connect a volume in the Docker run command, e.g. -v ~/local/cert/path:/opt/ovenmediaengine/bin/certs You can set the port for <TLS> in <TLSPort>. Currently, LLHLS and WebRTC Signaling support TLS.

Add your certificate files to as follows:

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

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

Let's Encrypt,

If you used certbot to create your certificates, the PEM files it creates can be linked in your Server.xml like this:

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

Configuration

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

Bind

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

Stream mapping

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

Publish

This is an example of publishing using FFMPEG.

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

Pulling streams using the Stream Creation API

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

Pulling streams using the OriginMapStore

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

Pulling streams using the OriginMap

Configuration

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

For example, in the above setup, when a player requests ws://{OvenMediaEngine Host}[:{Signaling Port}]/}App Name}/{RTSP Stream Name} to stream WebRTC, it pulls the stream from rtsp://192.168.0.200:554 and publishes it to WebRTC.

Event to trigger pulling

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

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

Reload All Certificates

Batch reload certificates of all Virtual Hosts. In case of failure, the existing certificate will continue to be used.

Request

Responses

Reload Certificate

Reload the certificate of the specified Virtual Hosts. In case of failure, the existing certificate will continue to be used.

Request

Responses

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

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

Configuration

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

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

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

Mux file format

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

OutputStream This is information about the stream to be newly created. It must be the same as the file name. {Stream Name}.mux

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

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

REST API

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

It allows you to insert events into streams. Right now events only support the ID3v2 format and only the LLHLS publisher handles it. Events delivered to LLHLS Publisher are inserted as emsg boxes within the m4s container.

Request

Responses

RTMP is one of the most widely used protocols in live streaming.

Configuration

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

<!-- /Server/Bind/Providers -->
<Providers>
    ...
    <RTMP>
        <Port>1935</Port>
        ...
    </RTMP>
    ...
</Providers>

<!-- /Server/VirtualHosts/VirtualHost/Applications/Application -->
<Providers>
    ...
    <RTMP />
    ...
</Providers>

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:

<!-- /Server/VirtualHosts/VirtualHost/Applications/Application -->
<Providers>
    <RTMP>
        <BlockDuplicateStreamName>true</BlockDuplicateStreamName>
        ...
    </RTMP>
</Providers>

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

<BlockDuplicateStreamName> works with the following rules:

Publish

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

• URL: rtmp://{OME Host}[:{RTMP Port}]/{App Name}

• Stream Key: {Stream Name}

If you use the default configuration, the {RTMP Port} 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://{OME Host}[:{RTMP 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.

E-RTMP

Enhanced RTMP (E-RTMP) is an experimental streaming feature that extends the capabilities of the traditional RTMP protocol. One of its key advantages is support for modern video codecs such as H.265 (HEVC), which are not available in standard RTMP. This allows for better video quality and lower bitrates, making it ideal for high-efficiency streaming workflows. The list of supported codecs will continue to grow as development progresses.

Since E-RTMP is still experimental, it is disabled by default and must be manually enabled in the server settings.

How to Enable E-RTMP

To enable E-RTMP, you need to update the Server.xml configuration file. Add the following configuration:

<Server>
    ...
    <Modules>
        ...
        <ERTMP>
            <Enable>true</Enable>
        </ERTMP>
        ...
    </Modules>
    ...
</Server>

Publish with OBS

To stream with E-RTMP using OBS, select an encoder that supports HEVC in the Video Encoder section of the Output settings as shown below:

OvenMediaEngine supports Push Publishing function that can restreaming live streams to other systems. The protocol supports widely used protocols such as SRT, RTMP, and MPEG-2 TS.

The StreamMap feature has been added, and it now automatically re-streaming based on predefined conditions. You can also use the Rest API to control and monitor it.

Configuration

Push Publisher

To use Push Publishing, you need to declare the <Push> publisher in the configuration. <StreamMap> is optional. It is used when automatic push is needed.

<Applications>
  <Application>
     ...
    <Publishers>
      ... 
      <Push>
         <!-- [Optional] -->
         <StreamMap>
           <Enable>false</Enable>
           <Path>path/to/map.xml</Path>
         </StreamMap>
      </Push>
      ...
    </Publishers>
  </Application>
</Applications>

StreamMap

<StreamMap> is used for automatically pushing content based on user-defined conditions. The XML file path should be specified relative to <ApplicationPath>/conf.

<StreamName> is used to match output stream names and supports the use of wildcard characters. <VariantNames> can be used to select specific tracks. Multiple variants can be specified using commas (','). The <Protocol> supports rtmp, mpegts, and srt. You enter the destination address in the <Url> and <StreamKey> field, where macros can also be used.

<?xml version="1.0" encoding="UTF-8"?>
<PushInfo>
  <Push>
    <!-- [Must] -->
    <Enable>true</Enable>
    <!-- [Must] -->
    <StreamName>stream_a_*</StreamName>
    <!-- [Optional] -->
    <VariantNames>video_h264,audio_aac</VariantNames>
    <!-- [Must] -->
    <Protocol>rtmp</Protocol>
    <!-- [Must] -->
    <Url>rtmp://1.2.3.4:1935/app/${SourceStream}</Url>
    <!-- <Url>rtmp://1.2.3.4:1935/app/${Stream}</Url> -->
    <!-- [Optional] -->
    <StreamKey></StreamKey>
    <!-- <StreamKey>some-stream-key</StreamKey> -->
  </Push>  
  <Push>
    <!-- [Must] -->
    <Enable>true</Enable>
    <!-- [Must] -->
    <StreamName>stream_b_*</StreamName>
    <!-- [Optional] -->
    <VariantNames></VariantNames>
    <!-- [Must] -->
    <Protocol>srt</Protocol>
    <!-- [Must] -->
    <Url>srt://1.2.3.4:9999?streamid=srt%3A%2F%2F1.2.3.4%3A9999%2Fapp%2Fstream</Url>
  </Push>      
  <Push>
    <!-- [Must] -->
    <Enable>false</Enable>
    <!-- [Must] -->
    <StreamName>stream_c_*</StreamName>
    <!-- [Optional] -->
    <VariantNames></VariantNames>
    <!-- [Must] -->
    <Protocol>mpegts</Protocol>
    <!-- [Must] -->
    <Url>udp://1.2.3.4:2400</Url>
  </Push>    
</PushInfo>

REST API

Push can be controlled using the REST API. Please refer to the documentation below for more details.

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.

<Bind>
    <Publishers>
      ...
        <Thumbnail>
            <Port>20080</Port>
            <!-- If you need TLS support, please uncomment below:
            <TLSPort>20081</TLSPort>
            -->
        </Thumbnail>
    </Publishers>
</Bind>

Encoding

To publish thumbnails, you need to set up an encoding profile. You can choose JPG, PNG and WEBP as the format. You can set the Framerate and Resolution. Please refer to the sample below.

<OutputProfiles>
    <OutputProfile>
        <Name>default_stream</Name>
        <OutputStreamName>${OriginStreamName}_preview</OutputStreamName>
        <Encodes>
            <Image>
                <Codec>jpeg</Codec>
                <Framerate>1</Framerate>
                <Width>1280</Width>
                <Height>720</Height>
            </Image>
            <Image>
                <Codec>png</Codec>
                <Framerate>1</Framerate>
                <Width>1280</Width>
                <Height>720</Height>
            </Image>
            <Image>
                <Codec>webp</Codec>
                <Framerate>1</Framerate>
                <Width>1280</Width>
                <Height>720</Height>
            </Image>            
        </Encodes>
    </OutputProfile>
</OutputProfiles>

Supported image codecs

Publisher

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

<Publishers>
    ...
    <Thumbnail>
        <CrossDomains>
            <Url>*</Url>
        </CrossDomains>	
    </Thumbnail>
</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.

Advanced

Keyframes Decoding Only

For use cases without video (re)encoding, OME can be set to only decode the keyframes of incoming streams. This is a massive performance increase when all you are using the encoder for is generating thumbnails.

<OutputProfiles>
<!-- Common setting for decoders. Decodes is optional. -->
	<Decodes>
	<!-- 
	By default, OME decodes all video frames. 
	With OnlyKeyframes, only keyframes are decoded,
	massively improving performance.
	Thumbnails are generated only on keyframes,
	they may not generate at your requested fps!
	-->
		<OnlyKeyframes>true</OnlyKeyframes>
	</Decodes>

    <OutputProfile>
       <Encodes>
           <Video>
                <Bypass>true</Bypass>	
  		   </Video>
           <Image>
               <Codec>jpeg</Codec>
               <Width>1280</Width>
               <Height>720</Height>
               <Framerate>1</Framerate>
          </Image>
       </Encodes>
    </OutputProfile>
</OutputProfiles>

CrossDomains

For information on CrossDomains, see CrossDomains chapter.

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

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

Configuration

Bind

Set the SRT listen port as follows:

Application

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

Encoders and streamid

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

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

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

streamid = {Host Name}/{App Name}/{Stream Name}

Here, the {Host Name} refers to one of the patterns listed under /<Server>/<VirtualHosts>/<VirtualHost>/<Host>/<Names>/<Name>. In other words, if you configure it as shown below, you can use values such as a.airensoft.com, test.com, and test.airensoft.com as the {Host Name}.

OBS Studio

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

srt://{OvenMediaEngine Host}:{SRT Port}?streamid={streamid}

Blackmagic Web Presenter

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

The default streaming profiles work well, and there are more advanced configuration options available if you

Multiple Audio Track

The SRT Provider supports multiple audio track inputs. This is automatically applied to the LLHLS Publisher.

If you want to label the input audio tracks, configure them as follows. This affects the player's audio selection UI when playing LLHLS.

SRT Socket Options

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

For more information on SRT socket options, please refer to .

Provides statistics of virtual host, application, and stream.

Get Statistics of Virtual Host

Request

Responses

Get Statistics of Application

Request

Responses

Get Statistics of Stream

Request

Responses

Getting Started with default settings

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

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

You can set the following environment variables.

Environment Variables

Getting Started with Complex Configuration

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

OvenMediaEngine docker container loads configuration files from the following path.

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

Setup

Create the directories

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

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

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

Copy the default configurations from Docker container

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

Copy the certificate files to the directory

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

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

Modify Server.xml if necessary

vi $OME_DOCKER_HOME/conf/Server.xml

Running

Run Docker Container

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

docker run -d -it --name ome -e OME_HOST_IP=Your.HOST.IP.Address \
-v $OME_DOCKER_HOME/conf:/opt/ovenmediaengine/bin/origin_conf \
-v $OME_DOCKER_HOME/logs:/var/log/ovenmediaengine \
-p 1935:1935 -p 9999:9999/udp -p 9000:9000 -p 3333:3333 -p 3478:3478 \
-p 10000-10009:10000-10009/udp \
airensoft/ovenmediaengine:latest

Check the log file

tail -f $OME_DOCKER_HOME/logs/ovenmediaengine.log

Restart Docker Container

docker restart ome

Stop and Remove Container

docker stop ome
docker rm ome

Overview

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

By default, OvenMediaEngine's API Server is disabled, so the following settings are required to use the API.

Setup API Server

Port Binding

The API server's port can be set in <Bind><Managers><API>. <Port> is an unsecured port and <TLSPort> is a secured port. To use TLSPort, TLS certificate must be set in the Managers.

<Server version="8">
	...
	<Bind>
		<Managers>
			<API>
				<Port>8081</Port>
				<TLSPort>8082</TLSPort>
			</API>
		</Managers>
		...
	</Bind>
	...
</Server>

Managers

In order to use the API server, you must configure <Managers> as well as port binding.

<Server version="8">
	<Bind>
		...
	</Bind>

	<Managers>
		<Host>
			<Names>
				<Name>*</Name>
			</Names>
			<TLS>
				<CertPath>airensoft_com.crt</CertPath>
				<KeyPath>airensoft_com.key</KeyPath>
				<ChainCertPath>airensoft_com_chain.crt</ChainCertPath>
			</TLS>
		</Host>
		<API>
			<AccessToken>your_access_token</AccessToken>
			<CrossDomains>
				<Url>*.airensoft.com</Url>
				<Url>http://*.sub-domain.airensoft.com</Url>
				<Url>http?://airensoft.*</Url>
			</CrossDomains>
		</API>
	</Managers>

	<VirtualHosts>
		...
	</VirtualHosts>
</Server>

Host

In <Names>, set the domain or IP that can access the API server. If * is set, any address is used. In order to access using the TLS Port, a certificate must be set in <TLS>.

AccessToken

API Server uses Basic HTTP Authentication Scheme to authenticate clients. An AccessToken is a plaintext credential string before base64 encoding. Setting the AccessToken to the form user-id:password per RFC7617 allows standard browsers to pass authentication, but it is not required.

For more information about HTTP Basic authentication, refer to the URL below.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication

CrossDomains

To enable CORS on your API Server, you can add a setting. You can add * to allow all domains. If contains a scheme, such as https://, only that scheme can be allowed, or if the scheme is omitted, such as *.airensoft.com, all schemes can be accepted.

API Request

API endpoints are provided in the following format.

Method http://API.Server.Address[:Port]/v1/Resource

Method https://API.Server.Address[:TLSPort]/v1/Resource

OvenMediaEngine supports GET, POST, and DELETE methods, and sometimes supports PATCH depending on the type of resource. For detailed API specifications, please check the subdirectory of this chapter.

Action

In OvenMediaEngine's REST API, action is provided in the following format.

POST http://host/v1/resource:{action name}

For example, an action to send an ID3 Timedmeta event to an LLHLS stream is provided by the endpoint below.

POST http://-/v1/vhosts/{vhost}/apps/{app}/streams/{stream}:sendEvent

Document format

In this API reference document, the API endpoint is described as follows. Note that scheme://Host[:Port] is omitted for all endpoints.

Header-Key: Value

# Header-Key
    Description

{
    "requestId": "value"
}
    
# key (required)
    The description of the key/value of the body content is provided like this.

Responses from API endpoints are provided in the following format.

Header-Key: Value

{
	"statusCode": 200,
	"message": "OK",
	"response": {
	}
}

# statusCode
	Same as HTTP Status Code
# message
	A human-readable description of the response code
# response
	Response Contents

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

1. Install Drivers

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

$ nvidia-smi

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

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

OvenMediaEngine-master/misc/install_nvidia_docker_container.sh

OvenMediaEngine-master/Dockerfile.cuda
OvenMediaEngine-master/Dockerfile.cuda.local

ldconfig -p | grep libxcoder_logan.so

./prerequisites.sh --enable-nilogan --nilogan-path=/root/T4xx/release/FFmpeg-n5.0_t4xx_patch

2. Build & Run

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

docker run -d ... --gpus all airensoft/ovenmediaengine:dev

3. Configuration

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

<OutputProfiles>
    <HWAccels>
        <!-- 
        Setting for Hardware Modules.
            - nv : Nvidia Video Codec SDK
            - xma :Xilinx Media Accelerator
            - qsv :Intel Quick Sync Video
            - nilogan: Netint VPU

        You can use multiple modules by separating them with commas.
        For example, if you want to use xma and nv, you can set it as follows.

        <Modules>[ModuleName]:[DeviceId],[ModuleName]:[DeviceId],...</Modules>
        <Modules>xma:0,nv:0</Modules>
        -->
        <Decoder>
                <Enable>true</Enable>
                <Modules>nv</Modules>
        </Decoder>
        <Encoder>
                <Enable>true</Enable>
                <Modules>nv</Modules>
        </Encoder>
    </HWAccels>
    
    <OutputProfile>
        ...
    </OutputProfile>
</OutputProfiles>

Appendix. Support Format

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

D : Decoding, E : Encoding

Reference

• NVIDIA NVDEC Video Format : https://en.wikipedia.org/wiki/Nvidia_NVDEC

• NVIDIA NVENV Video Format : https://en.wikipedia.org/wiki/Nvidia_NVENC

• CUDA Toolkit Installation Guide : https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#introduction

• NVIDIA Container Toolkit : https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/arch-overview.html#arch-overview

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

• Xilinx Video SDK : https://xilinx.github.io/video-sdk/v3.0/index.html

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

\

Configuration

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

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

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

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

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

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

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

Protocol

Request (OME → Control Server)

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

Response (Control Server → OME)

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

The outputProfiles section in the JSON structure mirrors the configuration in Server.xml and allows for detailed settings as shown below:

Overview

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

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

Policy

Policy is in JSON format and provides the following properties.

Signature

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

Configuration

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

Make SignedPolicy URL with a script

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

Here's how to use this script:

For example, you can use it like this:

Make SignedPolicy URL manually

Encoding policy

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

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

Signature

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

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

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

Usage examples

Applying SignedPolicy in OBS

Generate SignedPolicy URL with the script.

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

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

Configuration

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

Playback

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

If your input stream is already h.264/aac, you can use the input stream as is like below. If not, or if you want to change the encoding quality, you can do .

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

http[s]://{OvenMediaEngine Host}[:{HLS Port}]/{App Name}/{Stream Name}/ts:mster.m3u8

http[s]://{OvenMediaEngine Host}[:{HLS Port}]/{App Name}/{Stream Name}/master.m3u8?format=ts

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

http://{OvenMediaEngine Host}:3333/{App Name}/{Stream Name}/ts:master.m3u8

http://{OvenMediaEngine Host}:3333/{App Name}/{Stream Name}/master.m3u8?format=ts

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

Adaptive Bitrates Streaming (ABR)

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

See the section for how to configure renditions.

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

CrossDomain

For information on CrossDomains, see chapter.

Live Rewind

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

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.

OvenMediaEngine generates log files. If you start OvenMediaEngine by systemctl start ovenmediaengine, the log file is generated to the following path.

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

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

Following is the example of real logs.

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 for the statistics REST API.

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

OriginMap

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

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

Edge

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

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

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

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

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

<Properties>

NoInputFailoverTimeout (default 3000)

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

UnusedStreamDeletionTimeout (default 60000)

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

<Origin>

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

Location

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

Pass

Pass consists of Scheme and Url.

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

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

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

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

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

Rules for generating Origin URL

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

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

OriginMapStore

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

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

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

Dynamic Application

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

Load Balancer

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 , , or can be a good alternative.