API: Play Audio through External Screen

Trigger and control audio playback through the speakers attached to 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 with speakers 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

Play Audio

This function plays a designated sound file asynchronously, starting at a specified point in the audio file with a specified volume, once or infinitely.

Format 
kp_AudioPlayer_play(filePath, atTime, withVolume, repeat);
Parameters
  • filePath - [string] file path to the desired audio 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
  • atTime - [float] the playback point in seconds within the timeline of the audio file
  • withVolume - [float] the playback gain for the audio player, ranging from 0.0 through 1.0
  • repeat - [integer] representing whether the audio file should be looped. Possible values are:
    • 0 - audio will be played one time
    • 1 - audio will repeat in a loop until a new request is made
Triggers

If successful, Kiosk Pro will call: kp_AudioPlayer_playbackDidChange with information about the current state of the player.

If an error occurs, the callback kp_AudioPlayer_playingDidFailWithError will be called with appropriate error code.

Stop Audio

This function finishes playback and clears the audio player.

The kp_AudioPlayer_stop method does not reset the value of the currentTime property to 0, but is not compatible with kp_AudioPlayer_resume as playback will not resume at the point where it left off. If you want to be able to resume audio at the same point, kp_AudioPlayer_pause is a better choice.

Format 
kp_AudioPlayer_stop();
Triggers After executing, Kiosk Pro will immediately call kp_AudioPlayer_playbackDidChange with information about the current state of the player.

Pause Audio

This function pauses playback of an audio file remaining ready to resume playback from where it left off through the call kp_AudioPlayer_resume.

Format 
kp_AudioPlayer_pause();
Triggers After executing, Kiosk Pro will immediately call kp_AudioPlayer_playbackDidChange with information about the current state of the player.

Resume Audio

This function which resumes playing audio asynchronously, starting at the current point in the timeline of the audio file currently associated with the audio player. This function can only run if an audio file has previously been initialized with kp_AudioPlayer_play and then paused with kp_AudioPlayer_pause.

Format 
kp_AudioPlayer_resume();
Triggers After executing, Kiosk Pro will immediately call kp_AudioPlayer_playbackDidChange with information about the current state of the player.

Change Volume

This function changes the playback gain for the audio player, ranging from 0.0 (minimum gain/volume) to 1.0 (maximum gain/volume).

Format 
kp_AudioPlayer_changeVolume(volume);
Parameters volume - {float] value from 0.0 (speaker muted) to 1.0 (maximum volume). If this value is less than 0, it will be converted to 0. If this value is greater than 1.0, it will be converted to 1.0
Triggers After executing, Kiosk Pro will immediately call kp_AudioPlayer_playbackDidChange with information about the current state of the player.

Skip to Timestamp

This function changes the playback point, in seconds, within the timeline of the audio file currently associated with the audio player. You can use this method to implement audio fast-forward and rewind functions if needed.

Format 
kp_AudioPlayer_changeCurrentTime(currentTime);
Parameters currentTime - [float] value from 0.0 to the audio file's duration in seconds. If this value is less than 0, it'll be converted to 0. If this value is greater than the audio file's duration, it'll be converted to the audio file's duration.
Triggers After executing, Kiosk Pro will immediately call kp_AudioPlayer_playbackDidChange with information about the current state of the player.

Notifications via API Callbacks

When Audio Playback State Changes

This callback returns information about the current instance of the audio player and is triggered after any change in playback state.

Format 
kp_AudioPlayer_playbackDidChange(playingState, currentTime, duration, volume);
Return values
  • playingState - [integer] representing the current playback state
    • 0 - playing
    • 1 - resumed
    • 2 - paused
    • 3 - stopped
    • 4 - finished
  • currentTime - [float] indicating the current playback point, in seconds, in the timeline of the audio file associated with the player. If a file is playing, currentTime is the current playback position, measured in seconds from the start of the audio file. If the file is not playing, currentTime is the point where playback starts upon calling the play or resume functions, again measured in seconds from the start of the audio file
  • duration - [float] indicating the total duration, in seconds, of the audio file associated with the audio player
  • volume - [float] indicating the playback gain for the audio player, ranging from 0.0 (minimum) through 1.0 (maximum)

When Audio Playback Fails

This callback is triggered if an error occurs after calling kp_AudioPlayer_play().

Format 
kp_AudioPlayer_playingDidFailWithError(errorDomain, errorCode);
Return values
  • errorDomain - [string] representing the error domain
  • errorCode - [integer] representing the error code

The error domain and error code are returned directly from the iOS/iPadOS operating system. While we do not have a full list of possible errors available, in testing we found that searching online is the fastest way to find more information about a specific error and to troubleshoot it.

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 initial version of Enterprise. Major revision of underlying code base in version 7.3.

Related Articles

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