Publisher Extension

Here are some Publisher Extension features that can help you operate your service using various Publishers of OvenMediaEngine.

#01. Features in all Publishers

Add Delay to the Stream

The Stream Delay feature allows you to force additional latency on all <Publishers>. This can help you handle unexpected situations when operating a live service.

Set the <Publishers><DelayBufferTimeMs> value in Server.xml as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
  ...
  <VirtualHosts>
    <VirtualHost>
      <Applications>
        <Application>
          <Publishers>
            ...
            <!-- milliseconds -->
            <DelayBufferTimeMs>10000</DelayBufferTimeMs>
            ...
          </Publishers>
        </Application>
      </Applications>
    </VirtualHost>
  </VirtualHosts>
</Server>

#02. Features in (LL)-HLS and WebRTC

Default Playlist Creation Settings

If you wish to control the creation of the default Playlist (llhls, playlist, webrtc) for each playback protocol (LL-HLS, Legacy HLS, WebRTC). You can use the <CreateDefaultPlaylist> option to manage the system more easily.

Configure in Server.xml under <Publishers><LLHLS><CreateDefaultPlaylist> (or <Publishers><HLS><CreateDefaultPlaylist>, or <Publishers><WebRTC><CreateDefaultPlaylist>) as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
  ...
  <VirtualHosts>
    <VirtualHost>
      <Applications>
        <Application>
          <Publishers>
            ...
            <LLHLS>
              <CreateDefaultPlaylist>true</CreateDefaultPlaylist>
            </LLHLS>
          </Publishers>
        </Application>
      </Applications>
    </VirtualHost>
  </VirtualHosts>
</Server>

Element

Value

Description

CreateDefaultPlaylsit

true | false * Default: ture

Setting <CreateDefaultPlaylist> to false within each Publisher will prevent the creation of the default Playlist.

#03. Features in (LL)-HLS

Origin Redundancy Settings

When configuring redundancy for OvenMediaEngine's Low-Latency HLS Origin Servers (or HLS Origin Servers), you can make the Segment file names on the Primary and Secondary Origin Servers the same through the Origin redundancy setting. This ensures that the Edge Server or CDN Cache Server connects to the Secondary Origin Server instead of the Primary Origin Server and downloads the same content seamlessly if the Primary Origin Server fails.

Enable <Publishers><LLHLS><ServerTimeBasedSegmentNumbering> (or <Publishers><HLS><ServerTimeBasedSegmentNumbering>) in Server.xml as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
  ...
  <VirtualHosts>
    <VirtualHost>
      <Applications>
        <Application>
          <Publishers>
            ...
            <LLHLS>
              <ServerTimeBasedSegmentNumbering>true</ServerTimeBasedSegmentNumbering>
            </LLHLS>
          </Publishers>
        </Application>
      </Applications>
    </VirtualHost>
  </VirtualHosts>
</Server>

This feature generates segment file names based on server time, so you must synchronize the time on your primary and secondary origin servers.

Default Query String Settings

You can control the fundamental operations of Low-Latency HLS (or Legacy HLS) via the <DefaultQueryString>.

Set in <Publishers><LLHLS><DefaultQueryString> (or <Publishers><HLS><DefaultQueryString>) in Server.xml as follows:

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
  ...
  <VirtualHosts>
    <VirtualHost>
      <Applications>
        <Application>
          <Publishers>
            ...
            <LLHLS>
              <DefaultQueryString>
		        <Query>
				  <Key>_HLS_legacy</Key>
				  <Value>NO</Value>
		        </Query>
		        <Query>
				  <Key>_HLS_rewind</Key>
				  <Value>YES</Value>
			    </Query>
			  </DefaultQueryString>
            </LLHLS>
          </Publishers>
        </Application>
      </Applications>
    </VirtualHost>
  </VirtualHosts>
</Server>

This setting is ignored if the playback URL already has a query string appended to it.

Key

Value

Description

_HLS_legacy

YES | NO * Default: NO

Sets the _HLS_legacy value to YES will remove partial segment information from LL-HLS playlists, making them work the same as legacy HLS like HLSv6. * LL-HLS Only

_HLS_rewind

YES | NO * Default: YES

If the _HLS_rewind value is set to YES and the feature is enabled, old segment information will be included in the playlist.

Using Propagatet Query String

When you enable <PropagateQueryString>, the query string included in the initial Master Playlist request is automatically carried over to all sub-requests (Media Playlist, Segment, and Partial Segment). By including session keys, authentication tokens, etc., in the query string and utilizing this feature, content access control becomes easier as all requests can be verified at the CDN level.

Set the <Publishers><LLHLS><PropagateQueryString> (or <Publishers><HLS><PropagateQueryString>) in Server.xml like this:

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
  ...
  <VirtualHosts>
    <VirtualHost>
      <Applications>
        <Application>
          <Publishers>
            ...
            <LLHLS>
              <OriginMode>true</OriginMode>
              <PropagateQueryString>true</PropagateQueryString>
            </LLHLS>
          </Publishers>
        </Application>
      </Applications>
    </VirtualHost>
  </VirtualHosts>
</Server>

You should take care not to include sensitive information in the Query String directly.

Cache Validation

Enabling this feature allows identification of whether the cached resource version matches the resource in OvenMediaEngine. When the HTTP request includes the If-None-Match: "<etag_value>" header, it compares the resource Etag with OvenMediaEngine's resource Etag, and if the values match, it returns 304 Not-Modified.

Set the <Modules><ETag> in Server.xml like this:

<Server>
  <Modules>
    <ETag>
      <Enable>true</Enable>
    </ETag>
  </Modules>
</Server>

When enabled, an Etag header will be added to all HTTP responses.

#04. Features exclusive to LL-HLS

Control Origin Cache

You can specify how long content should be cached on edge servers or CDN cache servers by adding a Cache-Control header to the HTTP response.

Set the <Publishers><LLHLS><CacheControl> in Server.xml like this:

<?xml version="1.0" encoding="UTF-8"?>
<Server version="8">
  ...
  <VirtualHosts>
    <VirtualHost>
      <Applications>
        <Application>
          <Publishers>
            ...
            <LLHLS>
              <OriginMode>true</OriginMode>
              <CacheControl>
                <MasterPlaylistMaxAge>0</MasterPlaylistMaxAge>
                <ChunklistMaxAge>0</ChunklistMaxAge>
                <ChunklistWithDirectivesMaxAge>60</ChunklistWithDirectivesMaxAge>
                <SegmentMaxAge>-1</SegmentMaxAge>
                <PartialSegmentMaxAge>-1</PartialSegmentMaxAge>
              </CacheControl>
            </LLHLS>
          </Publishers>
        </Application>
      </Applications>
    </VirtualHost>
  </VirtualHosts>
</Server>

Element

Description

MasterPlaylistMaxAge

Specifies the max-age of the Master Playlist. It will not change while the Stream is being created.

ChunklistMaxAge

Specifies the max-age of the Media Playlist. It must always respond with the latest Media Playlist and is a URL without Delivery Directives for LL-HLS. Therefore, it should be cached as short as possible or not at all.

ChunklistWithDirectivesMaxAge

Specifies the max-age of the Media Playlist with the . The currently supported Delivery Directives are _HLS_msn and _HLS_part. It is a Playlist with Segment numbers and Partial Segment numbers, and this URL is unique while the Stream is being created and can be cached for a long time because the content of the same URL does not change.

SegmentMaxAge

Specifies the max-age of the Segment File. The URL of the Segment File is unique while the Stream is being created and can be cached for a long time because the content of the same URL does not change.

PartialSegmentMaxAge

Specifies the max-age of the Partial Segment File. The URL of the Partial Segment File is unique while the Stream is being created and can be cached for a long time because the content of the same URL does not change.

`<CacheControl>` Elements

Element

Description

CacheControl: no-cache, no-store

Instructs not to cache the content at all, always fetching new data from the Server.

Greater than 0

CacheControl: max-age=<seconds>

Specifies the duration for which the Cache remains valid.

-1

Without CacheControl header

Indicates that no specific Cache Header will be sent from the Origin. In this case, caching may not be used at all, or the CDN or Cache server's policies may be applied, or the default Cache behavior of the Client or Browser may be followed.

<CacheControl> can be used with 0 and positive values, while using -1 may result in unexpected caching behaviors, so caution is advised.

#05. Features exclusive to HLS

Inserting ad markers (EXT-X-CUE-OUT/EXT-X-CUE-IN)

You can dynamically insert ad markers into the HLS playlist using the REST API.

When requesting the CUE-OUT event, the following tags will be added to the playlist:

#EXT-X-CUE-OUT:DURATION=<time>
…
#EXT-X-CUE-IN

#EXT-X-CUE-OUT and #EXT-X-CUE-IN are a pair, and the entire section between the two tags will be replaced with ad content by the ad server.

DURATION=<time> is required and represents the duration of the ad.

You can request the CUE-IN event to end an inserted ad early. When the event is called, the #EXT-X-CUE-IN tag is immediately added to the playlist, and the previously added #EXT-X-CUE-IN tag is removed.

API Interface

Request

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

Header

Authorization: Basic {credentials}

# Authorization
Credentials for HTTP Basic Authentication created with <AccessToken>

Body

{
  "eventFormat": "cue",
  "events":[
    {
      "cueType": "out", // out | in
      "duration": 60500 // milliseconds, only available when cueType is out
    }
  ]
}

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

Header

Authorization: Basic {credentials}

# Authorization
Credentials for HTTP Basic Authentication created with <AccessToken>

Body

[
  {
    "eventFormat": "id3v2",
    "eventType": "video", // "eventTarget": "video" is same
    "events":[
      {
        "frameType": "TXXX",
        "info": "AirenSoft",
        "data": "OvenMediaEngine"
      },
      {
        "frameType": "TIT2",
        "data": "OvenMediaEngine 123"
      }
    ]
  },
  {
    "eventFormat": "cue",
    "events":[
      {
        "cueType": "out", // out | in
        "duration": 60500 // milliseconds, only available when cueType is out
      }
    ]
  }
]

Responses

200 Ok

The request has succeeded

Header

Content-Type: application/json

Body

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

400 Bad Request

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

401 Unauthorized

Authentication required

Header

WWW-Authenticate: Basic realm=”OvenMediaEngine”

Body

{
    "message": "[HTTP] Authorization header is required to call API (401)",
    "statusCode": 401
}

404 Not Found

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

Body

{
    "message": "[HTTP] Could not find the application: [default/app2] (404)",
    "statusCode": 404
}

PreviousRestart Application | 0.17.0.0+NextRTMP Authentication | 0.17.2.0+

Last updated 19 days ago

#01. Features in all Publishers

Add Delay to the Stream

#02. Features in (LL)-HLS and WebRTC

Default Playlist Creation Settings

#03. Features in (LL)-HLS

Origin Redundancy Settings

Default Query String Settings

Using Propagatet Query String

Cache Validation

#04. Features exclusive to LL-HLS

Control Origin Cache

<CacheControl> Elements

#05. Features exclusive to HLS

Inserting ad markers (EXT-X-CUE-OUT/EXT-X-CUE-IN)

API Interface

`<CacheControl>` Elements