“dataProvider” attribute of player configuration object can be JSON formatted Media Object (described below), or array of Media Objects as a media playlist.
Field name | Type | Description |
---|---|---|
id | string | Media asset id. |
title | string | Media asset title. |
duration | number | Media duration in seconds. |
source | array | Array of media source metadata objects (for more details see Media Source Object). |
sourceWithFallbacks | array | Array of arrays with media source metadata objects. Defines backup sources in case of playback error. |
splashImages | array | Array of splash image metadata objects (for more details see Media Splash Image Object). |
mediaLandingPage | string | Url pointing to media landing page. |
subtitlesSets | array | Subtitles configuration for subtitles not embedded in video stream (loading one language from single external file). |
liveStream | object | Additional settings for live stream transmission. |
progress | object | Additional settings for progress bar. |
Data type: string
Description: Identifier for media. Used for media identification for Bradmax analytics. It is string, so it is customizable. This parameter is required for proper work of Bradmax analytics statistics for content / media.
"dataProvider": {
"id": "701"
}
Data type: string
Description: Title of media asset.
"dataProvider": {
"title": "Tears of steel"
}
Data type: string
Description: Media asset duration time in seconds.
"dataProvider": {
"duration": 734.097415
}
Data type: array
Description: Array of media source objects, for more details see Media Source Object
"dataProvider": {
"source": [
{
"contentType": "movie",
"url": "https://bradmax.com/static/video/tos/440272.mpd",
"bitrate": 191999,
"width": 1280,
"height": 534
}
]
}
Only “url” field is needed. Rest fields is useful for automatically choosing best supported stream for user.
Minimal example:
"dataProvider": {
"source": [{"url": "https://bradmax.com/static/video/tos/440272.mpd"}]
}
Example with multiple formats. Player will use best supported format for user device:
"dataProvider": {
"source": [
{"url": "https://bradmax.com/static/video/tos/440272.mpd"}, // MPEG-DASG
{"url": "https://bradmax.com/static/video/tos/440272.m3u8"}, // HLS
{"url": "https://bradmax.com/static/video/tos/440272.mp4"} // ordinary MP4 file.
]
}
Data type: array
Description: Array of arrays with media source metadata objects (Media Source Object). Defines backup sources in case of playback error. Instead of list with available formats, this is list of such list. First is main and each next is used in case of previous source failure. This option is mutual with "source". Only one field: "source", “sourceWithFallbacks” - can be used in same time.
"dataProvider": {
"sourceWithFallbacks": [
// MPEG-DASG & HLS from main server
[{"url": "https://bradmax.com/static/video/tos/440272.mpd"}, {"url": "https://bradmax.com/static/video/tos/440272.m3u8"}],
// MPEG-DASG & HLS from backup server
[{"url": "https://backup-server.bradmax.com/static/video/tos/440272.mpd"}, {"url": "https://backup-server.bradmax.com/static/video/tos/440272.m3u8"}]
]
}
It can be useful if you want to define stream, which is temporary available (eg. live stream) and secondary stream, which should be played if main is not available (eg. archived version of video in case of lack of live stream).
Data type: array
Description: Array of media splash image objects, for more details see Media Splash Image Object
"splashImages": [
{
"url": "http://bradmax.com/static/images/startsplash.jpg",
"width": 955,
"height": 397
}
]
Data type: string
Description: Url pointing to media landing page.
"dataProvider": {
"mediaLandingPage": "http://bradmax.com"
}
Field name | Type | Description |
---|---|---|
contentType | string | Content type name. |
url | string | URL pointing to media asset. |
bitrate | number | Bitrate of media asset. |
width | number | Width of media asset in pixels. |
height | number | Height of media asset in pixels. |
Data type: string
Description: Content type name. Possible values 'movie’, 'trailer’, 'live’.
"dataProvider": {
"source": [
{
"contentType": "movie",
}
]
}
Data type: string
Description: URL pointing to media asset.
"dataProvider": {
"source": [
{
"url": "http://bradmax.com/static/video/tos/440272.mpd",
}
]
}
Data type: number
Description: Bitrate of media asset.
"dataProvider": {
"source": [
{
"bitrate": 191999
}
]
}
Data type: number
Description: Width of media asset in pixels.
"dataProvider": {
"source": [
{
"width": 955
}
]
}
Data type: number
Description: Height of media asset in pixels
"dataProvider": {
"source": [
{
"height": 397
}
]
}
Field name | Type | Description |
---|---|---|
url | string | URL pointing to image asset. |
width | number | Width of image asset in pixels. |
height | number | Height of image asset in pixels. |
Data type: string
Description: URL pointing to image asset
"dataProvider": {
"splashImages": [
{
"url": "http://bradmax.com/static/images/startsplash.jpg"
}
]
}
Data type: number
Description: Width of image asset in pixels.
"dataProvider": {
"splashImages": [
{
"width": 955
}
]
}
Data type: number
Description: Height of image asset in pixels
"dataProvider": {
"splashImages": [
{
"height": 397
}
]
}
Data type: array
Description: Subtitles configuration. Subtitles can be embedded in all video streams types: HLS, MPEG/DASH, Microsoft Smooth Streaming. In that case only link to video stream is needed. Bradmax player during video stream load checks automatically if there are any embedded subtitles and show list of them under subtitles pop-up. This process is automatic and doesn’t need any changes in player configuration.
In case, when there is a already encoded video stream without subtitles and subtitles are available in external files (all subtitles are available via URL to file *.srt, *.vtt, *.webvtt) “subtitlesSet” configuration option is needed.
"dataProvider": {
"subtitlesSets": [
{ "languageCode": "en", "url": "https://cdn.example.com/subtitels_for_en.srt" },
{ "languageCode": "fr", "url": "https://cdn.example.com/subtitels_for_fr.srt" },
{ "languageCode": "de", "url": "https://cdn.example.com/subtitels_for_de.srt" },
{ "languageCode": "cz", "url": "https://cdn.example.com/subtitels_for_cz.srt" }
]
}
subtitlesSet entry field name | Type | Description |
---|---|---|
languageCode | string | It is ISO 3166-1 language code. It can be defined as alpha-2 or alpha-3 (2 or 3 letter language code). |
url | string | URL address for raw subtiles file (not compressed by zip or similar compression method). |
Supported subtitles file formats | File extensions |
---|---|
SRT | *.srt |
VTT | *.vtt *.webvtt |
Note: If you want automatically select some language for subtitles please check subtitles
Data type: object
Description: This object marks that video is live stream transmission and keeps additional settings for such transmission. “Live stream transmission” mean video stream, which is “produced” on live. After some time video transmission will be not available any more.
Default value: null
Available optional settings for liveStream object:
Key | Description |
---|---|
endDate | Date time as ISO 8601 string (https://en.wikipedia.org/wiki/ISO_8601). Examples: “2020-06-10T20:00:00Z” (2020-06-10 20:00:00 UTC time zone), “2020-06-12T18:00:00+08:00” (2020-06-12 18:00:00 GMT+8 time zone). If defined, then player is able to detect end of live stream transmission. Without it player will be assume end of transmission and end splash screen will be presented. |
thankYouImageUrl | Link to custom end splash image, which should be shown after end of live stream transmission. If not defined then default start splash will be shown after end of transmission. |
waitingForTransmissionImageUrl | Link to custom waiting for transmission image, which should be shown when player is waiting for live stream transmission start. |
Data type: object
Default value: null
Available settings for progress object:
Field name | Type | Description |
---|---|---|
segments | array or string | Media progress track segments configuration. |
markers | array or string | Media progress track markers configuration. |
thumbnails | object | Media progress track thumbnails configuration. |
Samples:
{
"dataProvider": {
"progress": {
// segments as array of objects
"segments": [
{ "duration": 10, "label": "Example label" },
{ "duration": 20, "label": "Some other text" },
],
// or segments as url directing to vtt file
//"segments": "path/to/segments.vtt",
// markers as array of objects
"markers": [
{ "time": 10, "label": "Example label" },
{ "time": 20, "label": "Some other text" },
],
// or markers as url directing to vtt file
//"markers":"path/to/markers.vtt",
// thumbnails as object
"thumbnails": { "url": "path/to/thumbnails.vtt" },
},
"duration": 40
}
}
Data type: array or string
Default value: null
Description: Displays progres track time segments based on provided configuration.
Can be provided as:
– array - array containing configuration objects (more details).
{
"dataProvider": {
"progress": {
"segments": [
{ "duration": 10, "label": "Example label" },
{ "duration": 20, "label": "Some other text" },
]
},
"duration": 40,
"source": [{
"url": "https://bradmax.com/static/video/tos/big_buck_bunny.m3u8",
}]
}
}
– string - url directing to VTT file describing segments (more details).
{
"dataProvider": {
"progress": {
"segments": "path/to/segments.vtt"
},
"duration": 40
}
}
Data type: array
Default value: null
Description: Displays progres track time segments based on provided configuration. Segment ‘start’ on progress track is calculated as sum of previous segments durations, ‘end’ is calculated as sum of ‘start’ and segment duration. Segments with ‘end’ greater than media total duration will be cutted or not displayed. Configuration can also be provided as url to VTT file more details.
Available settings for segment array item object:
Key | Type | Description |
---|---|---|
duration | Number | segment duration in seconds. |
label | String | maximum label characters length is 22. |
Samples:
{
"dataProvider": {
"progress": {
"segments": [
{ "duration": 10, "label": "Example label" },
{ "duration": 20, "label": "Some other text" },
]
},
"duration": 40,
"source": [{
"url": "https://bradmax.com/static/video/tos/big_buck_bunny.m3u8",
}]
}
}
will render:
segments[0] | segments[1] | -------- |
---|---|---|
0-10 s. | 10-30 s. | 30-40 s. |
Notice: “segments” array order do matter.
Data type: string
Default value: null
Description: Displays progress track time segments based on provided configuration from vtt file.
Samples:
{
"dataProvider": {
"progress": {
"segments": "path/to/segments.vtt"
},
"duration": 40
}
}
segments.vtt:
WEBVTT
00:00:00.000 --> 00:00:10.000
Example label
00:00:10.000 --> 00:00:30.000
Some other text
...
will render:
segments[0] | segments[1] | -------- |
---|---|---|
0-10 s. | 10-30 s. | 30-40 s. |
Data type: array or string
Default value: null
Description: Displays progres track time markers based on provided configuration.
Can be provided as:
– array - array containing configuration objects (more details).
{
"dataProvider": {
"progress": {
"markers": [
{ "time": 10, "label": "Example label" },
{ "time": 20, "label": "Some other text" },
]
},
"duration": 40
}
}
– string - url directing to VTT file describing markers (more details).
{
"dataProvider": {
"markers": {
"segments": "path/to/markers.vtt"
},
"duration": 40
}
}
Data type: array
Description: Displays progres track time markers based on provided configuration. Markers with time value greater than media total duration will not be displayed.
Default value: null
Available settings for marker array item object:
Key | Type | Description |
---|---|---|
time | Number | marker time in seconds. |
label | String | maximum label characters length is 22. |
Samples:
{
"dataProvider": {
"progress": {
"markers": [
{ "time": 10, "label": "Example label" },
{ "time": 20, "label": "Some other text" },
]
},
"duration": 40,
"source": [{
"url": "https://bradmax.com/static/video/tos/big_buck_bunny.m3u8",
}]
}
}
will render:
------ | markers[0] | -------- | markers[1] | -------- |
---|---|---|---|---|
0-9 s. | 10 s. | 11-19 s. | 20 s. | 21-30 s. |
Notice: “markers” array order do matter.
Data type: string
Default value: null
Description: Displays progress track time markers based on provided configuration from vtt file.
Samples:
{
"dataProvider": {
"markers": {
"segments": "path/to/markers.vtt"
},
"duration": 40
}
}
segments.vtt:
WEBVTT
00:00:10.000 --> 00:00:00.000
Example label
00:00:20.000 --> 00:00:00.000
Some other text
...
Note: only first timestamp is used to position marker on progress track will render:
------ | markers[0] | -------- | markers[1] | -------- |
---|---|---|---|---|
0-9 s. | 10 s. | 11-19 s. | 20 s. | 21-30 s. |
Data type: object
Description: Displays progress thumbnails based on provided configuration. These thumbnails are displayed in a tooltip when a viewer hovers the progress track bar. Can handle single images or image sprite thumbnails.
Default value: null
Available settings for thumbnails object:
Key | Type | Description |
---|---|---|
url | String | (required) Path to VTT file containing thumbnails data. |
imageBaseUrl | String | (optional) Provide when thumbnail images have different base path than VTT file. If not than player use path relative to VTT file. |
Notice VTT files are subject to cross-domain security restrictions and therefore won’t automatically load from another domain than the player.
Notice: If imageBaseUrl is not provided in configuration then thumb image URL is relative to the VTT file (not to the page or player).
For each thumbnail you prepare single image in JPG, PNG or GIF format. Though it’s suggested to keep the same size for each image, it can be also different size, but it should keep the same display ratio. In VTT file you just type image path (relative or absolute) for each time cue. For best expirience, single image (frame) should have maximum width of 160 pixels.
WEBVTT
00:00:00.000 --> 00:00:10.000
thumbnails/thumb1.jpg
00:00:10.000 --> 00:00:15.000
thumbnails/thumb2.jpg
00:00:15.000 --> 00:00:20.000
thumbnails/thumb3.jpg
00:00:20.000 --> 00:00:25.000
thumbnails/thumb4.jpg
For best user expirience, it is adviced to append image size info to the thumbnail URL: “thumbnails/thumb1.jpg#wh=160,67” where w = 160px h = 67px.
WEBVTT
00:00:00.000 --> 00:00:10.000
thumbnails/thumb1.jpg#wh=160,67
Notice: The range needs to be in (HH:)MM:SS.MMM format. Only this exact notation will be parsed.
Notice Player supports pixel-based size data for image, not percentage-based ones.
To limit file size, load delay and server requests, player supports thumbnail sprites, multiple thumbnails tilled into a single image. In the VTT file, the individual thumbnails are identified by appending their coordinates (in pixels) to the thumbnail URL: “thumbnails/sprite.jpg#xywh=0,0,160,67” where x = 0, y = 0, w = 160px h = 67px.
WEBVTT
00:00:00.000 --> 00:00:10.000
thumbnails/sprite.jpg#xywh=0,0,160,67
00:00:10.000 --> 00:00:15.000
thumbnails/sprite.jpg#xywh=0,160,160,62
00:00:15.000 --> 00:00:20.000
thumbnails/sprite.jpg#xywh=0,320,160,62
00:00:20.000 --> 00:00:25.000
thumbnails/sprite.jpg#xywh=0,480,160,62
Notice: The range needs to be in (HH:)MM:SS.MMM format. Only this exact notation will be parsed.
Notice Player supports pixel-based coordinates for image sprites, not percentage-based ones.
Shell script to generate thumbnail images from video file with vtt file as thumbnails descriptor. Require ffmpeg and ffprobe to be installed.
Download: bradmax tumbnails tool
There are two wasy to generate thumbnails for video file:
Options:
required--input (-i)
- [string] path to ffmpeg input video file.--output (-o)
- [string] path to output directory.
optional-spritesheets
- when flag is added will generate image sprite files with thumbnails (default).-thumbnails
- when flag is added will generate single image for each thumbnail.-poster
- when flag is added will also generate poster image with random frame from input video.--timespan (-t)
- [integer] time span (in seconds) between each thumbnail, default 10 sec. It will generate thumbnail every 10 seconds.--width (-w)
- [integer] width (in pixels) of each thumbnail, default 160 px.--name (-n)
- [string] base name for generated files, default ‘spritesheet’ when -spritesheets or ‘thumbnail’ when -thumbnails flag is enabled.--vtt-name
- [string] override base name (-n) for VTT file. When provided generated vtt file path will be "[–output]/[–vtt-name].vtt".--img-name
- [string] override base name (-n) for image files. When provided generated images path will be "[–output]/[–img-name].jpg".--img-dir
- [string] base dir for image files. When provided generated images path will be "[–output]/[–img-dir]/[–(img-)name].jpg".--help (-h)
- display help message.
Note: When flag -spritesheets is enabled script will probe video file to find best match for image grid dimmentions based on provided video file duration and –timespan option value. Then You will need to choose one of proposed grid sizes. Best grid sizes are ones that do not have unused thumbnail spaces. For example if video duration is 30 seconds, thumbnails -timespan set to 10 (seconds) and choosed grid size is 2x2, then 1 thumbnail space will be unused, because (30s / 10s) = 3, but 2x2 = 4,
Usage:
$ thumbnails.sh -i /input/video.mp4 -o /output/directory
or:
$ thumbnails.sh -thumbnails -poster -i /input/video.mp4 -o /output/directory -w 160 -t 10 --vtt-name thumbnails --img-dir thumbs --img-name thumb
Basic example with minimal media configuration needed for proper bradmax statistics collection. "id", "title", “duration” fields are optional for video playback, but required for proper media details in bradmax statistics.
"dataProvider": {
"id": "101",
"title": "Big Buck Bunny",
"duration": 596.0,
"source": [{
"url": "https://bradmax.com/static/video/tos/big_buck_bunny.m3u8",
}]
}
Data provider configuration for defining playlist. For playlist replace configuration object for “dataProvider” by list of objects with configuration. More info: Playlist example
"dataProvider": [
{
"id": "101",
"title": "Big Buck Bunny",
"duration": 596.0,
"source": [{
"url": "https://bradmax.com/static/video/tos/big_buck_bunny.m3u8",
}]
},
{
"id": "102",
"title": "Tears of steel",
"duration": 734.097415,
"source": [{
"url": "https://bradmax.com/static/video/tears_of_steel.mp4",
}],
"splashImages": [{
url: "http://bradmax.com/static/images/startsplash.jpg",
}]
}
]
Sample 1: Live stream transmission ending at 2020-06-10 20:00:00 (UTC). Before staring stream image “http://bradmax.com/static/images/startsplash.jpg” will be shown. Before staring player will already show that it is live stream transmission (text “Live” next to progress bar). When user start playback then “https://bradmax.com/static/images/waiting_for_transmission.jpg” (link from waitingForTransmissionImageUrl) image will be shown until transmission start.
After end of transmission after 2020-06-10 20:00:00 (UTC), custom “thank you” image “https://bradmax.com/static/images/thankyou_endsplash.jpg” will be shown.
When content marked as live stream transmission (added “liveStream” key) player can be presented before live stream transmission. When user click “play” button before starting transmission, player will wait for it. User will see buffering/loading icon until transmission start with an image waitingForTransmissionImageUrl in background.
{
"dataProvider": {
"source": [
{ "url": "http://example.com/stream.m3u8" }
],
"splashImages": [
{ "url": "http://bradmax.com/static/images/startsplash.jpg" }
],
"liveStream": {
"endDate": "2020-06-10T20:00:00Z",
"thankYouImageUrl": "https://bradmax.com/static/images/thankyou_endsplash.jpg",
"waitingForTransmissionImageUrl": "https://bradmax.com/static/images/waiting_for_transmission.jpg"
}
}
}
Sample 2: Live stream transmission ending at 2020-06-20 14:00:00 (GMT+8). Before staring stream image “http://bradmax.com/static/images/startsplash.jpg” will be shown. After end of transmission after 2020-06-20 14:00:00 (GMT+8), start splash image will be shown ""http://bradmax.com/static/images/startsplash.jpg".
{
"dataProvider": {
"source": [
{ "url": "http://example.com/stream.m3u8" }
],
"splashImages": [
{ "url": "http://bradmax.com/static/images/startsplash.jpg" }
],
"liveStream": {
"endDate": "2020-06-14T14:00:00+08:00",
}
}
}
Sample 3: Minimal sample for enabling live stream mode. Setting liveStream key as object without any settings. Player will wait for live stream transmission, but without endDate in case of any connection problem with streaming server player will assume, that transmission has already ended.
{
"dataProvider": {
"source": [
{ "url": "http://example.com/stream.m3u8" }
],
"splashImages": [
{ "url": "http://bradmax.com/static/images/startsplash.jpg" }
]
},
"liveStream": {}
}
Sample 4: Sample for enabling live stream mode with custom end splash image presented after live stream transmission.
{
"dataProvider": {
"source": [
{ "url": "http://example.com/stream.m3u8" }
],
"splashImages": [
{ "url": "http://bradmax.com/static/images/startsplash.jpg" }
]
},
"liveStream": {
"thankYouImageUrl": "https://bradmax.com/static/images/thankyou_endsplash.jpg"
}
}