CrossBrowdy API documentation

Class: CB_AudioFileSprites

CB_AudioFileSprites

Class to manage audio sprites of a CB_AudioFileCache object (used internally).

new CB_AudioFileSprites( [dataObject]) → {CB_AudioFileSprites}

The constructor is recommended to be called through a user-driven event (as onClick, onTouch, etc.), as some clients may need this at least the first time in order to be able to play the audio.

Parameters:
Name Type Argument Description
dataObject CB_AudioFileSprites.DATA_OBJECT <optional>

Object with the desired data and options for the audio sprites. Although it can contain a "sprites" property, it will also be used as the first and unique parameter when calling the constructor of the CB_AudioFileCache object internally.
Source:
To Do:
  • Do not allow to create one object with an "id" which has already been used (unless the value is undefined, null...).
  • Think about using wrapper to replace "this" in callbacks (callbackOk, callbackError) to point to the CB_AudioFileSprites object itself.
  • Method getCopy and static method filterProperties (similar to the ones from CB_GraphicSprites and CB_GraphicSpritesScene).
Returns:

Returns a new CB_AudioFileSprites object.

Type
CB_AudioFileSprites

Members

<readonly> audioFileCache :CB_AudioFileCache

Contains the CB_AudioFileCache object. Internal usage only recommended.

Type:
Source:

<readonly> id :string

Stores the identifier for the audio file sprites object.

Type:
  • string
Source:

<readonly> spriteSoundInstances :Object

Object whose property names are the sprite identifiers (strings), including one called "_WITHOUT_SPRITE_ASSOCIATED" for sound instances without a sprite associated, and their values are an array containing the sound instance identifiers (created by the CB_AudioFileSprites#play method). Internal usage only recommended.

Type:
  • Object
Default Value:
  • { "_WITHOUT_SPRITE_ASSOCIATED" : [] }
Source:

<readonly> sprites :CB_AudioFileSprites.SPRITES_OBJECT

Object with information about the sprites.

Type:
Default Value:
  • {}
Source:

Methods

cancelSoundInstance(soundInstanceId [, cancel] [, affectWithObjectAssociated]) → {boolean}

Cancels (to prevent it starts playing) or enables a sound instance (created by the CB_AudioFileCache#play method), by its identifier. Uses the CB_AudioFileCache#cancelSoundInstance method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
soundInstanceId integer

Used as the "soundInstanceId" parameter when calling the CB_AudioFileCache#cancelSoundInstance method internally.
cancel boolean <optional>
 false

Used as the "cancel" parameter when calling the CB_AudioFileCache#cancelSoundInstance method internally.
affectWithObjectAssociated boolean <optional>
 false

Used as the "affectWithObjectAssociated" parameter when calling the CB_AudioFileCache#cancelSoundInstance method internally.
Source:
Returns:

Returns true if the sound instance has been modified or false otherwise.

Type
boolean

cancelSoundInstances( [cancel] [, affectWithObjectAssociated]) → {integer}

Cancels (to prevent they start playing) or enables all sound instances (created by the CB_AudioFileCache#play method). Uses the CB_AudioFileCache#cancelSoundInstances method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
cancel boolean <optional>
 false

Used as the "cancel" parameter when calling the CB_AudioFileCache#cancelSoundInstances method internally.
affectWithObjectAssociated boolean <optional>
 false

Used as the "affectWithObjectAssociated" parameter when calling the CB_AudioFileCache#cancelSoundInstances method internally.
Source:
Returns:

Returns the number of sound instances modified.

Type
integer

checkPlayingAll( [callbackOk] [, callbackError] [, ignoreQueue]) → {integer}

Checks whether each CB_AudioFile object whose CB_AudioFile#getStatus method returns the "unchecked" value (which belongs to the value of the CB_AudioFile#UNCHECKED property) can be played or not. After checking, if the audio can be played, the status of the CB_AudioFile object will get the value of CB_AudioFile.LOADED. Otherwise, if it cannot be played, the status of the CB_AudioFile object will get the value of CB_AudioFile.FAILED. If a CB_AudioFile object cannot be played and it is determined necessary, it will try to reload it internally (by calling the CB_AudioFileCache#removeAudioFile method). It will call the CB_AudioFileCache#clearAudioFiles method internally after finishing. Uses the CB_AudioFileCache#checkPlayingAll method internally and returns its returning value. Recommended to be called through a user-driven event (as onClick, onTouch, etc.).

Parameters:
Name Type Argument Default Description
callbackOk CB_AudioFileCache.checkPlayingAll_CALLBACK_OK <optional>

Used as the "callbackOk" parameter when calling the CB_AudioFileCache#checkPlayingAll method internally.
callbackError CB_AudioFileCache.checkPlayingAll_CALLBACK_ERROR <optional>

Used as the "callbackError" parameter when calling the CB_AudioFileCache#checkPlayingAll method internally.
ignoreQueue boolean <optional>
 false

Used as the "ignoreQueue" parameter when calling the CB_AudioFileCache#checkPlayingAll method internally.
Source:
Returns:

Returns the number of CB_AudioFile objects whose status belonged to the "unchecked" value (the value of the CB_AudioFile#UNCHECKED property) before the execution of this method. It will return 0 (zero) if the method is tried to be executed while there is another previous call of it still running. It will also return 0 (zero) if the status of the audio file cache is not loaded (the CB_AudioFileCache#status property does not belong to the value set in the CB_AudioFileCache.LOADED property).

Type
integer

clearAudioFiles( [avoidCallingCheckCacheLoaded]) → {array}

Cleans the array of the CB_AudioFile objects (taking off the undefined or null ones) which is in the CB_AudioFileCache#audioFiles property, just keeping the valid ones and clearing (destroying and removing) the others. For performance purposes. Uses the CB_AudioFileCache#clearAudioFiles method internally and returns its returning value. Internal usage only recommended.

Parameters:
Name Type Argument Default Description
avoidCallingCheckCacheLoaded boolean <optional>
 false

Used as the "avoidCallingCheckCacheLoaded" parameter when calling the CB_AudioFileCache#clearAudioFiles method internally.
Source:
Returns:

Returns the value of the CB_AudioFileCache#audioFiles property.

Type
array

clearSoundInstances( [clearWithObjectAssociated]) → {integer}

Clears the sound instances (created by the CB_AudioFileCache#play method) which have been cancelled. Uses the CB_AudioFileCache#clearSoundInstances method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
clearWithObjectAssociated boolean <optional>
 false

Used as the "clearWithObjectAssociated" parameter when calling the CB_AudioFileCache#clearSoundInstances method internally.
Source:
Returns:

Returns the number of cleared sound instances.

Type
integer

createAudioFile( [URIs] [, preferredAPIs] [, preferredFormats] [, audioObject] [, callbackOk] [, callbackError] [, storeURIsList] [, checkAutomatically]) → {CB_AudioFile|null}

Creates one internal CB_AudioFile object (inside the CB_AudioFileCache#audioFiles property). Recommended to be called through a user-driven event (as onClick, onTouch, etc.), as some clients may need this at least the first time in order to be able to play the audio. Uses the CB_AudioFileCache#createAudioFile method internally and returns its returning value. Internal usage only recommended.

Parameters:
Name Type Argument Default Description
URIs CB_AudioFileCache.URIS_OBJECT <optional>
 CB_AudioFileCache#URIs

Used as the "URIs" parameter when calling the CB_AudioFileCache#createAudioFile method internally.
preferredAPIs array <optional>
 CB_AudioFileCache#preferredAPIs

Used as the "preferredAPIs" parameter when calling the CB_AudioFileCache#createAudioFile method internally.
preferredFormats array <optional>
 CB_AudioFileCache#preferredFormats

Used as the "preferredFormats" parameter when calling the CB_AudioFileCache#createAudioFile method internally.
audioObject CB_AudioFile <optional>

Used as the "audioObject" parameter when calling the CB_AudioFileCache#createAudioFile method internally.
callbackOk function <optional>

Used as the "callbackOk" parameter when calling the CB_AudioFileCache#createAudioFile method internally.
callbackError function <optional>

Used as the "callbackError" parameter when calling the CB_AudioFileCache#createAudioFile method internally.
storeURIsList boolean <optional>
 false

Used as the "storeURIsList" parameter when calling the CB_AudioFileCache#createAudioFile method internally.
checkAutomatically boolean <optional>
 false

Used as the "checkAutomatically" parameter when calling the CB_AudioFileCache#createAudioFile method internally.
Source:
Returns:

If it fails, it returns null. Otherwise, returns the CB_AudioFile that has been created or reused.

Type
CB_AudioFile | null

createAudioFiles(minimumAudioFiles) → {integer}

Creates the desired number of internal CB_AudioFile objects (inside the CB_AudioFileCache#audioFiles property). Recommended to be called through a user-driven event (as onClick, onTouch, etc.), as some clients may need this at least the first time in order to be able to play the audio. Uses the CB_AudioFileCache#createAudioFiles method internally and returns its returning value.

Parameters:
Name Type Description
minimumAudioFiles integer

Used as the "minimumAudioFiles" parameter when calling the CB_AudioFileCache#createAudioFiles method internally.
Source:
Returns:

Returns the number of CB_AudioFile objects which are intended to be created (they could fail).

Type
integer

destroyAll( [stopSounds]) → {integer}

Destroys all the CB_AudioFile objects and frees memory, by calling CB_AudioFile#destructor(stopSounds, false, true). Uses the CB_AudioFileCache#destroyAll method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
stopSounds boolean <optional>
 false

Used as the "stopSounds" parameter when calling the CB_AudioFileCache#destroyAll method internally.
Source:
Returns:

Returns the number of CB_AudioFile objects whose CB_AudioFile#destructor has been called.

Type
integer

destructor( [stopSounds] [, preventAbortedStatus])

Destroys the audio file sprites object (removing all sprites, etc.), including the internal audio file cache object, and frees memory. By default, unless the "preventAbortedStatus" is set to true, sets the current status of the CB_AudioFileCache object as ABORTED (CB_AudioFileCache.ABORTED value).

Parameters:
Name Type Argument Default Description
stopSounds boolean <optional>
 false

Used as the "stopSounds" parameter when calling internally the CB_AudioFileCache#destructor method of the CB_AudioFileCache object.
preventAbortedStatus boolean <optional>
 false

If set to true (not recommended), it will not assign the status of "ABORTED" (it will not assign the value of CB_AudioFileCache.ABORTED to the CB_AudioFileCache#status property).
Source:

executeAll()

Alias for CB_AudioFileSprites#executeFunctionAll.

Source:
See:

executeAllSprite()

Alias for CB_AudioFileSprites#executeFunctionAllSprite.

Source:
See:

executeAllSprites()

Alias for CB_AudioFileSprites#executeFunctionAllSprites.

Source:
See:

executeFunctionAll(functionEach [, delayBetweenEach] [, audioFiles] [, returnSetTimeoutsArray] [, delayBetweenEachAffectsFirst] [, functionFinish]) → {integer|array}

Performs a desired action, using the provided function, on all the existing CB_AudioFile objects or on the desired ones (if provided). Uses the CB_AudioFileCache#executeFunctionAll method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
functionEach CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK

Used as the "functionEach" parameter when calling the CB_AudioFileSprites#executeFunctionAll method internally.
delayBetweenEach number | CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK <optional>
 0

Used as the "delayBetweenEach" parameter when calling the CB_AudioFileCache#executeFunctionAll method internally.
audioFiles array <optional>
 CB_AudioFileCache#audioFiles

Used as the "audioFiles" parameter when calling the CB_AudioFileCache#executeFunctionAll method internally.
returnSetTimeoutsArray boolean <optional>
 false

Used as the "returnSetTimeoutsArray" parameter when calling the CB_AudioFileCache#executeFunctionAll method internally.
delayBetweenEachAffectsFirst boolean <optional>
 false

Used as the "delayBetweenEachAffectsFirst" parameter when calling the CB_AudioFileCache#executeFunctionAll method internally.
functionFinish CB_Arrays.executeFunctionAll_ON_FINISH_CALLBACK <optional>

Function that will be called for when it has finished looping all the items. The first parameter will be the array which was looped, the second parameter will be the number of times that the "functionEach" callback was called (the most likely, matches the number of elements unless they are undefined or null), and the third parameter will be the maximum "delay" used, being "this" the array itself.
Source:
Returns:

If the "returnSetTimeoutsArray" parameter is set to false, it will return the number of calls to the "functionEach" function that were performed (which should be the same number as the CB_AudioFile objects given in the "audioFiles" parameter). Otherwise, if the "returnSetTimeoutsArray" is set to true, it will return a numeric array with a CB_AudioFileCache.executeFunctionAll_OBJECT object for each CB_AudioFile given. The length of this array will also be the number of calls to the "functionEach" function that were performed. Note that if a value greater than 0 (zero) for the "delayBetweenEach" parameter has been provided, perhaps not all calls of the "functionEach" function will have been performed yet when exiting this method because of the asynchronous nature of the setTimeout function.

Type
integer | array

executeFunctionAllSprite(spriteId, functionEach [, delayBetweenEach] [, avoidCancelled] [, returnSetTimeoutsArray] [, delayBetweenEachAffectsFirst] [, functionFinish]) → {integer|array}

Executes a desired function for all the CB_AudioFile objects used by the sound instances currently created that belong to a given sprite (by its ID). It calls the CB_AudioFileSprites#executeFunctionAll method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
spriteId string

The identifier for the sprite.
functionEach CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK

Used as the "functionEach" parameter when calling the CB_AudioFileSprites#executeFunctionAll method internally.
delayBetweenEach number | CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK <optional>
 0

Used as the "delayBetweenEach" parameter when calling the CB_AudioFileSprites#executeFunctionAll method internally.
avoidCancelled boolean <optional>
 false

If set to true, it will not affect the CB_AudioFile objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling the CB_AudioFileSprites#getAudioFilesUsedBySpriteId method internally.
returnSetTimeoutsArray boolean <optional>
 false

Used as the "returnSetTimeoutsArray" parameter when calling the CB_AudioFileSprites#executeFunctionAll method internally.
delayBetweenEachAffectsFirst boolean <optional>
 false

Used as the "delayBetweenEachAffectsFirst" parameter when calling the CB_AudioFileSprites#executeFunctionAll method internally.
functionFinish CB_Arrays.executeFunctionAll_ON_FINISH_CALLBACK <optional>

Function that will be called for when it has finished looping all the items. The first parameter will be the array which was looped, the second parameter will be the number of times that the "functionEach" callback was called (the most likely, matches the number of elements unless they are undefined or null), and the third parameter will be the maximum "delay" used, being "this" the array itself.
Source:
Returns:

If the "returnSetTimeoutsArray" parameter is set to false, it will return the number of calls to the "functionEach" function that were performed (which should be the same number as the CB_AudioFile objects used by the sound instances that belong to the given sprite identifier). Otherwise, if the "returnSetTimeoutsArray" is set to true, it will return a numeric array with a CB_AudioFileCache.executeFunctionAll_OBJECT object for each CB_AudioFile given. The length of this array will also be the number of calls to the "functionEach" function that were performed. Note that if a value greater than 0 (zero) for the "delayBetweenEach" parameter has been provided, perhaps not all calls of the "functionEach" function will have been performed yet when exiting this method because of the asynchronous nature of the setTimeout function.

Type
integer | array

executeFunctionAllSprites(functionEach [, delayBetweenEach] [, includeWithoutSpriteAssociated] [, avoidCancelled] [, returnSetTimeoutsArray] [, delayBetweenEachAffectsFirst] [, functionFinish]) → {integer|array}

Executes a desired function for all the CB_AudioFile objects used by all the sound instances currently created. It calls the CB_AudioFileSprites#executeFunctionAll method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
functionEach CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK

Used as the "functionEach" parameter when calling the CB_AudioFileSprites#executeFunctionAll method internally.
delayBetweenEach number | CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK <optional>
 0

Used as the "delayBetweenEach" parameter when calling the CB_AudioFileSprites#executeFunctionAll method internally.
includeWithoutSpriteAssociated boolean <optional>
 false

If set to true, it will also affect the CB_AudioFile objects whose sound instance ID is not associated to any sprite. Used as the "includeWithoutSpriteAssociated" parameter when calling the CB_AudioFileSprites#getAudioFilesUsed method internally.
avoidCancelled boolean <optional>
 false

If set to true, it will not affect the CB_AudioFile objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling the CB_AudioFileSprites#getAudioFilesUsed method internally.
returnSetTimeoutsArray boolean <optional>
 false

Used as the "returnSetTimeoutsArray" parameter when calling the CB_AudioFileSprites#executeFunctionAll method internally.
delayBetweenEachAffectsFirst boolean <optional>
 false

Used as the "delayBetweenEachAffectsFirst" parameter when calling the CB_AudioFileSprites#executeFunctionAll method internally.
functionFinish CB_Arrays.executeFunctionAll_ON_FINISH_CALLBACK <optional>

Function that will be called for when it has finished looping all the items. The first parameter will be the array which was looped, the second parameter will be the number of times that the "functionEach" callback was called (the most likely, matches the number of elements unless they are undefined or null), and the third parameter will be the maximum "delay" used, being "this" the array itself.
Source:
Returns:

If the "returnSetTimeoutsArray" parameter is set to false, it will return the number of calls to the "functionEach" function that were performed (which should be the same number as the CB_AudioFile objects used by the sound instances that belong to the sprites). Otherwise, if the "returnSetTimeoutsArray" is set to true, it will return a numeric array with a CB_AudioFileCache.executeFunctionAll_OBJECT object for each CB_AudioFile given. The length of this array will also be the number of calls to the "functionEach" function that were performed. Note that if a value greater than 0 (zero) for the "delayBetweenEach" parameter has been provided, perhaps not all calls of the "functionEach" function will have been performed yet when exiting this method because of the asynchronous nature of the setTimeout function.

Type
integer | array

forEach()

Alias for CB_AudioFileSprites#executeFunctionAll.

Source:
See:

forEachSprite()

Alias for CB_AudioFileSprites#executeFunctionAllSprites.

Source:
See:

forEachSpriteById()

Alias for CB_AudioFileSprites#executeFunctionAllSprite.

Source:
See:

getAudioFileBySoundInstanceId(soundInstanceId [, avoidCancelled]) → {CB_AudioFile|null}

Gets the CB_AudioFile object associated to a given sound instance ID (created by the CB_AudioFileCache#play method), if any, or null otherwise. Uses the CB_AudioFileCache#getAudioFileBySoundInstanceId method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
soundInstanceId integer

Used as the "soundInstanceId" parameter when calling the CB_AudioFileCache#getAudioFileBySoundInstanceId method internally.
avoidCancelled boolean <optional>
 false

Used as the "avoidCancelled" parameter when calling the CB_AudioFileCache#getAudioFileBySoundInstanceId method internally.
Source:
Returns:

Returns the CB_AudioFile object associated to a given sound instance ID, if any, or null otherwise.

Type
CB_AudioFile | null

getAudioFiles( [copy]) → {array}

Gets an array with all the CB_AudioFile objects. Uses the CB_AudioFileCache#getAudioFiles method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
copy boolean <optional>
 false

Used as the "copy" parameter when calling the CB_AudioFileCache#getAudioFiles method internally.
Source:
Returns:

Returns an array with all the CB_AudioFile objects.

Type
array

getAudioFilesBusy() → {array}

Gets an array with the busy CB_AudioFile objects (the objects which are not available and ready to use). Uses the CB_AudioFileCache#getAudioFilesBusy method internally and returns its returning value.

Source:
Returns:

Returns an array with the busy CB_AudioFile objects (the objects which are not available and ready to use).

Type
array

getAudioFilesFree() → {array}

Gets an array with the free CB_AudioFile objects (the objects which are available and ready to use). Uses the CB_AudioFileCache#getAudioFilesFree method internally and returns its returning value.

Source:
Returns:

Returns an array with the free CB_AudioFile objects (the objects which are available and ready to use).

Type
array

getAudioFilesFreeNumber() → {integer}

Tells the current number of free CB_AudioFile objects (the number of objects which are available and ready to use). Uses the CB_AudioFileCache#getAudioFilesFreeNumber method internally and returns its returning value.

Source:
Returns:

Returns the current number of free CB_AudioFile objects (the number of objects which are available and ready to use).

Type
integer

getAudioFilesNumber( [real]) → {integer}

Tells the number of CB_AudioFile objects created. Uses the CB_AudioFileCache#getAudioFilesNumber method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
real boolean <optional>
 false

Used as the "real" parameter when calling the CB_AudioFileCache#getAudioFilesNumber method internally.
Source:
Returns:

Returns the number of CB_AudioFile objects created.

Type
integer

getAudioFilesUsed( [oneDimension] [, includeWithoutSpriteAssociated] [, avoidCancelled]) → {CB_AudioFileSprites.getAudioFilesUsed_OBJECT|array}

Returns the CB_AudioFile objects used by all the sounds instances currently created.

Parameters:
Name Type Argument Default Description
oneDimension boolean <optional>
 false

If set to false, it will return an object whose property names are the sprite identifiers (including the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated, if the "includeWithoutSpriteAssociated" is set to true) and their value will be a numeric array with the CB_AudioFile objects used. Otherwise, if set to true, it will return a numeric array with the CB_AudioFile objects used (if the "includeWithoutSpriteAssociated" parameter is set to true, it will also contain the CB_AudioFile objects whose sound instance ID is not associated to any sprite).
includeWithoutSpriteAssociated boolean <optional>
 false

If set to true, it will also return the CB_AudioFile objects whose sound instance ID is not associated to any sprite. Used as the "includeWithoutSpriteAssociated" parameter when calling the CB_AudioFileSprites#getSprites method internally.
avoidCancelled boolean <optional>
 false

If set to true, it will not return the CB_AudioFile objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling the CB_AudioFileSprites#getAudioFilesUsedBySpriteId method internally.
Source:
Returns:

Returns the CB_AudioFile objects used by all the sounds instances currently created. If the "oneDimension" parameter is set to false, it will return a CB_AudioFileSprites.getAudioFilesUsed_OBJECT object whose property names are the sprite identifiers (including the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated, if the "includeWithoutSpriteAssociated" is set to true) and their value will be a numeric array with the CB_AudioFile objects used. Otherwise, if the "oneDimension" parameter set to true, it will return a numeric array with the CB_AudioFile objects used (if the "includeWithoutSpriteAssociated" parameter is set to true, it will also contain the CB_AudioFile objects whose sound instance ID is not associated to any sprite).

Type
CB_AudioFileSprites.getAudioFilesUsed_OBJECT | array

getAudioFilesUsedBySpriteId(spriteId [, avoidCancelled]) → {array}

Returns an array of the CB_AudioFile objects used by the sound instances that belong to a given sprite identifier.

Parameters:
Name Type Argument Default Description
spriteId string

The identifier for the sprite.
avoidCancelled boolean <optional>
 false

If set to true, it will not return the CB_AudioFile objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling the CB_AudioFileSprites#getAudioFileBySoundInstanceId method internally.
Source:
Returns:

Returns an array of the CB_AudioFile objects used by the sound instances that belong to the given sprite identifier.

Type
array

getDuration( [maximum]) → {number}

Tells the duration (minimum or maximum) of the sound stored (in milliseconds). Although the audio file cache should always be used to cache the same sound only, the duration might not always be the same due the usage of different formats, file paths, etc. So this method returns either the minimum or the maximum duration found among all the CB_AudioFile objects. Uses the CB_AudioFileCache#getDuration method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
maximum boolean <optional>
 false

Used as the "maximum" parameter when calling the CB_AudioFileCache#getDuration method internally.
Source:
Returns:

Returns the duration (minimum or maximum) of the sound stored (in milliseconds). Although the audio file cache should always be used to cache the same sound only, the duration might not always be the same due the usage of different formats, file paths, etc. So this method returns either the minimum or the maximum duration found among all the CB_AudioFile objects.

Type
number

getFreeAudioFile( [popIt]) → {CB_AudioFileCache.getFreeAudioFile_OBJECT}

Returns a free CB_AudioFile object, if any (from the CB_AudioFileCache#audioFilesFree property). Note that this will call the internal CB_AudioFileCache#_createNewAudioFilesIfNeeded method that could end creating a new CB_AudioFile object if needed. Uses the CB_AudioFileCache#getFreeAudioFile method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
popIt boolean <optional>
 false

Used as the "popIt" parameter when calling the CB_AudioFileCache#getFreeAudioFile method internally.
Source:
Returns:

Returns a CB_AudioFileCache.getFreeAudioFile_OBJECT object.

Type
CB_AudioFileCache.getFreeAudioFile_OBJECT

getProgress( [countLoadedObjects] [, alsoUncheckedAndCheckingObjects]) → {number}

Returns a number representing the percentage of the loading progress for the audio file sprites object (from 0 to 100, being 100 a complete loading progress). The way to calculate it internally may differ from one audio API to another and it is not totally reliable. Uses the CB_AudioFileCache#getProgress method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
countLoadedObjects boolean <optional>
 false

Used as the "countLoadedObjects" parameter when calling the CB_AudioFileCache#getProgress method internally.
alsoUncheckedAndCheckingObjects boolean <optional>
 false

Used as the "alsoUncheckedAndCheckingObjects" parameter when calling the CB_AudioFileCache#getProgress method internally.
Source:
Returns:

Returns a number representing the percentage of the loading progress for the audio file sprites object (from 0 to 100, being 100 a complete loading progress). The way to calculate it internally may differ from one audio API to another and it is not totally reliable.

Type
number

getSoundInstancesId( [oneDimension] [, includeWithoutSpriteAssociated]) → {Object|array}

Returns the sound instances (their ID) used (stored in the CB_AudioFileSprites#spriteSoundInstances property).

Parameters:
Name Type Argument Default Description
oneDimension boolean <optional>
 false

If set to true, it will return the CB_AudioFileSprites#spriteSoundInstances property directly (which includes the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated). Otherwise, if it is set to true, it will return a numeric array whose values are the sound instance IDs.
includeWithoutSpriteAssociated boolean <optional>
 false

If set to true, it will also return the sound instance identifiers which are not associated to any sprite. Used as the "includeWithoutSpriteAssociated" parameter when calling the CB_AudioFileSprites#getSprites method internally. Only used when the "oneDimension" parameter is set to true.
Source:
Returns:

Returns the sound instances (their ID) used (stored in the CB_AudioFileSprites#spriteSoundInstances property). If the "oneDimension" parameter is set to false, the property names of the returning object are the sprite identifiers (strings), including one called "_WITHOUT_SPRITE_ASSOCIATED" for sound instances without a sprite associated, and their values are an array containing the sound instance IDs. If the "oneDimension" parameter is set to true, it will return a numeric array whose values are the sound instance identifiers (if the "includeWithoutSpriteAssociated" parameter it set to true, it will also include the sound instances which are not associated to any sprite).

Type
Object | array

getSoundInstancesIdBySpriteId(spriteId) → {array}

Returns an array of the sound instance identifiers (created by the CB_AudioFileSprites#play method) used by the given sprite identifier.

Parameters:
Name Type Description
spriteId string

The identifier for the sprite.
Source:
Returns:

Returns a numeric array of the sound instances (created by the CB_AudioFileSprites#play method) used by the given sprite identifier.

Type
array

getSprite(spriteId) → {CB_AudioFileSprites.SPRITE_OBJECT}

Returns a sprite by its ID.

Parameters:
Name Type Description
spriteId string

The identifier for the sprite.
Source:
Returns:

Returns the desired sprite or a fake object if it was not found. The fake object will be this one: { "startAt" : 0, "stopAt" : null, "fake" : true }.

Type
CB_AudioFileSprites.SPRITE_OBJECT

getSprites( [includeWithoutSpriteAssociated]) → {CB_AudioFileSprites.SPRITES_OBJECT}

Returns an object with the sprites (and includes "_WITHOUT_SPRITE_ASSOCIATED" if we want to).

Parameters:
Name Type Argument Default Description
includeWithoutSpriteAssociated boolean <optional>
 false

If set to true, the returning object will also contain a property called "_WITHOUT_SPRITE_ASSOCIATED" whose value will be an empty object (unless the property existed before in the object stored in the CB_AudioFileSprites#sprites property and had a value which is not an empty object). If set to false, the returning object will not contain the "_WITHOUT_SPRITE_ASSOCIATED" property unless the property existed before in the object stored in the CB_AudioFileSprites#sprites property.
Source:
Returns:

Returns an object with the sprites (and includes "_WITHOUT_SPRITE_ASSOCIATED" if we want to).

Type
CB_AudioFileSprites.SPRITES_OBJECT

getStatus() → {number}

Gets the current status of the audio file sprites object. Uses the CB_AudioFileCache#getStatus method internally and returns its returning value.

Source:
Returns:

Returns the current status of the audio file sprites object. It is a number, which should match the value of the CB_AudioFileCache.UNLOADED (still unloaded), CB_AudioFileCache.LOADING (loading), CB_AudioFileCache.UNCHECKED (not checked by calling the CB_AudioFileCache#checkPlayingAll method yet), CB_AudioFileCache.CHECKING (being checked by the CB_AudioFileCache#checkPlayingAll method), CB_AudioFileCache.LOADED (loaded), CB_AudioFileCache.FAILED (failed loading or failed to play or by any other reason) or CB_AudioFileCache.ABORTED (aborted because it was destroyed with the "destructor" method) property.

Type
number

getStatusString() → {string}

Gets the current status of the audio file sprites, as a string. Uses the CB_AudioFileCache#getStatusString method internally and returns its returning value.

Source:
Returns:

Returns the current status of the audio file sprites, as a string. Possible return values are "UNLOADED", "LOADING", "UNCHECKED", "CHECKING", "LOADED", "FAILED", "ABORTED" or "UNKNOWN (UNKNOWN_STATUS)" (where "UNKNOWN_STATUS" will be a value from the CB_AudioFileCache#status property not recognized as any possible status).

Type
string

insertSprite(sprite, spriteId) → {boolean}

Inserts the given sprite. It will keep the existing ones. If a sprite identifier already existed and it is given again (not recommended), it will be replaced by the new one (but keeping its current sound instances, if any).

Parameters:
Name Type Description
sprite CB_AudioFileSprites.SPRITE_OBJECT

Object with the desired sprite.
spriteId string

The identifier for the sprite.
Source:
Returns:

Returns true if the sprite has been inserted or false otherwise.

Type
boolean

insertSprites(sprites) → {integer}

Inserts the given sprites. It will keep the existing ones. If a sprite identifier already existed and it is given again (not recommended), it will be replaced by the new one (but keeping its current sound instances, if any).

Parameters:
Name Type Description
sprites CB_AudioFileSprites.SPRITES_OBJECT

Object with the desired sprites.
Source:
Returns:

Returns the number of sprites inserted.

Type
integer

isAudioFileFree(id) → {boolean}

Tells whether a desired CB_AudioFile object is free (it is in the CB_AudioFileCache#audioFilesFree property) or not, by its identifier. A free CB_AudioFile object is an object which is not being used and it is available to be used. Uses the CB_AudioFileCache#isAudioFileFree method internally and returns its returning value.

Parameters:
Name Type Description
id string

Used as the "id" parameter when calling the CB_AudioFileCache#isAudioFileFree method internally.
Source:
Returns:

Returns whether a desired CB_AudioFile object is free (it is in the CB_AudioFileCache#audioFilesFree property) or not, by its identifier. A free CB_AudioFile object is an object which is not being used and it is available to be used.

Type
boolean

isPausedSprite(spriteId) → {boolean}

Tells whether a given sprite (by its ID) is paused or not. Note that there could be more than one sound instance (with a {@CB_AudioFile} object) by each sprite with different status (paused, stopped, etc.) and this method will return true if any of them is paused.

Parameters:
Name Type Description
spriteId string

The identifier for the sprite.
Source:
Returns:

Returns whether a given sprite (by its ID) is paused or not.

Type
boolean

isPlaying() → {boolean}

Tells whether any of the CB_AudioFile objects is playing or not. Uses the CB_AudioFileCache#isPlaying method internally and returns its returning value.

Source:
Returns:

Returns whether any of the CB_AudioFile objects is playing or not.

Type
boolean

isPlayingSprite(spriteId) → {boolean}

Tells whether a given sprite (by its ID) is playing or not. Note that there could be more than one sound instance (with a {@CB_AudioFile} object) by each sprite with different status (paused, stopped, etc.) and this method will return true if any of them is playing.

Parameters:
Name Type Description
spriteId string

The identifier for the sprite.
Source:
Returns:

Returns whether a given sprite (by its ID) is playing or not.

Type
boolean

isStoppedSprite(spriteId [, checkAudioFileObjects]) → {boolean}

Tells whether a given sprite (by its ID) is stopped or not. Note that there could be more than one sound instance (with a {@CB_AudioFile} object) by each sprite with different status (paused, stopped, etc.) and this method will only return true if all of them are stopped.

Parameters:
Name Type Argument Default Description
spriteId string

The identifier for the sprite.
checkAudioFileObjects boolean <optional>
 false

If set to true, it will check all the {@CB_AudioFile} objects associated to the sprite. Doing so, as internally all stopped {@CB_AudioFile} objects are disassociated from their sound instances, this method should return false normally (unless something went wrong).
Source:
Returns:

Returns whether a given sprite (by its ID) is stopped or not. As internally all stopped {@CB_AudioFile} objects are disassociated from their sound instances, this method should return false normally (unless something went wrong).

Type
boolean

load(dataObject) → {CB_AudioFileSprites|null}

Loads the audio file sprites with the desired data given. This method is called by the constructor automatically. Recommended to be called through a user-driven event (as onClick, onTouch, etc.), as some clients may need this at least the first time in order to be able to play the audio.

Parameters:
Name Type Description
dataObject CB_AudioFileSprites.DATA_OBJECT

Object with the desired data and options for the audio file sprites.
Source:
Returns:

If a "dataObject" is given, it returns the current CB_AudioFileSprites object. Otherwise, it returns null.

Type
CB_AudioFileSprites | null

muteAll( [onMute] [, audioFiles]) → {integer}

Mutes all the existing CB_AudioFile objects or the desired ones (if provided). Uses the CB_AudioFileCache#muteAll method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
onMute function <optional>

Used as the "onMute" parameter when calling the CB_AudioFileCache#muteAll method internally.
audioFiles array <optional>
 CB_AudioFileCache#audioFiles

Used as the "audioFiles" parameter when calling the CB_AudioFileCache#muteAll method internally.
Source:
Returns:

Returns the number of calls to the CB_AudioFile#mute method that were performed (which should be the same number as the CB_AudioFile objects in the "audioFiles" parameter).

Type
integer

muteSprite(spriteId [, onMute]) → {integer}

Mutes all the CB_AudioFile objects that belong to the sound instances (created by the CB_AudioFileSprites#play or the CB_AudioFileSprites#playSprite methods) used by a given sprite identifier. Uses the CB_AudioFileSprites#muteAll method internally and returns its returning value.

Parameters:
Name Type Argument Description
spriteId string

The identifier for the sprite.
onMute function <optional>

Callback function which will be called for each audio file if it has been possible to mute it (or at least it was possible to try it), being "this" the CB_AudioFile object. Used internally as the "onMute" parameter to call the CB_AudioFileSprites#muteAll method.
Source:
Returns:

Returns the number of calls to the CB_AudioFile#mute method that were performed internally.

Type
integer

pauseAll( [onPause] [, audioFiles]) → {integer}

Tries to pause all the existing CB_AudioFile objects or the desired ones (if provided), which are being played, by calling their CB_AudioFile#pause method internally. Uses the CB_AudioFileCache#pauseAll method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
onPause function <optional>

Used as the "onPause" parameter when calling the CB_AudioFileCache#pauseAll method internally.
audioFiles array <optional>
 CB_AudioFileCache#audioFiles

Used as the "audioFiles" parameter when calling the CB_AudioFileCache#pauseAll method internally.
Source:
Returns:

Returns the number of calls to the CB_AudioFile#pause method that were performed (which should be the same number as the CB_AudioFile objects in the "audioFiles" parameter).

Type
integer

pauseSprite(spriteId [, onPause]) → {integer}

Pauses all the CB_AudioFile objects that belong to the sound instances (created by the CB_AudioFileSprites#play or the CB_AudioFileSprites#playSprite methods) which are playing used by a given sprite identifier. Uses the CB_AudioFileSprites#pauseAll method internally and returns its returning value.

Parameters:
Name Type Argument Description
spriteId string

The identifier for the sprite.
onPause function <optional>

Function without parameters to be called when the audio is paused successfully, being "this" the CB_AudioFile object. Used internally as the "onPause" parameter to call the CB_AudioFileSprites#pauseAll method.
Source:
Returns:

Returns the number of calls to the CB_AudioFile#pause method that were performed internally.

Type
integer

play( [startAt] [, stopAt] [, loop] [, volume] [, allowedRecursiveDelay] [, allowedRecursiveDelaySkipping] [, onPlayStart] [, onStop] [, spriteId]) → {integer|null}

Plays a sound of the cache (if there is any free), using a sprite if desired. If a sound cannot be played, this method can call itself internally again and again (with most of the given parameters being the same, depending on the circumstances) to try to play the sound until a desired time limit is reached. If a CB_AudioFile object cannot be played and it is determined necessary, it will try to reload it internally (by calling the CB_AudioFileCache#removeAudioFile method). Uses the CB_AudioFileCache#play method internally and returns its returning value. Internal usage only recommended. To play a sprite, better use the CB_AudioFileSprites#playSprite method instead.

Parameters:
Name Type Argument Default Description
startAt number <optional>
 0 | CB_AudioFile_API.WAAPI#lastStartAt | CB_AudioFile_API.SM2#lastStartAt | CB_AudioFile_API.ACMP#lastStartAt | CB_AudioFile_API.AAPI#lastStartAt | stopAt

Used as the "startAt" parameter when calling the CB_AudioFileCache#play method internally.
stopAt number <optional>
 CB_AudioFile_API.WAAPI#getDuration() | CB_AudioFile_API.SM2#getDuration() | CB_AudioFile_API.ACMP#getDuration() | CB_AudioFile_API.AAPI#getDuration()

Used as the "stopAt" parameter when calling the CB_AudioFileCache#play method internally.
loop boolean <optional>
 CB_AudioFile#loop

Used as the "loop" parameter when calling the CB_AudioFileCache#play method internally.
volume number <optional>
 CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_USE_SPEAKER_VOLUME_AS_DEFAULT ? CB_Speaker.getVolume() : CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME

Used as the "volume" parameter when calling the CB_AudioFileCache#play method internally.
allowedRecursiveDelay boolean <optional>
 CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT

Used as the "allowedRecursiveDelay" parameter when calling the CB_AudioFileCache#play method internally.
allowedRecursiveDelaySkipping boolean <optional>
 stopAt-startAt

Used as the "allowedRecursiveDelaySkipping" parameter when calling the CB_AudioFileCache#play method internally.
onPlayStart function <optional>

Used as the "onPlayStart" parameter when calling the CB_AudioFileCache#play method internally.
onStop function <optional>

Used as the "onStop" parameter when calling the CB_AudioFileCache#play method internally.
spriteId string <optional>
 '_WITHOUT_SPRITE_ASSOCIATED'

The identifier for the sprite. Internal usage only recommended.
Source:
Returns:

Returns null if a sprite identifier was given but it could not be found. Otherwise, returns the sound instance ID used if there was one free or null otherwise. To get a sound instance returned does not mean necessarily that the sound started playing so it is necessary to use a callback function as the "onPlayStart" parameter for checking this. The sound instance created (if any), will be cancelled automatically once the sound is stopped.

Type
integer | null

playAll( [startAt] [, stopAt] [, loop] [, volume] [, avoidDelayedPlay] [, allowedRecursiveDelay] [, onPlayStart] [, onStop] [, includingPlaying]) → {integer}

Tries to play all the CB_AudioFile objects by calling their CB_AudioFile#play method internally. If a CB_AudioFile object cannot be played and it is determined necessary, it will try to reload it internally (by calling the CB_AudioFileCache#removeAudioFile method). Uses the CB_AudioFileCache#playAll method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
startAt number <optional>
 0 | CB_AudioFile_API.WAAPI#lastStartAt | CB_AudioFile_API.SM2#lastStartAt | CB_AudioFile_API.ACMP#lastStartAt | CB_AudioFile_API.AAPI#lastStartAt | stopAt

Used as the "startAt" parameter when calling the CB_AudioFileCache#playAll method internally.
stopAt number <optional>
 CB_AudioFile_API.WAAPI#getDuration() | CB_AudioFile_API.SM2#getDuration() | CB_AudioFile_API.ACMP#getDuration() | CB_AudioFile_API.AAPI#getDuration()

Used as the "stopAt" parameter when calling the CB_AudioFileCache#playAll method internally.
loop boolean <optional>
 CB_AudioFile#loop

Used as the "loop" parameter when calling the CB_AudioFileCache#playAll method internally.
volume number <optional>
 CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_USE_SPEAKER_VOLUME_AS_DEFAULT ? CB_Speaker.getVolume() : CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME

Used as the "volume" parameter when calling the CB_AudioFileCache#playAll method internally.
avoidDelayedPlay boolean <optional>
 false

Used as the "avoidDelayedPlay" parameter when calling the CB_AudioFileCache#playAll method internally.
allowedRecursiveDelay boolean <optional>
 CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT

Used as the "allowedRecursiveDelay" parameter when calling the CB_AudioFileCache#playAll method internally.
onPlayStart function <optional>

Used as the "onPlayStart" parameter when calling the CB_AudioFileCache#playAll method internally.
onStop function <optional>

Used as the "onStop" parameter when calling the CB_AudioFileCache#playAll method internally.
includingPlaying boolean <optional>
 false

Used as the "includingPlaying" parameter when calling the CB_AudioFileCache#playAll method internally.
Source:
Returns:

Returns the number of CB_AudioFile objects whose CB_AudioFile#play method did not return the value of "-1" (this does not mean necessarily that they could be played successfully).

Type
integer

playAndStopAll( [includingPlaying] [, delayBeforeStop]) → {integer}

Plays silently and stops all CB_AudioFile objects after a desired time. It can be useful for some clients which need the CB_AudioFile#play method to be called through a user-driven event (as onClick, onTouch, etc.). Internally, it calls CB_AudioFileCache#playAll(0, null, false, 0, true, null, null, null, includingPlaying) and, after a desired delay, calls the CB_AudioFileCache#stopAll method. Uses the CB_AudioFileCache#playAndStopAll method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
includingPlaying boolean <optional>
 false

Used as the "includingPlaying" parameter when calling the CB_AudioFileCache#playAndStopAll method internally.
delayBeforeStop number <optional>
 100

Used as the "delayBeforeStop" parameter when calling the CB_AudioFileCache#playAndStopAll method internally.
Source:
Returns:

Returns the number of CB_AudioFile objects whose CB_AudioFile#play method did not return the value of "-1" (this does not mean necessarily that they could be played successfully).

Type
integer

playSprite(spriteId [, loop] [, volume] [, allowedRecursiveDelay] [, allowedRecursiveDelaySkipping] [, onPlayStart] [, onStop]) → {integer|null}

Plays a sprite by its ID. If the sprite is found, uses the CB_AudioFileSprites#play method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
spriteId string

The identifier for the sprite. Used as the "spriteId" parameter when calling the CB_AudioFileSprites#play method internally.
loop boolean <optional>
 CB_AudioFile#loop

Used as the "loop" parameter when calling the CB_AudioFileSprites#play method internally.
volume number <optional>
 CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_USE_SPEAKER_VOLUME_AS_DEFAULT ? CB_Speaker.getVolume() : CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME

Used as the "volume" parameter when calling the CB_AudioFileSprites#play method internally.
allowedRecursiveDelay boolean <optional>
 CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT

Used as the "allowedRecursiveDelay" parameter when calling the CB_AudioFileSprites#play method internally.
allowedRecursiveDelaySkipping boolean <optional>
 stopAt-startAt

Used as the "allowedRecursiveDelaySkipping" parameter when calling the CB_AudioFileSprites#play method internally.
onPlayStart function <optional>

Used as the "onPlayStart" parameter when calling the CB_AudioFileSprites#play method internally.
onStop function <optional>

Used as the "onStop" parameter when calling the CB_AudioFileSprites#play method internally.
Source:
Returns:

Returns null if the sprite was not found. Otherwise, returns the sound instance ID used if there was one free or null otherwise. To get a sound instance returned does not mean necessarily that the sound started playing so it is necessary to use a callback function as the "onPlayStart" parameter for checking this. The sound instance created (if any), will be cancelled automatically once the sound is stopped.

Type
integer | null

purge(desiredNumber [, setAsMinimumAudioFiles] [, includePlaying] [, stopSounds] [, statuses]) → {integer}

Tries to purge the audio file cache until it reaches a desired number of CB_AudioFile objects internally (set in the CB_AudioFileCache#audioFiles property), by removing and destroying some of the current CB_AudioFile objects. For performance purposes. Uses the CB_AudioFileCache#purge method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
desiredNumber integer

Used as the "desiredNumber" parameter when calling the CB_AudioFileCache#purge method internally.
setAsMinimumAudioFiles boolean <optional>
 false

Used as the "setAsMinimumAudioFiles" parameter when calling the CB_AudioFileCache#purge method internally.
includePlaying boolean <optional>
 false

Used as the "includePlaying" parameter when calling the CB_AudioFileCache#purge method internally.
stopSounds boolean <optional>
 false

Used as the "stopSounds" parameter when calling the CB_AudioFileCache#purge method internally.
statuses array <optional>
 Array(CB_AudioFile.LOADING, CB_AudioFile.UNCHECKED, CB_AudioFile.CHECKING, CB_AudioFile.LOADED)

Used as the "statuses" parameter when calling the CB_AudioFileCache#purge method internally.
Source:
Returns:

Returns the number of CB_AudioFile objects removed.

Type
integer

removeAudioFile(audioObjectOrId [, reload] [, checkManually]) → {boolean|CB_AudioFile|null}

If found, takes a given CB_AudioFile object off the CB_AudioFileCache#audioFiles property (and reloads it if we want to). NOTE: It does neither destroy nor remove the CB_AudioFile object so it can be used for other purposes (and if a CB_AudioFile object is given, it will be tried to be reused by the CB_AudioFileCache#createAudioFile method internally if it is called). Uses the CB_AudioFileCache#removeAudioFile method internally and returns its returning value. Internal usage only recommended.

Parameters:
Name Type Argument Default Description
audioObjectOrId CB_AudioFile | string

Used as the "audioObjectOrId" parameter when calling the CB_AudioFileCache#removeAudioFile method internally.
reload boolean <optional>
 false

Used as the "reload" parameter when calling the CB_AudioFileCache#removeAudioFile method internally.
checkManually boolean <optional>
 false

Used as the "checkManually" parameter when calling the CB_AudioFileCache#removeAudioFile method internally.
Source:
Returns:

Returns null if the given "audioObjectOrId" parameter is not a valid CB_AudioFile object or its CB_AudioFile#id property is not set or when the "audioObjectOrId" parameter is an empty string. Returns a CB_AudioFile object, the given one through the "audioObjectOrId" parameter of the first one removed (it should be the first and unique one removed as the ID must be unique), if the CB_AudioFileCache#createAudioFile method is called internally (it will reuse this CB_AudioFile object). Otherwise, returns true if all goes well.

Type
boolean | CB_AudioFile | null

removeSprite(spriteId) → {boolean}

Removes a sprite by its ID.

Parameters:
Name Type Description
spriteId string

The identifier for the sprite.
Source:
Returns:

Returns true if the sprite has been deleted or false otherwise.

Type
boolean

removeSprites()

Removes all the sprites by clearing the CB_AudioFileSprites#sprites property.

Source:

removeSpritesAll()

Alias for CB_AudioFileSprites#removeSprites.

Source:
See:

resumeAll( [loop] [, allowedRecursiveDelay] [, allowedRecursiveDelaySkipping] [, onPlayStart] [, onStop] [, audioFiles] [, spriteId]) → {array}

Resumes all the existing CB_AudioFile objects or the desired ones (if provided), which are paused (and not stopped). Can be focused on just one sprite identifier if desired. Uses the CB_AudioFileCache#resumeAll method internally and returns its returning value. Internal usage only recommended. To resume a sprite, better use the CB_AudioFileSprites#resumeSprite method instead.

Parameters:
Name Type Argument Default Description
loop boolean <optional>
 CB_AudioFile#loop

Used as the "loop" parameter when calling the CB_AudioFileCache#resumeAll method internally.
allowedRecursiveDelay boolean <optional>
 CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT

Used as the "allowedRecursiveDelay" parameter when calling the CB_AudioFileCache#resumeAll method internally.
allowedRecursiveDelaySkipping boolean <optional>
 CB_AudioFile#lastStopAt-CB_AudioFile#lastStartAt

Used as the "allowedRecursiveDelaySkipping" parameter when calling the CB_AudioFileCache#resumeAll method internally.
onPlayStart function <optional>

Used as the "onPlayStart" parameter when calling the CB_AudioFileCache#resumeAll method internally.
onStop function <optional>

Used as the "onStop" parameter when calling the CB_AudioFileCache#resumeAll method internally.
audioFiles array <optional>
 CB_AudioFileCache#audioFiles

Used as the "audioFiles" parameter when calling the CB_AudioFileCache#resumeAll method internally.
spriteId string <optional>
 '_WITHOUT_SPRITE_ASSOCIATED'

The identifier for the sprite. Internal usage only recommended.
Source:
Returns:

Returns null if a sprite identifier was given but it could not be found. Otherwise, returns a numeric array containing all the return values of each internal call to the CB_AudioFileCache#play method.

Type
array

resumeSprite(spriteId [, loop] [, allowedRecursiveDelay] [, allowedRecursiveDelaySkipping] [, onPlayStart] [, onStop]) → {array}

Resumes all the CB_AudioFile objects that belong to the sound instances (created by the CB_AudioFileSprites#play or the CB_AudioFileSprites#playSprite methods) used by a given sprite identifier. Uses the CB_AudioFileSprites#resumeAll method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
spriteId string

Used as the "spriteId" parameter when calling the CB_AudioFileSprites#resumeAll method internally.
loop boolean <optional>
 CB_AudioFile#loop

Used as the "loop" parameter when calling the CB_AudioFileSprites#resumeAll method internally.
allowedRecursiveDelay boolean <optional>
 CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT

Used as the "allowedRecursiveDelay" parameter when calling the CB_AudioFileSprites#resumeAll method internally.
allowedRecursiveDelaySkipping boolean <optional>
 stopAt-startAt

Used as the "allowedRecursiveDelaySkipping" parameter when calling the CB_AudioFileSprites#resumeAll method internally.
onPlayStart function <optional>

Used as the "onPlayStart" parameter when calling the CB_AudioFileSprites#resumeAll method internally.
onStop function <optional>

Used as the "onStop" parameter when calling the CB_AudioFileSprites#resumeAll method internally.
Source:
Returns:

Returns null if the sprite identifier given could not be found. Otherwise, returns a numeric array containing all the return values of each internal call to the CB_AudioFileCache#play method (called through CB_AudioFileSprites#resumeAll).

Type
array

setAudioAPIAll(preferredAPIs [, callbackOk] [, callbackError] [, mandatory] [, forceReload] [, audioFiles]) → {integer}

Tries to change the audio API for all the existing CB_AudioFile objects or the desired ones (if provided). This method is not allowed to be called if a previous call to it did not finish yet. The function defined in the "callbackError" parameter, if any, will be called immediately if the method was previously called and it is still running currently. Uses the CB_AudioFileCache#setAudioAPIAll method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
preferredAPIs array | string

Used as the "preferredAPIs" parameter when calling the CB_AudioFileCache#setAudioAPIAll method internally.
callbackOk CB_AudioFileCache.setAudioAPIAll_CALLBACK_OK <optional>

Used as the "callbackOk" parameter when calling the CB_AudioFileCache#setAudioAPIAll method internally.
callbackError CB_AudioFileCache.setAudioAPIAll_CALLBACK_ERROR <optional>

Used as the "callbackError" parameter when calling the CB_AudioFileCache#setAudioAPIAll method internally.
mandatory boolean <optional>
 false

Used as the "mandatory" parameter when calling the CB_AudioFileCache#setAudioAPIAll method internally.
forceReload string <optional>
 false

Used as the "forceReload" parameter when calling the CB_AudioFileCache#setAudioAPIAll method internally.
audioFiles array <optional>
 CB_AudioFileCache#audioFiles

Used as the "audioFiles" parameter when calling the CB_AudioFileCache#setAudioAPIAll method internally.
Source:
Returns:

Returns the number of calls to the CB_AudioFile#setAudioAPI method that were performed (which should be the same number as the CB_AudioFile objects in the "audioFiles" parameter).

Type
integer

setAudioAPISprite(spriteId, preferredAPIs [, callbackOk] [, callbackError] [, mandatory] [, forceReload]) → {integer}

Tries to change the desired audio API of the CB_AudioFile objects that belong to the sound instances (created by the CB_AudioFileSprites#play or the CB_AudioFileSprites#playSprite methods) used by a given sprite identifier. Uses the CB_AudioFileSprites#setAudioAPIAll method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
spriteId string

The identifier for the sprite.
preferredAPIs array

Used as the "preferredAPIs" parameter when calling the CB_AudioFileSprites#setAudioAPIAll method internally.
callbackOk CB_AudioFileCache.setAudioAPIAll_CALLBACK_OK <optional>

Used as the "callbackOk" parameter when calling the CB_AudioFileSprites#setAudioAPIAll method internally.
callbackError CB_AudioFileCache.setAudioAPIAll_CALLBACK_ERROR <optional>

Used as the "callbackError" parameter when calling the CB_AudioFileSprites#setAudioAPIAll method internally.
mandatory boolean <optional>
 false

Used as the "mandatory" parameter when calling the CB_AudioFileSprites#setAudioAPIAll method internally.
forceReload string <optional>
 false

Used as the "forceReload" parameter when calling the CB_AudioFileSprites#setAudioAPIAll method internally.
Source:
Returns:

Returns the number of calls to the CB_AudioFile#setAudioAPI method that were performed internally.

Type
integer

setStartAtSprite(spriteId, startAt) → {boolean}

Sets when a sprite begins (stored in its "startAt" property), by sprite identifier.

Parameters:
Name Type Description
spriteId string

The identifier for the sprite.
startAt number

The time (in milliseconds) of the audio file where the audio sprite starts.
Source:
Returns:

Returns true if the sprite has been modified or false otherwise.

Type
boolean

setStopAtSprite(spriteId, stopAt) → {boolean}

Sets when a sprite ends (stored in its "stopAt" property), by sprite identifier.

Parameters:
Name Type Description
spriteId string

The identifier for the sprite.
stopAt number

The time (in milliseconds) of the audio file where the audio sprite ends.
Source:
Returns:

Returns true if the sprite has been modified or false otherwise.

Type
boolean

setVolumeAll( [volume] [, forceSetVolumeProperty] [, onSetVolume] [, audioFiles]) → {integer}

Sets the same volume for all the existing CB_AudioFile objects or the desired ones (if provided). Uses the CB_AudioFileCache#setVolumeAll method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
volume number <optional>
 CB_Speaker.getVolume() | CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME

Used as the "volume" parameter when calling the CB_AudioFileCache#setVolumeAll method internally.
forceSetVolumeProperty boolean <optional>
 false

Used as the "forceSetVolumeProperty" parameter when calling the CB_AudioFileCache#setVolumeAll method internally.
onSetVolume function <optional>

Used as the "onSetVolume" parameter when calling the CB_AudioFileCache#setVolumeAll method internally.
audioFiles array <optional>
 CB_AudioFileCache#audioFiles

Used as the "audioFiles" parameter when calling the CB_AudioFileCache#setVolumeAll method internally.
Source:
Returns:

Returns the number of calls to the CB_AudioFile#setVolume method that were performed (which should be the same number as the CB_AudioFile objects in the "audioFiles" parameter).

Type
integer

setVolumeSprite(spriteId [, volume] [, forceSetVolumeProperty] [, onSetVolume]) → {integer}

Sets the same desired volume to all the CB_AudioFile objects that belong to the sound instances (created by the CB_AudioFileSprites#play or the CB_AudioFileSprites#playSprite methods) used by a given sprite identifier. Uses the CB_AudioFileSprites#setVolumeAll method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
spriteId string

The identifier for the sprite.
volume number <optional>
 CB_Speaker.getVolume() | CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME

Used as the "volume" parameter when calling the CB_AudioFileSprites#setVolumeAll method internally.
forceSetVolumeProperty boolean <optional>
 false

Used as the "forceSetVolumeProperty" parameter when calling the CB_AudioFileSprites#setVolumeAll method internally.
onSetVolume function <optional>

Used as the "onSetVolume" parameter when calling the CB_AudioFileSprites#setVolumeAll method internally.
Source:
Returns:

Returns the number of calls to the CB_AudioFile#setVolume method that were performed internally.

Type
integer

stopAll( [audioFiles]) → {integer}

Tries to stops all the existing CB_AudioFile objects or the desired ones (if provided), which are being played, by calling their CB_AudioFile#stop method internally. Uses the CB_AudioFileCache#stopAll method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
audioFiles array <optional>
 CB_AudioFileCache#audioFiles

Used as the "audioFiles" parameter when calling the CB_AudioFileCache#stopAll method internally.
Source:
Returns:

Returns the number of calls to the CB_AudioFile#stop method that were performed (which should be the same number as the CB_AudioFile objects in the "audioFiles" parameter).

Type
integer

stopSprite(spriteId) → {integer}

Stops all the CB_AudioFile objects that belong to the sound instances (created by the CB_AudioFileSprites#play or the CB_AudioFileSprites#playSprite methods) which are playing used by a given sprite identifier. Uses the CB_AudioFileSprites#stopAll method internally and returns its returning value.

Parameters:
Name Type Description
spriteId string

The identifier for the sprite.
Source:
Returns:

Returns the number of calls to the CB_AudioFile#stop method that were performed internally.

Type
integer

unmuteAll( [onUnmute] [, audioFiles]) → {integer}

Unmutes all the existing CB_AudioFile objects or the desired ones (if provided). Uses the CB_AudioFileCache#unmuteAll method internally and returns its returning value.

Parameters:
Name Type Argument Default Description
onUnmute function <optional>

Used as the "onUnmute" parameter when calling the CB_AudioFileCache#unmuteAll method internally.
audioFiles array <optional>
 CB_AudioFileCache#audioFiles

Used as the "audioFiles" parameter when calling the CB_AudioFileCache#unmuteAll method internally.
Source:
Returns:

Returns the number of calls to the CB_AudioFile#unmute method that were performed (which should be the same number as the CB_AudioFile objects in the "audioFiles" parameter).

Type
integer

unmuteSprite(spriteId [, onUnmute]) → {integer}

Unmutes all the CB_AudioFile objects that belong to the sound instances (created by the CB_AudioFileSprites#play or the CB_AudioFileSprites#playSprite methods) used by a given sprite identifier. Uses the CB_AudioFileSprites#unmuteAll method internally and returns its returning value.

Parameters:
Name Type Argument Description
spriteId string

The identifier for the sprite.
onUnmute function <optional>

Used internally as the "onUnmute" parameter to call the CB_AudioFileSprites#unmuteAll method.
Source:
Returns:

Returns the number of calls to the CB_AudioFile#unmute method that were performed internally.

Type
integer

Type Definitions

DATA_OBJECT

Object with the desired data and options for the audio sprites. It is almost identical to the CB_AudioFileCache.DATA_OBJECT but adding a "sprites" property.

Type:
  • Object
Properties:
Name Type Argument Default Description
URIs CB_AudioFileCache.URIS_OBJECT

Object whose property names audio formats and their value is an array of strings with the URIs (audio file paths or audio data URIs) of the audio files in order of preference. The best audio format for the current client will be tried to be calculated and it will use the first working URI (audio file path or data URI). The more audio formats and URIs provided the better, as it will help to maximize the compatibility with as many clients as possible (as some audio APIs and client just support some formats, or use absolute paths instead of relative ones, etc.). Even with different formats, all provided URIs should belong to the same audio (this means same sound or same music, with same length, etc.). NOTE: Only some clients with some audio APIs will support data URIs. If a valid value is given, this will be added to the CB_AudioFileCache#URIs property.
sprites CB_AudioFileSprites.SPRITES_OBJECT <optional>

Object with the desired sprites. It will be used as the first parameter to call the CB_AudioFileSprites#insertSprites method internally. It will be added (after being processed) to the CB_AudioFileCache#sprites property.
id string <optional>
 ""

Desired identifier for the audio file sprites object. Internal usage only recommended. If a valid value is given, this will be added to the CB_AudioFileSprites#id property as well as to the CB_AudioFileCache#id property of the internally-created CB_AudioFileCache object.
preferredAPIs array <optional>
 CB_Configuration.CrossBase.CB_AudioFileCache_PREFERRED_AUDIO_APIS

Array of strings with the preferred audio API or audio APIs, in order of preference. Possible audio APIs are "WAAPI" (HTML5 Web Audio API), "SM2" (SoundManager 2), "ACMP" (Apache Cordova Media Plugin) or "AAPI" (HTML5 Audio API). It will try to calculate and use the best one for the current client. If a valid value is given, this will be added to the CB_AudioFileCache#preferredAPIs property.
preferredFormats array <optional>
 CB_Configuration.CrossBase.CB_AudioFileCache_PREFERRED_AUDIO_FORMATS

Array of strings with the preferred audio format or audio formats (they can include just the format as 'audio/ogg' or also the codec as for example 'audio/ogg; codecs="vorbis"'), in order of preference. It will try to calculate and use the best one for the current client. If a valid value is given, this will be added to the CB_AudioFileCache#preferredFormats property.
minimumAudioFiles integer <optional>
 CB_AudioFileCache.minimumAudioFiles_DEFAULT

Minimum CB_AudioFile objects to create internally. It must be an integer being 1 the minimum. If a valid value is given, this will be added to the CB_AudioFileCache#minimumAudioFiles property.
maximumAudioFiles integer <optional>
 CB_AudioFileCache.maximumAudioFiles_DEFAULT

Maximum CB_AudioFile objects that are to be created internally. If it is set to null, there will not be a maximum (it will be unlimited). If an integer is provided, it must be the same number or greater than the value set in the CB_AudioFileCache#minimumAudioFiles property (also provided by the "minimumAudioFiles" of this object), allowing 1 minimum. If a valid value is given, this will be added to the CB_AudioFileCache#maximumAudioFiles property.
minimumAudioFilesFree integer <optional>
 parseInt(CB_AudioFileCache#minimumAudioFiles * 0.25 + 0.5)

New CB_AudioFile objects will be created internally when the number of free CB_AudioFile objects reaches this limit. If provided, it must be an integer being 0 (zero) the minimum. It will end using a 25% of the CB_AudioFileCache#minimumAudioFiles by default, rounded to ceil, allowing 0 (zero) minimum. If a valid value is given, this will be added to the CB_AudioFileCache#minimumAudioFilesFree property.
newAudioFilesWhenNeeded integer <optional>
 Math.min(parseInt(CB_AudioFileCache#minimumAudioFiles * 0.1 + 0.5), 1)

Number of new CB_AudioFile objects to create internally when the minimum limit of free CB_AudioFile objects (CB_AudioFileCache#minimumAudioFilesFree) is reached. If provided, it must be an integer being 0 (zero) the minimum. It will end using a 10% of the CB_AudioFileCache#minimumAudioFiles by default, rounded to ceil, allowing 1 minimum. If a valid value is given, this will be added to the CB_AudioFileCache#newAudioFilesWhenNeeded property.
retries integer <optional>
 CB_AudioFileCache.retries_DEFAULT

Number of retries to try to load a CB_AudioFile object internally before trying to load the next possible one internally (if any). It must be an integer being 0 the minimum. If a valid value is given, this will be added to the CB_AudioFileCache#retries property.
checkManually boolean <optional>
 CB_AudioFileCache.checkManually_DEFAULT

Tells whether the CB_AudioFile objects must be checked automatically or not (manually) by default. If a valid value is given, this will be added to the CB_AudioFileCache#checkManually property.
checkManuallyOnNeededCreated boolean <optional>
 CB_AudioFileCache.checkManuallyOnNeededCreated_DEFAULT

Tells whether the CB_AudioFile objects must be checked automatically or not (manually) when creates a new CB_AudioFile object needed. If a valid value is given, this will be added to the CB_AudioFileCache#checkManuallyOnNeededCreated property.
checkManuallyOnPlayingFailed boolean <optional>
 CB_AudioFileCache.checkManuallyOnPlayingFailed_DEFAULT

Tells whether the CB_AudioFile objects must be checked automatically or not (manually) when playing one has failed and tries to reload it. If a valid value is given, this will be added to the CB_AudioFileCache#checkManuallyOnPlayingFailed property.
checkManuallyOnCheckingFailed boolean <optional>
 CB_AudioFileCache.checkManuallyOnCheckingFailed_DEFAULT

Tells whether the CB_AudioFile objects must be checked automatically or not (manually) when checking one has failed and tries to reload it. If a valid value is given, this will be added to the CB_AudioFileCache#checkManuallyOnCheckingFailed property.
onLoad function <optional>

Desired function to be called once the cache has been loaded. The first and unique parameter will be an integer with the CB_AudioFile objects that still need to be checked, if any, being "this" the current CB_AudioFileCache object. If a valid value is given, this will be added to the CB_AudioFileCache#onLoad property.
onError function <optional>

Desired function to be called when any kind of error happens. The first and unique parameter will be a string with the error description (if it could be determined), being "this" the current CB_AudioFileCache object. If a valid value is given, this will be added to the CB_AudioFileCache#onError property.
disableAutoLoad boolean <optional>
 false

If set to true, it will not create automatically the CB_AudioFile objects by calling the CB_AudioFileCache#createAudioFiles method internally. Internal usage only recommended.
Source:

SPRITES_OBJECT

Object whose property names the identifiers of each sprite (a case-sensitive string) and their value is a CB_AudioFileSprites.SPRITE_OBJECT object.

Type:
  • Object
Properties:
Name Type Description
spriteInformation CB_AudioFileSprites.SPRITE_OBJECT

Being the name of each property the identifier of a sprite (a string which cannot be "_WITHOUT_SPRITE_ASSOCIATED" as it is a reserved name), the value will always be a CB_AudioFileSprites.SPRITE_OBJECT object.
Source:
Example
{
	"whole_audio" : {},
	"first_sprite" : { stopAt: 10 },
	"second_sprite" : { startAt: 10, stopAt: 20 },
	"third_sprite" : { startAt: 20 },
	...
}

SPRITE_OBJECT

An object representing an audio sprite which can contain, optionally, the "startAt" and "stopAt" properties with a numeric value (representing when the audio sprite starts and when it stops, respectively). If not set, the default "startAt" value will be 0 (zero) and the default "stopAt" value will be null (which means it will not stop until the end of the audio is reached unless it is paused or stopped before). The "fake" property should never be used as it is used internally to distinguish real sprites from fake ones (generated and returned by the CB_AudioFileSprites#getSprite method when a requested sprite is not found).

Type:
  • Object
Properties:
Name Type Argument Default Description
startAt number <optional>
 0

The time (in milliseconds) of the audio file where the audio sprite starts. If not provided, it will use the value of 0 (zero) which means that it will start from the beginning.
stopAt number <optional>
 CB_AudioFile_API.WAAPI#getDuration() | CB_AudioFile_API.SM2#getDuration() | CB_AudioFile_API.ACMP#getDuration() | CB_AudioFile_API.AAPI#getDuration()

The time (in milliseconds) of the audio file where the audio sprite stops. If not provided (not recommended), it will use the whole duration of the file (which means until it reaches its end). NOTE: Due to some possible problems between clients with different audio APIs calculating the duration of an audio file, it is recommended to always set the "stopAt" property even when we want it to stop at the end of the audio.
Source:
Example
{ startAt: 10, stopAt: 20 }

getAudioFilesUsed_OBJECT

Object returned by the CB_AudioFileSprites#getAudioFilesUsed method. Each property names will be the sprites identifiers except the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated (if we wanted to include them).

Type:
  • Object
Properties:
Name Type Description
spriteId CB_AudioFile

Each property name will be a sprite identifier (it can be "_WITHOUT_SPRITE_ASSOCIATED" for sound instances without a sprite associated, if we wanted to include them). The value will be a numeric array with the CB_AudioFile objects used.
Source: