API The libao API makes a distinction between drivers and devices. A driver is a set of functions that allow audio to be played on a particular platform (i.e. Solaris, ESD, etc.). A device is a particular output target that uses a driver. For example, on my system, I use the OSS driver to play to the /dev/dsp device. Using the libao API is fairly simple. Your program should go like this: * Include the header into your program. * Call ao_initialize() to initialize the library. * Call ao_get_driver_id() with a string corresponding to the short name of the device (i.e. "oss", "wav", etc.). * Create an option list pointer of type (ao_option_t *) and initialize it to NULL. * Through successive calls to ao_append_option(), add any driver specific options you need. Note that the options take the form of key-value pairs where supported keys are listed in the DRIVER file. * Call ao_open() and save the returned device pointer. * Call ao_play() to output each block of audio. * Call ao_close() to close the device. Note that this will automatically free the memory that was allocated for the device. Do not attempt to free the device pointer yourself * Call ao_shutdown() to close the library. FUNCTIONS Before reading the function descriptions below, you should read through the header file and see the data structures used. --- void ao_initialize(void) Purpose: initialize the library. Parameters: none. --- void ao_shutdown(void) Purpose: shuts down the library. Parameters: none. --- int ao_get_driver_id(const char *short_name) Purpose: Get the id number for a particular driver. Parameters: const char* short_name - The short name of the driver Returns: The driver id number or -1 if the driver does not exist. --- ao_info_t *ao_get_driver_info(int driver_id) Parameters: int driver_id - The number returned from ao_get_driver_id(). Or one of the standard drivers. Purpose: To get the ao_info_t structure that describes this driver. Returns: A pointer to the info structure. Do not modify this structure. --- int ao_append_option(ao_option_t **options, const char *key, const char *value) Purpose: Append an option to a linked list of options. Parameters: ao_option_t **options - Address of a pointer to the head of the option list, which may be NULL. const char* key - The option key const char* value - the setting for this particular option Returns: 1 if the option was appended successfully 0 if the option was not appended (either due to memory allocation failure or incorrect option format) --- void ao_free_options(ao_option_t *options) Purpose: Free all of the memory allocated to an option list, including the key and value strings. Parameters: ao_option_t *options - A pointer to the option list. --- ao_device_t* ao_open(int driver_id, uint_32 bits, uint_32 rate, uint_32 channels, ao_option_t *options) Purpose: To open a particular device for writing. Parameters: int driver_id - ID number for the driver to use with this device uint_32 bits - Bits per audio sample (8 or 16) uint_32 rate - Samples per second (44100, 22050, etc.) uint_32 channels - Audio channels (1 = mono, 2 = stereo) ao_option_t *options - Option list Returns: Pointer to internal data used for this device. Must be used in later calls to ao_play() or ao_close(). NULL is returned if the device cannot be opened. --- void ao_play(ao_device_t *device, void* output_samples, uint_32 num_bytes) Purpose: To ouput some audio data to the device. Parameters: ao_device_t *device - Device pointer void *output_samples - Memory buffer containing audio data uint_32 num_bytes - Number of bytes of audio data in memory buffer --- void ao_close(ao_device_t *device) Purpose: To close the audio device and free device memory. [Do not free device memory yourself!] Parameters ao_device_t *device - Device pointer