diff --git a/configure.ac b/configure.ac
index 0e53752..5a14b46 100644
--- a/configure.ac
+++ b/configure.ac
@@ -73,28 +73,14 @@ if test -z "$GCC"; then
PROFILE="-g -p" ;;
esac
else
-
+ DEBUG="-g -Wall -fsigned-char"
+ CFLAGS="-fsigned-char"
+ PROFILE="-g -pg -fsigned-char"
case $host in
- *-*-linux*)
- PLUGIN_LDFLAGS="-export-dynamic -avoid-version"
- DEBUG="-g -Wall -D_REENTRANT -D__NO_MATH_INLINES -fsigned-char"
- CFLAGS="-O20 -ffast-math -D_REENTRANT -fsigned-char"
- PROFILE="-pg -g -O20 -ffast-math -D_REENTRANT -fsigned-char";;
- sparc-sun-*)
- PLUGIN_LDFLAGS="-export-dynamic -avoid-version"
- DEBUG="-g -Wall -D__NO_MATH_INLINES -fsigned-char"
- CFLAGS="-O20 -ffast-math -D__NO_MATH_INLINES -fsigned-char"
- PROFILE="-pg -g -O20 -D__NO_MATH_INLINES -fsigned-char" ;;
*-darwin*)
- PLUGIN_LDFLAGS="-module -avoid-version"
- DEBUG="-g -Wall -D__NO_MATH_INLINES -fsigned-char"
- CFLAGS="-D__NO_MATH_INLINES -fsigned-char"
- PROFILE="-g -pg -D__NO_MATH_INLINES -fsigned-char" ;;
+ PLUGIN_LDFLAGS="-module -avoid-version" ;;
*)
- PLUGIN_LDFLAGS="-export-dynamic -avoid-version"
- DEBUG="-g -Wall -D__NO_MATH_INLINES -fsigned-char"
- CFLAGS="-O20 -D__NO_MATH_INLINES -fsigned-char"
- PROFILE="-O20 -g -pg -D__NO_MATH_INLINES -fsigned-char" ;;
+ PLUGIN_LDFLAGS="-export-dynamic -avoid-version" ;;
esac
fi
CFLAGS="$CFLAGS $cflags_save -DAO_BUILDING_LIBAO"
@@ -166,35 +152,6 @@ esac
AC_DEFINE_UNQUOTED(DLOPEN_FLAG, $DLOPEN_FLAG)
AC_DEFINE_UNQUOTED(SHARED_LIB_EXT, "$SHARED_LIB_EXT")
-dnl ==============================
-dnl Checks for types
-dnl ==============================
-
-AC_CHECK_SIZEOF(short)
-AC_CHECK_SIZEOF(int)
-AC_CHECK_SIZEOF(long)
-
-case 2 in
- $ac_cv_sizeof_short) SIZE16="short";;
- $ac_cv_sizeof_int) SIZE16="int";;
-esac
-
-case 4 in
- $ac_cv_sizeof_short) SIZE32="short";;
- $ac_cv_sizeof_int) SIZE32="int";;
- $ac_cv_sizeof_long) SIZE32="long";;
-esac
-
-if test -z "$SIZE16"; then
- AC_MSG_ERROR(No 16 bit type found on this platform!)
-fi
-if test -z "$SIZE32"; then
- AC_MSG_ERROR(No 32 bit type found on this platform!)
-fi
-
-AC_SUBST(SIZE16)
-AC_SUBST(SIZE32)
-
dnl ======================================
dnl Disable default use of SLP in roar
dnl until such time as SLP doesn't block
@@ -462,11 +419,24 @@ AM_CONDITIONAL(HAVE_PULSE,test "x$have_pulse" = xyes)
dnl Orphaned driver. We'll probably dump it soon.
AM_CONDITIONAL(HAVE_SOLARIS,test "x$have_solaris" = xyes)
+dnl Build documentation
+docs_enabled=yes
+AC_ARG_ENABLE([docs], [AS_HELP_STRING([--disable-docs],
+[skip docs during build]) ], [ docs_enabled=$enableval ], [])
+
+AC_CHECK_PROG([HAS_SPHINX_BUILD], [sphinx-build], [yes])
+if test x${docs_enabled} = xyes; then
+ if test x${HAS_SPHINX_BUILD} = xyes; then
+ build_html=yes
+ fi
+fi
+AM_CONDITIONAL(BUILD_HTML, [test x$build_html = xyes])
+
dnl Plugins get special LDFLAGS
AC_SUBST(PLUGIN_LDFLAGS)
-AC_OUTPUT([Makefile src/Makefile doc/Makefile include/Makefile include/ao/Makefile include/ao/os_types.h src/plugins/Makefile src/plugins/esd/Makefile src/plugins/oss/Makefile src/plugins/alsa/Makefile src/plugins/sun/Makefile src/plugins/irix/Makefile src/plugins/arts/Makefile src/plugins/macosx/Makefile src/plugins/nas/Makefile src/plugins/pulse/Makefile src/plugins/sndio/Makefile src/plugins/roar/Makefile ao.pc])
+AC_OUTPUT([Makefile src/Makefile doc/Makefile include/Makefile include/ao/Makefile src/plugins/Makefile src/plugins/esd/Makefile src/plugins/oss/Makefile src/plugins/alsa/Makefile src/plugins/sun/Makefile src/plugins/irix/Makefile src/plugins/arts/Makefile src/plugins/macosx/Makefile src/plugins/nas/Makefile src/plugins/pulse/Makefile src/plugins/sndio/Makefile src/plugins/roar/Makefile ao.pc])
AS_AC_EXPAND(LIBDIR, ${libdir})
AS_AC_EXPAND(INCLUDEDIR, ${includedir})
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..8c6b163
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,3 @@
+.buildinfo
+.sphinx-cache
+
diff --git a/doc/Makefile.am b/doc/Makefile.am
index ad81252..93adb05 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,46 +1,27 @@
-## Process this with automake to create Makefile.in
-
-AUTOMAKE_OPTIONS = foreign
-
docdir = $(datadir)/doc/$(PACKAGE)-$(VERSION)
+src_files=\
+ build/api.rst \
+ build/plugins.rst \
+ build/config.rst \
+ build/drivers.rst \
+ build/index.rst
+if BUILD_HTML
+html_files= \
+ search.html \
+ config.html \
+ index.html \
+ plugins.html \
+ genindex.html \
+ api.html \
+ drivers.html
+else
+html_files=
+endif
+
+$(html_files) .sphinx-cache: $(src_files)
+ sphinx-build -b html -d .sphinx-cache $(top_srcdir)/doc/build .
-# We list all of these as opposed to using a wildcard so that
-# building outside the source directory works.
-doc_DATA = ao_append_option.html \
- ao_close.html \
- ao_default_driver_id.html \
- ao_device.html \
- ao_driver_id.html \
- ao_driver_info.html \
- ao_driver_info_list.html \
- ao_file_extension.html \
- ao_free_options.html \
- ao_info.html \
- ao_initialize.html \
- ao_is_big_endian.html \
- ao_open_file.html \
- ao_open_live.html \
- ao_option.html \
- ao_play.html \
- ao_plugin_close.html \
- ao_plugin_device_clear.html \
- ao_plugin_device_init.html \
- ao_plugin_driver_info.html \
- ao_plugin_file_extension.html \
- ao_plugin_open.html \
- ao_plugin_play.html \
- ao_plugin_set_option.html \
- ao_plugin_test.html \
- ao_sample_format.html \
- ao_shutdown.html \
- config.html \
- drivers.html \
- index.html \
- libao-api.html \
- overview.html \
- plugin-api.html \
- plugin-overview.html \
- ao_example.c \
- style.css
+doc_DATA=$(html_files) $(wildcard _static/*) $(src_files)
+# distribute pre-built docs
+EXTRA_DIST=$(doc_DATA)
-EXTRA_DIST = $(doc_DATA)
diff --git a/doc/ao_append_global_option.html b/doc/ao_append_global_option.html
deleted file mode 100644
index 682b4f5..0000000
--- a/doc/ao_append_global_option.html
+++ /dev/null
@@ -1,67 +0,0 @@
-
-
-
-libao - function - ao_append_global_option
-
-
-
-
-
-
-
libao documentation
-
libao version 1.2.0 - 201401271
-
-
-
-
ao_append_option
-
-
declared in "ao/ao.h";
-
-
Append a key-value pair to the internal linked list of global
-options obeyed by libao itself, as well as passed to any driver in
-use. The key and value strings are duplicated into newly allocated
-memory, so the calling function retains ownership of the string
-parameters.
-
-
Append a key-value pair to a linked list of options. The key and
-value strings are duplicated into newly allocated memory, so the
-calling function retains ownership of the string parameters.
-
-
Returns the ID number of the default live output driver.
-If the configuration files specify a
-default driver, its ID is returned, otherwise the library tries to
-pick a live output driver that will work on the host platform.
-
-
-
-
-
-
-int ao_default_driver_id();
-
-
-
-
-
-
Return Values
-
-
a non-negative value is the ID number of the default driver.
-
-
-1 indicates failure to find a usable audio output device.
-
-
-
-
Notes
-
If no default device is available, you may still use the null device
-to test your application.
Get a list of the ao_info structures
-for all of the available drivers. ao_driver_info_list() passes back
-the number of drivers through the driver_count pointer.
-
-
Returns the normal file extension associated with a particular
-driver (like "wav" or "au"). This is just an information function to
-allow library users to guess appropriate file names. You can safely
-ignore the recommended extension.
This structure describes the attributes of an output driver.
-
-
-
-
-
-
typedef struct {
- int type; /* live output or file output? */
- char *name; /* full name of driver */
- char *short_name; /* short name of driver */
- char *comment; /* driver comment */
- int preferred_byte_format;
- int priority;
- char **options;
- int option_count;
-} ao_info;
-
-
-
-
-
Relevant Struct Members
-
-
type
-
The output type of the driver:
-
-
AO_TYPE_LIVE - Live output.
-
AO_TYPE_FILE - File output.
-
-
-
name
-
A longer name for the driver which may contain whitespace, but no
-newlines. It is useful for telling users what output driver is in use.
-
short_name
-
A short identifier for the driver. The short name contains only
-alphanumeric characters, and no whitespace. It is used to look up the driver
-ID number using ao_driver_id().
-
preferred_byte_format
-
Specifies the preferred ordering of the sample bytes. Using the driver
-with this byte format usually results in slightly less memory usage and
-slightly less CPU usage because a swap buffer will not be needed.
-See
-ao_sample_format for a list of
-allowed values.
-
-
priority
-
A positive integer ranking how likely it is for this driver to be
-the default. The default driver will be a functioning driver with
-highest priority. See the drivers document
-for more explanation.
-
comment
-
Pointer to a driver comment string (possibly NULL). It may
-contain newlines.
-
options
-
An array of strings which list the option keys accepted by this
-driver.
This function initializes the internal libao data structures and
-loads all of the available plugins. The system and user configuration files are also read at this time
-if available. ao_initialize() must be called in the main thread and
-before any other libao functions can be used.
-
-
More background on initialization in the main thread:
-ao_initialize() must be called in the main thread because several
-sound system interfaces used by libao must be initialized in the main
-thread. One example is the system aRts interface, which stores some
-global state in thread-specific keys that it fails to delete on
-shutdown. If aRts is initialized in a non-main thread that later
-exits, these undeleted keys will cause a segmentation fault.
-
-
-
-
-
-
-void ao_initialize();
-
-
-
-
-
-
Notes
-
-
Do not invoke this function more than once before calling ao_shutdown(). If you want to reload the
-configuration files without restarting your program, first call
-ao_shutdown(), then call ao_initialize() again.
-
-
The ID number of the driver as returned by
-ao_driver_id().
-
filename
-
Name of the file in which to store the audio. The special filename "-" corresponds to stdout.
-
overwrite
-
If non-zero, the file is automatically overwritten. If zero, then a
-preexisting file will cause the function to report a failure.
-
format
-
Pointer to a struct describing the sample format. The caller retains ownership of this structure.
-
options
-
A linked list of options to be passed to the driver or NULL if no options
-are needed. Unsupported options are ignored.
-
-
-
Return Values
-
-
-non-NULL pointer inicates success. This pointer must be passed in subsequent
-calls to ao_play() and
-ao_close().
-
-
NULL indicates failure. errno will contain the specific cause of the failure:
-
-
AO_ENODRIVER - No driver corresponds to driver_id.
-
AO_ENOTFILE - This driver is not a file output driver.
-
AO_EBADOPTION - A valid option key has an invalid value.
-
AO_EOPENFILE - Cannot open the file.
-
AO_EFILEEXISTS - The file already exists.
-(Only if overwrite == 0)
-
AO_EFAIL - Any other cause of failure.
-
-
-
-
-
-
Notes
-
-
Live output drivers cannot be used with this function. Use ao_open_live() instead. Some file
-formats (notably .WAV) cannot be correctly written to non-seekable
-files (like stdout).
-
-
When passed to ao_open_file(), the
-byte_format member of an ao_sample_format struct does not
-specify the byte format that will be used in the file output,
-just the input sample format.
-
-
Play a block of audio data to an open device. Samples are interleaved by
-channels (Time 1, Channel 1; Time 1, Channel 2; Time 2, Channel 1;
-etc.) in the memory buffer.
-
-
Initialize the private device data structures. Memory should be
-allocated, and default values set if necessary, but devices should not
-be opened until ao_plugin_open() is
-called.
-
-
Drivers that wish to support automatic surround channel mapping should set device->output_matrix_order to one of:
-
-
-
AO_OUTPUT_MATRIX_FIXED - The audio driver outputs a fixed channel
-order that is always the same for a given number of channels and can't
-be changed. One example is ALSA where to play to the side right
-speaker, it is necessary to open eight channels and write to side
-right as channel eight, even if the other seven channels are unused.
-
-
AO_OUTPUT_MATRIX_COLLAPSIBLE - The audio driver outputs a fixed
-channel order that is always the same, but unused channels are not
-sent. In such a driver with the channel order 'L,R,C,LFE,BL,BR', we
-can write to the two rear speakers without opening six channels but
-the rear speakers must still be in the order 'BL,BR'. Such drivers
-usually use a bitmap to represent the channels present in the output.
-Examples are wav, wmm and macosx.
-
-
AO_OUTPUT_MATRIX_PERMUTABLE - Channels may be arranged in any
-order. An example of such a driver is pulse.
-
-
-In addition, a driver may set device->output_matrix to the
-list of possible output channels in order. Note that even
-AO_OUTPUT_MATRIX_PERMUTABLE drivers usually have a fixed numbering
-scheme for channels even if the channels may be sent in any order. A
-driver that is unable to set an output matrix without inspecting the
-input sample format (for example, the roar driver), may set
-device->output_matrix_order to
-AO_OUTPUT_MATRIX_FIXED and delay channel mapping
-initialization until ao_plugin_open().
-
-
Pointer to pre-allocated device structure. The driver should
-store the address of its private memory in device->internal.
-
-
-
Return Values
-
-
1 indicates success.
-
-
0 indicates failure, probably due to memory allocation problems.
-ao_plugin_device_clear() should be
-called to ensure the deallocate of all private data structures.
Returns the normal file extension associated with this driver (like
-"wav" or "au"). This is an optional function. Live audio
-plugins do not need to implement this function.
-
-
-
-
-
-
-char *ao_plugin_file_extension(int driver_id);
-
-
-
-
-
-
Return Values
-
-
pointer to string containing suggested file extension.
-
-
NULL if this driver has no file extension associated with it.
-Live audio plugins must always return NULL if they do implement this
-function.
Open the device for playback. All of the device options will have
-already been set by previous calls to ao_plugin_set_option(). If this is a
-file output driver, the file itself will have be already opened and a
-pointer to a FILE structure stored in device->file.
-
-
If the plugin wishes to support automatic channel mapping, but it
-was not possible to set device->output_matrix in ao_plugin_device_init(), the
-plugin should now set device->inter_matrix to the channel
-ordering that will be expected for buffers submitted to ao_plugin_play().
-
-
Plugins should use device->output_channels to determine
-the number of output channels to configure, not
-format->channels. device->output_channels is the
-number of channels libao will be submitting upon each call to ao_plugin_play(). A plugin may alter
-the value of device->output_channels to demand a different
-number of channels if necessary (such as if a plugin is manufacturing
-a channel mapping manually).
-
-
Pointer to pre-allocated device structure. The plugin should
-set its desired byte format in device->driver_byte_format.
-
format
-
-
Output device sample format. format->byte_format should
-be ignored as it is relevant only to the library core.
-format->channels is relevant only if a plugin is constructing
-a channel mapping manually; otherwise device->output should
-be used as it is the actual number of channels that will be sent to ao_plugin_play().
-
-
-
-
Return Values
-
-
1 indicates success.
-
-
0 indicates failure to open the device.
-ao_plugin_device_clear() should be
-called to ensure the deallocate of all private data structures.
Set a new option key-value pair for a device. This will only be
-called after ao_plugin_device_init() is called.
-Unrecognized option keys are silently ignored, but invalid option
-values will cause the function to return a failing error code.
-
-
Test if this driver could be used with only the default options. This
-function is used by the library core to determine if a driver is a possible
-candidate for the default driver. No devices are left open after this
-function returns.
-
-
-
-
-
-
-int ao_plugin_test();
-
-
-
-
-
-
Return Values
-
-
1 indicates that the driver can be successfully opened with no
-options.
-
-
0 indicates that the driver cannot be opened with no options.
This structure describes the format of audio samples.
-
-
-
-
-
-
typedef struct {
- int bits; /* bits per sample */
- int rate; /* samples per second (in a single channel) */
- int channels; /* number of audio channels */
- int byte_format; /* Byte ordering in sample, see constants below */
- char *matrix; /* channel input matrix */
-} ao_sample_format;
-
-
-
-
-
Relevant Struct Members
-
-
byte_format
-
Specifies the ordering of the sample bytes. The value of this member is ignored when samples have only 8 bits. Use the following constants:
-
-
AO_FMT_LITTLE - Samples are in little-endian order.
-
AO_FMT_BIG - Samples are in big-endian order.
-
AO_FMT_NATIVE - Samples are in the native ordering of the computer.
-
-
-
matrix
Specifies the mapping of input channels to
-intended speaker/ouput location (or NULL to specify no mapping). The matrix is specified as a comma
-seperated list of channel locations equal to the number and in the
-order of the input channels. The channel mnemonics are as follows:
-
-
L - Left speaker, located forward and to the left of the listener.
-
R - Right speaker, located forward and to the right of the listener.
-
C - Center speaker, located directly forward of the listener between the Left and Right speakers.
-
M - Monophonic, a virtual speaker for single-channel output.
-
CL - Left of Center speaker (used in some Widescreen formats), located forward of the listener between the Center and Left speakers. Alternatively referred to as 'Left Center'.
-
CR - Right of Center speaker (used in some Widescreen formats), located forward of the listener between the Center and Right speakers. Alternatively referred to as 'Right Center'.
-
BL - Back Left speaker, located behind and to the left of the listener. Alternatively called 'Left Surround' (primarily by Apple) or 'Surround Rear Left' (primarily by Dolby).
-
BR - Back Right speaker, located behind and to the right of the listener. Alternatively called 'Right Surround' (primarily by Apple) or 'Surround Rear Right' (primarily by Dolby).
-
BC - Back Center speaker, located directly behind the listener. Alternatively called 'Center Surround' (primarily by Apple) or 'Surround Rear Center' (primarily by Dolby).
-
SL - Side Left speaker, located directly to the listener's left side. The Side Left speaker is also referred to as 'Left Surround Direct' (primarily by Apple) or 'Surround Left' (primarily by Dolby)
-
SR - Side Right speaker, located directly to the listener's right side. The Side Right speaker is also referred to as 'Right Surround Direct' (primarily by Apple) or 'Surround Right' (primarily by Dolby)
-
LFE - Low Frequency Effect (subwoofer) channel. This is channel is usually lowpassed and meant only for bass, though in some recent formats it is a discrete, full-range channel. Microsoft calls this the 'Low Frequency' channel.
-
A1, A2, A3, A4 - 'auxiliary' channels, not mapped to a location. Intended for driver-specific use.
-
X - Unused/Invalid channel, to be dropped in the driver and not output to any speaker.
-
-
-
Note that the 'surround' speakers referred to in other systems
-can be either the side or back speakers depending on vendor. For
-example, Apple calls the back speakers 'surround' and the side
-speakers 'direct surround'. Dolby calls the back speakers 'surround
-rear' and the side speakers 'surround', resulting in a direct naming
-conflict. For this reason, libao explicitly refers to speakers as
-'back' and 'side' rather than 'surround'.
-
-
Common examples of channel orderings:
-
-
"L,R" - Stereo ordering in virtually all file formats
-
"L,R,BL,BR" - Quadraphonic ordering for most file formats
-
"L,R,C,LFE,BR,BL" - channel order of a 5.1 WAV or FLAC file
-
"L,R,C,LFE,BR,BL,SL,SR" - channel order of a 7.1 WAV or FLAC file
-
"L,C,R,BR,BL,LFE" - channel order of a six channel (5.1) Vorbis I file
-
"L,C,R,BR,BL,SL,SR,LFE" - channel order of an eight channel (7.1) Vorbis file
-
"L,CL,C,R,RC,BC" - channel order of a six channel AIFF[-C] file
-
-
-
Channel mappings for most formats are usually not tied to a single
-channel matrix (there are a few exceptions like Vorbis I, where the
-number of channels always maps to a specific order); the above
-examples cannot be blindly applied to a given file type and number of
-channels. The mapping must usually be read or intuited from the input.
-
-
This function unloads all of the plugins and deallocates any
-internal data structures the library has created. It should be called
-prior to program exit.
-
-
-
-
-
-
-void ao_shutdown();
-
-
-
-
-
-
Notes
-
-
Do not invoke this function before closing all of the open devices.
-You may call ao_initialize() after
-calling ao_shutdown().
-
-
-
-
-
-
diff --git a/doc/build/api.rst b/doc/build/api.rst
new file mode 100644
index 0000000..6375890
--- /dev/null
+++ b/doc/build/api.rst
@@ -0,0 +1,482 @@
+API reference
+=============
+
+Libao is designed to make it easy to do simple audio output using
+various audio devices and libraries. For this reason, complex audio
+control features are missing and will probably never be added.
+However, if you just want to be able to open whatever audio device is
+available and play sound, libao should be just fine.
+
+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. In addition, libao
+distinguishes between *live* output drivers, which write audio to
+playback devices (sound cards, etc.), and *file* output drivers,
+which write audio to disk in a particular format.
+
+To use libao in your program, you need to follow these steps:
+
+- Include the :file:`ao/ao.h` header into your program.
+- Call :c:func:`ao_initialize` to initialize the library. This loads the
+ plugins from disk, reads the libao :doc:`configuration
+ files `, and identifies an appropriate default output driver if none is
+ specified in the configuration files.
+- Call :c:func:`ao_default_driver_id` to get the
+ ID number of the default output driver. This may not be successful if no
+ audio hardware is available, it is in use, or is not in the "standard"
+ configuration. If you want to specify a particular output driver, you may
+ call :c:func:`ao_driver_id` with a string corresponding to the short name of
+ the device (i.e. "oss", "wav", etc.) instead.
+- If you are using the default device, no extra options are needed.
+ However, if you wish to to pass special options to the driver, you will need
+ to:
+
+ - Create an option list pointer of type :c:type:`ao_option *` and
+ initialize it to :c:macro:`NULL`.
+ - Through successive calls to :c:func:`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 :doc:`driver
+ documentation `.
+- Call :c:func:`ao_open_live` and save the returned device pointer. If you are
+ using a file output driver, you will need to call :c:func:`ao_open_file`
+ instead.
+- Call :c:func:`ao_play` to output each block of audio.
+- Call :c:func:`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 :c:func:`ao_shutdown` to close the library.
+
+Setup/Teardown
+--------------
+
+.. c:function:: void ao_initialize()
+
+ This function initializes the internal libao data structures and loads all
+ of the available plugins. The system and user :doc:`configuration files
+ ` are also read at this time if available.
+ :c:func:`ao\_initialize` must be called in the main thread and before any
+ other libao functions can be used.
+
+ More background on initialization in the main thread:
+ :c:func:`ao\_initialize` must be called in the main thread because several
+ sound system interfaces used by libao must be initialized in the main
+ thread. One example is the system aRts interface, which stores some global
+ state in thread-specific keys that it fails to delete on shutdown. If aRts
+ is initialized in a non-main thread that later exits, these undeleted keys
+ will cause a segmentation fault.
+
+ .. note::
+ Do not invoke this function more than once before calling
+ :c:func:`ao\_shutdown`. If you want to reload the configuration files
+ without restarting your program, first call :c:func:`ao\_shutdown`,
+ then call :c:func:`ao\_initialize` again.
+
+.. c:function:: void ao_shutdown()
+
+ This function unloads all of the plugins and deallocates any internal data
+ structures the library has created. It should be called prior to program exit.
+
+ .. note::
+
+ Do not invoke this function before closing all of the open devices.
+ You may call :c:func:`ao\_initialize` after calling
+ :c:func:`ao\_shutdown`.
+
+
+Device Setup/Playback/Teardown
+------------------------------
+
+.. c:function:: int ao_append_global_option(const char *key, const char *value)
+
+ Append a key-value pair to the internal linked list of global
+ options obeyed by libao itself, as well as passed to any driver in
+ use. The key and value strings are duplicated into newly allocated
+ memory, so the calling function retains ownership of the string
+ parameters.
+
+ :param key: A string holding the option key.
+ :param value: A string holding the option value.
+ :return:
+ - 1 indicates success.
+ - 0 indicates memory allocation failure.
+
+.. c:function:: int ao_append_option(ao_option **options, const char *key, const char *value)
+
+ Append a key-value pair to a linked list of options. The key and
+ value strings are duplicated into newly allocated memory, so the
+ calling function retains ownership of the string parameters.
+
+ :param options: Address of the pointer to the head of the option list. For an empty list *options will be NULL.
+ :param key: A string holding the option key.
+ :param value: A string holding the option value.
+ :return:
+ - 1 indicates success.
+ - 0 indicates memory allocation failure.
+
+.. c:function:: int ao_close(ao_device *device)
+
+ Closes the audio device and frees the memory allocated by the
+ device structure.
+
+ :param device:
+ Pointer to device structure as returned by :c:func:`ao_open_live` or
+ :c:func:`ao_open_file`
+ :return:
+ - 1 indicates remaining data written correctly and device closed.
+ - 0 indicates an error while the device was being closed. If this
+ device was writing to a file, the file may be corrupted.
+
+.. c:function:: void ao_free_options(ao_option *options)
+
+ Free all of the memory allocated to an option list, including the key and
+ value strings.
+
+ :param options:
+ Pointer to the head of the option list. If NULL is passed, the function
+ does nothing.
+
+.. c:function:: ao_device* ao_open_file(int driver_id, const char *filename, int overwrite, ao_sample_format *format, ao_option *options)
+
+ Open a file for audio output. The file format is determined by the audio
+ driver used.
+
+ :param driver\_id:
+ The ID number of the driver as returned by :c:func:`ao\_driver\_id`.
+ :param filename:
+ Name of the file in which to store the audio. The special filename
+ "-" corresponds to ``stdout``.
+ :param overwrite:
+ If non-zero, the file is automatically overwritten. If zero, then a
+ preexisting file will cause the function to report a failure.
+ :param format:
+ Pointer to a struct describing the sample format. The caller retains
+ ownership of this structure.
+ :param options:
+ A linked list of options to be passed to the driver or NULL if no
+ options are needed. Unsupported options are ignored.
+
+ :return:
+ non-NULL pointer inicates success. This pointer must be passed in
+ subsequent calls to :c:func:`ao\_play` and :c:func:`ao\_close`.
+
+ NULL indicates failure. ``errno`` will contain the specific cause of
+ the failure:
+
+ - AO\_ENODRIVER - No driver corresponds to ``driver_id``.
+ - AO\_ENOTFILE - This driver is not a file output driver.
+ - AO\_EBADOPTION - A valid option key has an invalid value.
+ - AO\_EOPENFILE - Cannot open the file.
+ - AO\_EFILEEXISTS - The file already exists. (Only if
+ ``overwrite == 0``)
+ - AO\_EFAIL - Any other cause of failure.
+
+ .. note::
+ Live output drivers cannot be used with this function. Use
+ :c:func:`ao\_open\_live` instead. Some file formats (notably .WAV)
+ cannot be correctly written to non-seekable files (like ``stdout``).
+
+ When passed to :c:func:`ao\_open\_file`,
+ :c:type:`ao_sample_format.byte_format` does not specify the byte
+ format that will be used in the file *output*, just the input sample
+ format.
+
+
+.. c:function:: ao_device* ao_open_live(int driver_id, ao_sample_format *format, ao_option *options)
+
+ Open a live playback audio device for output.
+
+ :param driver\_id:
+ The ID number of the driver as returned by either
+ :c:func:`ao\_driver\_id` or :c:func:`ao\_default\_driver\_id`.
+ :param format:
+ Pointer to a struct describing the sample format. The caller retains
+ ownership of this structure.
+ :param options:
+ A linked list of options to be passed to the driver or NULL if no
+ options are needed. Unsupported options are ignored.
+ :return:
+ non-NULL pointer inicates success. This pointer must be passed in
+ subsequent calls to :c:func:`ao\_play` and :c:func:`ao\_close`.
+
+ NULL indicates failure. ``errno`` will contain the specific cause of
+ the failure:
+
+ - AO\_ENODRIVER - No driver corresponds to ``driver_id``.
+ - AO\_ENOTLIVE - This driver is not a live output device.
+ - AO\_EBADOPTION - A valid option key has an invalid value.
+ - AO\_EOPENDEVICE - Cannot open the device (for example, if
+ /dev/dsp cannot be opened for writing).
+ - AO\_EFAIL - Any other cause of failure.
+
+ .. note::
+ File output drivers cannot be used with this function. Use
+ :c:func:`ao\_open\_file` instead.
+
+.. c:function:: int ao_play(ao_device *device, char *output_samples, uint32_t num_bytes)
+
+ Play a block of audio data to an open device. Samples are interleaved by
+ channels (Time 1, Channel 1; Time 1, Channel 2; Time 2, Channel 1; etc.) in
+ the memory buffer.
+
+ :param device:
+ Pointer to device structure as returned by :c:func:`ao\_open\_live` or
+ :c:func:`ao\_open\_file`
+ :param output\_samples:
+ Memory buffer containing audio data.
+ :param num\_bytes:
+ Number of bytes of audio data in the memory buffer.
+ :return: non-zero value indicates success.
+ 0 indicates failure. The device should be closed.
+
+Driver Information
+------------------
+
+.. c:function:: int ao_default_driver_id()
+
+ Returns the ID number of the default live output driver. If the
+ :doc:`configuration files ` specify a default driver, its ID is
+ returned, otherwise the library tries to pick a live output driver that
+ will work on the host platform.
+
+ :return:
+ - a non-negative value is the ID number of the default driver.
+ - -1 indicates failure to find a usable audio output device.
+
+ .. note::
+ If no default device is available, you may still use the null device
+ to test your application.
+
+.. c:function:: int ao_driver_id(char *short_name)
+
+ Looks up the ID number for a driver based upon its short name. The ID
+ number is need to open the driver or get info on it.
+
+ :param short_name:
+ The short name of the driver. See the :doc:`list of drivers `
+ for valid short names.
+ :return:
+ - a non-negative value is the ID number of the driver.
+ - -1 indicates failure. No driver by that name exists.
+
+.. c:function:: ao_info* ao_driver_info(int driver_id)
+
+ Get information about a particular driver.
+
+ :param driver\_id: The ID number of the driver as returned by either
+ :c:func:`ao\_driver\_id` or :c:func:`ao\_default\_driver\_id`.
+ :return: non-NULL pointer indicates success. It points to a static info
+ structure that should not be modified under any circumstances.
+ NULL indicates failure because ``driver_id`` does not correspond to
+ an actual driver
+
+.. c:function:: ao_info** ao_driver_info_list(int *driver_count)
+
+ Get a list of the :c:type:`ao\_info` structures for all of the
+ available drivers. :c:func:`ao\_driver\_info\_list` passes back the number
+ of drivers through the ``driver_count`` pointer.
+
+ :param driver\_count: Pointer to an integer that will contain the number of
+ drivers.
+ :return:
+ An array of driver info structures with ``*driver_count`` elements.
+
+
+.. c:function:: const char* ao_file_extension(int driver_id)
+
+ Returns the normal file extension associated with a particular driver (like
+ "wav" or "au"). This is just an information function to allow library users
+ to guess appropriate file names. You can safely ignore the recommended
+ extension.
+
+ :param driver\_id:
+ The ID number of the driver as returned by either
+ :c:func:`ao\_driver\_id` or :c:func:`ao\_default\_driver\_id`.
+ :return:
+ pointer to string containing suggested file extension. NULL if this
+ driver has no file extension associated with it or if this driver does
+ not exist.
+
+Miscellaneous
+-------------
+
+.. c:function:: int ao_is_big_endian(void)
+
+ Test if this computer uses big-endian byte ordering. Provided as a
+ convenience function.
+
+ :return:
+ 1 indicates that this platform using big-endian byte ordering.
+ 0 indicates that this computer uses little-endian byte ordering.
+
+Data structures
+---------------
+
+.. c:type:: ao_option
+
+ A linked list structure to hold option key/value pairs as standard
+ null-terminated C strings. It is used by :c:func:`ao_open_live` and
+ :c:func:`ao_open_file`.
+
+ .. c:member:: char *key
+ .. c:member:: char *value
+ .. c:member:: struct ao_option *next
+
+ Pointer to the next option in the list. Set to :c:macro:`NULL` to mark
+ the end of the list.
+
+.. c:type:: ao_device
+
+ This structure holds all of the data for an open device.
+
+ .. versionchanged:: 0.9.0
+
+ The ao_device structure is opaque now.
+
+.. c:type:: ao_sample_format
+
+ This structure describes the format of audio samples.
+
+ .. c:member:: int bits
+ .. c:member:: int rate
+ .. c:member:: int channels
+ .. c:member:: int byte_format
+
+ Specifies the ordering of the sample bytes. The value of this member
+ is ignored when samples have only 8 bits. Use the following
+ constants:
+
+ - AO\_FMT\_LITTLE - Samples are in little-endian order.
+ - AO\_FMT\_BIG - Samples are in big-endian order.
+ - AO\_FMT\_NATIVE - Samples are in the native ordering of the
+ computer.
+
+ .. c:member:: char *matrix
+
+ .. versionadded:: 0.9.0
+
+ Specifies the mapping of input channels to intended speaker/ouput
+ location (or NULL to specify no mapping). The matrix is specified as
+ a comma seperated list of channel locations equal to the number and
+ in the order of the input channels. The channel mnemonics are as
+ follows:
+
+ - L - Left speaker, located forward and to the left of the
+ listener.
+ - R - Right speaker, located forward and to the right of the
+ listener.
+ - C - Center speaker, located directly forward of the listener
+ between the Left and Right speakers.
+ - M - Monophonic, a virtual speaker for single-channel output.
+ - CL - Left of Center speaker (used in some Widescreen formats),
+ located forward of the listener between the Center and Left
+ speakers. Alternatively referred to as 'Left Center'.
+ - CR - Right of Center speaker (used in some Widescreen formats),
+ located forward of the listener between the Center and Right
+ speakers. Alternatively referred to as 'Right Center'.
+ - BL - Back Left speaker, located behind and to the left of the
+ listener. Alternatively called 'Left Surround' (primarily by
+ Apple) or 'Surround Rear Left' (primarily by Dolby).
+ - BR - Back Right speaker, located behind and to the right of the
+ listener. Alternatively called 'Right Surround' (primarily by
+ Apple) or 'Surround Rear Right' (primarily by Dolby).
+ - BC - Back Center speaker, located directly behind the listener.
+ Alternatively called 'Center Surround' (primarily by Apple) or
+ 'Surround Rear Center' (primarily by Dolby).
+ - SL - Side Left speaker, located directly to the listener's left
+ side. The Side Left speaker is also referred to as 'Left Surround
+ Direct' (primarily by Apple) or 'Surround Left' (primarily by
+ Dolby)
+ - SR - Side Right speaker, located directly to the listener's right
+ side. The Side Right speaker is also referred to as 'Right
+ Surround Direct' (primarily by Apple) or 'Surround Right'
+ (primarily by Dolby)
+ - LFE - Low Frequency Effect (subwoofer) channel. This is channel
+ is usually lowpassed and meant only for bass, though in some
+ recent formats it is a discrete, full-range channel. Microsoft
+ calls this the 'Low Frequency' channel.
+ - A1, A2, A3, A4 - 'auxiliary' channels, not mapped to a location.
+ Intended for driver-specific use.
+ - X - Unused/Invalid channel, to be dropped in the driver and not
+ output to any speaker.
+
+ .. note::
+ Note that the 'surround' speakers referred to in other systems can
+ be either the side or back speakers depending on vendor. For
+ example, Apple calls the back speakers 'surround' and the side
+ speakers 'direct surround'. Dolby calls the back speakers 'surround
+ rear' and the side speakers 'surround', resulting in a direct naming
+ conflict. For this reason, libao explicitly refers to speakers as
+ 'back' and 'side' rather than 'surround'.
+
+ Common examples of channel orderings:
+
+ - "L,R" - Stereo ordering in virtually all file formats
+ - "L,R,BL,BR" - Quadraphonic ordering for most file formats
+ - "L,R,C,LFE,BR,BL" - channel order of a 5.1 WAV or FLAC file
+ - "L,R,C,LFE,BR,BL,SL,SR" - channel order of a 7.1 WAV or FLAC file
+ - "L,C,R,BR,BL,LFE" - channel order of a six channel (5.1) Vorbis I
+ file
+ - "L,C,R,BR,BL,SL,SR,LFE" - channel order of an eight channel (7.1)
+ Vorbis file
+ - "L,CL,C,R,RC,BC" - channel order of a six channel AIFF[-C] file
+
+ Channel mappings for most formats are usually not tied to a single
+ channel matrix (there are a few exceptions like Vorbis I, where the
+ number of channels always maps to a specific order); the above
+ examples cannot be blindly applied to a given file type and number
+ of channels. The mapping must usually be read or intuited from the
+ input.
+
+.. c:type:: ao_info
+
+ This structure describes the attributes of an output driver.
+
+ .. c:member:: int type
+
+ The output type of the driver:
+
+ - AO\_TYPE\_LIVE - Live output.
+ - AO\_TYPE\_FILE - File output.
+
+ .. c:member:: char *name
+
+ A longer name for the driver which may contain whitespace, but no
+ newlines. It is useful for telling users what output driver is in
+ use.
+
+ .. c:member:: char *short\_name
+
+ A short identifier for the driver. The short name contains only
+ alphanumeric characters, and no whitespace. It is used to look up
+ the driver ID number using :c:func:`ao\_driver\_id`.
+
+ .. c:member:: int preferred\_byte\_format
+
+ Specifies the preferred ordering of the sample bytes. Using the
+ driver with this byte format usually results in slightly less memory
+ usage and slightly less CPU usage because a swap buffer will not be
+ needed. See :c:func:`ao\_sample\_format` for a list of allowed values.
+
+ .. c:member:: int priority
+
+ A positive integer ranking how likely it is for this driver to be
+ the default. The default driver will be a functioning driver with
+ highest priority. See the :doc:`drivers document ` for
+ more explanation.
+
+ .. c:member:: char *comment
+
+ Pointer to a driver comment string (possibly :c:macro:`NULL`). It may
+ contain newlines.
+
+ .. c:member:: char **options
+
+ An array of strings which list the option keys accepted by this
+ driver.
+
+ .. c:member:: int option\_count
+
+ Number of strings in :c:type:`ao_info.options` array.
+
+
diff --git a/doc/build/conf.py b/doc/build/conf.py
new file mode 100644
index 0000000..5885401
--- /dev/null
+++ b/doc/build/conf.py
@@ -0,0 +1,284 @@
+# -*- coding: utf-8 -*-
+#
+# libao documentation build configuration file, created by
+# sphinx-quickstart on Sun Jan 17 19:09:57 2016.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+import shlex
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'libao'
+copyright = u'2016, libao contributors'
+author = u'libao contributors'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.2'
+# The full version, including alpha/beta/rc tags.
+release = '1.2.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinx_rtd_theme'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# " v documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+html_show_sourcelink = False
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+html_show_copyright = False
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
+# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
+#html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# Now only 'ja' uses this config value
+#html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'libaodoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+
+# Latex figure (float) alignment
+#'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+# author, documentclass [howto, manual, or own class]).
+latex_documents = [
+ (master_doc, 'libao.tex', u'libao Documentation',
+ u'libao contributors', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ (master_doc, 'libao', u'libao Documentation',
+ [author], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+# dir menu entry, description, category)
+texinfo_documents = [
+ (master_doc, 'libao', u'libao Documentation',
+ author, 'libao', 'One line description of project.',
+ 'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
diff --git a/doc/build/config.rst b/doc/build/config.rst
new file mode 100644
index 0000000..9d2fdfb
--- /dev/null
+++ b/doc/build/config.rst
@@ -0,0 +1,49 @@
+Configuration Files
+===================
+
+When libao is :c:func:`initialized `, it reads two configuration
+files: the system-wide configuration in :file:`/etc/libao.conf` and the user
+configuration in :file:`~/.libao`. Neither file needs to be present on the
+system for libao to load. If both are present, the system configuration file is
+read first, followed by the user configuration file. Options set in the user
+configuration will take precedence.
+
+Options are specified in these files in the form:
+
+::
+
+ option=value
+
+There can be no extra spaces anywhere on the line. Comment lines begin
+with a ``#`` symbol.
+
+AO Options
+----------
+
+*default\_driver*
+ Set this equal to the short name of the driver you want the system
+ to use by default. If this is not specified in any of the
+ configuration files, the library will try to guess an appropriate
+ driver to use.
+*debug* (Value optional/ignored)
+ Sets all the drivers as well as AO itself into debugging output
+ mode. Unlike passing the debug option to a driver, ``debug`` will
+ also print debugging information from driver loading and testing.
+*quiet* (Value optional/ignored)
+ Sets all the drivers as well as AO itself into silent mode. Errors
+ will return only error codes; neither ao nor the drivers will print
+ any output whatsoever to stderr.
+*verbose* (Value optional/ignored)
+ Sets all the drivers as well as AO itself into verbose mode.
+
+Driver Options
+--------------
+
+:doc:`Driver options ` may be set in the configuration files using
+``option=value`` pairs, just as they would be set by passing :c:func:`options
+` to :c:func:`ao\_open\_live` or :c:func:`ao\_open\_file`. Options
+passed to :c:func:`ao\_open\_live` or :c:func:`ao\_open\_file` take precedence
+over options specified in a configuration file. Options specified in a
+configuration file will be passed to whatever driver is eventually opened; they
+cannot be set specific to a single driver.
+
diff --git a/doc/build/drivers.rst b/doc/build/drivers.rst
new file mode 100644
index 0000000..7446e30
--- /dev/null
+++ b/doc/build/drivers.rst
@@ -0,0 +1,328 @@
+Drivers
+=======
+
+Libao supports both *live* output drivers and *file* output drivers.
+Live output drivers send audio data to sound cards and sound daemons.
+File output drivers write audio to disk using a particular file format
+(such as WAV, AU, etc.). You must invoke the ao\_open\_????() function
+that corresponds to the type of driver you are using, but otherwise live
+and file drivers are treated identically in libao.
+
+Driver options may be passed to the drivers via the ``*options``
+argument to :c:func:`ao\_open\_live` and
+:c:func:`ao\_open\_file`, or they may be set in the
+:doc:`configuration file ` as ``name=value`` pairs.
+
+Options Understood by All Drivers
+---------------------------------
+
+debug
+ (value not required) Requests driver print detailed
+ debugging information.
+matrix
+ Set an output channel mapping similar to the use of the
+ *matrix* field in :c:type:`ao\_sample\_format`. The
+ specified matrix overrides the backend's native channel
+ ordering/numbering. The channel numbering used by the driver does not
+ necessarily reflect the physical ordering; for example, the fourth
+ PulseAudio channel is always 'Center' by default whether the channel
+ physically exists or not.
+quiet
+ (value not required) Requests the driver print no output
+ whatsoever, even in the event of error.
+verbose
+ (value not required) Requests that the driver print more
+ detailed information concerning normal operation.
+
+Standard Driver Options
+-----------------------
+
+These are options that have the same use in each driver, but may not be
+supported by all drivers (due to the option being meaningless or
+unimplemented for a given audio backend).
+
+- "id" - Request a specific playback device/sink/output by number. In
+ most audio backends, this will correspond to a specific output
+ device, but for all devices, this means 'give me the Nth output'.
+- "dev" - Request a specific playback device/sink/output by name. This
+ name will be in a format determined by the specific driver backend
+ (eg, the first hardware device in ALSA format would be 'hw:0', and
+ for OSS it would be '/dev/dsp').
+- "server" - Daemon-based sound subsystems often support connecting to
+ non-default local or remote servers. The "server" option allows
+ specifying the connection for a given driver in a format specific to
+ that system.
+- "client\_name" - specify a descriptive name for the application; this
+ is often used by sound backends to display status information about
+ which applications are currently making use of playback.
+
+Live Output Drivers
+-------------------
+
+aixs
+~~~~
+
+IBM AIX sound driver. According to the author, "tested on AIX 5.1 with
+the Crystal chipsets only (found as internal audio in the 7043-140 and
+on the MCA adapter DFE5 (7-6)), but it should work with other AIX
+releases and the ACPA also."
+
+**Option keys:**
+
+- "dev" - (see 'Standard Driver Options' above). By default, the driver
+ tries "/dev/baud0/1" (device for MCA machines with the Crystal
+ chipset). Other possible devices are "/dev/paud0/1" for PCI machines
+ with the Crystal chipset, and "/dev/acpa0/1" for MCA machines with
+ the ACPA.
+- "id" - (see 'Standard Driver Options' above).
+
+alsa
+~~~~
+
+Advanced Linux Sound Architecture (API versions 0.9.x/1.x.x; earlier API
+versions are now deprecated).
+
+**Option keys:**
+
+- "buffer\_time" - Override the default hardware buffer size (in
+ milliseconds).
+- "dev" - (see 'Standard Driver Options' above). ALSA device label to
+ use. Examples include "hw:0" for the first soundcard and "hw:1" for
+ the second. The alsa driver normally chooses one of "surround71",
+ "surround51", "surround40", "front", or "default" automatically
+ depending on number of output channels.
+- "id" - (see 'Standard Driver Options' above).
+- "period\_time" - Override the default hardware period size (in
+ microseconds).
+- "use\_mmap" - set to "yes" or "no" to override the compiled-in
+ default to use or not use mmap device access. In the past, some buggy
+ alsa drivers have behaved better when not using mmap access at the
+ penalty of slightly higher CPU usage.
+
+arts
+~~~~
+
+aRts Sound Daemon live output driver.
+
+**Option keys:**
+
+- "multi" - set to "yes" to allow opening the aRts playback device for
+ multiply concurrent playback. Although the driver works properly in
+ multi mode, it is known to occasionally crash the aRts server itself.
+ Default behavior is "no".
+
+esd
+~~~
+
+ESounD audio driver. Although declining in poularity, this sound daemon
+is still used on some Linux systems. It permits multiple programs to
+play sound simultaneously and sound to be sent to networked computers.
+
+**Option keys:**
+
+- "host" - Deprecated synonym for 'server' below.
+- "server" - (see 'Standard Driver Options' above). The hostname where
+ esd is running. By default sound is played on the local host. A port
+ number can be specified after a colon, as in "whizbang.com:555".
+- "client\_name" - descriptive name for this client (eg, the
+ application name).
+
+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.)
+
+macosx
+~~~~~~
+
+MacOS X AUHAL live output driver. This driver supports MacOS X 10.5 and
+later (10.4 and earlier uses an earlier, incompatable interface).
+
+**Option keys:**
+
+- "buffer\_time" - Set the hardware buffer size to the equivalent of
+ value in milliseconds.
+- "dev" - specify the audio device to use by name (eg, 'speaker',
+ 'headphones', 'hdmi' or 'iMic'), or by audio device UID (eg
+ 'AppleHDAEngineOutputDP:8,5,1,0:0:{2D4C-05ED-00000000}'). Partial
+ matches are allowed, matching is case insensivtive.
+
+nas
+~~~
+
+Network Audio System live output driver.
+
+**Option keys:**
+
+- "buf\_size" - Set size of audio buffer on server in bytes.
+- "host" - Deprecated synonym for 'server' below.
+- "server" - (see 'Standard Driver Options' above). Set location of NAS
+ server; See nas(1) for format.
+
+null
+~~~~
+
+Null driver. This is just a test device which does not write the audio
+data anywhere.
+
+oss
+~~~
+
+Open Sound System driver. This is the audio system for older Linux and
+FreeBSD as well as some other UNIX-like systems.
+
+**Option keys:**
+
+- "buffer\_time" - Override the default hardware buffer size (in
+ milliseconds).
+- "dev" - (see 'Standard Driver Options' above). By default, the driver
+ tries "/dev/sound/dsp", followed by "/dev/dsp".
+- "dsp" - Deprecated synonym for "dev".
+- "id" - (see 'Standard Driver Options' above).
+
+pulse
+~~~~~
+
+PulseAudio live audio sound driver. Pulse is a sound server daemon used
+by the modern Gnome desktop on UNIX-like systems.
+
+**Option keys:**
+
+- "buffer\_time" - Override the default hardware buffer size (in
+ milliseconds).
+- "dev" - (see 'Standard Driver Options' above). This maps to a
+ specific Pulse sink; it may be specified by Pulse sink name, or by
+ number.
+- "id" - (see 'Standard Driver Options' above). Maps to a specific
+ pulse sink number.
+- "server" - Specifies Pulseaudio server to use.
+- "sink" - Deprecated synonym for "dev".
+
+roar
+~~~~
+
+RoarAudio live audio sound driver.
+
+**Option keys:**
+
+- "server" - Specifies Roar server to use.
+- "host" - Specifies Roar server to use (legacy synonym for 'server').
+- "id" - Selects audio device to use for playback by number. For a roar
+ server, this is mapped to a given output mixer.
+- "dev" - Selects audio device to use for playback by name. For a roar
+ server, this is a number and thus synonymous with 'id' above.
+- "client\_name" - descriptive name for this client (eg, the
+ application name).
+- "role" - stream type as enumerated by Roar; see RoarAudio
+ documentation.
+
+sndio
+~~~~~
+
+SNDIO is the modern audio interface used by OpenBSD.
+
+**Option keys:**
+
+- "dev" - (see 'Standard Driver Options' above).
+- "id" - (see 'Standard Driver Options' above).
+
+sun
+~~~
+
+Sun audio driver. This is the audio system for NetBSD, OpenBSD, and
+Solaris.
+
+**Option keys:**
+
+- "dev" - (see 'Standard Driver Options' above). By default, the driver
+ tries "/dev/sound/0"
+- "id" - (see 'Standard Driver Options' above).
+
+wmm
+~~~
+
+Windows MMSound output driver for Win98 and later.
+
+**Option keys:**
+
+- "dev" - (see 'Standard Driver Options' above).
+- "id" - (see 'Standard Driver Options' above).
+
+File Output Drivers
+-------------------
+
+au
+~~
+
+Sun audio file driver. Writes a .au file from audio output. This driver
+can write usable data to unseekable files (like standard out), which the
+wav driver cannot do.
+
+raw
+~~~
+
+Raw sample driver. Writes the sound to disk in uncompressed, headerless
+form using the byte order specified.
+
+**Option keys:**
+
+- "byteorder" - Byte order used in the output. Use "native" for native
+ machine byte order, "big" for big-endian order, and "little" for
+ little-endian order. By default this is "native".
+
+wav
+~~~
+
+Windows 'WAV' sound file output. Because of the way WAV files are
+structured, this driver cannot correct files unless the target file is
+seekable. Writing WAVs to stdout will result in broken files. Use either
+the raw or the au driver instead.
+
+Default Driver Detection
+------------------------
+
+In the absence of :doc:`configuration files ` to explicit identify a
+default driver, the library will try to detect a suitable default driver. It
+does this by testing every available live output driver (using
+:c:func:`ao\_plugin\_test`) and finding the driver with the highest priority
+(see the :c:type:`ao\_info` struct) that works. Drivers with priority 0, such
+as the null and file output drivers, are never selected as the default.
+
+The ranking system currently used is:
+
++------------+-----------------------------+
+| Priority | Drivers |
++============+=============================+
+| 50 | pulse, roar |
++------------+-----------------------------+
+| 45 | arts [#arts]_ |
++------------+-----------------------------+
+| 40 | esd |
++------------+-----------------------------+
+| 35 | alsa |
++------------+-----------------------------+
+| 30 | macosx, sndio |
++------------+-----------------------------+
+| 20 | aixs, oss, irix, sun, wmm |
++------------+-----------------------------+
+| 15 | arts [#arts]_ |
++------------+-----------------------------+
+| 10 | nas |
++------------+-----------------------------+
+| 0 | null, all file output |
++------------+-----------------------------+
+
+.. [#arts] priority depends on whether or not the arts install was built with
+ :c:macro:`HAVE_ARTS_SUSPENDED`; when present, the default aRts priority is
+ 45, else it is 15.
+
+Clearly, any ranking scheme will fail to make everybody happy. For such cases,
+the :doc:`configuration files ` can be easily used to define an
+appropriate default output device.
+
+Adding ``debug`` to the libao :doc:`configuration file ` on a line by
+itself will cause libao to print what static and dynamic drivers are available
+for use, as well as print the testing order.
+
diff --git a/doc/build/index.rst b/doc/build/index.rst
new file mode 100644
index 0000000..7f71a29
--- /dev/null
+++ b/doc/build/index.rst
@@ -0,0 +1,31 @@
+libao documentation
+===================
+
+Libao is a cross-platform library that allows programs to output PCM
+audio data to the native audio devices on a wide variety of platforms.
+It currently supports:
+
+- OSS (Open Sound System)
+- ESD (ESounD)
+- ALSA (Advanced Linux Sound Architecture)
+- Sun audio system (used in Solaris, OpenBSD, and NetBSD)
+- aRts (Analog Realtime Synthesizer)
+- PulseAudio
+- RoarAudio
+- OpenBSD sndio
+- Windows MMSound
+- IRIX
+- MacOS X (AU HAL)
+- NAS
+- AIX
+
+.. toctree::
+ :maxdepth: 2
+
+ drivers
+ config
+ api
+ plugins
+
+* :ref:`genindex`
+
diff --git a/doc/build/plugins.rst b/doc/build/plugins.rst
new file mode 100644
index 0000000..915b21d
--- /dev/null
+++ b/doc/build/plugins.rst
@@ -0,0 +1,287 @@
+Plugin API
+==========
+
+Plugins are drivers that are loaded dynamically when libao is first
+initialized by the client application. Drivers that are operating system
+dependent, like the ``oss`` and ``sun`` drivers, or that depend on
+external libraries, like the ``esd`` driver, must be implemented as
+plugins in order to keep binary packagers happy. There are also
+statically linked drivers, which are written in a nearly identical way,
+but won't be covered here. In nearly all cases, a dynamically loadable
+plugin is the preferred way to write a driver, and the required way if
+the driver depends upon any external libraries.
+
+Life Cycle
+----------
+
+The life cycle of a plugin is:
+
+- When libao is first :c:func:`initialized `, it loads
+ all of the plugins from disk.
+- Libao then :c:func:`tests ` each plugin to see if can
+ be used as the default driver.
+- When the user opens a device, libao will:
+
+ - Call :c:func:`ao\_plugin\_device\_init` to allow the plugin to allocate
+ and initialize any private data structures it will use.
+ - Call :c:func:`ao\_plugin\_set\_option` for each parameter passed to the
+ library by the client application.
+ - Call :c:func:`ao\_plugin\_open` to open the device for playback.
+
+- Each time the client app calls :c:func:`ao\_play`, the
+ library will reorder the byte format (little-endian vs. big-endian)
+ and rearrange input channels to match the format requested by the
+ plugin. The library will then call
+ :c:func:`ao\_plugin\_play` for the block of audio
+ data.
+- When the client app closes the audio device, the library calls
+ :c:func:`ao\_plugin\_close` to close the device,
+ followed by a call to
+ :c:func:`ao\_plugin\_device\_clear` to deallocate
+ the private data structures.
+- When the library is :c:func:`shutdown `, the plugin will
+ be unloaded from memory.
+
+In case of errors, :c:func:`ao\_plugin\_device\_clear` will always be called if
+:c:func:`ao\_plugin\_device\_init` executed successfully. Similarly,
+:c:func:`ao\_plugin\_close` will always be called if :c:func:`ao\_plugin\_open`
+executed successfully.
+
+Creating a New Plugin
+---------------------
+
+In order to write a new plugin, follow these steps:
+
+- Decide upon a new short name for your plugin. It should be less than
+ 8 characters and contain only alphanumeric characters (underscores
+ are okay, but discouraged).
+- Make a new directory in the src/plugins directory with the short name
+ of your plugin.
+- Study the contents of one of the other plugin directories. The Sun
+ driver is a good example of a driver that uses system devices for
+ output, and the ALSA driver is a good example of a plugin that uses
+ an external library. Rename the source file to ao\_shortname.c, where
+ "shortname" is the short name of your plugin.
+- Create an :c:type:`ao\_info` structure.
+- Implement the all of the methods defined in the :doc:`plugin
+ API `.
+- Create src/plugins/shortname/Makefile.am ("shortname" is as described
+ above) and edit the files configure.ac and src/plugins/Makefile.am.
+ There should be a an configure option to disable your plugin. Look at
+ the existing configure.ac file for examples of how to do this.
+- Test it thoroughly! :)
+- Send a tarball of the src/plugin/shortname directory (only this
+ directory, please!) and a cvs diff -u of the changes you have made to
+ the `vorbis-dev `__ list and we'll take a
+ look at it for inclusion.
+
+API Implementation Tips
+-----------------------
+
+- Remember to close any devices/connections you openned in
+ :c:func:`ao\_plugin\_test`.
+- Although you should try to allocate all of your data structures in
+ :c:func:`ao\_plugin\_device\_init`, there are cases where you won't be able
+ to allocate memory until :c:func:`ao\_plugin\_open` is called. That is
+ acceptable, but the rule is that you must deallocate memory in
+ :c:func:`ao\_plugin\_close` that was allocated in :c:func:`ao\_plugin\_open`
+ and deallocate memory in :c:func:`ao\_plugin\_device\_clear` that was
+ allocated in :c:func:`ao\_plugin\_device\_init`.
+- Don't forget to set device->driver\_byte\_format in
+ :c:func:`ao\_plugin\_open` to the byte ordering your plugin needs. The libao
+ core will reorder the bytes for you if it necessary.
+- Depending on the driver, a channel mapping may be very easy, tricky,
+ or impossible. If the audio backend uses a fixed numbering for its channels
+ (not necessarily a fixed order), your new driver can simply set an
+ ``output_matrix`` and ``output_matrix_ordering`` in
+ :c:func:`ao\_plugin\_device\_init` and not need to worry about much else.
+ Libao will automatically permute channels, as well has hand over the needed
+ mapping information in a form that can usually be submitted directly to the
+ audio backend during device configuration. Examples of drivers that do this
+ are WAV, ALSA and PULSE.
+- Some drivers can't perform channel mapping determination until they
+ see the input sample format in :c:func:`ao\_plugin\_open`. Such a driver
+ supports channel mapping by setting the overall ``output_matrix_ordering``
+ in :c:func:`ao\_plugin\_device\_init` and then setting the ``inter_matrix``
+ field in :c:func:`ao\_plugin\_open`. One driver that works this way is the
+ Roar plugin.
+- The number of channels to be sent to the hardware is not the number
+ of channels declared in the sample format; use the
+ device->output\_channels field instead. The number of channels an
+ application submits to libao is not necessarily the same as the
+ number of channels libao sends to the plugin to play.
+- Read the :doc:`driver documentation ` to see what priority
+ you should set for your plugin in the :c:type:`ao\_info` structure.
+
+
+.. c:function:: int ao_plugin_close(ao_device *device)
+
+ Close the device. Private data structures are not deallocated yet.
+
+ :param device:
+ Pointer to pre-allocated device structure.
+ :return:
+ 1 indicates remaining data written correctly and device closed. 0
+ indicates an error while the device was being closed. If this device
+ was writing to a file, the file may be corrupted.
+
+.. c:function:: void ao_plugin_device_clear(ao_device *device)
+
+ Deallocate the private device data structures.
+
+ :param device:
+ Pointer to pre-allocated device structure.
+
+.. c:function:: int ao_plugin_device_init(ao_device *device)
+
+ Initialize the private device data structures. Memory should be
+ allocated, and default values set if necessary, but devices should not
+ be opened until :c:func:`ao\_plugin\_open` is called.
+
+ Drivers that wish to support automatic surround channel mapping should
+ set :c:type:`ao_device.output_matrix_order` to one of:
+
+ - AO\_OUTPUT\_MATRIX\_FIXED - The audio driver outputs a fixed channel
+ order that is always the same for a given number of channels and
+ can't be changed. One example is ALSA where to play to the side right
+ speaker, it is necessary to open eight channels and write to side
+ right as channel eight, even if the other seven channels are unused.
+ - AO\_OUTPUT\_MATRIX\_COLLAPSIBLE - The audio driver outputs a fixed
+ channel order that is always the same, but unused channels are not
+ sent. In such a driver with the channel order 'L,R,C,LFE,BL,BR', we
+ can write to the two rear speakers without opening six channels but
+ the rear speakers must still be in the order 'BL,BR'. Such drivers
+ usually use a bitmap to represent the channels present in the output.
+ Examples are wav, wmm and macosx.
+ - AO\_OUTPUT\_MATRIX\_PERMUTABLE - Channels may be arranged in any
+ order. An example of such a driver is pulse.
+
+ In addition, a driver may set :c:type:`ao_device.output_matrix` to the list
+ of possible output channels in order. Note that even
+ AO\_OUTPUT\_MATRIX\_PERMUTABLE drivers usually have a fixed numbering
+ scheme for channels even if the channels may be sent in any order. A driver
+ that is unable to set an output matrix without inspecting the input sample
+ format (for example, the roar driver), may set
+ :c:type:`ao_device.output_matrix_order` to
+ :c:macro:`AO_OUTPUT_MATRIX_FIXED` and delay channel mapping initialization
+ until :c:func:`ao\_plugin\_open`.
+
+ :param device:
+ Pointer to pre-allocated device structure. The driver should store
+ the address of its private memory in :c:type:`ao_device.internal`.
+ :return:
+ 1 indicates success.
+ 0 indicates failure, probably due to memory allocation problems.
+ :c:func:`ao\_plugin\_device\_clear` should be called to ensure the
+ deallocate of all private data structures.
+
+.. c:function:: ao_info* ao_plugin_driver_info()
+
+ Get the driver information structure.
+
+ :return:
+ Pointer to the driver information structure. This structure should not
+ be modified.
+
+
+.. c:function:: char *ao_plugin_file_extension(int driver_id)
+
+ Returns the normal file extension associated with this driver (like "wav"
+ or "au"). This is an **optional** function. Live audio plugins do not need
+ to implement this function.
+
+ :return:
+ pointer to string containing suggested file extension.
+ NULL if this driver has no file extension associated with it. Live
+ audio plugins must always return NULL if they do implement this
+ function.
+
+.. c:function:: int ao_plugin_open(ao_device *device, ao_sample_format *format)
+
+ Open the device for playback. All of the device options will have already
+ been set by previous calls to :c:func:`ao\_plugin\_set\_option`. If this is
+ a file output driver, the file itself will have be already opened and a
+ pointer to a :c:type:`FILE` structure stored in :c:type:`ao_device.file`.
+
+ If the plugin wishes to support automatic channel mapping, but it was not
+ possible to set :c:type:`ao_device.output_matrix` in
+ :c:func:`ao\_plugin\_device\_init`, the plugin should now set
+ :c:type:`ao_device.inter_matrix` to the channel ordering that will be
+ expected for buffers submitted to :c:func:`ao\_plugin\_play`.
+
+ Plugins should use :c:type:`ao_device.output_channels` to determine the
+ number of output channels to configure, not
+ :c:type:`ao_sample_format.channels`. :c:type:`ao_device.output_channels`
+ is the number of channels libao will be submitting upon each call to
+ :c:func:`ao\_plugin\_play`. A plugin may alter the value of
+ :c:type:`ao_device.output_channels` to demand a different number of
+ channels if necessary (such as if a plugin is manufacturing a channel
+ mapping manually).
+
+ :param device:
+ Pointer to pre-allocated device structure. The plugin should set its
+ desired byte format in :c:type:`ao_device.driver_byte_format`.
+ :param format:
+ Output device sample format. :c:type:`ao_sample_format.byte_format`
+ should be ignored as it is relevant only to the library core.
+ :c:type:`ao_sample_format.channels` is relevant only if a plugin is
+ constructing a channel mapping manually; otherwise
+ :c:type:`ao_device.output` should be used as it is the actual number of
+ channels that will be sent to :c:func:`ao\_plugin\_play`.
+ :return:
+ 1 indicates success.
+ 0 indicates failure to open the device.
+ :c:func:`ao\_plugin\_device\_clear` should be called to ensure the
+ deallocate of all private data structures.
+
+.. c:function:: int ao_plugin_play(ao_device *device, void *output_samples, uint32_t num_bytes)
+
+ Write samples to the device. Channels are interleaved, and samples have the
+ byte order requested by the plugin
+ (:c:type:`ao_device.driver_byte_format`).
+
+ :param device:
+ Pointer to pre-allocated device structure. The plugin should set its
+ desired byte format in :c:type:`ao_device.driver_byte_format`.
+ :param output\_samples:
+ Pointer to audio sample buffer.
+ :param num\_bytes:
+ Number of bytes in buffer.
+ :return:
+ 1 indicates success.
+ 0 indicates failure to send the samples to the device.
+ :c:func:`ao\_plugin\_close` should be called.
+
+.. c:function:: int ao_plugin_set_option(ao_device *device, const char *key, const char *value)
+
+ Set a new option key-value pair for a device. This will only be called after
+ :c:func:`ao\_plugin\_device\_init` is called. Unrecognized option keys are
+ silently ignored, but invalid option values will cause the function to
+ return a failing error code.
+
+ :param device:
+ Pointer to the device structure.
+ :param key:
+ A string holding the option key. The calling function retains
+ ownership of this memory.
+ :param value:
+ A string holding the option value. The calling function retains
+ ownership of this memory.
+ :return:
+ 1 indicates success.
+ 0 indicates failure.
+ :c:func:`ao\_plugin\_device\_clear` should be called to ensure the
+ deallocate of all private data structures.
+
+.. c:function:: int ao_plugin_test()
+
+ Test if this driver could be used with only the default options. This function
+ is used by the library core to determine if a driver is a possible candidate
+ for the default driver. No devices are left open after this function returns.
+
+ :return:
+ 1 indicates that the driver can be successfully opened with no
+ options.
+ 0 indicates that the driver cannot be opened with no options.
+
+
diff --git a/doc/config.html b/doc/config.html
deleted file mode 100644
index a4c370d..0000000
--- a/doc/config.html
+++ /dev/null
@@ -1,70 +0,0 @@
-
-
-
-libao - Documentation
-
-
-
-
-
-
-
libao documentation
-
libao version 1.2.0 - 201401271
-
-
-
-
libao Configuration Files
-
-
-When libao is initialized, it reads
-two configuration files: the system-wide configuration in
-"/etc/libao.conf" and the user configuration in
-"~/.libao". Neither file needs to be present on the system for
-libao to load. If both are present, the system configuration file is
-read first, followed by the user configuration file. Options set in
-the user configuration will take precedence.
-
-
-Options are specified in these files in the form:
-
-option=value
-
-There can be no extra spaces anywhere on the line. Comment lines begin with a # symbol.
-
-
AO Options
-
-
-
default_driver
-
Set this equal to the short name of the driver you want the system to use by default. If this is not specified in any of the configuration files, the library will try to guess an appropriate driver to use.
-
debug (Value optional/ignored)
-
Sets all the drivers as well as AO itself into debugging output mode. Unlike passing the debug option to a driver, debug will also print debugging information from driver loading and testing.
-
-
quiet (Value optional/ignored)
-
Sets all the drivers as well as AO itself into silent mode. Errors will return only error codes; neither ao nor the drivers will print any output whatsoever to stderr.
-
-
verbose (Value optional/ignored)
-
Sets all the drivers as well as AO itself into verbose mode.
-
-
-
-
-
Driver Options
-
-Driver options may be set in the configuration files using option=value pairs, just as they would be set by passing options to ao_open_live() or ao_open_file(). Options passed to ao_open_live() or ao_open_file() take precedence over options specified in a configuration file. Options specified in a configuration file will be passed to whatever driver is eventually opened; they cannot be set specific to a single driver.
-
-Libao supports both live output drivers and file output
-drivers. Live output drivers send audio data to sound cards and sound
-daemons. File output drivers write audio to disk using a particular
-file format (such as WAV, AU, etc.). You must invoke the
-ao_open_????() function that corresponds to the type of driver you are
-using, but otherwise live and file drivers are treated identically in
-libao.
-
-
"matrix" - Set an output channel mapping similar to the use of the
-matrix field in ao_sample_format. The specified
-matrix overrides the backend's native channel ordering/numbering. The
-channel numbering used by the driver does not necessarily reflect the
-physical ordering; for example, the fourth PulseAudio channel is
-always 'Center' by default whether the channel physically exists or not.
-
-
"quiet" - (value not required) Requests the driver print no output
-whatsoever, even in the event of error.
-
-
"verbose" - (value not required) Requests that the driver print
-more detailed information concerning normal operation.
-
-
-
Standard Driver Options
-
-These are options that have the same use in each driver, but may not
-be supported by all drivers (due to the option being meaningless or
-unimplemented for a given audio backend).
-
-
-
"id" - Request a specific playback device/sink/output by number.
-In most audio backends, this will correspond to a specific output
-device, but for all devices, this means 'give me the Nth output'.
-
"dev" - Request a specific playback device/sink/output by name.
-This name will be in a format determined by the specific driver
-backend (eg, the first hardware device in ALSA format would be 'hw:0',
-and for OSS it would be '/dev/dsp').
-
"server" - Daemon-based sound subsystems often support connecting
-to non-default local or remote servers. The "server" option allows
-specifying the connection for a given driver in a format specific to
-that system.
-
"client_name" - specify a descriptive name for the application;
-this is often used by sound backends to display status information
-about which applications are currently making use of playback.
-
-
-
Live Output Drivers
-
-
aixs
-
-IBM AIX sound driver. According to the author, "tested on AIX 5.1 with
-the Crystal chipsets only (found as internal audio in the 7043-140 and
-on the MCA adapter DFE5 (7-6)), but it should work with other AIX
-releases and the ACPA also."
-
-
-Option keys:
-
-
"dev" - (see 'Standard Driver Options' above). By default, the
-driver tries "/dev/baud0/1" (device for MCA machines with the Crystal
-chipset). Other possible devices are "/dev/paud0/1" for PCI machines
-with the Crystal chipset, and "/dev/acpa0/1" for MCA machines with the
-ACPA.
-
"id" - (see 'Standard Driver Options' above).
-
-
-
-
-
-
alsa
-
-Advanced Linux Sound Architecture (API versions 0.9.x/1.x.x; earlier
-API versions are now deprecated).
-
-
-Option keys:
-
-
-
"buffer_time" - Override the default hardware buffer size (in
-milliseconds).
-
-
"dev" - (see 'Standard Driver Options' above). ALSA device label
-to use. Examples include "hw:0" for the first soundcard and "hw:1" for
-the second. The alsa driver normally chooses one of "surround71",
-"surround51", "surround40", "front", or "default" automatically
-depending on number of output channels.
-
-
"id" - (see 'Standard Driver Options' above).
-
-
"period_time" - Override the default hardware period size (in
-microseconds).
-
-
"use_mmap" - set to "yes" or "no" to override the compiled-in
-default to use or not use mmap device access. In
-the past, some buggy alsa drivers have behaved
-better when not using mmap access at the penalty
-of slightly higher CPU usage.
-
-
-
-
-
-
-
arts
-
-aRts Sound Daemon live output driver.
-
-
-Option keys:
-
-
-
"multi" - set to "yes" to allow opening the aRts playback device
-for multiply concurrent playback. Although the driver works properly
-in multi mode, it is known to occasionally crash the aRts server
-itself. Default behavior is "no".
-
-
-
-
-
-
esd
-
-ESounD audio driver. Although declining in poularity, this sound
-daemon is still used on some Linux systems. It permits multiple
-programs to play sound simultaneously and sound to be sent to
-networked computers.
-
-
-Option keys:
-
-
"host" - Deprecated synonym for 'server' below.
-
-
"server" - (see 'Standard Driver Options' above). The hostname
-where esd is running. By default sound is played on the local host. A
-port number can be specified after a colon, as in "whizbang.com:555".
-
"client_name" - descriptive name for this client (eg, the application name).
-
-
-
-
-
-
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.)
-
-
-
-
-
macosx
-
-MacOS X AUHAL live output driver. This driver supports MacOS X 10.5
-and later (10.4 and earlier uses an earlier, incompatable interface).
-
-
-
-Option keys:
-
-
"buffer_time" - Set the hardware buffer size to the equivalent of
-value in milliseconds.
-
"dev" - specify the audio device to use by name (eg, 'speaker', 'headphones', 'hdmi' or 'iMic'), or by audio device UID (eg 'AppleHDAEngineOutputDP:8,5,1,0:0:{2D4C-05ED-00000000}'). Partial matches are allowed, matching is case insensivtive.
-
-
-
-
-
-
nas
-Network Audio System live output driver.
-
-
-Option keys:
-
-
"buf_size" - Set size of audio buffer on server in bytes.
-
"host" - Deprecated synonym for 'server' below.
-
"server" - (see 'Standard Driver Options' above). Set location of
-NAS server; See nas(1) for format.
-
-
-
-
-
-
null
-
-Null driver. This is just a test device which does not write the
-audio data anywhere.
-
-
-
-
-
oss
-
-Open Sound System driver. This is the audio system for
-older Linux and FreeBSD as well as some other UNIX-like systems.
-
-
-Option keys:
-
-
"buffer_time" - Override the default hardware buffer size (in
-milliseconds).
-
"dev" - (see 'Standard Driver Options' above). By default, the driver tries
-"/dev/sound/dsp", followed by "/dev/dsp".
-
"dsp" - Deprecated synonym for "dev".
-
"id" - (see 'Standard Driver Options' above).
-
-
-
-
-
-
pulse
-
-PulseAudio live audio sound driver. Pulse is a sound server daemon
-used by the modern Gnome desktop on UNIX-like systems.
-
-
-Option keys:
-
-
"buffer_time" - Override the default hardware buffer size (in milliseconds).
-
"dev" - (see 'Standard Driver Options' above). This maps to a specific Pulse sink; it may be specified by Pulse sink name, or by number.
-
"id" - (see 'Standard Driver Options' above). Maps to a specific pulse sink number.
-
"server" - Specifies Pulseaudio server to use.
-
"sink" - Deprecated synonym for "dev".
-
-
-
-
-
-
roar
-
-RoarAudio live audio sound driver.
-
-
-Option keys:
-
-
"server" - Specifies Roar server to use.
-
"host" - Specifies Roar server to use (legacy synonym for 'server').
-
"id" - Selects audio device to use for playback by number. For a roar server, this is mapped to a given output mixer.
-
"dev" - Selects audio device to use for playback by name. For a roar server, this is a number and thus synonymous with 'id' above.
-
"client_name" - descriptive name for this client (eg, the application name).
-
"role" - stream type as enumerated by Roar; see RoarAudio documentation.
-
-
-
-
-
-
-
sndio
-
-SNDIO is the modern audio interface used by OpenBSD.
-
-
-Option keys:
-
-
"dev" - (see 'Standard Driver Options' above).
-
"id" - (see 'Standard Driver Options' above).
-
-
-
-
-
-
sun
-
-Sun audio driver. This is the audio system for NetBSD, OpenBSD, and
-Solaris.
-
-
-Option keys:
-
-
"dev" - (see 'Standard Driver Options' above). By default, the
-driver tries "/dev/sound/0"
-
"id" - (see 'Standard Driver Options' above).
-
-
-
-
-
-
wmm
-
-Windows MMSound output driver for Win98 and later.
-
-
-Option keys:
-
-
"dev" - (see 'Standard Driver Options' above).
-
"id" - (see 'Standard Driver Options' above).
-
-
-
-
-
-
File Output Drivers
-
-
au
-
-Sun audio file driver. Writes a .au file from audio output. This
-driver can write usable data to unseekable files (like standard out),
-which the wav driver cannot do.
-
-
-
-
-
raw
-
-Raw sample driver. Writes the sound to disk in uncompressed,
-headerless form using the byte order specified.
-
-
-Option keys:
-
-
"byteorder" - Byte order used in the output. Use "native" for
-native machine byte order, "big" for big-endian order, and "little"
-for little-endian order. By default this is "native".
-
-
-
-
-
-
wav
-
-Windows 'WAV' sound file output. Because of the way WAV files are
-structured, this driver cannot correct files unless the target file is
-seekable. Writing WAVs to stdout will result in broken files. Use
-either the raw or the au driver instead.
-
-
-In the absence of configuration files to
-explicit identify a default driver, the library will try to detect a
-suitable default driver. It does this by testing every available live
-output driver (using ao_plugin_test()) and finding the
-driver with the highest priority (see the ao_info struct) that works. Drivers with
-priority 0, such as the null and file output drivers, are never
-selected as the default.
-
-
-The ranking system currently used is:
-
-
-
Priority
Drivers
-
50
pulse, roar
-
45
arts*
-
40
esd
-
35
alsa
-
30
macosx, sndio
-
20
aixs, oss, irix, sun, wmm
-
15
arts*
-
10
nas
-
0
null, all file output
-
-
-
-*arts priority depends on whether or not the arts install was built
-with HAVE_ARTS_SUSPENDED; when present, the default aRts
-priority is 45, else it is 15.
-
-
Clearly, any ranking scheme will fail to make everybody happy. For
-such cases, the configuration files can be
-easily used to define an appropriate default output device.
-
-
Adding debug to the libao configuration file on a line by itself will
-cause libao to print what static and dynamic drivers are available for
-use, as well as print the testing order.
-
-
-Libao is a cross-platform library that allows programs to output
-PCM audio data to the native audio devices on a wide variety of
-platforms. It currently supports:
-
-
OSS (Open Sound System)
-
ESD (ESounD)
-
ALSA (Advanced Linux Sound Architecture)
-
Sun audio system (used in Solaris, OpenBSD, and NetBSD)
-
-Libao is designed to make it easy to do simple audio output using
-various audio devices and libraries. For this reason, complex audio
-control features are missing and will probably never be added.
-However, if you just want to be able to open whatever audio device is
-available and play sound, libao should be just fine.
-
-
-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. In addition, libao
-distinguishes between live output drivers, which write audio to
-playback devices (sound cards, etc.), and file output drivers,
-which write audio to disk in a particular format.
-
-
-To use libao in your program, you need to follow these steps:
-
-
Include the <ao/ao.h> header into your program.
-
-
-
Call ao_initialize() to
-initialize the library. This loads the plugins from disk, reads the
-libao configuration files, and identifies an
-appropriate default output driver if none is specified in the
-configuration files.
-
-
-
Call ao_default_driver_id() to get the
-ID number of the default output driver. This may not be successful if
-no audio hardware is available, it is in use, or is not in the "standard"
-configuration. If you want to specify a particular output driver, you
-may call ao_driver_id() with a string
-corresponding to the short name of the device (i.e. "oss", "wav",
-etc.) instead.
-
-
-
If you are using the default device, no extra options are needed.
-However, if you wish to to pass special options to the driver, you
-will need to:
-
-
-
-
Create an option list pointer of type (ao_option *) 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 documentation.
-
-
-
-
Call ao_open_live() and save the
-returned device pointer. If you are using a file output driver, you
-will need to call ao_open_file()
-instead.
-
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!
-
-Plugins are drivers that are loaded dynamically when libao is first
-initialized by the client application. Drivers that are operating
-system dependent, like the oss and sun drivers, or
-that depend on external libraries, like the esd driver, must
-be implemented as plugins in order to keep binary packagers happy.
-There are also statically linked drivers, which are written in a
-nearly identical way, but won't be covered here. In nearly all cases,
-a dynamically loadable plugin is the preferred way to write a driver,
-and the required way if the driver depends upon any external
-libraries.
-
-
-
Life Cycle
-
-
-The life cycle of a plugin is:
-
-
When libao is first initialized,
-it loads all of the plugins from disk.
-
-
Libao then tests each plugin to
-see if can be used as the default driver.
-
-
When the user opens a device, libao will:
-
-
-
-
Call ao_plugin_device_init() to
- allow the plugin to allocate and initialize any private data
- structures it will use.
-
-
Call ao_plugin_set_option() for each
- parameter passed to the library by the client application.
-
-
Each time the client app calls ao_play(), the library will reorder the byte
-format (little-endian vs. big-endian) and rearrange input channels to
-match the format requested by the plugin. The library will then call
-ao_plugin_play() for the block of
-audio data.
-
-
When the client app closes the audio device, the library calls ao_plugin_close() to close the device,
-followed by a call to ao_plugin_device_clear() to deallocate
-the private data structures.
-
-
When the library is shutdown, the
-plugin will be unloaded from memory.
-
-
-In order to write a new plugin, follow these steps:
-
-
-
Decide upon a new short name for your plugin. It should be less
-than 8 characters and contain only alphanumeric characters
-(underscores are okay, but discouraged).
-
-
Make a new directory in the src/plugins directory with the short name of your plugin.
-
-
Study the contents of one of the other plugin directories. The
-Sun driver is a good example of a driver that uses system devices for
-output, and the ALSA driver is a good example of a plugin that uses an
-external library. Rename the source file to ao_shortname.c, where
-"shortname" is the short name of your plugin.
-
-
Implement the all of the methods defined in the plugin API.
-
-
Create src/plugins/shortname/Makefile.am ("shortname" is as
-described above) and edit the files configure.ac and
-src/plugins/Makefile.am. There should be a an configure option to
-disable your plugin. Look at the existing configure.ac file for
-examples of how to do this.
-
-
Test it thoroughly! :)
-
-
Send a tarball of the src/plugin/shortname directory (only this
-directory, please!) and a cvs diff -u of the changes you have made to
-the vorbis-dev list and we'll
-take a look at it for inclusion.
-
-
-
-
-
API Implementation Tips
-
-
-
-
-
Remember to close any devices/connections you openned in ao_plugin_test().
Don't forget to set device->driver_byte_format in ao_plugin_open() to the byte ordering
-your plugin needs. The libao core will reorder the bytes for you if
-it necessary.
-
-
Depending on the driver, a channel mapping may be very easy,
-tricky, or impossible. If the audio backend uses a fixed numbering
-for its channels (not necessarily a fixed order), your new driver can
-simply set an output_matrix and
-output_matrix_ordering in ao_plugin_device_init() and not
-need to worry about much else. Libao will automatically permute
-channels, as well has hand over the needed mapping information in a
-form that can usually be submitted directly to the audio backend
-during device configuration. Examples of drivers that do this are WAV,
-ALSA and PULSE.
-
-
Some drivers can't perform channel mapping determination until
-they see the input sample format in ao_plugin_open(). Such a driver
-supports channel mapping by setting the overall
-output_matrix_ordering in ao_plugin_device_init() and then
-setting the inter_matrix field in ao_plugin_open(). One driver that
-works this way is the Roar plugin.
-
-
The number of channels to be sent to the hardware is not the
-number of channels declared in the sample format; use the
-device->output_channels field instead. The number of channels an
-application submits to libao is not necessarily the same as the number
-of channels libao sends to the plugin to play.
-
-
Read the driver documentation to see
-what priority you should set for your plugin in the ao_info structure.
-
-