Configuration

HTML player configuration

Player has multiple options, which can be setup by configuration object. Please click on field name for see more detail.

Field nameTypeDescription
dataSourcestringURL pointing to json file with media data.
dataProviderobjectJavaScript object with media data.
advertisementobjectConfiguration object for player advertisement.
freewheelobjectConfiguration object for freewheel advertisement.
autoplayboolIndicates if player should play video after player load.
muteboolIndicates if player should start playback with muted sound.
startTimefloatIndicates initial start time of video.
qualitySelectionEnabledboolIndicates if quality selection should be enabled in player.
qualityLabelTypestringSelects if bitrate or resolution should be on quality list.
qualityInitialBandwidthKbsnumberSelects initial quality bitrate on playback start.
showSkinOnInitboolIndicates if player skin should be visible at player start.
shareButtonsstringList of comma separated social button names.
hideUIElementsstringList of comma separated elements to disable/hide.
endSplashstringName of end splash view to use.
subtitlesstringDefault subtitles language in ISO 3166-1 language code.
audiostringDefault audio language in ISO 3166-1 language code.
localestringLanguage code for translating player messages.
dvrWindowStartTimefloatHead constraint for DVR window for live streams.
dvrWindowEndTimefloatTail constraint for DVR window for live streams.
isDvrWallTimeModeboolIndicates if wall-time mode is enabled for live stream.
iosInlineVideoboolIndicates if video should be inlined for iOS.
gdprAgreeRequiredboolIndicates if GDPR agree is required for users statistics.
gdprAgreeForCookieboolIndicates if agree for cookie is present for users stats.
logoAutohideboolIndicates if logo should hide during hiding skin.
logoVisibleDuringAdPlaybackboolIndicates if logo should be visible during ad playback.
liveStreamobjectAdditional settings for live stream transmission.
skinColorstringUse for custom player skin color.
logoFilestringImage URL for custom player logo.
logoLinkstringPage URL, where user should land after clicking logo.
logoLinkTargetstringPage target after clicking player logo.
logoAutohideboolOptional - Indicates if logo should hide with player skin.
logoYPositionstringOptional - Vertical logo configuration ("top", “bottom”).
logoXPositionstringOptional - Horizontal logo configuration ("left", “right”).
pictureInPictureButtonVisibleboolOptional - Enables additional button for Picture-in-Picture.
videoCastEnabledboolOptional - Enables video casting for AirPlay technology.

dataSource

Data type: string

Description: URL pointing to json file with media data. For structure of media data see section Media object.

Note: If json file/service is on other domain than web page with player, then CORS headers are required response load. In other case browser will trigger an error that JavaScript has no permissions for loading them.

Example of json response:

    {
        "dataProvider": {
            "title": "Tears of steel",
            "duration": 734.097415,
            "source": [
                {
                    "contentType": "movie",
                    "url": "http://bradmax.com/static/video/tos/440272.mpd",
                    "bitrate": 191999,
                    "width": 1280,
                    "height": 534
                }
            ],
            "splashImages": [
                {
                    "url": "http://bradmax.com/static/images/startsplash.jpg",
                    "width": 955,
                    "height": 397
                }
            ]
        }
    }

dataProvider

Data type: object

Description: JavaScript object with media object formatted structure.

advertisement

Data type: object

Description: Configuration object defining which and how should be displayed advertisements by player. For more details see Advertisements section.

freewheel

Data type: object

Description: Configuration object defining which and how freewheel advertisements should be displayed by player. For more details see Freewheel section.

autoplay

Data type: bool

Description: Field indicates if player should start playback just after player setup. If “true” then video starts just after player setup. In other case user has to click “play” button for playback. By default option is disabled.

Note: This option is not working on mobile devices. All mobile devices require user action for starting video playback. It is limitation of mobile device platforms, which cannot be bypass.

mute

Data type: bool

Description: Field indicates if player should be muted at start. If “true” then video starts with muted sound.

Note: Currently “autoplay” is blocked by most of browsers. It is possible to bypass this constraint, when video is muted. Use this option ("muted": true) for automatic starting video playback.

Example of use:

    {
        "autoplay": true,
        "mute": true,
        "dataProvider": {
            "title": "Tears of steel",
            "duration": 734.097415,
            "source": [ { "url": "http://bradmax.com/static/video/tos/440272.mpd" } ]
        }
    }

startTime

Data type: float

Description: This field define initial time of video, where playback should start. For ordinary streams it is time of video, for live events streaming it is timestamp (in seconds, with fraction of second).

Example of use:

    {
        "startTime": 120.66,
        "dataProvider": {
            "title": "Tears of steel",
            "duration": 734.097415,
            "source": [ { "url": "http://bradmax.com/static/video/tos/440272.mpd" } ]
        }
    }

qualitySelectionEnabled

Data type: bool

Description: This field enable / disable possibility for user to change video quality - if available for played media. If set to “true” then button with quality selection will be visible on player. In other case selection will be hidden and player will choose quality automatically. Default value for this field is "true".

qualityLabelType

Data type: string

Description: This field choose if bitrate or screen resolution, should be present on quality selection list.

ValueDescription
resolutionResolution will be presented on quality selection list (eg. 480p, 720p)
bitrateBitrate will be presented on quality selection list (eg. 600k, 1200k).

Default value: “resolution”

qualityInitialBandwidthKbs

Data type: number

Description: This field choose initial bitrate for player, when there is no knowledge about user internet connection speed. This value has only affect on playback start. Later quality will be adjusted to user connection. Value is defined in [kb/s].

Tip: By setting this parameter you can adjust player start behaviour. By setting:

ValueDescription
0Player will start as soon as possible, but with lower quality at begin - good for Live content.
20000Player will load longer, but with better quality from beginning - good for VOD content.

Default value: 1000 (1Mb/s, 125kB/s)

Example:

{
    "qualityInitialBandwidthKbs": 100,
    "dataProvider": {
        "title": "Tears of steel",
        "duration": 734.097415,
        "source": [
            { "url": "http://bradmax.com/static/video/tos/440272.mpd" }
        ]
    }
}

showSkinOnInit

Data type: bool

Description: When option enabled then player skin is visible after player setup and user do not need to click / tap / hover with mouse over player for showing player controls. By default this option is disabled.

shareButtons

Data type: string

Description: List of comma separated social button names, which should be presented on player screen.

ValueDescription
embedShow pop up window with player embed code.
mailOpen system default email client.
facebookOpen Facebook share page with media url address and title.
twitterOpen Twitter share page with media url address and title.
linkedInOpen LinkedIn share page with media url address and title.

Example:

shareButtons: "embed,facebook,twitter",

hideUIElements

Data type: string

Description: List of comma separated elements names to hide in player. Currently only: “fullscreenButton” support this feature.

ValueDescription
fullscreenButtonButton for opening player in fullscreen mode.

Example:

hideUIElements: "fullscreenButton",

endSplash

Data type: string

Description: Name of end splash view to use. Below are list of available values. By default ‘reload’ is selected.

ValueDescriptionPreview
reloadDefault value.reload
socialAvailable when “shareButtons” data is present in player configuration, else default ‘reload’.reload
countdownAvailable when “playList” data is present in provided media object, else default ‘reload’.reload
tilesAvailable when “playList” data is present in provided media object, else default ‘reload’.reload

subtitles

Data type: string

Description: Defines default language for subtitles. When defined this language will be automatically selected, when subtitles for this language are present. Language is defined as two letters (alpha-2) ISO 3306-1 language code (for eg. “fr” for France).

subtitles: "fr",
{
    "subtitles": "fr",
    "dataProvider": {
        "title": "Tears of steel",
        "duration": 734.097415,
        "source": [
            { "url": "http://bradmax.com/static/video/tos/440272.mpd" }
        ]
    }
}

audio

Data type: string

Description: Defines default audio track language. When defined this language will be automatically selected, when audio track for this language is present. Language is defined as two letters (alpha-2) ISO 3306-1 language code (for eg. “fr” for France).

audio: "fr",
{
    "audio": "fr",
    "dataProvider": {
        "title": "Tears of steel",
        "duration": 734.097415,
        "source": [
            { "url": "http://bradmax.com/static/video/tos/440272.mpd" }
        ]
    }
}

locale

Data type: string

Description: Defines language code, which should be used for player messages on player skin (eg. error message). Default: 'en’. Available values: da, en, fi, pl, no, sv

locale: "da",
{
    "locale": "da",
    "dataProvider": {
        "title": "Tears of steel",
        "duration": 734.097415,
        "source": [
            { "url": "http://bradmax.com/static/video/tos/440272.mpd" }
        ]
    }
}

dvrWindowStartTime

Data type: float

Description: This option is only for live streams with DVR window. It is additional constraint for it. When unix timestamp defined for this option then user is not able to seek before this moment. For user, video starts after this time and he will be not aware that available DVR window is wider.

{
    "dvrWindowStartTime": 1537444800,
    "dataProvider": {
        "source": [
            { "url": "http://example.com/live_stream_with_dvr.m3u8" }
        ]
    }
}

dvrWindowEndTime

Data type: float

Description: This option is only for live streams with DVR window. It is additional constraint for it. When unix timestamp defined for this option then user is not able to seek after this moment. For user, video ends after this time and he will be not aware that available DVR window is wider.

{
    "startTime": 1537444800,
    "dvrWindowStartTime": 1537444800,
    "dvrWindowEndTime": 1537448400,
    "dataProvider": {
        "source": [
            { "url": "http://example.com/live_stream_with_dvr.m3u8" }
        ]
    }
}

isDvrWallTimeMode

Data type: bool

Description: Indicates if wall-time should be presented during live stream transmission. It is most useful for IP TV transmission. By default it is disabled for not confusing users for ordinary live streams.

Default value: false

{
    "isDvrWallTimeMode": true,
    "dataProvider": {
        "source": [
            { "url": "http://example.com/live_stream_with_dvr.m3u8" }
        ]
    }
}

iosInlineVideo

Data type: bool

Description: This option indicates if video should be inlined for iPhone devices. By default for iPhones devices video is fullscreened with native iOS player. When defined option "iosInlineVideo": true , then playback will be performed on HTML page - similar to MacOS or iPad playback.

Default value: false

{
    "iosInlineVideo": true,
    "dataProvider": {
        "source": [
            { "url": "http://example.com/stream.m3u8" }
        ]
    }
}

gdprAgreeRequired

Data type: bool

Description: This option indicates if user agree for cookie is required. If gdprAgreeRequired:true, then cookies will not be used for users statistics and additional agree “gdprAgreeForCookie” is required for using them. If gdprAgreeRequired:false, then it is assumed that cookie can be used without user agree. This option has to be defined in “bradmaxAnalytics” settings scope - see example below.

Default value: false

{
    "bradmaxAnalytics": {
        "gdprAgreeRequired": true,
        "gdprAgreeForCookie": true
    },
    "dataProvider": {
        "source": [
            { "url": "http://example.com/stream.m3u8" }
        ]
    }
}

gdprAgreeForCookie

Data type: bool

Description: This option works together with gdprAgreeRequired option. When gdprAgreeRequired:true, then setting this option is required for using cookies for user statistics. gdprAgreeForCookie:true indicates user agree for using cookue for statistics purpose. This option has to be defined in “bradmaxAnalytics” settings scope - see example below.

Bradmax cookies names used for statistics purpose: _bamcdc, _bame, _baml .

Default value: false

{
    "bradmaxAnalytics": {
        "gdprAgreeRequired": true,
        "gdprAgreeForCookie": true
    },
    "dataProvider": {
        "source": [
            { "url": "http://example.com/stream.m3u8" }
        ]
    }
}

logoAutohide

Data type: bool

Description: This option indicates if brand logo should hide with hiding skin during video playback.

Default value: (predefined in player configuration in bradmax client panel)

{
    "logoAutohide": false,
    "dataProvider": {
        "source": [
            { "url": "http://example.com/stream.m3u8" }
        ]
    }
}

logoVisibleDuringAdPlayback

Data type: bool

Description: This option indicates if brand logo should be visible during advertisement playback.

Default value: false

{
    "logoVisibleDuringAdPlayback": true,
    "dataProvider": {
        "source": [
            { "url": "http://example.com/stream.m3u8" }
        ]
    }
}

liveStream

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.
lowLatencyModeIndicates if lowLatencyMode should be enabled. By default it is disabled. When lowLatencyMode:true then latency optimization is used at the expense of quality (stream is in lower quality and can buffer more frequently, but with much lower latency). This mode is working only for HLS and MPEG-DASH streams. example configuration

Samples:

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 showing lowLatencyMode for live stream. It is mostly useful for transmission, where latency is a critical factor (eg. conferences, some sport events). For “Low Latency MPEG-DASH” streams latency between streaming server and user is typically 2 seconds. For LL-HLS (Low Latency - HLS) typical latency is 4 seconds.

Not all devices support this mode. In case of lack support player will play such streams normally - with higher latency and better quality.

{
    "dataProvider": {
        "source": [
            { "url": "https://ll-hls-test.apple.com/cmaf/master.m3u8" }
        ],
        "splashImages": [
            { "url": "https://bradmax.com/static/images/startsplash.jpg" }
        ]
    },
    "liveStream": {
        "lowLatencyMode": true
    }
}

skinColor

Data type: string

Description: This parameter can be used to override player skin defined color. Color defined in HEX format "#RRGGBB".

Default value: null

{
    "dataProvider": {
        "source": [
            { "url": "http://example.com/stream.m3u8" }
        ]
    },
    "skinColor": "#FF0000"
}

logoFile

Data type: string

Description: Image URL for custom player logo. It overwrites player logo configuration - if defined.

Default value: null

{
    "dataProvider": {
        "source": [
            { "url": "http://example.com/stream.m3u8" }
        ]
    },
    "logoFile": "http://example.com/logo.png"
}

logoLink

Data type: string

Description: Page URL, which should be open after clicking logo on player.

Default value: null

logoLinkTarget

Data type: string

Description: If not defined any value, then clicking logo will open target page (logoLink) in current player page. Usually it is good to define “_blank” for instruct browser to open target page in new browser tab.

Default value: null

{
    "dataProvider": {
        "source": [
            { "url": "http://example.com/stream.m3u8" }
        ]
    },
    "logoFile": "http://example.com/logo.png",
    "logoLink": "http://bradmax.com",
    "logoLinkTarget": "_blank"
}

Clicking logo will open “http://bradmax.com” page in new tab.

logoAutohide

Data type: bool

Description: Indicates if logo should hide with player skin. By default logo will be kept visible even player skin is hidden. If logoAutohide:true, then logo will hide with player skin.

Default value: false

logoYPosition

Data type: string

Description: Vertical logo configuration. Available values: "top", “bottom”

Default value: “top”

logoXPosition

Data type: string

Description: Vertical logo configuration. Available values: "left", “right”

Default value: “left”

{
    "dataProvider": {
        "source": [
            { "url": "http://example.com/stream.m3u8" }
        ]
    },
    "logoFile": "http://example.com/logo.png",
    "logoLink": "http://bradmax.com",
    "logoLinkTarget": "_blank",
    "logoYPosition": "bottom",
    "logoXPosition": "right"
}

Logo will be displayed on bottom right corner of player (over player controls).

pictureInPictureButtonVisible

Data type: bool

Description: Enables additional button in player skin for enabling/disabling Picture-in-Picture mode. When PIP mode is enabled then player is detached from browser and user can watch video over other screens.

Notice: PIP button will appear only when browser supports such feature and it can be enabled. Button appears only, when browser allows PIP mode for video. Usually after video playback start (user action is required). Button is not available for FireFox browser. FireFox browser has own Picture-in-Picture mechanics for video and it cannot be controlled by custom buttons or JavaScript.

Default value: false

{
    "dataProvider": {
        "source": [
            { "url": "http://example.com/stream.m3u8" }
        ]
    },
    "pictureInPictureButtonVisible": true
}

videoCastEnabled

Data type: bool

Description: Enables video casting for AirPlay technology. When enabled Safari browser can cast video to AppleTV. Web player becomes a remote controller for this video.

AirPlay icon appears in player control bar only, when AirPlay device (eg. AppleTV) is detected in the same local network (eg. same WiFi network).

Default value: false

{
    "dataProvider": {
        "source": [
            { "url": "http://example.com/stream.m3u8" }
        ]
    },
    "videoCastEnabled": true
}