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:

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:

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:

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

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:

6. Media progress configuration

Data type: object

Default value: null

Available settings for progress object:

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:

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:

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:

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:

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:

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:

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.

Default value: null

Available settings for thumbnails object:

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