🎮

Player API

For use with AI / LLM

events

Player events

Boomstream Player triggers events that you can catch on the page using JavaScript. Player triggers the following events:

loaded - Player's iframe is loaded and ready to get actions.
play - When Player starts playing a video.
pause - When user pauses a video.
stop - When Player finishes playing a video.
time - Periodical event which sends current video position.
event - JavaScript event.
progress - When user/player changes progress bar point.
fullScreen - When fullscreen mode is changed.
playbackRate - When playback speed is changed.
qualities - When the list of available qualities is ready or updated.
quality - When a quality is selected.
theme - When player theme is changed.

Note: You can pass parameter use_fullscreen_mode=0 to disable the full screen mode entering (it works just events and the button switching). Example: https://play.boomstream.com/VCcNtuiw?use_fullscreen_mode=0

Integration

You should add the following JavaScript code to the page where Boomstream Player is located:

window.addEventListener('message', receiveMessage, false);
function receiveMessage(event) {
  if (event.origin !== "https://play.boomstream.com") {
    return;
  }
  // Your code here
}

Event data will be located in the event object in the data field.

Possible field properties:

method - Event name (loaded, play, pause, stop, time, event, fullScreen, progress, playbackRate, qualities, quality, theme).
code - Video code.
time - Current video position. Allowed for events: loaded, play, pause, stop, time.
duration - Duration of video. Allowed for events: loaded, play, pause, stop, time.
event - JavaScript event type from iframe (it works in case of method is 'event' or 'fullScreen').
- In case of method is 'event', it can be: window.onfocus, window.onblur
- In case of method is 'fullScreen', it can be: requestFullscreen, exitFullscreen
- In case of method is 'progress', it can be: change
- In case of method is 'playbackRate' - playback speed, a number: 0.5, 1, 1.5, etc.
- In case of method is 'qualities' - array of available qualities (frame height, descending), e.g. [1080, 720, 360]
- In case of method is 'quality' - selected quality: frame height (e.g. 720) or 'auto'
- In case of method is 'theme' - player theme: light, dark or device

calls

Action calls

There is a messaging system JavaScript API (postMessage) to control Boomstream player outside of iframe (to use external buttons on the site). Actions you can pass into the player:

play - Start playback.
pause - Set pause.
seek - Seek to a time moment (time is in percents %).
mute - Disable sound.
unmute - Enable sound.
volume - Setup volume (volume is in percent).
useLastTime - Start playback from a last time.
previous - Set previous video in playlist.
next - Set next video in playlist.
fullScreen - Toggle full screen mode.
toggleFullScreenButtonState - Toggle full screen button without full screen mode action (options for value: 'requestFullscreen', 'exitFullscreen').
playbackRate - Set playback speed: a number from 0.5 to 2. Speed is not changed for live streams.
quality - Select quality: 'auto' (automatic) or a frame height from the qualities event, e.g. 720 or '720p'. If there is no such quality, the action is ignored.
theme - Set player theme: 'light', 'dark' or 'device' (follow the device settings).

Note: actions and events playbackRate, quality, qualities and theme are supported by player v2; SDK methods player.playbackRate(), player.quality(), player.theme() are available since SDK 1.5.0. Selected speed, quality and theme are remembered in the viewer's browser, the same as when selected in the player menu.

Integration

Use this HTML code to send actions into the player:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>Example of player in frame</title>
        <style>
            .embed-container iframe {
                position: absolute;
                top: 0;
                left: 0;
                width: 100%;
                height: 100%;
            }
            .embed-container {
                position: relative;
                padding-bottom: 56.25%;
                height: 0;
                overflow: hidden;
                max-width: 100%;
            }
        </style>
        <script src="https://play.boomstream.com/assets/javascripts/biframesdk.js?v=1.5.0"></script>
    </head>
    <body>
    <script>

        let player = new bIframeSDK('MEDIA_CODE');
        let seekTime = 10; //value is in percents

        window.addEventListener('message', receiveMessage, false);

        function receiveMessage(event) {

            if (event.data && event.data.method == 'loaded' && event.data.code == 'MEDIA_CODE') {

                console.log(event);

                if (seekTime > event.data.time && event.data.duration) {
                    let seek = seekTime * 100 / event.data.duration; // Seek value is in percents
                    player.mute(); // Onloaded start is allowed only with sound muted.
                    player.seek(seek);
                }
            }
        }

    </script>
    <button onclick="player.play()">play</button>
    <button onclick="player.pause()">pause</button>
    <button onclick="player.seek(10)">seek to 10 %</button>
    <button onclick="player.mute()">mute</button>
    <button onclick="player.unmute()">unmute</button>
    <button onclick="player.volume(50)">volume to 50 %</button>
    <button onclick="player.useLastTime()">useLastTime</button>
    <button onclick="player.previous()">previous</button>
    <button onclick="player.next()">next</button>
    <button onclick="player.fullScreen()">fullScreen</button>
    <button onclick="player.toggleFullScreenButtonState()">toggleFullScreenButtonState</button>
    <button onclick="player.playbackRate(1.5)">speed 1.5x</button>
    <button onclick="player.quality(720)">quality 720p</button>
    <button onclick="player.quality('auto')">quality auto</button>
    <button onclick="player.theme('dark')">dark theme</button>
    <button onclick="player.theme('light')">light theme</button>
    <div style="margin-right: auto;margin-left: auto;width:900px;">
        <div class="embed-container">
            <iframe width="100%" height="355" src="https://play.boomstream.com/MEDIA_CODE" frameborder="0" scrolling="no" allow="autoplay; fullscreen" name="target"></iframe>
        </div>
    </div>
    </body>
</html>

You can try demo by link: https://play.boomstream.com/test/frame.html

Important: Iframe code must contain parameter: allow="autoplay; fullscreen"

To send actions into the player you can use JavaScript API (postMessage). Examples:

let frame = document.querySelector("iframe");
frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'play', data: ''}, '*');
frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'pause', data: ''}, '*');
frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'seek', data: '10'}, '*');
frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'mute', data: ''}, '*');
frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'unmute', data: ''}, '*');
frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'volume', data: '50'}, '*');
frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'useLastTime', data: ''}, '*');
frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'previous', data: ''}, '*');
frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'next', data: ''}, '*');
frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'fullScreen', data: ''}, '*');

frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'toggleFullScreenButtonState', data: ''}, '*');
frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'toggleFullScreenButtonState', data: 'exitFullscreen'}, '*');
frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'toggleFullScreenButtonState', data: 'requestFullscreen'}, '*');

frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'playbackRate', data: 1.5}, '*');
frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'quality', data: 720}, '*');
frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'quality', data: 'auto'}, '*');
frame.contentWindow.postMessage({code: 'MEDIA_CODE', method: 'action', action: 'theme', data: 'dark'}, '*');

The player sends the list of available qualities in the qualities event — use it to build your own quality menu:

window.addEventListener('message', function (event) {
  if (event.origin !== "https://play.boomstream.com" || !event.data) {
    return;
  }
  if (event.data.method === 'qualities') {
    console.log('Available qualities:', event.data.event); // e.g. [1080, 720, 360]
  }
  if (event.data.method === 'quality') {
    console.log('Current quality:', event.data.event); // 720 or 'auto'
  }
});

Player theme matching the site

The theme can be set when embedding — it is applied right on player load and is not remembered as the viewer's choice:

URL parameter theme: https://play.boomstream.com/MEDIA_CODE?theme=dark (light, dark or device);
in the SDK (since 1.5.0) — the data-boomstream-theme attribute: auto — the player becomes light or dark to match the page and switches together with it; light / dark — a fixed theme; device — follows the viewer's system (for sites whose theme follows the system):

<span data-boomstream-code="MEDIA_CODE" data-boomstream-theme="auto"></span>

Dark-themed sites: if the player iframe is embedded without the SDK, pass the dark theme in the URL (?theme=dark) or add style="color-scheme: light" to the iframe (the player stays light). If the site's theme follows the viewer's system, pass ?theme=device. Otherwise the browser may show a thin white line at the player's edge. SDK 1.5.0 does this automatically.