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
- External Monitor Mode = Interactive or Standard Mirroring
- 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
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 |
|
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 |
|
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 |
|