Universal Speech Access API events

In response to commands executed by an application, USAI generates events and reason codes that indicate the occurrence (or lack) of certain conditions or state changes.

This topic provides the following information:

• NaturalAccess event structure

• Universal Speech Access API event header

• Alphabetical event summary

• Numerical event summary

• Event information buffers

NaturalAccess event structure

Events returned by NaturalAccess APIs (such as USAI) conform to the following structure:

typedef struct
{    
DWORD     id;
CTAHD     ctahd;
DWORD     timestamp;
DWORD     userid;
DWORD     size;
void      *buffer;
DWORD     value;
unsigned  objHd;
} CTA_EVENT;

where fields in the event structure provide the following information:

USAI events are preceded with the prefix SAIEVN_ and contain. All defined SAI event buffers contain event header information and may contain additional information in the event buffer.

Universal Speech Access API event header

Universal Speech Access API events contain the following header:

typedef struct
{    
DWORD              size;         /* For compatibility. */    
DWORD              eventType;    /* Event type */    
SAI_REQUEST_ID     reqId;        /* Request id associated to this event */    
SAI_REQUEST_STATE  reqState;     /* Command request state */    
DWORD              engineHandle; /* SAI_SYNTHESIZER_HANDLE or SAI_RECOGNIZER_HANDLE */    
DWORD              clientObjId;  /* The client registered object identifier */
}
SAI_EVENT_HEADER;

The USAI event header provides the following information:

Alphabetical listing

The following table alphabetically lists the USAI events:

Numerical listing

The following table numerically lists the USAI events:

Event information buffers

USAI events can return additional information in the following event buffers:

• SAI_EVENT_ASR_DEFINE_GRAMMAR

• SAI_EVENT_ASR_GET_RECOGNITION_RESULT

• SAI_EVENT_ASR_RECOGNITION_COMPLETE

• SAI_EVENT_ASR_START_OF_SPEECH

• SAI_EVENT_ASR_STOP

• SAI_EVENT_COMMON

• SAI_EVENT_ENGINE_CREATION

• SAI_EVENT_ENGINE_FAILED

• SAI_EVENT_ENGINE_RELEASE

• SAI_EVENT_LINK_CHANGED

• SAI_EVENT_TTS_CONTROL

• SAI_EVENT_TTS_MARKER

• SAI_EVENT_TTS_NOTIFY_BARGE_IN

• SAI_EVENT_TTS_PAUSE

• SAI_EVENT_TTS_RESUME

• SAI_EVENT_TTS_SPEAK_COMPLETE

• SAI_EVENT_TTS_STOP

SAI_EVENT_ASR_DEFINE_GRAMMAR

Buffer associated with the SAIEVN_ASR_DEFINE_GRAMMAR_DONE event that is returned when an ASR engine finishes downloading and compiling a specified grammar. The SAI_EVENT_ASR_DEFINE_GRAMMAR buffer consists of the following fields:

typedef struct
{    
SAI_EVENT_HEADER                header;  
SAI_STATUS_CODE                 statusCode;
SAI_RECOGNIZER_COMPLETION_CAUSE completionCause;
} SAI_EVENT_ASR_DEFINE_GRAMMAR;

where:

SAI_EVENT_ASR_GET_RECOGNITION_RESULT

Buffer associated with the SAIEVN_ASR_GET_RESULT_DONE event that is returned when a request to re-compute a recognition process completes. The SAI_EVENT_ASR_GET_RECOGNITION_RESULT buffer consists of the following fields:

typedef struct
{    
SAI_EVENT_HEADER             header;             
SAI_STATUS_CODE              statusCode;         
char                         recognitionResult[1];
} SAI_EVENT_ASR_GET_RECOGNITION_RESULT;

where:

SAI_EVENT_ASR_RECOGNITION_COMPLETE

Buffer associated with the SAIEVN_ASR_RECOGNITION_DONE event that is returned when the ASR engine completes (successfully or unsuccessfully) a recognition task.

If the completionCause value is SAI_RCC_NORMAL, then the recognitionResult value is valid. All media servers must support the W3C Natural Language Semantics Markup Language (NLSML) as the default standard for returning recognition results to the client, and must also support the MIME-type application/x-nlsml. The ASR context keeps the result and the audio waveform input of the recognition task until USAI receives the next recognition request .

The SAI_EVENT_ASR_RECOGNITION_COMPLETE buffer consists of the following fields:

typedef struct
{    
SAI_EVENT_HEADER                header;
SAI_RECOGNIZER_COMPLETION_CAUSE completionCause;
char                            recognitionResult[1];
} SAI_EVENT_ASR_RECOGNITION_COMPLETE;

where:

SAI_EVENT_ASR_START_OF_SPEECH

Buffer associated to the SAIEVN_ASR_START_OF_SPEECH event that is returned when the ASR engine detects a speech signal. The SAIEVN_ASR_START_OF_SPEECH event is useful in implementing kill-on-barge-in functionality when the synthesizer resource is in a different session than the recognizer resource and therefore is not aware of an incoming audio source. In these cases, the client must act as a proxy and invoke saiNotifyBargeInToSynthesizer to notify the synthesizer that a barge-in occurred.

The recognizer resource returns a unique proxy-sync-id in the event header, according to the proxySyncId parameter specified in saiNotifyBargeInToSynthesizer.

The SAI_EVENT_ASR_START_OF_SPEECH buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER         header;
SAI_PROXY_SYNC_ID        proxySyncId;
} SAI_EVENT_ASR_START_OF_SPEECH;

where:

SAI_EVENT_ASR_STOP

Buffer associated with the SAIEVN_ASR_STOP_DONE event that is returned when a request to stop a recognition process completes. The SAIEVN_ASR_STOP_DONE buffer consists of the following fields:

typedef struct
{    
SAI_EVENT_HEADER             header;
SAI_STATUS_CODE              statusCode;
SAI_REQUEST_ID               stoppedReqId;
} SAI_EVENT_ASR_STOP;

where:

SAI_EVENT_COMMON

Buffer associated to the following events:    

• SAIEVN_GET_PARAMETER_DONE

• SAIEVN_SET_PARAMETER_DONE

• SAIEVN_ASR_RECOGNITION_STARTED

• SAIEVN_ASR_START_TIMER_DONE

• SAIEVN_TTS_SPEAK_ACKNOWLEDGED

• SAIEVN_ENGINE_FAILED

The SAI_EVENT_COMMON buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER                header;
SAI_STATUS_CODE                 statusCode;
} SAI_EVENT_COMMON;

where:

SAI_EVENT_ENGINE_CREATION

Buffer associated with the SAIEVN_ENGINE_CREATION_DONE event that indicates that USAI has either succeeded or failed in creating a TTS or ASR engine. The SAIEVN_ENGINE_CREATION buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER    header;
SAI_ENGINE_STATUS_CODE statusCode;   
DWORD               enginePort;/
char                engineIp[SAI_MAX_IP_ADDRESS_LENGTH];
} SAI_EVENT_ENGINE_CREATION;

where:

SAI_EVENT_ENGINE_FAILED

Buffer associated with the SAIEVN_ENGINE_FAILED event returned when a session connection problem occured at the TTS or ASR side. When an application receives an SAIEVN_ENGINE_FAILED event, it must invoke saiReleaseSynthesizer or saiReleaseRecognizer to release the associated TTS or ASR engine.

The SAI_EVENT_ENGINE_FAILED buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER           header;
SAI_ENGINE_STATUS_CODE     statusCode;   
} SAI_EVENT_ENGINE_FAILED;

where:

SAI_EVENT_ENGINE_RELEASE

Buffer associated with the SAIEVN_ENGINE_RELEASE_DONE event. The buffer indicates whether the ASR or TTS engine has been released. The SAIEVN_ENGINE_CREATION buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER              header;
SAI_ENGINE_STATUS_CODE        statusCode;
} SAI_EVENT_ENGINE_RELEASE;

where:

SAI_EVENT_LINK_CHANGED

Buffer associated with the SAIEVN_LINK_CHANGED event that indicates whether the speech server is up or down. The SAIEVN_LINK_CHANGED buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER              header;
BOOL                          isUp;
char                          serverName[SAI_MAX_SERVER_NAME];
} SAI_EVENT_LINK_CHANGED;

where:

SAI_EVENT_TTS_CONTROL

Buffer associated to the SAIEVN_TTS_CONTROL_DONE event that is returned when the a speech synthesis control request completes. The SAI_EVENT_TTS_CONTROL buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER           header;    
SAI_STATUS_CODE            statusCode;
BOOL                       fSpeakRestart;       
SAI_REQUEST_ID             reqList[ SAI_MAX_STOPREQUEST + 1 ]; // +1 for padding
} SAI_EVENT_TTS_CONTROL;

where:

SAI_EVENT_TTS_MARKER

Buffer associated with the unsolicited SAIEVN_TTS_SPEAK_MARKER_REACHED event that is returned when the TTS engine detects an occurrence of a specified marker. The SAI_EVENT_TTS_MARKER buffer consists of the following fields::

typedef struct
{
SAI_EVENT_HEADER             header;
SAI_MARKER                   markerStr;
} SAI_EVENT_TTS_MARKER;

where:

SAI_EVENT_TTS_NOTIFY_BARGE_IN

Buffer associated to the SAIEVN_TTS_NOTIFY_BARGE_IN_DONE event that is returned when a NOTIFY-BARGE-IN request completes. The SAI_EVENT_TTS_NOTIFY_BARGE_IN buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER           header;
SAI_STATUS_CODE            statusCode;
SAI_REQUEST_ID             reqList[ SAI_MAX_STOPREQUEST + 1 ]; // +1 for padding
} SAI_EVENT_TTS_NOTIFY_BARGE_IN;

where:

SAI_EVENT_TTS_PAUSE

Buffer associated to the SAIEVN_TTS_PAUSE_DONE event  that is returned when a request to pause an active speech synthesis process completes. The SAI_EVENT_TTS_PAUSE buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER             header;
SAI_STATUS_CODE              statusCode;    
SAI_REQUEST_ID               pausedReqId;        /* The paused reqId */
} SAI_EVENT_TTS_PAUSE;

where:

SAI_EVENT_TTS_RESUME

Buffer associated to the SAIEVN_TTS_RESUME_DONE event that is returned when the request to resume a paused speech synthesis process completes. The SAI_EVENT_TTS_RESUME buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER             header;   
SAI_STATUS_CODE              statusCode;  
SAI_REQUEST_ID               resumedReqId;  
} SAI_EVENT_TTS_RESUME;

where:

SAI_EVENT_TTS_SPEAK_COMPLETE

Buffer associated with the SAIEVN_TTS_SPEAK_DONE event that is returned when the TTS engine successfully or unsuccessfully completes a speech synthesis command. The SAI_EVENT_TTS_SPEAK_COMPLETE buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER             header;
SPEAK_COMPLETION_CAUSE       completionCause;
} SAI_EVENT_TTS_SPEAK_COMPLETE;

where:

SAI_EVENT_TTS_STOP

Buffer associated to the SAIEVN_TTS_STOP_DONE event that is returned when a request to stop a list of speech synthesis tasks completes. The SAI_EVENT_TTS_STOP buffer consists of the following fields:

typedef struct
{
SAI_EVENT_HEADER          header;             
SAI_STATUS_CODE           statusCode;         
SAI_REQUEST_ID            reqList[ SAI_MAX_STOPREQUEST + 1 ]; // +1 for padding
} SAI_EVENT_TTS_STOP;

where: