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.

title

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

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

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