Events¶

Use setHandler with keys in this section to register callback handlers for events. The values for these settings refer to runtime instances of code objects and are not serialized by save or dup.

The results and iterators available in these handlers vary by event. See the descriptions below for details on what these are.

^result is the most used event by a large margin.

^adapt-started¶

event handle write-only

C/C++Java

#define SNSR_ADAPT_STARTED_EVENT "^adapt-started"

public class Snsr {
  public final static String ADAPT_STARTED_EVENT = "^adapt-started";
}

Wake word model adaptation thread has started.

This handler is called from a thread started to do model adaptation in continuously adapting spotter models. The handle function should return OK to continue with model adaptation, or SKIP to abort adaptation and ignore this enrollment without raising an error.

The handler function's Session argument will be NULL as it is not safe to access this handle from the enrollment thread.

You can use this handler to adjust the adaptation thread priority, or delay the start of adaptation by blocking on a condition variable.

Note

Session teardown waits on joining the adaptation thread. Any handler function registered for this event must return before the associated Session is released.

sample-count

none

^adapted

^adapted¶

event handle write-only

C/C++Java

#define SNSR_ADAPTED_EVENT "^adapted"

public class Snsr {
  public final static String ADAPTED_EVENT = "^adapted";
}

Wake word adaptation complete event.

Adaptation is the estimation of spotter model parameters from a number of enrollments for one or more users.

Example

Add a handler for this event to save adapted enrollment contexts.

C/C++Java

snsrSave(session, SNSR_FM_RUNTIME, snsrStreamFromFileName("context.snsr", "w"));

session.save(Snsr.FM_RUNTIME, SnsrStream.fromFileName("context.snsr", "w"));

To load a previously saved enrollment context, do so after loading the model that created it.

sample-count, user, user-count

user-iterator

^enrolled, save, RUNTIME

^begin¶

event handle write-only

C/C++Java

#define SNSR_BEGIN_EVENT "^begin"

public class Snsr {
  public final static String BEGIN_EVENT = "^begin";
}

Begin point detected VAD event.

Raised when speech has been detected. Use begin-ms or begin-sample to retrieve the start point relative to the beginning of ->audio-pcm.

begin-ms, begin-sample, sample-count

none

backoff, end, limit, silence

^done¶

event handle write-only

C/C++Java

#define SNSR_DONE_EVENT "^done"

public class Snsr {
  public final static String DONE_EVENT = "^done";
}

Wake word adaptation complete event.

Handler called when adaptation has completed and the model-stream model is available.

This handler typically returns STOP to end processing.

model-stream, sample-count

none

^end¶

event handle write-only

C/C++Java

#define SNSR_END_EVENT "^end"

public class Snsr {
  public final static String END_EVENT = "^end";
}

Endpoint detected VAD event.

Raised trailing-silence ms after end-of-speech has been detected. Use end-ms or end-sample to retrieve the endpoint relative to the beginning of ->audio-pcm.

begin-ms, begin-sample, end-ms, end-sample, sample-count

none

begin, limit, silence, hold-over, trailing-silence

^enrolled¶

event handle write-only

C/C++Java

#define SNSR_ENROLLED_EVENT "^enrolled"

public class Snsr {
  public final static String ENROLLED_EVENT = "^enrolled";
}

Wake word enrollment complete event.

Handler called when enrollment is complete, just before model adaptation starts. Use this handler for the earliest possible access to the enrollment context.

Enrollment is the process of taking individual enrollments (audio files or live audio clips), validating them, and adding them to the model. These enrollments are used during the adaptation stage to estimate spotter model parameters.

Example

Add a handler for this event to save enrollment contexts before they are adapted.

C/C++Java

snsrSave(session, SNSR_FM_RUNTIME, snsrStreamFromFileName("enrollments.snsr", "w"));

session.save(Snsr.FM_RUNTIME, SnsrStream.fromFileName("enrollments.snsr", "w"));

sample-count

none

^adapted, ^done, save, RUNTIME

^fail¶

event handle write-only

C/C++Java

#define SNSR_FAIL_EVENT "^fail"

public class Snsr {
  public final static String FAIL_EVENT = "^fail";
}

Wake word enrollment failed event.

Handler called if an enrollment fails quality checks.

audio-stream, enrollment-id, reason, reason-guidance, reason-pass, reason-threshold, reason-value, sample-count

reason-iterator

^pass

^limit¶

event handle write-only

C/C++Java

#define SNSR_LIMIT_EVENT "^limit"

public class Snsr {
  public final static String LIMIT_EVENT = "^limit";
}

Maximum recording reached VAD event.

Raised when max-recording ms of speech has been processed by the VAD before a trailing-silence endpoint is found. Use end-ms or end-sample to retrieve the endpoint relative to the beginning of ->audio-pcm.

begin-ms, begin-sample, end-ms, end-sample, sample-count

none

^begin, ^end, ^silence, max-recording

^listen-begin¶

event handle write-only

C/C++Java

#define SNSR_LISTEN_BEGIN_EVENT "^listen-begin"

public class Snsr {
  public final static String LISTEN_BEGIN_EVENT = "^listen-begin";
}

Sequential task has started listening on second slot.

Raised in a sequential task when audio focus has shifted from the first slot to the second. This typically happens when the spotter n the first slot has detected the phrase.

This event is ignored for tasks that do not feature sequential behavior.

sample-count

none

^listen-end

^listen-end¶

event handle write-only

C/C++Java

#define SNSR_LISTEN_END_EVENT "^listen-end"

public class Snsr {
  public final static String LISTEN_END_EVENT = "^listen-end";
}

Sequential task has stopped listening on second slot.

Raised in a sequential task when audio focus has shifted from the second slot back to the first.

This event is ignored for tasks that do not feature sequential behavior.

sample-count

none

^listen-begin

^new-user¶

event handle write-only

C/C++Java

#define SNSR_NEW_USER_EVENT "^new-user"

public class Snsr {
  public final static String NEW_USER_EVENT = "^new-user";
}

New user detected event.

Handler called when a continuously adapting spotter model has adapted to a new user.

sample-count, user, user-count

user-iterator

^adapted, delete-user, rename-user, user

^next¶

event handle write-only

C/C++Java

#define SNSR_NEXT_EVENT "^next"

public class Snsr {
  public final static String NEXT_EVENT = "^next";
}

Next user event.

Handler called during interactive enrollment to prompt the end-user for a new enrollment phrase. This handler should set user to the tag associated with the new user. Leave user if there are no more users or phrases to enroll.

sample-count

none

user

^nlu-intent¶

event handle write-only tnl stt

C/C++Java

#define SNSR_NLU_INTENT_EVENT "^nlu-intent"

public class Snsr {
  public final static String NLU_INTENT_EVENT = "^nlu-intent";
}

NLU intent available.

This event is raised when a natural language parse result is available.

Each intent that matched input generates an ^nlu-intent event. Use nlu-entity-iterator in this callback handler to retrieve the names of entities found.

An intent is an action, such as turning on the windshield wipers, or setting a microwave clock.

Intents are exactly the same as the top-level NLU slots reported by ^nlu-slot. The entities available inside the handler for this event, however, are only one level deep. The SDK flattens nested nlu-slot-names by separating each level with a period.

For example: Grammar snippet { date { time {hours} {minutes} } } has intent date with entities time.hours and time.minutes, but slot date has a single child slot time, which in turn has two children, hours and minutes.

See the NLU section in the grammar syntax section for more detail on the {} NLU slot capturing operator.

nlu-intent-name, nlu-intent-score, nlu-intent-value, sample-count

nlu-entity-iterator

^nlu-slot, grammar syntax

^nlu-slot¶

event handle write-only tnl stt

C/C++Java

#define SNSR_NLU_SLOT_EVENT "^nlu-slot"

public class Snsr {
  public final static String NLU_SLOT_EVENT = "^nlu-slot";
}

NLU result available.

This event is raised when a lightweight natural language parse result is available. Each top-level slot that matched input generates a ^nlu-slot event. Use nlu-slot-iterator in this callback handler to retrieve child slot names and values.

See the NLU section in the grammar syntax section for more detail on the {} NLU slot capturing operator.

nlu-match-count, nlu-slot-count, nlu-slot-name, nlu-slot-score, nlu-slot-value, sample-count

nlu-slot-iterator

^nlu-intent, grammar syntax

^pass¶

event handle write-only

C/C++Java

#define SNSR_PASS_EVENT "^pass"

public class Snsr {
  public final static String PASS_EVENT = "^pass";
}

Wake word enrollment succeeded event.

Handler called when an enrollment passes quality checks.

Return SKIP from this event handler to discard an enrollment.

audio-stream, audio-stream-first, audio-stream-last, begin-sample, end-sample, enrollment-id, sample-count

none

^fail

^pause¶

event handle write-only

C/C++Java

#define SNSR_PAUSE_EVENT "^pause"

public class Snsr {
  public final static String PAUSE_EVENT = "^pause";
}

Input stream pause event.

Handler called when a time-consuming processing step is about to start. Use this handler to pause the input stream when doing interactive enrollment.

sample-count

none

^resume

^progress¶

event handle write-only

C/C++Java

#define SNSR_PROG_EVENT "^progress"

public class Snsr {
  public final static String PROG_EVENT = "^progress";
}

Wake word adaptation progress event.

Handler called to report adaptation progress.

percent-done, sample-count

none

^adapted

^result¶

event handle write-only

C/C++Java

#define SNSR_RESULT_EVENT "^result"

public class Snsr {
  public final static String RESULT_EVENT = "^result";
}

Recognition result available event.

Raised when a final recognition hypothesis is available.

begin-ms, begin-sample, confidence-score, domain, end-ms, end-sample, id, noise-energy, score, signal-energy, snr, sv-score, text

phone-iterator, phrase-iterator, sample-count, word-iterator

^result-partial

^result-partial¶

event handle write-only tnl stt

C/C++Java

#define SNSR_PARTIAL_RESULT_EVENT "^result-partial"

public class Snsr {
  public final static String PARTIAL_RESULT_EVENT = "^result-partial";
}

Partial recognition result available event.

Raised when a preliminary recognition hypothesis is available.

begin-ms, begin-sample, domain, end-ms, end-sample, sample-count, score, text

phone-iterator, phrase-iterator, word-iterator

^result

^resume¶

event handle write-only

C/C++Java

#define SNSR_RESUME_EVENT "^resume"

public class Snsr {
  public final static String RESUME_EVENT = "^resume";
}

Input stream resume event.

Handler called when a time-consuming processing step has completed. Use this handler to restart an input stream that was stopped during a ^pause event handler.

sample-count

none

^pause

^sample-count¶

event handle write-only

C/C++Java

#define SNSR_SAMPLES_EVENT "^sample-count"

public class Snsr {
  public final static String SAMPLES_EVENT = "^sample-count";
}

Samples available event.

Raised whenever audio samples have been read from the input stream and are about to be processed.

sample-count

none

^silence¶

event handle write-only

C/C++Java

#define SNSR_SILENCE_EVENT "^silence"

public class Snsr {
  public final static String SILENCE_EVENT = "^silence";
}

No speech detected event.

Raised if no speech is detected within leading-silence ms from the start of ->audio-pcm, adjusted by skip-to-ms or skip-to-sample

sample-count

none

leading-silence, skip-to-ms, skip-to-sample

^slm-result¶

event handle write-only stt 7.4.0

C/C++Java

#define SNSR_SLM_RESULT_EVENT "^slm-result"

public class Snsr {
  public final static String SLM_RESULT_EVENT = "^slm-result";
}

SLM final output available

This event is raised when an optional SLM has a complete result available.

In the handler for this callback text holds the entire SLM response.

sample-count, text

none

^slm-result-partial

^slm-result-partial¶

event handle write-only stt 7.4.0

C/C++Java

#define SNSR_SLM_PARTIAL_RESULT_EVENT "^slm-result-partial"

public class Snsr {
  public final static String SLM_PARTIAL_RESULT_EVENT = "^slm-result-partial";
}

SLM partial output available

This event is raised when an optional SLM has a new word prediction available.

In the handler for this callback text holds the next word prediction. Return STOP from the callback to abort further SLM generation; this will not stop the overall recognition pipeline.

sample-count, text

none

^slm-result

^slm-start¶

event handle write-only stt 7.4.0

C/C++Java

#define SNSR_SLM_START_EVENT "^slm-start"

public class Snsr {
  public final static String SLM_START_EVENT = "^slm-start";
}

SLM processing is about to start

Return STOP from the callback handler to avoid doing SLM processing.

sample-count

none

^slm-result, ^slm-result-partial