new CB_AudioFileSprites( [dataObject]) → {CB_AudioFileSprites}
The constructor is recommended to be called through a user-driven event (as onClick, onTouch, etc.), as some clients may need this at least the first time in order to be able to play the audio.
Parameters:
Name | Type | Argument | Description |
---|---|---|---|
dataObject |
CB_AudioFileSprites.DATA_OBJECT |
<optional> |
Object with the desired data and options for the audio sprites. Although it can contain a "sprites" property, it will also be used as the first and unique parameter when calling the constructor of the |
- Source:
- To Do:
-
- Do not allow to create one object with an "id" which has already been used (unless the value is undefined, null...).
- Think about using wrapper to replace "this" in callbacks (callbackOk, callbackError) to point to the
CB_AudioFileSprites
object itself. - Method getCopy and static method filterProperties (similar to the ones from
CB_GraphicSprites
andCB_GraphicSpritesScene
).
Returns:
Returns a new CB_AudioFileSprites
object.
- Type
- CB_AudioFileSprites
Members
-
<readonly> audioFileCache :CB_AudioFileCache
-
Contains the
CB_AudioFileCache
object. Internal usage only recommended.Type:
-
<readonly> id :string
-
Stores the identifier for the audio file sprites object.
Type:
- string
-
<readonly> spriteSoundInstances :Object
-
Object whose property names are the sprite identifiers (strings), including one called "_WITHOUT_SPRITE_ASSOCIATED" for sound instances without a sprite associated, and their values are an array containing the sound instance identifiers (created by the
CB_AudioFileSprites#play
method). Internal usage only recommended.Type:
- Object
- Default Value:
-
- { "_WITHOUT_SPRITE_ASSOCIATED" : [] }
- Source:
-
<readonly> sprites :CB_AudioFileSprites.SPRITES_OBJECT
-
Object with information about the sprites.
Type:
- Default Value:
-
- {}
- Source:
Methods
-
cancelSoundInstance(soundInstanceId [, cancel] [, affectWithObjectAssociated]) → {boolean}
-
Cancels (to prevent it starts playing) or enables a sound instance (created by the
CB_AudioFileCache#play
method), by its identifier. Uses theCB_AudioFileCache#cancelSoundInstance
method internally and returns its returning value.Parameters:
Name Type Argument Default Description soundInstanceId
integer Used as the "soundInstanceId" parameter when calling the
CB_AudioFileCache#cancelSoundInstance
method internally.cancel
boolean <optional>
false Used as the "cancel" parameter when calling the
CB_AudioFileCache#cancelSoundInstance
method internally.affectWithObjectAssociated
boolean <optional>
false Used as the "affectWithObjectAssociated" parameter when calling the
CB_AudioFileCache#cancelSoundInstance
method internally.Returns:
Returns true if the sound instance has been modified or false otherwise.
- Type
- boolean
-
cancelSoundInstances( [cancel] [, affectWithObjectAssociated]) → {integer}
-
Cancels (to prevent they start playing) or enables all sound instances (created by the
CB_AudioFileCache#play
method). Uses theCB_AudioFileCache#cancelSoundInstances
method internally and returns its returning value.Parameters:
Name Type Argument Default Description cancel
boolean <optional>
false Used as the "cancel" parameter when calling the
CB_AudioFileCache#cancelSoundInstances
method internally.affectWithObjectAssociated
boolean <optional>
false Used as the "affectWithObjectAssociated" parameter when calling the
CB_AudioFileCache#cancelSoundInstances
method internally.Returns:
Returns the number of sound instances modified.
- Type
- integer
-
checkPlayingAll( [callbackOk] [, callbackError] [, ignoreQueue]) → {integer}
-
Checks whether each
CB_AudioFile
object whoseCB_AudioFile#getStatus
method returns the "unchecked" value (which belongs to the value of theCB_AudioFile#UNCHECKED
property) can be played or not. After checking, if the audio can be played, the status of theCB_AudioFile
object will get the value ofCB_AudioFile.LOADED
. Otherwise, if it cannot be played, the status of theCB_AudioFile
object will get the value ofCB_AudioFile.FAILED
. If aCB_AudioFile
object cannot be played and it is determined necessary, it will try to reload it internally (by calling theCB_AudioFileCache#removeAudioFile
method). It will call theCB_AudioFileCache#clearAudioFiles
method internally after finishing. Uses theCB_AudioFileCache#checkPlayingAll
method internally and returns its returning value. Recommended to be called through a user-driven event (as onClick, onTouch, etc.).Parameters:
Name Type Argument Default Description callbackOk
CB_AudioFileCache.checkPlayingAll_CALLBACK_OK <optional>
Used as the "callbackOk" parameter when calling the
CB_AudioFileCache#checkPlayingAll
method internally.callbackError
CB_AudioFileCache.checkPlayingAll_CALLBACK_ERROR <optional>
Used as the "callbackError" parameter when calling the
CB_AudioFileCache#checkPlayingAll
method internally.ignoreQueue
boolean <optional>
false Used as the "ignoreQueue" parameter when calling the
CB_AudioFileCache#checkPlayingAll
method internally.Returns:
Returns the number of
CB_AudioFile
objects whose status belonged to the "unchecked" value (the value of theCB_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 (theCB_AudioFileCache#status
property does not belong to the value set in theCB_AudioFileCache.LOADED
property).- Type
- integer
-
clearAudioFiles( [avoidCallingCheckCacheLoaded]) → {array}
-
Cleans the array of the
CB_AudioFile
objects (taking off the undefined or null ones) which is in theCB_AudioFileCache#audioFiles
property, just keeping the valid ones and clearing (destroying and removing) the others. For performance purposes. Uses theCB_AudioFileCache#clearAudioFiles
method internally and returns its returning value. Internal usage only recommended.Parameters:
Name Type Argument Default Description avoidCallingCheckCacheLoaded
boolean <optional>
false Used as the "avoidCallingCheckCacheLoaded" parameter when calling the
CB_AudioFileCache#clearAudioFiles
method internally.Returns:
Returns the value of the
CB_AudioFileCache#audioFiles
property.- Type
- array
-
clearSoundInstances( [clearWithObjectAssociated]) → {integer}
-
Clears the sound instances (created by the
CB_AudioFileCache#play
method) which have been cancelled. Uses theCB_AudioFileCache#clearSoundInstances
method internally and returns its returning value.Parameters:
Name Type Argument Default Description clearWithObjectAssociated
boolean <optional>
false Used as the "clearWithObjectAssociated" parameter when calling the
CB_AudioFileCache#clearSoundInstances
method internally.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 theCB_AudioFileCache#audioFiles
property). Recommended to be called through a user-driven event (as onClick, onTouch, etc.), as some clients may need this at least the first time in order to be able to play the audio. Uses theCB_AudioFileCache#createAudioFile
method internally and returns its returning value. Internal usage only recommended.Parameters:
Name Type Argument Default Description URIs
CB_AudioFileCache.URIS_OBJECT <optional>
CB_AudioFileCache#URIs
Used as the "URIs" parameter when calling the
CB_AudioFileCache#createAudioFile
method internally.preferredAPIs
array <optional>
CB_AudioFileCache#preferredAPIs
Used as the "preferredAPIs" parameter when calling the
CB_AudioFileCache#createAudioFile
method internally.preferredFormats
array <optional>
CB_AudioFileCache#preferredFormats
Used as the "preferredFormats" parameter when calling the
CB_AudioFileCache#createAudioFile
method internally.audioObject
CB_AudioFile <optional>
Used as the "audioObject" parameter when calling the
CB_AudioFileCache#createAudioFile
method internally.callbackOk
function <optional>
Used as the "callbackOk" parameter when calling the
CB_AudioFileCache#createAudioFile
method internally.callbackError
function <optional>
Used as the "callbackError" parameter when calling the
CB_AudioFileCache#createAudioFile
method internally.storeURIsList
boolean <optional>
false Used as the "storeURIsList" parameter when calling the
CB_AudioFileCache#createAudioFile
method internally.checkAutomatically
boolean <optional>
false Used as the "checkAutomatically" parameter when calling the
CB_AudioFileCache#createAudioFile
method internally.Returns:
If it fails, it returns null. Otherwise, returns the
CB_AudioFile
that has been created or reused.- Type
- CB_AudioFile | null
-
createAudioFiles(minimumAudioFiles) → {integer}
-
Creates the desired number of internal
CB_AudioFile
objects (inside theCB_AudioFileCache#audioFiles
property). Recommended to be called through a user-driven event (as onClick, onTouch, etc.), as some clients may need this at least the first time in order to be able to play the audio. Uses theCB_AudioFileCache#createAudioFiles
method internally and returns its returning value.Parameters:
Name Type Description minimumAudioFiles
integer Used as the "minimumAudioFiles" parameter when calling the
CB_AudioFileCache#createAudioFiles
method internally.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 callingCB_AudioFile#destructor
(stopSounds, false, true). Uses theCB_AudioFileCache#destroyAll
method internally and returns its returning value.Parameters:
Name Type Argument Default Description stopSounds
boolean <optional>
false Used as the "stopSounds" parameter when calling the
CB_AudioFileCache#destroyAll
method internally.Returns:
Returns the number of
CB_AudioFile
objects whoseCB_AudioFile#destructor
has been called.- Type
- integer
-
destructor( [stopSounds] [, preventAbortedStatus])
-
Destroys the audio file sprites object (removing all sprites, etc.), including the internal audio file cache object, and frees memory. By default, unless the "preventAbortedStatus" is set to true, sets the current status of the
CB_AudioFileCache
object as ABORTED (CB_AudioFileCache.ABORTED
value).Parameters:
Name Type Argument Default Description stopSounds
boolean <optional>
false Used as the "stopSounds" parameter when calling internally the
CB_AudioFileCache#destructor
method of theCB_AudioFileCache
object.preventAbortedStatus
boolean <optional>
false If set to true (not recommended), it will not assign the status of "ABORTED" (it will not assign the value of
CB_AudioFileCache.ABORTED
to theCB_AudioFileCache#status
property). -
executeAll()
-
Alias for
CB_AudioFileSprites#executeFunctionAll
. -
executeAllSprite()
-
Alias for
CB_AudioFileSprites#executeFunctionAllSprite
. -
executeAllSprites()
-
executeFunctionAll(functionEach [, delayBetweenEach] [, audioFiles] [, returnSetTimeoutsArray] [, delayBetweenEachAffectsFirst] [, functionFinish]) → {integer|array}
-
Performs a desired action, using the provided function, on all the existing
CB_AudioFile
objects or on the desired ones (if provided). Uses theCB_AudioFileCache#executeFunctionAll
method internally and returns its returning value.Parameters:
Name Type Argument Default Description functionEach
CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK Used as the "functionEach" parameter when calling the
CB_AudioFileSprites#executeFunctionAll
method internally.delayBetweenEach
number | CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK <optional>
0 Used as the "delayBetweenEach" parameter when calling the
CB_AudioFileCache#executeFunctionAll
method internally.audioFiles
array <optional>
CB_AudioFileCache#audioFiles
Used as the "audioFiles" parameter when calling the
CB_AudioFileCache#executeFunctionAll
method internally.returnSetTimeoutsArray
boolean <optional>
false Used as the "returnSetTimeoutsArray" parameter when calling the
CB_AudioFileCache#executeFunctionAll
method internally.delayBetweenEachAffectsFirst
boolean <optional>
false Used as the "delayBetweenEachAffectsFirst" parameter when calling the
CB_AudioFileCache#executeFunctionAll
method internally.functionFinish
CB_Arrays.executeFunctionAll_ON_FINISH_CALLBACK <optional>
Function that will be called for when it has finished looping all the items. The first parameter will be the array which was looped, the second parameter will be the number of times that the "functionEach" callback was called (the most likely, matches the number of elements unless they are undefined or null), and the third parameter will be the maximum "delay" used, being "this" the array itself.
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 aCB_AudioFileCache.executeFunctionAll_OBJECT
object for eachCB_AudioFile
given. The length of this array will also be the number of calls to the "functionEach" function that were performed. Note that if a value greater than 0 (zero) for the "delayBetweenEach" parameter has been provided, perhaps not all calls of the "functionEach" function will have been performed yet when exiting this method because of the asynchronous nature of the setTimeout function.- Type
- integer | array
-
executeFunctionAllSprite(spriteId, functionEach [, delayBetweenEach] [, avoidCancelled] [, returnSetTimeoutsArray] [, delayBetweenEachAffectsFirst] [, functionFinish]) → {integer|array}
-
Executes a desired function for all the
CB_AudioFile
objects used by the sound instances currently created that belong to a given sprite (by its ID). It calls theCB_AudioFileSprites#executeFunctionAll
method internally and returns its returning value.Parameters:
Name Type Argument Default Description spriteId
string The identifier for the sprite.
functionEach
CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK Used as the "functionEach" parameter when calling the
CB_AudioFileSprites#executeFunctionAll
method internally.delayBetweenEach
number | CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK <optional>
0 Used as the "delayBetweenEach" parameter when calling the
CB_AudioFileSprites#executeFunctionAll
method internally.avoidCancelled
boolean <optional>
false If set to true, it will not affect the
CB_AudioFile
objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling theCB_AudioFileSprites#getAudioFilesUsedBySpriteId
method internally.returnSetTimeoutsArray
boolean <optional>
false Used as the "returnSetTimeoutsArray" parameter when calling the
CB_AudioFileSprites#executeFunctionAll
method internally.delayBetweenEachAffectsFirst
boolean <optional>
false Used as the "delayBetweenEachAffectsFirst" parameter when calling the
CB_AudioFileSprites#executeFunctionAll
method internally.functionFinish
CB_Arrays.executeFunctionAll_ON_FINISH_CALLBACK <optional>
Function that will be called for when it has finished looping all the items. The first parameter will be the array which was looped, the second parameter will be the number of times that the "functionEach" callback was called (the most likely, matches the number of elements unless they are undefined or null), and the third parameter will be the maximum "delay" used, being "this" the array itself.
Returns:
If the "returnSetTimeoutsArray" parameter is set to false, it will return the number of calls to the "functionEach" function that were performed (which should be the same number as the
CB_AudioFile
objects used by the sound instances that belong to the given sprite identifier). Otherwise, if the "returnSetTimeoutsArray" is set to true, it will return a numeric array with aCB_AudioFileCache.executeFunctionAll_OBJECT
object for eachCB_AudioFile
given. The length of this array will also be the number of calls to the "functionEach" function that were performed. Note that if a value greater than 0 (zero) for the "delayBetweenEach" parameter has been provided, perhaps not all calls of the "functionEach" function will have been performed yet when exiting this method because of the asynchronous nature of the setTimeout function.- Type
- integer | array
-
executeFunctionAllSprites(functionEach [, delayBetweenEach] [, includeWithoutSpriteAssociated] [, avoidCancelled] [, returnSetTimeoutsArray] [, delayBetweenEachAffectsFirst] [, functionFinish]) → {integer|array}
-
Executes a desired function for all the
CB_AudioFile
objects used by all the sound instances currently created. It calls theCB_AudioFileSprites#executeFunctionAll
method internally and returns its returning value.Parameters:
Name Type Argument Default Description functionEach
CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK Used as the "functionEach" parameter when calling the
CB_AudioFileSprites#executeFunctionAll
method internally.delayBetweenEach
number | CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK <optional>
0 Used as the "delayBetweenEach" parameter when calling the
CB_AudioFileSprites#executeFunctionAll
method internally.includeWithoutSpriteAssociated
boolean <optional>
false If set to true, it will also affect the
CB_AudioFile
objects whose sound instance ID is not associated to any sprite. Used as the "includeWithoutSpriteAssociated" parameter when calling theCB_AudioFileSprites#getAudioFilesUsed
method internally.avoidCancelled
boolean <optional>
false If set to true, it will not affect the
CB_AudioFile
objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling theCB_AudioFileSprites#getAudioFilesUsed
method internally.returnSetTimeoutsArray
boolean <optional>
false Used as the "returnSetTimeoutsArray" parameter when calling the
CB_AudioFileSprites#executeFunctionAll
method internally.delayBetweenEachAffectsFirst
boolean <optional>
false Used as the "delayBetweenEachAffectsFirst" parameter when calling the
CB_AudioFileSprites#executeFunctionAll
method internally.functionFinish
CB_Arrays.executeFunctionAll_ON_FINISH_CALLBACK <optional>
Function that will be called for when it has finished looping all the items. The first parameter will be the array which was looped, the second parameter will be the number of times that the "functionEach" callback was called (the most likely, matches the number of elements unless they are undefined or null), and the third parameter will be the maximum "delay" used, being "this" the array itself.
Returns:
If the "returnSetTimeoutsArray" parameter is set to false, it will return the number of calls to the "functionEach" function that were performed (which should be the same number as the
CB_AudioFile
objects used by the sound instances that belong to the sprites). Otherwise, if the "returnSetTimeoutsArray" is set to true, it will return a numeric array with aCB_AudioFileCache.executeFunctionAll_OBJECT
object for eachCB_AudioFile
given. The length of this array will also be the number of calls to the "functionEach" function that were performed. Note that if a value greater than 0 (zero) for the "delayBetweenEach" parameter has been provided, perhaps not all calls of the "functionEach" function will have been performed yet when exiting this method because of the asynchronous nature of the setTimeout function.- Type
- integer | array
-
forEach()
-
Alias for
CB_AudioFileSprites#executeFunctionAll
. -
forEachSprite()
-
forEachSpriteById()
-
Alias for
CB_AudioFileSprites#executeFunctionAllSprite
. -
getAudioFileBySoundInstanceId(soundInstanceId [, avoidCancelled]) → {CB_AudioFile|null}
-
Gets the
CB_AudioFile
object associated to a given sound instance ID (created by theCB_AudioFileCache#play
method), if any, or null otherwise. Uses theCB_AudioFileCache#getAudioFileBySoundInstanceId
method internally and returns its returning value.Parameters:
Name Type Argument Default Description soundInstanceId
integer Used as the "soundInstanceId" parameter when calling the
CB_AudioFileCache#getAudioFileBySoundInstanceId
method internally.avoidCancelled
boolean <optional>
false Used as the "avoidCancelled" parameter when calling the
CB_AudioFileCache#getAudioFileBySoundInstanceId
method internally.Returns:
Returns the
CB_AudioFile
object associated to a given sound instance ID, if any, or null otherwise.- Type
- CB_AudioFile | null
-
getAudioFiles( [copy]) → {array}
-
Gets an array with all the
CB_AudioFile
objects. Uses theCB_AudioFileCache#getAudioFiles
method internally and returns its returning value.Parameters:
Name Type Argument Default Description copy
boolean <optional>
false Used as the "copy" parameter when calling the
CB_AudioFileCache#getAudioFiles
method internally.Returns:
Returns an array with all the
CB_AudioFile
objects.- Type
- array
-
getAudioFilesBusy() → {array}
-
Gets an array with the busy
CB_AudioFile
objects (the objects which are not available and ready to use). Uses theCB_AudioFileCache#getAudioFilesBusy
method internally and returns its returning value.Returns:
Returns an array with the busy
CB_AudioFile
objects (the objects which are not available and ready to use).- Type
- array
-
getAudioFilesFree() → {array}
-
Gets an array with the free
CB_AudioFile
objects (the objects which are available and ready to use). Uses theCB_AudioFileCache#getAudioFilesFree
method internally and returns its returning value.Returns:
Returns an array with the free
CB_AudioFile
objects (the objects which are available and ready to use).- Type
- array
-
getAudioFilesFreeNumber() → {integer}
-
Tells the current number of free
CB_AudioFile
objects (the number of objects which are available and ready to use). Uses theCB_AudioFileCache#getAudioFilesFreeNumber
method internally and returns its returning value.Returns:
Returns the current number of free
CB_AudioFile
objects (the number of objects which are available and ready to use).- Type
- integer
-
getAudioFilesNumber( [real]) → {integer}
-
Tells the number of
CB_AudioFile
objects created. Uses theCB_AudioFileCache#getAudioFilesNumber
method internally and returns its returning value.Parameters:
Name Type Argument Default Description real
boolean <optional>
false Used as the "real" parameter when calling the
CB_AudioFileCache#getAudioFilesNumber
method internally.Returns:
Returns the number of
CB_AudioFile
objects created.- Type
- integer
-
getAudioFilesUsed( [oneDimension] [, includeWithoutSpriteAssociated] [, avoidCancelled]) → {CB_AudioFileSprites.getAudioFilesUsed_OBJECT|array}
-
Returns the
CB_AudioFile
objects used by all the sounds instances currently created.Parameters:
Name Type Argument Default Description oneDimension
boolean <optional>
false If set to false, it will return an object whose property names are the sprite identifiers (including the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated, if the "includeWithoutSpriteAssociated" is set to true) and their value will be a numeric array with the
CB_AudioFile
objects used. Otherwise, if set to true, it will return a numeric array with theCB_AudioFile
objects used (if the "includeWithoutSpriteAssociated" parameter is set to true, it will also contain theCB_AudioFile
objects whose sound instance ID is not associated to any sprite).includeWithoutSpriteAssociated
boolean <optional>
false If set to true, it will also return the
CB_AudioFile
objects whose sound instance ID is not associated to any sprite. Used as the "includeWithoutSpriteAssociated" parameter when calling theCB_AudioFileSprites#getSprites
method internally.avoidCancelled
boolean <optional>
false If set to true, it will not return the
CB_AudioFile
objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling theCB_AudioFileSprites#getAudioFilesUsedBySpriteId
method internally.Returns:
Returns the
CB_AudioFile
objects used by all the sounds instances currently created. If the "oneDimension" parameter is set to false, it will return aCB_AudioFileSprites.getAudioFilesUsed_OBJECT
object whose property names are the sprite identifiers (including the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated, if the "includeWithoutSpriteAssociated" is set to true) and their value will be a numeric array with theCB_AudioFile
objects used. Otherwise, if the "oneDimension" parameter set to true, it will return a numeric array with theCB_AudioFile
objects used (if the "includeWithoutSpriteAssociated" parameter is set to true, it will also contain theCB_AudioFile
objects whose sound instance ID is not associated to any sprite).- Type
- CB_AudioFileSprites.getAudioFilesUsed_OBJECT | array
-
getAudioFilesUsedBySpriteId(spriteId [, avoidCancelled]) → {array}
-
Returns an array of the
CB_AudioFile
objects used by the sound instances that belong to a given sprite identifier.Parameters:
Name Type Argument Default Description spriteId
string The identifier for the sprite.
avoidCancelled
boolean <optional>
false If set to true, it will not return the
CB_AudioFile
objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling theCB_AudioFileSprites#getAudioFileBySoundInstanceId
method internally.Returns:
Returns an array of the
CB_AudioFile
objects used by the sound instances that belong to the given sprite identifier.- Type
- array
-
getDuration( [maximum]) → {number}
-
Tells the duration (minimum or maximum) of the sound stored (in milliseconds). Although the audio file cache should always be used to cache the same sound only, the duration might not always be the same due the usage of different formats, file paths, etc. So this method returns either the minimum or the maximum duration found among all the
CB_AudioFile
objects. Uses theCB_AudioFileCache#getDuration
method internally and returns its returning value.Parameters:
Name Type Argument Default Description maximum
boolean <optional>
false Used as the "maximum" parameter when calling the
CB_AudioFileCache#getDuration
method internally.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 theCB_AudioFileCache#audioFilesFree
property). Note that this will call the internalCB_AudioFileCache#_createNewAudioFilesIfNeeded
method that could end creating a newCB_AudioFile
object if needed. Uses theCB_AudioFileCache#getFreeAudioFile
method internally and returns its returning value.Parameters:
Name Type Argument Default Description popIt
boolean <optional>
false Used as the "popIt" parameter when calling the
CB_AudioFileCache#getFreeAudioFile
method internally.Returns:
Returns a
CB_AudioFileCache.getFreeAudioFile_OBJECT
object. -
getProgress( [countLoadedObjects] [, alsoUncheckedAndCheckingObjects]) → {number}
-
Returns a number representing the percentage of the loading progress for the audio file sprites object (from 0 to 100, being 100 a complete loading progress). The way to calculate it internally may differ from one audio API to another and it is not totally reliable. Uses the
CB_AudioFileCache#getProgress
method internally and returns its returning value.Parameters:
Name Type Argument Default Description countLoadedObjects
boolean <optional>
false Used as the "countLoadedObjects" parameter when calling the
CB_AudioFileCache#getProgress
method internally.alsoUncheckedAndCheckingObjects
boolean <optional>
false Used as the "alsoUncheckedAndCheckingObjects" parameter when calling the
CB_AudioFileCache#getProgress
method internally.Returns:
Returns a number representing the percentage of the loading progress for the audio file sprites object (from 0 to 100, being 100 a complete loading progress). The way to calculate it internally may differ from one audio API to another and it is not totally reliable.
- Type
- number
-
getSoundInstancesId( [oneDimension] [, includeWithoutSpriteAssociated]) → {Object|array}
-
Returns the sound instances (their ID) used (stored in the
CB_AudioFileSprites#spriteSoundInstances
property).Parameters:
Name Type Argument Default Description oneDimension
boolean <optional>
false If set to true, it will return the
CB_AudioFileSprites#spriteSoundInstances
property directly (which includes the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated). Otherwise, if it is set to true, it will return a numeric array whose values are the sound instance IDs.includeWithoutSpriteAssociated
boolean <optional>
false If set to true, it will also return the sound instance identifiers which are not associated to any sprite. Used as the "includeWithoutSpriteAssociated" parameter when calling the
CB_AudioFileSprites#getSprites
method internally. Only used when the "oneDimension" parameter is set to true.Returns:
Returns the sound instances (their ID) used (stored in the
CB_AudioFileSprites#spriteSoundInstances
property). If the "oneDimension" parameter is set to false, the property names of the returning object are the sprite identifiers (strings), including one called "_WITHOUT_SPRITE_ASSOCIATED" for sound instances without a sprite associated, and their values are an array containing the sound instance IDs. If the "oneDimension" parameter is set to true, it will return a numeric array whose values are the sound instance identifiers (if the "includeWithoutSpriteAssociated" parameter it set to true, it will also include the sound instances which are not associated to any sprite).- Type
- Object | array
-
getSoundInstancesIdBySpriteId(spriteId) → {array}
-
Returns an array of the sound instance identifiers (created by the
CB_AudioFileSprites#play
method) used by the given sprite identifier.Parameters:
Name Type Description spriteId
string The identifier for the sprite.
Returns:
Returns a numeric array of the sound instances (created by the
CB_AudioFileSprites#play
method) used by the given sprite identifier.- Type
- array
-
getSprite(spriteId) → {CB_AudioFileSprites.SPRITE_OBJECT}
-
Returns a sprite by its ID.
Parameters:
Name Type Description spriteId
string The identifier for the sprite.
Returns:
Returns the desired sprite or a fake object if it was not found. The fake object will be this one: { "startAt" : 0, "stopAt" : null, "fake" : true }.
-
getSprites( [includeWithoutSpriteAssociated]) → {CB_AudioFileSprites.SPRITES_OBJECT}
-
Returns an object with the sprites (and includes "_WITHOUT_SPRITE_ASSOCIATED" if we want to).
Parameters:
Name Type Argument Default Description includeWithoutSpriteAssociated
boolean <optional>
false If set to true, the returning object will also contain a property called "_WITHOUT_SPRITE_ASSOCIATED" whose value will be an empty object (unless the property existed before in the object stored in the
CB_AudioFileSprites#sprites
property and had a value which is not an empty object). If set to false, the returning object will not contain the "_WITHOUT_SPRITE_ASSOCIATED" property unless the property existed before in the object stored in theCB_AudioFileSprites#sprites
property.Returns:
Returns an object with the sprites (and includes "_WITHOUT_SPRITE_ASSOCIATED" if we want to).
-
getStatus() → {number}
-
Gets the current status of the audio file sprites object. Uses the
CB_AudioFileCache#getStatus
method internally and returns its returning value.Returns:
Returns the current status of the audio file sprites object. It is a number, which should match the value of the
CB_AudioFileCache.UNLOADED
(still unloaded),CB_AudioFileCache.LOADING
(loading),CB_AudioFileCache.UNCHECKED
(not checked by calling theCB_AudioFileCache#checkPlayingAll
method yet),CB_AudioFileCache.CHECKING
(being checked by theCB_AudioFileCache#checkPlayingAll
method),CB_AudioFileCache.LOADED
(loaded),CB_AudioFileCache.FAILED
(failed loading or failed to play or by any other reason) orCB_AudioFileCache.ABORTED
(aborted because it was destroyed with the "destructor" method) property.- Type
- number
-
getStatusString() → {string}
-
Gets the current status of the audio file sprites, as a string. Uses the
CB_AudioFileCache#getStatusString
method internally and returns its returning value.Returns:
Returns the current status of the audio file sprites, as a string. Possible return values are "UNLOADED", "LOADING", "UNCHECKED", "CHECKING", "LOADED", "FAILED", "ABORTED" or "UNKNOWN (UNKNOWN_STATUS)" (where "UNKNOWN_STATUS" will be a value from the
CB_AudioFileCache#status
property not recognized as any possible status).- Type
- string
-
insertSprite(sprite, spriteId) → {boolean}
-
Inserts the given sprite. It will keep the existing ones. If a sprite identifier already existed and it is given again (not recommended), it will be replaced by the new one (but keeping its current sound instances, if any).
Parameters:
Name Type Description sprite
CB_AudioFileSprites.SPRITE_OBJECT Object with the desired sprite.
spriteId
string The identifier for the sprite.
Returns:
Returns true if the sprite has been inserted or false otherwise.
- Type
- boolean
-
insertSprites(sprites) → {integer}
-
Inserts the given sprites. It will keep the existing ones. If a sprite identifier already existed and it is given again (not recommended), it will be replaced by the new one (but keeping its current sound instances, if any).
Parameters:
Name Type Description sprites
CB_AudioFileSprites.SPRITES_OBJECT Object with the desired sprites.
Returns:
Returns the number of sprites inserted.
- Type
- integer
-
isAudioFileFree(id) → {boolean}
-
Tells whether a desired
CB_AudioFile
object is free (it is in theCB_AudioFileCache#audioFilesFree
property) or not, by its identifier. A freeCB_AudioFile
object is an object which is not being used and it is available to be used. Uses theCB_AudioFileCache#isAudioFileFree
method internally and returns its returning value.Parameters:
Name Type Description id
string Used as the "id" parameter when calling the
CB_AudioFileCache#isAudioFileFree
method internally.Returns:
Returns whether a desired
CB_AudioFile
object is free (it is in theCB_AudioFileCache#audioFilesFree
property) or not, by its identifier. A freeCB_AudioFile
object is an object which is not being used and it is available to be used.- Type
- boolean
-
isPausedSprite(spriteId) → {boolean}
-
Tells whether a given sprite (by its ID) is paused or not. Note that there could be more than one sound instance (with a {@CB_AudioFile} object) by each sprite with different status (paused, stopped, etc.) and this method will return true if any of them is paused.
Parameters:
Name Type Description spriteId
string The identifier for the sprite.
Returns:
Returns whether a given sprite (by its ID) is paused or not.
- Type
- boolean
-
isPlaying() → {boolean}
-
Tells whether any of the
CB_AudioFile
objects is playing or not. Uses theCB_AudioFileCache#isPlaying
method internally and returns its returning value.Returns:
Returns whether any of the
CB_AudioFile
objects is playing or not.- Type
- boolean
-
isPlayingSprite(spriteId) → {boolean}
-
Tells whether a given sprite (by its ID) is playing or not. Note that there could be more than one sound instance (with a {@CB_AudioFile} object) by each sprite with different status (paused, stopped, etc.) and this method will return true if any of them is playing.
Parameters:
Name Type Description spriteId
string The identifier for the sprite.
Returns:
Returns whether a given sprite (by its ID) is playing or not.
- Type
- boolean
-
isStoppedSprite(spriteId [, checkAudioFileObjects]) → {boolean}
-
Tells whether a given sprite (by its ID) is stopped or not. Note that there could be more than one sound instance (with a {@CB_AudioFile} object) by each sprite with different status (paused, stopped, etc.) and this method will only return true if all of them are stopped.
Parameters:
Name Type Argument Default Description spriteId
string The identifier for the sprite.
checkAudioFileObjects
boolean <optional>
false If set to true, it will check all the {@CB_AudioFile} objects associated to the sprite. Doing so, as internally all stopped {@CB_AudioFile} objects are disassociated from their sound instances, this method should return false normally (unless something went wrong).
Returns:
Returns whether a given sprite (by its ID) is stopped or not. As internally all stopped {@CB_AudioFile} objects are disassociated from their sound instances, this method should return false normally (unless something went wrong).
- Type
- boolean
-
load(dataObject) → {CB_AudioFileSprites|null}
-
Loads the audio file sprites with the desired data given. This method is called by the constructor automatically. Recommended to be called through a user-driven event (as onClick, onTouch, etc.), as some clients may need this at least the first time in order to be able to play the audio.
Parameters:
Name Type Description dataObject
CB_AudioFileSprites.DATA_OBJECT Object with the desired data and options for the audio file sprites.
Returns:
If a "dataObject" is given, it returns the current
CB_AudioFileSprites
object. Otherwise, it returns null.- Type
- CB_AudioFileSprites | null
-
muteAll( [onMute] [, audioFiles]) → {integer}
-
Mutes all the existing
CB_AudioFile
objects or the desired ones (if provided). Uses theCB_AudioFileCache#muteAll
method internally and returns its returning value.Parameters:
Name Type Argument Default Description onMute
function <optional>
Used as the "onMute" parameter when calling the
CB_AudioFileCache#muteAll
method internally.audioFiles
array <optional>
CB_AudioFileCache#audioFiles
Used as the "audioFiles" parameter when calling the
CB_AudioFileCache#muteAll
method internally.Returns:
Returns the number of calls to the
CB_AudioFile#mute
method that were performed (which should be the same number as theCB_AudioFile
objects in the "audioFiles" parameter).- Type
- integer
-
muteSprite(spriteId [, onMute]) → {integer}
-
Mutes all the
CB_AudioFile
objects that belong to the sound instances (created by theCB_AudioFileSprites#play
or theCB_AudioFileSprites#playSprite
methods) used by a given sprite identifier. Uses theCB_AudioFileSprites#muteAll
method internally and returns its returning value.Parameters:
Name Type Argument Description spriteId
string The identifier for the sprite.
onMute
function <optional>
Callback function which will be called for each audio file if it has been possible to mute it (or at least it was possible to try it), being "this" the
CB_AudioFile
object. Used internally as the "onMute" parameter to call theCB_AudioFileSprites#muteAll
method.Returns:
Returns the number of calls to the
CB_AudioFile#mute
method that were performed internally.- Type
- integer
-
pauseAll( [onPause] [, audioFiles]) → {integer}
-
Tries to pause all the existing
CB_AudioFile
objects or the desired ones (if provided), which are being played, by calling theirCB_AudioFile#pause
method internally. Uses theCB_AudioFileCache#pauseAll
method internally and returns its returning value.Parameters:
Name Type Argument Default Description onPause
function <optional>
Used as the "onPause" parameter when calling the
CB_AudioFileCache#pauseAll
method internally.audioFiles
array <optional>
CB_AudioFileCache#audioFiles
Used as the "audioFiles" parameter when calling the
CB_AudioFileCache#pauseAll
method internally.Returns:
Returns the number of calls to the
CB_AudioFile#pause
method that were performed (which should be the same number as theCB_AudioFile
objects in the "audioFiles" parameter).- Type
- integer
-
pauseSprite(spriteId [, onPause]) → {integer}
-
Pauses all the
CB_AudioFile
objects that belong to the sound instances (created by theCB_AudioFileSprites#play
or theCB_AudioFileSprites#playSprite
methods) which are playing used by a given sprite identifier. Uses theCB_AudioFileSprites#pauseAll
method internally and returns its returning value.Parameters:
Name Type Argument Description spriteId
string The identifier for the sprite.
onPause
function <optional>
Function without parameters to be called when the audio is paused successfully, being "this" the
CB_AudioFile
object. Used internally as the "onPause" parameter to call theCB_AudioFileSprites#pauseAll
method.Returns:
Returns the number of calls to the
CB_AudioFile#pause
method that were performed internally.- Type
- integer
-
play( [startAt] [, stopAt] [, loop] [, volume] [, allowedRecursiveDelay] [, allowedRecursiveDelaySkipping] [, onPlayStart] [, onStop] [, spriteId]) → {integer|null}
-
Plays a sound of the cache (if there is any free), using a sprite if desired. If a sound cannot be played, this method can call itself internally again and again (with most of the given parameters being the same, depending on the circumstances) to try to play the sound until a desired time limit is reached. If a
CB_AudioFile
object cannot be played and it is determined necessary, it will try to reload it internally (by calling theCB_AudioFileCache#removeAudioFile
method). Uses theCB_AudioFileCache#play
method internally and returns its returning value. Internal usage only recommended. To play a sprite, better use theCB_AudioFileSprites#playSprite
method instead.Parameters:
Name Type Argument Default Description startAt
number <optional>
0 | CB_AudioFile_API.WAAPI#lastStartAt
|CB_AudioFile_API.SM2#lastStartAt
|CB_AudioFile_API.ACMP#lastStartAt
|CB_AudioFile_API.AAPI#lastStartAt
| stopAtUsed as the "startAt" parameter when calling the
CB_AudioFileCache#play
method internally.stopAt
number <optional>
CB_AudioFile_API.WAAPI#getDuration
() |CB_AudioFile_API.SM2#getDuration
() |CB_AudioFile_API.ACMP#getDuration
() |CB_AudioFile_API.AAPI#getDuration
()Used as the "stopAt" parameter when calling the
CB_AudioFileCache#play
method internally.loop
boolean <optional>
CB_AudioFile#loop
Used as the "loop" parameter when calling the
CB_AudioFileCache#play
method internally.volume
number <optional>
CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_USE_SPEAKER_VOLUME_AS_DEFAULT ? CB_Speaker.getVolume() : CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME Used as the "volume" parameter when calling the
CB_AudioFileCache#play
method internally.allowedRecursiveDelay
boolean <optional>
CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT
Used as the "allowedRecursiveDelay" parameter when calling the
CB_AudioFileCache#play
method internally.allowedRecursiveDelaySkipping
boolean <optional>
stopAt-startAt Used as the "allowedRecursiveDelaySkipping" parameter when calling the
CB_AudioFileCache#play
method internally.onPlayStart
function <optional>
Used as the "onPlayStart" parameter when calling the
CB_AudioFileCache#play
method internally.onStop
function <optional>
Used as the "onStop" parameter when calling the
CB_AudioFileCache#play
method internally.spriteId
string <optional>
'_WITHOUT_SPRITE_ASSOCIATED' The identifier for the sprite. Internal usage only recommended.
Returns:
Returns null if a sprite identifier was given but it could not be found. Otherwise, returns the sound instance ID used if there was one free or null otherwise. To get a sound instance returned does not mean necessarily that the sound started playing so it is necessary to use a callback function as the "onPlayStart" parameter for checking this. The sound instance created (if any), will be cancelled automatically once the sound is stopped.
- Type
- integer | null
-
playAll( [startAt] [, stopAt] [, loop] [, volume] [, avoidDelayedPlay] [, allowedRecursiveDelay] [, onPlayStart] [, onStop] [, includingPlaying]) → {integer}
-
Tries to play all the
CB_AudioFile
objects by calling theirCB_AudioFile#play
method internally. If aCB_AudioFile
object cannot be played and it is determined necessary, it will try to reload it internally (by calling theCB_AudioFileCache#removeAudioFile
method). Uses theCB_AudioFileCache#playAll
method internally and returns its returning value.Parameters:
Name Type Argument Default Description startAt
number <optional>
0 | CB_AudioFile_API.WAAPI#lastStartAt
|CB_AudioFile_API.SM2#lastStartAt
|CB_AudioFile_API.ACMP#lastStartAt
|CB_AudioFile_API.AAPI#lastStartAt
| stopAtUsed as the "startAt" parameter when calling the
CB_AudioFileCache#playAll
method internally.stopAt
number <optional>
CB_AudioFile_API.WAAPI#getDuration
() |CB_AudioFile_API.SM2#getDuration
() |CB_AudioFile_API.ACMP#getDuration
() |CB_AudioFile_API.AAPI#getDuration
()Used as the "stopAt" parameter when calling the
CB_AudioFileCache#playAll
method internally.loop
boolean <optional>
CB_AudioFile#loop
Used as the "loop" parameter when calling the
CB_AudioFileCache#playAll
method internally.volume
number <optional>
CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_USE_SPEAKER_VOLUME_AS_DEFAULT ? CB_Speaker.getVolume() : CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME Used as the "volume" parameter when calling the
CB_AudioFileCache#playAll
method internally.avoidDelayedPlay
boolean <optional>
false Used as the "avoidDelayedPlay" parameter when calling the
CB_AudioFileCache#playAll
method internally.allowedRecursiveDelay
boolean <optional>
CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT
Used as the "allowedRecursiveDelay" parameter when calling the
CB_AudioFileCache#playAll
method internally.onPlayStart
function <optional>
Used as the "onPlayStart" parameter when calling the
CB_AudioFileCache#playAll
method internally.onStop
function <optional>
Used as the "onStop" parameter when calling the
CB_AudioFileCache#playAll
method internally.includingPlaying
boolean <optional>
false Used as the "includingPlaying" parameter when calling the
CB_AudioFileCache#playAll
method internally.Returns:
Returns the number of
CB_AudioFile
objects whoseCB_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 theCB_AudioFile#play
method to be called through a user-driven event (as onClick, onTouch, etc.). Internally, it callsCB_AudioFileCache#playAll
(0, null, false, 0, true, null, null, null, includingPlaying) and, after a desired delay, calls theCB_AudioFileCache#stopAll
method. Uses theCB_AudioFileCache#playAndStopAll
method internally and returns its returning value.Parameters:
Name Type Argument Default Description includingPlaying
boolean <optional>
false Used as the "includingPlaying" parameter when calling the
CB_AudioFileCache#playAndStopAll
method internally.delayBeforeStop
number <optional>
100 Used as the "delayBeforeStop" parameter when calling the
CB_AudioFileCache#playAndStopAll
method internally.Returns:
Returns the number of
CB_AudioFile
objects whoseCB_AudioFile#play
method did not return the value of "-1" (this does not mean necessarily that they could be played successfully).- Type
- integer
-
playSprite(spriteId [, loop] [, volume] [, allowedRecursiveDelay] [, allowedRecursiveDelaySkipping] [, onPlayStart] [, onStop]) → {integer|null}
-
Plays a sprite by its ID. If the sprite is found, uses the
CB_AudioFileSprites#play
method internally and returns its returning value.Parameters:
Name Type Argument Default Description spriteId
string The identifier for the sprite. Used as the "spriteId" parameter when calling the
CB_AudioFileSprites#play
method internally.loop
boolean <optional>
CB_AudioFile#loop
Used as the "loop" parameter when calling the
CB_AudioFileSprites#play
method internally.volume
number <optional>
CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_USE_SPEAKER_VOLUME_AS_DEFAULT ? CB_Speaker.getVolume() : CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME Used as the "volume" parameter when calling the
CB_AudioFileSprites#play
method internally.allowedRecursiveDelay
boolean <optional>
CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT
Used as the "allowedRecursiveDelay" parameter when calling the
CB_AudioFileSprites#play
method internally.allowedRecursiveDelaySkipping
boolean <optional>
stopAt-startAt Used as the "allowedRecursiveDelaySkipping" parameter when calling the
CB_AudioFileSprites#play
method internally.onPlayStart
function <optional>
Used as the "onPlayStart" parameter when calling the
CB_AudioFileSprites#play
method internally.onStop
function <optional>
Used as the "onStop" parameter when calling the
CB_AudioFileSprites#play
method internally.Returns:
Returns null if the sprite was not found. Otherwise, returns the sound instance ID used if there was one free or null otherwise. To get a sound instance returned does not mean necessarily that the sound started playing so it is necessary to use a callback function as the "onPlayStart" parameter for checking this. The sound instance created (if any), will be cancelled automatically once the sound is stopped.
- Type
- integer | null
-
purge(desiredNumber [, setAsMinimumAudioFiles] [, includePlaying] [, stopSounds] [, statuses]) → {integer}
-
Tries to purge the audio file cache until it reaches a desired number of
CB_AudioFile
objects internally (set in theCB_AudioFileCache#audioFiles
property), by removing and destroying some of the currentCB_AudioFile
objects. For performance purposes. Uses theCB_AudioFileCache#purge
method internally and returns its returning value.Parameters:
Name Type Argument Default Description desiredNumber
integer Used as the "desiredNumber" parameter when calling the
CB_AudioFileCache#purge
method internally.setAsMinimumAudioFiles
boolean <optional>
false Used as the "setAsMinimumAudioFiles" parameter when calling the
CB_AudioFileCache#purge
method internally.includePlaying
boolean <optional>
false Used as the "includePlaying" parameter when calling the
CB_AudioFileCache#purge
method internally.stopSounds
boolean <optional>
false Used as the "stopSounds" parameter when calling the
CB_AudioFileCache#purge
method internally.statuses
array <optional>
Array( CB_AudioFile.LOADING
,CB_AudioFile.UNCHECKED
,CB_AudioFile.CHECKING
,CB_AudioFile.LOADED
)Used as the "statuses" parameter when calling the
CB_AudioFileCache#purge
method internally.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 theCB_AudioFileCache#audioFiles
property (and reloads it if we want to). NOTE: It does neither destroy nor remove theCB_AudioFile
object so it can be used for other purposes (and if aCB_AudioFile
object is given, it will be tried to be reused by theCB_AudioFileCache#createAudioFile
method internally if it is called). Uses theCB_AudioFileCache#removeAudioFile
method internally and returns its returning value. Internal usage only recommended.Parameters:
Name Type Argument Default Description audioObjectOrId
CB_AudioFile | string Used as the "audioObjectOrId" parameter when calling the
CB_AudioFileCache#removeAudioFile
method internally.reload
boolean <optional>
false Used as the "reload" parameter when calling the
CB_AudioFileCache#removeAudioFile
method internally.checkManually
boolean <optional>
false Used as the "checkManually" parameter when calling the
CB_AudioFileCache#removeAudioFile
method internally.Returns:
Returns null if the given "audioObjectOrId" parameter is not a valid
CB_AudioFile
object or itsCB_AudioFile#id
property is not set or when the "audioObjectOrId" parameter is an empty string. Returns aCB_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 theCB_AudioFileCache#createAudioFile
method is called internally (it will reuse thisCB_AudioFile
object). Otherwise, returns true if all goes well.- Type
- boolean | CB_AudioFile | null
-
removeSprite(spriteId) → {boolean}
-
Removes a sprite by its ID.
Parameters:
Name Type Description spriteId
string The identifier for the sprite.
Returns:
Returns true if the sprite has been deleted or false otherwise.
- Type
- boolean
-
removeSprites()
-
Removes all the sprites by clearing the
CB_AudioFileSprites#sprites
property. -
removeSpritesAll()
-
Alias for
CB_AudioFileSprites#removeSprites
. -
resumeAll( [loop] [, allowedRecursiveDelay] [, allowedRecursiveDelaySkipping] [, onPlayStart] [, onStop] [, audioFiles] [, spriteId]) → {array}
-
Resumes all the existing
CB_AudioFile
objects or the desired ones (if provided), which are paused (and not stopped). Can be focused on just one sprite identifier if desired. Uses theCB_AudioFileCache#resumeAll
method internally and returns its returning value. Internal usage only recommended. To resume a sprite, better use theCB_AudioFileSprites#resumeSprite
method instead.Parameters:
Name Type Argument Default Description loop
boolean <optional>
CB_AudioFile#loop
Used as the "loop" parameter when calling the
CB_AudioFileCache#resumeAll
method internally.allowedRecursiveDelay
boolean <optional>
CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT
Used as the "allowedRecursiveDelay" parameter when calling the
CB_AudioFileCache#resumeAll
method internally.allowedRecursiveDelaySkipping
boolean <optional>
CB_AudioFile#lastStopAt-CB_AudioFile#lastStartAt Used as the "allowedRecursiveDelaySkipping" parameter when calling the
CB_AudioFileCache#resumeAll
method internally.onPlayStart
function <optional>
Used as the "onPlayStart" parameter when calling the
CB_AudioFileCache#resumeAll
method internally.onStop
function <optional>
Used as the "onStop" parameter when calling the
CB_AudioFileCache#resumeAll
method internally.audioFiles
array <optional>
CB_AudioFileCache#audioFiles
Used as the "audioFiles" parameter when calling the
CB_AudioFileCache#resumeAll
method internally.spriteId
string <optional>
'_WITHOUT_SPRITE_ASSOCIATED' The identifier for the sprite. Internal usage only recommended.
Returns:
Returns null if a sprite identifier was given but it could not be found. Otherwise, returns a numeric array containing all the return values of each internal call to the
CB_AudioFileCache#play
method.- Type
- array
-
resumeSprite(spriteId [, loop] [, allowedRecursiveDelay] [, allowedRecursiveDelaySkipping] [, onPlayStart] [, onStop]) → {array}
-
Resumes all the
CB_AudioFile
objects that belong to the sound instances (created by theCB_AudioFileSprites#play
or theCB_AudioFileSprites#playSprite
methods) used by a given sprite identifier. Uses theCB_AudioFileSprites#resumeAll
method internally and returns its returning value.Parameters:
Name Type Argument Default Description spriteId
string Used as the "spriteId" parameter when calling the
CB_AudioFileSprites#resumeAll
method internally.loop
boolean <optional>
CB_AudioFile#loop
Used as the "loop" parameter when calling the
CB_AudioFileSprites#resumeAll
method internally.allowedRecursiveDelay
boolean <optional>
CB_Configuration.CrossBase.CB_AudioFile_AudioFileCache_ALLOWED_RECURSIVE_DELAY_DEFAULT
Used as the "allowedRecursiveDelay" parameter when calling the
CB_AudioFileSprites#resumeAll
method internally.allowedRecursiveDelaySkipping
boolean <optional>
stopAt-startAt Used as the "allowedRecursiveDelaySkipping" parameter when calling the
CB_AudioFileSprites#resumeAll
method internally.onPlayStart
function <optional>
Used as the "onPlayStart" parameter when calling the
CB_AudioFileSprites#resumeAll
method internally.onStop
function <optional>
Used as the "onStop" parameter when calling the
CB_AudioFileSprites#resumeAll
method internally.Returns:
Returns null if the sprite identifier given could not be found. Otherwise, returns a numeric array containing all the return values of each internal call to the
CB_AudioFileCache#play
method (called throughCB_AudioFileSprites#resumeAll
).- Type
- array
-
setAudioAPIAll(preferredAPIs [, callbackOk] [, callbackError] [, mandatory] [, forceReload] [, audioFiles]) → {integer}
-
Tries to change the audio API for all the existing
CB_AudioFile
objects or the desired ones (if provided). This method is not allowed to be called if a previous call to it did not finish yet. The function defined in the "callbackError" parameter, if any, will be called immediately if the method was previously called and it is still running currently. Uses theCB_AudioFileCache#setAudioAPIAll
method internally and returns its returning value.Parameters:
Name Type Argument Default Description preferredAPIs
array | string Used as the "preferredAPIs" parameter when calling the
CB_AudioFileCache#setAudioAPIAll
method internally.callbackOk
CB_AudioFileCache.setAudioAPIAll_CALLBACK_OK <optional>
Used as the "callbackOk" parameter when calling the
CB_AudioFileCache#setAudioAPIAll
method internally.callbackError
CB_AudioFileCache.setAudioAPIAll_CALLBACK_ERROR <optional>
Used as the "callbackError" parameter when calling the
CB_AudioFileCache#setAudioAPIAll
method internally.mandatory
boolean <optional>
false Used as the "mandatory" parameter when calling the
CB_AudioFileCache#setAudioAPIAll
method internally.forceReload
string <optional>
false Used as the "forceReload" parameter when calling the
CB_AudioFileCache#setAudioAPIAll
method internally.audioFiles
array <optional>
CB_AudioFileCache#audioFiles
Used as the "audioFiles" parameter when calling the
CB_AudioFileCache#setAudioAPIAll
method internally.Returns:
Returns the number of calls to the
CB_AudioFile#setAudioAPI
method that were performed (which should be the same number as theCB_AudioFile
objects in the "audioFiles" parameter).- Type
- integer
-
setAudioAPISprite(spriteId, preferredAPIs [, callbackOk] [, callbackError] [, mandatory] [, forceReload]) → {integer}
-
Tries to change the desired audio API of the
CB_AudioFile
objects that belong to the sound instances (created by theCB_AudioFileSprites#play
or theCB_AudioFileSprites#playSprite
methods) used by a given sprite identifier. Uses theCB_AudioFileSprites#setAudioAPIAll
method internally and returns its returning value.Parameters:
Name Type Argument Default Description spriteId
string The identifier for the sprite.
preferredAPIs
array Used as the "preferredAPIs" parameter when calling the
CB_AudioFileSprites#setAudioAPIAll
method internally.callbackOk
CB_AudioFileCache.setAudioAPIAll_CALLBACK_OK <optional>
Used as the "callbackOk" parameter when calling the
CB_AudioFileSprites#setAudioAPIAll
method internally.callbackError
CB_AudioFileCache.setAudioAPIAll_CALLBACK_ERROR <optional>
Used as the "callbackError" parameter when calling the
CB_AudioFileSprites#setAudioAPIAll
method internally.mandatory
boolean <optional>
false Used as the "mandatory" parameter when calling the
CB_AudioFileSprites#setAudioAPIAll
method internally.forceReload
string <optional>
false Used as the "forceReload" parameter when calling the
CB_AudioFileSprites#setAudioAPIAll
method internally.Returns:
Returns the number of calls to the
CB_AudioFile#setAudioAPI
method that were performed internally.- Type
- integer
-
setStartAtSprite(spriteId, startAt) → {boolean}
-
Sets when a sprite begins (stored in its "startAt" property), by sprite identifier.
Parameters:
Name Type Description spriteId
string The identifier for the sprite.
startAt
number The time (in milliseconds) of the audio file where the audio sprite starts.
Returns:
Returns true if the sprite has been modified or false otherwise.
- Type
- boolean
-
setStopAtSprite(spriteId, stopAt) → {boolean}
-
Sets when a sprite ends (stored in its "stopAt" property), by sprite identifier.
Parameters:
Name Type Description spriteId
string The identifier for the sprite.
stopAt
number The time (in milliseconds) of the audio file where the audio sprite ends.
Returns:
Returns true if the sprite has been modified or false otherwise.
- Type
- boolean
-
setVolumeAll( [volume] [, forceSetVolumeProperty] [, onSetVolume] [, audioFiles]) → {integer}
-
Sets the same volume for all the existing
CB_AudioFile
objects or the desired ones (if provided). Uses theCB_AudioFileCache#setVolumeAll
method internally and returns its returning value.Parameters:
Name Type Argument Default Description volume
number <optional>
CB_Speaker.getVolume()
|CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME
Used as the "volume" parameter when calling the
CB_AudioFileCache#setVolumeAll
method internally.forceSetVolumeProperty
boolean <optional>
false Used as the "forceSetVolumeProperty" parameter when calling the
CB_AudioFileCache#setVolumeAll
method internally.onSetVolume
function <optional>
Used as the "onSetVolume" parameter when calling the
CB_AudioFileCache#setVolumeAll
method internally.audioFiles
array <optional>
CB_AudioFileCache#audioFiles
Used as the "audioFiles" parameter when calling the
CB_AudioFileCache#setVolumeAll
method internally.Returns:
Returns the number of calls to the
CB_AudioFile#setVolume
method that were performed (which should be the same number as theCB_AudioFile
objects in the "audioFiles" parameter).- Type
- integer
-
setVolumeSprite(spriteId [, volume] [, forceSetVolumeProperty] [, onSetVolume]) → {integer}
-
Sets the same desired volume to all the
CB_AudioFile
objects that belong to the sound instances (created by theCB_AudioFileSprites#play
or theCB_AudioFileSprites#playSprite
methods) used by a given sprite identifier. Uses theCB_AudioFileSprites#setVolumeAll
method internally and returns its returning value.Parameters:
Name Type Argument Default Description spriteId
string The identifier for the sprite.
volume
number <optional>
CB_Speaker.getVolume()
|CB_Configuration.CrossBase.CB_Speaker_DEFAULT_VOLUME
Used as the "volume" parameter when calling the
CB_AudioFileSprites#setVolumeAll
method internally.forceSetVolumeProperty
boolean <optional>
false Used as the "forceSetVolumeProperty" parameter when calling the
CB_AudioFileSprites#setVolumeAll
method internally.onSetVolume
function <optional>
Used as the "onSetVolume" parameter when calling the
CB_AudioFileSprites#setVolumeAll
method internally.Returns:
Returns the number of calls to the
CB_AudioFile#setVolume
method that were performed internally.- Type
- integer
-
stopAll( [audioFiles]) → {integer}
-
Tries to stops all the existing
CB_AudioFile
objects or the desired ones (if provided), which are being played, by calling theirCB_AudioFile#stop
method internally. Uses theCB_AudioFileCache#stopAll
method internally and returns its returning value.Parameters:
Name Type Argument Default Description audioFiles
array <optional>
CB_AudioFileCache#audioFiles
Used as the "audioFiles" parameter when calling the
CB_AudioFileCache#stopAll
method internally.Returns:
Returns the number of calls to the
CB_AudioFile#stop
method that were performed (which should be the same number as theCB_AudioFile
objects in the "audioFiles" parameter).- Type
- integer
-
stopSprite(spriteId) → {integer}
-
Stops all the
CB_AudioFile
objects that belong to the sound instances (created by theCB_AudioFileSprites#play
or theCB_AudioFileSprites#playSprite
methods) which are playing used by a given sprite identifier. Uses theCB_AudioFileSprites#stopAll
method internally and returns its returning value.Parameters:
Name Type Description spriteId
string The identifier for the sprite.
Returns:
Returns the number of calls to the
CB_AudioFile#stop
method that were performed internally.- Type
- integer
-
unmuteAll( [onUnmute] [, audioFiles]) → {integer}
-
Unmutes all the existing
CB_AudioFile
objects or the desired ones (if provided). Uses theCB_AudioFileCache#unmuteAll
method internally and returns its returning value.Parameters:
Name Type Argument Default Description onUnmute
function <optional>
Used as the "onUnmute" parameter when calling the
CB_AudioFileCache#unmuteAll
method internally.audioFiles
array <optional>
CB_AudioFileCache#audioFiles
Used as the "audioFiles" parameter when calling the
CB_AudioFileCache#unmuteAll
method internally.Returns:
Returns the number of calls to the
CB_AudioFile#unmute
method that were performed (which should be the same number as theCB_AudioFile
objects in the "audioFiles" parameter).- Type
- integer
-
unmuteSprite(spriteId [, onUnmute]) → {integer}
-
Unmutes all the
CB_AudioFile
objects that belong to the sound instances (created by theCB_AudioFileSprites#play
or theCB_AudioFileSprites#playSprite
methods) used by a given sprite identifier. Uses theCB_AudioFileSprites#unmuteAll
method internally and returns its returning value.Parameters:
Name Type Argument Description spriteId
string The identifier for the sprite.
onUnmute
function <optional>
Used internally as the "onUnmute" parameter to call the
CB_AudioFileSprites#unmuteAll
method.Returns:
Returns the number of calls to the
CB_AudioFile#unmute
method that were performed internally.- Type
- integer
Type Definitions
-
DATA_OBJECT
-
Object with the desired data and options for the audio sprites. It is almost identical to the
CB_AudioFileCache.DATA_OBJECT
but adding a "sprites" property.Type:
- Object
- Source:
Properties:
Name Type Argument Default Description URIs
CB_AudioFileCache.URIS_OBJECT Object whose property names audio formats and their value is an array of strings with the URIs (audio file paths or audio data URIs) of the audio files in order of preference. The best audio format for the current client will be tried to be calculated and it will use the first working URI (audio file path or data URI). The more audio formats and URIs provided the better, as it will help to maximize the compatibility with as many clients as possible (as some audio APIs and client just support some formats, or use absolute paths instead of relative ones, etc.). Even with different formats, all provided URIs should belong to the same audio (this means same sound or same music, with same length, etc.). NOTE: Only some clients with some audio APIs will support data URIs. If a valid value is given, this will be added to the
CB_AudioFileCache#URIs
property.sprites
CB_AudioFileSprites.SPRITES_OBJECT <optional>
Object with the desired sprites. It will be used as the first parameter to call the
CB_AudioFileSprites#insertSprites
method internally. It will be added (after being processed) to theCB_AudioFileCache#sprites
property.id
string <optional>
"" Desired identifier for the audio file sprites object. Internal usage only recommended. If a valid value is given, this will be added to the
CB_AudioFileSprites#id
property as well as to theCB_AudioFileCache#id
property of the internally-createdCB_AudioFileCache
object.preferredAPIs
array <optional>
CB_Configuration.CrossBase.CB_AudioFileCache_PREFERRED_AUDIO_APIS
Array of strings with the preferred audio API or audio APIs, in order of preference. Possible audio APIs are "WAAPI" (HTML5 Web Audio API), "SM2" (SoundManager 2), "ACMP" (Apache Cordova Media Plugin) or "AAPI" (HTML5 Audio API). It will try to calculate and use the best one for the current client. If a valid value is given, this will be added to the
CB_AudioFileCache#preferredAPIs
property.preferredFormats
array <optional>
CB_Configuration.CrossBase.CB_AudioFileCache_PREFERRED_AUDIO_FORMATS
Array of strings with the preferred audio format or audio formats (they can include just the format as 'audio/ogg' or also the codec as for example 'audio/ogg; codecs="vorbis"'), in order of preference. It will try to calculate and use the best one for the current client. If a valid value is given, this will be added to the
CB_AudioFileCache#preferredFormats
property.minimumAudioFiles
integer <optional>
CB_AudioFileCache.minimumAudioFiles_DEFAULT
Minimum
CB_AudioFile
objects to create internally. It must be an integer being 1 the minimum. If a valid value is given, this will be added to theCB_AudioFileCache#minimumAudioFiles
property.maximumAudioFiles
integer <optional>
CB_AudioFileCache.maximumAudioFiles_DEFAULT
Maximum
CB_AudioFile
objects that are to be created internally. If it is set to null, there will not be a maximum (it will be unlimited). If an integer is provided, it must be the same number or greater than the value set in theCB_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 theCB_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 freeCB_AudioFile
objects reaches this limit. If provided, it must be an integer being 0 (zero) the minimum. It will end using a 25% of theCB_AudioFileCache#minimumAudioFiles
by default, rounded to ceil, allowing 0 (zero) minimum. If a valid value is given, this will be added to theCB_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 freeCB_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 theCB_AudioFileCache#minimumAudioFiles
by default, rounded to ceil, allowing 1 minimum. If a valid value is given, this will be added to theCB_AudioFileCache#newAudioFilesWhenNeeded
property.retries
integer <optional>
CB_AudioFileCache.retries_DEFAULT
Number of retries to try to load a
CB_AudioFile
object internally before trying to load the next possible one internally (if any). It must be an integer being 0 the minimum. If a valid value is given, this will be added to theCB_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 theCB_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 newCB_AudioFile
object needed. If a valid value is given, this will be added to theCB_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 theCB_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 theCB_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 currentCB_AudioFileCache
object. If a valid value is given, this will be added to theCB_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 theCB_AudioFileCache#onError
property.disableAutoLoad
boolean <optional>
false If set to true, it will not create automatically the
CB_AudioFile
objects by calling theCB_AudioFileCache#createAudioFiles
method internally. Internal usage only recommended. -
SPRITES_OBJECT
-
Object whose property names the identifiers of each sprite (a case-sensitive string) and their value is a
CB_AudioFileSprites.SPRITE_OBJECT
object.Type:
- Object
- Source:
Properties:
Name Type Description spriteInformation
CB_AudioFileSprites.SPRITE_OBJECT Being the name of each property the identifier of a sprite (a string which cannot be "_WITHOUT_SPRITE_ASSOCIATED" as it is a reserved name), the value will always be a
CB_AudioFileSprites.SPRITE_OBJECT
object.Example
{ "whole_audio" : {}, "first_sprite" : { stopAt: 10 }, "second_sprite" : { startAt: 10, stopAt: 20 }, "third_sprite" : { startAt: 20 }, ...}
-
SPRITE_OBJECT
-
An object representing an audio sprite which can contain, optionally, the "startAt" and "stopAt" properties with a numeric value (representing when the audio sprite starts and when it stops, respectively). If not set, the default "startAt" value will be 0 (zero) and the default "stopAt" value will be null (which means it will not stop until the end of the audio is reached unless it is paused or stopped before). The "fake" property should never be used as it is used internally to distinguish real sprites from fake ones (generated and returned by the
CB_AudioFileSprites#getSprite
method when a requested sprite is not found).Type:
- Object
- Source:
Properties:
Name Type Argument Default Description startAt
number <optional>
0 The time (in milliseconds) of the audio file where the audio sprite starts. If not provided, it will use the value of 0 (zero) which means that it will start from the beginning.
stopAt
number <optional>
CB_AudioFile_API.WAAPI#getDuration
() |CB_AudioFile_API.SM2#getDuration
() |CB_AudioFile_API.ACMP#getDuration
() |CB_AudioFile_API.AAPI#getDuration
()The time (in milliseconds) of the audio file where the audio sprite stops. If not provided (not recommended), it will use the whole duration of the file (which means until it reaches its end). NOTE: Due to some possible problems between clients with different audio APIs calculating the duration of an audio file, it is recommended to always set the "stopAt" property even when we want it to stop at the end of the audio.
Example
{ startAt: 10, stopAt: 20 }
-
getAudioFilesUsed_OBJECT
-
Object returned by the
CB_AudioFileSprites#getAudioFilesUsed
method. Each property names will be the sprites identifiers except the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated (if we wanted to include them).Type:
- Object
- Source:
Properties:
Name Type Description spriteId
CB_AudioFile Each property name will be a sprite identifier (it can be "_WITHOUT_SPRITE_ASSOCIATED" for sound instances without a sprite associated, if we wanted to include them). The value will be a numeric array with the
CB_AudioFile
objects used.