[xiph-cvs] cvs commit: ao/doc API DRIVERS USAGE WANTED Makefile.am index.html
Jack Moffitt
jack at xiph.org
Mon Oct 30 23:08:44 PST 2000
jack 00/10/30 23:08:43
Modified: doc Makefile.am
Added: doc API DRIVERS USAGE WANTED
Removed: doc index.html
Log:
documetation???? WHAT!?!
jack.
Revision Changes Path
1.2 +1 -1 ao/doc/Makefile.am
Index: Makefile.am
===================================================================
RCS file: /usr/local/cvsroot/ao/doc/Makefile.am,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Makefile.am 2000/09/03 09:56:05 1.1
+++ Makefile.am 2000/10/31 07:08:41 1.2
@@ -4,6 +4,6 @@
docdir = $(prefix)/doc/$(PACKAGE)-$(VERSION)
-doc_DATA = index.html
+doc_DATA = API USAGE DRIVERS WANTED
EXTRA_DIST = $(doc_DATA)
1.1 ao/doc/API
Index: API
===================================================================
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 <ao/ao.h> 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 option string has the
form "key:value" 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 <ao/ao.h> 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_options(ao_option_t **options, const char *op_str)
Purpose: Append an option to a linked list of options.
Parameters:
ao_option_t **options - A pointer to the linked list pointer.
const char* op_str - The option string. Form "key:value".
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
1.1 ao/doc/DRIVERS
Index: DRIVERS
===================================================================
DEVICE DRIVERS
Below are the short names of the devices that libao supports:
null
----
Null device. This is just a test device. It counts the
number of bytes sent, but does not write them anywhere.
Option keys: None.
oss
---
Open Sound System. This is the audio driver system for
Linux and Free/Net/OpenBSD as well as other UNIX-like systems.
Option keys:
"dsp" - set the dsp device. By default, this is
"/dev/dsp".
irix
----
IRIX audio driver. This was inherited from the original
libao, but has not been tested. Use at your own risk. (Better yet,
fix it! I don't have access to an IRIX system.)
Option keys: None.
olaris
-------
Solaris audio driver. This was also inherited from the
original libao. Same caveats apply.
Option keys: None.
esd
---
ESounD audio driver. This driver by default connects to the ESounD
Daemon on the localhost.
Option keys:
"host" - The hostname where esd is running. This can include
a port number after a colon, as in "whizbang.com:555".
alsa
----
Advanced Linux Sound Architecture. This driver borrows some code from
Jaroslav Kysela's <perex at suse.cz> GPLed aplay that is included with
the alsa-util distribution. It defaults to device 0 on card 0.
Because of the way ALSA reads data, this driver packs sound from
successive calls into a fixed size buffer (defaults to 32kB) and sends
it to the card.
Option keys:
"card" - Sound card number
"dev" - Device number on the sound card
"buf_size" - Override the default buffer size (in bytes)
esd
---
ESounD audio driver. Uses libesd to communicate with the audio
server.
Option keys:
"host" - Hostname where esd is running. By default, this is
the localhost.
wav
---
WAV file output. This produces a wav file from the audio
data you output.
Option keys:
"file" - Sets the output file. By default, this is
"output.wav".
ADDING NEW DRIVERS
[To be written. - Stan]
1.1 ao/doc/USAGE
Index: USAGE
===================================================================
USAGE
Libao is currently a dynamically-linked library. This means if you
want to use it, you have to rewrite your program to use the libao API
and link libao to your programs.
If you are using autoconf and automake, include the ao.m4 project in
your project (acinclude.m4 is the usual place) and call
AM_PATH_AO(minimum-required-version, action-if-found, action-if-not-found)
in your configure.in. Please look at the ogg123 project for an example
of how this works.
If you do not use autoconf, you need to link against libao and use
ao-config to figure out where the libs and headers are on your
machine.
Finally, you need to modify your program to use the libao API.
1.1 ao/doc/WANTED
Index: WANTED
===================================================================
WANTED
* Testers to check out the IRIX and Solaris drivers.
* Win32 driver
* BeOS driver
* Other audio file formats.
--- >8 ----
List archives: http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'cvs-request at xiph.org'
containing only the word 'unsubscribe' in the body. No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.
More information about the commits
mailing list