Prosody speech processing: API: sm_record_status

Prototype Definition

int sm_record_status(struct sm_record_status_parms *statusp)

Parameters

*statusp
a structure of the following type: 
typedef struct sm_record_status_parms {
	tSMChannelId channel;					/* inout */
	enum kSMRecordStatus {
		kSMRecordStatusComplete,
		kSMRecordStatusCompleteData,
		kSMRecordStatusOverrun,
		kSMRecordStatusData,
		kSMRecordStatusNoData,
		kSMRecordStatusRecognition,
	} status;						/* out */
	/* Only in Prosody version 2 (TiNG) */
	enum kSMRecognition recog_type;				/* out */
	tSM_INT param0;						/* out */
	tSM_INT param1;						/* out */
	enum kSMRecordHowTerminated {
		kSMRecordHowTerminatedNotYet,
		kSMRecordHowTerminatedLength,
		kSMRecordHowTerminatedMaxTime,
		kSMRecordHowTerminatedSilence,
		kSMRecordHowTerminatedAborted,
		kSMRecordHowTerminatedError,
	} termination_reason;					/* out */
	tSM_UT32 termination_octets;				/* out */
	tSM_UT32 sample_rate;					/* out */
	/* End of part only in Prosody version 2 (TiNG) */
} SM_RECORD_STATUS_PARMS;

Description

This call, typically invoked in response to a read event being signalled, allows an application to determine the status of a specific on-going record job.

In order to determine the status of a specific record job, the application should set channel to specify the job concerned.

In order to determine the record job that has completed or would most benefit from having data read, on calling sm_record_status() the application should set channel to kSMNullChannelId. On return, if any suitable record job exists, channel will be set to the identifier for the input channel corresponding to that job and status will be set to one of the values: kSMRecordStatusComplete, kSMRecordStatusCompleteData, kSMRecordStatusOverrun, or kSMRecordStatusData. If no such record job exists, then channel will remain set to kSMNullChannelId and the call will return ERR_SM_NO_SUCH_CHANNEL.

Only on Prosody version 2 (TiNG): When you set channel to kSMNullChannelId, the only channels which can be indicated as being ready are those which have been registered for 'any channel' read operation using sm_channel_set_event() See Prosody TiNG: any channel operation for how to do this.

A channel ceases to be recording when this function returns a status of kSMRecordStatusComplete. Until this happens, the channel input is reserved for the record and no other recording activity can take place on the channel during this time. After this happens, the channel input returns to being idle and consequently if this function is used again it will return the error ERR_SM_NO_RECORD_IN_PROGRESS.

Fields

channel
The channel which is recording.
status
The channel's status. One of these values:
kSMRecordStatusComplete
The recording job has completed and all the recorded data has been passed to the application.
kSMRecordStatusCompleteData
The recording job has completed but there still remains recorded data for the application to collect.
kSMRecordStatusOverrun
Data has not been retrieved sufficiently frequently by the application and now some has been lost due to module buffer overrun.
kSMRecordStatusData
The record job is still ongoing and data is available for collection by the application.
kSMRecordStatusNoData
The record job is still ongoing however not enough data is buffered in the module to justify collection by the application.
kSMRecordStatusRecognition
Only on Prosody version 2 (TiNG): A recognition event has occurred in the recording. The recog_type, param0 and param1 fields contain a report of what was detected. This status can occur when sm_record_start() specified an option such as tone elimination.
recog_type (Only in Prosody version 2 (TiNG))
The recognition event which has occurred. This field, with the param0 and param1 fields, has the same meaning as the type field returned by sm_get_recognised() with its corresponding param0 and param1 fields. This field is only valid when the status field is kSMRecordStatusRecognition.
One of these values:
kSMRecognisedNothing
No digit, simple or call-progress tone has been recognised
kSMRecognisedTrainingDigit
Only on Prosody version 1: The first pulse dialled digit received on a channel (or after sm_reset_channel()) will always be recognised as a training digit. The actual digit value returned in param0 will be set to -1.
kSMRecognisedDigit
A pulse dialled or DTMF dialled digit has been recognised and a character representation for it has been stored in param0. In param1 will be an indication of the digit type (kSMPulseDigits or kSMDTMFDigits) unless a tone detection mode of type kSMToneLen... was specified in which case it will contain the duration in milliseconds of the detected DTMF digit.
kSMRecognisedTone
A simple tone has been recognised from the active set of input tones for the channel. The parameter param0 and param1 are assigned values as described above.
kSMRecognisedCPTone
A call-progress tone has been recognised and the corresponding identifier has been stored in param0.
kSMRecognisedGruntStart
The beginning of a grunt has been detected
kSMRecognisedGruntEnd
The end of a grunt has been detected, param0 is set to grunt duration in milliseconds, and param1 to grunt average energy in negative dBm0 (average is calculated only over periods during which signal is present).
Only on Prosody version 1: The maximum value that can be reported as the duration is 4080.
kSMRecognisedASRResult
Only on Prosody version 1: A spoken word has been recognised with a high degree of confidence. The most likely user id has been stored in param0, with the next most likely alternative in param1.
kSMRecognisedASRUncertain
Only on Prosody version 1: A spoken word has been detected, but its identity is uncertain. The most likely user id has been stored in param0, with the next most likely alternative in param1.
kSMRecognisedASRRejected
Only on Prosody version 1: A spoken word may have been detected, but its identity could not be determined with any confidence. Possible user ids have been stored in param0 and param1.
kSMRecognisedASRTimeout
Only on Prosody version 1: A one shot ASR recognition job has timed out without any speech being detected.
kSMRecognisedCatSig
A signal has been categorised, the parameter param0 indicates the algorithm id (see sm_catsig_listen_for()) and param1 is a value indicating the signal category with respect to this algorithm (eg. live speaker or answer machine).
kSMRecognisedOverrun
The recognition FIFO has been overrun because it has not been polled frequently enough through calls to sm_get_recognised().
kSMRecognisedANS
Only on Preliminary Documentation: An ANS or ANSam tone has been detected (see sm_ans_listen_for()). The parameter param0 will describe the tone detected: 0 for end of tone, 1 for an ordinary ANS tone, or 2 for the modulated ANSam tone.
param0 (Only in Prosody version 2 (TiNG))
A parameter giving details of what was detected. The interpretation of this depends on the recog_type field. This field is only valid when the status field is kSMRecordStatusRecognition.
param1 (Only in Prosody version 2 (TiNG))
Another parameter giving details of what was detected. The interpretation of this also depends on the recog_type field. This field is only valid when the status field is kSMRecordStatusRecognition.
termination_reason (Only in Prosody version 2 (TiNG))
The reason why a recording has terminated.
One of these values:
kSMRecordHowTerminatedNotYet
Recording not yet completed.
kSMRecordHowTerminatedLength
The max_octets criterion specified to sm_record_start() was satisfied.
kSMRecordHowTerminatedMaxTime
The max_elapsed_time criterion specified to sm_record_start() was satisfied.
kSMRecordHowTerminatedSilence
The max_silence criterion specified to sm_record_start() was satisfied. The termination_octets field will indicate approximately how many octets of recorded silence were present at the end of the recording.
kSMRecordHowTerminatedAborted
sm_record_abort() was invoked.
kSMRecordHowTerminatedError
An error occurred.
termination_octets (Only in Prosody version 2 (TiNG))
The amount of data representing silence at the end of the recording (only valid if the recording has completed and termination_reason was kSMRecordHowTerminatedSilence).
sample_rate (Only in Prosody version 2 (TiNG))
The sample rate of data. This is the rate for data not yet collected.

Returns

0 if call completed successfully, otherwise a standard error such as:

This function is part of the Prosody speech processing API.