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

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

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

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