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 comes with 2 independent engines:
hlsEngine:
'shakaplayer'
setting)On Apple devices or where media source extensions are not available (e.g. older iOS or Android) we fallback to native HLS to HTML5 video. In this case we are leaving the adaptation/buffer logic to the device.
With the release of Safari 17.1 for iOS, iPadOS and macOS, Apple devices can now use
Managed Media Source for better
HLS streaming. Please enable this feature with forceMseHlsOnAppleDevices
set to true.
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/10.1.4/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, width: 640, height: 360, contentMetadata: { poster: [ 'https://your-poster-url.jpg' ] } }; const rmp = new RadiantMP('rmp'); // Player initialisation async function initRmpPlayer() { try { await rmp.init(settings); console.log('player ready'); } catch (error) { console.error('Radiant Media Player failed to initialize', error); } } initRmpPlayer(); </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
quality 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?
Reducing the streaming media industry carbon footprint matters! Also bandwidth can be expensive. Not only for
you as a streaming service but also for your viewers. There is very little point to throw a 1080p rendition in
a player that is 640x360 window-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.
displayCodecData: Boolean
When set to true this setting will add codecs information to the quality menu for each rendition where that information is available. Default: false.
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
.
hlsJSProgressive: Boolean
Enables streaming segment data with fetch loaderexperimental (rather than
XHR). 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 is mostly use for debugging
or to support legacy OTT devices. Default: false
.
forceMseHlsOnAppleDevices: Boolean
When set to true the player will use MSE HLS (hls.js or Shaka player if hlsEngine
is set to
'shakaplayer') over native HLS on Apple devices (macOS, iPadOS and iOS Safari).
This can be used for specific use-cases like DVR or WebRTC-powered solution support where native HLS may not
provide full support for those features. For eligible Apple devices (Safari 17.0+ for macOS
and iPadOS and Safari 17.1+ for iOS) Managed Media Source will be used over classic Media Source Extensions for a better streaming experience and energy savings. Default: false
.
manualSwitchingMode: String
Select what mode for manual bitrate switching should be used by the player
(works for HLS and MPEG-DASH).
Available values are 'instant'
, 'smooth'
,
'conservative'
.
Default: 'smooth'
which provides
an intermediary setting between 'instant'
(immediate) and
'conservative'
(slow) bitrate switching.
videoPreference: Object
videoPreference.videoHdr: String
The preferred HDR level of the video. If possible, this will cause the player to filter assets that either have that HDR level, or no HDR level at all. Can be 'SDR', 'PQ', 'HLG', 'auto' for auto-detect, or '' for no preference. Note that on some platforms, such as Chrome, attempting to play PQ content may cause problems. Defaults to 'auto'.
const videoPreference = {}; videoPreference.videoHdr = 'HLG'; const playerSettings = { ... videoPreference, ... }
audioPreference: Object
audioPreference.lang: String
Sets the preferred language for audio track upon player load. If not set player will opt for the 'main' audio
track. The audioPreference.lang
setting must be specified as a ISO 639 language code (example:
'en', 'de' or 'pt-BR') and must match a MPEG-DASH or HLS manifest value. Example:
const audioPreference = {}; audioPreference.lang = 'fr'; const playerSettings = { ... audioPreference, ... }
subtitlePreference: Object
subtitlePreference.lang: String
Sets the preferred language for text track upon player load. If not set player will opt for the 'main' text
track. The subtitlePreference.lang
setting must be specified as a ISO 639 language code (example:
'en', 'de' or 'pt-BR') and must match a MPEG-DASH or HLS manifest value. Example:
const subtitlePreference = {}; subtitlePreference.lang = 'fr'; const playerSettings = { ... subtitlePreference, ... }
For more information on low-latency live HLS streaming see our live documentation.
lowLatencyMode: Boolean
Support for Low-latency live HLS needs to be explicitly activated. 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 XMLHttpRequest) made in the context of HLS
streaming (manifest, segment, license). Setting hlsJSFetchXhrWithCredentials has no effect on same-site
requests. Default: false
. Setting this setting to true will also enable requests with credentials
in our
Google Cast CAF receiver.
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: 25000, // 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: 25000, maxAttempts: 3, delay: 1000 }, segment: { timeout: 15000, maxAttempts: 5, delay: 1000 }, steering: { timeout: 25000, 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:
''
.
cmcdIncludeKeys: String[]
Takes an array of CMCD keys to include in client requests.. 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 and
override 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. This is mostly used for debugging. All player settings
related to hls.js will be
overridden with those found in hlsJSFullCustomConfig
or reset to hls.js default if not
specified. The main difference with hlsJSCustomConfig
is that
hlsJSFullCustomConfig
will reset to hls.js default unspecified values (instead of using Radiant
Media Player default values). Default: {}
. Example:
See this page for a list of all hls.js options.
The player can pass custom HTTP headers for manifest and segment requests. Example:
const hlsJSCustomConfig = {
xhrSetup: (xhr, url) => {
xhr.setRequestHeader("Authorization", "abc-token-abc")
},
// if you use fetch (hlsJSProgressive set to true)
fetchSetup: function (context, initParams) {
initParams.headers = {
"Authorization": "abc-token-abc"
};
return new Request(context.url, initParams);
},
};
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.
Radiant Media Player supports rendering of multiple audio tracks (different languages or bitrate) with HLS. When the player detects multiple audio tracks within a HLS manifest it will automatically display the audio tracks selection module (headset icon). Also see Audio tracks API.
On iOS, iPadOS & macOS Safari and older Android devices, we display HLS to HTML5 video using native device support (this is where Media Source Extensions support is lacking). In those environments some player features may be unavailable (example: the quality menu will not be available and the quality icon will be replaced with the 'Auto' label). In this case we are also leaving the adaptation/buffer logic to the device.
With the release of Safari 17 for iOS, iPadOS and macOS, Apple devices can now use
Managed Media Source for better
HLS streaming. Please enable this feature with forceMseHlsOnAppleDevices
set to true.
Radiant Media Player supports the retrieval & parsing of ID3 frames when streaming HLS (either through hls.js, native HLS or Shaka player). 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.
We also support metadata TextTrack for ID3 Timed Metadata found in CMAF Event Message (emsg) boxes.
For more information on ID3 tags you can visit the id3.org site. A list of ID3 frames (id3v2.4) can be found here.
We provide native and easy-to-use extraction of ID3 frames through our player API:
meta
Fires each time ID3 metadata are updated.
metadata
getter (Metadata)
const metadata = rmp.metadata;
This getter returns a Metadata Object
representing the current ID3 metadata. The
Metadata Object
has 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/10.1.4/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, 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, metadata getter is updated and can be queried console.log(rmp.metadata); }); // Initialization ... and done! async function initRmpPlayer() { try { await rmp.init(settings); } catch(error) { console.error('Radiant Media Player failed to initialize', error); } } initRmpPlayer(); </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. Data displayed
include song title, artwork (if any), song duration, artist name, album title, recording time.
<script src="https://cdn.radiantmediatechs.com/rmp/10.1.4/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, 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); // Initialization ... and done! async function initRmpPlayer() { try { await rmp.init(settings); } catch(error) { console.error('Radiant Media Player failed to initialize', error); } } initRmpPlayer(); </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 metadata
getter upon meta
API event.
meta
Fires each time new SEI packets custom data are available
metadata
getter (Metadata)
const metadata = rmp.metadata;
This getter returns a Metadata Object
representing the current SEI packets custom data. The returned
Metadata 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/10.1.4/js/rmp.min.js"></script> <div id="rmp"></div> <script> const src = { hls: 'https://your-hls-stream-with-sei-packets-with-resolution-payloadType-5.m3u8' }; const settings = { licenseKey: 'your-license-key', src, width: 640, height: 360 }; const elementID = 'rmp'; const rmp = new RadiantMP(elementID); rmp.on('meta', () => { // Each time meta event fires, metadata getter can be queried console.log(rmp.metadata); }); // Initialization ... and done! async function initRmpPlayer() { try { await rmp.init(settings); } catch(error) { console.error('Radiant Media Player failed to initialize', error); } } initRmpPlayer(); </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.
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.
metadata
getter (Metadata)
const metadata = rmp.metadata;
This getter returns a Metadata Object
representing the current program date time metadata.
The returned Metadata 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), when using
native HLS (default) 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 currentTime
getter to read the current program date time. With those two values
you should be able to measure the delay time specific to your context. Also note you can use
forceMseHlsOnAppleDevices
setting to true to stream to Managed Media Source and enable this
feature fully, but you will loose support for iOS before iOS 17.1.
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/10.1.4/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, width: 640, height: 360 }; const elementID = 'rmp'; const rmp = new RadiantMP(elementID); rmp.on('meta', () => { // Each time meta event fires, metadata getter can be queried console.log(rmp.metadata); }); // Initialization ... and done! async function initRmpPlayer() { try { await rmp.init(settings); } catch(error) { console.error('Radiant Media Player failed to initialize', error); } } initRmpPlayer(); </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
metadata
getter (Metadata)
const metadata = rmp.metadata;
This getter returns an Metadata Object
representing the current EXT-X-DATERANGE SCTE-35 metadata. The returned
Metadata 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
metadata
getter (Metadata)
const metadata = rmp.metadata;
This getter returns an Metadata Object
representing the current EXT-X-CUE-IN or EXT-X-CUE-OUT SCTE-35 metadata. The returned
Metadata 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 should only be considered to support specific use-cases. Examples: HLS with Widevine or PlayReady DRM, offline HLS. 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.
HLS features not supported with Shaka player
hlsEngine: String
Selects the HLS rendering engine. Default: 'hlsjs'
. Other
possible value is
'shakaplayer'
.
<!-- Include Radiant Media Player - here we use the optimised build for Shaka player --> <script src="https://cdn.radiantmediatechs.com/rmp/10.1.4/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, 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'); // Initialization ... and done! async function initRmpPlayer() { try { await rmp.init(settings); } catch(error) { console.error('Radiant Media Player failed to initialize', error); } } initRmpPlayer(); </script>
©2015-2025 Radiant Media Player. All Rights Reserved. ✝