# 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 56
  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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 68

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

  - CB_AudioFileCache.URIS_OBJECT
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 113

#### <readonly> audioFiles :array

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

  ##### Type:

  - array
  Default Value:
    - []
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 221

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 230

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 239

#### <readonly> audioFilesFreePointer :integer

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

  ##### Type:

  - integer
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 248

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 167

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 194

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 176

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 185

#### <readonly> duration :number

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

  ##### Type:

  - number
  Default Value:
    - 0
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 266

#### <readonly> durationMaximum :number

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

  ##### Type:

  - number
  Default Value:
    - 0
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 275

#### <readonly> id :string

  Stores the identifier for the audio files cache.

  ##### Type:

  - string
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 87

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 131

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 122

#### <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:
    - parseInt(`CB_AudioFileCache#minimumAudioFiles` * 0.25 + 0.5)
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 140

#### <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:
    - Math.min(parseInt(`CB_AudioFileCache#minimumAudioFiles` * 0.1 + 0.5), 1)
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 149

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 212

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 203

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 96

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 105

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 158

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 257

#### <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:
    - `CB_AudioFileCache.UNLOADED`
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 71

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 355

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 331

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 347

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 339

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 315

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 323

#### <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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 307

#### <static, constant> checkManuallyOnCheckingFailed_DEFAULT :boolean

  Default value for the `CB_AudioFileCache#checkManuallyOnCheckingFailed` property.

  ##### Type:

  - boolean
  Default Value:
    - false
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 411

#### <static, constant> checkManuallyOnNeededCreated_DEFAULT :boolean

  Default value for the `CB_AudioFileCache#checkManuallyOnNeededCreated` property.

  ##### Type:

  - boolean
  Default Value:
    - false
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 395

#### <static, constant> checkManuallyOnPlayingFailed_DEFAULT :boolean

  Default value for the `CB_AudioFileCache#checkManuallyOnPlayingFailed` property.

  ##### Type:

  - boolean
  Default Value:
    - false
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 403

#### <static, constant> checkManually_DEFAULT :boolean

  Default value for the `CB_AudioFileCache#checkManually` property.

  ##### Type:

  - boolean
  Default Value:
    - false
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 387

#### <static, constant> maximumAudioFiles_DEFAULT :integer|null

  Default value for the `CB_AudioFileCache#maximumAudioFiles` property.

  ##### Type:

  - integer | null
  Default Value:
    - null
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 371

#### <static, constant> minimumAudioFiles_DEFAULT :integer

  Default value for the `CB_AudioFileCache#minimumAudioFiles` property.

  ##### Type:

  - integer
  Default Value:
    - 2
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 363

#### <static, constant> retries_DEFAULT :integer

  Default value for the `CB_AudioFileCache#retries` property.

  ##### Type:

  - integer
  Default Value:
    - 1
  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 379

### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1643

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1624

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1990
  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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1038

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1592

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 665

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 583

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1951
  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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 457

#### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2855

  ##### Returns:

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

  Type
    boolean

#### executeAll()

  Alias for `CB_AudioFileCache#executeFunctionAll`.

  Source:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1870
  See:
    - `CB_AudioFileCache#executeFunctionAll`

#### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1892
  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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1875
  See:
    - `CB_AudioFileCache#executeFunctionAll`

#### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1666

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1448

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2678

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2724

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2703

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2666

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2746

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2759

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1407

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2774
  To Do:
    - Although it would be more accurate, it does not use the `CB_AudioFile#getProgress` method internally because the `CB_AudioFile` objects are not added to the `CB_AudioFileCache#audioFiles` property until they are loaded. It would be nice to code a way to be able to use it (perhaps a property where the `CB_AudioFile` objects loading are kept temporarily).

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2828

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2839

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1479

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1493

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2647

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 504

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2304

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2235

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1754

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2145
  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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2218
  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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1295

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1149
  To Do:
    - Think about calling the `CB_AudioFileCache#createAudioFile` method internally (when the "reload" parameter is set to true) only when the `CB_AudioFile` object has been found and removed from the `CB_AudioFileCache#audioFiles` property.

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2252

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2369

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2332

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2204

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2317

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 24

#### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 8

  ##### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1972

#### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1964

#### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1861

#### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 1393

#### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2347

#### 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:
    - CrossBase/audiovisual/audio/CB_AudioFileCache.js, line 2338

#### Search results