Voice Operations
Voice operations discusses how to perform voice operations using IRAPI functions. These functions are used to play pre-recorded speech and to record speech from the caller.
Speech queuing
Voice coded speech data may be placed on the channel play queue from a file or an internal buffer. Play commences when the irEnd(3IRAPI) function is called. Coded speech [irPlay(3IRAPI) functions] and TTS [irSay(3IRAPI) functions] queuing or playing cannot be mixed. A call to irEnd() must be used between queuing different types of speech (voice or TTS). Play of one type of speech must be stopped before another type is queued for play.
Pre-recorded speech may be queued for play with any combination of the irFPlay(3IRAPI) or irLP(3IRAPI) functions. Speech stored in a voice file may be queued for play with the irFPlay() function containing the path name of the voice file. irFPlay() queues the entire contents of the file given for play. A portion of a file may be queued for playing by obtaining a voice file descriptor from irOpen() function and using it with the irPlay() function. The voice file descriptor may be positioned at any point in the file using irLSeek(3IRAPI) and passed to irPlay() with a length specification. This queues the portion of the open file for play. Speech stored in an internal buffer may be queued for play with the irBPlay() function.
The irSpeakChar() function may be used to queue a character string for play. The irSpeakNum() function may be used to play whole numbers. It does not support speaking numbers in the billions and trillions because most of these numbers do not fit into an integer variable. These functions also support speaking numbers and character strings with rising, falling, or total inflections.
Speech play and control
The following functions are used to control the actual playing of queued speech.
- The irEnd(3IRAPI) function starts play of queued voice or TTS. The IRF_REMEMBER flag may be used with this function to allow a voice play request to be restarted with irPlayResume(3IRAPI). (This flag is not valid for TTS play requests.) Once irEnd() is executed, play must complete before more voice or text may be queued. Play is complete when the application receives an IRE_PLAY_DONE event.
- The irPlayResume(3IRAPI) function resumes a "remembered" play request after it has stopped [when the IRF_REMEMBER flag is used with irEnd()].
Note:
Applications should handle the possible denial or delay of voice resource allocation when irEnd() is used. Depending on the value of the IRP_RESOURCE_RETURNMODE parameter, irEnd() or irPlayResume() may return IRR_FAIL or IRR_PENDING if the voice resource is not immediately available.
- The irGetVCount(3IRAPI) function obtains the amount of time that voice activity has taken place. The return value of irGetVCount(3IRAPI) is only valid after an IRE_PLAY_DONE, IRE_PLAY_PROG or IRE_RECORD_DONE event. Time is accumulated from the most recent call to irEnd(3IRAPI), irPlayResume(3IRAPI), or irRecord(3IRAPI).
- The irStop(3IRAPI) function stops voice activity on a channel before normal completion. Play is stopped when the application receives an IRE_PLAY_DONE event.
Voice recording
The following functions are used to control voice recording.
- The irPhReserve(3IRAPI) function reserves space in a voice file for a subsequent recording. The amount of space reserved is determined by the voice coding algorithm used (that is, the value of the IRP_RECORD_ALGO parameter) and the amount of time (in milliseconds) passed to the function.
- The irRecord(3IRAPI) function records speech into a voice file descriptor obtained from irOpen(3IRAPI).
- The irFRecord(3IRAPI) function records directly to a given voice file. It opens the file passed to it, records the caller's voice into the file, and closes the file when recording terminates.
- The irBRecord(3IRAPI) function records directly into an internal buffer of IRD_SPEECH_BUF_SIZE bytes. This function generates an IRE_RECORD_BUF event to signal the application to process the contents of the buffer before waiting for another event. The data in the buffer is overwritten as each IRE_RECORD_BUF is received.
- The irRecordResume(3IRAPI) function resumes voice recording after it has been stopped. The recording must have been initiated with the "remember'' flag set in a call to irRecord(3IRAPI) or irFRecord(3IRAPI).
- The irStop(3IRAPI) function terminates recording. Recording is stopped when the application receives an IRE_RECORD_DONE event.
