The client implements a JavaScript interface allowing web applications to speak text, play sounds, change playback properties, queue commands, manage independent audio channels, and cache results for low-latency playback.
The client consists of a set of named channels that maintain independent queues of commands. A channel processes its queue sequentially in first in, first out order, though some commands are processed immediately (e.g., stop). Multiple channels can process commands at the same time, however. For example, the default channel might have one speech utterance queued while it is speaking another. At the same time, the secondary channel might process a volume change command followed by a command to play a sound.
Channels send notifications of important events as they occur in two manners. First, channels invoke callback functions registered by an application for one or more kinds of notifications. Second, the channels return deferred results for each command before and after it is processed. The former technique is useful for listeners that need information across many commands. The latter is useful when an application wants information about particular commands.
Initializes the client API.
| Parameters: | args (object) – Object with the following properties: cacheSize (optional)
defaultCaching (optional)
jsonicURI (optional)
|
|---|
Changed in version 0.5: Added cacheSize parameter.
The JSonic class implements the entire client API. Only one instance is allowed per page and should be constructed using the initJSonic factory function.
True if caching is enabled by default for all to say and play calls. False if caching is disabled by default.
Changed in version 0.4.
Read-only. The root of the JSonic REST API.
Adds a listener for notifications.
| Parameters: |
|
|---|---|
| Returns: | Token to use to unregister the callback later using removeObserver |
| Return type: | object |
Gets the version number of the client API implemented by this instance.
| Return type: | string |
|---|
Gets the names of the text to speech engines installed on the server.
| Returns: | A deferred callback with an object matching the /engine schema or an errback with an Error object |
|---|---|
| Return type: | dojo.Deferred |
Gets detailed information about a particular text to speech engine.
| Parameters: | id (string) – Identifier associated with the engine as returned by getEngines. |
|---|---|
| Returns: | A deferred callback with an object matching the /engine/[id] schema or an errback with an Error object |
| Return type: | dojo.Deferred |
Gets the current value of one of the supported audio properties, immediately and at the time this command is processed in the queue.
| Parameters: | args (object) – Object with the following properties:
|
|---|---|
| Returns: | A deferred callback with the property value at the time this command is received (before) and when the command is processed in the queue (after) |
| Return type: | JSonicDeferred |
Gets the version number of the server API currently in use by this instance.
| Returns: | A deferred callback with an object matching the /version schema or an errback with an Error object |
|---|---|
| Return type: | dojo.Deferred |
Immediately pauses all output and commands on a channel. Fails when the channel is already paused.
| Parameters: | args (object) – Object with the following properties:
|
|---|---|
| Returns: | A deferred callback with a invoked with no parameters when the pause command is processed (before) and invoked with a complete flag when the pause is processed successfully (true) or not (false) |
| Return type: | JSonicDeferred |
New in version 0.5.
Immediately pauses all output and commands on all channels.
| Returns: | An array of deferred callbacks with no parameters invoked before the pause is processed (before) and after the pause is processed (after) |
|---|---|
| Return type: | array of JSonicDeferred |
New in version 0.5.
Plays a sound.
| Parameters: | args (object) – Object with the following properties:
|
|---|---|
| Returns: | A deferred callback with a invoked with no parameters when the play command is processed (before) and invoked with a completion flag (after) when the sound finishes playing (true) or is interrupted (false) |
| Return type: | JSonicDeferred |
Removes a listener for speech and sound notifications.
| Parameters: | token (object) – Token returned when registering the observer with addObserver |
|---|---|
| Return type: | undefined |
Resets all channel audio properties to their defaults.
| Parameters: | args (object) – Object with the following properties:
|
|---|---|
| Return type: | JSonicDeferred |
Resets all channel audio properties of all channels to their defaults.
| Return type: | array of JSonicDeferred |
|---|
New in version 0.4.
Speaks an utterance.
| Parameters: | args (object) – Object with the following properties:
|
|---|---|
| Returns: | A deferred callback with a invoked with no parameters when the say command is processed (before) and invoked with a completion flag (after) when the utterance finishes playing (true) or is interrupted (false) |
| Return type: | JSonicDeferred |
Sets the current value of one of the supported audio properties either immediately or when the command is processed in the queue.
| Parameters: | args (object) – Object with the following properties:
|
|---|---|
| Returns: | A deferred callback with the value of the property before it is processed (before) and the value of the property after the change is made (after) |
| Return type: | JSonicDeferred |
Immediately stops all output from a channel and clears all queued commands for that channel.
| Parameters: | args (object) – Object with the following properties:
|
|---|---|
| Returns: | A deferred callback with no parameters invoked before the stop is processed (before) and after the stop is processed (after) |
| Return type: | JSonicDeferred |
Immediately stops all output on all channels and clear all queued commands on all channels.
| Returns: | An array of deferred callbacks with no parameters invoked before the stop is processed (before) and after the stop is processed (after) |
|---|---|
| Return type: | array of JSonicDeferred |
New in version 0.5.
Immediately synthesizes an utterance on the server and caches its URL for later playback. The utterance adopts the properties of the channel as if it was queued behind all other commands on the channel. The synthesis startsimmediately and does not block the next command queued on the channel. The resulting speech is not queued on the channel but is always cached.
| Parameters: | args (object) – Object with the following properties:
|
|---|---|
| Returns: | A deferred callback with a invoked with no parameters when the synth command is processed (before) and when it completes (after) |
| Return type: | JSonicDeferred |
New in version 0.5.
Immediately unpauses all output and commands on a channel. Fails when the channel is not paused.
| Parameters: | args (object) – Object with the following properties:
|
|---|---|
| Returns: | A deferred callback with a invoked with no parameters when the unpause command is processed (before) and invoked with a completion flag when the unpause is processed successfully (true) or not (false) |
| Return type: | JSonicDeferred |
New in version 0.5.
Immediately unpauses all output and commands on all channels.
| Returns: | An array of deferred callbacks with no parameters invoked before the unpause is processed (before) and after the unpause is processed (after) |
|---|---|
| Return type: | array of JSonicDeferred |
New in version 0.5.
Queues silence on a channel.
| Parameters: | args (object) – Object with the following properties:
|
|---|---|
| Returns: | A deferred callback invoked with no parameters when the wait command is processed (before) and invoked with a completion flag (after) when the wait duration elapses (true) or is interrupted (false) |
| Return type: | JSonicDeferred |
New in version 0.5.
The JSonicDeferred class wraps two dojo.Deferred instances. A channel invokes the callback or errback method on the before deferred before a command is processed in the channel queue. A channel invokes the callback or errback method on the after deferred after the channel has finished processing the command.
Adds a function to be called once after a command is processed successfully.
| Parameters: | func (function(notice)) – Callback function |
|---|---|
| Returns: | This instance for call chaining |
| Return type: | JSonicDeferred |
Adds a function to be called once before a command is processed successfully.
| Parameters: | func (function(notice)) – Callback function |
|---|---|
| Returns: | This instance for call chaining |
| Return type: | JSonicDeferred |
Adds a function to be called once after a command is processed successfully or if an error occurs.
| Parameters: | func (function(noticeOrError)) – Callback function |
|---|---|
| Returns: | This instance for call chaining |
| Return type: | JSonicDeferred |
Adds a function to be called once before a command is processed successfully or if an error occurs.
| Parameters: | func (function(noticeOrError)) – Callback function |
|---|---|
| Returns: | This instance for call chaining |
| Return type: | JSonicDeferred |
Adds a function to be called once after a command is processed but an error occurs.
| Parameters: | func (function(error)) – Callback function |
|---|---|
| Returns: | This instance for call chaining |
| Return type: | JSonicDeferred |
Adds a function to be called once before a command is processed but an error occurs.
| Parameters: | func (function(error)) – Callback function |
|---|---|
| Returns: | This instance for call chaining |
| Return type: | JSonicDeferred |
The type of a channel notification is determined by the value of its action property. The following notifications are supported, listed by their actions.
Occurs when a channel starts processing a JSonic.say command (i.e., when it starts synthesizing the utterance).
| Param channel: | Name of the channel |
|---|---|
| Type channel: | string |
| Param url: | URL of the synthesized speech file |
| Type url: | string |
| Param name: | Application name assigned to the utterance |
| Type name: | string |
Occurs when a channel finishes processing a JSonic.say command (i.e., when it finishes speaking the utterance).
| Param channel: | Name of the channel |
|---|---|
| Type channel: | string |
| Param url: | URL of the synthesized speech file |
| Type url: | string |
| Param name: | Application name assigned to the utterance |
| Type name: | string |
| Param completed: | |
| True if the speech finished in its entirety, false if it was interrupted before it could finish | |
| Type completed: | boolean |
Occurs when a channel starts processing a JSonic.play command (i.e., when it starts streaming the sound).
| Param channel: | Name of the channel |
|---|---|
| Type channel: | string |
| Param url: | URL of the sound file |
| Type url: | string |
| Param name: | Application name assigned to the sound |
| Type name: | string |
Occurs when a channel finishes processing a JSonic.play command (i.e., when it finishes playing the sound).
| Param channel: | Name of the channel |
|---|---|
| Type channel: | string |
| Param url: | URL of the sound file |
| Type url: | string |
| Param name: | Application name assigned to the sound |
| Type name: | string |
| Param completed: | |
| True if the sound finished in its entirety, false if it was interrupted before it could finish | |
| Type completed: | boolean |
Occurs when a channel starts processing a JSonic.wait command.
| Param channel: | Name of the channel |
|---|---|
| Type channel: | string |
| Param name: | Application name assigned to the sound |
| Type name: | string |
New in version 0.5.
Occurs when a channel finishes processing a JSonic.wait command (i.e., when the wait duration elapses).
| Param channel: | Name of the channel |
|---|---|
| Type channel: | string |
| Param name: | Application name assigned to the sound |
| Type name: | string |
| Param completed: | |
| True if the wait finished in its entirety, false if it was interrupted before it could finish | |
| Type completed: | boolean |
New in version 0.5.
Occurs when a channel encounters an error processing a command.
| Param channel: | Name of the channel |
|---|---|
| Type channel: | string |
| Param name: | Application name assigned to the command that caused the error |
| Type name: | string |
| Param description: | |
| English description of the problem that occurred | |
| Type description: | |
| string | |
The following examples assume an uow.audio.JSonic instance with caching disabled by default exists in local variable js. The following code creates such an instance.
var js = uow.audio.JSonic();
To say an utterance on the default channel and not cache the result, do the following:
js.say({text : "This is some text to speak."});
To say an utterance on the same channel and cache the result for lower latency, do the following:
js.say({text : "This is some text to speak.", cache : true});
To queue two sequential utterances on the default channel, do the following:
js.say({text : "This is some text to speak."});
js.say({text : "I wait my turn."});
To say two utterances simultaneously, one of the default channel and the other on the custom channel, do the following:
js.say({text : "This is some text to speak."});
js.say({text : "Ha! I like to interrupt.", channel : 'custom'});
To play a sound, letting JSonic choose the proper format (OGG or MP3) based on the browser capabilities, do the following:
js.play({url : 'http://somewhere.com/sounds/sound_effect'});
where a file named sound_effect.mp3 and/or sound_effect.ogg exists at the given URL.
To cease output on the default channel and clear its queued commands, do the following:
js.stop()
To query the espeak engine for its available voices, do the following:
js.getEngineInfo('espeak').addAfter(function(response) {
var voices = response.voices.values;
});
To set an Italian voice for all following speech commands on the default channel, do the following:
js.setProperty({name : 'voice', value : 'it'});
To query the espeak engine for its range of speech rates, do the following:
js.getEngineInfo('espeak').addCallback(function(response) {
var min = response.rate.minimum;
var max = response.rate.maximum;
});
To set the rate for all following speech commands on the default channel, do the following:
js.setProperty({name : 'rate', value : 250});
To set the volume for all following audio output on the default channel, do the following:
js.setProperty({name : 'volume', value : 0.5});
To set the volume for the current audio output and all following commands on the custom channel, do the following:
js.setProperty({name : 'volume', value : 0.25, immediate : true});
Say you have a JSonic event callback named onEvent implemented as follows:
function onEvent(event) {
console.log(event);
}
To register the callback for all events on the default channel, do the following:
var tok1 = js.addObserver(onEvent);
To register the callback only for sound start and error events on the custom channel, do the following:
var tok2 = js.addObserver(onEvent, 'custom', ['start-play', 'error']);
To unregister the callback on the default channel only, do the following:
js.removeObserver(tok1);
Say you have the onEvent function described above. You want it to execute in response to certain commands without monitoring all commands.
To execute the callback as the default channel finishes speaking an utterance completely, do the following:
js.say({text : 'I am a banana.'}).addAfter(onEvent);
To execute the callback as the default channel starts speaking an utterance and either finishes speaking or encounters an error speaking, do the following:
js.say({text : 'I am a banana.'}).callBefore(onEvent).anyAfter(onEvent);
To execute the callback with the voice configured on the default channel immediately and when the command is processed by the channel, do the following:
js.getProperty({name : 'voice'}).callBefore(onEvent).addAfter(onEvent);