SoundJS v1.0.0 API Documentation : CordovaAudioPlugin (original) (raw)

Play sounds using Cordova Media plugin, which will work with a Cordova app and tools that utilize Cordova such as PhoneGap or Ionic. This plugin is not used by default, and must be registered manually in Soundusing the registerPlugins method. This plugin is recommended when building a Cordova based app, but is not required.

NOTE the Cordova Media plugin is required

    cordova plugin add org.apache.cordova.media

Known Issues

Audio Position

Audio position is calculated asynchronusly by Media. The SoundJS solution to this problem is two-fold:

• Provide getCurrentPosition that maps directly to media.getCurrentPosition.
• Provide a best guess position based on elapsed time since playback started, which is synchronized with actual position when the audio is paused or stopped. Testing showed this to be fairly reliable within 200ms.

Cordova Media Docs

• See the Cordova Media Docs for various known OS issues.

Constructor

• Index
• Methods
• Properties

Item Index

Methods

• _generateCapabilities static
• _handlePreloadComplete
• _handlePreloadError
• _updateVolume
• create
• getSrcDuration
• getVolume
• isPreloadComplete
• isPreloadStarted
• isSupported static
• preload
• register
• removeAllSounds
• removeSound
• setMute
• setVolume

Properties

• _audioSources
• _capabilities static
• _volume
• buildDate static
• playWhenScreenLocked static
• version static

Methods

_generateCapabilities

() private static

Determine the capabilities of the plugin. Used internally. Please see the Sound API capabilitiesmethod for an overview of plugin capabilities.

_handlePreloadComplete

protected

Handles internal preload completion.

_handlePreloadError

protected

Handles internal preload errors

_updateVolume

() protected

Set the gain value for master audio. Should not be called externally.

create

(

• src
• startTime
• duration

)

AbstractSoundInstance

Create a sound instance. If the sound has not been preloaded, it is internally preloaded here.

Parameters:

• src String
  The sound source to use.
• startTime Number
  Audio sprite property used to apply an offset, in milliseconds.
• duration Number
  Audio sprite property used to set the time the clip plays for, in milliseconds.

Returns:

getSrcDuration

Number

Get the duration for a src. Intended for internal use by CordovaAudioSoundInstance.

Returns:

Number:

The duration of the src or null if it does not exist

getVolume

() Number

Get the master volume of the plugin, which affects all SoundInstances.

Returns:

Number:

The volume level, between 0 and 1.

isPreloadComplete

Boolean

Checks if preloading has finished for a specific source.

Parameters:

• src String
  The sound URI to load.

Returns:

isPreloadStarted

Boolean

Checks if preloading has started for a specific source. If the source is found, we can assume it is loading, or has already finished loading.

Parameters:

• src String
  The sound URI to check.

Returns:

isSupported

() Boolean static

Determine if the plugin can be used in the current browser/OS. Note that HTML audio is available in most modern browsers, but is disabled in iOS because of its limitations.

Returns:

Boolean:

If the plugin can be initialized.

preload

Internally preload a sound.

Parameters:

• loader Loader
  The sound URI to load.

register

Object

Pre-register a sound for preloading and setup. This is called by Sound. Note all plugins provide a Loader instance, which PreloadJScan use to assist with preloading.

Parameters:

• loadItem String
  An Object containing the source of the audio Note that not every plugin will manage this value.

Returns:

Object:

A result object, containing a "tag" for preloading purposes.

removeAllSounds

Remove all sounds added using WebAudioPlugin/register. Note this does not cancel a preload.

Parameters:

• src String
  The sound URI to unload.

removeSound

Remove a sound added using WebAudioPlugin/register. Note this does not cancel a preload.

Parameters:

• src String
  The sound URI to unload.

setMute

Boolean

Mute all sounds via the plugin.

Parameters:

• value Boolean
  If all sound should be muted or not. Note that plugin-level muting just looks up the mute value of Sound muted, so this property is not used here.

Returns:

Boolean:

If the mute call succeeds.

setVolume

Boolean

Set the master volume of the plugin, which affects all SoundInstances.

Parameters:

• value Number
  The volume to set, between 0 and 1.

Returns:

Boolean:

If the plugin processes the setVolume call (true). The Sound class will affect all the instances manually otherwise.

Properties

_audioSources

Object protected

Object hash indexed by the source URI of each file to indicate if an audio source has begun loading, is currently loading, or has completed loading. Can be used to store non boolean data after loading is complete (for example arrayBuffers for web audio).

_capabilities

Object private static

The capabilities of the plugin. This is generated via the _generateCapabilitiesmethod. Please see the Sound capabilities method for an overview of all of the available properties.

_volume

Number protected

The internal master volume value of the plugin.

Default: 1

buildDate

String static

The build date for this release in UTC format.

playWhenScreenLocked

Boolean static

Sets a default playAudioWhenScreenIsLocked property for play calls on iOS devices. Individual SoundInstances can alter the default with CordovaAudioSoundInstance/playWhenScreenLocked.

version

String static

The version string for this release.