crossbrowdy
Version:
A Multimedia JavaScript framework to create real cross-platform and hybrid game engines, games, emulators, multimedia libraries and apps.
710 lines (618 loc) • 116 kB
HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>CrossBrowdy API documentation Source: CrossBase/audiovisual/audio/CB_AudioFileSprites.js</title>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/sunlight.default.css">
<link type="text/css" rel="stylesheet" href="styles/site.cosmo.css">
</head>
<body style="min-width:800px; overflow-wrap:break-word; word-wrap:break-word; word-break:break-word; line-break:strict; hyphens:none; -webkit-hyphens:none; -moz-hyphens:none;">
<div class="navbar navbar-default navbar-fixed-top ">
<div class="container">
<div class="navbar-header">
<a class="navbar-brand" href="index.html">CrossBrowdy API documentation</a>
<button class="navbar-toggle" type="button" data-toggle="collapse" data-target="#topNavigation">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
</div>
<div class="navbar-collapse collapse" id="topNavigation">
<ul class="nav navbar-nav">
<li class="dropdown">
<a href="namespaces.list.html" class="dropdown-toggle" data-toggle="dropdown">Namespaces<b class="caret"></b></a>
<ul class="dropdown-menu inline">
<li><a href="CB_Arrays.html">CB_Arrays</a></li><li><a href="CB_AudioDetector.html">CB_AudioDetector</a></li><li><a href="CB_Client.html">CB_Client</a></li><li><a href="CB_Collisions.html">CB_Collisions</a></li><li><a href="CB_Configuration.html">CB_Configuration</a></li><li><a href="CB_Configuration.CrossBase.html">CB_Configuration.CrossBase</a></li><li><a href="CB_Configuration.CrossBrowdy.html">CB_Configuration.CrossBrowdy</a></li><li><a href="CB_Controllers.html">CB_Controllers</a></li><li><a href="CB_Controllers_Proprietary.html">CB_Controllers_Proprietary</a></li><li><a href="CB_Controllers_Proprietary.WII.html">CB_Controllers_Proprietary.WII</a></li><li><a href="CB_Controllers_Proprietary.WII_U.html">CB_Controllers_Proprietary.WII_U</a></li><li><a href="CB_Device.html">CB_Device</a></li><li><a href="CB_Device.AmbientLight.html">CB_Device.AmbientLight</a></li><li><a href="CB_Device.Battery.html">CB_Device.Battery</a></li><li><a href="CB_Device.Location.html">CB_Device.Location</a></li><li><a href="CB_Device.Motion.html">CB_Device.Motion</a></li><li><a href="CB_Device.Orientation.html">CB_Device.Orientation</a></li><li><a href="CB_Device.Proximity.html">CB_Device.Proximity</a></li><li><a href="CB_Device.Vibration.html">CB_Device.Vibration</a></li><li><a href="CB_Elements.html">CB_Elements</a></li><li><a href="CB_Events.html">CB_Events</a></li><li><a href="CB_Keyboard.html">CB_Keyboard</a></li><li><a href="CB_Keyboard.chars.html">CB_Keyboard.chars</a></li><li><a href="CB_Keyboard.extended.html">CB_Keyboard.extended</a></li><li><a href="CB_Keyboard.keys.html">CB_Keyboard.keys</a></li><li><a href="CB_Modules.html">CB_Modules</a></li><li><a href="CB_Mouse.html">CB_Mouse</a></li><li><a href="CB_Mouse.CursorImage.html">CB_Mouse.CursorImage</a></li><li><a href="CB_Net.html">CB_Net</a></li><li><a href="CB_Net.Fetch.html">CB_Net.Fetch</a></li><li><a href="CB_Net.REST.html">CB_Net.REST</a></li><li><a href="CB_Net.Sockets.html">CB_Net.Sockets</a></li><li><a href="CB_Net.Sockets.SockJS.html">CB_Net.Sockets.SockJS</a></li><li><a href="CB_Net.XHR.html">CB_Net.XHR</a></li><li><a href="CB_Pointer.html">CB_Pointer</a></li><li><a href="CB_Screen.html">CB_Screen</a></li><li><a href="CB_Speaker.html">CB_Speaker</a></li><li><a href="CB_Touch.html">CB_Touch</a></li><li><a href="CB_baseSymbols.html">CB_baseSymbols</a></li>
</ul>
</li>
<li class="dropdown">
<a href="classes.list.html" class="dropdown-toggle" data-toggle="dropdown">Classes<b class="caret"></b></a>
<ul class="dropdown-menu inline">
<li><a href="CB_AudioFile.html">CB_AudioFile</a></li><li><a href="CB_AudioFileCache.html">CB_AudioFileCache</a></li><li><a href="CB_AudioFileSprites.html">CB_AudioFileSprites</a></li><li><a href="CB_AudioFileSpritesPool.html">CB_AudioFileSpritesPool</a></li><li><a href="CB_AudioFile_API.AAPI.html">CB_AudioFile_API.AAPI</a></li><li><a href="CB_AudioFile_API.ACMP.html">CB_AudioFile_API.ACMP</a></li><li><a href="CB_AudioFile_API.SM2.html">CB_AudioFile_API.SM2</a></li><li><a href="CB_AudioFile_API.WAAPI.html">CB_AudioFile_API.WAAPI</a></li><li><a href="CB_Canvas.html">CB_Canvas</a></li><li><a href="CB_GraphicSprites.html">CB_GraphicSprites</a></li><li><a href="CB_GraphicSpritesScene.html">CB_GraphicSpritesScene</a></li>
</ul>
</li>
<li class="dropdown">
<a href="global.html" class="dropdown-toggle" data-toggle="dropdown">Global<b class="caret"></b></a>
<ul class="dropdown-menu inline">
<li><a href="global.html#CB_BASE_NAME">CB_BASE_NAME</a></li><li><a href="global.html#CB_CREDITS_DEFAULT">CB_CREDITS_DEFAULT</a></li><li><a href="global.html#CB_NAME">CB_NAME</a></li><li><a href="global.html#CB_OPTIONS">CB_OPTIONS</a></li><li><a href="global.html#CB_VERSION">CB_VERSION</a></li><li><a href="global.html#CB_addCredits">CB_addCredits</a></li><li><a href="global.html#CB_baseToBase">CB_baseToBase</a></li><li><a href="global.html#CB_baseToInt">CB_baseToInt</a></li><li><a href="global.html#CB_br2nl">CB_br2nl</a></li><li><a href="global.html#CB_brToNl">CB_brToNl</a></li><li><a href="global.html#CB_combineArraysOrObjects">CB_combineArraysOrObjects</a></li><li><a href="global.html#CB_combineAutomatically">CB_combineAutomatically</a></li><li><a href="global.html#CB_combineJSON">CB_combineJSON</a></li><li><a href="global.html#CB_combineURIParameters">CB_combineURIParameters</a></li><li><a href="global.html#CB_combineURLParameters">CB_combineURLParameters</a></li><li><a href="global.html#CB_console">CB_console</a></li><li><a href="global.html#CB_copyObject">CB_copyObject</a></li><li><a href="global.html#CB_countDecimalDigits">CB_countDecimalDigits</a></li><li><a href="global.html#CB_countDecimalPart">CB_countDecimalPart</a></li><li><a href="global.html#CB_countDecimals">CB_countDecimals</a></li><li><a href="global.html#CB_countIntegerDigits">CB_countIntegerDigits</a></li><li><a href="global.html#CB_countIntegerPart">CB_countIntegerPart</a></li><li><a href="global.html#CB_credits">CB_credits</a></li><li><a href="global.html#CB_forEach">CB_forEach</a></li><li><a href="global.html#CB_forceString">CB_forceString</a></li><li><a href="global.html#CB_getBase64StringObject">CB_getBase64StringObject</a></li><li><a href="global.html#CB_getCookie">CB_getCookie</a></li><li><a href="global.html#CB_getDatum">CB_getDatum</a></li><li><a href="global.html#CB_getJSONPropertyValue">CB_getJSONPropertyValue</a></li><li><a href="global.html#CB_getLZStringObject">CB_getLZStringObject</a></li><li><a href="global.html#CB_getValueIndex">CB_getValueIndex</a></li><li><a href="global.html#CB_getValuePath">CB_getValuePath</a></li><li><a href="global.html#CB_includeJSFile">CB_includeJSFile</a></li><li><a href="global.html#CB_indexOf">CB_indexOf</a></li><li><a href="global.html#CB_init">CB_init</a></li><li><a href="global.html#CB_intToBase">CB_intToBase</a></li><li><a href="global.html#CB_isArray">CB_isArray</a></li><li><a href="global.html#CB_isEmail">CB_isEmail</a></li><li><a href="global.html#CB_isFileLocal">CB_isFileLocal</a></li><li><a href="global.html#CB_isString">CB_isString</a></li><li><a href="global.html#CB_lastIndexOf">CB_lastIndexOf</a></li><li><a href="global.html#CB_ltrim">CB_ltrim</a></li><li><a href="global.html#CB_nl2br">CB_nl2br</a></li><li><a href="global.html#CB_nlToBr">CB_nlToBr</a></li><li><a href="global.html#CB_numberFormat">CB_numberFormat</a></li><li><a href="global.html#CB_numberOfDecimalDigits">CB_numberOfDecimalDigits</a></li><li><a href="global.html#CB_numberOfDecimals">CB_numberOfDecimals</a></li><li><a href="global.html#CB_numberOfIntegerDigits">CB_numberOfIntegerDigits</a></li><li><a href="global.html#CB_parseJSON">CB_parseJSON</a></li><li><a href="global.html#CB_parseString">CB_parseString</a></li><li><a href="global.html#CB_regularExpressionString">CB_regularExpressionString</a></li><li><a href="global.html#CB_renderString">CB_renderString</a></li><li><a href="global.html#CB_replaceAll">CB_replaceAll</a></li><li><a href="global.html#CB_rtrim">CB_rtrim</a></li><li><a href="global.html#CB_scriptPath">CB_scriptPath</a></li><li><a href="global.html#CB_scriptPathCalculate">CB_scriptPathCalculate</a></li><li><a href="global.html#CB_setCookie">CB_setCookie</a></li><li><a href="global.html#CB_setDatum">CB_setDatum</a></li><li><a href="global.html#CB_sizeOf">CB_sizeOf</a></li><li><a href="global.html#CB_sizeof">CB_sizeof</a></li><li><a href="global.html#CB_stringifyJSON">CB_stringifyJSON</a></li><li><a href="global.html#CB_symmetricCall">CB_symmetricCall</a></li><li><a href="global.html#CB_symmetricCallClear">CB_symmetricCallClear</a></li><li><a href="global.html#CB_this">CB_this</a></li><li><a href="global.html#CB_trim">CB_trim</a></li>
</ul>
</li>
</ul>
<div class="col-sm-3 col-md-3">
<form class="navbar-form" role="search">
<div class="input-group">
<input type="text" class="form-control" placeholder="Search" name="q" id="search-input">
<div class="input-group-btn">
<button class="btn btn-default" id="search-submit"><i class="glyphicon glyphicon-search"></i></button>
</div>
</div>
</form>
</div>
</div>
</div>
</div>
<div class="container" id="toc-content" style="width:100%;">
<div class="row" style="width:100%;">
<div class="col-md-12">
<div id="main">
<h1 class="page-title">Source: CrossBase/audiovisual/audio/CB_AudioFileSprites.js</h1>
<section>
<article>
<pre
class="sunlight-highlight-javascript linenums">/**
* @file Audio sprites management. Contains the {@link CB_AudioFileSprites} class.
* @author Joan Alba Maldonado <workindalian@gmail.com>
* @license Creative Commons Attribution 4.0 International. See more at {@link https://crossbrowdy.com/about#what_is_the_crossbrowdy_copyright_and_license}.
*/
/**
* 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 {@link CB_AudioFileSprites#getSprite} method when a requested sprite is not found).
* @example { startAt: 10, stopAt: 20 }
* @memberof CB_AudioFileSprites
* @typedef {Object} CB_AudioFileSprites.SPRITE_OBJECT
* @property {number} [startAt=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.
* @property {number} [stopAt={@link CB_AudioFile_API.WAAPI#getDuration}() | {@link CB_AudioFile_API.SM2#getDuration}() | {@link CB_AudioFile_API.ACMP#getDuration}() | {@link 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.
*/
/**
* Object whose property names the identifiers of each sprite (a case-sensitive string) and their value is a {@link CB_AudioFileSprites.SPRITE_OBJECT} object.
* @example
* {
* "whole_audio" : {},
* "first_sprite" : { stopAt: 10 },
* "second_sprite" : { startAt: 10, stopAt: 20 },
* "third_sprite" : { startAt: 20 },
* ...
* }
* @memberof CB_AudioFileSprites
* @typedef {Object} CB_AudioFileSprites.SPRITES_OBJECT
* @property {CB_AudioFileSprites.SPRITE_OBJECT} spriteInformation - 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 {@link CB_AudioFileSprites.SPRITE_OBJECT} object.
*/
/**
* Object with the desired data and options for the audio sprites. It is almost identical to the {@link CB_AudioFileCache.DATA_OBJECT} but adding a "sprites" property.
* @memberof CB_AudioFileSprites
* @typedef {Object} CB_AudioFileSprites.DATA_OBJECT
* @property {CB_AudioFileCache.URIS_OBJECT} 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. 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 {@link CB_AudioFileCache#URIs} property.
* @property {CB_AudioFileSprites.SPRITES_OBJECT} [sprites] Object with the desired sprites. It will be used as the first parameter to call the {@link CB_AudioFileSprites#insertSprites} method internally. It will be added (after being processed) to the {@link CB_AudioFileCache#sprites} property.
* @property {string} [id=""] - Desired identifier for the audio file sprites object. Internal usage only recommended. If a valid value is given, this will be added to the {@link CB_AudioFileSprites#id} property as well as to the {@link CB_AudioFileCache#id} property of the internally-created {@link CB_AudioFileCache} object.
* @property {array} [preferredAPIs={@link 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]{@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API}), "SM2" ([SoundManager 2]{@link http://schillmania.com/projects/soundmanager2/}), "ACMP" ([Apache Cordova Media Plugin]{@link https://github.com/apache/cordova-plugin-media}) or "AAPI" ([HTML5 Audio API]{@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio}). 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 {@link CB_AudioFileCache#preferredAPIs} property.
* @property {array} [preferredFormats={@link 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 {@link CB_AudioFileCache#preferredFormats} property.
* @property {integer} [minimumAudioFiles={@link CB_AudioFileCache.minimumAudioFiles_DEFAULT}] - Minimum {@link 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 {@link CB_AudioFileCache#minimumAudioFiles} property.
* @property {integer} [maximumAudioFiles={@link CB_AudioFileCache.maximumAudioFiles_DEFAULT}] - Maximum {@link 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 {@link 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 {@link CB_AudioFileCache#maximumAudioFiles} property.
* @property {integer} [minimumAudioFilesFree=parseInt({@link CB_AudioFileCache#minimumAudioFiles} * 0.25 + 0.5)] - New {@link CB_AudioFile} objects will be created internally when the number of free {@link 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 {@link CB_AudioFileCache#minimumAudioFiles} by default, rounded to ceil, allowing 0 (zero) minimum. If a valid value is given, this will be added to the {@link CB_AudioFileCache#minimumAudioFilesFree} property.
* @property {integer} [newAudioFilesWhenNeeded=Math.min(parseInt({@link CB_AudioFileCache#minimumAudioFiles} * 0.1 + 0.5), 1)] - Number of new {@link CB_AudioFile} objects to create internally when the minimum limit of free {@link CB_AudioFile} objects ({@link 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 {@link CB_AudioFileCache#minimumAudioFiles} by default, rounded to ceil, allowing 1 minimum. If a valid value is given, this will be added to the {@link CB_AudioFileCache#newAudioFilesWhenNeeded} property.
* @property {integer} [retries={@link CB_AudioFileCache.retries_DEFAULT}] - Number of retries to try to load a {@link CB_AudioFile} object internally before trying to load the next possible one internally (if any). It must be an integer being 0 the minimum. If a valid value is given, this will be added to the {@link CB_AudioFileCache#retries} property.
* @property {boolean} [checkManually={@link CB_AudioFileCache.checkManually_DEFAULT}] - Tells whether the {@link CB_AudioFile} objects must be checked automatically or not (manually) by default. If a valid value is given, this will be added to the {@link CB_AudioFileCache#checkManually} property.
* @property {boolean} [checkManuallyOnNeededCreated={@link CB_AudioFileCache.checkManuallyOnNeededCreated_DEFAULT}] - Tells whether the {@link CB_AudioFile} objects must be checked automatically or not (manually) when creates a new {@link CB_AudioFile} object needed. If a valid value is given, this will be added to the {@link CB_AudioFileCache#checkManuallyOnNeededCreated} property.
* @property {boolean} [checkManuallyOnPlayingFailed={@link CB_AudioFileCache.checkManuallyOnPlayingFailed_DEFAULT}] - Tells whether the {@link 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 {@link CB_AudioFileCache#checkManuallyOnPlayingFailed} property.
* @property {boolean} [checkManuallyOnCheckingFailed={@link CB_AudioFileCache.checkManuallyOnCheckingFailed_DEFAULT}] - Tells whether the {@link 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 {@link CB_AudioFileCache#checkManuallyOnCheckingFailed} property.
* @property {function} [onLoad] - Desired function to be called once the cache has been loaded. The first and unique parameter will be an integer with the {@link CB_AudioFile} objects that still need to be checked, if any, being "this" the current {@link CB_AudioFileCache} object. If a valid value is given, this will be added to the {@link CB_AudioFileCache#onLoad} property.
* @property {function} [onError] - 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 {@link CB_AudioFileCache} object. If a valid value is given, this will be added to the {@link CB_AudioFileCache#onError} property.
* @property {boolean} [disableAutoLoad=false] - If set to true, it will not create automatically the {@link CB_AudioFile} objects by calling the {@link CB_AudioFileCache#createAudioFiles} method internally. Internal usage only recommended.
*/
/**
* 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.
* @class
* @classdesc Class to manage audio sprites of a {@link CB_AudioFileCache} object (used internally).
* @param {CB_AudioFileSprites.DATA_OBJECT} [dataObject] - 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 {@link CB_AudioFileCache} object internally.
* @returns {CB_AudioFileSprites} Returns a new {@link CB_AudioFileSprites} object.
* @todo Do not allow to create one object with an "id" which has already been used (unless the value is undefined, null...).
* @todo Think about using wrapper to replace "this" in callbacks (callbackOk, callbackError) to point to the {@link CB_AudioFileSprites} object itself.
* @todo Method getCopy and static method filterProperties (similar to the ones from {@link CB_GraphicSprites} and {@link CB_GraphicSpritesScene}).
*/
var CB_AudioFileSprites = function(dataObject)
{
//Creates an instance of this object and returns it in the case that it is being called from an unexpected context:
if (this === window || !(this instanceof CB_AudioFileSprites)) { return new CB_AudioFileSprites(dataObject); }
//Properties and variables:
/**
* Stores the identifier for the audio file sprites object.
* @var
* @readonly
* @type {string}
* @default
*/
this.id = "";
/**
* Object with information about the sprites.
* @var
* @readonly
* @type {CB_AudioFileSprites.SPRITES_OBJECT}
* @default
*/
this.sprites = {};
/**
* 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 {@link CB_AudioFileSprites#play} method). Internal usage only recommended.
* @var
* @readonly
* @type {Object}
* @default { "_WITHOUT_SPRITE_ASSOCIATED" : [] }
*/
this.spriteSoundInstances = { "_WITHOUT_SPRITE_ASSOCIATED" : [] }; //Object with the sound instances associated to each sprite ID.
//If not defined, defines a fake prototype object:
CB_AudioFileSprites._audioFileCachePrototype = CB_AudioFileSprites._audioFileCachePrototype ||
{
DEFAULT_ERROR_MESSAGE : "CB_AudioFileCache object not loaded (using prototype).",
usingPrototype : true,
status : CB_AudioFileCache.UNLOADED,
audioFiles : [],
audioFilesCreated : 0,
audioFilesFreePointer : 0,
soundInstancesQueued : {},
duration : 0,
destructor : function() {},
createAudioFiles : function() { return 0; },
createAudioFile : function(URIs, preferredAPIs, preferredFormats, audioObject, callbackOk, callbackError)
{
if (typeof(callbackError) === "function") { callbackError.call(CB_AudioFileSprites._audioFileCachePrototype, DEFAULT_ERROR_MESSAGE); }
return null;
},
clearAudioFiles : function() { return []; },
removeAudioFile : function() { return null; },
purge : function() { return 0; },
getFreeAudioFile : function() { return { "object" : null, "index" : -1 }; },
isAudioFileFree : function() { return false; },
clearSoundInstances : function() { return 0; },
cancelSoundInstances : function() { return false; },
cancelSoundInstance : function() { return false; },
getAudioFileBySoundInstanceId : function() { return null; },
play : function(startAt, stopAt, loop, volume, allowedRecursiveDelay, allowedRecursiveDelaySkipping, onPlayStart, onStop)
{
if (typeof(onStop) === "function") { onStop(); }
return null;
},
executeFunctionAll : function() { return 0; },
destroyAll : function() { return 0; },
checkPlayingAll : function(callbackOk, callbackError)
{
if (typeof(callbackError) === "function") { callbackError.call(CB_AudioFileSprites._audioFileCachePrototype, DEFAULT_ERROR_MESSAGE); }
return 0;
},
playAll : function(startAt, stopAt, loop, volume, avoidDelayedPlay, allowedRecursiveDelay, onPlayStart, onStop)
{
if (typeof(onStop) === "function") { onStop(); }
return 0;
},
stopAll : function() { return 0; },
playAndStopAll : function() { return 0; },
pauseAll : function() { return 0; },
resumeAll : function(loop, allowedRecursiveDelay, allowedRecursiveDelaySkipping, onPlayStart, onStop)
{
if (typeof(onStop) === "function") { onStop(); }
return 0;
},
muteAll : function() { return 0; },
unmuteAll : function() { return 0; },
setVolumeAll : function() { return 0; },
setAudioAPIAll : function(preferredAPIs, callbackOk, callbackError)
{
if (typeof(callbackError) === "function") { callbackError.call(CB_AudioFileSprites._audioFileCachePrototype, DEFAULT_ERROR_MESSAGE); }
return 0;
},
getStatus : function() { return CB_AudioFileCache.UNLOADED; },
getStatusString : function() { return "UNLOADED"; },
getAudioFilesFreeNumber : function() { return 0; },
getAudioFiles : function() { return []; },
getAudioFilesFree : function() { return []; },
getAudioFilesBusy : function() { return []; },
getAudioFilesNumber : function() { return 0; },
getDuration : function() { return 0; },
getProgress : function() { return 0; },
isPlaying : function() { return false; }
};
/**
* Contains the {@link CB_AudioFileCache} object. Internal usage only recommended.
* @var
* @readonly
* @type {CB_AudioFileCache}
* @default
*/
this.audioFileCache = CB_AudioFileSprites._audioFileCachePrototype; //Keeps the CB_AudioFileCache object.
//Calls the constructor of the object when creates an instance:
return this._init(dataObject);
}
//Constructor:
CB_AudioFileSprites.prototype._init = function(dataObject)
{
/*
FORMAT:
dataObject =
{
[id : String,]
[preferredAPIs : Array<String>,]
[preferredFormats : Array<String>,]
URIs : Object,
[minimumAudioFiles : Integer,]
[maximumAudioFiles : Integer,]
[minimumAudioFilesFree : Integer,]
[newAudioFilesWhenNeeded : Integer,]
[retries : Integer,]
[checkManually : Boolean,]
[checkManuallyOnNeededCreated : Boolean,]
[checkManuallyOnPlayingFailed : Boolean,]
[checkManuallyOnCheckingFailed : Boolean,]
[disableAutoLoad : Boolean,]
[onLoad : Function,]
[onError : Function,]
sprites :
{
"sprite_id" :
{
[startAt : Integer,]
[stopAt : Integer,]
}
[, ...]
}
};
*/
//Tries to load the data (if any):
this.load(dataObject);
//Returns the object:
return this;
}
/**
* 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 {@link CB_AudioFileCache} object as ABORTED ({@link CB_AudioFileCache.ABORTED} value).
* @function
* @param {boolean} [stopSounds=false] - Used as the "stopSounds" parameter when calling internally the {@link CB_AudioFileCache#destructor} method of the {@link CB_AudioFileCache} object.
* @param {boolean} [preventAbortedStatus=false] - If set to true (not recommended), it will not assign the status of "ABORTED" (it will not assign the value of {@link CB_AudioFileCache.ABORTED} to the {@link CB_AudioFileCache#status} property).
*/
CB_AudioFileSprites.prototype.destructor = function(stopSounds, preventAbortedStatus)
{
//Resets properties to their default value:
this.sprites = {};
this.spriteSoundInstances = { "_WITHOUT_SPRITE_ASSOCIATED" : [] };
//Destroys the CB_AudioFileCache object:
this.audioFileCache.destructor(stopSounds, preventAbortedStatus);
this.audioFileCache = CB_AudioFileSprites._audioFileCachePrototype;
}
/**
* 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.
* @function
* @param {CB_AudioFileSprites.DATA_OBJECT} dataObject - Object with the desired data and options for the audio file sprites.
* @returns {CB_AudioFileSprites|null} If a "dataObject" is given, it returns the current {@link CB_AudioFileSprites} object. Otherwise, it returns null.
*/
CB_AudioFileSprites.prototype.load = function(dataObject)
{
if (typeof(dataObject) === "undefined" || dataObject === null) { return null; }
//Destroys all previous data (if any):
this.destructor(true, true); //Also stops all sounds.
//Sanitizes the given data:
dataObject.id = CB_trim(dataObject.id);
//Sets the new data:
if (dataObject.id !== "") { this.id = dataObject.id; }
//Inserts the sprites:
if (typeof(dataObject.sprites) !== "undefined" && dataObject.sprites !== null)
{
this.removeSprites();
this.insertSprites(dataObject.sprites);
}
//Creates the audio file cache object:
this.audioFileCache = new CB_AudioFileCache(dataObject);
return this;
}
/**
* Alias for {@link CB_AudioFileSprites#removeSprites}.
* @function CB_AudioFileSprites#removeSpritesAll
* @see {@link CB_AudioFileSprites#removeSprites}
*/
/**
* Removes all the sprites by clearing the {@link CB_AudioFileSprites#sprites} property.
* @function
*/
CB_AudioFileSprites.prototype.removeSprites = CB_AudioFileSprites.prototype.removeSpritesAll = function()
{
this.sprites = {};
}
/**
* 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).
* @function
* @param {CB_AudioFileSprites.SPRITES_OBJECT} sprites - Object with the desired sprites.
* @returns {integer} Returns the number of sprites inserted.
*/
CB_AudioFileSprites.prototype.insertSprites = function(sprites)
{
var inserted = 0;
if (typeof(sprites) !== "undefined" && sprites !== null)
{
for (var spriteId in sprites)
{
//Inserts the sprite:
if (this.insertSprite(sprites[spriteId], spriteId)) { inserted++; }
}
}
return inserted;
}
/**
* 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).
* @function
* @param {CB_AudioFileSprites.SPRITE_OBJECT} sprite - Object with the desired sprite.
* @param {string} spriteId - The identifier for the sprite.
* @returns {boolean} Returns true if the sprite has been inserted or false otherwise.
*/
CB_AudioFileSprites.prototype.insertSprite = function(sprite, spriteId)
{
if (typeof(spriteId) === "undefined" || spriteId === null) { return false; }
this.sprites[spriteId] = {};
this.setStartAtSprite(spriteId, (typeof(sprite.startAt) === "undefined") ? undefined : sprite.startAt);
this.setStopAtSprite(spriteId, (typeof(sprite.stopAt) === "undefined") ? undefined : sprite.stopAt);
if (typeof(this.spriteSoundInstances[spriteId]) === "undefined" || this.spriteSoundInstances[spriteId] === null)
{
this.spriteSoundInstances[spriteId] = [];
}
return true;
}
/**
* Sets when a sprite begins (stored in its "startAt" property), by sprite identifier.
* @function
* @param {string} spriteId - The identifier for the sprite.
* @param {number} startAt - The time (in milliseconds) of the audio file where the audio sprite starts.
* @returns {boolean} Returns true if the sprite has been modified or false otherwise.
*/
CB_AudioFileSprites.prototype.setStartAtSprite = function(spriteId, startAt)
{
if (typeof(this.sprites[spriteId]) === "undefined" || this.sprites[spriteId] === null) { return false; }
this.sprites[spriteId].startAt = 0;
if (typeof(startAt) !== "undefined" && startAt !== null && !isNaN(startAt) && startAt >= 0 && this.sprites[spriteId].startAt !== startAt)
{
this.sprites[spriteId].startAt = startAt;
return true;
}
return false;
}
/**
* Sets when a sprite ends (stored in its "stopAt" property), by sprite identifier.
* @function
* @param {string} spriteId - The identifier for the sprite.
* @param {number} stopAt - The time (in milliseconds) of the audio file where the audio sprite ends.
* @returns {boolean} Returns true if the sprite has been modified or false otherwise.
*/
CB_AudioFileSprites.prototype.setStopAtSprite = function(spriteId, stopAt)
{
if (typeof(this.sprites[spriteId]) === "undefined" || this.sprites[spriteId] === null) { return false; }
this.sprites[spriteId].stopAt = null;
if (typeof(stopAt) !== "undefined" && stopAt !== null && !isNaN(stopAt) && stopAt > this.sprites[spriteId].startAt && this.sprites[spriteId].stopAt !== stopAt)
{
this.sprites[spriteId].stopAt = stopAt;
return true;
}
return false;
}
/**
* Removes a sprite by its ID.
* @function
* @param {string} spriteId - The identifier for the sprite.
* @returns {boolean} Returns true if the sprite has been deleted or false otherwise.
*/
CB_AudioFileSprites.prototype.removeSprite = function(spriteId)
{
if (typeof(this.sprites[spriteId]) !== "undefined" && this.sprites[spriteId] !== null)
{
this.sprites[spriteId] = null;
var sprites = {};
var deleted = false;
for (spriteId in this.sprites)
{
if (typeof(this.sprites[spriteId]) !== "undefined" && this.sprites[spriteId] !== null)
{
sprites[spriteId] = this.sprites[spriteId];
deleted = true;
}
}
this.sprites = sprites;
return deleted;
}
return false;
}
/**
* Returns a sprite by its ID.
* @function
* @param {string} spriteId - The identifier for the sprite.
* @returns {CB_AudioFileSprites.SPRITE_OBJECT} 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 }.
*/
CB_AudioFileSprites.prototype.getSprite = function(spriteId)
{
if (typeof(this.sprites[spriteId]) !== "undefined")
{
return this.sprites[spriteId];
}
return { "startAt" : 0, "stopAt" : null, "fake" : true };
}
/**
* Returns an object with the sprites (and includes "_WITHOUT_SPRITE_ASSOCIATED" if we want to).
* @function
* @param {boolean} [includeWithoutSpriteAssociated=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 {@link CB_AudioFileSprites#sprites} property and had a value which is not an empty object). If set to false, the returning object will not contain the "_WITHOUT_SPRITE_ASSOCIATED" property unless the property existed before in the object stored in the {@link CB_AudioFileSprites#sprites} property.
* @returns {CB_AudioFileSprites.SPRITES_OBJECT} Returns an object with the sprites (and includes "_WITHOUT_SPRITE_ASSOCIATED" if we want to).
*/
CB_AudioFileSprites.prototype.getSprites = function(includeWithoutSpriteAssociated)
{
if (!includeWithoutSpriteAssociated) { return this.sprites; }
else
{
var sprites = {};
sprites["_WITHOUT_SPRITE_ASSOCIATED"] = {};
for (var spriteId in this.sprites)
{
sprites[spriteId] = this.sprites[spriteId];
}
return sprites;
}
}
/**
* Returns an array of the sound instance identifiers (created by the {@link CB_AudioFileSprites#play} method) used by the given sprite identifier.
* @function
* @param {string} spriteId - The identifier for the sprite.
* @returns {array} Returns a numeric array of the sound instances (created by the {@link CB_AudioFileSprites#play} method) used by the given sprite identifier.
*/
CB_AudioFileSprites.prototype.getSoundInstancesIdBySpriteId = function(spriteId)
{
if (typeof(this.spriteSoundInstances[spriteId]) !== "undefined")
{
return this.spriteSoundInstances[spriteId];
}
return [];
}
/**
* Returns the sound instances (their ID) used (stored in the {@link CB_AudioFileSprites#spriteSoundInstances} property).
* @function
* @param {boolean} [oneDimension=false] - If set to true, it will return the {@link 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.
* @param {boolean} [includeWithoutSpriteAssociated=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 {@link CB_AudioFileSprites#getSprites} method internally. Only used when the "oneDimension" parameter is set to true.
* @returns {Object|array} Returns the sound instances (their ID) used (stored in the {@link 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).
*/
CB_AudioFileSprites.prototype.getSoundInstancesId = function(oneDimension, includeWithoutSpriteAssociated)
{
if (!oneDimension)
{
return this.spriteSoundInstances;
}
else
{
var soundInstances = [];
var soundInstancesSprite;
var soundInstancesSpriteLength;
var y = 0;
var x = 0;
var sprites = this.getSprites(includeWithoutSpriteAssociated);
for (var spriteId in sprites)
{
soundInstancesSprite = this.getSoundInstancesIdBySpriteId(spriteId);
soundInstancesSpriteLength = soundInstancesSprite.length;
for (x = 0; x < soundInstancesSpriteLength; x++)
{
soundInstances[y++] = soundInstancesSprite[x];
}
}
return soundInstances;
}
}
/**
* Returns an array of the {@link CB_AudioFile} objects used by the sound instances that belong to a given sprite identifier.
* @function
* @param {string} spriteId - The identifier for the sprite.
* @param {boolean} [avoidCancelled=false] - If set to true, it will not return the {@link CB_AudioFile} objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling the {@link CB_AudioFileSprites#getAudioFileBySoundInstanceId} method internally.
* @returns {array} Returns an array of the {@link CB_AudioFile} objects used by the sound instances that belong to the given sprite identifier.
*/
CB_AudioFileSprites.prototype.getAudioFilesUsedBySpriteId = function(spriteId, avoidCancelled)
{
var soundInstances = this.getSoundInstancesIdBySpriteId(spriteId);
var audioFiles = [];
var y = 0;
var soundInstancesLength = soundInstances.length;
var currentObject = null;
for (var x = 0; x < soundInstancesLength; x++)
{
currentObject = this.getAudioFileBySoundInstanceId(soundInstances[x], avoidCancelled);
if (currentObject !== null) { audioFiles[y++] = currentObject; }
}
return audioFiles;
}
/**
* Object returned by the {@link 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).
* @memberof CB_AudioFileSprites
* @typedef {Object} CB_AudioFileSprites.getAudioFilesUsed_OBJECT
* @property {CB_AudioFile} spriteId - 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 {@link CB_AudioFile} objects used.
*/
/**
* Returns the {@link CB_AudioFile} objects used by all the sounds instances currently created.
* @function
* @param {boolean} [oneDimension=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 {@link CB_AudioFile} objects used. Otherwise, if set to true, it will return a numeric array with the {@link CB_AudioFile} objects used (if the "includeWithoutSpriteAssociated" parameter is set to true, it will also contain the {@link CB_AudioFile} objects whose sound instance ID is not associated to any sprite).
* @param {boolean} [includeWithoutSpriteAssociated=false] - If set to true, it will also return the {@link CB_AudioFile} objects whose sound instance ID is not associated to any sprite. Used as the "includeWithoutSpriteAssociated" parameter when calling the {@link CB_AudioFileSprites#getSprites} method internally.
* @param {boolean} [avoidCancelled=false] - If set to true, it will not return the {@link CB_AudioFile} objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling the {@link CB_AudioFileSprites#getAudioFilesUsedBySpriteId} method internally.
* @returns {CB_AudioFileSprites.getAudioFilesUsed_OBJECT|array} Returns the {@link CB_AudioFile} objects used by all the sounds instances currently created. If the "oneDimension" parameter is set to false, it will return a {@link CB_AudioFileSprites.getAudioFilesUsed_OBJECT} object whose property names are the sprite identifiers (including the "_WITHOUT_SPRITE_ASSOCIATED" property for sound instances without a sprite associated, if the "includeWithoutSpriteAssociated" is set to true) and their value will be a numeric array with the {@link CB_AudioFile} objects used. Otherwise, if the "oneDimension" parameter set to true, it will return a numeric array with the {@link CB_AudioFile} objects used (if the "includeWithoutSpriteAssociated" parameter is set to true, it will also contain the {@link CB_AudioFile} objects whose sound instance ID is not associated to any sprite).
*/
CB_AudioFileSprites.prototype.getAudioFilesUsed = function(oneDimension, includeWithoutSpriteAssociated, avoidCancelled)
{
var audioFiles;
var sprites = this.getSprites(includeWithoutSpriteAssociated);
if (!oneDimension)
{
audioFiles = {};
for (var spriteId in sprites)
{
audioFiles[spriteId] = this.getAudioFilesUsedBySpriteId(spriteId, avoidCancelled);
}
}
else
{
audioFiles = [];
var audioFilesSprite;
var audioFilesSpriteLength;
var y = 0;
var x = 0;
for (var spriteId in sprites)
{
audioFilesSprite = this.getAudioFilesUsedBySpriteId(spriteId, avoidCancelled);
audioFilesSpriteLength = audioFilesSprite.length;
for (x = 0; x < audioFilesSpriteLength; x++)
{
audioFiles[y++] = audioFilesSprite[x];
}
}
}
return audioFiles;
}
/**
* Alias for {@link CB_AudioFileSprites#executeFunctionAllSprite}.
* @function CB_AudioFileSprites#executeAllSprite
* @see {@link CB_AudioFileSprites#executeFunctionAllSprite}
*/
/**
* Alias for {@link CB_AudioFileSprites#executeFunctionAllSprite}.
* @function CB_AudioFileSprites#forEachSpriteById
* @see {@link CB_AudioFileSprites#executeFunctionAllSprite}
*/
/**
* Executes a desired function for all the {@link CB_AudioFile} objects used by the sound instances currently created that belong to a given sprite (by its ID). It calls the {@link CB_AudioFileSprites#executeFunctionAll} method internally and returns its returning value.
* @function
* @param {string} spriteId - The identifier for the sprite.
* @param {CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK} functionEach - Used as the "functionEach" parameter when calling the {@link CB_AudioFileSprites#executeFunctionAll} method internally.
* @param {number|CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK} [delayBetweenEach=0] - Used as the "delayBetweenEach" parameter when calling the {@link CB_AudioFileSprites#executeFunctionAll} method internally.
* @param {boolean} [avoidCancelled=false] - If set to true, it will not affect the {@link CB_AudioFile} objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling the {@link CB_AudioFileSprites#getAudioFilesUsedBySpriteId} method internally.
* @param {boolean} [returnSetTimeoutsArray=false] - Used as the "returnSetTimeoutsArray" parameter when calling the {@link CB_AudioFileSprites#executeFunctionAll} method internally.
* @param {boolean} [delayBetweenEachAffectsFirst=false] - Used as the "delayBetweenEachAffectsFirst" parameter when calling the {@link CB_AudioFileSprites#executeFunctionAll} method internally.
* @param {CB_Arrays.executeFunctionAll_ON_FINISH_CALLBACK} [functionFinish] - 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 {integer|array} 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 {@link CB_AudioFile} objects used by the sound instances that belong to the given sprite identifier). Otherwise, if the "returnSetTimeoutsArray" is set to true, it will return a numeric array with a {@link CB_AudioFileCache.executeFunctionAll_OBJECT} object for each {@link 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]{@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout} function.
*/
CB_AudioFileSprites.prototype.executeFunctionAllSprite = CB_AudioFileSprites.prototype.executeAllSprite = CB_AudioFileSprites.prototype.forEachSpriteById = function(spriteId, functionEach, delayBetweenEach, avoidCancelled, returnSetTimeoutsArray, delayBetweenEachAffectsFirst, finishFunction)
{
return this.executeFunctionAll(functionEach, delayBetweenEach, this.getAudioFilesUsedBySpriteId(spriteId, avoidCancelled), returnSetTimeoutsArray, delayBetweenEachAffectsFirst, finishFunction);
}
/**
* Alias for {@link CB_AudioFileSprites#executeFunctionAllSprites}.
* @function CB_AudioFileSprites#executeAllSprites
* @see {@link CB_AudioFileSprites#executeFunctionAllSprites}
*/
/**
* Alias for {@link CB_AudioFileSprites#executeFunctionAllSprites}.
* @function CB_AudioFileSprites#forEachSprite
* @see {@link CB_AudioFileSprites#executeFunctionAllSprites}
*/
/**
* Executes a desired function for all the {@link CB_AudioFile} objects used by all the sound instances currently created. It calls the {@link CB_AudioFileSprites#executeFunctionAll} method internally and returns its returning value.
* @function
* @param {CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK} functionEach - Used as the "functionEach" parameter when calling the {@link CB_AudioFileSprites#executeFunctionAll} method internally.
* @param {number|CB_Arrays.executeFunctionAll_ON_LOOP_CALLBACK} [delayBetweenEach=0] - Used as the "delayBetweenEach" parameter when calling the {@link CB_AudioFileSprites#executeFunctionAll} method internally.
* @param {boolean} [includeWithoutSpriteAssociated=false] - If set to true, it will also affect the {@link CB_AudioFile} objects whose sound instance ID is not associated to any sprite. Used as the "includeWithoutSpriteAssociated" parameter when calling the {@link CB_AudioFileSprites#getAudioFilesUsed} method internally.
* @param {boolean} [avoidCancelled=false] - If set to true, it will not affect the {@link CB_AudioFile} objects whose sound instance has been cancelled. Used as the "avoidCancelled" parameter when calling the {@link CB_AudioFileSprites#getAudioFilesUsed} method internally.
* @param {boolean} [returnSetTimeoutsArray=false] - Used as the "returnSetTimeoutsArray" parameter whe