API: Play Video on External Screen

Trigger and control full-screen video playback on an external screen or projector.

In this article

Requirements

Kiosk Pro Enterprise

  • Integration of our JavaScript API into your webpage
    • Sample code to run within the app and download for integration into your own project is available here.
    • Best practices for working with the JavaScript API are available here.
  • App Settings
    • Content > JavaScript API > Access JavaScript API = By Import
    • Screensaver > External Monitor Mode = Interactive or Standard Mirroring
  • Physical Hardware
    • External screen or projector connected via HDMI to the iPad through a Digital AV Adapter or hub or to a connected Apple TV for wireless Airplay.

Triggers via API Functions

Set Video Playback Options

This function sets how the video should fit the screen, fade duration and the background color or image shown when video starts, completes playback, or is stopped. The background color or image is also shown if the video file is not proportioned to fit the screen dimensions.

Format 
kp_ExternalScreen_setPlayVideoParamsEx(configDic, callback);
Parameters
  • configDic - [JSON] dictionary array consisting of the following possible keys:
    • fillMode - [integer] the duration in seconds to fade in and out the video being shown on the external display. Note that the fade overlaps video playback so if you are using extended fade times, you may want to take that into account when formatting your video files
      • 0 - ResizeAspect - preserve aspect ratio; fit within layer bounds (default)
      • 1 - ResizeAspectFill - preserve aspect ratio; fill layer bounds (some cropping may occur
      • 2 - Resize - stretch to fill layer bounds
    • fadeDuration - [real number] the duration in seconds to fade in and out the video being shown on the external display. Note that the fade overlaps video playback so if you are using extended fade times, you may want to take that into account when formatting your video files
    • fadeBgColor - [string] the background color or image to be shown during fade animation or if the video file does not fill the external screen
      • R,G,B - [string] the background color, set in R,G,B format
      • image file - [string] the file path to the desired video file. If local, this path should be relative to the Kiosk Pro documents folder (rather than relative to the file calling the function). If remote, this should be the full URL
  • callback - [string] the name of the callback to be triggered after the function has been executed
Callback format 
callback(success);
Callback return values
  • success - [integer] indicating whether options were successfully updated. Possible values are:
    • 0 - option update failed
    • 1 - new options set

Check Current Video Playback Options

This function triggers a callback returning the current fill mode, fade duration, and the background color or image shown when video starts, completes playback, or is stopped.

Format 
kp_ExternalScreen_getPlayVideoParamsEx(callback);
Parameters
  • callback - [string] the name of the callback to be triggered after the function has been executed
    		•
    Callback format 
    callback(configDic);
    Callback return values Callback uses the same configDic JSON array outlined in kp_ExternalScreen_setPlayVideoParamsEx directly above.

    Play Video

    This function plays the video file specified by the 'filePath' parameter on the external display. Kiosk Pro supports the following video formats:

    • .mp4 - recommended
    • .mov (encoded with H264 codec only)
    • .mpv
    • .3gp

    If referencing a locally stored file, the file path is relative to the Kiosk Pro documents folder. If referencing a remotely stored file, use the full URL. If the app cannot find the file at the specified path, then the method will fail.

    Using the 'repeat' parameter, your code can tell Kiosk Pro whether to just play the video once or to repeat in an infinite loop until a new request is made. If your code makes another primary request (for example, calling kp_ExternalScreen_playVideo again), that request will be honored and the video currently playing will be immediately stopped.

    Format 
    kp_ExternalScreen_playVideo(filePath, repeat, сallback);
    Parameters
    • filePath - [string] the file path to the desired video file. If local, this path should be relative to the Kiosk Pro documents folder (rather than relative to the file calling the function). If remote, this should be the full URL
    • repeat - [integer] indicating whether the video should be looped. Possible values are:
      • 0 - video will be played one time
      • 1 - video will repeat in a loop until a new request is made
    • callback - [string] the name of the callback to be triggered after the function has been executed
    Callback format 
    callback(isPlayingJobWasAccepted);
    Callback return values
    • isPlayingJobWasAccepted - [integer] indicating whether an external display is linked and returned no errors when playback was requested. Possible values are:
      • 0 - video playback failed
      • 1 - external display is linked and returned no errors when playback was requested
    Triggers Nothing directly, but the change in playback state will trigger kp_ExternalScreen_videoPlaybackStateDidChange

    Stop Video Immediately

    This function immediately stops the video currently being displayed on the external screen. No fade is shown when ending a video with this function and playback cannot be resumed.

    Format 
    kp_ExternalScreen_stopVideo();
    Triggers Nothing directly, but the change in playback state will trigger kp_ExternalScreen_videoPlaybackStateDidChange

    Stop Video With Fade

    This function stops the video currently being displayed on the external screen and transitions with the fade currently configured.

    Format 
    kp_ExternalScreen_stopVideoWithFading();
    Triggers Nothing directly, but the change in playback state will trigger kp_ExternalScreen_videoPlaybackStateDidChange

    Pause Video

    This function pauses the video currently being displayed on the external screen. Paused video can be resumed using the kp_ExternalScreen_resumeVideo(); call.

    Format 
    kp_ExternalScreen_pauseVideo();
    Triggers Nothing directly, but the change in playback state will trigger kp_ExternalScreen_videoPlaybackStateDidChange

    Resume Video

    This function resumes a video currently being paused on the external screen.

    Format 
    kp_ExternalScreen_resumeVideo();
    Triggers Nothing directly, but the change in playback state will trigger kp_ExternalScreen_videoPlaybackStateDidChange

    Skip to Timestamp

    This function moves the playhead of the video currently being displayed to a position x number of seconds from the start of the video.

    Format 
    kp_ExternalScreen_changeCurrentTimeOfVideo(timestamp);
    Parameters timestamp - [string] the number of seconds from the start of the video to move the playhead

    Check Current Playback State

    This function returns the current state of any video being displayed on the external screen, including playback state, file path, current time, duration, and whether the video is set to continuously loop.

    Format 
    kp_ExternalScreen_getCurrentVideoPlaybackState(callback);
    Parameters callback - [string] the name of the callback to be triggered after the function has been executed
    Callback format 
    callback(playbackState, filePath, currentTime, duration, isLooped);
    Callback return values
    • playbackState - [integer] indicating the state of playback. Possible values of:
      • -1 - video is loading (added in version 7.3)
      • 0 - video currently stopped
      • 1 - video currently playing
      • 2 - video currently paused
      • 3 - video currently interrupted
      • 4 - video currently seeking forward
      • 5 - video currently seeking backward
    • filePath - [string] the path and filename of the video file being shown
    • currentTime - [string] the current timestamp of the video file being shown
    • duration - [string] the total duration of the video file being shown
    • isLooped - [boolean integer] indicating whether the video is set to continuously loop. Possible values are:
      • 0 - video will only play once and will not loop
      • 1 - video will loop

    Notifications via API Callbacks

    When Video Playback State Changes

    This callback triggers each time the current video changes playback state.

    Format 
    kp_ExternalScreen_videoPlaybackStateDidChange(state, startPlayingHeadPosition, duration, filePath, isLooped);
    Return values
    • state - [integer] indicating the state of playback. Possible values of:
      • -1 - video is loading (added in version 7.3)
      • 0 - video currently stopped
      • 1 - video currently playing
      • 2 - video currently paused
      • 3 - video currently interrupted
      • 4 - video currently seeking forward
      • 5 - video currently seeking backward
    • startPlayingHeadPosition - [integer] representing the current position in the video playback head in seconds
    • duration - [string] the total duration of the video being shown
    • filepath - [string] the URL or filepath of the video being shown (added in version 9.4)
    • isLooped - [integer] indicating whether the video is set to continuously loop (added in version 9.4). Possible values are:
      • 0 - video will not loop
      • 1 - video will loop

    Deprecated

    Set New Fade

    [DEPRECATED IN VERSION 11.2 - see Set Video Options above] This function sets fade duration and the background color or image shown when video starts, completes playback, or is stopped through kp_ExternalScreen_stopVideoWithFading();. This background color or image is also shown if the video file is not proportioned to fit the screen dimensions.

    Format 
    kp_ExternalScreen_setPlayVideoParams(fadeDuration, fadeBgColor, callback);
    Parameters
    • fadeDuration - [string] the duration in seconds to fade in and out the video being shown on the external display. Note that the fade overlaps video playback so if you are using extended fade times, you may want to take that into account when formatting your video files
    • fadeBgColor - [string] the background color or image to be shown during fade animation or if the video file does not fill the external screen
      • R,G,B - [string] the background color, set in R,G,B format
      • image file - [string] the file path to the desired video file. If local, this path should be relative to the Kiosk Pro documents folder (rather than relative to the file calling the function). If remote, this should be the full URL
    • callback - [string] the name of the callback to be triggered after the function has been executed
    Callback format 
    callback(success);
    Callback return values
    • success - [integer] indicating whether fade options were successfully updated. Possible values are:
      • 0 - fade option update failed
      • 1 - new fade options set

    Check Current Fade

    [DEPRECATED IN VERSION 11.2 - see Get Video Options above] This function triggers a callback returning the current fade duration and the background color or image shown when video starts, completes playback, or is stopped through kp_ExternalScreen_stopVideoWithFading();.

    Format 
    kp_ExternalScreen_getPlayVideoParams(callback);
    Parameters
  • callback - [string] the name of the callback to be triggered after the function has been executed
    		•
    Callback format 
    callback(fadeDuration, fadeBgColor);
    Callback return values
    • fadeDuration - [string] the duration in seconds to fade in and out the video being shown on the external display. Note that the fade overlaps video playback so if you are using extended fade times, you may want to take that into account when formatting your video files
    • fadeBgColor - [string] the background color or image to be shown during fade animation or if the video file does not fill the external screen. Can be set as:
      • R,G,B - [string] the background color set in R,G,B format
      • image file - [string] the file path to the desired video file. If local, this path should be relative to the Kiosk Pro documents folder (rather than relative to the file calling the function). If remote, this should be the full URL

    Sample Code

    • This sample code relies on the JavaScript APIs built into Kiosk Pro and will not run successfully in other browsers or within our in-app help interface.
    • To run sample code, set the app's homepage to kioskgroup.com/external-screen-api
    • To download a .zip of sample code, click here.

    Change Log

    • Added in version 5.3. Major revision of underlying code base in version 7.3. Ability to stop video with fade added in version 7.4

    Related Articles

    Still stuck? How can we help? How can we help?