1 of 62

0.20.0 Introduction

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

Supported Platforms

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

Docker ()
Ubuntu 18+
Rocky Linux 8+

Getting Started

Please read 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 , , and .

We always hope that OvenMediaEngine will give you good inspiration.

For more information

License

OvenMediaEngine is licensed under the . However, if you need another license, please feel free to email us at .

Quick Start

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

Run OvenMediaEngine

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

Online Demo

Player & WebRTC Encoder

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

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

OvenSpace

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

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

OvenSpace is available online, so you can try it out for yourself at . 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 as open source. It will be a good reference when developing media services using OvenMediaEngine, OvenPlayer and OvenLiveKit.

Getting Started

Getting Started with Docker Image

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

Getting Started with Source Code

Installing dependencies

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

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

Building & Running

You can build the OvenMediaEngine source using the following command:

if systemctl start ovenmediaengine fails in Fedora, SELinux may be the cause. See .

Ports used by default

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

Port

Purpose

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

You can open firewall ports as in the following example:

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.

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:

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.

MPEG-2 TS

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

Title

Functions

RTSP Pull

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

Title

Functions

Multiplex Channel

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.

ABR and Transcoding

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 and Adaptive Streaming Architecture}

ABR

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

Streaming

CrossDomains

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 Thumbnail Publishers and WebRTC Provider(WHIP).

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

Url Value

Description

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.

Default(Global) CORS Settings

If all Applications share the same CORS policy, you can configure CORS under <Server><Defaults><CrossDomains> to apply it globally. This default CORS setting is also applied to invalid requests, such as 400 Bad Request responses or requests to non-existent Applications.

Up to version 0.19.0, the default CORS setting was supported per VirtualHost and had to be configured at <Server><VirtualHosts><VirtualHost><CrossDomain>. However, this method is now deprecated and no longer applied. The configuration has been consolidated under <Server><Defaults><CrossDomain>.

Application-Specific CORS Settings

If a particular Application requires a different CORS policy, you can add a CORS configuration to that Application. In this case, the Application-specific CORS setting takes precedence. For example, you can configure CORS for the current WebRTC Provider (WHIP), LLHLS, HLS, and Thumbnail Publisher as follows:

Access Control

Subtitles

From OvenMediaEngine 0.19.1 and later, you can insert subtitles into live streams in real time using the API.

Currently, only the LL-HLS publisher is supported. HLS and WebRTC will be supported in future releases.

To enable subtitles, add a subtitles section under <Application><OutputProfiles><MediaOptions>

Push Publishing

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.

The RTMP protocol only supports H264 and AAC codecs.

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.

Macro

Description

REST API

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

v1

Reload Certificate

Reload All Certificates

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

Send Event

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

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

Send Subtitles

Using this API, you can insert subtitles into a stream in real time. By specifying the label of the subtitle track defined in the application config, you can insert multiple subtitles at once.

Request

POST v1/vhosts/{vhost}/apps/{app}/streams/{stream}:sendSubtitles

Header

Body

Responses

200 Ok

The request has succeeded

Header

400 Bad Request

Invalid request. Body is not a Json Object or does not have a required value

401 Unauthorized

Authentication required

Header

404 Not Found

The given vhost name or app name could not be found.

Body

Conclude HLS Live

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

POST v1/vhosts/{vhost}/apps/{app}/streams/{stream}:concludeHlsLive

Statistics

Managers

API Server

Reload Certificate

Reload the certificate of the API Server. In case of failure, the existing certificate will continue to be used.

Request

POST /v1/managers/api:reloadCertificate

Header

Responses

200 OK

The request has succeeded

Header

Body

400 Bad Request

TLS is not enabled for the API Server

Header

Body

500 Internal Server Error

Failed to reload the certificate, so the existing one will be kept. The reason for the failure can be found in the server logs.

Header

Body

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:

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

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 .

Scheduled Channel

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

Getting Started

To use this feature, activate Schedule Provider as follows.

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

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

Schedule Files

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

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

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

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

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

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

<Stream>/<AudioMap> (optional, default: false) To enable multiple audio tracks (multilingual audio) in Scheduled Channel, enable AudioMap. It is important that all scheduled live sources and file sources provide audio tracks equal to or greater than the number of audio tracks defined in AudioMap. If you define 3 AudioMaps, but the file source or live source provides less than 3 audio tracks, the Program will generate an error. If you provide more audio tracks than the defined AudioMaps, they will be mapped in order and the rest will be ignored.

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

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

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

The url points to the location of the media source. If it starts with file://, it refers to a file within the <MediaRootDir> directory. If it starts with stream://, it refers to another stream within the same OvenMediaEngine. stream:// has the following format: stream://{VHost Name}/{App Name}/{Stream Name}

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

Supported Formats for File Live

Title

Description

Multiple Audio Track

The Scheduled Channel supports multiple audio tracks. This is automatically applied to the LLHLS Publisher. You can configure the <AudioMap> settings as follows to prepare multiple audio tracks in a Scheduled Channel.

A Scheduled Channel creates streams in advance and copies tracks from files or other streams. Therefore, all source content used in a Scheduled Channel with multiple audio tracks must provide at least the same number of audio tracks. Otherwise, the content will not be scheduled.

Application : Persistent Live Channel

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

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

You may experience some buffering when going from file to live. This is unavoidable due to the nature of the function and low latency. If this is inconvenient, buffering issues can disappear if you add a little delay in advance by setting PartHoldBack in LLHLS to 5 or more. It is a choice between delay and buffering.

REST API

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

getroot@Jeheon-Main:/var/log/ovenmediaengine$ cat ovenmediaengine.log
[03-27 19:59:13.221] I 10996 Config | config_manager.cpp:144  | Trying to set logfile in directory... (/var/log/ovenmediaengine)
[03-27 19:59:13.221] I 10996 Config | config_manager.cpp:47   | Trying to load configurations... (origin_conf/Server.xml)
[03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:211  | OvenMediaEngine v0.9.5 (v0.9.1-422-g6e4b7ce) is started on [Jeheon-Main] (Linux x86_64 - 4.4.0-18362-Microsoft, #476-Microsoft Fri Nov 01 16:53:00 PST 2019)
[03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:213  | With modules:
[03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:214  |   FFmpeg 3.4.2
[03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:215  |     Configuration: --prefix=/opt/ovenmediaengine --enable-gpl --enable-nonfree --extra-cflags=-I/opt/ovenmediaengine/include --extra-ldflags='-L/opt/ovenmediaengine/lib -Wl,-rpath,/opt/ovenmediaengine/lib' --extra-libs=-ldl --enable-shared --disable-static --disable-debug --disable-doc --disable-programs --disable-avdevice --disable-dct --disable-dwt --disable-error-resilience --disable-lsp --disable-lzo --disable-rdft --disable-faan --disable-pixelutils --disable-everything --enable-zlib --enable-libopus --enable-libvpx --enable-libfdk_aac --enable-libx264 --enable-encoder='libvpx_vp8,libvpx_vp9,libopus,libfdk_aac,libx264' --enable-decoder='aac,aac_latm,aac_fixed,h264' --enable-parser='aac,aac_latm,aac_fixed,h264' --enable-network --enable-protocol=tcp --enable-protocol=udp --enable-protocol=rtp --enable-demuxer=rtsp --enable-filter='asetnsamples,aresample,aformat,channelmap,channelsplit,scale,transpose,fps,settb,asettb'
[03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:216  |     libavformat: 57.83.100
[03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:217  |     libavcodec: 57.107.100
[03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:218  |     libavutil: 55.78.100
[03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:219  |     libavfilter: 6.107.100
[03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:220  |     libswresample: 2.9.100
[03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:221  |     libswscale: 4.8.100
[03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:222  |   SRT: 1.3.3
[03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:223  |   SRTP: libsrtp2 2.2.0
[03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:224  |   OpenSSL: OpenSSL 1.1.0g  2 Nov 2017
[03-27 19:59:13.235] I 10996 OvenMediaEngine | main.cpp:225  |     Configuration: compiler: gcc -DDSO_DLFCN -DHAVE_DLFCN_H -DNDEBUG -DOPENSSL_THREADS -DOPENSSL_NO_STATIC_ENGINE -DOPENSSL_PIC -DOPENSSL_IA32_SSE2 -DOPENSSL_BN_ASM_MONT -DOPENSSL_BN_ASM_MONT5 -DOPENSSL_BN_ASM_GF2m -DSHA1_ASM -DSHA256_ASM -DSHA512_ASM -DRC4_ASM -DMD5_ASM -DAES_ASM -DVPAES_ASM -DBSAES_ASM -DGHASH_ASM -DECP_NISTZ256_ASM -DPADLOCK_ASM -DPOLY1305_ASM -DOPENSSLDIR="\"/opt/ovenmediaengine\"" -DENGINESDIR="\"/opt/ovenmediaengine/lib/engines-1.1\""  -Wa,--noexecstack
[03-27 19:59:13.240] I 10996 Monitor | monitoring.cpp:35   | Create HostMetrics(default) for monitoring
[03-27 19:59:13.240] I 10996 OvenMediaEngine | main.cpp:148  | Trying to create a module MediaRouter for [default] host...
[03-27 19:59:13.240] I 10996 MediaRouter | media_router.cpp:40   | MediaRouter has been started.
[03-27 19:59:13.240] I 10996 OvenMediaEngine | main.cpp:151  | Trying to create a module RTMP Provider for [default] host...
[03-27 19:59:13.244] I 10996 RtmpProvider | rtmp_provider.cpp:63   | RTMP Server has started listening on 0.0.0.0:1935...
[03-27 19:59:13.246] I 10996 Provider | provider.cpp:40   | RtmpProvider has been started.
[03-27 19:59:13.246] I 10996 OvenMediaEngine | main.cpp:152  | Trying to create a module OVT Provider for [default] host...
[03-27 19:59:13.248] I 10996 Provider | provider.cpp:40   | OvtProvider has been started.
[03-27 19:59:13.248] I 10996 OvenMediaEngine | main.cpp:153  | Trying to create a module RTSPC Provider for [default] host...
[03-27 19:59:13.250] I 10996 Provider | provider.cpp:40   | RtspcProvider has been started.
[03-27 19:59:13.250] I 10996 OvenMediaEngine | main.cpp:154  | Trying to create a module RTSP Provider for [default] host...
[03-27 19:59:13.250] I 10996 RtspProvider | rtsp_provider.cpp:40   | RTSP is disabled in the configuration.
[03-27 19:59:13.251] I 10996 OvenMediaEngine | main.cpp:157  | Trying to create a module Transcoder for [default] host...
[03-27 19:59:13.251] I 10996 Transcoder | transcoder.cpp:38   | Transcoder has been started.
[03-27 19:59:13.251] I 10996 OvenMediaEngine | main.cpp:160  | Trying to create a module WebRTC Publisher for [default] host...
[03-27 19:59:13.251] I 10996 Signalling | rtc_signalling_server.cpp:74   | P2P is disabled in the configuration
[03-27 19:59:13.258] I 10996 Ice | ice_port.cpp:89   | ICE port is bound to 0.0.0.0:10000/UDP
[03-27 19:59:13.260] I 10996 Ice | ice_port.cpp:89   | ICE port is bound to 0.0.0.0:10001/UDP
[03-27 19:59:13.261] I 10996 Ice | ice_port.cpp:89   | ICE port is bound to 0.0.0.0:10002/UDP
[03-27 19:59:13.263] I 10996 Ice | ice_port.cpp:89   | ICE port is bound to 0.0.0.0:10003/UDP
[03-27 19:59:13.264] I 10996 Ice | ice_port.cpp:89   | ICE port is bound to 0.0.0.0:10004/UDP
[03-27 19:59:13.266] I 10996 Ice | ice_port.cpp:89   | ICE port is bound to 0.0.0.0:10005/UDP
[03-27 19:59:13.266] I 10996 Publisher | publisher.cpp:15   | WebRTC Publisher has been started.
[03-27 19:59:13.266] I 10996 WebRTC | webrtc_publisher.cpp:89   | WebRTC Publisher has started listening on 0.0.0.0:3333...
[03-27 19:59:13.266] I 10996 Publisher | publisher.cpp:15   | WebRTC Publisher has been started.
[03-27 19:59:13.266] I 10996 OvenMediaEngine | main.cpp:161  | Trying to create a module HLS Publisher for [default] host...
[03-27 19:59:13.273] I 10996 Publisher | segment_publisher.cpp:65   | HLS Publisher has started listening on 0.0.0.0:8080...
[03-27 19:59:13.273] I 10996 Publisher | publisher.cpp:15   | HLS Publisher has been started.
[03-27 19:59:13.275] I 10996 OvenMediaEngine | main.cpp:162  | Trying to create a module MPEG-DASH Publisher for [default] host...
[03-27 19:59:13.281] I 10996 Publisher | segment_publisher.cpp:65   | DASH Publisher has started listening on 0.0.0.0:8080...
[03-27 19:59:13.281] I 10996 Publisher | publisher.cpp:15   | DASH Publisher has been started.
[03-27 19:59:13.282] I 10996 OvenMediaEngine | main.cpp:163  | Trying to create a module Low-Latency MPEG-DASH Publisher for [default] host...
[03-27 19:59:13.289] I 10996 Publisher | segment_publisher.cpp:65   | LLDASH Publisher has started listening on 0.0.0.0:8080...
[03-27 19:59:13.289] I 10996 Publisher | publisher.cpp:15   | LLDASH Publisher has been started.
[03-27 19:59:13.291] I 10996 OvenMediaEngine | main.cpp:164  | Trying to create a module OVT Publisher for [default] host...
[03-27 19:59:13.294] I 10996 OVT | ovt_publisher.cpp:49   | Ovt Publisher has started listening on 0.0.0.0:9000
[03-27 19:59:13.294] I 10996 Publisher | publisher.cpp:15   | OVTPublisher has been started.
[03-27 19:59:13.294] I 10996 OvenMediaEngine | main.cpp:169  | All modules are initialized successfully
[03-27 19:59:13.294] I 10996 Orchestrator | orchestrator.cpp:856  | Trying to create an application: [#default#app]
[03-27 19:59:13.294] I 10996 Monitor | host_metrics.cpp:52   | Create ApplicationMetrics(#default#app) for monitoring
[03-27 19:59:13.297] I 10996 Provider | application.cpp:30   | [#default#app] RTMP Provider application has been started
[03-27 19:59:13.297] I 10996 Provider | application.cpp:30   | [#default#app] OVT Provider application has been started
[03-27 19:59:13.297] I 10996 Provider | application.cpp:30   | [#default#app] RTSP Pull Provider application has been started
[03-27 19:59:13.297] I 10996 Provider | application.cpp:30   | [#default#app] RTSP Provider application has been started
[03-27 19:59:13.298] I 10996 TranscodeApplication | transcode_application.cpp:36   | [#default#app] Transcoder Application has been started
[03-27 19:59:13.300] I 10996 Publisher | application.cpp:26   | [#default#app] WebRTC Publisher application has been started
[03-27 19:59:13.302] I 10996 Publisher | application.cpp:26   | [#default#app] HLS Publisher application has been started
[03-27 19:59:13.304] I 10996 Publisher | application.cpp:26   | [#default#app] DASH Publisher application has been started
[03-27 19:59:13.305] I 10996 Publisher | application.cpp:26   | [#default#app] LLDASH Publisher application has been started
[03-27 19:59:13.307] I 10996 Publisher | application.cpp:26   | [#default#app] OVT Publisher application has been started
[03-27 19:59:14.706] I 11002 RtmpProvider | rtmp_server.cpp:126  | A RTMP client has connected from <ClientSocket: 0x7fffd4000b70, #24, state: 4, TCP, 192.168.0.200:11031>
[03-27 19:59:14.835] I 11002 RtmpProvider | rtmp_server.cpp:226  | [#default#app/stream] RTMP Provider stream has been created: id(0/0) device(OBS) remote(<ClientSocket: 0x7fffd4000b70, #24, state: 4, TCP, 192.168.0.200:11031>)
[03-27 19:59:14.835] I 11002 MediaRouter.App | media_route_application.cpp:184  | Trying to create a stream: [#default#app/stream(2921228900)]
[03-27 19:59:14.836] I 11002 Monitor | stream.cpp:240  | 
[Stream Info]
id(2921228900), name(stream), SourceType(Rtmp), Created Time (Fri Mar 27 19:59:14 2020)

        Video Track #0: Bypass(false) Bitrate(2.50Mb) codec(1, avc) resolution(1280x720) framerate(30.00fps) timebase(1/90000)
        Audio Track #1: Bypass(false) Bitrate(160.00Kb) codec(5, aac) samplerate(44.1K) format(s16, 16) channel(stereo, 2) timebase(1/44100)
[03-27 19:59:14.836] I 11002 Monitor | application_metrics.cpp:56   | Create StreamMetrics(stream) for monitoring
[03-27 19:59:14.836] I 11002 TranscodeStream | transcode_stream.cpp:353  | [#default#app/stream(2921228900)] -> [#default#app/stream_medium_o(3169746412)] Transcoder output stream has been created.
[03-27 19:59:14.839] I 11002 FFmpeg | third_parties.cpp:115  |  [AVCodecContext] using SAR=1/1
[03-27 19:59:14.841] I 11002 FFmpeg | third_parties.cpp:115  |  [AVCodecContext] using cpu capabilities: MMX2 SSE2Fast SSSE3 SSE4.2 AVX FMA3 BMI2 AVX2
[03-27 19:59:14.846] I 11002 FFmpeg | third_parties.cpp:115  |  [AVCodecContext] profile Constrained Baseline, level 3.0, 4:2:0, 8-bit
[03-27 19:59:14.849] I 11002 FFmpeg | third_parties.cpp:115  |  [AVCodecContext] v1.7.0
[03-27 19:59:14.864] I 11048 MediaRouter.App | media_route_application.cpp:184  | Trying to create a stream: [#default#app/stream_medium_o(3169746412)]
[03-27 19:59:14.864] I 11002 TranscodeStream | transcode_stream.cpp:108  | [#default#app/stream(2921228900)] Transcoder input stream has been started. Status : (2) Decoders, (4) Encoders
[03-27 19:59:14.865] I 11048 Monitor | stream.cpp:240  | 
[Stream Info]
id(3169746412), name(stream_medium_o), SourceType(Transcoder), Created Time (Fri Mar 27 19:59:14 2020)
        >> Origin Stream Info
        id(2921228900), name(stream), SourceType(Rtmp), Created Time (Fri Mar 27 19:59:14 2020)

        Video Track #0: Bypass(false) Bitrate(700.00Kb) codec(2, vp8) resolution(640x360) framerate(30.00fps) timebase(1/90000)
        Video Track #1: Bypass(false) Bitrate(700.00Kb) codec(1, avc) resolution(640x360) framerate(30.00fps) timebase(1/90000)
        Audio Track #2: Bypass(false) Bitrate(48.00Kb) codec(7, opus) samplerate(48.0K) format(s16, 16) channel(stereo, 2) timebase(1/48000)
        Audio Track #3: Bypass(false) Bitrate(48.00Kb) codec(5, aac) samplerate(48.0K) format(s16, 16) channel(stereo, 2) timebase(1/48000)
[03-27 19:59:14.865] I 11048 Monitor | application_metrics.cpp:56   | Create StreamMetrics(stream_medium_o) for monitoring
[03-27 19:59:14.865] I 11048 WebRTC | rtc_stream.cpp:181  | Unsupported codec(Audio/AAC) is being input from media track
[03-27 19:59:14.880] I 11048 Publisher | stream.cpp:192  | [stream_medium_o(3169746412)] WebRTC Publisher stream has been started
[03-27 19:59:14.881] I 11048 Publisher | stream.cpp:192  | [stream_medium_o(3169746412)] HLS Publisher stream has been started
[03-27 19:59:14.881] I 11048 Publisher | stream.cpp:192  | [stream_medium_o(3169746412)] DASH Publisher stream has been started
[03-27 19:59:14.881] I 11048 Publisher | stream.cpp:192  | [stream_medium_o(3169746412)] LLDASH Publisher stream has been started
[03-27 19:59:14.897] I 11048 Publisher | stream.cpp:192  | [stream_medium_o(3169746412)] OVT Publisher stream has been started
[03-27 19:59:14.898] I 11048 TranscodeCodec | transcode_codec_dec_aac.cpp:49   | [#default#app/stream(2921228900)] input stream information: [audio] aac (LC), 44100 Hz, stereo, fltp, 154 kbps, timebase: 1/44100, frame_size: 1024
[03-27 19:59:14.985] I 11048 TranscodeCodec | transcode_codec_dec_avc.cpp:48   | [#default#app/stream(2921228900)] input stream information: [video] h264 (Constrained Baseline 3.1), yuv420p, 1280x720 [SAR 0:1 DAR 16:9], 30 fps, 195 kbps, timebase: 1/60, frame_size: 0

HLS

Beta

MaxDurationHLS is still in development and some features such as SignedPolicy and AdmissionWebhooks are not supported.

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.

Title

Descriptions

To differentiate between LLHLS and HLS playback addresses, we created the following rule for HLS playback addresses:

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

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

Configuration

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

Element

Decscription

Safari Native Player only provides the Seek UI if #EXT-X-PLAYLIST-TYPE: EVENT is present. Since it is specified that nothing can be removed from the playlist when it is of type EVENT, you must call the to switch to VoD or terminate the stream before <MaxDuration> is exceeded if you use this option. Otherwise, unexpected behavior may occur in the Safari Player.

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:

Since TS files used in HLS must have A/V pre-muxed, the Playlist must have the EnableTsPackaging option set.

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.

Dump

You can dump the HLS stream for VoD. You can enable it by setting the following in <Application><Publishers><LLHLS>. Unlike LLHLS, dump function cannot be controlled by REST API at this time.

TargetStreamName

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

Playlists

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

OutputPath

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

Macro

Description

Getting Started with OME Docker Launcher

Overview and Features

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

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

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

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

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

Installation

Run the following command in your Linux shell.

Below is an example of execution:

Commands

OME Docker Launcher can be executed in the following format:

`setup`

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

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

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

/usr/share/ovenmediaengine/conf
- This directory contains the OME configuration files and is mounted into the container when it is run.
/usr/share/ovenmediaengine/logs

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

Certificate Installation

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

Type

File name

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

`start`

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

When running the OME Docker Launcher, you can specify the IP to be used as an ICE Candidate by using the OME_HOST_IP environment variable. For instance, specifying the OME_HOST_IP as shown below will propagate the ICE Candidate to that particular address.

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

If you have declared the following environment variable in the shell where you run the OME Docker Launcher, this value will be used to bind the port and passed into the Docker container. This enables you to dynamically set configuration values using environment variables.

`sh`

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

`status`

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

`stop`

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

`restart`

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

Troubleshootings

Enable debug log

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

Get the crash dump of OME in the container

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

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

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:

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.

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.

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 .

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 .

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.

Scalable Threads and Configuration

AppWorkerCount

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

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.

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.

WebRTC / WHIP

Users can send video and audio from a web browser to OvenMediaEngine via WebRTC without requiring any plug-ins. In addition to browsers, any encoder that supports WebRTC transmission can also be used as a media source.

Title

Functions

Container

RTP / RTCP

Security

DTLS, SRTP

Transport

ICE

Configuration

Bind

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

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

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

<TcpRelay> means OvenMediaEngine's built-in TURN Server. When this is enabled, the address of this turn server is passed to the peer via self-defined signaling protocol or WHIP, and the peer communicates with this turn server over TCP. This allows OvenMediaEngine to support WebRTC/TCP itself. For more information on URL settings, check out .

Application

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

URL Pattern

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

Self-defined Signaling URL

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

ws[s]://<OME Host>[:Signaling Port]/<App Name>/<Stream Name>?direction=send

WHIP URL

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

http[s]://<OME Host>[:Signaling Port]/<App Name>/<Stream Name>?direction=whip

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 for more information.

ws[s]://{OME Host}[:{Signaling Port}]/{App Name}/{Stream Name}?direction=send&transport=tcp
http[s]://{OME Host}[:{Signaling Port}]/{App Name}/{Stream Name}?direction=whip&transport=tcp

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

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

Simulcast

Simulcast is a feature that allows the sender to deliver multiple layers of quality to the end viewer without relying on a server encoder. This is a useful feature that allows for high-quality streaming to be delivered to viewers while significantly reducing costs in environments with limited server resources.

OvenMediaEngine supports WebRTC simulcast since 0.18.0. OvenMediaEngine only supports simulcast with WHIP signaling, and not with OvenMediaEngine's own signaling. Simulcast is only supported with WHIP signaling, and is not supported with OvenMediaEngine's own defined signaling.

You can test this using an encoder that supports WHIP and simulcast, such as OvenLiveKit or OBS. You can usually set the number of layers as below, and if you use the OvenLiveKit API directly, you can also configure the resolution and bitrate per layer.

Playlist Template for Simulcast

When multiple input video Tracks exist, it means that several Tracks with the same Variant Name are present. For example, consider the following basic <OutputProfile> and assume there are three input video Tracks. In this case, three Tracks with the Variant Name video_bypass will be created:

How can we structure Playlists with multiple Tracks? A simple method introduces an Index concept in Playlists:

<VideoIndexHint> and <AudioIndexHint> specify the Index of input video and audio Tracks, respectively.

However, when using the above configuration, if the encoder broadcasts 3 video tracks with Simulcast, it is inconvenient to change the configuration and restart the server to provide HLS/WebRTC streaming with 3 ABR layers. So I implemented a dynamic Rendition tool called RenditionTemplate.

RenditionTemplate

The <RenditionTemplate> feature automatically generates Renditions based on specified conditions, eliminating the need to define each one manually. Here’s an example:

This configuration creates Renditions for all bypassed videos and uses audio Tracks with the aac_audio Variant Name. The following macros can be used in the Name of a RenditionTemplate: ${Width} | ${Height} | ${Bitrate} | ${Framerate} | ${Samplerate} | ${Channel}

You can specify conditions to control Rendition creation. For example, to include only videos with a minimum resolution of 280p and bitrate above 500kbps, or to exclude videos exceeding 1080p or 2Mbps:

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.

The getUserMedia API to access the local device only works in a . So, the WebRTC Input demo page can only work on the https site **** . This means that due to 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.

Self-defined WebRTC Ingest Signaling Protocol

To create a custom WebRTC Producer, you need to implement OvenMediaEngine's Self-defined Signaling Protocol or WHIP. Self-defined protocol is structured in a simple format and uses the.

When the player connects to ws[s]://host:port/app/stream?direction=send through a WebSocket and sends a request offer command, the server responds to the offer SDP. If transport=tcp exists in the query string of the URL, 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.

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

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

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

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

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

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

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

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

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

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

    <!--
        Enable this configuration if you want to use API Server

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

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

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

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

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

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

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

            <!--
            <Origins>
                <Properties>
                    <NoInputFailoverTimeout>3000</NoInputFailoverTimeout>
                    <UnusedStreamDeletionTimeout>60000</UnusedStreamDeletionTimeout>
                </Properties>
                <Origin>
                    <Location>/app/stream</Location>
                    <Pass>
                        <Scheme>ovt</Scheme>
                        <Urls><Url>origin.com:9000/app/stream_720p</Url></Urls>
                    </Pass>
                    <ForwardQueryParams>false</ForwardQueryParams>
                </Origin>
                <Origin>
                    <Location>/app/</Location>
                    <Pass>
                        <Scheme>ovt</Scheme>
                        <Urls><Url>origin.com:9000/app/</Url></Urls>
                    </Pass>
                </Origin>
                <Origin>
                    <Location>/edge/</Location>
                    <Pass>
                        <Scheme>ovt</Scheme>
                        <Urls><Url>origin.com:9000/app/</Url></Urls>
                    </Pass>
                </Origin>
            </Origins>
            -->

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

0.20.0

Introduction

hashtagWhat is OvenMediaEngine?

hashtagFeatures

hashtagSupported Platforms

hashtagGetting Started

hashtagHow to Contribute

hashtagFor more information

hashtagLicense

Quick Start

hashtagRun OvenMediaEngine

Online Demo

hashtagPlayer & WebRTC Encoder

hashtagOvenSpace

Getting Started

hashtagGetting Started with Docker Image

hashtagGetting Started with Source Code

hashtagInstalling dependencies

hashtagBuilding & Running

hashtagPorts used by default

TLS Encryption

hashtagDocker

hashtagLet's Encrypt,

Live Source

MPEG-2 TS

RTSP Pull

Multiplex Channel

hashtagConfiguration

hashtagMux file format

hashtagREST API

ABR and Transcoding

hashtag

ABR

hashtagAdaptive Bitrate Streaming (ABR)

Streaming

CrossDomains

hashtagDefault(Global) CORS Settings

hashtagApplication-Specific CORS Settings

Access Control

Subtitles

Push Publishing

hashtagConfiguration

hashtagPush Publisher

hashtagStreamMap

hashtagREST API

v1

Reload Certificate

hashtagReload All Certificates

hashtag

Send Event

hashtagRequest

Send Subtitles

hashtagRequest

hashtagHeader

hashtagBody

hashtagResponses

hashtagHeader

hashtagHeader

hashtagBody

Conclude HLS Live

hashtagRequest

Statistics

Managers

API Server

Reload Certificate

hashtagReload Certificate

hashtagRequest

hashtagHeader

hashtagResponses

P2P Delivery (Experiment)

hashtagWhat are the benefits of using P2P Delivery?

hashtagHow does it work?

hashtagHow does it classify Peers?

Online Demo

hashtagPlayer & WebRTC Encoder

hashtagOvenSpace

Quick Start

hashtagRun OvenMediaEngine

hashtagRun OvenPlayer Demo

hashtagPublishing

What is OvenMediaEngine?

Features

Supported Platforms

Getting Started

How to Contribute

For more information

License

Run OvenMediaEngine

Player & WebRTC Encoder

OvenSpace

Getting Started with Docker Image

Getting Started with Source Code

Installing dependencies

Building & Running

Ports used by default

Docker

Let's Encrypt,

Configuration

Mux file format

REST API

Adaptive Bitrate Streaming (ABR)

Default(Global) CORS Settings

Application-Specific CORS Settings

Configuration

Push Publisher

StreamMap

REST API

Reload All Certificates

Request

Request

Header

Body

Responses

Header

Header

Body

Request

Reload Certificate

Request

Header

Responses

What are the benefits of using P2P Delivery?

How does it work?

How does it classify Peers?

Player & WebRTC Encoder

OvenSpace

Run OvenMediaEngine

Run OvenPlayer Demo

Publishing

Playback

WebRTC Playback

LLHLS Playback

What is OvenMediaEngine?

Features

Supported Platforms

Getting Started

How to Contribute

For more information

License

Adaptive Bitrate (ABR) Stream

TranscodeWebhook

Support Codecs

Hardware accelerators

Docker

Let's Encrypt,

What are the benefits of using P2P Delivery?

How does it work?

How does it classify Peers?

Request

Request

Reload All Certificates

Configuration

Bind

Stream mapping

Publish

Insert Subtitle Cues

Playlist Subtitle Disable per Playlist

Header

Body

Responses