DISCONTINUATION OF PROJECT.
This project will no longer be maintained by Intel.
Intel has ceased development and contributions including, but not limited to, maintenance, bug fixes, new releases, or updates, to this project.
Intel no longer accepts patches to this project.
If you have an ongoing need to use this project, are interested in independently developing it, or would like to maintain patches for the open source software community, please create your own fork of this project. DISCONTINUATION OF PROJECT. This project will no longer be maintained by Intel. Intel will not provide or guarantee development of or support for this project, including but not limited to, maintenance, bug fixes, new releases or updates. Patches to this project are no longer accepted by Intel. In an effort to support the developer community, Intel has made this project available under the terms of the Apache License, Version 2. If you have an ongoing need to use this project, are interested in independently developing it, or would like to maintain patches for the community, please create your own fork of the project.
For playing audio files.
The player plugin is used to play media natively in applications. It is a useful alternative to the HTML5 <video> and <audio> tags.
- clearAudioCurrentTimeWatch — Stop an audio track watch.
- loadSound — Preload a sound file.
- playSound — Play a sound with no UI, events, or control.
- setAudioCurrentTime — Change the current play position in an audio file.
- setAudioVolume — Change the player volume for an audio file.
- startAudio — Play an audio file in the background.
- stopAudio — Stop playing an audio file.
- toggleAudio — Pause or restart an audio file.
- unloadAllSounds — Unload all sound files.
- unloadSound — Unload a sound file.
- watchAudioCurrentTime — Watch the time of the current audio file.
- audioInfo — Information about the currently playing audio file.
- intel.xdk.player.audio.currenttime.set — Execution of setAudioCurrentTime is complete.
- intel.xdk.player.audio.currenttime.set — Execution of setAudioVolume is complete.
- intel.xdk.player.audio.error — An error occurred when trying to play an audio file.
- intel.xdk.player.audio.start — An audio file has started playing.
- intel.xdk.player.audio.stop — An audio file has finished playing or been stopped.
- intel.xdk.player.sound.error — playSound was called with an invalid or missing file.
Stop a timer process that was started by a call to watchAudioCurrentTime.
intel.xdk.player.clearAudioCurrentTimeWatch(watchID);
- Apple iOS
- Google Android
watchID: The watch identifier that was returned by a call to watchAudioCurrentTime.
var watchID = intel.xdk.player.watchAudioCurrentTime(onSuccess, 3000);
// ... some time later ...
intel.xdk.player.clearAudioCurrentTimeWatch(watchID);
Preload a sound file.
intel.xdk.player.loadSound(soundURL, count);
This method preloads a sound file so that it can be played without a delay when it is needed. The sound file must be included within the application file folder. Valid audio formats depend on the device that the app is running on.
Call this method when the application is not busy with other processes. For
example, load sounds that will be needed at startup when the Cordova
deviceready
event fires. Then, while switching between levels of a game,
unload sounds that are no longer needed and load new sounds.
Once a sound has been loaded, it can be played by calling playSound.
- Apple iOS
- Google Android
- Microsoft Windows 8 - BETA
- Microsoft Windows Phone 8 - BETA
- soundURL: The URL of the sound file to play relative to the root folder of the application.
- count: The polyphonic count of the sound — that is, how many instances of the sound can be playing simultaneously. This parameter is optional, and defaults to 1.
- intel.xdk.player.sound.error: The file referenced by soundURL is invalid or missing.
intel.xdk.player.loadSound("sounds/boing.wav",5);
intel.xdk.player.loadSound("sounds/jump.wav");
function loadSoundError()
{
alert("Sound file could not be loaded");
}
document.addEventListener("intel.xdk.player.sound.error",loadSoundError,false);
Play a sound with no UI, events, or control.
intel.xdk.player.playSound(soundURL);
This method will start playing a sound with no user control, no program control, and no events. (Compare startAudio.) It is intended as a simple way to play sound effects in your application. The sound file must be included within the application file folder. Valid audio formats depend on the device that the app is running on.
If the sound has been preloaded with loadSound, it will start playing immediately; otherwise, there may be a delay while it is loaded.
A call to playSound will be ignored if the number of occurrences of the specified sound that are already being played is greater than or equal to its polyphonic count. If the sound was not preloaded, its polyphonic count is 1.
- Apple iOS
- Google Android
- Microsoft Windows 8 - BETA
- Microsoft Windows Phone 8 - BETA
- soundURL: The URL of the sound file to play relative to the root folder of the application.
- intel.xdk.player.sound.error: The file referenced by soundURL is invalid or missing.
// play the sound
intel.xdk.player.playSound("sounds/boing.wav");
Change the current play position in an audio file.
intel.xdk.player.setAudioCurrentTime(time);
This method causes the player to jump to the specified time in the currently playing audio file. If no audio file is currently playing, the effect of calling this method is undefined.
NOTE: This is an asynchronous operation. After a call to
setAudioCurrentTime
, watchAudioCurrentTime callbacks and the value of the player.audioInfo property are invalid until an audio.currenttime.set event occurs.
- Apple iOS
- Google Android
- Microsoft Windows 8 - BETA
- Microsoft Windows Phone 8 - BETA
- time: A floating point value that specifies the time in seconds where the player should continue or where new audio files should start playing.
- intel.xdk.player.audio.currenttime.set: The audio player has been restarted at the specified time. watchAudioCurrentTime callbacks and the player.audioInfo property are valid again.
// Set Audio to start at 30 seconds into the file
intel.xdk.player.startAudio("sounds/file1.mp3",false);
intel.xdk.player.setAudioCurrentTime(30);
Change the volume at which an audio file is played.
intel.xdk.player.setAudioVolume(volume);
This method causes the player volume to be changed.
- Apple iOS
- Google Android
- Microsoft Windows 8 - BETA
- Microsoft Windows Phone 8 - BETA
- volume: A floating point value between
0.0
(muted) and1.0
(maximum volume)..
- intel.xdk.player.audio.volume.set: The audio player volume has been changed.
// Set Audio to play at 75% volume.
intel.xdk.player.startAudio("sounds/file1.mp3",false);
intel.xdk.player.setAudioVolume(0.75);
Play an audio file in the background.
intel.xdk.player.startAudio(audioURL, looping);
This method will load and start playing a specified audio file without any UI, but with events and programmatic control. (Compare playSound.) It is useful for adding a response to an application event or for playing a background audio file while the user performs other actions.
If an audio file is already being played, then the current audio file will be stopped and the new one will be started.
- Apple iOS
- Google Android
- Microsoft Windows 8 - BETA
- Microsoft Windows Phone 8 - BETA
- audioURL: The URL of the audio file to play relative to the root folder of the application.
- looping:* A Boolean parameter specifying whether the audio should loop. Defaults to false.
- intel.xdk.player.audio.start: An audio file has started playing.
- intel.xdk.player.audio.stop: An audio file has finished playing or been stopped.
- intel.xdk.player.audio.error: An error occurred when trying to play an audio file.
// start playing an audio file without looping
intel.xdk.player.startAudio("sounds/cowbell.wav",false);
Stop playing an audio file.
intel.xdk.player.stopAudio();
This method will stop the playing og an audio file previously created by a call to startAudio. If no audio file is currently playing, then a call to this method will not have any effect.
- Apple iOS
- Google Android
- Microsoft Windows 8 - BETA
- Microsoft Windows Phone 8 - BETA
- intel.xdk.player.audio.stop: An audio file has finished playing or been stopped.
- intel.xdk.player.audio.error: An error occurred when trying to stop playing an audio file.
// stop playback of the audio
intel.xdk.player.stopAudio();
Pause or resume playing an audio file.
intel.xdk.player.toggleAudio();
- If an audio file is currently playing, it will be paused.
- If an audio file is currently paused, it will resume playing.
- If there is no current audio either playing or paused, then this method will not have any effect.
- Apple iOS
- Google Android
- Microsoft Windows 8 - BETA
- Microsoft Windows Phone 8 - BETA
// toggle playback of the audio
intel.xdk.player.toggleAudio();
Unload all sound files.
intel.xdk.player.unloadAllSounds();
This method unloads unload all sound files that have been loaded with the loadSound or playSound methods. Unloading sound files will free up application memory.
- Apple iOS
- Google Android
- Microsoft Windows 8 - BETA
- Microsoft Windows Phone 8 - BETA
intel.xdk.player.unloadAllSounds();
Unload a sound file.
intel.xdk.player.unloadSound(soundURL);
This method unloads a single a sound file. Unloading sound files will free up application memory.
- Apple iOS
- Google Android
- Microsoft Windows 8 - BETA
- Microsoft Windows Phone 8 - BETA
- soundURL: The URL of the sound file to be unloaded relative to the root folder of the application.
intel.xdk.player.unloadSound("sounds/boing.wav");
Start watching the time of the current audio file.
var watchID = intel.xdk.player.watchAudioCurrentTime(callback, interval);
This method starts regularly updating the plugin’s audioInfo property. It can optionally specify a callback to be called with the audioInfo property as an argument at each update.
To cancel the watch, call clearAudioCurrentTimeWatch with the identifier returned by this method.
- Apple iOS
- Google Android
- callback: A function that will be called at the specified time interval,
with the plugin’s audioInfo property as an argument. May be
nil
. - interval: The time interval in milliseconds at which to update the audioInfo property and call the callback function.
- A unique identifier that can be passed as an argument to clearAudioCurrentTimeWatch to cancel the watch.
function onSuccess(info) {
alert('Track Position: ' + info.currentTime + '\n' +
'Track Duration: ' + info.duration + '\n');
}
// start a watch on the current audio track
var watchID = intel.xdk.player.watchAudioCurrentTime(onSuccess, 3000);
An object with the following properties describing the currently playing audio file. This property is only defined if watchAudioCurrentTime has been called, in which case it is updated regularly at the interval specified in the call.
-
currentTime: The current offset (in seconds) from the beginning of the currently playing audio file. Note that this property will temporarily be invalid following a call to setAudioCurrentTime.
-
duration: The length (in seconds) of the currently playing audio file.
Execution of setAudioCurrentTime is complete.
This event is fired when execution of setAudioCurrentTime is complete. It signifies that the watchAudioCurrentTime callback and the audioInfo variable are again valid.
Execution of setAudioVolume is complete.
This event is fired when execution of setAudioVolume is complete
An error occurred when trying to play an audio file.
This event fires when there is an error in a call to startAudio.
An audio file has started playing.
This event is fired when the startAudio method successfully starts playing an audio file.
An audio file has finished playing or been stopped.
This event will fire when an audio file that was played by a call to startAudio stops playing because it has reached the end or stopAudio was called.
The file specified in the playSound command is invalid or missing.
This event fires if the file specified in a call to playSound is invalid or missing.