io.spokestack.spokestack

Class Spokestack

java.lang.Object

io.spokestack.spokestack.SpokestackAdapter

io.spokestack.spokestack.Spokestack

All Implemented Interfaces:

DialogueListener, OnSpeechEventListener, TTSListener, Callback<NLUResult>, TraceListener, AutoCloseable

public final class Spokestack
extends SpokestackAdapter
implements AutoCloseable

This class combines all Spokestack modules into a single component to provide a unified interface to the library's ASR, NLU, and TTS features. Like the individual modules, it is configurable using a fluent builder pattern, but it provides a default configuration; only a few parameters are required from the calling application, and those only for specific features noted in the documentation for the builder's methods.

Client applications may wish to establish event listeners for purposes such as forwarding trace events to a logging framework, but events necessary to complete user interactions (for example, sending ASR transcripts through NLU) are handled entirely by this class. This includes internal management of TTS playback, which requires the client application to declare additional media player dependencies; see the documentation for more details. This feature can be disabled via the builder if desired.

The default configuration of this class assumes that the client application wants to use all of Spokestack's features, regardless of their implied dependencies or required configuration, so an error will be thrown if any prerequisite is missing at build time. Individual features can be disabled via the builder.

Convenience methods are provided to interact with the most important features of individual modules, but they do not completely duplicate the modules' public APIs. Each module in use can be retrieved via its own getter, enabling use of its full API.

Any convenience methods called on a module that has been explicitly disabled will result in a NullPointerException.

This class is not threadsafe; public methods used to interact with Spokestack modules should be called from the same thread. The modules themselves use background threads where appropriate to perform intensive tasks.

See Also:

SpeechPipeline, TensorflowNLU, TTSManager

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Spokestack.Builder Fluent builder interface for configuring Spokestack.

Method Summary

Modifier and Type	Method and Description
void	activate() Manually activate the speech pipeline, forcing the current ASR class to begin recognizing speech.
void	addListener(SpokestackAdapter listener) Add a new listener to receive events from Spokestack modules.
AsyncResult<NLUResult>	classify(String utterance) Classify a user utterance, returning a wrapper that can either block until the classification is complete or call a registered callback when the result is ready.
void	close() Release internal resources held by all registered Spokestack modules.
void	deactivate() Manually deactivate the speech pipeline, forcing the current ASR class to stop recognizing speech.
void	eventReceived(TTSEvent event) Receive events from the TTS module.
FinalizedPrompt	finalizePrompt(Prompt prompt) Finalize a prompt, interpolating template strings using the current conversation data store.
DialogueManager	getDialogueManager()
NLUManager	getNlu()
SpeechPipeline	getSpeechPipeline()
TTSManager	getTts()
void	nluResult(NLUResult result) Called when an NLU classification result is available if this class is registered as a callback at classification time.
void	onEvent(SpeechContext.Event event, SpeechContext context) Receive events from the speech pipeline.
void	pause() Pauses the speech pipeline, suspending passive listening.
void	putConversationData(String key, Object value) Stores an object in the conversation data store for use in interpolating system prompts.
void	removeListener(SpokestackAdapter listener) Remove a Spokestack event listener, allowing it to be garbage collected.
void	resume() Resumes a paused speech pipeline, returning it to a passive listening state.
void	setAndroidContext(android.content.Context context) Update the Android application context used for on-device ASR and the TTS manager.
void	start() Prepares all registered Spokestack modules for use and starts the speech pipeline in passive listening mode.
void	stop() Stops the speech pipeline and releases internal resources held by all registered Spokestack modules.
void	stopPlayback() Stops playback of any playing or queued synthesis results.
void	synthesize(SynthesisRequest request) Synthesizes a piece of text or SSML, dispatching the result to any registered listeners.

Methods inherited from class io.spokestack.spokestack.SpokestackAdapter

call, error, onDialogueEvent, onError, onTrace, speechEvent, trace, ttsEvent

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setAndroidContext

public void setAndroidContext(android.content.Context context)

Update the Android application context used for on-device ASR and the TTS manager.

Parameters:

context - The new Android context.

getSpeechPipeline

public SpeechPipeline getSpeechPipeline()

Returns:

The speech pipeline currently in use.

start

public void start()
           throws Exception

Prepares all registered Spokestack modules for use and starts the speech pipeline in passive listening mode.

Throws:

Exception - if there is an error configuring or starting a module.

pause

public void pause()

Pauses the speech pipeline, suspending passive listening. This can be useful for scenarios where you expect false positives for the wakeword to be possible.

This method will implicitly deactivate the pipeline, canceling any in-flight ASR requests.

This method is called automatically when Spokestack is playing a TTS prompt if Spokestack is managing audio playback.

See Also:

SpeechPipeline.pause()

resume

public void resume()

Resumes a paused speech pipeline, returning it to a passive listening state.

This method is called automatically when Spokestack finishes playing a TTS prompt if Spokestack is managing audio playback.

See Also:

SpeechPipeline.resume()

stop

public void stop()

Stops the speech pipeline and releases internal resources held by all registered Spokestack modules.

In order to support restarting Spokestack (calling start() after this method), this method does not clear registered listeners. To do this, close then destroy the current Spokestack instance and build a new one.

activate

public void activate()

Manually activate the speech pipeline, forcing the current ASR class to begin recognizing speech. Useful when a wakeword is not employed, or in conjunction with a microphone button.

deactivate

public void deactivate()

Manually deactivate the speech pipeline, forcing the current ASR class to stop recognizing speech. Useful in conjunction with a hold-to-talk button.

Note: This method currently has no effect on the Android speech recognizer this class uses by default.

getNlu

public NLUManager getNlu()

Returns:

The NLU manager currently in use.

classify

public AsyncResult<NLUResult> classify(String utterance)

Classify a user utterance, returning a wrapper that can either block until the classification is complete or call a registered callback when the result is ready.

This convenience method automatically registers all SpokestackAdapters added to this class at build time to receive the classification result asynchronously.

Parameters:

utterance - The utterance to classify.

Returns:

An object representing the result of the asynchronous classification.

getTts

public TTSManager getTts()

Returns:

The TTS manager currently in use.

synthesize

public void synthesize(SynthesisRequest request)

Synthesizes a piece of text or SSML, dispatching the result to any registered listeners.

Parameters:

request - The synthesis request data.

stopPlayback

public void stopPlayback()

Stops playback of any playing or queued synthesis results.

getDialogueManager

public DialogueManager getDialogueManager()

Returns:

The dialogue manager currently in use.

finalizePrompt

public FinalizedPrompt finalizePrompt(Prompt prompt)

Finalize a prompt, interpolating template strings using the current conversation data store.

This method can only be used if a dialogue manager is active.

Parameters:

prompt - The prompt to be finalized.

Returns:

The finalized prompt.

See Also:

DialogueManager.finalizePrompt(Prompt), ConversationData

putConversationData

public void putConversationData(String key,
                                Object value)

Stores an object in the conversation data store for use in interpolating system prompts.

This method can only be used if a dialogue manager is active.

Parameters:

key - The name of the object to store.

value - The object to store.

See Also:

ConversationData.set(String, Object)

addListener

public void addListener(SpokestackAdapter listener)

Add a new listener to receive events from Spokestack modules.

Parameters:

listener - A listener that will receive events from all Spokestack modules.

removeListener

public void removeListener(SpokestackAdapter listener)

Remove a Spokestack event listener, allowing it to be garbage collected.

Parameters:

listener - The listener to be removed.

onEvent

public void onEvent(@NotNull
                    SpeechContext.Event event,
                    @NotNull
                    SpeechContext context)

Description copied from class: SpokestackAdapter

Receive events from the speech pipeline.

Clients should typically override SpokestackAdapter.speechEvent(SpeechContext.Event, SpeechContext) instead of this method.

Specified by:

onEvent in interface OnSpeechEventListener

Overrides:

onEvent in class SpokestackAdapter

Parameters:

event - The name of the event that was raised.

context - The current speech context.

nluResult

public void nluResult(@NotNull
                      NLUResult result)

Description copied from class: SpokestackAdapter

Called when an NLU classification result is available if this class is registered as a callback at classification time. Adapters added to a Spokestack class at build time are automatically registered for all classifications.

Overrides:

nluResult in class SpokestackAdapter

Parameters:

result - The NLU result.

See Also:

TensorflowNLU.classify(String), AsyncResult

eventReceived

public void eventReceived(@NotNull
                          TTSEvent event)

Description copied from class: SpokestackAdapter

Receive events from the TTS module.

Clients should typically override SpokestackAdapter.ttsEvent(TTSEvent) instead of this method.

Specified by:

eventReceived in interface TTSListener

Overrides:

eventReceived in class SpokestackAdapter

Parameters:

event - The event from the TTS module.

close

public void close()

Release internal resources held by all registered Spokestack modules.

In order to support restarting Spokestack (calling start() after this method), this method does not clear registered listeners. To do this, close then destroy the current Spokestack instance and build a new one.

Specified by:

close in interface AutoCloseable