Display API: Video Playback

Functions

Callbacks

Related Settings

The External Screen API will work with video formats supported by iOS, specifically .mp4 files and .mov files encoded with the H264 codec. If your video files are in a different format, there are a number of free video converters online that you can use (like HandBrake, an open-source option we use in-house).

When working with video, we recommend storing files directly on the device whenever possible for the best performance and responsiveness. When using API calls, files on the device are referenced relative to Kiosk Pro's Documents folder.

Before calling any of the functions below, you must use the API to trigger a full-screen connection to the external display.

Requirements

  • Access JavaScript API
    • 'By Import' - recommended, works both online & offline, requires inclusion of kiosk_functions.js prior to any of the following calls.
    • 'By Injection' - only works offline, may not be available 'onload' event.
  • Screensaver
  • Connection to an External Display
    • iOS device must be connected to an external monitor, screen or projector via AirPlay or through Apple's Digital AV Adapter (which creates a wired connection betweeen an HDMI port on the external display and your device's 30-pin or Lightning port).

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 http://www.kioskproapp.com/external-screen

Download Sample Code


kp_ExternalScreen_setPlayVideoParams

This function sets fade duration and the background color or image shown during video fade in and fade out. 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 = 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 = background color or image to be shown during fade animation or if the video file does not fill the external screen.
    • R,G,B = background color, set as R,G,B: [0..255] (i.e. '255,0,0' = red).
    • image file = 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 = callback name as a string.
Callback format
callback(success);
		
Callback return values
  • success = integer variable which indicates parameters were successfully updated. If 0 - then the method failed, otherwise - success.

Status

You can also verify that parameters were successfully set by calling kp_ExternalScreen_getPlayVideoParams.


kp_ExternalScreen_getPlayVideoParams

This function triggers a callback returning current fade duration and the background color or image shown during video fade in and fade out.

Format
kp_ExternalScreen_getPlayVideoParams(callback);
		
Parameters callback = callback name as a string.
Callback format
callback(fadeDuration, fadeBgColor);
		
Callback return values
  • fadeDuration = 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 = 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 = background color set as R,G,B: [0..255] (i.e. '255,0,0' = red).
    • image file = 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.

kp_ExternalScreen_playVideo

This function plays a 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 = 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 variable representing whether the video should be looped. Possible values are:
    • 0 = video will be played one time.
    • 1 or other = video will repeat in a loop until a new request is made.
  • callback = callback name as a string.
Callback format
callback(isPlayingJobWasAccepted);
		
Callback return values
  • isPlayingJobWasAccepted = integer variable which indicates that the external display is linked and returned no errors when playback was requested. Possible values are:
    • 0 = video playback failed.
    • otherwise = external display is linked and returned no errors when playback was requested.

Status

Kiosk Pro will immediately call  kp_ExternalScreen_videoPlaybackStateDidChange and pass the current playback state of the video.


kp_ExternalScreen_stopVideo

This function stops the video currently being displayed on the external screen.

Format
kp_ExternalScreen_stopVideo();
		

Status

Kiosk Pro will immediately call kp_ExternalScreen_videoPlaybackStateDidChange and pass the current playback state of the video.


kp_ExternalScreen_stopVideoWithFading

Added in version 7.4

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

Format
kp_ExternalScreen_stopVideoWithFading();
		

Status

Kiosk Pro will immediately call kp_ExternalScreen_videoPlaybackStateDidChange and pass the current playback state of the video.


kp_ExternalScreen_pauseVideo

This function pauses the video currently being displayed on the external screen.

Format
kp_ExternalScreen_pauseVideo();
		

Status

Kiosk Pro will immediately call kp_ExternalScreen_videoPlaybackStateDidChange and pass the current playback state of the video.


kp_ExternalScreen_resumeVideo

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

Format
kp_ExternalScreen_resumeVideo();
		

Status

Kiosk Pro will immediately call kp_ExternalScreen_videoPlaybackStateDidChange and pass the current playback state of the video.


kp_ExternalScreen_changeCurrentTimeOfVideo

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 = number of seconds from the start of the video to move the playhead.

kp_ExternalScreen_getCurrentVideoPlaybackState

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 = callback name as a string.
Callback format
callback(playbackState, filePath, currentTime, duration, isLooped);
		
Callback return values
  • playbackState = an integer value indicating the state of playback with 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 = the path and filename of the video file being shown.
  • currentTime = the current timestamp of the video file being shown.
  • duration = the total duration of the video file being shown.
  • isLooped = 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.

kp_ExternalScreen_videoPlaybackStateDidChange

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

Format
kp_ExternalScreen_videoPlaybackStateDidChange(state, startPlayingHeadPosition, duration);
		
Return values
  • state = an integer value indicating the state of playback with 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 = an integer value indicating the current position in the video in seconds.
  • duration = the total duration of the video file being shown.

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