Class: CB_AudioFileSpritesPool

CB_AudioFileSpritesPool

Class to manage many audio sprites stored in different groups, each with one CB_AudioFileSprites object (used internally).


new CB_AudioFileSpritesPool( [dataObject]) → {CB_AudioFileSpritesPool}

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_AudioFileSpritesPool.DATA_OBJECT <optional>

Object with the desired data and options for the groups of audio sprites. Each group will have a CB_AudioFileSprites object. Some of its properties ("preferredAPIs", "preferredFormats", "minimumAudioFiles", "maximumAudioFiles", "minimumAudioFilesFree", "newAudioFilesWhenNeeded", "retries", "checkManually", "checkManuallyOnNeededCreated", "checkManuallyOnPlayingFailed", "checkManuallyOnCheckingFailed" and "disableAutoLoad") will be used as the default value to create internally the CB_AudioFileSprites objects when the value is not given in the CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT object (set as the value of the CB_AudioFileSpritesPool.DATA_OBJECT#spritesGroups property).

Source:
To Do:
  • Do not allow to create one object with an "id" which has already been used (unless the value is undefined, null...).
  • Method getCopy and static method filterProperties (similar to the ones from CB_GraphicSprites and CB_GraphicSpritesScene).
Returns:

Returns a new CB_AudioFileSpritesPool object.

Type
CB_AudioFileSpritesPool

Members


<readonly> audioFileSprites :Object

Stores the internally-created CB_AudioFileSprites objects, using the name of each property as their group ID and the value being the CB_AudioFileSprites object itself. Internal usage only recommended.

Type:
  • Object
Default Value:
  • {}
Source:

<readonly> checkManually :boolean

Tells whether the CB_AudioFile objects must be checked automatically or not (manually). Internal usage only recommended.

Type:
  • boolean
Default Value:
  • CB_AudioFileCache.checkManually_DEFAULT
Source:

<readonly> checkManuallyOnCheckingFailed :boolean

Tells whether the CB_AudioFile objects must be checked automatically or not (manually) when checking one has failed and tries to reload it. Internal usage only recommended.

Type:
  • boolean
Default Value:
  • CB_AudioFileCache.checkManuallyOnCheckingFailed_DEFAULT
Source:

<readonly> checkManuallyOnNeededCreated :boolean

Tells whether the CB_AudioFile objects must be checked automatically or not (manually) when creates a new CB_AudioFile object needed. Internal usage only recommended.

Type:
  • boolean
Default Value:
  • CB_AudioFileCache.checkManuallyOnNeededCreated_DEFAULT
Source:

<readonly> checkManuallyOnPlayingFailed :boolean

Tells whether the CB_AudioFile objects must be checked automatically or not (manually) when playing one has failed and tries to reload it. Internal usage only recommended.

Type:
  • boolean
Default Value:
  • CB_AudioFileCache.checkManuallyOnPlayingFailed_DEFAULT
Source:

<readonly> disableAutoLoad :boolean

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.

Type:
  • boolean
Default Value:
  • false
Source:

<readonly> id :string

Stores the identifier for the audio file sprites pool object.

Type:
  • string
Source:

<readonly> maximumAudioFiles :integer|null

Maximum CB_AudioFile objects that are to be created internally for each CB_AudioFileSprites object. 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, allowing 1 minimum. Internal usage only recommended.

Type:
  • integer | null
Default Value:
  • CB_AudioFileCache.maximumAudioFiles_DEFAULT
Source:

<readonly> minimumAudioFiles :integer

Minimum CB_AudioFile objects to create internally for each CB_AudioFileSprites object. It must be an integer being 1 the minimum. Internal usage only recommended.

Type:
  • integer
Default Value:
  • CB_AudioFileCache.minimumAudioFiles_DEFAULT
Source:

<readonly> minimumAudioFilesFree :integer

New CB_AudioFile objects will be created internally for each CB_AudioFileSprites object when the number of free CB_AudioFile objects reaches this limit. It must be an integer being 0 (zero) the minimum. Internal usage only recommended.

Type:
  • integer
Default Value:
Source:

<readonly> newAudioFilesWhenNeeded :integer

Number of new CB_AudioFile objects to create internally for each CB_AudioFileSprites object when the minimum limit of free CB_AudioFile objects (CB_AudioFileCache#minimumAudioFilesFree) is reached. It must be an integer being 0 (zero) the minimum. Internal usage only recommended.

Type:
  • integer
Default Value:
Source:

<readonly> onError :function

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_AudioFileSpritesPool object. If a function is set, it will always be called through the CB_AudioFileSpritesPool#errorFunction method whenever the "onError" event of an internally-created CB_AudioFileSprites object is fired.

Type:
  • function
Source:

<readonly> onLoad :function

Desired function to be called once the pool 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_AudioFileSpritesPool object.

Type:
  • function
Source:

<readonly> preferredAPIs :array

Stores an 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). Internal usage only recommended.

Type:
  • array
Default Value:
  • CB_Configuration.CrossBase.CB_AudioFileCache_PREFERRED_AUDIO_APIS
Source:

<readonly> preferredFormats :array

Stores an 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. Internal usage only recommended.

Type:
  • array
Default Value:
  • CB_Configuration.CrossBase.CB_AudioFileCache_PREFERRED_AUDIO_FORMATS
Source:

<readonly> retries :integer

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. Internal usage only recommended.

Type:
  • integer
Default Value:
  • CB_AudioFileCache.retries_DEFAULT
Source:

<static, constant> ABORTED :integer

Status value for an audio file sprites pool which has been aborted. This will happen when the audio file sprites pool has been destroyed with the CB_AudioFileSpritesPool#destructor method. Can be used to compare the value returned by the CB_AudioFileSpritesPool#getStatus method. Recommended for internal usage only.

Type:
  • integer
Default Value:
  • 6
Source:

<static, constant> CHECKING :integer

Status value for an audio file sprites pool which is being checked currently. Can be used to compare the value returned by the CB_AudioFileSpritesPool#getStatus method. Recommended for internal usage only.

Type:
  • integer
Default Value:
  • 3
Source:

<static, constant> FAILED :integer

Status value for an audio file sprites pool which failed to be loaded or failed for any other reason. Can be used to compare the value returned by the CB_AudioFileSpritesPool#getStatus method. Recommended for internal usage only.

Type:
  • integer
Default Value:
  • 5
Source:

<static, constant> LOADED :integer

Status value for an audio file sprites pool which has been loaded. Can be used to compare the value returned by the CB_AudioFileSpritesPool#getStatus method. Recommended for internal usage only.

Type:
  • integer
Default Value:
  • 4
Source:

<static, constant> LOADING :integer

Status value for an audio file sprites pool which is loading. Can be used to compare the value returned by the CB_AudioFileSpritesPool#getStatus method. Recommended for internal usage only.

Type:
  • integer
Default Value:
  • 1
Source:

<static, constant> UNCHECKED :integer

Status value for an audio file sprites pool which has not been checked yet. Can be used to compare the value returned by the CB_AudioFileSpritesPool#getStatus method. Recommended for internal usage only.

Type:
  • integer
Default Value:
  • 2
Source:

<static, constant> UNLOADED :integer

Status value for audio file sprites pool which is unloaded. Can be used to compare the value returned by the CB_AudioFileSpritesPool#getStatus method. Recommended for internal usage only.

Type:
  • integer
Default Value:
  • 0
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_AudioFileSprites#cancelSoundInstance method internally.

Parameters:
Name Type Argument Default Description
soundInstanceId integer

Used as the "soundInstanceId" parameter when calling the CB_AudioFileSprites#cancelSoundInstance method internally.

cancel boolean <optional>
false

Used as the "cancel" parameter when calling the CB_AudioFileSprites#cancelSoundInstance method internally.

affectWithObjectAssociated boolean <optional>
false

Used as the "affectWithObjectAssociated" parameter when calling the CB_AudioFileSprites#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_AudioFileSprites#cancelSoundInstances method internally.

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

Used as the "cancel" parameter when calling the CB_AudioFileSprites#cancelSoundInstances method internally.

affectWithObjectAssociated boolean <optional>
false

Used as the "affectWithObjectAssociated" parameter when calling the CB_AudioFileSprites#cancelSoundInstances method internally.

Source:
Returns:

Returns the number of sound instances modified.

Type
integer

checkPlayingAll( [callbackOk] [, callbackError] [, ignoreQueue] [, ignoreStatus]) → {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 each call to the CB_AudioFileSprites#checkPlayingAll method. Uses the CB_AudioFileSprites#checkPlayingAll method internally. Recommended to be called through a user-driven event (as onClick, onTouch, etc.).

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

A function which will be called if all the CB_AudioFile objects whose CB_AudioFile#getStatus method returned the "unchecked" value (which belongs to the value of the CB_AudioFile#UNCHECKED property) could finally be checked successfully and all can be played, being "this" the CB_AudioFileSpritesPool object itself.

callbackError CB_AudioFileSpritesPool.checkPlayingAll_CALLBACK_ERROR <optional>

A function which will be called if not all the CB_AudioFile objects whose CB_AudioFile#getStatus method returned the "unchecked" value (which belongs to the value of the CB_AudioFile#UNCHECKED property) could finally be checked successfully and any cannot be played, being "this" the CB_AudioFileSpritesPool object itself. This function will be called immediately if the method was previously called and it is still running currently.

ignoreQueue boolean <optional>
false

Used as the "ignoreQueue" parameter when calling the CB_AudioFileSprites#checkPlayingAll method internally.

ignoreStatus boolean <optional>
false

If it is set to false and the sprites pool object is loaded (the CB_AudioFileSpritesPool#getStatus method returns the value set in the CB_AudioFileSpritesPool.LOADED property), it will exit returning an error. Otherwise, if it is set to true, it will ignore the current sprites pool object status.

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 audio sprites pool is neither loaded (the CB_AudioFileSpritesPool#getStatus method does not returns the value set in the CB_AudioFileSpritesPool.LOADED property) nor unchecked (the CB_AudioFileSpritesPool#status method does not return the value set in the CB_AudioFileSpritesPool.UNCHECKED property).

Type
integer

clearAudioFiles( [avoidCallingCheckCacheLoaded]) → {array}

Cleans the arrays of the CB_AudioFile objects (taking off the undefined or null ones) which is in the CB_AudioFileCache#audioFiles property used by each CB_AudioFileSprites object, just keeping the valid ones and clearing (destroying and removing) the others. For performance purposes. Uses the CB_AudioFileSprites#clearAudioFiles method internally. Internal usage only recommended.

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

Used as the "avoidCallingCheckCacheLoaded" parameter when calling the CB_AudioFileSprites#clearAudioFiles method internally.

Source:
Returns:

Returns an object whose each property name is the sprites group ID and each value is the returning value of calling internally the CB_AudioFileSprites#clearAudioFiles method.

Type
array

clearSoundInstances( [clearWithObjectAssociated]) → {integer}

Clears the sound instances (created by the CB_AudioFileCache#play method) which have been cancelled. Uses the CB_AudioFileSprites#clearSoundInstances method internally.

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

Used as the "clearWithObjectAssociated" parameter when calling the CB_AudioFileSprites#clearSoundInstances method internally.

Source:
Returns:

Returns the number of cleared sound instances.

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_AudioFileSprites#destroyAll method internally.

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

Used as the "stopSounds" parameter when calling the CB_AudioFileSprites#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 pool object (removing all sprites, etc.), including the internal audio file sprites objects, and frees memory. By default, unless the "preventAbortedStatus" is set to true, sets the current status of all the CB_AudioFileCache objects as ABORTED (CB_AudioFileCache.ABORTED value). Internally, calls the CB_AudioFileSprites#destructor method of all the internally-created CB_AudioFileSprites objects.

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

Used as the "stopSounds" parameter when calling internally the CB_AudioFileSprites#destructor method of all the internally-created CB_AudioFileSprites objects.

preventAbortedStatus boolean <optional>
false

If set to true (not recommended), it will not assign the status of "ABORTED" (it will not set the CB_AudioFileSpritesPool#_aborted property to true}. Used as the "preventAbortedStatus" parameter when calling internally the CB_AudioFileSprites#destructor method of all the internally-created CB_AudioFileSprites objects.

Source:

errorFunction( [message] [, ignorePreviousExecution]) → {boolean}

Calls the error function which should be set in the CB_AudioFileSprites#onError property (if any), being "this" the CB_AudioFileSpritesPool object itself. Internal usage only recommended.

Parameters:
Name Type Argument Default Description
message string <optional>

The message describing the error that will be sent to the set CB_AudioFileSprites#onError function (if any) as the first and unique parameter.

ignorePreviousExecution boolean <optional>
false

If it is set to false, the function set in the CB_AudioFileSprites#onError property (if any) will only be called if it was not executed previously.

Source:
Returns:

Returns true if the CB_AudioFileSprites#onError function could be called or false otherwise.

Type
boolean

executeAll()

Source:
See:

executeAllSprites()

Source:
See:

executeAllSubSprites()

Alias for CB_AudioFileSpritesPool#executeFunctionAllSubSprites.

Source:
See:
  • CB_AudioFileSpritesPool#executeFunctionAllSubSprites

executeFunctionAll(functionEach [, delayBetweenEach] [, audioFiles] [, returnArrayOfSetTimeoutsArray] [, 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_AudioFileSprites#executeFunctionAll method internally.

Parameters:
Name Type Argument Default Description
functionEach CB_Arrays.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. Note that each call to the CB_AudioFileSprites#executeFunctionAll method will be performed sequentially one after the other, without adding a delay.

audioFiles array <optional>
CB_AudioFileCache#audioFiles

Used as the "audioFiles" parameter when calling the CB_AudioFileSprites#executeFunctionAll method internally.

returnArrayOfSetTimeoutsArray boolean <optional>
false

If it is set to false, it will return the number of calls to the "functionEach" function that were performed. Otherwise, if it is set to true, it will return a numeric array and each value (which will belong to each sprites group) will be another numeric array with a CB_AudioFileCache.executeFunctionAll_OBJECT object for each CB_AudioFile of that sprites group.

delayBetweenEachAffectsFirst boolean <optional>
false

Used as the "delayBetweenEachAffectsFirst" parameter when calling the CB_AudioFileSprites#executeFunctionAll method internally. Note that each call to the CB_AudioFileSprites#executeFunctionAll method will be performed sequentially one after the other, without adding a delay.

functionFinish CB_AudioFileSpritesPool.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 containing all the items which were 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:
To Do:
  • Think about consider executing only one by one (now it will loop CB_AudioFile objects from different sprites groups simultaneously).
Returns:

If the "returnArrayOfSetTimeoutsArray" parameter is set to false, it will return the number of calls to the "functionEach" function that were performed. Otherwise, if the "returnArrayOfSetTimeoutsArray" is set to true, it will return a numeric array and each value will be another numeric array with a CB_AudioFileCache.executeFunctionAll_OBJECT object for each CB_AudioFile given. 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] [, delayBetweenEachAffectsFirst] [, functionFinish]) → {integer}

Executes a desired function for all the CB_AudioFile objects used by all the sound instances currently created of each sprite group. It calls the CB_AudioFileSprites#executeFunctionAllSprites method internally.

Parameters:
Name Type Argument Default Description
functionEach CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK

Used as the "functionEach" parameter when calling the CB_AudioFileSprites#executeFunctionAllSprites method internally.

delayBetweenEach number | CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK <optional>
0

Used as the "delayBetweenEach" parameter when calling the CB_AudioFileSprites#executeFunctionAllSprites method internally. Note that each call to the CB_AudioFileSprites#executeFunctionAllSprites method will be performed sequentially one after the other, without adding a delay.

includeWithoutSpriteAssociated boolean <optional>
false

Used as the "includeWithoutSpriteAssociated" parameter when calling the CB_AudioFileSprites#executeFunctionAllSprites method internally.

avoidCancelled boolean <optional>
false

Used as the "avoidCancelled" parameter when calling the CB_AudioFileSprites#executeFunctionAllSprites method internally.

delayBetweenEachAffectsFirst boolean <optional>
false

Used as the "delayBetweenEachAffectsFirst" parameter when calling the CB_AudioFileSprites#executeFunctionAllSprites method internally. Internal usage only recommended. Note that each call to the CB_AudioFileSprites#executeFunctionAllSprites method will be performed sequentially one after the other, without adding a delay.

functionFinish CB_AudioFileSpritesPool.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 containing all the items which were 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:
To Do:
Returns:

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 of each sprites group). 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

forEach()

Source:
See:

forEachSprite()

Source:
See:

forEachSubSprite()

Alias for CB_AudioFileSpritesPool#executeFunctionAllSubSprites.

Source:
See:
  • CB_AudioFileSpritesPool#executeFunctionAllSubSprites

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_AudioFileSprites#getAudioFileBySoundInstanceId method internally.

Parameters:
Name Type Argument Default Description
soundInstanceId integer

Used as the "soundInstanceId" parameter when calling the CB_AudioFileSprites#getAudioFileBySoundInstanceId method internally.

avoidCancelled boolean <optional>
false

Used as the "avoidCancelled" parameter when calling the CB_AudioFileSprites#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] [, oneDimension]) → {Object|array}

Gets an object with arrays or a one-dimension array with all the CB_AudioFile objects. Uses the CB_AudioFileSprites#getAudioFiles method internally.

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

Used as the "copy" parameter when calling the CB_AudioFileSprites#getAudioFiles method internally.

oneDimension boolean <optional>
false

If it is set to true, the method will return an array with all the CB_AudioFile objects. Otherwise, if it is set to false, the method will return an object whose property names will be the ID of each sprites group and their value will be an array with all the CB_AudioFile objects that belong to that sprites group.

Source:
Returns:

If the "oneDimension" parameter is set to true, returns an array with all the CB_AudioFile objects. Otherwise, if the "oneDimension" parameter is set to false, it will return an object whose property names will be the ID of each sprites group and their value will be an array with all the CB_AudioFile objects that belong to that sprites group.

Type
Object | array

getAudioFilesBusy( [oneDimension]) → {Object|array}

Gets an object with arrays or a one-dimension array with the busy CB_AudioFile objects (the objects which are not available and ready to use). Uses the CB_AudioFileSprites#getAudioFilesBusy method internally.

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

If it is set to true, the method will return an array with the busy CB_AudioFile objects. Otherwise, if it is set to false, the method will return an object whose property names will be the ID of each sprites group and their value will be an array with the busy CB_AudioFile objects that belong to that sprites group.

Source:
Returns:

If the "oneDimension" parameter is set to true, returns an array with the busy CB_AudioFile objects. Otherwise, if the "oneDimension" parameter is set to false, it will return an object whose property names will be the ID of each sprites group and their value will be an array with the busy CB_AudioFile objects that belong to that sprites group.

Type
Object | array

getAudioFilesFree( [oneDimension]) → {Object|array}

Gets an object with arrays or a one-dimension array with the free CB_AudioFile objects (the objects which are available and ready to use). Uses the CB_AudioFileSprites#getAudioFilesFree method internally.

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

If it is set to true, the method will return an array with the free CB_AudioFile objects. Otherwise, if it is set to false, the method will return an object whose property names will be the ID of each sprites group and their value will be an array with the free CB_AudioFile objects that belong to that sprites group.

Source:
Returns:

If the "oneDimension" parameter is set to true, returns an array with the free CB_AudioFile objects. Otherwise, if the "oneDimension" parameter is set to false, it will return an object whose property names will be the ID of each sprites group and their value will be an array with the free CB_AudioFile objects that belong to that sprites group.

Type
Object | 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_AudioFileSprites#getAudioFilesFreeNumber method internally.

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_AudioFileSprites#getAudioFilesNumber method internally.

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

Used as the "real" parameter when calling the CB_AudioFileSprites#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 of all the sprites groups.

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

If set to false, it will return an object whose property names will be the ID of each sprites group and their value will be the 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#getAudioFilesUsed 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#getAudioFilesUsed method internally.

Source:
Returns:

Returns the CB_AudioFile objects used by all the sounds instances of all the sprites groups. If the "oneDimension" parameter is set to false, it will return a CB_AudioFileSpritesPool.getAudioFilesUsed_OBJECT object whose property names will be the ID of each sprites group and their value will be 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

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

Returns a number representing the percentage of the loading progress for the audio sprites pool 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_AudioFileSprites#getProgress method internally.

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

Used as the "countLoadedObjects" parameter when calling the CB_AudioFileSprites#getProgress method internally.

alsoUncheckedAndCheckingObjects boolean <optional>
false

Used as the "alsoUncheckedAndCheckingObjects" parameter when calling the CB_AudioFileSprites#getProgress method internally.

Source:
Returns:

Returns a number representing the percentage of the loading progress for the audio sprites pool 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 of each CB_AudioFileSprites object).

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

If set to false, it will return an object whose property names will be the ID of each sprites group and their value will be the CB_AudioFileSprites#spriteSoundInstances property of each CB_AudioFileSprites object (which includes the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated) which belongs to that sprites group. 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#getSoundInstancesId 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, it will return an object whose property names will be the ID of each sprites group and their value will be the CB_AudioFileSprites#spriteSoundInstances property of each CB_AudioFileSprites object (which includes the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated) which belongs to that sprites group. 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

getSprites( [includeWithoutSpriteAssociated] [, orderBySpritesGroup]) → {CB_AudioFileSprites.SPRITES_OBJECT|Object}

Returns an object with the sprites (and includes "_WITHOUT_SPRITE_ASSOCIATED" if we want to). Internally, uses the CB_AudioFileSprites#getSprites method.

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 "orderBySpritesGroup" parameter is set to true and 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 and the "orderBySpritesGroup" parameter is also set to false, the returning object will not contain the "_WITHOUT_SPRITE_ASSOCIATED" property. If set to false and the "orderBySpritesGroup" parameter is set to true, 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.

orderBySpritesGroup boolean <optional>
false

If set to false, it will return a CB_AudioFileSprites.SPRITES_OBJECT object whose properties will be the ID of each sprite (each sprite ID should be unique) and their value will be a CB_AudioFileSprites.SPRITE_OBJECT object. If set to true, it will return an object whose properties will be the ID of each sprites group and the value will be a CB_AudioFileSprites.SPRITES_OBJECT object which will include its sprites.

Source:
Returns:

If the "orderBySpritesGroup" is set to false, it will return a CB_AudioFileSprites.SPRITES_OBJECT object whose properties will be the ID of each sprite (each sprite ID should be unique) and their value will be a CB_AudioFileSprites.SPRITE_OBJECT object. If the "orderBySpritesGroup" is set to true, it will return an object whose properties will be the ID of each sprites group and the value will be a CB_AudioFileSprites.SPRITES_OBJECT object which will include its sprites.

Type
CB_AudioFileSprites.SPRITES_OBJECT | Object

getSpritesGroup(spritesGroupId [, withoutChecking]) → {CB_AudioFileSprites|undefined|*|null}

Returns a sprites group (the CB_AudioFileSprites object) by its ID.

Parameters:
Name Type Argument Default Description
spritesGroupId string

The identifier for the sprites group.

withoutChecking boolean <optional>
false

If set to true and the sprites group cannot be found, the method will return undefined (or whatever is stored by the given ID) instead of null.

Source:
Returns:

Returns null if the "withoutChecking" parameter is set to true and the sprites group cannot be found. Otherwise, it will return what is stored internally by the given ID which can be a CB_AudioFileSprites object if found or undefined (or whatever is stored by the given ID) if not found.

Type
CB_AudioFileSprites | undefined | * | null

getSpritesGroups() → {Object}

Returns an object with the sprites groups (all the internally-created CB_AudioFileSprites objects), being the name of each property their group ID and the value being the CB_AudioFileSprites object itself. Internally, it just returns the CB_AudioFileSpritesPool#audioFileSprites property.

Source:
Returns:

Returns an object with the sprites groups (all the internally-created CB_AudioFileSprites objects), being the name of each property their group ID and the value being the CB_AudioFileSprites object itself. Internally, it just returns the CB_AudioFileSpritesPool#audioFileSprites property.

Type
Object

getStatus() → {number}

Gets the current status of the audio file sprites pool object. Uses the CB_AudioFileSprites#getStatus method internally.

Source:
Returns:

Returns the current status of the audio file sprites pool object. It is a number, affected by the returning value of the CB_AudioFileSprites#getStatus method of each CB_AudioFileSprites object used internally, 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 pool object, as a string.

Source:
Returns:

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

Type
string

insertSpritesGroup(spritesGroupId [, dataObject] [, avoidCheckingLoaded]) → {boolean}

Inserts the given sprites group to the audio file sprites pool object.

Parameters:
Name Type Argument Default Description
spritesGroupId string

The identifier for the sprites group.

dataObject CB_AudioFileSprites.DATA_OBJECT <optional>

Object with the data of the sprites group. Optional but recommended.

avoidCheckingLoaded boolean <optional>
false

If set to true, it will not check whether all sprites groups has been loaded after inserting the desired one. This is done internally by the CB_AudioFileSpritesPool#_checkSpritesGroupsLoaded method which will fire the CB_AudioFileSpritesPool#onLoad function (if any).

Source:
Returns:

Returns true if the sprites group has been inserted or false otherwise.

Type
boolean

insertSpritesGroups(sprites) → {integer}

Inserts the given sprites groups.

Parameters:
Name Type Description
sprites CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT

Object with the desired sprites groups.

Source:
Returns:

Returns the number of sprites groups inserted.

Type
integer

isAudioFileFree(id) → {boolean}

Tells whether a desired CB_AudioFile object is free (it is in the CB_AudioFileCache#audioFilesFree property of any CB_AudioFileSprites object) 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_AudioFileSprites#isAudioFileFree method internally.

Parameters:
Name Type Description
id string

Used as the "id" parameter when calling the CB_AudioFileSprites#isAudioFileFree method internally.

Source:
Returns:

Returns whether a desired CB_AudioFile object is free (it is in the CB_AudioFileCache#audioFilesFree property of any CB_AudioFileSprites object) 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

isPlaying() → {boolean}

Tells whether any of the CB_AudioFile objects is playing or not. Uses the CB_AudioFileSprites#isPlaying method internally.

Source:
Returns:

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

Type
boolean

load(dataObject) → {CB_AudioFileSpritesPool|null}

Loads the audio file sprites pool 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_AudioFileSpritesPool.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_AudioFileSpritesPool object. Otherwise, it returns null.

Type
CB_AudioFileSpritesPool | null

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

Mutes all the existing CB_AudioFile objects or the desired ones (if provided). Uses the CB_AudioFileSprites#muteAll method internally.

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

Used as the "onMute" parameter when calling the CB_AudioFileSprites#muteAll method internally.

audioFiles array <optional>
CB_AudioFileCache#audioFiles

Used as the "audioFiles" parameter when calling the CB_AudioFileSprites#muteAll method internally.

Source:
Returns:

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

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_AudioFileSprites#pauseAll method internally.

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

Used as the "onPause" parameter when calling the CB_AudioFileSprites#pauseAll method internally.

audioFiles array <optional>
CB_AudioFileCache#audioFiles

Used as the "audioFiles" parameter when calling the CB_AudioFileSprites#pauseAll method internally.

Source:
Returns:

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

Type
integer

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_AudioFileSprites#playAll method internally.

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_AudioFileSprites#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_AudioFileSprites#playAll method internally.

loop boolean <optional>
CB_AudioFile#loop

Used as the "loop" parameter when calling the CB_AudioFileSprites#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_AudioFileSprites#playAll method internally.

avoidDelayedPlay boolean <optional>
false

Used as the "avoidDelayedPlay" parameter when calling the CB_AudioFileSprites#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_AudioFileSprites#playAll method internally.

onPlayStart function <optional>

Used as the "onPlayStart" parameter when calling the CB_AudioFileSprites#playAll method internally.

onStop function <optional>

Used as the "onStop" parameter when calling the CB_AudioFileSprites#playAll method internally.

includingPlaying boolean <optional>
false

Used as the "includingPlaying" parameter when calling the CB_AudioFileSprites#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_AudioFileSprites#playAndStopAll method internally.

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

Used as the "includingPlaying" parameter when calling the CB_AudioFileSprites#playAndStopAll method internally.

delayBeforeStop number <optional>
100

Used as the "delayBeforeStop" parameter when calling the CB_AudioFileSprites#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

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

Tries to purge the audio file cache of each CB_AudioFileSprites object 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. Note that the desired number is for each CB_AudioFileSprites object and not a global number. For performance purposes. Uses the CB_AudioFileSprites#purge method internally.

Parameters:
Name Type Argument Default Description
desiredNumber integer

Used as the "desiredNumber" parameter when calling the CB_AudioFileSprites#purge method internally. Note that the desired number is for each CB_AudioFileSprites object and not a global number.

setAsMinimumAudioFiles boolean <optional>
false

Used as the "setAsMinimumAudioFiles" parameter when calling the CB_AudioFileSprites#purge method internally.

includePlaying boolean <optional>
false

Used as the "includePlaying" parameter when calling the CB_AudioFileSprites#purge method internally.

stopSounds boolean <optional>
false

Used as the "stopSounds" parameter when calling the CB_AudioFileSprites#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_AudioFileSprites#purge method internally.

Source:
Returns:

Returns the number of CB_AudioFile objects removed.

Type
integer

removeSpritesGroup(spritesGroupId [, destroy] [, stopSounds] [, preventAbortedStatus]) → {boolean}

Removes a sprites group by its ID.

Parameters:
Name Type Argument Default Description
spritesGroupId string

The identifier for the sprites group.

destroy boolean <optional>
false

If set to true, it will call the CB_AudioFileSprites#destructor method of the CB_AudioFileSprites object which belongs to the desired sprites group.

stopSounds boolean <optional>
false

If the "destroy" parameter is set to false, this parameter will be ignored. Used as the "stopSound" parameter when calling internally the CB_AudioFileSprites#destructor method of the CB_AudioFileSprites object which belongs to the desired sprites group.

preventAbortedStatus boolean <optional>
false

If the "destroy" parameter is set to false, this parameter will be ignored. Used as the "preventAbortedStatus" parameter when calling internally the CB_AudioFileSprites#destructor method of the CB_AudioFileSprites object which belongs to the desired sprites group.

Source:
Returns:

Returns true if the sprites group has been deleted or false otherwise.

Type
boolean

removeSpritesGroups()

Removes all the sprites groups (CB_AudioFileSprites objects) by clearing the CB_AudioFileSpritesPool#audioFileSprites property.

Source:

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

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 ID if desired. Uses the CB_AudioFileSprites#resumeAll method internally. 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_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.

audioFiles array <optional>
CB_AudioFileCache#audioFiles

Used as the "audioFiles" parameter when calling the CB_AudioFileSprites#resumeAll method internally.

spriteId string <optional>
'_WITHOUT_SPRITE_ASSOCIATED'

Used as the "spriteId" when calling the CB_AudioFileSprites#resumeAll method internally. Internal usage only recommended.

Source:
Returns:

Returns an object whose property names will be the ID of each sprites group and their value will be the returning value of the internal call to the CB_AudioFileSprites#resumeAll method.

Type
Object

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_AudioFileSprites#setAudioAPIAll method internally.

Parameters:
Name Type Argument Default Description
preferredAPIs array | string

Used as the "preferredAPIs" parameter when calling the CB_AudioFileSprites#setAudioAPIAll method internally.

callbackOk CB_AudioFileSpritesPool.setAudioAPIAll_CALLBACK_OK <optional>

Function that will be called when all the process was performed successfully, being "this" the CB_AudioFileSpritesPool object.

callbackError CB_AudioFileSpritesPool.setAudioAPIAll_CALLBACK_ERROR <optional>

Function that will be called when any error happened, being "this" the CB_AudioFileSpritesPool object. This function will be called immediately if the method was previously called and it is still running currently.

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.

audioFiles array <optional>
CB_AudioFileCache#audioFiles

Used as the "audioFiles" 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.

Type
integer

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_AudioFileSprites#setVolumeAll method internally.

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_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.

audioFiles array <optional>
CB_AudioFileCache#audioFiles

Used as the "audioFiles" 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_AudioFileSprites#stopAll method internally.

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

Used as the "audioFiles" parameter when calling the CB_AudioFileSprites#stopAll method internally.

Source:
Returns:

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

Type
integer

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

Unmutes all the existing CB_AudioFile objects or the desired ones (if provided). Uses the CB_AudioFileSprites#unmuteAll method internally.

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

Used as the "onUnmute" parameter when calling the CB_AudioFileSprites#unmuteAll method internally.

audioFiles array <optional>
CB_AudioFileCache#audioFiles

Used as the "audioFiles" parameter when calling the CB_AudioFileSprites#unmuteAll method internally.

Source:
Returns:

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

Type
integer

Type Definitions


DATA_OBJECT

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

Type:
  • Object
Properties:
Name Type Argument Default Description
spritesGroups CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT <optional>

Object with the desired sprites groups, containing the CB_AudioFileSprites.DATA_OBJECT objects which will be used to create the CB_AudioFileSprites objects internally. Each group will have a CB_AudioFileSprites object. It will be used as the first parameter to call the CB_AudioFileSpritesPool#insertSpritesGroups method internally. Some of the missing properties ("preferredAPIs", "preferredFormats", "minimumAudioFiles", "maximumAudioFiles", "minimumAudioFilesFree", "newAudioFilesWhenNeeded", "retries", "checkManually", "checkManuallyOnNeededCreated", "checkManuallyOnPlayingFailed", "checkManuallyOnCheckingFailed" and "disableAutoLoad") of the CB_AudioFileSprites.DATA_OBJECT objects given will use the value set on the other properties of this object (if any).

id string <optional>
""

Desired identifier for the object. If a valid value is given, this will be added to the CB_AudioFileSpritesPool#id property.

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_AudioFileSpritesPool#preferredAPIs property. If the CB_AudioFileSprites.DATA_OBJECT object (defined in the CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT object set in the "spritesGroups") of a certain sprites group does not contain the "preferredAPIs" property, it will use the value of this property instead when creating its CB_AudioFileSprites object internally.

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_AudioFileSpritesPool#preferredFormats property. If the CB_AudioFileSprites.DATA_OBJECT object (defined in the CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT object set in the "spritesGroups") of a certain sprites group does not contain the "preferredFormats" property, it will use the value of this property instead when creating its CB_AudioFileSprites object internally.

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_AudioFileSpritesPool#minimumAudioFiles property. If the CB_AudioFileSprites.DATA_OBJECT object (defined in the CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT object set in the "spritesGroups") of a certain sprites group does not contain the "minimumAudioFiles" property, it will use the value of this property instead when creating its CB_AudioFileSprites object internally.

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_AudioFileSpritesPool#maximumAudioFiles property. If the CB_AudioFileSprites.DATA_OBJECT object (defined in the CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT object set in the "spritesGroups") of a certain sprites group does not contain the "maximumAudioFiles" property, it will use the value of this property instead when creating its CB_AudioFileSprites object internally.

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_AudioFileSpritesPool#minimumAudioFiles by default, rounded to ceil, allowing 0 (zero) minimum. If a valid value is given, this will be added to the CB_AudioFileSpritesPool#minimumAudioFilesFree property. If the CB_AudioFileSprites.DATA_OBJECT object (defined in the CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT object set in the "spritesGroups") of a certain sprites group does not contain the "minimumAudioFilesFree" property, it will use the value of this property instead when creating its CB_AudioFileSprites object internally.

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_AudioFileSpritesPool#minimumAudioFilesFree) is reached. If provided, it must be an integer being 0 (zero) the minimum. It will end using a 10% of the CB_AudioFileSpritesPool#minimumAudioFiles by default, rounded to ceil, allowing 1 minimum. If a valid value is given, this will be added to the CB_AudioFileSpritesPool#newAudioFilesWhenNeeded property. If the CB_AudioFileSprites.DATA_OBJECT object (defined in the CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT object set in the "spritesGroups") of a certain sprites group does not contain the "newAudioFilesWhenNeeded" property, it will use the value of this property instead when creating its CB_AudioFileSprites object internally.

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_AudioFileSpritesPool#retries property. If the CB_AudioFileSprites.DATA_OBJECT object (defined in the CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT object set in the "spritesGroups") of a certain sprites group does not contain the "retries" property, it will use the value of this property instead when creating its CB_AudioFileSprites object internally.

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_AudioFileSpritesPool#checkManually property. If the CB_AudioFileSprites.DATA_OBJECT object (defined in the CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT object set in the "spritesGroups") of a certain sprites group does not contain the "checkManually" property, it will use the value of this property instead when creating its CB_AudioFileSprites object internally.

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_AudioFileSpritesPool#checkManuallyOnNeededCreated property. If the CB_AudioFileSprites.DATA_OBJECT object (defined in the CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT object set in the "spritesGroups") of a certain sprites group does not contain the "checkManuallyOnNeededCreated" property, it will use the value of this property instead when creating its CB_AudioFileSprites object internally.

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_AudioFileSpritesPool#checkManuallyOnPlayingFailed property. If the CB_AudioFileSprites.DATA_OBJECT object (defined in the CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT object set in the "spritesGroups") of a certain sprites group does not contain the "checkManuallyOnPlayingFailed" property, it will use the value of this property instead when creating its CB_AudioFileSprites object internally.

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_AudioFileSpritesPool#checkManuallyOnCheckingFailed property. If the CB_AudioFileSprites.DATA_OBJECT object (defined in the CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT object set in the "spritesGroups") of a certain sprites group does not contain the "checkManuallyOnCheckingFailed" property, it will use the value of this property instead when creating its CB_AudioFileSprites object internally.

onLoad function <optional>

Desired function to be called once the pool 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_AudioFileSpritesPool object. If a valid value is given, this will be added to the CB_AudioFileSpritesPool#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_AudioFileSpritesPool object. If a valid value is given, this will be added to the CB_AudioFileSpritesPool#onError property. If a function is set, it will always be called through the CB_AudioFileSpritesPool#errorFunction method whenever the "onError" event of an internally-created CB_AudioFileSprites object is fired.

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. If the CB_AudioFileSprites.DATA_OBJECT object (defined in the CB_AudioFileSpritesPool.SPRITES_GROUPS_OBJECT object set in the "spritesGroups") of a certain sprites group does not contain the "disableAutoLoad" property, it will use the value of this property instead when creating its CB_AudioFileSprites object internally.

Source:

SPRITES_GROUPS_OBJECT

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

Type:
  • Object
Properties:
Name Type Description
spritesGroupId CB_AudioFileSprites.DATA_OBJECT

Being the name of each property the unique identifier of a sprites group which will use a future internally-created CB_AudioFileSprites object, the value will always be the CB_AudioFileSprites.DATA_OBJECT that the CB_AudioFileSprites object will use to be created (received by its constructor). Some of the missing properties ("preferredAPIs", "preferredFormats", "minimumAudioFiles", "maximumAudioFiles", "minimumAudioFilesFree", "newAudioFilesWhenNeeded", "retries", "checkManually", "checkManuallyOnNeededCreated", "checkManuallyOnPlayingFailed", "checkManuallyOnCheckingFailed" and "disableAutoLoad") will use the value set on the properties of the main CB_AudioFileSpritesPool.DATA_OBJECT object (if any) used by the CB_AudioFileSpritesPool object. If a function in the "onError" parameter is given, it will always be wrapped so the main error function set on the CB_AudioFileSpritesPool#onError parameter will always be called (if any) through the CB_AudioFileSpritesPool#errorFunction method.

Source:
Example
{	"sprites_group_id_1" : CB_AudioFileSprites.DATA_OBJECT,	"sprites_group_id_2" : CB_AudioFileSprites.DATA_OBJECT,	"sprites_group_id_3" : CB_AudioFileSprites.DATA_OBJECT,	...} 

checkPlayingAll_CALLBACK_ERROR(errorsObject, performedActions, uncheckedObjects)

Callback function used by the CB_AudioFileSpritesPool#checkPlayingAll method that will be called when not all was performed successfully.

Parameters:
Name Type Description
errorsObject Object

Object whose property names are the ID of each sprites group or "GENERAL_ERROR" if the error is not related to any sprites group and their value will be a CB_AudioFileSpritesPool.checkPlayingAll_CALLBACK_ERROR_OBJECT object.

performedActions integer

The number of CB_AudioFile objects that can be played).

uncheckedObjects integer | undefined

The number of CB_AudioFile objects that needed to be checked before calling this method (it will be undefined if it could not be determined).

Source:

checkPlayingAll_CALLBACK_ERROR_OBJECT

An object with errors, used by the CB_AudioFileSpritesPool.checkPlayingAll_CALLBACK_ERROR callback (used by the CB_AudioFileSpritesPool#checkPlayingAll method).

Type:
  • Object
Properties:
Name Type Description
error string

A string describing the error (if it was possible to be determined).

checked integer

The number of CB_AudioFile objects that can be played.

needed integer | undefined

The number of CB_AudioFile objects that needed to be checked before calling this method (it will be undefined if it could not be determined).

Source:

checkPlayingAll_CALLBACK_OK(performedActions, uncheckedObjects)

Callback function used by the CB_AudioFileSpritesPool#checkPlayingAll method that will be called when all the process was performed successfully.

Parameters:
Name Type Description
performedActions integer

The number of CB_AudioFile objects that can be played.

uncheckedObjects integer

The number of CB_AudioFile objects that needed to be checked before calling this method.

Source:

executeFunctionAll_ON_FINISH_CALLBACK(array, itemsAffected, delayMaximum)

Callback that is used when finishes all iterations after looping through the items. Being "this" an array with all the items.

Parameters:
Name Type Description
array array

An array with all the items which were being looped.

itemsAffected integer

The number of times that the "functionEach" callback was called (the most likely, matches the number of elements unless they are undefined or null).

delayMaximum integer

The maximum "delay" used.

Source:

getAudioFilesUsed_OBJECT

Object returned by the CB_AudioFileSpritesPool#getAudioFilesUsed method. Each property names will be the the ID of each sprites group and their value will be a CB_AudioFileSprites.getAudioFilesUsed_OBJECT object.

Type:
  • Object
Properties:
Name Type Description
spriteId CB_AudioFileSpritesPool.getAudioFilesUsed_OBJECT

Each property names will be the the ID of each sprites group and their value will be a CB_AudioFileSprites.getAudioFilesUsed_OBJECT object.

Source:

setAudioAPIAll_CALLBACK_ERROR(errorsObject, errorsHappened, objectsChangedAPI, performedActions, actionsNeeded)

Callback function used by the CB_AudioFileCache#setAudioAPIAll method that will be called when any error happened.

Parameters:
Name Type Description
errorsObject Object

Object whose property names are the ID of each sprites group or "GENERAL_ERROR" if the error is not related to any sprites group and their value will be a CB_AudioFileSpritesPool.setAudioAPIAll_CALLBACK_ERROR_OBJECT object each.

errorsHappened integer

The number of errors that happened, which could be greater than 1 if more than one internal call to the CB_AudioFile#setAudioAPI method failed.

objectsChangedAPI integer

The number of CB_AudioFile objects that actually changed its audio API.

performedActions integer

The number of CB_AudioFile objects that ended with a desired audio API, including those ones which were already using it.

actionsNeeded integer | undefined

The total number of CB_AudioFile objects that were considered to perform the action (it will be undefined if it could not be determined).

Source:

setAudioAPIAll_CALLBACK_ERROR_OBJECT

Object used by the CB_AudioFileSpritesPool.setAudioAPIAll_CALLBACK_ERROR callback. Unless it belongs to a general error, its information will only be regarding a certain sprites group.

Type:
  • Object
Properties:
Name Type Description
error string

A string describing the error, if it was possible to be determined.

errors integer

The number of errors that happened, which could be greater than 1 if more than one internal call to the CB_AudioFile#setAudioAPI method failed.

changed integer

The number of objects that actually changed its audio API.

performed integer

The number of CB_AudioFile objects that ended with a desired audio API, including those ones which were already using it.

needed integer | undefined

The total number of CB_AudioFile objects that were considered to perform the action (it will be undefined if it could not be determined).

Source:

setAudioAPIAll_CALLBACK_OK(objectsChangedAPI, performedActions, actionsNeeded)

Callback function used by the CB_AudioFileSpritesPool#setAudioAPIAll method that will be called when all the process was performed successfully.

Parameters:
Name Type Description
objectsChangedAPI integer

The number of CB_AudioFile objects that actually changed its audio API.

performedActions integer

The number of CB_AudioFile objects that ended with a desired audio API, including those ones which were already using it.

actionsNeeded integer

The total number of CB_AudioFile objects that were considered to perform the action (it will be undefined if it could not be determined).

Source: