Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
OvenMediaEngine has an XML configuration file. If you start OvenMediaEngine with systemctl start ovenmediaengine
, the config file is loaded from the following path.
If you run it directly from the command line, it loads the configuration file from:
If you run it in Docker container, the path to the configuration file is:
The Server
is the root element of the configuration file. The version
attribute indicates the version of the configuration file. OvenMediaEngine uses this version information to check if the config file is a compatible version.
The IP address
is OvenMediaEngine will bind to. If you set *, all IP addresses of the system are used. If you enter a specific IP, the Host uses that IP only.
OvenMediaEngine needs to know its public IP in order to connect to the player through WebRTC. The server must inform the player of the IceCandidates and TURN server addresses when signaling, and this information must be the IP the player can connect to. However, in environments such as Docker or AWS, public IP cannot be obtained through a local interface, so a method of obtaining public IP using stun server is provided (available from version 0.11.1).
If OvenMediaEngine obtains the public IP through communication with the set stun server, you can set the public IP by using * or ${PublicIP} in IceCandidate and TcpRelay.
The Bind
is the configuration for the server port that will be used. Bind consists of Providers
and Publishers
. The Providers are the server for stream input, and the Publishers are the server for streaming.
The meaning of each element is shown in the following table:
HLS and DASH can be set to the same port, but all other protocols have to use different ports. The ability for all protocols to use the same port will be updated in the future.
VirtualHosts
are a way to run more than one streaming server on a single machine. OvenMediaEngine supports IP-based virtual host and Domain-based virtual host. "IP-based" means that you can separate streaming servers into multiples by setting different IP addresses, and "Domain-based" means that even if the streaming servers use the same IP address, you can split the streaming servers into multiples by setting different domain names.
VirtualHosts
consist of Name
, Host
, Origins
, SignedPolicy
, and Applications
.
The Domain has Names
and TLS. Names can be either a domain address or an IP address. Setting * means it allows all domains and IP addresses.
SignedPolicy is a module that limits the user's privileges and time. For example, operators can distribute RTMP URLs that can be accessed for 60 seconds to authorized users, and limit RTMP transmission to 1 hour. The provided URL will be destroyed after 60 seconds, and transmission will automatically stop after 1 hour. Users who are provided with a SingedPolicy URL cannot access resources other than the provided URL. This is because the SignedPolicy URL is authenticated. See the SignedPolicy chapter for more information.
AdmissionWebhooks are HTTP callbacks that query the control server to control publishing and playback admission requests. Users can use the AdmissionWebhook for a variety of purposes, including customer authentication, tracking published streams, hide app/stream names, logging and more. See the AdmissionWebhooks chapter for more information.
Origins (also we called OriginMap) are a feature to pull streams from external servers. It now supports OVT and RTSP for the pulling protocols. OVT is a protocol defined by OvenMediaEngine for Origin-Edge communication. It allows OvenMediaEngine to relay a stream from other OvenMediaEngines that have OVP Publisher turned on. Using RTSP, OvenMediaEngine pulls a stream from an RTSP server and creates a stream. RTSP stream from external servers can stream by WebRTC, HLS, and MPEG-DASH.
The Origin has Location
and Pass
elements. Location is a URI pattern for incoming requests. If the incoming URL request matches Location, OvenMediaEngine pulls the stream according to a Pass element. In the Pass element, you can set the origin stream's protocol and URLs.
To run the Edge server, Origin creates application and stream if there isn't those when user request. For more learn about Origin-Edge, see the Live Source chapter.
<Application>
consists of various elements that can define the operation of the stream, including Stream input, Encoding, and Stream output. In other words, you can create as many <Application>
as you like and build various streaming environments.
<Application>
needs to set <Name>
and <Type>
as follows:
<Name>
is used to configure the Streaming URL.
<Type>
defines the operation of <Application>
. Currently, there is only a live
type.
<OutputProfile>
is a configuration that creates an output stream. Output stream name can be set with <OutputStreamName>
, and transcoding properties can be set through <Encodes>
. If you want to stream one input to multiple output streams, you can set multiple <OutputProfile>
.
For more information about the OutputProfiles, please see the Transcoding chapter.
Providers
ingest streams that come from a media source.
If you want to get more information about the <Providers>
, please refer to the Live Source chapter.
You can configure the Output Stream operation in <Publishers>
. <ThreadCount>
is the number of threads used by each component responsible for the <Publishers>
protocol.
You need many threads to transmit streams to a large number of users at the same time. So it's better to use a higher core CPU and set <ThreadCount>
equal to the number of CPU cores.
​OvenMediaEngine currently supports WebRTC, Low-Latency DASH, MEPG-DASH, and HLS. If you don't want to use any protocol then you can delete that protocol setting, the component for that protocol isn't initialized. As a result, you can save system resources by deleting the settings of unused protocol components.
If you want to learn more about WebRTC, visit the WebRTC Streaming chapter. And if you want to get more information on Low-Latency DASH, MPEG-DASH, and HLS, refer to the chapter on HLS & MPEG-DASH Streaming.
Finally, Server.xml
is configured as follows:
User can send video/audio from web browser to OvenMediaEngine via WebRTC without plug-in. Of course, you can use any encoder that supports WebRTC transmission as well as a browser.
In order for OvenMediaEngine to receive streams through WebRTC, web socket-based signaling port and ICE candidate must be set. The ICE candidate can configure a TCP relay. WebRTC provider and WebRTC publisher can use the same port. Ports of WebRTC provider can be set in as follows.
WebRTC input can be turned on/off for each application. As follows Setting enables the WebRTC input function of the application.
The signaling url for WebRTC input uses the query string(?direction=send) as follows to distinguish it from the url for WebRTC playback.
ws[s]://<host>[:port]/<app name>/<stream name>?direction=send
When WebRTC transmission starts, a stream is created with under application.
ws[s]://<host>[:port]/<app name>/<stream name>?direction=send&transport=tcp
To use WebRTC/tcp, <TcpRelay> must be turned on in <Bind> setting.
We provide a demo page so you can easily test your WebRTC input. You can access the demo page at the URL below.
Our goal is to make it easier for you to build a stable broadcasting/streaming service with sub second latency.
Ingest
WebRTC Push, RTMP Push, SRT Push, MPEG-2 TS Push, RTSP Pull
WebRTC sub-second streaming
WebRTC over TCP (with embedded TURN server)
Embedded WebRTC Signalling Server (WebSocket based)
ICE (Interactive Connectivity Establishment)
DTLS (Datagram Transport Layer Security)
SRTP (Secure Real-time Transport Protocol)
ULPFEC (Forward Error Correction) with VP8, H.264
In-band FEC (Forward Error Correction) with Opus
Low-Latency MPEG-DASH streaming (Chunked CMAF)
Legacy HLS/MPEG-DASH streaming
Embedded Live Transcoder (VP8, H.264, Opus, AAC, Bypass)
Origin-Edge structure
Monitoring
Beta
File Recording
RTMP Push Publishing(re-streaming)
Thumbnail
REST API
Experiment
P2P Traffic Distribution
We have tested OvenMediaEngine on platforms, listed below. However, we think it can work with other Linux packages as well:
Ubuntu 18
CentOS 7
Fedora 28
Basic Information, FAQ, and Benchmark
Getting Started, Install, and Configuration
Test Player
Providers
ingests streams that come from a media source. OvenMediaEngine supports RTMP protocol. You can set it in the configuration as follows:
When a live source inputs to the <Application>
, a stream is automatically created in the <Application>
. The created stream is passed to Encoder and Publisher.
If you set up a live stream using an RTMP-based encoder, you need to set the following in Server.xml
:
<BlockDuplicateStreamName>
is a policy for streams that are inputted as overlaps.
<BlockDuplicateStreamName>
works with the following rules:
To allow the duplicated stream name feature can cause several problems. When a new stream is an input the player may be disconnected. Most encoders have the ability to automatically reconnect when it is disconnected from the server. As a result, two encoders compete and disconnect each other, which can cause serious problems in playback.
If you want to publish the source stream, you need to set the following in the Encoder:
URL
RTMP://<OvenMediaEngine IP>[:<RTMP Listen Port>]/<App Name]>
Stream Key
Stream Name
If you use the default configuration, the <RTMP><ListenPort>
is 1935, which is the default port for RTMP. So it can be omitted. Also, since the Application named app
is created by default in the default configuration, you can enter app
in the [App Name]
. You can define a Stream Key and use it in the Encoder, and the Streaming URL will change according to the Stream Key.
Moreover, some encoders can include a stream key in the URL, and if you use these encoders, you need to set it as follows:
URL
RTMP://<OvenMediaEngine IP>[:<RTMP Listen Port>/<App Name>/<Stream Name>
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.
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.
If you use the default configuration, you can stream with the following streaming URLs when you start broadcasting to OBS:
WebRTC
ws://192.168.0.1:3333/app/stream
HLS
http://192.168.0.1:8080/app/stream/playlist.m3u8
MPEG-DASH
http://192.168.0.1:8080/app/stream/manifest.mpd
You can set the following environment variables.
OvenMediaEngine can work with a variety of open-sources and libraries. First, install them on your clean Linux machine as described below. We think that OME can support most Linux packages, but the tested platforms we use are Ubuntu 18+, Fedora 28+, and CentOS 7+.
You can build the OvenMediaEngine source using the following command:
In addition, we recommend that you permanently set environment variables as follows.
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:
rtmp://<Server IP>[:<RTMP Port>]/<Application name>/<Stream name>
The meanings of each item are as follows:
<Server IP>
: IP address or domain of the OvenMediaEngine server.
<RTMP Port>
: You can use <Port>
of <Provider>
in the above Server.xml
file. With the default configuration, the RTMP default port (1935) is used. Also, by setting the default port, you can omit the port.
<Application name>
: This value corresponds to <Name>
of <Application>
in conf/Server.xml
. If you use the default configuration, you can use the app
.
<Stream name>
: Name of the stream you defined.
After you enter the above RTMP URL into the encoder and start publishing, you will have an environment in which the player can view the live stream.
OvenStreamEncoder supports the mode that implements the streaming of the screen recorded by a camera and another that performs the streaming of the current screen by capturing it.
So, select the mode along with the broadcasting concept you want and proceed with the optimum setting by pressing the Setting icon at this right upper position.
After broadcast setting, return to the original screen, press the URL button at right upper, and input RTMP URL and Stream Key to transmitting.
If all preparation is ready, begin the broadcast by pressing the Recording button at the center bottom.
The server address in OBS needs to use <Application name>
generated in Server.xml
. If you use the default configuration, the app is already created and ready to use.
Install OBS on your PC and run it.
Click "File" in the top menu, then click "Settings" (or press "Settings" on the lower right).
Select the "Stream" tab and enter your stream information.
Go to the "Output" tab.
Set the following entries.
For lower latency, we recommend using the Hardware Encoder as follows: "NVENC" provides a Low-Latency preset. It's also important to set "MAX B-frame = 0" to reduce latency.
If Hardware Encoder isn't installed on your PC, it's recommended to set x264 as follows: We highly recommend setting "bframes = 0" to reduce latency. Then set the "threads" option to 8 or less. Chrome doesn't handle more than 10 Nal Units. The best way to avoid this is to set "thread = 8".
We recommend checking "Enable new networking code" and "Low latency mode" on Network in Advanced Settings as follows:
Please note that WebRTC Signalling URL is similar to the RTMP URL and consists of the following:
ws://<Server IP>:[<Signalling Port>/<Application name>/<Output Stream name>[?transport=tcp]
<Server IP>
: IP address or domain of the OvenMediaEngine server.
<Signalling Port>
: You can use the value of <Signalling><ListenPort>
in Server.xml
above. If you use the default configuration, the WebRTC Signalling default port (3333) is used.
<Application name>
: This value corresponds to <Name>
of <Application>
in conf/Server.xml
. If you use the default configuration, you can use the app
.
<Output Stream name>
: You have to use an output stream name for streaming. If you use the default configuration, an output stream named <Stream Name>
is automatically generated when the stream is input.
?transport=tcp
: You can use this query string to play through webrtc over tcp. Useful in environments with severe packet loss.
As of version 0.10.4, the default output stream name has been changed from <Input Stream Name>_o to <Input Stream Name>, and has been updated to use the input stream name as the output stream name for convenience.
If you use the default configuration, the RTMP publishing URL is rtmp://192.168.0.1:1935/app/stream
Then the WebRTC URL will bews://192.168.0.1:3333/app/stream
In addition,
WebRTC over TCP URL will be ws://192.168.0.1:3333/app/stream?transport=tcp
HLS streaming URL will behttp://192.168.0.1:8080/app/stream/playlist.m3u8
MPEG-DASH streaming URL will behttp://192.168.0.1:8080/app/stream/manifest.mpd
Low-Latency MPEG-DASH streaming URL will be http://192.168.0.1:8080/app/stream/manifest_ll.mpd
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.
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.
To create a custom WebRTC Producer, you need to implement OvenMediaEngine's Signaling Protocol. The protocol is structured in a simple format and uses the.
When the player connects to ws[s]://host:port/app/stream?direction=send through a web socket and sends a request offer command, the server responds to the offer sdp. If transport=tcp exists in the query string of the URL, 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.
OvenMediaEngine (OME) is an open-source and streaming server with sub-second latency. OME receives video via RTMP, MPEG-TS, and RSTP Pull from live encoders such as OBS, FFMPEG, and more. Then OME transmits video using WebRTC, Low-Latency HTTP (DASH), MPEG-DASH, and HLS. This enables sub-second latency streaming from OME which plays back seamlessly in your browser without requiring any plug-ins. Also, we provide , the most optimized HTML5 player for OME, as an open-source.
Docker ()
Please read chapter in tutorials.
Without TLS
:
Based on TLS
:
Please see our and .
OvenMediaEngine is under the .
OvenMediaEngine supports the Docker image from (airensoft/ovenmediaengine) repository. After installing , you can simply run the following command:
If the prerequisites.sh script fails, proceed with the .
if systemctl start ovenmediaengine
fails in Fedora, SELinux may be the cause. See .
You can live streaming using live encoders such as , , and . Please set the RTMP URL as below:
is a transmission SDK. So, you can easily add broadcast transmission functions to your apps using this SDK. And OvenStreamEncoder is a sample app that shows you can make and use it with OvenLiveKit. You can use it by searching in Google Play.
Also, we ran tests to see how well OvenStreamEnocder is optimized for OvenMediaEngine. If you are interested, click to check.
We have prepared a test player so that you can easily check if OvenMediaEngine is working properly. Please see the chapter on for more information.
If you want to build OvenPlayer in your environment, see .
Element
Description
RTMP
RTMP port for incoming RTMP stream.
SRT
SRT port for incoming SRT stream
MPEG-TS
MPEGTS ports for incoming MPEGTS/UDP stream.
WebRTC
Port for WebRTC. If you want more information on the WebRTC port, see the WebRTC Ingest and WebRTC Streaming chapters.
OVT
OVT port for an origin server.
OVT is a protocol defined by OvenMediaEngine for Origin-Edge communication. For more information about Origin-Edge, see the Origin-Edge Clustering chapter.
HLS
HTTP(s) port for HLS streaming.
DASH
HTTP(s) port for MPEG-DASH streaming including Low-Latency MPEG-DASH.
Value | Description |
true |
|
false | Accepts a new stream inputted as overlap and disconnects the existing stream. |
Env | Default Value |
OME_ORIGIN_PORT | 9000 |
OME_RTMP_PROV_PORT | 1935 |
OME_SRT_PROV_PORT | 9999/udp |
OME_MPEGTS_PROV_PORT | 4000-4005/udp |
OME_HLS_PUB_PORT | 8080 |
OME_DASH_PUB_PORT | 8080 |
OME_TCP_RELAY_ADDRESS | *:3478 |
OME_ICE_CANDIDATES | *:10000-10010/udp |
OME_SIGNALLING_PORT | 3333 |
Port | Purpose |
1935/TCP | RTMP Input |
9999/UDP | SRT Input |
4000-4005/UDP | MPEG-2 TS Input |
9000/TCP | Origin Server (OVT) |
80/TCP | HLS & MPEG-Dash Streaming |
3333/TCP | WebRTC Signalling (both ingest and streaming) |
3478/TCP | WebRTC TCP relay (TURN Server, both ingest and streaming) |
10000 - 10010/UDP | WebRTC Ice candidate (both ingest and streaming) |
From version 0.10.4, MPEG-2 TS input is supported as a beta version. The supported codecs are H.264, AAC(ADTS). Supported codecs will continue to be added. And the current version only supports basic MPEG-2 TS with 188 bytes packet size. Since the information about the input stream is obtained using PAT and PMT, the client must send this table information as required.
This version supports MPEG-2 TS over UDP. MPEG-2 TS over TCP or MPEG-2 TS over SRT will be supported soon.
To enable MPEG-2 TS, you must bind the ports fist and map the bound ports and streams.
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.
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.
This is an example of publishing using FFMPEG.
Giving the -pes_payload_size 0 option to the AAC codec is very important for AV synchronization and low latency. If this option is not given, FFMPEG bundles several ADTSs and is transmitted at once, which may cause high latency and AV synchronization errors.
If you use the default configuration, you can stream with the following streaming URLs when you start broadcasting to OBS:
WebRTC
ws://192.168.0.1:3333/app/stream_4000
HLS
http://192.168.0.1:8080/app/stream_4000/playlist.m3u8
MPEG-DASH
http://192.168.0.1:8080/app/stream_4000/manifest.mpd
Secure Reliable Transport (or SRT in short) is an open source video transport protocol and technology stack that optimizes streaming performance across unpredictable networks with secure streams and easy firewall traversal, bringing the best quality live video over the worst networks. We consider SRT to be one of the great alternatives to RTMP, and OvenMediaEngine can receive video streaming over SRT. For more information on SRT, please visit the SRT Alliance website.
SRT uses the MPEG-TS format when transmitting live streams. This means that unlike RTMP, it can support many codecs. Currently, OvenMediaEngine supports H.264, H.265, and AAC codecs received by SRT.
Set the SRT listen port as follows:
SRT input can be turned on/off for each application. As follows Setting enables the SRT input function of the application.
There are various encoders that support SRT such as FFMPEG, OBS Studio, and srt-live-transmit. Please check the specifications of each encoder on how to transmit streams through SRT from the encoder. We describe an example using OBS Studio.
OvenMediaEngine classifies each stream using SRT's streamid. This means that unlike MEPG-TS/udp, OvenMediaEngine can receive multiple SRT streams through one port. For more information on streamid, see Haivision's official documentation.
Therefore, in order for the SRT encoder to transmit a stream to OvenMediaEngine, the following information must be included in the streamid as percent encoded.
streamid = percent_encoding("srt://{host}[:port]/{app name}/{stream name}[?query=value]")
The streamid contains the URL format, so it must be percent encoded
OBS Studio 25.0 or later supports SRT. Please refer to the OBS official documentation for more information. Enter the address of OvenMediaEngine in OBS Studio's Server as follows: When using SRT in OBS, you can leave the Stream Key blank.
srt://ip:port?streamid=srt%3A%2F%2F{domain or IP address}[%3APort]%2F{App name}%2F{Stream name}
From version 0.10.4, RTSP Pull input is supported as a beta version. The supported codecs are H.264, AAC(ADTS). Supported codecs will continue to be added.
This function pulls a stream from an external RTSP server and operates as an RTSP client.
RTSP Pull is provided through OriginMap configuration. OriginMap is the rule that the Edge server pulls the stream of the Origin server. Edge server can pull a stream of origin with RTSP and OVT (protocol defined by OvenMediaEngine for Origin-Edge) protocol. See the Clustering section for more information about OVT.
For example, in the above setup, when a player requests "ws://ome.com/app_name/rtsp_stream_name" to stream WebRTC, it pulls the stream from "rtsp://192.168.0.200:554" and publishes it to WebRTC.
If the app name set in Location isn't created, OvenMediaEngine creates the app with default settings. The default generated app doesn't have an OPUS encoding profile, so to use WebRTC streaming, you need to add the app to your configuration.
The pull-type provider is activated by the publisher's streaming request. And if there is no client playing for 30 seconds, the provider is automatically disabled.
According to the above setting, the RTSP pull provider operates for the following streaming URLs.
OvenMediaEngine uses WebRTC to provide sub-second latency streaming. WebRTC uses RTP for media transmission and provides various extensions.
OvenMediaEngine provides the following features:
If you want to use the WebRTC feature, you need to add <WebRTC>
element to the <Publishers>
and <Ports> in the Server.xml
configuration file, as shown in the example below.
WebRTC uses ICE for connections and specifically NAT traversal. The web browser or player exchanges the Ice Candidate with each other in the Signalling phase. Therefore, OvenMediaEngine provides an ICE for WebRTC connectivity.
If you set IceCandidate to *: 10000-10005/udp
, as in the example above, OvenMediaEngine automatically gets IP from the server and generates IceCandidate
using UDP ports from 10000 to 10005. If you want to use a specific IP as IceCandidate, specify a specific IP. You can also use only one 10000 UDP Port, not a range, by setting it to *: 10000.
OvenMediaEngine has embedded a WebSocket-based signalling server and provides our defined signalling protocol. Also, OvenPlayer supports our signalling protocol. WebRTC requires signalling to exchange Offer SDP and Answer SDP, but this part isn't standardized. If you want to use SDP, you need to create your exchange protocol yourself.
If you want to change the signaling port, change the value of <Ports><WebRTC><Signalling>
.
The Signalling protocol is defined in a simple way:
If you want to use a player other than OvenPlayer, you need to develop the signalling protocol as shown above and can integrate OvenMediaEngine.
Add WebRTC
element to Publisher to provide streaming through WebRTC.
WebRTC Publisher's <JitterBuffer>
is a function that evenly outputs A/V (interleave) and is useful when A/V synchronization is no longer possible in the browser (player) as follows.
If the A/V sync is excessively out of sync, some browsers may not be able to handle this or it may take several seconds to synchronize.
Players that do not support RTCP also cannot A/V sync.
WebRTC Streaming starts when a live source is inputted and a stream is created. Viewers can stream using OvenPlayer or players that have developed or applied the OvenMediaEngine Signalling protocol.
Also, the codecs supported by each browser are different, so you need to set the Transcoding profile according to the browser you want to support. For example, Safari for iOS supports H.264 but not VP8. If you want to support all browsers, please set up VP8, H.264, and Opus codecs in all transcoders.
WebRTC doesn't support AAC, so when trying to bypass transcoding RTMP input, audio must be encoded as opus. See the settings below.
Some browsers support both H.264 and VP8 to send Answer SDP to OvenMediaEngine, but sometimes H.264 can't be played. In this situation, if you write the VP8 above the H.264 code line in the Transcoding profile setting, you can increase the priority of the VP8.
Using this manner so that some browsers, support H.264 but can't be played, can stream smoothly using VP8. This means that you can solve most problems with this method.
If you created a stream as shown in the table above, you can play WebRTC on OvenPlayer via the following URL:
If you use the default configuration, you can stream to the following URL:
ws://[OvenMediaEngine IP]:3333/app/stream
wss://[OvenMediaEngine IP]:3333/app/stream
You can turn on the TURN server by setting <TcpRelay> in the WebRTC Bind.
Example : <TcpRelay>*:3478</TcpRelay>
If * is used as the IP of TcpRelay and IceCandidate, all available candidates are generated and sent to the player, so the player tries to connect to all candidates until a connection is established. This can cause delay in initial playback. Therefore, specifying the ${PublicIP} macro or IP directly may be more beneficial to quality.
You can play the WebRTC stream over TCP by attaching the query transport=tcp
to the existing WebRTC play URL as follows.
OvenPlayer automatically sets iceServers by obtaining TURN server information set in <TcpRelay> through signaling with OvenMediaEngine.
If <TcpForce>
is set to true, it will force a TCP connection even if ?transport=tcp
is not present. To use this, <TcpRelay>
must be set.
If you are using custom player, set iceServers like this:
All libraries are installed, the system must be rebooted.
We have prepared a test player to make it easy to check if OvenMediaEngine is working. Please see the chapter for more information.
There are environments where the network speed is fast but UDP packet loss is abnormally high. In such an environment, WebRTC may not play normally. WebRTC does not support streaming using TCP, but connections to the TURN () server support TCP. Based on these characteristics of WebRTC, OvenMediaEngine supports TCP connections from the player to OvenMediaEngine by embedding a TURN server.
OME may sometimes not be able to get the server's public IP to its local interface. (Environment like Docker or AWS) So, specify the public IP for Relay IP
. If * is used, the public IP obtained from and all IPs obtained from the local interface are used. Port
is the tcp port on which the TURN server is listening.
WebRTC players can configure the TURN server through the setting.
When sending Request Offer
in the phase with OvenMediaEngine, if you send the transport=tcp
query string, ice_servers
information is delivered as follows. You can use this information to set iceServers.
Protocol
URL
WebRTC
ws:://ome.com:3333/app_name/rtsp_stream_name
HLS
http://ome.com:8080/app_name/rtsp_stream_name/playlist.m3u8
DASH
http://ome.com:8080/app_name/rtsp_stream_name/manifest.mpd
LL DASH
http://ome.com:8080/app_name/rtsp_stream_name/manifest_ll.mpd
Title | Functions |
Delivery | RTP / RTCP |
Security | DTLS, SRTP |
Connectivity | ICE |
Error Correction | ULPFEC (VP8, H.264), In-band FEC (Opus) |
Codec | VP8, H.264, Opus |
Signalling | Self-Defined Signalling Protocol and Embedded Web Socket-Based Server |
Option | Description | Default |
Timeout | ICE (STUN request/response) timeout as milliseconds, if there is no request or response during this time, the session is terminated. | 30000 |
Rtx | WebRTC retransmission, a useful option in WebRTC/udp, but ineffective in WebRTC/tcp. | false |
Ulpfec | WebRTC forward error correction, a useful option in WebRTC/udp, but ineffective in WebRTC/tcp. | false |
JitterBuffer | Audio and video are interleaved and output evenly, see below for details | false |
Protocol | URL format |
WebRTC Signalling | ws://<Server IP>[:<Signalling Port]/<Application name>/<Stream name> |
Secure WebRTC Signalling | wss://<Server IP>[:<Signalling Port]/<Application name>/<Stream name> |
Most browsers can't load resources via HTTP and WS (WebSocket) from HTTPS web pages secured with TLS. Therefore, if the player is on an HTTPS page, the player must request streaming through "https" and "wss" URLs secured with TLS. In this case, you must apply the TLS certificate to the OvenMediaEngine.
You can set the port for TLS in TLSPort
. Currently, only HLS, DASH, and WebRTC Signaling support TLS.
Add your certificate files to as follows:
To configure HTTPs for HLS, DASH, and WebRTC Signalling servers, the TLS element must be enabled. The CertPath has to indicate a server certificate and the KeyPath has to indicate a private key file. They can be set to absolute paths or relative paths from the executable. If the server certificate is issued using an intermediate certificate, some browsers may complain about a certificate. In this case, you should set a bundle of chained certificates provided by a Certificate Authority in ChainCertPath.
If you set up TLS, you can't set IP or * into <Name>. You can only set Domains that the certificate contains. If you have a certificate for *.host.com
, it means you can set domains such as aaa.host.com
, bbb.host.com
, and *.host.com
.
If the certificate settings are completed correctly, WebRTC streaming can be played wss://url
with HLS and DASH streaming https://url
.
The current version of OvenMediaEngine doesn't yet support SNI. This means that you can't set multiple TLS. So currently OvenMediaEngine can only set TLS on the first VirtualHost. We will support SNI in the next version.
OvenMediaEngine supports HTTP based streaming protocols such as HLS, MPEG-DASH(Hereafter DASH), and Low-Latency MPEG-DASH with CMAF(Hereafter LLDASH).
OvenMediaEngine will support Low-Latency HLS in the near future. We are always keeping an eye on the decision from Apple inc.
To use HLS, Dash and LLDash, you need to add the <HLS>
and<DASH>
elements to the <Publishers>
in the configuration as shown in the following example.
Most browsers and players prohibit accessing other domain resources in the currently running domain. You can control this situation through Cross-Origin Resource Sharing (CORS) or Cross-Domain (CrossDomain). You can set CORS and Cross-Domain as <CrossDomains>
element.
You can set it using the <Url>
element as shown above, and you can use the following values:
LLDASH, DASH, and HLS Streaming are ready when a live source is inputted and a stream is created. Viewers can stream using OvenPlayer or other players.
Also, you need to set H.264 and AAC in the Transcoding profile because MPEG-DASH and HLS use these codecs.
When you create a stream, as shown above, you can play LLDASH, DASH, and HLS through OvenPlayer with the following URL:
If you use the default configuration, you can start streaming with the following URL:
https://[OvenMediaEngine IP]:443/app/<stream name>_o/playlist.m3u8
http://[OvenMediaEngine IP]:80/app/<stream name>_o/playlist.m3u8
https://[OvenMediaEngine IP]:443/app/<stream name>_o/manifest.mpd
http://[OvenMediaEngine IP]:80/app/<stream name>_o/manifest.mpd
https://[OvenMediaEngine IP]:443/app/<stream name>_o/manifest_ll.mpd
http://[OvenMediaEngine IP]:80/app/<stream name>_o/manifest_ll.mpd
We have prepared a test player that you can quickly see if OvenMediaEngine is working. Please refer to the Test Player for more information.
OvenMediaEngine supports GPU-based hardware decoding and encoding. Currently supported GPU acceleration devices are Intel's QuickSync and NVIDIA's NVDECODE/NVENCODE. This document describes how to install the video driver for OvenMediaEngine to use the GPU and how to set the Config file. Please check what graphics card you have and refer to the NVIDIA or Intel driver installation guide.
Quick Sync Video format support: https://en.wikipedia.org/wiki/Intel_Quick_Sync_Video
If you are using an Intel CPU that supports QuickSync, please refer to the following guide to install the driver. The OSes that support installation using the provided scripts are CentOS 7/8 and Ubuntu 18/20 versions. If you want to install the driver on a different OS, please refer to the Manual Installation Guide document.
When the Intel QuickSync driver installation is complete, the OS must be rebooted for normal operation.
After the driver installation is complete, check whether the driver operates normally with the Matrix Monitor program.
If you are using an NVIDIA graphics card, please refer to the following guide to install the driver. The OS that supports installation with the provided script are CentOS 7/8 and Ubuntu 18/20 versions. If you want to install the driver in another OS, please refer to the manual installation guide document.
CentOS environment requires the process of uninstalling the nouveau driver. After uninstalling the driver, the first reboot is required, and a new NVIDIA driver must be installed and rebooted. Therefore, two install scripts must be executed.
After the driver installation is complete, check whether the driver is operating normally with the nvidia-smi command.
Describes how to enable GPU acceleration for users running OvenMediaEngine in the Docker runtime environment. To use GPU acceleration in Docker, the NVIDIA Driver must be installed on the host OS and the NVIDIA Container Toolkit must be installed. This toolkit includes container runtime libraries and utilities to use NVIDIA GPUs in Docker containers.
The NVIDIA Driver must have been previously installed
To use GPU when running Docker, you need to add the --gpus all option.
If the provided installation script fails, please refer to the manual installation guide.
If you have finished installing the driver to use the GPU, you need to reinstall the open source library using Prerequisites.sh . The purpose is to allow external libraries to use the installed graphics driver.
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.
You can build the OvenMediaEngine source using the following command. Same as the contents of Getting Started.
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
Quick Sync Video Format : https://en.wikipedia.org/wiki/Intel_Quick_Sync_Video
NVIDIA NVDEC Video Format : https://en.wikipedia.org/wiki/Nvidia_NVDEC
NVIDIA NVENV Video Format : https://en.wikipedia.org/wiki/Nvidia_NVENC
CUDA Toolkit Installation Guide : https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#introduction
NVIDIA Container Toolkit : https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/arch-overview.html#arch-overview
OvenMediaEngine has a built-in live transcoder. The live transcoder can decode the incoming live source and re-encode it with the set codec or adjust the quality to encode at multiple bitrates.
OvenMediaEngine currently supports the following codecs:
The <OutputProfile>
setting allows incoming streams to be re-encoded via the <Encodes>
setting to create a new output stream. The name of the new output stream is determined by the rules set in <OutputStreamName>
, and the newly created stream can be used according to the streaming URL format.
According to the above setting, if the incoming stream name is stream
, the output stream becomes stream_bypass
and the stream URL can be used as follows.
WebRTC
ws://192.168.0.1:3333/app/stream_bypass
Low-Latency MPEG-DASH
http://192.168.0.1:8080/app/`stream_bypass`/manifest_ll.mpd
You can set the video profile as below:
The meaning of each property is as follows:
Table of presets
A table in which presets provided for each codec library are mapped to OvenMediaEngine's presets. Slow presets are of good quality and use a lot of resources, whereas Fast presets have lower quality and better performance. It can be set according to your own system environment and service purpose.
References
https://trac.ffmpeg.org/wiki/Encode/H.264
https://x265.readthedocs.io/en/stable/presets.html
https://trac.ffmpeg.org/wiki/Encode/VP8
https://docs.nvidia.com/video-technologies/video-codec-sdk/nvenc-preset-migration-guide/
You can set the audio profile as below:
The meaning of each property is as follows:
It is possible to have an audio only output profile by specifying the Audio profile and omitting a Video one.
You can set the Image profile as below:
The meaning of each property is as follows:
The image encoding profile is only used by thumbnail publishers. and, bypass option is not supported.
You can configure Video and Audio to bypass transcoding as follows:
You need to consider codec compatibility with some browsers. For example, chrome only supports OPUS codec for audio to play WebRTC stream. If you set to bypass incoming audio, it can't play on chrome.
WebRTC doesn't support AAC, so if video bypasses transcoding, audio must be encoded in OPUS.
If you want to transcode with the same quality as the original. See the sample below for possible parameters that OME supports to keep original. If you remove the Width, Height, Framerate, Samplerate, and Channel parameters. then, It is transcoded with the same options as the original.
To change the video resolution when transcoding, use the values of width and height in the Video encode option. If you don't know the resolution of the original, it will be difficult to keep the aspect ratio after transcoding. Please use the following methods to solve these problems. For example, if you input only the Width value in the Video encoding option, the Height value is automatically generated according to the ratio of the original video.
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 HLS or MPEG-DASH, you need to set up H.264 and AAC, and if you want to stream using WebRTC, you need to set up Opus.
Also, if you are going to use WebRTC on all platforms, you need to configure both VP8 and H.264. This is because different codecs are supported for each browser, for example, VP8 only, H264 only, or both.
However, don't worry. If you set the codecs correctly, OME automatically sends the stream of codecs requested by the browser.
Currently, OME doesn't support adaptive streaming on HLS, MPEG-DASH. However, it will be updated soon.
SignedPolicy is a module that limits the user's privileges and time. For example, operators can distribute RTMP URLs that can be accessed for 60 seconds to authorized users, and limit RTMP transmission to 1 hour. The provided URL will be destroyed after 60 seconds, and transmission will automatically stop after 1 hour. Users who are provided with a SingedPolicy URL cannot access resources other than the provided URL. This is because the SignedPolicy URL is authenticated.
SingedPolicy URL consists of the query string of the streaming URL with Policy and Signature as shown below. If SignedPolicy is enabled in the configuration of OvenMediaEngine, access to URLs with no signature or invalid signature is not allowed. Signature uses HMAC-SHA1 to authenticate all URLs except signature.
Policy is in json format and provides the following properties.
url_expire means the time the URL is valid, so if you connect before the URL expires, you can continue to use it, and sessions that have already been connected will not be deleted even if the time expires. However, stream_expire forcibly terminates the session when the time expires even if it is already playing.
The URL entered into HMAC to generate the Signature must include :port.
When creating a signature, you cannot omit the default port such as http port 80, https port 443, or rtmp port 1935. This is because when OvenMediaEngine creates a signature for checking the signature, it is created by putting the port value.
When using SignedPolicy with SRT providers, only use the streamid portion of the URL, e.g. srt://myserver:9999?streamid=srt://myserver:9999/app/stream?policy=abc123
To enable SignedPolicy, you need to add the following <SingedPolicy> setting in Server.xml under <VirtualHost>.
We provide a script that can easily generate SingedPolicy 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:
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 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.
Generate SingedPolicy URL with the script.
Separate the URL based on "app" as shown in the example below and enter all the parts under the stream in the Stream Key.
AdmissionWebhooks are HTTP callbacks that query the control server to control publishing and playback admission requests.
Users can use the AdmissionWebhook for a variety of purposes, including customer authentication, tracking published streams, hide app/stream names, logging and more.
AdmissionWebhooks can be set up on VirtualHost, as shown below.
AdmissionWebhooks send HTTP/1.1 request message to the configured user's control server when an encoder requests publishing or a player requests playback. The request message format is as follows.
Here is a detailed explanation of each element of Json payload:
The control server may need to validate incoming http requests for security reasons. To do this, the AdmissionWebhooks module puts the X-OME-Signature
value in the HTTP request header. X-OME-Signature
is a base64 url safe encoded value obtained by encrypting the payload of an HTTP request with the HMAC-SHA1 algorithm using the secret key set in <AdmissionWebhooks><SecretKey>
of the configuration.
As shown below, the trigger condition of request is different for each protocol.
ControlServer must respond with the following Json format. In particular, the "allowed"
element is required.
new_url
redirects the original request to another app/stream. This can be used to hide the actual app/stream name from the user or to authenticate the user by inserting additional information instead of the app/stream name.
For example, you can issue a WebRTC streaming URL by inserting the user ID as follows: ws://domain.com:3333/user_id
It will be more effective if you issue a URl with the encrypted value that contains the user ID, url expiration time, and other information.
After the Control Server checks whether the user is authorized to play using user_id
, and responds with ws://domain.com:3333/app/sport-3
to new_url
, the user can play app/sport-3.
If the user has only one hour of playback rights, the Control Server responds by putting 3600000 in the lifetime
.
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.
We hope to provide SignedPolicy URL Generator Library in various languages. If you have created the SignedPolicy URL Generator Library in another language, please send a Pull Request to our . Thank you for your open source contributions.
In order to include the policy in the URL, it must be encoded with .
The message is sent in POST method and the payload is in application/json format. X-OME-Signature is a base64 url safe encoded value obtained by encrypting the payload with HMAC-SHA1 so that the ControlServer can validate this message. See the section for more information on X-OME-Signature.
Title
Functions
Delivery
HTTP for HLS and DASH HTTP 1.1 chunked transfer for LLDash
Security
TLS (HTTPS)
Format
TS for HLS
ISOBMFF for DASH
CMAF for LLDASH
Codec
H.264, AAC
Element
Decscription
Bind
Set the HTTP port to provide HLS and DASH. LLDASH and DASH are provided on the same port, and DASH and HLS can be set to the same port.
SegmentDuration
Set the length of the segment in seconds. The shorter the <SegmentDuration>
, the lower latency can be streamed, but it is less stable during streaming. Therefore, we are recommended to set it to 3 to 5 seconds.
SegmentCount
Set the number of segments to be exposed to *.mpd
. The smaller the number of <SegmentCount>
, the lower latency can be streamed, but it is less reliable during streaming. Therefore, it is recommended to set this value to 3.
It doesn't need to set SegmentCount for LLDASH because LLDASH only has one segment on OvenMediaEngine.
CrossDomains
Control the domain in which the player works through <CorssDomain>
. For more information, please refer to the CrossDomain section.
Url Value
Description
*
Allows requests from all Domains
domain
Allows both HTTP and HTTPS requests from the specified Domain
http://domain
Allows HTTP requests from the specified Domain
https://domain
Allows HTTPS requests from the specified Domain
Protocol
URL format
LLDASH
http://<Server IP>[:<DASH Port>]/<Application Name>/<Stream Name>/manifest_ll.mpd
Secure LLDASH
https://<Domain>[:<DASH TLSPort>]/<Application Name>/<Stream Name>/manifest_ll.mpd
DASH
http://<Server IP>[:<DASH Port>]/<Application Name>/<Stream Name>/manifest.mpd
Secure DASH
https://<Domain>[:<DASH TLSPort>]/<Application Name>/<Stream Name>/manifest.mpd
HLS
http://<Server IP>[:<HLS Port>]/<Application Name>/<Stream Name>/playlist.m3u8
Secure HLS
https://<Domain>[:<HLS TLSPort>]/<Application Name>/<Stream Name>/playlist.m3u8
Device
H264
H265
VP8
VP9
QuickSync
D / E
D / E
-
-
NVIDIA
D / E
D / E
-
-
Docker on NVIDIA Container Toolkit
D / E
D / E
-
-
Video Decoding
Audio Decoding
Video Encoding
Audio Encoding
Image Encoding
H.264 (Baseline)
AAC
H.264 (Baseline)
AAC
JPEG
VP8
Opus
PNG
Property
Description
Codec
Specifies the vp8
or h264
codec to use
Width
Width of resolution
Height
Height of resolution
Bitrate
Bit per second
Framerate
Frames per second
Preset
Presets of encoding quality and performance
Presets
x264/x265
libvpx
h264/265 NVC
h264/265 QSV
slower
slower
best
hq
-
slow
slow
best
llhq
-
medium
medium
good
bd
-
fast
fast
realtime
hp
-
faster
*faster
*realtime
*llhp
-
Property
Description
Codec
Specifies the opus
or aac
codec to use
Bitrates
Bits per second
Samplerate
Samples per second
Channel
The number of audio channels
Property
Description
Codec
Specifies the jpeg
or png
codec to use
Width
Width of resolution
Height
Height of resolution
Framerate
Frames per second
Protocol
Supported Codec
WebRTC
VP8, H.264, Opus
HLS
H.264, AAC
Low-Latency MPEG-Dash
H.264, AAC
Key | Value | Description |
url_expire (Required) | <Number> Milliseconds since unix epoch | The time the URL expires Reject on request after the expiration |
url_activate (Optional) | <Number> Milliseconds since unix epoch | The time the URL activates Reject on request before activation |
stream_expire (Optional) | <Number> Milliseconds since unix epoch | The time the Stream expires Transmission and playback stop when the time expires |
allow_ip (Optional) | <String> IPv4 CIDR | Allowed IP address range, 192.168.0.0/24 |
Key | Description |
PolicyQueryKeyName | The query string key name in the URL pointing to the policy value |
SignatureQueryKeyName | The query string key name in the URL pointing to the signature value |
SecretKey | The secret key used when encoding with HMAC-SHA1 |
Enables | List of providers and publishers to enable SignedPolicy. Currently, SingedPolicy supports rtmp among providers, and among publishers, WebRTC, HLS, MPEG-DASH, and Low-Latency MPEG-DASH (LLDASH) are supported. |
Element | Sub-Element | Description |
client | Information of the client who requested the connection. |
address | Client's IP address |
port | Client's Port number |
request | Information about the client's request |
direction | incoming : A client requests to publish a stream outgoing : A client requests to play a stream |
protocol | webrtc, srt, rtmp, hls, dash, lldash |
url | url requested by the client |
time | time requested by the client (ISO8601 format) |
Element | Description |
allowed (required) | true or false Allows or rejects the client's request. |
new_url (optional) | Redirects the client to a new url. However, the |
lifetime (optional) | The amount of time (in milliseconds) that a client can maintain a connection (Publishing or Playback)
HTTP based streaming (HLS, DASH, LLDASH) does not keep a connection, so this value does not apply. |
reason (optional) | If allowed is false, it will be output to the log. |
ApplicationType
>Application type
Examples
"live"
"vod"
Codec
>Codecs
Examples
"h264"
"h265"
"vp8"
"opus"
"aac"
StreamSourceType
>A type of input stream
Examples
"Ovt"
"Rtmp"
"Rtspc"
"RtspPull"
"MpegTs"
MediaType
>type
Examples
"video"
"audio"
SessionState
>A state of the session
Examples
"Ready"
"Started"
"Stopping"
"Stopped"
"Error"
AudioLayout
>Audio layout
Examples
"stereo"
"mono"
Key | Description |
ControlServerUrl | The HTTP Server to receive the query. HTTP and HTTPS are available. |
SecretKey | The secret key used when encrypting with HMAC-SHA1 |
Timeout | Time to wait for a response after request (in milliseconds) |
Enables | Enable Providers and Publishers to use AdmissionWebhooks |
Protocol | Condition |
WebRTC | When a client requests Offer SDP |
RTMP | When a client sends a publish message |
SRT |
HLS | Every time a client requests a playlist |
DASH | Every time a client requests a playlist |
LL-DASH | Every time a client requests a playlist |
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.
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.
In order to publish thumbnails, an encoding profile for thumbnails must be set. JPG and PNG are supported as codec. And framerate and resolution can be adjusted. Framerate is the number of thumbnails extracted per second. We recommend 1 as the thumbnail framerate. Thumbnail encoding uses a lot of resources. Therefore, if you increase this value excessively, it can cause a failure due to excessive use of system resources. The resolution can be set as desired by the user, and if the ratio is different from the input image, it is stretched. We plan to support various ratio modes in the future.
Declaring a thumbnail publisher. Cross-domain settings are available as a detailed option.
When the setting is made for the thumbnail and the stream is input, you can view the thumbnail through the following URL.
OvenMediaEngine supports clustering and ensures High Availability (HA) and scalability.
OvenMediaEngine supports the Origin-Edge structure for cluster configuration and provides scalability. Also, you can set Origin as Primary
and Secondary
in OvenMediaEngine for HA.
The OvenMediaEngine running as edge pulls a stream from an external server when a user requests it. The external server could be another OvenMediaEngine with OVT enabled or another stream server that supports RTSP.
The OVT is a protocol defined by OvenMediaEngine to relay stream between Origin-Edge and OVT can be run over SRT and TCP. For more information on the SRT Protocol, please visit the SRT Alliance site.
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 :
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 or RTSP is bypassed without being encoded.
In order to re-encode the stream created by OVT and RTSP, the function to put into an existing application will be supported in the future.
To run OvenMediaEngine as Edge, you need to add Origins elements to the configuration file as follows:
The <Origin>
is a rule about where to pull a stream from for what request.
The <Origin>
has the ability to automatically create an application with that name if the application you set in <Location>
doesn't exist on the server. If an application exists in the system, a stream will be created in the application.
The automatically created application by <Origin>
enables all providers but if you create an application yourself, you must enable the provider that matches the setting as follows.
For a detailed description of Origin's elements, see:
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 consists of Scheme and Url.
<Scheme>
is the protocol that will use to pull from the Origin Stream. It currently can be configured as OVT
or RTSP
.
If the origin server is OvenMediaEngine, you have to set OVT
into the <Scheme>
.
You can pull the stream from the RTSP server by setting RTSP
into the<Scheme>
. In this case, the <RTSPPull>
provider must be enabled. The application automatically generated by Origin doesn't need to worry because all providers are enabled.
Urls
is the address of origin stream and can consist of multiple URLs.
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.
When you are configuring Load Balancer, you need to use third-party solutions such as L4 Switch, LVS, or GSLB, but we recommend using DNS Round Robin. Also, services such as cloud-based AWS Route53, Azure DNS, or Google Cloud DNS can be a good alternative.
OvenMediaEngine can record live streams. You can start and stop recording the output stream through REST API. When the recording is complete, a recording information file is created together with the recorded file so that the user can perform various post-recording processing.
To enable recording, add the <FILE>
publisher to the configuration file as shown below. <FilePath>
and <InfoPath>
are required and used as default values. <FilePath> is the setting for the file path and file name. <InfoPath>
is the setting for the path and name of the XML file that contains information about the recorded files. If there is no file path value among parameters when requesting recording through API, recording is performed with the set default value. This may be necessary if for security reasons you do not want to specify the file path when calling the API to avoid exposing the server's internal path. <<RootPath>
is an optional parameter. It is used when requesting with a relative path is required when requesting an API. also, it is applied to <FilePath>
and <InfoPath>
as in the example below.
You must specify .ts
or .mp4
at the end of the FilePath string to select a container for the recording file. We recommend using .ts unless you have a special case. This is because vp8 and opus codecs are not recorded due to container limitations if you choose .mp4.
Various macro values are supported for file paths and names as shown below.
For control of recording, use the REST API. Recording can be requested based on the output stream name (specified in the JSON body), and all/some tracks can be selectively recorded. And, it is possible to simultaneously record multiple files for the same stream. When recording is complete, an XML file is created at the path specified in InfoPath. For a sample of the recorded file information XML, refer to Appendix A.
For how to use the API, please refer to the link below.
Split recording methods provide interval and schedule. The interval method splits files based on the accumulated recording time. The Schedule method then splits files according to scheduling options based on system time. The scheduling option is the same as the pattern used in crontab. However, only three options are used: seconds/minutes/hour.
interval and schedule methods cannot be used simultaneously.
The following is a sample of an XML file that expresses information on a recorded file.
The REST APIs provided by OME allow you to query or change settings such as VirtualHost and Application/Stream.
The APIs are currently beta version, so there are some limitations/considerations.
Settings of VirtualHost can only be viewed and cannot be changed or deleted.
If you add/change/delete the settings of the App/Output Profile by invoking the API, the app will be restarted. This means that all sessions associated with the app will be disconnected.
The API version is fixed with v1 until the experimental stage is complete, and the detailed specification can be changed at any time.
By default, OvenMediaEngine's APIs are disabled, so the following settings are required to use the API:
Set the <Port>
to use by the API server. If you omit <Port>
, you will use the API server's default port, port 8081
.
<Host>
sets the Host name and TLS certificate information to be used by the API server, and <AccessToken>
sets the token to be used for authentication when calling the APIs. You must use this token to invoke the API of OvenMediaEngine.
In this manual, the following format is used when describing the API.
GET
http://<OME_HOST>:<API_PORT>/<VERSION>/<API_PATH>[/...]
Here is the description of the API
Request Example:
- Method: GET
- URL: http://1.2.3.4:8081/v1/vhost
- Header:
authorization: Basic b21ldGVzdA==
This means the IP or domain of the server on which your OME is running.
This means the port number of the API you set up in Server.xml
. The default value is 8081.
Indicates the version of the API. Currently, all APIs are v1.
Indicates the API path to be called. The API path is usually in the following form:
resource
means an item, such as VirtualHost
or Application
, and action
is used to command an action to a specific resource, such as push
or record
.
For more information, see .
When a client send a
Name | Type | Description |
---|
Name | Type | Description |
---|
All response results are provided in the HTTP status code and response body, and if there are multiple response results in the response, the HTTP status code will be 207 MultiStatus
. The API response data is in the form of an array of or as follows:
Method
URL Pattern
GET
http(s)://<ome_host>:<port>/<app_name>/<output_stream_name>/thumb.<jpg|png>
Macro
Description
${TransactionId}
Unique ID for the recording transaction. It is automatically created when recording starts. and is released when recording is stopped. In case of split recording, it is distinguished that it is the same transaction.
${Id}
User-defined identification ID
${StartTime:YYYYMMDDhhmmss}
Recording start time
YYYY - Year
MM - Month
DD - Days
hh : Hours (0~23)
mm : Minutes (00~59)
ss : Seconds (00~59)
${EndTime:YYYYMMDDhhmmss}
Recording end time
YYYY - Year
MM - Month
DD - Days
hh : Hours (0~23)
mm : Minutes (00~59)
ss : Seconds (00~59)
${VirtualHost}
Virtual host name
${Application}
Application name
${SourceStream}
Source stream name
${Stream}
Output stream name
${Sequence}
Sequence value that increases when splitting a file in a single transaction
Type | Description | Examples |
Short | 16bits integer |
|
Int | 32bits integer |
|
Long | 64bits integer |
|
Float | 64bits real number |
|
String | A string |
|
Bool | true/false |
|
Timestamp (String) | A timestamp in ISO8601 format |
|
TimeInterval (Long) | A time interval (unit: milliseconds) |
|
IP (String) | IP address |
|
RangedPort (String) | Port numbers with range (it can contain multiple ports and protocols)
|
|
Port (String) | A port number
|
|
string |
authorization | string |
|
OvenMediaEngine supports Push Publishing function that can retransmit live streams to other systems. The protocol supported for retransmission uses RTMP. Because, most services and products support this protocol. also, one output stream can be transmitted to multiple destinations at the same time. You can start and stop pushing the output stream through REST API. Note that the only codecs that can be retransmitted in RTMP protocol are H264 and AAC.
To use RTMP Push Publishing, you need to declare the <RTMPPush>
publisher in the configuration. There are no other detailed options.
Only H264 and AAC are supported codecs.
For control of push, use the REST API. RTMP push can be requested based on the output stream name (specified in the JSON body), and you can selectively transfer all/some tracks. In addition, you must specify the URL and Stream Key of the external server to be transmitted. It can send multiple Pushes simultaneously for the same stream. If transmission is interrupted due to network or other problems, it automatically reconnects.
For how to use the API, please refer to the link below.
GET
http://<OME_HOST>:<API_PORT>/v1/vhosts
Lists all virtual host names
Request Example:
GET http://1.2.3.4:8081/v1/vhosts
GET
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}
Gets the configuration of the VirtualHost
Request Example:
GET http://1.2.3.4:8081/v1/vhosts/default
POST
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps
Creates Application
s in the VirtualHost
Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps
[
{
"name": "app",
"type": "live",
"outputProfiles": [
{
"name": "bypass_profile",
"outputStreamName": "${OriginStreamName}",
"encodes": {
"videos": [
{
"bypass": true
}
],
"audios": [
{
"bypass": true
}
]
}
}
]
}
]
GET
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps
Lists all application names in the VirtualHost
Request Example:
GET http://1.2.3.4:8081/v1/vhosts/default/apps
GET
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}
Gets the configuration of the Application
Request Example:
GET http://1.2.3.4:8081/v1/vhosts/default/apps/app
PUT
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}
Changes the configuration of the Application
Request Example:
PUT http://1.2.3.4:8081/v1/vhosts/default/apps/app
{
"type": "live"
}
DELETE
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}
Deletes the Application
Request Example:
DELETE http://1.2.3.4:8081/v1/vhosts/default/apps/app
[TYPE]
>GET
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}/streams
Lists all stream names in the Application
Request Example:
GET http://1.2.3.4:8081/v1/vhosts/default/apps/app/streams
GET
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}/streams/{stream_name}
Gets the configuration of the Stream
Request Example:
GET http://1.2.3.4:8081/v1/vhosts/default/apps/app/streams/stream
POST
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}:startRecord
This API performs a recording start request operation. for recording, the output stream name must be specified. file path, information path, recording interval and schedule parameters can be specified as options.
Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps/app:startRecord
{
"id": "custom_id",
"stream": {
"name": "stream_o",
"tracks": [ 100, 200 ]
},
"filePath" : "/path/to/save/recorded/file_${Sequence}.ts",
"infoPath" : "/path/to/save/information/file.xml",
"interval" : 60000, # Split it every 60 seconds
"schedule" : "0 0 */1" # Split it at second 0, minute 0, every hours.
"segmentationRule" : "continuity"
}
POST
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}:stopRecord
This API performs a recording stop request.
Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps/app:stopRecord
{
"id": "custom_id"
}
POST
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}:records
This API performs a query of the job being recorded. Provides job inquiry function for all or custom Id.
Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps/app:records
{
"id" : "custom_id"
}
POST
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}/outputProfiles
Creates OutputProfile
s in the Application
Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps/app/outputProfiles
[
{
"name": "bypass_profile",
"outputStreamName": "${OriginStreamName}",
"encodes": {
"videos": [
{
"bypass": true
}
],
"audios": [
{
"bypass": true
}
]
}
}
]
GET
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}/outputProfiles
Lists all output profile names in the Application
Request Example:
GET http://1.2.3.4:8081/v1/vhosts/default/apps/app/outputProfiles
GET
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}/outputProfiles/{profile_name}
Gets the configuration of the OutputProfile
Request Example:
GET http://1.2.3.4:8081/v1/vhosts/default/apps/app/outputProfiles/bypass_profile
PUT
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}/outputProfiles/{profile_name}
Changes the configuration of the OutputProfile
Request Example:
PUT http://1.2.3.4:8081/v1/vhosts/default/apps/app/outputProfiles/bypass_profile
{
"outputStreamName": "${OriginStreamName}",
"encodes": {
"videos": [
{
"codec": "h264",
"bitrate": "3M",
"width": 1280,
"height": 720,
"framerate": 30
}
],
"audios": [
{
"bypass": true
}
]
}
}
DELETE
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}/outputProfiles/{profile_name}
Deletes the OutputProfile
Request Example:
DELETE http://1.2.3.4:8081/v1/vhosts/default/apps/app/outputProfiles/bypass_profile
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
Name | Type | Description |
---|
authorization
string
A string for authentication in Basic Base64(AccessToken)
format.
For example, Basic b21lLWFjY2Vzcy10b2tlbg==
if access token is ome-access-token
.
vhost_name
string
A name of VirtualHost
authorization
string
A string for authentication in Basic Base64(AccessToken)
format.
For example, Basic b21lLWFjY2Vzcy10b2tlbg==
if access token is ome-access-token
.
vhost_name
string
A name of VirtualHost
authorization
string
A string for authentication in Basic Base64(AccessToken)
format.
For example, Basic b21lLWFjY2Vzcy10b2tlbg==
if access token is ome-access-token
.
(json body)
array
A list of Application
vhost_name
string
A name of VirtualHost
authorization
string
A string for authentication in Basic Base64(AccessToken)
format.
For example, Basic b21lLWFjY2Vzcy10b2tlbg==
if access token is ome-access-token
.
vhost_name
string
A name of VirtualHost
app_name
string
A name of Application
authorization
string
A string for authentication in Basic Base64(AccessToken)
format.
For example, Basic b21lLWFjY2Vzcy10b2tlbg==
if access token is ome-access-token
.
vhost_name
string
A name of VirtualHost
app_name
string
A name of Application
authorization
string
A string for authentication in Basic Base64(AccessToken)
format.
For example, Basic b21lLWFjY2Vzcy10b2tlbg==
if access token is ome-access-token
.
(json body)
object
Application
vhost_name
string
A name of VirtualHost
app_name
string
A name of Application
authorization
string
A string for authentication in Basic Base64(AccessToken)
format.
For example, Basic b21lLWFjY2Vzcy10b2tlbg==
if access token is ome-access-token
.
Type
Name
Optional
Description
Examples
Int
statusCode
N
Status code
200
String
message
N
A message describing the value returned
"OK"
[TYPE]
response
Y
A response data
{}
Type
Name
Optional
Description
Examples
String
name
N
A name of Virtual Host
"default"
Host
td
Y
Host
Host
SignedPolicy
signedPolicy
Y
SignedPolicy
SignedPolicy
SignedToken
signedToken
Y
SignedToken
SignedToken
List<OriginMap
>
td
Y
A list of Origin map
[OriginMap, OriginMap, ...]
Type
Name
Optional
Description
Examples
List<String>
td
N
A list of hosts
["airensoft.com", "*.test.com", ...]
Tls
td
Y
TLS
TLS
Type
Name
Optional
Description
Examples
String
certPath
N
A path of cert file
"a.crt"
String
keyPath
N
A path of private key file
"a.key"
String
chainCertPath
Y
A path of chain cert file
"c.crt"
Type
Name
Optional
Description
Examples
String
policyQueryKey
N
String
signatureQueryKey
N
String
secretKey
N
Type
Name
Optional
Description
Examples
String
cryptoKey
N
String
queryStringKey
N
Type
Name
Optional
Description
Examples
String
location
N
A pattern to map origin
"/"
Pass
pass
N
What to request with Origin if the pattern matches
Pass
Type
Name
Optional
Description
Examples
String
scheme
N
Scheme to distinguish the provider
"ovt"
List<String>
urls
N
An address list to pull from provider
["origin:9000", "origin2:9000", ...]
Type
Name
Optional
Description
Examples
String
name
N
App name (You cannot change this value after you create it)
"app"
Bool
dynamic
N
Whether the app was created using PullStream()
true
Enum<ApplicationType
>
type
N
App type
"live"
Providers
providers
Y
A list of Provider
s
Providers
Publishers
publishers
Y
A list of Publisher
s
Publishers
List<OutputProfile
>
outputProfiles
Y
A list of OutputProfile
s
[OutputProfile, OutputProfile, ...]
Type
Name
Optional
Description
Examples
RtmpProvider
rtmp
Y
RtmpProvider
RtspPullProvider
rtspPull
Y
RtspPullProvider
RtspProvider
rtsp
Y
RtspProvider
OvtProvider
ovt
Y
OvtProvider
MpegtsProvider
mpegts
Y
MpegtsProvider
Type
Name
Optional
Description
Examples
(Reserved for future use)
-
-
-
Type
Name
Optional
Description
Examples
(Reserved for future use)
-
-
-
Type
Name
Optional
Description
Examples
(Reserved for future use)
-
-
-
Type
Name
Optional
Description
Examples
(Reserved for future use)
-
-
-
Type
Name
Optional
Description
Examples
List<MpegtsStream
>
streams
Y
MPEG-TS Stream map
[MpegtsStream, MpegtsStream, ...]
Type
Name
Optional
Description
Examples
String
name
N
A name to generate when MPEG-TS stream is received
"stream"
RangedPort
port
Y
MPEG-TS Port
"40000-40001/udp"
Type
Name
Optional
Description
Examples
Int
threadCount
N
Number of threads
4
RtmpPushPublisher
rtmpPush
Y
RtmpPushPublisher
HlsPublisher
hls
Y
HlsPublisher
DashPublisher
dash
Y
DashPublisher
LlDashPublisher
llDash
Y
LlDashPublisher
WebrtcPublisher
webrtc
Y
WebrtcPublisher
OvtPublisher
ovt
Y
OvtPublisher
FilePublisher
file
Y
FilePublisher
ThumbnailPublisher
thumbnail
Y
ThumbnailPublisher
Type
Name
Optional
Description
Examples
(Reserved for future use)
-
-
-
Type
Name
Optional
Description
Examples
Int
segmentCount
N
Segment count in the playlist.m3u8
3
Int
segmentDuration
N
Segment duration (unit: seconds)
4
List<String>
crossDomains
Y
Cross domain URLs
["*"]
Type
Name
Optional
Description
Examples
Int
segmentCount
N
Segment count in the manifest.mpd
3
Int
segmentDuration
N
Segment duration (unit: seconds)
4
List<String>
crossDomains
Y
Cross domain URLs
["*"]
Type
Name
Optional
Description
Examples
Int
segmentDuration
N
Segment duration (unit: seconds)
3
List<String>
crossDomains
Y
Cross domain URLs
["*"]
Type
Name
Optional
Description
Examples
TimeInterval
timeout
Y
ICE timeout (unit: seconds)
30
Type
Name
Optional
Description
Examples
(Reserved for future use)
-
-
-
Type
Name
Optional
Description
Examples
String
filePath
Y
A path to store recorded file
You can use the following macros:
${TransactionId}: An identifier of transaction
${Id}: An identifier to distinguish files
${StartTime:YYYYMMDDhhmmss}: Start time of recording
${EndTime:YYYYMMDDhhmmss}: End time of of recording
${VirtualHost}: A name of virtual host
${Application}: A name of application
${SourceStream}: A name of input stream
${Stream}: A name of output stream
${Sequence}: A sequence number
"/tmp/${StartTime:YYYYMMDDhhmmss}_${Stream}.mp4"
String
fileInfoPath
Y
A path of recorded files
"/tmp/${StartTime:YYYYMMDDhhmmss}_${Stream}.xml"
Type
Name
Optional
Description
Examples
List<String>
crossDomains
Y
Cross domain URLs
["*"]
Type
Name
Optional
Description
Examples
String
name
N
A name of OutputProfile
"bypass_stream"
String
outputStreamName
N
A name of output stream
"${OriginStreamName}"
Encodes
encodes
Y
[Encodes, Encodes, ...]
Type
Name
Optional
Description
Examples
List<Video
>
videos
Y
[Video, Video, ...]
List<Audio
>
audios
Y
[Audio, Audio, ...]
List<Image
>
images
Y
[Image, Image, ...]
Type
Name
Optional
Description
Examples
Bool
bypass
Y
true
Enum<Codec
>
codec
Conditional
Video codec
"h264"
Int
width
Conditional
1280
Int
height
Conditional
720
String
bitrate
Conditional
bitrate (You can use "K" or "M" suffix like 100K
, 3M
)
"3000000"
"2.5M"
Float
framerate
Conditional
29.997
Type
Name
Optional
Description
Examples
Bool
bypass
Y
true
Enum<Codec
>
codec
Conditional
Audio codec
"opus"
Int
samplerate
Conditional
48000
Int
channel
Conditional
2
String
bitrate
Conditional
bitrate (You can use "K" or "M" suffix like 128K
, 0.1M
)
"128000"
"128K"
Type
Name
Optional
Description
Examples
Enum<Codec
>
codec
N
"jpeg" | "png"
Int
width
Conditional
854
Int
height
Conditional
480
Float
framerate
N
An interval of image creation
1
Type
Name
Optional
Description
Examples
String
name
N
A name of stream
"stream"
InputStream
input
N
An information of input stream
InputStream
List<OutputStream
>
outputs
N
An information of output streams
[OutputStream, OutputStream, ...]
Type
Name
Optional
Description
Examples
String
name
N
A name of stream to create
"stream"
PullStream
pull
Y
pull
PullStream
MpegtsStream
mpegts
Y
Creates a prestream
MpegtsStream
Type
Name
Optional
Description
Examples
String
url
N
URL to pull
"rtsp://host.com/resource"
Type
Name
Optional
Description
Examples
String
agent
Y
A name of broadcast tool
"OBS 12.0.4"
String
from
N
URI stream created
"tcp://192.168.0.200:33399"
String
to
Y
URI represents connection with the input
"rtmp://dev.airensoft.com:1935"
List<Track
>
tracks
N
A list of tracks in input stream
[Track, Track, ...]
Timestamp
createdTime
N
Creation time
"2020-10-30T11:00:00+09:00"
Type
Name
Optional
Description
Examples
String
name
N
An name of OutputStream
"stream_o"
List<Track
>
tracks
N
A list of tracks in OutputStream
[Track, Track, ...]
Type
Name
Optional
Description
Examples
Enum<MediaType
>
type
Y
Media type
"video"
Video
video
Conditional
A configuration of video encoding
Video
Audio
audio
Conditional
A configuration of audio encoding
Audio
Type
Name
Optional
Description
Examples
(Extends Video
)
-
-
Timebase
timebase
Y
Timebase
Timebase
Type
Name
Optional
Description
Examples
Int
num
N
Numerator
1
Int
den
N
Denominator
90000
Type
Name
Optional
Description
Examples
(Extends Audio
)
-
-
true
Timebase
timebase
Y
Timebase
Timebase
Type
Name
Optional
Description
Examples
String
id
Y
Unique identifier
OutputStream
streams
N
A combination of output stream's track name and track id
Enum<SessionState
>
state
N
Record state
String
filePath
N
A path of recorded files
String
fileInfoPath
N
A path of recorded file informations
String
recordedBytes
N
Recorded bytes
Int
recordedTime
N
Recorded time
Timestamp
startTime
N
Started time
Timestamp
finishTime
N
Finished time
Int
bitrate
N
Average bitrate
Type
Name
Optional
Description
Examples
String
id
N
Unique identifier
OutputStream
stream
Y
A combination of output stream's track name and track id
Enum<StreamSourceType
>
protocol
Y
Protocol of input stream
String
url
Y
Destination URL
String
streamKey
Conditional
Stream key of destination
Enum<SessionState
>
state
N
Push state
Int
sentBytes
N
Sent bytes
Int
sentPackets
N
Sent packets count
Int
sentErrorBytes
N
Error bytes
Int
sentErrorPackets
N
Error packets count
Int
reconnect
N
Reconnect count
Timestamp
startTime
N
Started time
Timestamp
finishTime
N
Finished time
Int
bitrate
N
Average bitrate
Type
Name
Optional
Description
Examples
Timestamp
createdTime
N
Creation time
"2020-10-30T11:00:00+09:00"
Timestamp
lastUpdatedTime
N
Modified time
"2020-10-30T11:00:00+09:00"
Long
totalBytesIn
N
Received bytes
3109481213
Long
totalBytesOut
N
Sent bytes
1230874123
Int
totalConnections
N
Current connections
10
Int
maxTotalConnections
N
Max connections since the stream is created
293
Timestamp
maxTotalConnectionTime
N
When the maximum number of concurrent connections has been updated.
"2020-10-30T11:00:00+09:00"
Timestamp
lastRecvTime
N
Last time data was received
"2020-10-30T11:00:00+09:00"
Timestamp
lastSentTime
N
Last time data was sent
"2020-10-30T11:00:00+09:00"
Type
Name
Optional
Description
Examples
(Extends CommonMetrics
)
-
-
Includes all fields of CommonMetrics
TimeInterval
requestTimeToOrigin
Y
A elapsed time to connect to Origin
1000
TimeInterval
responseTimeFromOrigin
Y
A elapsed time from Origin to respond
10000
vhost_name | string | A name of |
app_name | string | A name of |
authorization | string | A string for authentication in |
vhost_name | string | A name of |
app_name | string | A name of |
stream_name | string | A name of |
authorization | string | A string for authentication in |
vhost_name | string | A name of |
app_name | string | A name of |
authorization | string | A string for authentication in |
segmentationRule | string | Define the policy for continuously or discontinuously generating timestamp in divided recorded files. - continuity - discontinuity (default) |
id | string | An unique identifier for recording job. |
stream | string | Output stream. |
name | string | Output stream name. |
tracks | array | Default is all tracks. It is possible to record only a specific track using the track Id. - default is all tracks |
schedule | string | Schedule based split recording. set only <second minute hour> using crontab method. It cannot be used simultaneously with interval. |
interval | number | Interval based split recording. It cannot be used simultaneously with schedule. |
filePath | string | Set the path of the file to be recorded. same as setting macro pattern in Config file. |
infoPath | string | Set the path to the information file to be recorded. same as setting macro pattern in Config file. |
vhost_name | string | A name of |
app_name | string | A name of |
authorization | string | A string for authentication in |
id | string | An unique identifier for recording job. |
vhost_name | string | A name of |
app_name | string | A name of |
authorization | string | A string for authentication in |
id | string | An unique identifier for recording job. If no value is specified, the entire recording job is requested. |
vhost_name | string | A name of |
app_name | string | A name of |
authorization | string | A string for authentication in |
(json body) | array | List< |
vhost_name | string | A name of |
app_name | string | A name of |
authorization | string | A string for authentication in |
vhost_name | string | A name of |
app_name | string | A name of |
profile_name | string | A name of |
authorization | string | A string for authentication in |
vhost_name | string | A name of |
app_name | string | A name of |
profile_name | string | A name of |
authorization | string | A string for authentication in |
(json body) | object |
|
vhost_name | string | A name of |
app_name | string | A name of |
profile_name | string | A name of |
authorization | string | A string for authentication in |
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.
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
This is available through the Monitoring class, and we use this information to generate various log files. OvenMediaEngine outputs various statistics through log files. OvenMediaEngine now prints logs for WebRTC and HTTP based streamings, but its format is for a specific purpose and isn't standardized. This will be standardized in future 1.0 and will be published throughout this manual.
Currently, OvenMediaEngine outputs statistics like this:
The statistics logs are mostly different because they are collected from Bigdata's collection system and output for various purposes. OvenMediaEngine is open-source, so you have the flexibility to respond in such situations. OME keeps all the metrics for Vhost, App, and Stream in the Monitoring Class, so anyone can use them.
We provide you our test player to make sure that OvenMediaEngine works well. Most browsers prohibit access to the TLS-based HTTPS site through unsecured HTTP or WebSocket (WS) for security reasons. Thus, we have prepared the HTTP or HTTPS based player as follows:
When playing Low-Latency DASH, you can control the delay time in the player as shown below. Delay time is closely related to the buffering size. The smaller the value, the shorter the latency, but if it is too small, there is no buffer and playback may not be smooth. In a typical network environment, it is most stable to give 2 as the delay value.
GET
http://<OME_HOST>:<API_PORT>/v1/stats/current/vhosts/{vhost_name}
Usage statistics of the VirtualHost
Request Example:
GET http://1.2.3.4:8081/v1/stats/current/vhosts/default
GET
http://<OME_HOST>:<API_PORT>/v1/stats/current/vhosts/{vhost_name}/apps/{app_name}
Usage statistics of the Application
Request Example:
GET http://1.2.3.4:8081/v1/stats/current/vhosts/default/apps/app
GET
http://<OME_HOST>:<API_PORT>/v1/stats/current/vhosts/{vhost_name}/apps/{app_name}/streams/{stream}
Usage statistics of the Stream
Request Example:
GET http://1.2.3.4:8081/v1/stats/current/vhosts/default/apps/app/streams/{stream}
POST
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}:startPush
This is an action to request a push of a selected stream. Please refer to the "Push" document for detail setting.
Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps/app:startPush
{
"id": "{UserDefinedUniqueId}",
"stream": {
"name": "output_stream_name",
"tracks": [
101,
102 ]
},
"protocol": "rtmp",
"url":"rtmp://{host}[:port]/{appName}",
"streamKey":"{streamName}"
}
POST
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}:stopPush
Request to stop pushing
Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps/app:stopRecord
{
"id": "{userDefinedUniqueId}"
}
POST
http://<OME_HOST>:<API_PORT>/v1/vhosts/{vhost_name}/apps/{app_name}:pushes
Get all push lists for a specific application
Request Example:
POST http://1.2.3.4:8081/v1/vhosts/default/apps/app:pushes
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.
Since OvenRtcTester is developed in Go language, Go must be installed on your system. Install Go from the following URL: https://golang.org/doc/install
OvenRtcTester was tested with the latest version of go 1.17.
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.
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 tuning the number of threads.
This is the result of tuning the number of StreamWorkerCount to 8 in config. This time, we simulated 1000 players with OvenRtcTester, and you can see that it works stably.
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.
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.
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.
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.
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.
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.
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.
When OvenMediaEngine receives a WebRTC connection request from a new player, it determines the Host Peer or Client Peer according to the following rules:
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.
prerequisites.sh
Script FailedIf you have problems with the prerequisites.sh
script we have provided, please install it manually as follows.
systemctl start ovenmediaengine
failedIf SELinux is running on your system, SELinux can deny the execution of OvenMediaEngine.
You can choose between two methods of adding a policy to SELinux or setting SELinux to permissive mode. To add a policy, you must apply the SELinux policy file for the OvenMediaEngine service to your system as follows:
Setting SELinux to permissive mode is as simple as follows. But we don't recommend this method.
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
Name | Type | Description |
---|---|---|
If you have a better idea, we hope that you improve our code and contribute to our project. Please visit .
Site URL
Description
A player without TLS that can test all streaming URLs such as WS://
, WSS://
, HTTP://
, HTTPS://
A player with TLS that can only test WSS://
and HTTPS://
based streaming URLs
vhost_name
string
A name of VirtualHost
access_token
string
A token for authentication
vhost_name
string
A name of VirtualHost
app_name
string
A name of Application
access_token
string
A token for authentication
vhost_name
string
A name of VirtualHost
app_name
string
A name of Application
stream_name
string
A name of Stream
access_token
string
A token for authentication
vhost_name*
string
A name of VirtualHost
app_name*
string
A name of Application
authorization*
string
A string for authentication in Basic Base64(AccessToken)
format.
For example, Basic b21lLWFjY2Vzcy10b2tlbg==
if access token is ome-access-token
.
id*
string
Unique identifier for push management. if there is no value, automatically created and returned
stream*
string
Output stream for push
name*
string
Output stream name
tracks
string
Track id for want to push, if there is no value, all tracks are push
protocol*
string
Transport protocol [rtmp | mpegts]
url*
string
Destination URL
streamKey*
object
Destination stream key
vhost_name*
string
A name of VirtualHost
app_name*
string
A name of Application
authorization*
string
A string for authentication in Basic Base64(AccessToken)
format.
For example, Basic b21lLWFjY2Vzcy10b2tlbg==
if access token is ome-access-token.
id*
string
Unique identifier for push management
vhost_name*
string
A name of VirtualHost
app_name*
string
A name of Application
authorization*
string
A string for authentication in Basic Base64(AccessToken)
format.
For example, Basic b21lLWFjY2Vzcy10b2tlbg==
if access token is ome-access-token
.
Thread name
Element in the configuration
AW-XXX
<Application><Publishers><AppWorkerCount>
StreamWorker
<Application><Publishers><StreamWorkerCount>
SPICE-XXX
<Bind><Provider><WebRTC><IceCandidates><TcpRelayWorkerCount>
<Bind><Pubishers><WebRTC><IceCandidates><TcpRelayWorkerCount>
SPRtcSignalling
<Bind><Provider><WebRTC><Signalling><WorkerCount>
<Bind><Pubishers><WebRTC><Signalling><WorkerCount>
SPSegPub
<Bind><Pubishers><HLS><WorkerCount>
<Bind><Pubishers><DASH><WorkerCount>
SPRTMP-XXX
<Bind><Providers><RTMP><WorkerCount>
SPMPEGTS
<Bind><Providers><MPEGTS><WorkerCount>
SPOvtPub
<Bind><Pubishers><OVT><WorkerCount>
SPSRT
<Bind><Providers><SRT><WorkerCount>
Type
Value
Default
1
Minimum
1
Maximum
72
Type
Value
Default
8
Minimum
0
Maximum
72
Qualification for Host Peer | Qualification for Client Peer |
|
|