Audio module interface.


struct asra_module_interface asra_module_interface_t {
    const char * name ;
    const char * version ;
    int(* init )(cfg_item_t *asr_config);
    void(* destroy )();
    int(* rate )(const char *url);
    void(* unrate )();
    int(* set_params )();
    int(* open )();
    int(* start )();
    int(* acquire_buffer )(asr_audio_info_t *info, int wait);
    void(* relinquish_buffer )(asr_audio_info_t *info);
    int(* get_utterance )(asr_audio_info_t *info);
    int(* set_utterance )(asr_audio_info_t *info, int offset_ms);
    int(* save_wavefile )(const char *fname);
    int(* stop )();
    int(* close )();


const char * name
The name of the module.
const char * version
The version of ASR that this module was designed for.

The version number is used to prevent newer, incompatible modules from being used with an older build of ASR.

int(* init)(cfg_item_t *asr_config)
Initialize the specified module.

The io-asr service calls init() for each registered module on startup. The init() function sets the audio properties.

  • asr_config ASR configuration information (such as the sample rate, number of channels sample size, and so on. The required settings depend on the vendor implementation). See cfg_item_t.
  • 0 Success.
  • <0 An error occurred.
void(* destroy)()
Destroy a module.

The io-asr service calls destroy() when shutting down a module that has successfuly initialized via the init() function.

int(* rate)(const char *url)
Rate this module for the specified source.

The rate() function rates this module's ability to handle the specified audio source URL. The module should rate itself 100 if it can reliably play resources of the specified type, but should supply a lower rating if can't play the resources or if it must perform additional processing first.

  • url The URL for the audio source.
  • The module's rating on success; -1 on error.
void(* unrate)()
Remove the rating for this module.

The unrate() function removes the rating for this audio module.

int(* set_params)()
Set the audio parameters for this module.

The set_params() function sets the global audio parameters for this module.

  • 0 Success.
  • -1 An error occurred.
int(* open)()
Open the audio module.

The open() function opens this audio module.

  • 1 Success.
  • <1 An error occurred.
int(* start)()
Start the audio module.

The start() function causes the module to begin to perform its particular service, for example capturing audio or playing back from a file.

  • 0 Success.
  • -1 An error occurred.
int(* acquire_buffer)(asr_audio_info_t *info, int wait)
Request an audio buffer.

The acquire_buffer() function requests a buffer.

  • info The structure to store the audio sample.
  • wait An optional flag to indicate whether the module should wait for a successful audio sample.
  • 0 Capturing has finished. The buffer is available.
  • >0 Capturing is ongoing.
  • <0 An error ocurred.
void(* relinquish_buffer)(asr_audio_info_t *info)
Relinquish an audio buffer.

The relinquish_buffer() function resets the buffer in the info structure so that it can be used again.

  • info The structure that contains the buffer.
int(* get_utterance)(asr_audio_info_t *info)
Capture an utterance.

The get_utterance() function stores an audio sample in the buffer referenced by the info parameter. It also sets the associated properties of the utterance: buffer size, sample size, sample rate, and number of channels. The get_utterance() function waits until the audio capture has completed before copying the sample and returning.

  • info Indicates the structure in which to store the utterance and set the properties.
  • 0 Success.
  • -1 An error occurred.
int(* set_utterance)(asr_audio_info_t *info, int offset_ms)
Copy an utterance to the specified buffer.

The set_utterance() function copies the last captured audio sample to the buffer referenced by the info parameter, at the offset specified by the offset_ms parameter. The sample size, sample rate, and number of channels must match the properties of the captured sample. If the requested offset results in a buffer overrun, an error is returned. If the audio capture has not completed, an error is returned.

  • info Indicates the structure in which to store the utterance.
  • offset_ms The offset (in milliseconds) of the utterance.
  • 0 Success.
  • EBUSY Capture has not completed.
  • EINVAL The audio properties don't match.
  • ERANGE Buffer overrun.
int(* save_wavefile)(const char *fname)
Save the captured audio sample as a WAV file.

The save_wavefile() copies the captured audio sample as a WAV file with the specified filename.

  • fname The name to use for the WAV file.
  • 0 Success.
  • -1 The file couldn't be opened for writing.
int(* stop)()
Stop the audio capture.

The stop() function forces the audio capturing to stop.

  • 0 Success
  • -1 An error occurred.
int(* close)()
Close the audio module.

The close() function closes the audio module.

  • 0 on success.




This structure defines the interface from io-asr to the audio module. Each audio module's constructor function passes this structure to asra_connect().