The following functions are provided by the Prosody high level FILE play/record API:
| API call | W | Description |
|---|---|---|
| sm_replay_file_start() | Start replaying data from a file. | |
| sm_replay_file_progress_istatus() | Proceed with replaying data from a file | |
| sm_replay_file_progress() | Proceed with replaying data from a file | |
| sm_replay_file_complete() | Replay remaining data from a file and clean up afterwards | |
| sm_replay_file_stop() | Abort replaying data from a file. | |
| sm_record_file_start() | Start recording data into a file. | |
| sm_record_file_progress_istatus() | Proceed with recording data to a file | |
| sm_record_file_progress_ostatus() | Proceed with recording data to a file and report ongoing status | |
| sm_record_file_progress() | Proceed with recording data to a file | |
| sm_record_file_complete() | Record remaining data to a file and clean up afterwards | |
| sm_record_file_complete_tstatus() | T | Record remaining data to a file, report temination status and clean up afterwards |
| sm_record_file_stop() | Abort the recording of data to a file |
Key to W column:
| T | Functionality added in Prosody version 2 (TiNG) |
|---|
This document is also available as separate pages for each function.
int sm_replay_file_start(struct sm_file_replay_parms *file_parms)
typedef struct sm_file_replay_parms {
tSM_OPEN_FILE fd; /* in */
tSM_UT32 offset; /* in */
SM_REPLAY_PARMS replay_parms; /* in */
int status; /* out */
tSM_UT32 private_length; /* out */
int completing; /* out */
int data_length_in_buffer; /* out */
char buffer[kSMMaxHiReplayDataBufferSize]; /* out */
} SM_FILE_REPLAY_PARMS;
Prepares a channel for replay of data from a file to an output channel previously allocated by a call to sm_channel_alloc_placed().
When using the TiNG dll under Windows use of this function requires a FILE* to be passed across the dll boundry. This may cause problems when the application uses a different C runtime library from the TiNG dll. Since the C runtime library used by the TiNG dll may change in future versions, this function is deprecated when using the TiNG dll.
The fields of the structure replay_parms should be set up as described in sm_replay_start() low level API call. Note the field data_length should either be set to zero or to the actual number of octets to be replayed from the file. If it is set to zero then all of the data starting from offset to the end of the file will be replayed.
The
status
field is used to indicate the current status of the
replay. On return from a successful invocation of
sm_replay_file_start()
it will be set to a value of ERR_SM_PENDING and
will continue to have this value until replay has been
completed, aborted or terminated on occurrence of an error.
The fields private_length, data_length_in_buffer and buffer are used internally by the high level library and should not be accessed by the application.
The replay is finished when a call to sm_replay_file_complete() returns.
__SMWIN32HLIB__ defined, in which case it must be a
Windows HANDLE. It is recommended that the
Prosody high level BFILE play/record is used where possible
instead of rebuilding this library, since it avoids the risk of
accidentally using the library built for the wrong type of file
access.
0 if call completed successfully, otherwise a standard error such as:
int sm_replay_file_progress_istatus(SM_FILE_REPLAY_PARMS *file_parms, int initial_status)
Transfers file data to speech processing module for previously initiated replay unless the channel has insufficient buffering space to accept more data, or all data has been transferred, or an error occurs.
If the current replay status for the channel is not known, then the sm_replay_file_progress() variant of the call must be used.
The parameter
file_parms
must point to the same
sm_file_replay_parms structure as was previously
used to initiate the file replay.
On return if the status field is still set to a value of
ERR_SM_PENDING then further calls to this routine will be
required to complete the file replay. If status has a zero value
then replay has successfully completed. Otherwise replay has
been terminated on error, and status will be set to a
corresponding error code.
Note: this routine (or the equivalent sm_replay_file_progress()) must be periodically invoked following a call to sm_replay_file_start(). This may either be done explicitly by the application, or alternatively through a call to sm_replay_file_complete() which will handle the scheduling of calls to sm_replay_file_progress() on behalf of the application.
The same value as stored in the status field of the structure
pointed to by
file_parms
which is 0 or ERR_SM_PENDING
if call completed successfully, otherwise a standard error such as:
int sm_replay_file_progress(SM_FILE_REPLAY_PARMS *file_parms)
This is the same as sm_replay_file_progress_istatus() except it first determines the replay status.
If the current replay status for the channel is known, then the sm_replay_file_progress_istatus() variant of the call should be used with initial_status set to this status.
int sm_replay_file_complete(SM_FILE_REPLAY_PARMS *file_parms)
Transfers all remaining data from file to speech processing module for previously initiated replay. This call may block during execution while it waits for buffering capacity to become available on the speech processing module.
On completion the offset field will have been updated to indicate at which byte offset in the file replay was aborted at, thus allowing a simple method for playback to be resumed through a subsequent call to sm_replay_file_start().
Note that this function assigns an event to the channel and removes it again when the replay finishes. If the channel previously had an event assigned, that assignment may have been lost (this depends on the operating system as events work differently on different operating systems).
0 if call completed successfully, otherwise a standard error such as:
int sm_replay_file_stop(SM_FILE_REPLAY_PARMS *file_parms, int nowait)
Abort a previously initiated file replay. If nowait if non-zero, this function assumes the current file replay is being progressed by a separate thread of execution in which sm_replay_file_complete() has been invoked.
0 if call completed successfully, otherwise a standard error such as:
int sm_record_file_start(struct sm_file_record_parms *file_parms)
typedef struct sm_file_record_parms {
tSM_OPEN_FILE fd; /* in */
SM_RECORD_PARMS record_parms; /* in */
int status; /* out */
tSM_UT32 private_length; /* out */
int completing; /* out */
char buffer[kSMMaxHiRecordDataBufferSize]; /* out */
} SM_FILE_RECORD_PARMS;
Prepares channel for recording of data to a file from an input channel previously allocated by a call to sm_channel_alloc_placed().
When using the TiNG dll under Windows use of this function requires a FILE* to be passed across the dll boundry. This may cause problems when the application uses a different C runtime library from the TiNG dll. Since the C runtime library used by the TiNG dll may change in future versions, this function is deprecated when using the TiNG dll.
The status field is used to indicate the current status of the
record. On return from a successful invocation of
sm_record_file_start()
it will be set to a value of ERR_SM_PENDING and
will continue to have this value until recording has been
completed, aborted or terminated on occurrence of an error.
The fields private_length and buffer are used internally by the high level library and should not be accessed by the application.
The recording is finished when a call to sm_record_file_complete() returns.
__SMWIN32HLIB__ defined, in which case it must be a
Windows HANDLE. It is recommended that the
Prosody high level BFILE play/record is used where possible
instead of rebuilding this library, since it avoids the risk of
accidentally using the library built for the wrong type of file
access.
0 if call completed successfully, otherwise a standard error such as:
int sm_record_file_progress_istatus(SM_FILE_RECORD_PARMS *file_parms, int initial_status)
Transfers data from a recording channel to file for a previously initiated record unless the channel has insufficient buffered data to collect, or all data in recording has been collected, or an error occurs.
If the current record status for the channel is not known, then the sm_record_file_progress() variant of the call must be used.
On return if the status field is still set to a value of
ERR_SM_PENDING then further calls to this routine
will be required to complete the file record. If the status is
zero then recording successfully completed, otherwise the
record has been terminated on error, and the status will be set
to a corresponding error code.
Note: this routine must be periodically invoked following a call to sm_record_file_start(). This may either be done explicitly by the application, or alternatively through a call to sm_record_file_complete() which will handle the scheduling of calls to sm_record_file_progress() on behalf of the application.
Note that the sampling_rate of the record_parms structure is not updated to the recorded sample rate, as returned by sm_record_status(). If the recording is to a WAV file, then this is must be done by the application before closing the WAV file. Otherwise the WAV header will not have the correct values.
The same value as stored in the status field of the structure
pointed to by
file_parms
which is 0 or ERR_SM_PENDING
if call completed successfully, otherwise a standard error such as:
int sm_record_file_progress_ostatus(SM_FILE_RECORD_PARMS *file_parms, SM_RECORD_STATUS_PARMS *status_parms)
This is the same as sm_record_file_progress_istatus() except it first determines the status of the recording and reports this to the user.
When this function returns without an error, the fields in the status_parms structure are valid. On completion of a recording, the termination status will be reported in the status_parms structure.
If the current record status for the channel is known, then the sm_record_file_progress_istatus() variant of the call should be used with initial_status set to this status.
The same value as stored in the status field of the structure
pointed to by
file_parms
which is 0 or ERR_SM_PENDING
if call completed successfully, otherwise a standard error such as:
int sm_record_file_progress(SM_FILE_RECORD_PARMS *file_parms)
This is the same as sm_record_file_progress_istatus() except it first determines the record status.
If the current record status for the channel is known, then the sm_record_file_progress_istatus() variant of the call should be used with initial_status set to this status.
The same value as stored in the status field of the structure
pointed to by
file_parms
which is 0 or ERR_SM_PENDING
if call completed successfully, otherwise a standard error such as:
int sm_record_file_complete(SM_FILE_RECORD_PARMS *file_parms)
Transfers all remaining data from speech processing module to file for previously initiated record. This call may block during execution while it waits for buffered data to become available on the speech processing module.
Note that this function assigns an event to the channel and removes it again when the replay finishes. If the channel previously had an event assigned, that assignment may have been lost (this depends on the operating system as events work differently on different operating systems).
0 if call completed successfully, otherwise a standard error such as:
This function is only in Prosody version 2 (TiNG).
int sm_record_file_complete_tstatus(SM_FILE_RECORD_PARMS *file_parms, SM_RECORD_STATUS_PARMS *status_parms)
This is the same as sm_record_file_complete() except that on successful completion the status_parms structure will contain the termination status of the recording. The fields in the status_parms structure are only valid when the function returns success.
0 if call completed successfully, otherwise a standard error such as:
int sm_record_file_stop(SM_FILE_RECORD_PARMS *file_parms, int nowait)
Abort a previously initiated file recording. If nowait if non-zero, this function assumes the current file recording is being progressed by a separate thread of execution in which sm_record_file_complete() has been invoked.
0 if call completed successfully, otherwise a standard error such as:
These functions constitute the Prosody high level FILE play/record API.