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

#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 Low-Latency HLS Delivery Directives. 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
0	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.