Dataprovider

“dataProvider” attribute of player configuration object can be JSON formatted Media Object (described below), or array of Media Objects as a media playlist.

1. Media Object:

Field nameTypeDescription
idstringMedia asset id.
titlestringMedia asset title.
durationnumberMedia duration in seconds.
sourcearrayArray of media source metadata objects (for more details see Media Source Object).
sourceWithFallbacksarrayArray of arrays with media source metadata objects. Defines backup sources in case of playback error.
splashImagesarrayArray of splash image metadata objects (for more details see Media Splash Image Object).
mediaLandingPagestringUrl pointing to media landing page.
subtitlesSetsarraySubtitles configuration for subtitles not embedded in video stream (loading one language from single external file).
liveStreamobjectAdditional settings for live stream transmission.
progressobjectAdditional settings for progress bar.

id

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"
}

title

Data type: string

Description: Title of media asset.

"dataProvider": {
    "title": "Tears of steel"
}

duration

Data type: string

Description: Media asset duration time in seconds.

"dataProvider": {
    "duration": 734.097415
}

source

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.
    ]
}

sourceWithFallbacks

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).

splashImages

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
    }
]

mediaLandingPage

Data type: string

Description: Url pointing to media landing page.

"dataProvider": {
    "mediaLandingPage": "http://bradmax.com"
}

2. Media Source Object:

Field nameTypeDescription
contentTypestringContent type name.
urlstringURL pointing to media asset.
bitratenumberBitrate of media asset.
widthnumberWidth of media asset in pixels.
heightnumberHeight of media asset in pixels.

source contentType

Data type: string

Description: Content type name. Possible values 'movie’, 'trailer’, 'live’.

"dataProvider": {
    "source": [
        {
            "contentType": "movie",
        }
    ]
}

source url

Data type: string

Description: URL pointing to media asset.

"dataProvider": {
    "source": [
        {
            "url": "http://bradmax.com/static/video/tos/440272.mpd",
        }
    ]
}

source bitrate

Data type: number

Description: Bitrate of media asset.

"dataProvider": {
    "source": [
        {
            "bitrate": 191999
        }
    ]
}

source width

Data type: number

Description: Width of media asset in pixels.

"dataProvider": {
    "source": [
        {
            "width": 955
        }
    ]
}

source height

Data type: number

Description: Height of media asset in pixels

"dataProvider": {
    "source": [
        {
            "height": 397
        }
    ]
}

3. Media Splash Image Object:

Field nameTypeDescription
urlstringURL pointing to image asset.
widthnumberWidth of image asset in pixels.
heightnumberHeight of image asset in pixels.

splashImage url

Data type: string

Description: URL pointing to image asset

"dataProvider": {
    "splashImages": [
        {
            "url": "http://bradmax.com/static/images/startsplash.jpg"
        }
    ]
}

splashImage width

Data type: number

Description: Width of image asset in pixels.

"dataProvider": {
    "splashImages": [
        {
            "width": 955
        }
    ]
}

splashImage height

Data type: number

Description: Height of image asset in pixels

"dataProvider": {
    "splashImages": [
        {
            "height": 397
        }
    ]
}

4. Media Subtitles Configuration

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 nameTypeDescription
languageCodestringIt is ISO 3166-1 language code. It can be defined as alpha-2 or alpha-3 (2 or 3 letter language code).
urlstringURL address for raw subtiles file (not compressed by zip or similar compression method).
Supported subtitles file formatsFile extensions
SRT*.srt
VTT*.vtt *.webvtt

Note: If you want automatically select some language for subtitles please check subtitles

5. Media liveStream transmission Configuration

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:

KeyDescription
endDateDate 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.
thankYouImageUrlLink 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.
waitingForTransmissionImageUrlLink to custom waiting for transmission image, which should be shown when player is waiting for live stream transmission start.




6. Media progress configuration


Data type: object

Default value: null

Available settings for progress object:

Field nameTypeDescription
segmentsarray or stringMedia progress track segments configuration.
markersarray or stringMedia progress track markers configuration.
thumbnailsobjectMedia 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
    }
}


6.1 Media progress segments configuration


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
    }
}

6.1.1 Media progress segments as array of objects


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:

KeyTypeDescription
durationNumbersegment duration in seconds.
labelStringmaximum 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.

segments

Notice: “segments” array order do matter.


6.1.1 Media progress segments as url


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.

segments


6.2 Media progress markers configuration


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
    }
}


6.2.1 Media progress markers configuration as array of objects


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:

KeyTypeDescription
timeNumbermarker time in seconds.
labelStringmaximum 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.

markers Notice: “markers” array order do matter.

6.2.3 Media progress markers as url


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.

markers


6.3 Media progress thumbnails configuration


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. thumbnails

Default value: null

Available settings for thumbnails object:

KeyTypeDescription
urlString(required) Path to VTT file containing thumbnails data.
imageBaseUrlString(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).


6.3.1 Single image thumbnails


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.


6.3.2 Thumbnails from sprite image


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.


6.4 Bradmax Thumbnails Tool


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:

  • as spritesheets. Images are merged into sprites sheets (flag -spritesheets ). These is default behaviour.
  • as thumbnails. Each thumbnail as separated image file (flag -thumbnails ).


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




7. Basic example

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",
    }]
}

8. Playlist example

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",
        }]
    }
]

9. LiveStream transmission examples

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"
    }
}