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 & audio implementation relies on media source extensions (MSE) and is based on hls.js. Where media source extensions are not available (e.g. iOS, 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.
See our compatibility table for a list of environments where HLS streaming is supported with Radiant Media Player.
You must set up your streaming server to return proper CORS settings permitting GET requests for HLS streaming to Radiant Media Player to work as expected.
<!-- Include Radiant Media Player - here we use the optimised build for hls.js --> <script src="https://cdn.radiantmediatechs.com/rmp/9.12.0/js/rmp-hlsjs.min.js"></script> <!-- Player container element --> <div id="rmp"></div> <!-- Set up player configuration options --> <script> // Here we set our HLS streaming source const src = { hls: 'https://your-hls-url.m3u8' }; const settings = { licenseKey: 'your-license-key', src: src, width: 640, height: 360, contentMetadata: { poster: [ 'https://your-poster-url.jpg' ] } }; const rmp = new RadiantMP('rmp'); rmp.init(settings); </script>
capLevelToPlayerSize: Boolean
This setting limits bitrates usable in auto-quality depending on player size (width). Default: true. If set to true, potential rendition width will be compared with the actual player width 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. For 360° video this setting is always set to false.
Why is that setting on by default in Radiant Media Player?
Bandwidth can be expensive. Not only for you as a streaming service (cost of CDN and/or origin streaming servers) but also for your viewers. There is very little point to throw a 1080p rendition in a player that is 640x360 sized. This can actually
result in a poor viewing experience as more resources will be used by the client device (CPU, memory, network). Therefore we have decided to set capLevelToPlayerSize default to true. This can still be turn off for specific needs.
ignoreDevicePixelRatio: Boolean
When set to true this setting will not take into account devicePixelRatio for ABR logic. Default: true.
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.
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.
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.
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.
forceNativeHlsOverHlsJS: Boolean
When set to true the player will use native HLS support on the targeted device over Media Source Extensions HLS (provided both are detected as available). This can be useful in OTT environments where Media Source Extensions are known to be less
efficient than native HLS (Fire TV, lower-end Android TV). Default: false.
forceHlsJSOnMacOSSafari: Boolean
When set to true the player will use hls.js over native HLS on macOS Safari (native HLS is default). This can be used for specific use-cases like DVR or eCDN support where native HLS may not provide full support for those features. Default:
false.
forceHlsJSOnIpadOS: Boolean
When set to true the player will use hls.js over native HLS on iPadOS (native HLS is default). This can be used for specific use-cases like DVR or eCDN support where native HLS may not provide full support for those features. Default:
false.
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.
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).
For more information on low-latency live HLS streaming see our live documentation.
autoLowLatencyMode: Boolean
By default player auto-detect LL-HLS streams and configure itself for LL-HLS support when a LL-HLS stream is detected. If you want to disable LL-HLS detection/configuration set this setting to false. Default:
true.
hlsJSProgressive: Boolean
Enables streaming segment data with fetch loaderexperimental (rather than XHR). Default:
false.
hlsJSFetchXhrWithCredentials: 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. This applies to all requests (Fetch or XHR) made in the context of HLS streaming. Setting hlsJSFetchXhrWithCredentials has no effect on same-site
requests. Default: false.
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: 20000, // timeout in ms, after which we abort a request
maxAttempts: 3, // the maximum number of requests before we fail
delay: 1000 // the base delay in ms between retries
},
levels: {
timeout: 20000,
maxAttempts: 3,
delay: 1000
},
segment: {
timeout: 12000,
maxAttempts: 5,
delay: 1000
},
steering: {
timeout: 20000,
maxAttempts: 3,
delay: 1000
}
};
enableCMCD: Boolean
Enables CMCD data to be passed with manifest/chunks/license requests. Default behaviour is to pass those data through URI query string. Default:
false.
useHeadersForCMCD: Boolean
Pass CMCD data through HTTP request headers instead of URI query string. Default:
false.
cmcdContentId: string
If not specificed the player will try to use contentMetadata.id for cmcdContentId. With this setting you can specify a custom cmcdContentId. Default:
''.
cmcdSessionId: string
If not specificed the player will automatically create a cmcdSessionId (UUID). With this setting you can specify a custom cmcdSessionId. Default:
''.
You may pass to the player any
parameter available with hls.js using the
hlsJSCustomConfig setting:
hlsJSCustomConfig: Object
Allow passing a custom config object to hls.js. As such any hls.js internal setting can be tuned. Note that settings in hlsJSCustomConfig will complement (complement and override if applicable) any other hls.js settings set with other
player settings. Default: {}. Example:
const hlsJSCustomConfig = {
fragLoadingTimeOut: 20000,
fragLoadingMaxRetry: 6,
fragLoadingRetryDelay: 500,
fragLoadingMaxRetryTimeout: 64000
};
const settings = {
licenseKey: 'your-license-key',
src: {
hls: 'https://your-hls-url.m3u8'
},
width: 640,
height: 360,
hlsJSCustomConfig: hlsJSCustomConfig
};
hlsJSFullCustomConfig: Object
Allow passing a full custom config object to hls.js. All player settings related to hls.js will be overridden with those found in hlsJSFullCustomConfig or otherwise reset to hls.js default if not specified. Default: {}. Example:
See this page for a list of all hls.js options.
const hlsJSCustomConfig = {
xhrSetup: (xhr, url) => {
xhr.setRequestHeader("Authorization", "abc-token-abc")
}
};
const settings = {
licenseKey: 'your-license-key',
src: {
hls: 'https://your-hls-url.m3u8'
},
width: 640,
height: 360,
hlsJSCustomConfig: hlsJSCustomConfig
};
hlsJSMaxBufferAhead: Number
Maximum front buffer size in seconds that the player can reach. When this value is reached the player will stop downloading chunks until further content has been consumed. Default:
30. It generally is best to use the default value but for on-demand content you may increase this value up to 60 seconds.
hlsJSMaxBufferBehind: Number
Maximum back buffer size in seconds that the player can reach. The player will progressively remove already consumed content from the buffer passed that mark. Default:
30. It generally is best to use the default value but for on-demand content you may increase this value up to 60 seconds.
On iOS & macOS Safari and older Android devices, 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:
Radiant Media Player supports the retrieval & parsing of ID3 frames when streaming HLS (either through hls.js or native HLS in Safari). Usage examples vary from server-side ad insertion, metadata of audio-only streams (song title, album cover ...), slides attached to a video presentation and so on.
For more information on ID3 tags you can visit the id3.org site. A list of ID3 frames (id3v2.4) can be found here.
Since Radiant Media Player version 5.1.14 we provide native and easy-to-use extraction of ID3 frames through our player API:
meta
Fires each time ID3 metadata are updated.
getMetadata()
When invoked, this method will return Object representing the current ID3 metadata. The returned
Object when available will have the following structure:
{
data: {
albumTitle: String, // TALB frame
recordingTime: String, // TDRC frame
releaseTime: String, // TDRL frame
composer: String, // TCOM frame
contentType: String, // TCON frame
fileType: String, // TFLT frame
contentGroup: String, // TIT1 frame
title: String, // TIT2 frame
duration: String, // TLEN frame
artist: String, // TPE1 frame
band: String, // TPE2 frame
conductor: String, // TPE3 frame
radioStationName: String, // TRSN frame
radioStationOwner: String, // TRSO frame
isrc: String, // TSRC frame
commercialInfo: String, // WCOM frame
copyrightInfo: String, // WCOP frame
url: String, // WXXX frame (poster frame)
start: Number, // start time of the metadata in seconds
end: Number // end time of the metadata in seconds
},
type: "id3",
raw: { rawData } // raw ID3 tags data
}
Depending on your HLS stream not all attributes from the data object may be available
<script src="https://cdn.radiantmediatechs.com/rmp/9.12.0/js/rmp.min.js"></script>
<div id="rmp"></div>
<script>
const src = {
// Test stream - courtesy of our partner indexcom.com
hls: 'https://db2.indexcom.com/bucket/ram/00/05/05.m3u8'
};
const settings = {
licenseKey: 'your-license-key',
src: src,
width: 640,
height: 360,
audioOnly: true
};
const elementID = 'rmp';
const rmp = new RadiantMP(elementID);
// We listen to meta API event
rmp.on('meta', () => {
// Each time meta event fires, getMetadata API method is updated and can be queried
console.log(rmp.getMetadata());
});
rmp.init(settings);
</script>
audioOnlyID3UI: Boolean
When set to true this setting will display ID3 tags data to the player UI automatically. This only works when
audioOnly and audioOnlyUseVideoLayout settings are set to true. This includes song title, artwork (if any), song duration, artist name, album title, recording time.
<script src="https://cdn.radiantmediatechs.com/rmp/9.12.0/js/rmp.min.js"></script>
<div id="rmp"></div>
<script>
const src = {
// Test stream - courtesy of our partner indexcom.com
hls: 'https://db2.indexcom.com/bucket/ram/00/05/05.m3u8'
};
const settings = {
licenseKey: 'your-license-key',
src: src,
width: 640,
height: 360,
audioOnly: true,
// Automatic display of ID3 tags data in player UI
audioOnlyID3UI: true,
audioOnlyUseVideoLayout: true
};
const elementID = 'rmp';
const rmp = new RadiantMP(elementID);
rmp.init(settings);
</script>
The player will parse SEI packets with resolution payloadType 5 based on H.264 specification for HLS (for default hls.js based streaming). Now you can write custom data to a HLS H.264 stream and get those data from API method
getMetadata upon meta API event.
meta
Fires each time new SEI packets custom data are available
getMetadata()
When invoked, this method will return Object representing the current SEI packets custom data. The returned
Object when available will have the following structure:
{
data: {
samples: [
{
pts: 0,
payloadType: 5,
uuid: "8fbb6c74-7c3e-4f78-9f7-8cb35d3c177e",
userDataBytes: Object,
userData: "some user data"
}
]
},
type: "sei"
}
<script src="https://cdn.radiantmediatechs.com/rmp/9.12.0/js/rmp.min.js"></script>
<div id="rmp"></div>
<script>
const src = {
hls: 'your-hls-stream-with-sei-packets-with-resolution-payloadType-5'
};
const settings = {
licenseKey: 'your-license-key',
src: src,
width: 640,
height: 360
};
const elementID = 'rmp';
const rmp = new RadiantMP(elementID);
rmp.on('meta', () => {
// Each time meta event fires, getMetadata API method is updated and can be queried
console.log(rmp.getMetadata());
});
rmp.init(settings);
</script>
The EXT-X-PROGRAM-DATE-TIME tag in HLS associates the first sample of a Media Segment with an absolute date and/or time. It applies only to the next Media Segment. More information can be found in HLS specification.
Since Radiant Media Player version 5.2.1 we provide native and easy-to-use extraction of program date time metadata through our player API:
meta
Fires each time program date time metadata are updated.
getMetadata()
When invoked, this method will return Object representing the current program date time metadata. The returned
Object when available will have the following structure:
{
data: {
programDateTime: Number, // epoch time in seconds for start of program date time
rawProgramDateTime: String, // Date time for program date time (ISO/IEC 8601:2004)
endProgramDateTime: Number, // epoch time in seconds for end of program date time
start: Number, // start time of the metadata in seconds
end: Number // end time of the metadata in seconds
},
type: "program-date-time"
}
On Apple devices (iOS, iPadOS and macOS Safari), we use the
getStartDate method native to the HTML5
video tag to get program date time data - this is the only way to access program date time data on Apple devices. If there is a program date time in the HLS stream the first one will be stored as the date returned by this method.
From there, you should be able to combine it with the player
getCurrentTime or getLiveCurrentTime API methods to get the
current program date time. With those two values you should be able to measure the delay time specific to your context.
Depending on your HLS stream not all attributes from the data object may be available - check property before usage
<script src="https://cdn.radiantmediatechs.com/rmp/9.12.0/js/rmp.min.js"></script>
<div id="rmp"></div>
<script>
const src = {
hls: 'https://your-live-hls-stream-with-program-date-time-metadata.m3u8'
};
const settings = {
licenseKey: 'your-license-key',
src: src,
width: 640,
height: 360
};
const elementID = 'rmp';
const rmp = new RadiantMP(elementID);
rmp.on('meta', () => {
// Each time meta event fires, getMetadata API method is updated and can be queried
console.log(rmp.getMetadata());
});
rmp.init(settings);
</script>
In HLS, SCTE-35 tags are visible in the .m3u8 manifests. Two main types of tags are used in HLS to signal ad opportunities in a manifest: EXT-X-DATERANGE tag and EXT-X-CUE-OUT/EXT-X-CUE-IN tags. The main difference between the two is how they handle timing: EXT-X-DATERANGE relies on UTC, and EXT-X-CUE-IN/OUT depends on the position in the playlist. In the next sections we describe how to extract EXT-X-DATERANGE SCTE-35 metadata with our player.
meta
Fires each time the player enters a EXT-X-DATERANGE tag
getMetadata()
When invoked, this method will return Object representing the current EXT-X-DATERANGE SCTE-35 metadata. The returned
Object when available will have the following structure:
{
data: {
duration: 3.1999999999999886,
end: 391.99999999701976,
start: 388.79999999701977,
metadata: {
attributes: [
{name: 'ID', value: '956380'},
{name: 'START-DATE', value: '2023-08-18T13:14:12.520Z'},
{name: 'PLANNED-DURATION', value: '31.000'},
{name: 'SCTE35-OUT', value: '0xFC302500013254351800FFF01405000E97DC7FEFFF8B183380FE002A929100010101000067A7D3D6'}
],
content: "ID=\"956380\",START-DATE=\"2023-08-18T13:14:12.520Z\",PLANNED-DURATION=31.000,SCTE35-OUT=0xFC302500013254351800FFF01405000E97DC7FEFFF8B183380FE002A929100010101000067A7D3D6",
tag: "EXT-X-DATERANGE"
}
},
type: "date-range"
}
In HLS, SCTE-35 tags are visible in the .m3u8 manifests. Two main types of tags are used in HLS to signal ad opportunities in a manifest: EXT-X-DATERANGE tag and EXT-X-CUE-OUT/EXT-X-CUE-IN tags. The main difference between the two is how they handle timing: EXT-X-DATERANGE relies on UTC, and EXT-X-CUE-IN/OUT depends on the position in the playlist. In the next sections we describe how to extract EXT-X-CUE-IN and EXT-X-CUE-OUT SCTE-35 metadata with our player.
meta
Fires each time the player enters a EXT-X-CUE-IN or EXT-X-CUE-OUT tag
getMetadata()
When invoked, this method will return Object representing the current EXT-X-CUE-IN or EXT-X-CUE-OUT SCTE-35 metadata. The returned
Object when available will have the following structure:
{
data: {
duration: 8.717333333333329,
end: 200.75733333333332,
start: 192.04,
metadata: {
content: "DURATION=120.04",
tag: "EXT-X-CUE-OUT"
}
},
type: "scte-35"
}
HLS streaming with Shaka player is only reserved to specific use-cases: HLS with DRM, offline HLS, HLS with embedded TTML captions. For all other use-cases please use the default hls.js engine.
As an alternative to hls.js for streaming HLS content to Radiant Media Player, it is also possible to use Shaka player to support specific use-cases.
hlsEngine: String
Selects the HLS rendering engine. Default: 'hlsjs'. Other possible value is
'shakaplayer'.
All other player settings that apply to Shaka player can all be used even if they are not explicitly marked as compatible with HLS streaming.
<!-- Include Radiant Media Player - here we use the optimised build for Shaka player --> <script src="https://cdn.radiantmediatechs.com/rmp/9.12.0/js/rmp-shaka.min.js"></script> <!-- Player container element --> <div id="rmp"></div> <!-- Set up player configuration options --> <script> // Here we pass our HLS streaming source const src = { hls: 'https://your-fmp4-hls-url.m3u8' }; const settings = { licenseKey: 'your-license-key', src: src, width: 640, height: 360, // Here we tell the player to use Shaka Player for HLS streaming hlsEngine: 'shakaplayer', contentMetadata: { poster: [ 'https://your-poster-url.jpg' ] } }; const rmp = new RadiantMP('rmp'); rmp.init(settings); </script>
©2015-2023 Radiant Media Player. All Rights Reserved.