irFPlay, irBPlay - play speech from a voice file name, or a buffer
#include <irapi.h>
int irFPlay (channel_id cid, int tag, char *voice_file);
int irBPlay (channel_id cid, int tag, char *buf, unsigned long count);
This function plays speech on a voice channel indicated by a channel identifier (cid). The cid is obtained by calling irInit(3IRAPI).
Tag is a user-supplied number that associates a play function call with a subsequent event.
irFPlay plays speech from a voice file identified by the file name voice_file. irFPlay opens the voice_file, plays the entire file from the beginning, then automatically closes the file. voice_file should be in wav format. The only encoding algorithm supported at present is ITU G.711.
irBPlay plays count bytes of speech from a voice buffer identified by the buffer name buf. The data represented by buf and count cannot be reused until the play is complete (that is, IRE_PLAY_DONE occurs).
The IRAPI library parameter IRP_PLAY_GAIN specifies the play volume and IRP_PLAY_SPEED specifies play speed. Existing values for these parameters can be retrieved using irGetParam(3IRAPI) while new values can be assigned to them using irSetParam(3IRAPI). The default IRP_PLAY_GAIN is unity gain (0 db) and IRP_PLAY_SPEED is unity. These parameters must be set to the desired values before invoking a play function. Play functions use the value of these parameters available at the time of the play.
Any play function must be followed by irEnd(3IRAPI) and can be terminated when an enabled interrupt occurs [see irSetEvent(3IRAPI)]. When irFPlay is terminated, the voice_file is closed.
If the library state is IRS_IDLE (not playing), calling irFPlay changes the library state to IRS_PLAY_QUEUED. If the library state is IRS_PLAY_QUEUED, subsequent calls to a play function are queued and the library remains in the IRS_PLAY_QUEUED state.
Multiple invocation of play functions to a single cid results in concatenated speech to that channel. The speech stream, up to a "terminating" irEnd(3IRAPI), are played seamlessly.
irGetVCount(3IRAPI) is used to obtain the number of bytes played after play function is interrupted or stops playing. irGetVCount(3IRAPI) does not return meaningful results until IRE_PLAY_DONE occurs.
An IRE_PLAY_DONE event is generated when all play requests preceding the irEnd(3IRAPI) complete or an interrupt occurs which causes play to stop.
All play functions return IRR_OK if the play request is queued successfully.
IRR_FAIL is returned if an error occurs.
irError is set as follows if an error occurs:
IRER_INVALID if the cid is invalid
IRER_INVALID if the buf is the NULL pointer or if count is less than or equal to zero
IRER_SYSERROR if a system or driver call failure occurs (check irSysError for additional information)
IRER_BADSTATE if the cid is not in the IRS_IDLE or IRS_PLAY_QUEUED state
IRER_OVERFLOW if the voice_file is greater than IRD_MAX_FILE_LEN
irFPlay does not check for the existence of voice_file. Failure to find a file specified through irFPlay results in a logger message generated by VROP_TNG and an IREM_ERROR modifier on the subsequent IRE_PLAY_DONE event.
irSay(3IRAPI), IrPARAMETERS(4IRAPI)
One variety of play is now obsolete:
int irPlay (channel_id cid, int tag, vf_descriptor vfd, unsigned long count);
irPlay() would play speech from a voice file descriptor
IRE_PLAY_PROG is no longer supported.
This is version 05/22/03 of this man page.