Radiant Media Player

HLS streaming

Documentation sections

HLS support in Radiant Media Player

Radiant Media Player provides a comprehensive and cross-device solution to display HLS streams for on-demand, live or DVR content. Our HLS to HTML5 video implementation relies on media source extensions (MSE) and is based on hls.js. Where media source extensions are not available (e.g. iOS, macOS Safari, older Android) we fallback to native HLS to HTML5 video.

A standard-compliant HLS streaming URL is all you need - the player will take care of opting for the best way to render it based on device capabilities.

Supported HLS features

  • Playback of H.264 + AAC in .ts fragments
  • Playback of H.264 + AAC in fmp4 fragments (CMAF / fragmented MP4 container)
  • Playback of H.265 (HEVC) + AAC in fmp4 fragments (CMAF / fragmented MP4 container) where supported
  • Playback of H.264 + MP3 content in .ts fragments (with the limitation of no Internet Explorer 11 support)
  • Live, DVR and on-demand video streaming
  • Optimized adaptive bitrate streaming with automatic or manual bitrate selection
  • Multiple-audio tracks
  • AES-128/SAMPLE-AES decryption
  • ID3 tags
  • WebVTT & CEA 608/708 captions
  • Program-date-time
  • Discontinuities
  • Resilience to errors
  • Redundant/Failover Playlists
  • Audio-only: AAC container or MPEG Audio container (MPEG-1/2 Audio Layer III)
  • App-store compliant HLS streams playback (see hlsJSAppleAppStoreCompliance setting below for compliance notes)

Generally available features like video ads, JavaScript API or playback rate changes are also supported with HLS to Radiant Media Player.

Supported M3U8 tags

  • #EXTM3U
  • #EXT-X-STREAM-INF (adaptive streaming)
  • #EXT-X-ENDLIST (Live playlist)
  • #EXT-X-MAP
  • #EXT-X-KEY

Supported environments

See our compatibility table for a list of environments where HLS streaming is supported with Radiant Media Player.

Best practices

As a rule of thumb Radiant Media Player should work with any-standard compliant HLS streaming service provider. In order to provide better cross-device support for HLS streaming to Radiant Media Player we recommend the following:

  • You must set up your streaming server to return proper CORS settings permitting GET requests.
  • For H.264 encoded content H.264 Main profile provides best coverage - H.264 Level 5+ (this is for 4K/360 content mainly) encoded content may cause playback issue on older devices so only go there if you need to.
  • Have the same pair of video/audio codecs for each rendition of the HLS stream.
  • Have the same audio sampling rate and number of audio channels for each rendition of the HLS stream.
  • For HLS with .ts segments, .ts segments should be 10 seconds length whenever possible.

Player code example

In this example we use a multi-bitrate HLS (.ts with H.264/AAC) stream:

<!-- Include Radiant Media Player - here we use the optimised build for hls.js -->
<script src="https://cdn.radiantmediatechs.com/rmp/5.6.1/js/rmp-hlsjs.min.js"></script>
<!-- Player container element -->
<div id="rmpPlayer"></div>
<!-- Set up player configuration options -->
// Here we set our HLS streaming source
var src = {
  hls: 'https://your-hls-url.m3u8'
var settings = {
  licenseKey: 'your-license-key',
  src: src,
  width: 640,
  height: 360,
  contentMetadata: {
    poster: [
var elementID = 'rmpPlayer';
var rmp = new RadiantMP(elementID);

Native HLS support notes

On iOS & macOS Safari and older Android devices (Android before version 5), we display HLS to HTML5 video using native device support (this is where media source extensions are not available or not reliable enough). On those devices limitations may apply:

  • DVR controls may not be supported, in which case DVR streams will be treated as simple live streams - on iOS 11+ DVR controls are only available in fullscreen mode. You may use forceHlsJSOnMacOSIpadOSSafari setting to force support of DVR controls on macOS and iPadOS Safari.
  • Manual bitrate switching is not supported - the player uses adaptive bitrate streaming in auto mode and the adaptation logic is left to the device.

HLS player settings

hlsJSCapLevelToPlayerSize: Boolean

This setting limits bitrates usable in auto-quality depending on player size (width & height). Default: true. If set to true, width and height (defined in m3u8 playlist) will be compared with the actual player width and height and only the best match will be used as the maximum available bitrate, hence helping to preserve bandwidth usage while maintaining streaming quality. This setting is ignored in manual mode so all levels can be selected manually. Note that this setting takes into account information provided by window.devicePixelRatio to preserve quality on mobile devices. For 360 video this setting is always set to false.

hlsJSStopDownloadWhilePaused: Boolean

When set to true this setting will cause the player to stop downloading HLS fragments while it is in a paused or stopped state. This can help to preserve bandwidth. Default: false.

hlsJSEnableCaptions: Boolean
This setting indicates to the player whether or not to parse and display CEA 608/708 or WebVTT captions when detected in an HLS stream. Default: true.
hlsJSCaptionsTextTrack1Label: String
Label for the text track generated for CEA-6/708 captions track 1. This is how it will appear in the player captions menu. Default: 'CC1'.
hlsJSCaptionsTextTrack2Label: String
Label for the text track generated for CEA-6/708 captions track 2. This is how it will appear in the player captions menu. Default: 'CC2'.
hlsJSLiveSyncDurationCount: Number
Edge of live delay, expressed in multiple of EXT-X-TARGETDURATION. If set to 3, playback will start from fragment N-3, N being the last fragment of the live playlist. Decreasing this value is likely to cause playback stalls. Default: 3.
hlsJSInitialLiveManifestSize: Number
Number of segments needed to start a playback of a HLS live stream. Default: 1.
hlsJSAppleAppStoreCompliance: Boolean
For App-store compliant HLS video streams which include an audio-only rendition this setting should be set to true to insure proper playback across devices. Default: false.
hlsJSMaxAudioFramesDrift: Number
See here for full details on this setting. You generally do not need to tweak this setting unless trying to solve specific audio issues with some exotic HLS streams. Default: 1.
hlsJSDefaultAudioCodec: String
If audio codec is not signaled in variant manifest, or if only a stream manifest is provided, the player will try to guess audio codec by parsing audio sampling rate in ADTS header. If sampling rate is less or equal than 22050 Hz, then the player assumes it is HE-AAC, otherwise it assumes it is AAC-LC. This could result in bad guess, leading to audio decode error, ending up in media error. It is possible to hint default audio codec to the player by setting hlsJSDefaultAudioCodec to:
  • 'mp4a.40.2': AAC-LC
  • 'mp4a.40.5': HE-AAC
  • 'auto': the player auto-guesses. This is the default.
hlsJSXhrWithCredentials: Boolean
This setting indicates to the player whether or not cross-site Access-Control requests should be made using credentials such as cookies, authorization headers or TLS client certificates. Setting withCredentials has no effect on same-site requests. Default: false.
hlsJSUseManifestRenditionName: Boolean
By default the player present renditions in the quality menu as "resolution · bitrate" pattern. Example: 400p · 1728 kbps. However a HLS manifest is also required to have a NAME attribute for each rendition. When set to true this setting will cause the player to display the NAME of the rendition in place of the "resolution · bitrate" default pattern. This also applies to audio tracks when multi-language audio tracks are available in a HLS manifest. Default: false.
hlsJSXhrSetup: Function
This setting allows to pass a custom XMLHttpRequest setup to the player (including passing custom HTTP headers). This custom XMLHttpRequest setup will be used for all HLS playlist/chunk requests. Following is an example of using this feature. Note this is just an example - you will need to adapt this to your own set up for a working solution.
function xhrSetup(xhr) {
  if (xhr) {
    // passing custom headers
    xhr.setRequestHeader('X-File-Name', 'rmp-file');
    // passing cookies withCredentials
    xhr.withCredentials = true;
// Then we set our player settings
var settings = {
  licenseKey: 'your-license-key',
  src: {
    hls: 'https://your-hls-url.m3u8'
  width: 640,
  height: 360,
  hlsJSXhrSetup: xhrSetup
forceHlsJSOnMacOSIpadOSSafari: Boolean

When set to true the player will force use hls.js on macOS and iPadOS Safari (where native HLS would be used generally). The main use case is to enable DVR controls, quality and multi-audio modules on macOS and iPadOS Safari. Note that hls.js support for macOS and iPadOS Safari is still in BETA as of June 2019 so only use this setting if you have a business requirement to do so. Also note that setting forceHlsJSOnMacOSIpadOSSafari to true disables AirPlay casting support from macOS and iPadOS Safari as it requires native HLS or MP4 progressive download. Default: false. When forceHlsJSOnMacOSIpadOSSafari is set to true the only option to display video ads is the IMA SDK.

retryParameters: Object

This represents an Object to pass to the player to specify specific retry parameters when attempting to load HLS content. The following example shows the default player parameters:

retryParameters: {
  manifest: {
    timeout: 10000, // timeout in ms, after which we abort a request
    maxTimeout: 64000, // maximum timeout in ms for all attempts before we fail
    maxAttempts: 2, // the maximum number of requests before we fail
    delay: 1000 // the base delay in ms between retries
  levels: {
    timeout: 10000,
    maxTimeout: 64000,
    maxAttempts: 5,
    delay: 1000
  segment: {
    timeout: 20000,
    maxTimeout: 64000,
    maxAttempts: 7,
    delay: 1000
hlsEngine: String

Since Radiant Media Player 4.4.0 it is possible to use Shaka Player HLS streaming engine instead of hls.js. While hls.js offers more options using HLS through Shaka player notably provides support for HLS with DRM content. Default: 'hlsjs'. Other possible value is 'shakaplayer'.

hlsJSCustomConfig: Object

Allow passing a custom config object to hls.js. As such any hls.js internal setting can be tuned. Note that this may override any setting previously documented on this page. Default: {}. Example:

var hlsJSCustomConfig = {
  fragLoadingTimeOut: 20000,
  fragLoadingMaxRetry: 6,
  fragLoadingRetryDelay: 500,
  fragLoadingMaxRetryTimeout: 64000
var settings = {
  licenseKey: 'your-license-key',
  src: {
    hls: 'https://your-hls-url.m3u8'
  width: 640,
  height: 360,
  hlsJSCustomConfig: hlsJSCustomConfig

See this page for a list of all hls.js options.

manualSwitchingMode: String

Select what mode for manual bitrate switching should be used by the player (works for HLS and DASH). Available values are 'instant', 'smooth', 'conservative'. Default: 'smooth' which provides an intermediary setting between 'instant' (immediate) and 'conservative' (slow) bitrate switching.

hls.js ABR & buffer player settings

HLS is an adaptive bitrate streaming technology. Hence having a well-tuned ABR logic is paramount to insure a good user experience and reduce bandwidth cost. Radiant Media Player default ABR logic is tuned to work well in most common use-cases seen now-days. The following settings will let you tune the ABR/buffer logic to your environment. Only use those settings if you are trying to address a specific issue and fully understand what they do. Ill-configured ABR/buffer settings may cause a deteriorated user experience. Those settings are only applicable when streaming HLS through hls.js in Radiant Media Player, they do not apply when using native HLS or HLS through Shaka player (ABR/buffer settings for Shaka player are available here).

Also note that the player offers a getHlsBwEstimate API method that allows to track in real-time the available device bandwidth captured by the player (only applies to hls.js).

hlsJSMaxBufferLength: Number

Maximum buffer length in seconds. The player will try to reach and never exceed this value for its internal buffer. Default: 30.

hlsJSStartLevel: Number
Defines the preferred initial bitrate when playback starts. Default: -1.
  • -1: automatic start level selection, playback will start from level matching download bandwidth (determined from download of first segment based on first level appearing in manifest) and information provided by rmp-connection when available.
  • n: where n is an integer will cause the player to select the n th level at startup (where 0 is the lowest quality).
Best practice: when hlsJSStartLevel is set to -1, your HLS manifest should include a lower-end rendition (generally this should not exceed 500 kbps audio & video included) and this rendition should be the first listed in your HLS manifest. This should provide optimal performance.
hlsJSMinAutoBitrate: Number
Set the minimum value (in bps) that should be used by the ABR algorithm. Default: 0. For example setting hlsJSMinAutoBitrate to 500000 means that the player - while in auto mode - will pick the best matching level that has a bitrate above or equal to 500000 bps (500 kbps).
hlsJSAbrBandWidthFactor: Number
Scale factor to be applied against measured bandwidth average, to determine whether we can stay on current or lower quality level. If hlsJSAbrBandWidthFactor * bandwidth average < level.bitrate then ABR can switch to that level providing that it is equal or less than current level. Default: 0.95.
hlsJSAbrBandWidthUpFactor: Number
Scale factor to be applied against measured bandwidth average, to determine whether we can switch up to a higher quality level. If hlsJSAbrBandWidthUpFactor * bandwidth average < level.bitrate then ABR can switch up to that quality level. Default: 0.75.
hlsJSLiveBackBufferLength: Number
Sets the maximum length of the buffer, in seconds, to keep during a live stream. Any video buffered past this time will be evicted. Infinity means no restriction on back buffer length; 0 keeps the minimum amount. The minimum amount is equal to the target duration of a segment to ensure that current playback is not interrupted. Default: Infinity.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License.