CrossBrowdy API documentation

Class: CB_AudioFileCache

CB_AudioFileCache

Class to manage a cache with multiple CB_AudioFile objects (they should be the same sound although they can be in different formats). This is not only useful for performance purposes but also for being able to play the same sound simultaneously and multiple times in different audio APIs and clients.

new CB_AudioFileCache( [dataObject]) → {CB_AudioFileCache}

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

Object with the desired data and options for the audio files cache.
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_AudioFileCache object.

Type
CB_AudioFileCache

Members

<constant> DEFAULT_VOLUME :number

Keeps the default volume. If the CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_USE_SPEAKER_VOLUME_AS_DEFAULT property is true, this will keep the result of calling the CB_Speaker.getVolume function. Otherwise, it will use the value of the CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME variable.

Type:
  • number
Default Value:
  • CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_USE_SPEAKER_VOLUME_AS_DEFAULT ? CB_Speaker.getVolume() : CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME
Source:

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

Type:
Source:

<readonly> audioFiles :array

Numeric array containing all the CB_AudioFile objects created internally. Internal usage only recommended.

Type:
  • array
Default Value:
  • []
Source:

<readonly> audioFilesCreated :integer

Total number of CB_AudioFile objects created internally (optimization purposes, to avoid using CB_AudioFileCache#audioFiles.length). Internal usage only recommended.

Type:
  • integer
Source:

<readonly> audioFilesFree :array

Stack that stores the indexes (belonged to the CB_AudioFileCache#audioFiles array) of the free CB_AudioFile objects. Internal usage only recommended.

Type:
  • array
Default Value:
  • []
Source:

<readonly> audioFilesFreePointer :integer

Pointer for the CB_AudioFileCache#audioFilesFree stack (for optimization purposes). Internal usage only recommended.

Type:
  • integer
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> duration :number

Stores the minimum duration found among all the CB_AudioFile objects. Internal usage only recommended.

Type:
  • number
Default Value:
  • 0
Source:

<readonly> durationMaximum :number

Stores the maximum duration found among all the CB_AudioFile objects. Internal usage only recommended.

Type:
  • number
Default Value:
  • 0
Source:

<readonly> id :string

Stores the identifier for the audio files cache.

Type:
  • string
Source:

<readonly> maximumAudioFiles :integer|null

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

Type:
  • function
Source:

<readonly> onLoad :function

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

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:

<readonly> soundInstancesQueued :Object

Object with sound instance identifiers (integers created by the CB_AudioFileCache#play method) which are going to play (this way we can cancel the sound before it starts playing). Each property name is the identifier of the sound instance and the value will be an object with "cancelled" (boolean, to know whether the sound instance was cancelled or not) and "object" (containing the CB_AudioFile object used) properties. Internal usage only recommended.

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

<readonly> status :integer

Tells whether the cache is unloaded (CB_AudioFileCache.UNLOADED), loading (CB_AudioFileCache.LOADING), unchecked (CB_AudioFileCache.UNCHECKED), checking (CB_AudioFileCache.CHECKING), loaded (CB_AudioFileCache.LOADED), failed (CB_AudioFileCache.FAILED) or aborted (CB_AudioFileCache.ABORTED).

Type:
  • integer
Default Value:
Source:

<static, constant> ABORTED :integer

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

Type:
  • integer
Default Value:
  • 6
Source:

<static, constant> CHECKING :integer

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

Type:
  • integer
Default Value:
  • 3
Source:

<static, constant> FAILED :integer

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

Type:
  • integer
Default Value:
  • 5
Source:

<static, constant> LOADED :integer

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

Type:
  • integer
Default Value:
  • 4
Source:

<static, constant> LOADING :integer

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

Type:
  • integer
Default Value:
  • 1
Source:

<static, constant> UNCHECKED :integer

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

Type:
  • integer
Default Value:
  • 2
Source:

<static, constant> UNLOADED :integer

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

Type:
  • integer
Default Value:
  • 0
Source:

<static, constant> checkManuallyOnCheckingFailed_DEFAULT :boolean

Default value for the CB_AudioFileCache#checkManuallyOnCheckingFailed property.

Type:
  • boolean
Default Value:
  • false
Source:

<static, constant> checkManuallyOnNeededCreated_DEFAULT :boolean

Default value for the CB_AudioFileCache#checkManuallyOnNeededCreated property.

Type:
  • boolean
Default Value:
  • false
Source:

<static, constant> checkManuallyOnPlayingFailed_DEFAULT :boolean

Default value for the CB_AudioFileCache#checkManuallyOnPlayingFailed property.

Type:
  • boolean
Default Value:
  • false
Source:

<static, constant> checkManually_DEFAULT :boolean

Default value for the CB_AudioFileCache#checkManually property.

Type:
  • boolean
Default Value:
  • false
Source:

<static, constant> maximumAudioFiles_DEFAULT :integer|null

Default value for the CB_AudioFileCache#maximumAudioFiles property.

Type:
  • integer | null
Default Value:
  • null
Source:

<static, constant> minimumAudioFiles_DEFAULT :integer

Default value for the CB_AudioFileCache#minimumAudioFiles property.

Type:
  • integer
Default Value:
  • 2
Source:

<static, constant> retries_DEFAULT :integer

Default value for the CB_AudioFileCache#retries property.

Type:
  • integer
Default Value:
  • 1
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.

Parameters:
Name Type Argument Default Description
soundInstanceId integer

The identifier (integer) of the sound instance we want to affect.
cancel boolean <optional>
 false

Defines whether we want to cancel it or enable it.
affectWithObjectAssociated boolean <optional>
 false

If set to true, it will also affect the sound instance even it has a CB_AudioFile object associated.
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).

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

Defines whether we want to cancel them or enable them.
affectWithObjectAssociated boolean <optional>
 false

If set to true, it will also affect the sound instances which have a CB_AudioFile object associated.
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. 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>

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_AudioFileCache object itself.
callbackError CB_AudioFileCache.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_AudioFileCache 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 internally as the "ignoreQueue" parameter when calling the CB_AudioFile#checkPlaying method of each CB_AudioFile object.
Source:
To Do:
  • Think about implementing an "audioFiles" parameter.
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) nor unchecked (the CB_AudioFileCache#status property does not belong to the value set in the CB_AudioFileCache.UNCHECKED 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. Internal usage only recommended.

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

If set to false and neither the CB_AudioFileCache#checkPlayingAll nor the CB_AudioFileCache#setAudioAPIAll methods are being executed, it will call the CB_AudioFileCache#_checkCacheLoaded internal method which will call the "onLoad" function defined in the CB_AudioFileCache#onLoad property if the number of needed CB_AudioFile objects has been reached (after performing the cleaning process). Internal usage only recommended.
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.

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

If set to true, it will also clear the sound instances which have a CB_AudioFile object associated.
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). This method is already called by the CB_AudioFileCache#createAudioFiles method and other methods 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. Internal usage only recommended.

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

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. It will try to calculate and use the best audio format for the current client and 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.
preferredAPIs array <optional>
 CB_AudioFileCache#preferredAPIs

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.
preferredFormats array <optional>
 CB_AudioFileCache#preferredFormats

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.
audioObject CB_AudioFile <optional>

A CB_AudioFile object that we want to reuse instead of creating a new one (for performance purposes).
callbackOk function <optional>

Function with no parameters that will be called once the CB_AudioFile object is created and loaded successfully (or after it has been checked successfully, depending on the desired option), being "this" the CB_AudioFileCache object itself.
callbackError function <optional>

Function called when any error is produced during creation, loading or checking process, etc. The unique parameter will be a string describing the error (if it was possible to be determined), being "this" the CB_AudioFileCache object itself.
storeURIsList boolean <optional>
 false

If set to true, it will store internally the valid supported "URIs" from the given ones (needed by the CB_AudioFileCache#setAudioAPIAll method, for example). Internal usage only recommended.
checkAutomatically boolean <optional>
 false

If set to true (not recommended), it will call the CB_AudioFile#checkPlaying method automatically. Otherwise, it will perform according to the value set at the CB_AudioFileCache#checkManually property. Internal usage only recommended.
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 [, setAsLoaded]) → {integer}

Creates the desired number of internal CB_AudioFile objects (inside the CB_AudioFileCache#audioFiles property). This method is already called by the CB_AudioFileCache#load method automatically (unless the "disableAutoLoad" property has been set to true in the "dataObject" given). 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 Default Description
minimumAudioFiles integer

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.
setAsLoaded boolean <optional>
 false

If the CB_AudioFile objects already created internally (before calling this method) does not reach the number given in the "minimumAudioFiles", this parameter will be ignored. Otherwise, if set to true, it will set the CB_AudioFileCache.status property as "LOADED" (the value of the CB_AudioFileCache#LOADED property) after reaching the desired number. If set to false, the CB_AudioFileCache.status property will be set as "LOADED" CB_AudioFileCache#LOADED property) if the CB_AudioFileCache#checkManually property is set to true or set as "UNCHECKED" if the CB_AudioFileCache#checkManually property is set to false. Internal usage only recommended.
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).

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

Used internally as the "stopSound" parameter when calling the CB_AudioFile#destructor method of each CB_AudioFile object.
Source:
To Do:
  • Think about implementing an "audioFiles" parameter.
Returns:

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

Type
integer

destructor( [stopSounds] [, preventAbortedStatus])

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

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

Used as the "stopSound" parameter when calling internally the CB_AudioFile#destructor method for all the CB_AudioFile objects.
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:

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

Calls the error function which should be set in the CB_AudioFileCache#onError property (if any), being "this" the CB_AudioFileCache 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_AudioFileCache#onError function (if any) as the first and unique parameter.
avoidFailing boolean <optional>
 false

If set to true, it will not set the CB_AudioFileCache#status property to "FAILED" (the value of the CB_AudioFile#FAILED property).
Source:
Returns:

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

Type
boolean

executeAll()

Alias for CB_AudioFileCache#executeFunctionAll.

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). Calls the CB_Arrays.executeFunctionAll function internally and returns its returning value.

Parameters:
Name Type Argument Default Description
functionEach CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK

Function that will be called for each CB_AudioFile object. As the first parameter it receives the CB_AudioFile object of the "audioFiles" being looped, as the second parameter the position of this CB_AudioFile object in the "audioFiles" array provided (or, if not provided, in the array of the CB_AudioFileCache#audioFiles property), the third parameter is the array being looped and the fourth parameter will be the "delayBetweenEach" being used, being "this" the CB_AudioFile object itself.
delayBetweenEach number | CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK <optional>
 0

If a value greater than zero is used, it will be used as the delay desired between each call to the "functionEach" function (calling them using the setTimeout function internally). If not provided or the value is 0 (zero) or lower, each call to the "functionEach" function will be performed immediately one after the other. If a function is provided, it will be called with the same parameters as the "functionEach" function and its returning value will be used as the delay (executed every loop for each CB_AudioFile object).
audioFiles array <optional>
 CB_AudioFileCache#audioFiles

A numeric array containing the CB_AudioFile objects that we want to loop. It should contain only CB_AudioFile objects which are already in the current audio file cache. If not provided, it will use all the CB_AudioFile objects contained in the cache.
returnSetTimeoutsArray boolean <optional>
 false

Defines whether we want the method to return an integer or a numeric array with information of each setTimeout call. Returning an array with information of each setTimeout call is only useful when the setTimeout function is called internally, which happens when the "delayBetweenEach" parameter is greater than 0 (zero).
delayBetweenEachAffectsFirst boolean <optional>
 false

If set to true, the desired delay (if any) will also affect the first call to the "functionEach" function.
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:
To Do:
  • Think about only allowing CB_AudioFile objects (in the "audioFiles" parameter) which are already in the cache (identify them by their ID), to avoid problems.
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

forEach()

Alias for CB_AudioFileCache#executeFunctionAll.

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.

Parameters:
Name Type Argument Default Description
soundInstanceId integer

The identifier (integer) of the sound instance we want to get.
avoidCancelled boolean <optional>
 false

If set to true, it will not return the CB_AudioFile object if its sound instance has been cancelled.
Source:
Returns:

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

Type
CB_AudioFile | null

getAudioFilePosition(id) → {integer}

Tells the position of a desired CB_AudioFile object (by its identifier) in the CB_AudioFileCache#audioFiles property or -1 otherwise.

Parameters:
Name Type Description
id string

The identifier of the CB_AudioFile object (belongs to its CB_AudioFile#id property) whose position we want to find. Note that the identifier is not case sensitive and it should be unique for each object.
Source:
Returns:

Returns the position of a desired CB_AudioFile object (by its identifier) in the CB_AudioFileCache#audioFiles property or -1 otherwise.

Type
integer

getAudioFiles( [copy]) → {array}

Gets an array with all the CB_AudioFile objects.

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

If set to true, instead of returning the CB_AudioFileCache#audioFiles property directly, it will return a new copy of it.
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).

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

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

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.

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

If set to true, instead of returning the value of the CB_AudioFileCache#audioFilesCreated property, it will return the value of the "length" property of the CB_AudioFileCache#audioFiles array which are the real number of CB_AudioFile objects used. If all went well, the returning value should be always the same regardless of this parameter.
Source:
Returns:

Returns the number of CB_AudioFile objects created.

Type
integer

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.

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

If set to true, instead of returning the value of the CB_AudioFileCache#duration property (which belongs to the minimum duration found among all the CB_AudioFile objects), it will return the value of CB_AudioFileCache#durationMaximum property (which belongs to the maximum duration found among all the CB_AudioFile objects).
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.

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

If set to true, the CB_AudioFile object will also be "popped" (removed) from the CB_AudioFileCache#audioFilesFree property.
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 cache (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.

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

If set to true, it will count the CB_AudioFile objects whose CB_AudioFile#getStatus method returns "LOADED" (the value of the CB_AudioFile#LOADED property), instead of just using the array's "length" of the CB_AudioFileCache#audioFiles property.
alsoUncheckedAndCheckingObjects boolean <optional>
 false

If set to true and the "countLoadedObjects" parameter is also true, it will also count the CB_AudioFile objects whose CB_AudioFile#getStatus method returns "UNCHECKED" (the value of the CB_AudioFile#UNCHECKED property) or "CHECKING" (the value of the CB_AudioFile#CHECKING property). If the "countLoadedObjects" parameter is false, this parameter will be ignored.
Source:
To Do:
Returns:

Returns a number representing the percentage of the loading progress for the audio file cache (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

getStatus() → {number}

Gets the current status of the audio file cache.

Source:
Returns:

Returns the current status of the audio file cache. 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 cache, as a string.

Source:
Returns:

Returns the current status of the audio file cache, 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

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.

Parameters:
Name Type Description
id string

The identifier of the CB_AudioFile object (belongs to its CB_AudioFile#id property) that we want to check. Note that the identifier is not case sensitive and it should be unique for each object.
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

isAudioFileFreeByPosition(position) → {boolean}

Tells whether a given numeric position of a CB_AudioFile object in the CB_AudioFileCache#audioFiles property is stored in the CB_AudioFileCache#audioFilesFree property or not (this means that the CB_AudioFile object in that position of the CB_AudioFileCache#audioFiles property is free). A free CB_AudioFile object is an object which is not being used and it is available to be used.

Parameters:
Name Type Description
position integer

Position of the CB_AudioFile object in the CB_AudioFileCache#audioFiles property that we want to check whether it is in the CB_AudioFileCache#audioFilesFree property or not.
Source:
Returns:

Returns whether the given numeric position of a CB_AudioFile object in the CB_AudioFileCache#audioFiles property is stored in the CB_AudioFileCache#audioFilesFree property or not (this means that the CB_AudioFile object in that position of the CB_AudioFileCache#audioFiles property is free). 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. It uses the CB_AudioFile#isPlaying method internally.

Source:
Returns:

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

Type
boolean

load(dataObject) → {CB_AudioFileCache|null}

Loads the audio file cache 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_AudioFileCache.DATA_OBJECT

Object with the desired data and options for the audio files cache.
Source:
Returns:

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

Type
CB_AudioFileCache | null

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

Mutes all the existing CB_AudioFile objects or the desired ones (if provided). It uses the CB_AudioFile#mute method internally.

Parameters:
Name Type Argument Default Description
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_AudioFile#mute method.
audioFiles array <optional>
 CB_AudioFileCache#audioFiles

A numeric array containing the CB_AudioFile objects that we want to affect. It should contain only CB_AudioFile objects which are already in the current audio file cache. If not provided, it will use all the CB_AudioFile objects contained in the cache.
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

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.

Parameters:
Name Type Argument Default Description
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_AudioFile#pause method of the CB_AudioFile object.
audioFiles array <optional>
 CB_AudioFileCache#audioFiles

A numeric array containing the CB_AudioFile objects that we want to affect. It should contain only CB_AudioFile objects which are already in the current audio file cache. If not provided, it will use all the CB_AudioFile objects contained in the cache.
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

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

Plays a sound of the cache (if there is any free). 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).

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

Time in milliseconds where we want the audio to start at. If not provided or it is not a valid number, it will use zero (0) as default which belongs to the beginning of the audio. If the value provided is greater than the "stopAt" provided, it will use the value set in the "lastStartAt" property of the used audio API object (which belongs to the "startAt" value the last time that the "play" method was called). If, even using the "lastStartAt" value is still greater than the "stopAt" provided, it will use the same value as the "stopAt" which means it will not play and will stop immediately. Used internally as the "startAt" parameter to call the CB_AudioFile#play method of the free CB_AudioFile object (if any).
stopAt number <optional>
 CB_AudioFile_API.WAAPI#getDuration() | CB_AudioFile_API.SM2#getDuration() | CB_AudioFile_API.ACMP#getDuration() | CB_AudioFile_API.AAPI#getDuration()

Time in milliseconds where we want the audio to stop at. If not provided or it is not a valid number, it will use the returning value of the "getDuration" method of the used audio API object (which should belong to the total duration of the audio, if it was calculated correctly). Used internally as the "stopAt" parameter to call the CB_AudioFile#play method of the free CB_AudioFile object (if any).
loop boolean <optional>
 CB_AudioFile#loop

Sets whether we want to play the audio looping (starting again and again) or just play it once. Used internally as the "loop" parameter to call the CB_AudioFile#play method of the free CB_AudioFile object (if any).
volume number <optional>
 CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_USE_SPEAKER_VOLUME_AS_DEFAULT ? CB_Speaker.getVolume() : CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME

Desired volume to play the audio. Used internally as the "volume" parameter to call the CB_AudioFile#setVolume method of the free CB_AudioFile object (if any), before playing it.
allowedRecursiveDelay boolean <optional>
 CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT

The maximum amount of time (in milliseconds) of delay that we accept before start playing the audio. If the amount of time is overcome, the audio will not play at all. Used only when the audio is not able to play immediately.
allowedRecursiveDelaySkipping boolean <optional>
 stopAt-startAt

If provided (uses milliseconds) and the time expired trying to start playing the sound without success is still inside this amount of time provided, it will try to play the sound but skipping the part of the audio which should have already been played already. In other words, it will try to start playing the sound as if the previous non-played part (which should have been playing during the time which already expired) was already being playing silently. Only used when the time set in the "allowedRecursiveDelay" parameter has been reached and the audio did not start playing yet. The default value is the duration of the sound that we want to play (having in mind the real value of the "startAt" and "stopAt" parameters which are calculated internally and can be different from the provided ones in the case that they had any error).
onPlayStart function <optional>

Function to be called when the audio starts playing successfully. The function will be called with the following parameters (in order): "soundInstanceId" (the identifier of the sound instance used), "startAt", "stopAt", "startAtNextLoop", "loop", "avoidDelayedPlay", "allowedRecursiveDelay" and "startPlayingTime", being "this" the CB_AudioFile object used (if any). Used internally as the "onPlayStart" parameter (wrapped in another function) to call the CB_AudioFile#play method of the free CB_AudioFile object (if any).
onStop function <optional>

Function to call when the sound stops playing, with an unique parameter which belongs to the "soundInstanceId" (the identifier of the sound instance used), being "this" the CB_AudioFile object (if any). Used internally as the "callbackFunction" parameter (wrapped in a function) to call the CB_AudioFile#onStop method of the free CB_AudioFile object (if any), before playing it.
startPlayingTime number <optional>
 CB_Device.getTiming()

Used internally to calculate the amount of time (in milliseconds) expired without playing the sound. Internal usage only recommended.
startAtOriginal number <optional>
 startAt

Used internally to start playing the sound accurately and skipping the part which could not be played before, if the time expired without being played is still inside the amount of time provided in the "allowedRecursiveDelaySkipping" parameter. Internal usage only recommended.
soundInstanceId integer <optional>
 CB_AudioFileCache._soundInstanceIdUnique++

The identifier of the sound instance that will be played. Used internally when the function is called recursively in the case that the sound could not be played immediately. Internal usage only recommended.
_callRecursivelyIfNotTooLateCalledObject Object <optional>

Object with just the "called" property (boolean). Used internally to know whether the current execution thread called already the _callRecursivelyIfNotTooLate internal method for the same sound instance or not. Internal usage only recommended.
Source:
Returns:

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). It does not create sound instances.

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

Time in milliseconds where we want the audio to start at. If not provided or it is not a valid number, it will use zero (0) as default which belongs to the beginning of the audio. If the value provided is greater than the "stopAt" provided, it will use the value set in the "lastStartAt" property of the used audio API object (which belongs to the "startAt" value the last time that the "play" method was called). If, even using the "lastStartAt" value is still greater than the "stopAt" provided, it will use the same value as the "stopAt" which means it will not play and will stop immediately. Used internally as the "startAt" parameter to call the CB_AudioFile#play method of the CB_AudioFile object.
stopAt number <optional>
 CB_AudioFile_API.WAAPI#getDuration() | CB_AudioFile_API.SM2#getDuration() | CB_AudioFile_API.ACMP#getDuration() | CB_AudioFile_API.AAPI#getDuration()

Time in milliseconds where we want the audio to stop at. If not provided or it is not a valid number, it will use the returning value of the "getDuration" method of the used audio API object (which should belong to the total duration of the audio, if it was calculated correctly). Used internally as the "stopAt" parameter to call the CB_AudioFile#play method of the CB_AudioFile object.
loop boolean <optional>
 CB_AudioFile#loop

Sets whether we want to play the audio looping (starting again and again) or just play it once. Note that at the end of each loop the "onStop" function defined will not be called. Used internally as the "loop" parameter to call the CB_AudioFile#play method of the CB_AudioFile object.
volume number <optional>
 CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_USE_SPEAKER_VOLUME_AS_DEFAULT ? CB_Speaker.getVolume() : CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME

Desired volume to play the audio. Used internally as the "volume" parameter to call the CB_AudioFile#setVolume method of the CB_AudioFile object, before playing it.
avoidDelayedPlay boolean <optional>
 false

If set to false (recommended) and the audio failed previously or was aborted (destroyed), it will try to load it correctly again automatically and play it after that if possible (this can take some time so the audio could start playing after a delay). Otherwise, if set to true and the audio failed or was aborted (destroyed), the audio will not play at all and the "stop" method of the audio file object will be called immediately. Used internally as the "avoidDelayedPlay" parameter to call the CB_AudioFile#play method of the CB_AudioFile object.
allowedRecursiveDelay boolean <optional>
 CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT

The maximum amount of time (in milliseconds) of delay that we accept before start playing the audio. If the amount of time is overcome, the audio will not play at all and the "stop" method will be called immediately. Used only when the "avoidDelayedPlay" parameter is set to false and the audio needs to be loaded because it failed previously or was aborted (destroyed). Used internally as the "allowedRecursiveDelay" parameter to call the CB_AudioFile#play method of the CB_AudioFile object.
onPlayStart function <optional>

Function to be called when the audio starts playing successfully. The function will be called with the following parameters (in order): "startAt", "stopAt", "startAtNextLoop", "loop", "avoidDelayedPlay", "allowedRecursiveDelay" and "startPlayingTime", being "this" the CB_AudioFile object. Used internally as the "onPlayStart" parameter to call the CB_AudioFile#play method of the CB_AudioFile object.
onStop function <optional>

Function that will be called each time that a CB_AudioFile object stops playing. Used internally as the "callbackFunction" parameter to call the CB_AudioFile#onStop method of the CB_AudioFile object, before playing it.
includingPlaying boolean <optional>
 false

If set to true, it will call the CB_AudioFile#play method even for those CB_AudioFile objects which are currently playing.
Source:
To Do:
  • Think about implementing an "audioFiles" parameter.
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.

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

If set to true, it will call the CB_AudioFile#play method even for those CB_AudioFile objects which are currently playing.
delayBeforeStop number <optional>
 100

Delay (in milliseconds) before stopping the audio, that will be used as the second parameter of the setTimeout function when calling the CB_AudioFileCache#stopAll method.
Source:
To Do:
  • Think about implementing an "audioFiles" parameter.
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 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.

Parameters:
Name Type Argument Default Description
desiredNumber integer

The desired number of internal CB_AudioFile objects that we want to keep in the CB_AudioFileCache#audioFiles property. It mus be 1 or greater.
setAsMinimumAudioFiles boolean <optional>
 false

If set to true, it will set the value of the "desiredNumber" parameter to the CB_AudioFileCache#minimumAudioFiles property (only when there is a maximum defined in CB_AudioFileCache#maximumAudioFiles).
includePlaying boolean <optional>
 false

If it is set to true and removing non-playing CB_AudioFile objects was not enough to reach the desired number (defined in the "desiredNumber" parameter), it will also try to remove objects which are being playing currently.
stopSounds boolean <optional>
 false

Used as the "stopSound" parameter when calling the CB_AudioFile#destructor method of each CB_AudioFile object removed.
statuses array <optional>
 Array(CB_AudioFile.LOADING, CB_AudioFile.UNCHECKED, CB_AudioFile.CHECKING, CB_AudioFile.LOADED)

Numeric array containing the statuses of the CB_AudioFile objects that we want this method to authorize to remove. This means that if the returning value of the CB_AudioFile#getStatus method of a CB_AudioFile object is not in this list, it will not be tried to be removed (unless they end removed by the CB_AudioFileCache#clearAudioFiles method called internally). Have in mind that this method will call the CB_AudioFileCache#clearAudioFiles method internally, which destroys the CB_AudioFile objects whose CB_AudioFile#getStatus method returns CB_AudioFile.ABORTED and CB_AudioFile.FAILED, so these two statuses need not be indicated. It will respect the order given. Possible values for this array are: CB_AudioFile.UNLOADED, CB_AudioFile.LOADING, CB_AudioFile.UNCHECKED, CB_AudioFile.CHECKING, CB_AudioFile.LOADED, CB_AudioFile.FAILED and CB_AudioFile.ABORTED.
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). Internal usage only recommended.

Parameters:
Name Type Argument Default Description
audioObjectOrId CB_AudioFile | string

The CB_AudioFile object or a string with its identifier (not case sensitive) that we want to remove from the CB_AudioFileCache#audioFiles property. If a CB_AudioFile object is given, its CB_AudioFile#id property (which should be unique always) must be set as it is used to identify the object. 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).
reload boolean <optional>
 false

If it is set to true, the CB_AudioFileCache#createAudioFile method will be called automatically at the end of the process. If a CB_AudioFile object has been given (through the "audioObjectOrId" parameter) or found by its identifier, it will be tried to be reused by the CB_AudioFileCache#createAudioFile method (as its "audioObject" parameter).
checkManually boolean <optional>
 false

Only used when the "reload" parameter is set to true, to calculate the "checkAutomatically" parameter when calling the CB_AudioFileCache#createAudioFile method internally.
Source:
To Do:
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 the number of internal CB_AudioFile objects (inside the CB_AudioFileCache#audioFiles property) has decreased or false otherwise.

Type
boolean | CB_AudioFile | null

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

Resumes all the existing CB_AudioFile objects or the desired ones (if provided), which are paused (and not stopped). It uses the CB_AudioFileCache#play method internally.

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

Used internally as the "loop" parameter to call the CB_AudioFileCache#play method.
allowedRecursiveDelay boolean <optional>
 CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT

Used internally as the "allowedRecursiveDelay" parameter to call the CB_AudioFileCache#play method.
allowedRecursiveDelaySkipping boolean <optional>
 CB_AudioFile#lastStopAt-CB_AudioFile#lastStartAt

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

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

Used internally as the "onStop" parameter to call the CB_AudioFileCache#play method.
audioFiles array <optional>
 CB_AudioFileCache#audioFiles

A numeric array containing the CB_AudioFile objects that we want to affect. It should contain only CB_AudioFile objects which are already in the current audio file cache. If not provided, it will use all the CB_AudioFile objects contained in the cache.
Source:
Returns:

Returns a numeric array containing all the return values of each internal call to the CB_AudioFileCache#play method.

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). Uses the CB_AudioFile#setAudioAPI method internally. 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.

Parameters:
Name Type Argument Default Description
preferredAPIs array | string

Array of strings with the preferred audio API or audio APIs, in order of preference. It also accepts a string with only one audio API. If more than one audio API is provided and setting an audio API fails for a CB_AudioFile object, it will try setting the next one and so on (this means that some of the CB_AudioFile objects could end with a different audio API). Possible audio APIs are "WAAPI" (HTML5 Web Audio API), "SM2" (SoundManager 2), "ACMP" (Apache Cordova Media Plugin) or "AAPI" (HTML5 Audio API).
callbackOk CB_AudioFileCache.setAudioAPIAll_CALLBACK_OK <optional>

Function that will be called when all the process was performed successfully, being "this" the CB_AudioFileCache object.
callbackError CB_AudioFileCache.setAudioAPIAll_CALLBACK_ERROR <optional>

Function that will be called when any error happened, being "this" the CB_AudioFileCache object. This function will be called immediately if the method was previously called and it is still running currently.
mandatory boolean <optional>
 false

If set to true and any CB_AudioFile object could not perform successfully any call to its CB_AudioFile#setAudioAPI method for all desired audio APIs provided in the "preferredAPIs" parameter (this means that, internally, all the CB_AudioFile#setAudioAPI calls, one per desired audio API, have fired an error by calling the function defined in its "callbackError" parameter), the audio file cache will be set as "FAILED" (the CB_AudioFileCache#status property will be set to the value of CB_AudioFileCache.FAILED).
forceReload string <optional>
 false

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

A numeric array containing the CB_AudioFile objects that we want to affect. It should contain only CB_AudioFile objects which are already in the current audio file cache. If not provided, it will use all the CB_AudioFile objects contained in the cache.
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

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

Sets the same volume for all the existing CB_AudioFile objects or the desired ones (if provided). It uses the CB_AudioFile#setVolume method internally.

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

Desired volume (from 0 to the maximum value, where the maximum value will be the returning value of calling the CB_Speaker.getVolume function if the CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_USE_SPEAKER_VOLUME_AS_MAXIMUM property is set to true or it will be 100 otherwise). Used internally as the "volume" parameter to call the CB_AudioFile#setVolume method.
forceSetVolumeProperty boolean <optional>
 false

If set to true (not recommended), it will change the "volume" property of the used audio API object even when the volume was failed to be changed. Used internally as the "forceSetVolumeProperty" parameter to call the CB_AudioFile#setVolume method.
onSetVolume function <optional>

Callback function which will be called if it has been possible to set the volume (or at least it was possible to try it), being "this" the CB_AudioFile object. Used internally as the "onSetVolume" parameter to call the CB_AudioFile#setVolume method.
audioFiles array <optional>
 CB_AudioFileCache#audioFiles

A numeric array containing the CB_AudioFile objects that we want to affect. It should contain only CB_AudioFile objects which are already in the current audio file cache. If not provided, it will use all the CB_AudioFile objects contained in the cache.
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

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.

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

A numeric array containing the CB_AudioFile objects that we want to affect. It should contain only CB_AudioFile objects which are already in the current audio file cache. If not provided, it will use all the CB_AudioFile objects contained in the cache.
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

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

Unmutes all the existing CB_AudioFile objects or the desired ones (if provided). It uses the CB_AudioFile#unmute method internally.

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

Callback function which will be called for each audio file if it has been possible to unmute it (or at least it was possible to try it), being "this" the CB_AudioFile object. Used internally as the "onUnmute" parameter to call the CB_AudioFile#unmute method.
audioFiles array <optional>
 CB_AudioFileCache#audioFiles

A numeric array containing the CB_AudioFile objects that we want to affect. It should contain only CB_AudioFile objects which are already in the current audio file cache. If not provided, it will use all the CB_AudioFile objects contained in the cache.
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

Type Definitions

DATA_OBJECT

Object with the desired data and options for the audio files cache.

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.
id string <optional>
 ""

Desired identifier for the audio files cache. Internal usage only recommended. If a valid value is given, this will be added to the CB_AudioFileCache#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_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 | null <optional>
 CB_AudioFileCache.maximumAudioFiles_DEFAULT

Maximum CB_AudioFile objects that are allowed 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 (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:

URIS_OBJECT

Object whose property names are audio formats (they can include just the format as 'audio/ogg' or also the codec as for example 'audio/ogg; codecs="vorbis"') 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.

Type:
  • Object
Properties:
Name Type Description
filePaths array

Being the name of each property the audio format (it can include just the format as 'audio/ogg' or also the codec as for example 'audio/ogg; codecs="vorbis"'), the value will always be a numeric 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.
Source:
Example
{	"audio/mp4" : [ "first/path/sound.m4a", "alternative/path/sound.m4a", "alternative/path/2/sound.mp4", ... ],	"audio/ogg" : [ "first/path/sound.opus", "alternative/path/sound.ogg", "alternative/path/2/sound.ogg", ... ],	"audio/mpeg" : [ "first/path/sound.mp3", "alternative/path/sound.mp3", "alternative/path/2/sound.mp3", ... ],	"audio/wav" : [ "first/path/sound.wav", "alternative/path/sound.wav", "alternative/path/2/sound.wav", ... ],	...}

checkPlayingAll_CALLBACK_ERROR(errorMessage, performedActions, uncheckedObjects)

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

Parameters:
Name Type Description
errorMessage string

A string describing the error, if it could be determined.
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_OK(performedActions, uncheckedObjects)

Callback function used by the CB_AudioFileCache#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_OBJECT

Object used by the CB_AudioFileCache#executeFunctionAll method when the "returnSetTimeoutsArray" parameter is set to true.

Type:
  • Object
Properties:
Name Type Description
item CB_AudioFile

The CB_AudioFile affected.
setTimeoutReturningValue integer

The returning value of calling the setTimeout internally or null if it was not called, depending on the "delayBetweenEach" parameter.
setTimeoutDelay number

The value used as the second parameter when calling the setTimeout internally or zero if it was not called, depending on the "delayBetweenEach" parameter.
Source:

getFreeAudioFile_OBJECT

Object returned by the CB_AudioFileCache#getFreeAudioFile method.

Type:
  • Object
Properties:
Name Type Description
object CB_AudioFile | null

Contains the CB_AudioFile object if found or null otherwise.
index string | integer

Contains the position of the CB_AudioFile object inside the CB_AudioFileCache#audioFiles property if found or "-1" otherwise.
Source:

setAudioAPIAll_CALLBACK_ERROR(error, 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
error string

A string describing the error, if it was possible to be determined.
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

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_AudioFileCache#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: