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) 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.
Copy the contents of one of the other plugin directories into your
directory. 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.
Edit the files ("shortname" is as described above): configure.in,
src/plugins/Makefile.am, src/plugins/shortname/Makefile.am. There
should be a an configure option to disable your plugin. Look at the
existing configure.in 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.