osVoiceGetReadData

#include <ultra64.h>

s32 osVoiceGetReadData(OSVoiceHandle *hd, OSVoiceData *result);

Explanation
The osVoiceGetReadData() function is for getting the recognition result from the Voice Recognition System. hd is the Voice Recognition System control structure. The Voice Recognition System must be initialized with the osVoiceInit() function before the osVoiceGetReadData() function is called.

The recognition result is stored in result of the OSVoiceData structure. The contents of the OSVoiceData structure are as follows.

typedef struct {
   u16  warning;		/* Warning */
   u16  answer_num;	/* Candidate number (0~5) */
   u16  voice_level;	/* Voice input level */
   u16  voice_sn;	/* Relative voice level */
   u16  voice_time;	/* Voice input time */
   u16  answer[5];	/* Candidate word number */
   u16  distance[5];	/* Distance value */
} OSVoiceData;

The warning member variable of the OSVoiceData structure is the warning which pertains to the recognition result. The following bits are flagged when there is any problem with the recognition result.

Table 7  Bits Flagged When There is a Problem with the Recognition Result

Warning Name	Value	Description	Conditions
VOICE_WARN_TOO_SMALL	0x0400	Voice level is too low	100 < Voice Level < 150
VOICE_WARN_TOO_LARGE	0x0800	Voice level is too high	Voice Level > 3500
VOICE_WARN_NOT_FIT	0x4000	No words match recognition word	No. 1 Candidate Distance Value > 1600
VOICE_WARN_TOO_NOISY	0x8000	Too much ambient noise	Relative Voice Level is less than, or equal to 400

The "answer_num" member variable is the number of valid candidates. This is the number of words judged by the Voice Recognition System being valid as candidates. It is a value from 0 to 5. If this is 0, there are no valid candidates.

The "voice_level" member variable is the level of the input voice. The greater the voice input, the larger this value is.

The "voice_sn" member variable is the relative level of the voice input to the noise input.

The voice_time member variable is the voice input time in ms units.

The "answer[]" member variable is the numbers of the words from the 1st candidate to the 5th candidate. The word numbers are always output from the 1st candidate to the 5th candidate, but those which are deemed by the Voice Recognition System to be valid are numbered as candidates from the first to number of words in answer_num. Normally, answer[] is a value 0 ~ 0x00ff, but if there are no suitable words, its value is 0x7fff.

The "distance[]" member variable is the distance value of the word from the 1st candidate to the 5th candidate. The more similar the word, the smaller this value is.

Before calling the osVoiceGetReadData() function, voice recognition processing must be started with the osVoiceStartReadData() function.

The returned value is an error code. A 0 (zero) is returned when processing ends normally. If an error occurs, this function has the following error codes.

CONT_ERR_NO_CONTROLLER
Nothing is connected to the controller port.

CONT_ERR_DEVICE
Something other than the Voice Recognition System is connected to the controller port.

CONT_ERR_NOT_READY
Either no voice has been input, or results cannot be acquired for some reason, such as that processing is still underway, etc. Wait for a moment then try calling this function again. This error will occur if the status following execution of the osVoiceStartReadData() function is any of VOICE_STATUS_START, VOICE_STATUS_CANCEL, or VOICE_STATUS_BUSY.

CONT_ERR_VOICE_NO_RESPONSE
There was no response from the Voice Recognition System. There may be a problem with the hardware.

CONT_ERRO_CONTRFAIL
There was a data transmission failure. There is a problem in the Voice Recognition System connection.

CONT_ERR_INVALID
There is an error in the function call method or in the argument. This error will not occur if the function is being used correctly. Write your program so that this error does not occur when development is completed.

See Also
osContInit
osVoiceCheckWord
osVoiceClearDictionary
osVoiceControlGain
osVoiceCountSyllables
osVoiceInit
osVoiceMaskDictionary
osVoiceSetWord
osVoiceStartReadData
osVoiceStopReadData