libao Plugin Writer's Overview

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.
  • Call ao_plugin_open.html to open the device for playback.
• 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.

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 ao_info structure.
• 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().
• Although you should try to allocate all of your data structures in ao_plugin_device_init(), there are cases where you won't be able to allocate memory until ao_plugin_open() is called. That is acceptable, but the rule is that you must deallocate memory in ao_plugin_close() that was allocated in ao_plugin_open() and deallocate memory in ao_plugin_device_clear() that was allocated in ao_plugin_device_init().
• 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.