Display API: Audio Playback

The Audio Player API pairs with Kiosk Pro's External Screen API to provide playback of audio content through speakers attached to an external display connected to your iOS device wirelessly 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).

Using this API, you can play audio from files located locally on the device or remotely on a server, loop audio files, control playback volume, and seek to a particular point in a sound file. The API also gives you basic audio controls, allowing you to play, pause/resume, or stop an audio player. It is designed to work together with the External Screen API, allowing you to play background audio while displaying separate image files, documents, and/or videos.

Kiosk Pro can play standard audio formats supported by iOS, which include .mp3, .aac, and .wav.

Functions

Callbacks

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_AudioPlayer_play

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 = 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.
  • atTime = the playback point in seconds (float value) within the timeline of the sound file.
  • withVolume = the playback gain for the audio player, ranging from 0.0 through 1.0.
  • repeat = integer variable representing whether the audio file should be looped. Possible values are:
    • 0 = audio will be played one time.
    • 1 or other = audio will repeat in a loop until a new request is made.

Status

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.

kp_AudioPlayer_stop

This function finishes playback and clears the audio player.

Format 
kp_AudioPlayer_stop();

Status

After executing, Kiosk Pro will immediately call kp_AudioPlayer_playbackDidChange with information about the current state of the player.

Discussion

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.

kp_AudioPlayer_pause

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();

Status

After executing, Kiosk Pro will immediately call kp_AudioPlayer_playbackDidChange with information about the current state of the player.

kp_AudioPlayer_resume

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();

Status

After executing, Kiosk Pro will immediately call kp_AudioPlayer_playbackDidChange with information about the current state of the player.

kp_AudioPlayer_changeVolume

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 to 1.0. 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.

Status

After executing, Kiosk Pro will immediately call kp_AudioPlayer_playbackDidChange with information about the current state of the player.

kp_AudioPlayer_changeCurrentTime

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.

Status

After executing, Kiosk Pro will immediately call kp_AudioPlayer_playbackDidChange with information about the current state of the player.

kp_AudioPlayer_playingDidFailWithError

This callback is triggered if an error occurs during calling kp_AudioPlayer_play(filePath, atTime, withVolume, repeat).

Format 
kp_AudioPlayer_playingDidFailWithError(errorDomain, errorCode);
Return values
  • errorDomain = a string containing the error domain.
  • errorCode = an integer containing the error code.

Discussion

The error domain and error code is returned directly from iOS; 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.

kp_AudioPlayer_playbackDidChange

This callback returns information about the current instance of the audio player, which is triggered after any functions which change playback state.

Format 
kp_AudioPlayer_playbackDidChange(playingState, currentTime, duration, volume);
Return values
  • playingState = a string containing the error domain.
    • 0 = playing
    • 1 = resumed
    • 2 = paused
    • 3 = stopped
    • 4 = finished
  • currentTime = a 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 = a float value indicating the total duration, in seconds, of the audio file associated with the audio player.
  • volume = a float value indicating the playback gain for the audio player, ranging from 0.0 (minimum) through 1.0 (maximum).

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