API: Play Video on External Screen

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

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.

Check Current Fade

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

Set New Fade

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

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

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

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