Namespace mmir.MediaManager

Defined in: mediaManager.js.

Namespace Summary
Constructor Attributes	Constructor Name and Description
	mmir.MediaManager The MediaManager gives access to audio in- and output functionality.

Field Summary
Field Attributes	Field Name and Description
	_log A logger for the MediaManager and its plugins/modules.
	ctx Execution context for plugins TODO add doc
	waitReadyImpl Wait indicator, e.g.

Method Summary
Method Attributes	Method Name and Description
<private>	_addListenerObserver(eventName, observerCallback) Add an observer for registration / removal of event-handler.
<private>	_fireEvent(eventName, argsArray) Helper for firing / triggering an event.
<private>	_notifyObservers(eventName, actionType, eventHandler) Helper for notifying listener-observers about changes (adding/removing listeners).
<private>	_preparing(moduleName) This function is called by media plugin implementations (i.e.
<private>	_ready(moduleName) This function is called by media plugin implementations (i.e.
	addListener(eventName, eventHandler) Adds the handler-function for the event.
	cancelRecognition(successCallBack, failureCallBack) Cancel currently active speech recognition.
	cancelSpeech(successCallBack, failureCallBack) Cancel current synthesis.
	createEmptyAudio() Get an empty audio object.
	getFunc(ctx, funcName) Returns function `funcName` from "sub-module" `ctx`.
	getListeners(eventName) Get list of registered listeners / handlers for an event.
<private>	getPluginsToLoad(configurationName) HELPER for init-function: determines, which plugins (i.e.
	getURLAsAudio(url, onPlayedCallback, failureCallBack, onLoadedCallBack) Get an audio object for the audio file specified by URL.
	hasListeners(eventName) Check if at least one listener / handler is registered for the event.
<private>	loadAllPlugins(pluginArray, successCallback, failureCallback)
	MediaManager#getInstance() Same as #init.
	MediaManager#init(successCallback, failureCallback, listenerList) Object containing the instance of the class {{#crossLink "audioInput"}}{{/crossLink}} If listenerList is provided, each listener will be registered after the instance is initialized, but before media-plugins (i.e.
	MediaManager#loadFile(filePath, successCallback, failureCallback, execId) loads a file.
	off()
	on()
	perform(ctx, funcName, args) Executes function `funcName` in "sub-module" `ctx` with arguments `args`.
	playURL(url, onPlayedCallback, failureCallBack) Play audio file from the specified URL.
	playWAV(blob, onPlayedCallback, failureCallBack) Play PCM audio data.
	recognize(successCallBack, failureCallBack) Start speech recognition with end-of-speech detection: the recognizer automatically tries to detect when speech has finished and then triggers the callback with the result.
	removeListener(eventName, eventHandler) Removes the handler-function for the event.
	setDefaultCtx(ctxId) Set the default execution context.
	setTextToSpeechVolume(newValue) Set the volume for the speech synthesis (text-to-speech).
	startRecord(successCallBack, failureCallBack, isWithIntermediateResults) Start continuous speech recognition: The recognizer continues until #stopRecord is called.
	stopRecord(successCallBack, failureCallBack) Stops continuous speech recognition: After #startRecord was called, invoking this function will stop the recognition process and return the result by invoking the `succesCallback`.
	textToSpeech(parameter, onPlayedCallback, failureCallBack) Synthesizes ("read out loud") text.

Namespace Detail

mmir.MediaManager

The MediaManager gives access to audio in- and output functionality. Depending on its configuration, the MediaManager loads different implementation modules (plugins) that realize the interface-functions differently. See directory mmirf/env/media for available plugins. This "class" is a singleton - so that only one instance is in use.

Requires:: jQuery.extend; jQuery.Deferred TODO remove / change dependency on forBrowser: constants.isBrowserEnv()!!!

Field Detail

{mmir.Logger} _log

A logger for the MediaManager and its plugins/modules.

This logger MAY be used by media-plugins and / or tools and helpers related to the MediaManager.

This logger SHOULD NOT be used by "code" that non-related to the MediaManager

Default Value:: mmir.Logger (logger instance for mmir.MediaManager)

{mmir.Logger} ctx

Execution context for plugins TODO add doc

Default Value:: Object (empty context, i.e. plugins are loaded into the "root context", and no plugins loaded into the execution context)

{mmir.env.media.IWaitReadyIndicator} waitReadyImpl

Wait indicator, e.g. for speech input:

provides 2 functions:
preparing(): if called, the implementation indicates that the "user should wait"
ready(): if called, the implementation stops indicating that the "user should wait" (i.e. that the system is ready for user input now)

If not set (or functions are not available) will do nothing

//define custom wait/ready implementation:
var impl = {
	preparing: function(str){
		console.log('Media module '+str+' is preparing...');
	},
	ready: function(str){
		console.log('Media module '+str+' is ready now!');
	}
};

//configure MediaManager to use custom implementation:
mmir.MediaManager.waitReadyImpl = impl;

//-> now plugins that call  mmir.MediaManager._preparing() and  mmir.MediaManager._ready()
//   will invoke the custom implementation's functions.

See:: #_preparing; #_ready

Default Value:: Object (no implementation set)

Method Detail

<private> _addListenerObserver(eventName, observerCallback)

Add an observer for registration / removal of event-handler. The observer gets notified,when handlers are registered / removed for the event. The observer-callback function will be called with the following arguments (eventName, ACTION_TYPE, eventHandler) where

eventName: String the name of the event that should be observed
ACTION_TYPE: the type of action: "added" if the handler was registered for the event, "removed" if the the handler was removed
eventHandler: the handler function that was registered or removed

Parameters:
{String} eventName
{Function} observerCallback

<private> _fireEvent(eventName, argsArray)

Helper for firing / triggering an event. This should only be used by media plugins (that handle the eventName).

Parameters:
{String} eventName
{Array} argsArray: the list of arguments with which the event-handlers will be called.

<private> _notifyObservers(eventName, actionType, eventHandler)

Helper for notifying listener-observers about changes (adding/removing listeners). This should only be used by media plugins (that handle the eventName).

Parameters:
{String} eventName
{String} actionType: the change-type that occurred for the event/event-handler: one of ["added" | "removed"].
{Function} eventHandler: the event-handler function that has changed.

<private> _preparing(moduleName)

This function is called by media plugin implementations (i.e. modules) to indicate that they are preparing something and that the user should wait.

The actual implementation for _preparing(String) is given by #waitReadyImpl.preparing (if not set, then calling _preparing(String) will have no effect.

Parameters:
{String} moduleName: the module name from which the function was invoked

See:: #waitReadyImpl; #_ready

<private> _ready(moduleName)

This function is called by media plugin implementations (i.e. modules) to indicate that they are now ready and that the user can start interacting.

The actual implementation for _ready(String) is given by the #waitReadyImpl implementation (if not set, then calling _ready(String) will have no effect.

Parameters:
{String} moduleName: the module name from which the function was invoked

See:: #waitReadyImpl; #_ready

addListener(eventName, eventHandler)

Adds the handler-function for the event. This function calls #_notifyObservers for the eventName with actionType "added". Event names (and firing events) are specific to the loaded media plugins. TODO list events that the default media-plugins support * "miclevelchanged": fired by AudioInput plugins that support querying the microphone (audio input) levels A plugin can tigger / fire events using the helper #_fireEvent of the MediaManager. Media plugins may observe registration / removal of listeners via #_addListenerObserver and #_removeListenerObserver. Or get and iterate over listeners via #getListeners.

Parameters:
{String} eventName
{Function} eventHandler

cancelRecognition(successCallBack, failureCallBack)

Cancel currently active speech recognition. Has no effect, if no recognition is active.

Parameters:
successCallBack
failureCallBack

cancelSpeech(successCallBack, failureCallBack)

Cancel current synthesis.

Parameters:
successCallBack
failureCallBack

{mmir.env.media.IAudio} createEmptyAudio()

Get an empty audio object. This can be used as dummy or placeholder for a "real" audio object. The audio object exports the following functions:

play()
stop()
release()
enable()
disable()
setVolume(number)
getDuration()
isPaused()
isEnabled()

Note: enable() and disable() will set the internal enabled-state, which can be queried via isEnabled(). play() and stop() will set the internal playing-state, which can be queried via isPaused() (note however, that this empty audio does not actually play anything. setVolume() sets the internal volume-value. getDuration() will always return 0.

Returns:: {mmir.env.media.IAudio} the audio

See:

getFunc(ctx, funcName)

Returns function funcName from "sub-module" ctx.

If there is no funcName in "sub-module" ctx, then funcName from the "main-module" (i.e. from the MediaManager instance itself) will be returned.

NOTE that the returned functions will always execute within the context of the MediaManager instance (i.e. this will refer to the MediaManager instance).

 //same as mmir.MediaManager.ctx.android.textToSpeech("...", function...):
	mmir.MediaManager.getFunc("android", "textToSpeech")("some text to read out loud",
		function onFinished(){ console.log("finished reading."); }
	);

 //same as mmir.MediaManager.textToSpeech("...", function...):
 //... IF the defaultExecId is falsy 
 //    (i.e. un-changed or set to falsy value via setDefaultExec())
	mmir.MediaManager.getFunc(null, "textToSpeech")("some text to read out loud",
		function onFinished(){ console.log("finished reading."); }
	);

Parameters:
{String} ctx: the execution context, i.e. "sub-module", in which to execute funcName.
If falsy, the "root-module" will used as execution context.
{String} funcName: the function name

Throws:
{ReferenceError}: if funcName does not exist in the requested Execution context.
Or if ctx is not falsy but there is no valid execution context ctx in MediaManager.

{Array} getListeners(eventName)

Get list of registered listeners / handlers for an event.

Parameters:
eventName

Returns:: {Array} of event-handlers. Empty, if there are no event handlers for eventName

<private> {Array} getPluginsToLoad(configurationName)

HELPER for init-function: determines, which plugins (i.e. files) should be loaded.

has 2 default configuarions:
if isCordovaEnvironment TRUE: use 'cordova' config
if FALSEy: use 'browser' config

OR
loads the list for the current environment (cordova or browser) that is set in configuration.json via

"mediaManager": {
		"cordova": [...],
		"browser": [...]
}

Each entry may either be a String (file name of the plugin) or an Object with properties

	mod:  //String
	ctx:      //String

If String: the functions of the loaded plugin will be attached to the MediaManager instance: mmir.MediaManager.thefunction()
If {mod: plugin,ctx: theContextId}: the functions of the loaded plugin will be attached to the "sub-module" to the MediaManager instance (NOTE the execution context of the function will remain within the MediaManager instance, i.e. this will still refer to the MediaManager instance): mmir.MediaManager.theId.thefunction()

If plugins are loaded with an ID, you can use mmir.MediaManager.getFunc(ctxId, func)(the, arguments) or mmir.MediaManager.perform(ctxId, func, [the, arguments]): If the "sub-module" ctxId does not have the function func (i.e. no MediaManager.ctx.ctxId.func exists), then the default function in MediaManager will be executed (i.e. MediaManager.func(the, arguments) ).

Parameters:
configurationName

Returns:: {Array} the list of plugins which should be loaded

{mmir.env.media.IAudio} getURLAsAudio(url, onPlayedCallback, failureCallBack, onLoadedCallBack)

Get an audio object for the audio file specified by URL. The audio object exports the following functions:

play()
stop()
release()
enable()
disable()
setVolume(number)
getDuration()
isPaused()
isEnabled()

NOTE: the audio object should only be used, after the onLoadedCallback was triggered.

Parameters:
{String} url
{Function} onPlayedCallback Optional: OPTIONAL
{Function} failureCallBack Optional: OPTIONAL
{Function} onLoadedCallBack Optional: OPTIONAL

Returns:: {mmir.env.media.IAudio} the audio

See:

{Boolean} hasListeners(eventName)

Check if at least one listener / handler is registered for the event.

Parameters:
eventName

Returns:: {Boolean} true if at least 1 handler is registered for eventName; otherwise false.

<private> loadAllPlugins(pluginArray, successCallback, failureCallback)

Parameters:
pluginArray
successCallback
failureCallback

MediaManager#getInstance()

Same as #init.

Deprecated:
access MediaManger directly via mmir.MediaManager.someFunction - &tl;internal: for initialization use init() instead>

{Object} MediaManager#init(successCallback, failureCallback, listenerList)

Object containing the instance of the class {{#crossLink "audioInput"}}{{/crossLink}} If listenerList is provided, each listener will be registered after the instance is initialized, but before media-plugins (i.e. environment specfific implementations) are loaded. Each entry in the listenerList must have fields name (String) and listener (Function), where
name: is the name of the event
listener: is the listener implementation (the signature/arguments of the listener function depends on the specific event for which the listener will be registered)

Parameters:
{Function} successCallback Optional: OPTIONAL callback that gets triggered after the MediaManager instance has been initialized.
{Function} failureCallback Optional: OPTIONAL a failure callback that gets triggered if an error occurs during initialization.
{Array: OPTIONAL a list of listeners that should be registered, where each entry is an Object with properties:
{ name: String the event name, listener: Function the handler function }

Classes

Namespace mmir.MediaManager