Author:	Perette Barella
Date:	2015-11-19
Updated: 2015-12-03
Summary:	Plans for updating Pianod2 autoconf scripts.
Status: Implemented, except configure script checks for OSS/ALSA support and selecting AVDevice exclusively.

Pianod2 Autoconf Updates
========================

pianod2’s autoconf/build scripts have heretofore simply had to determine, “Can I compile this, and how?”  This is changing as pianod2 advances:

* There are multiple audio output libraries supported.
* There are multiple media engines in progress.
* Some media engines have built-in audio output, and may or may not allow external ones.

The question becomes, “What do we include?  How much do we need?”

Answer: *A default configuration should include the minimal set of components to support the most complete set of features possible, with the best reliability possible:*

1. More than this creates software bloat.
2. Leaving features out is undesirable, but acceptable if impossible to include them.
3. Dodgy software should be avoided when better options are available.

Configuration switches allow users to expand or contract this to specialized needs.

Media Engines
-------------
At present, there are three media engines:

* ffmpeg
* libav
* AVFoundation (OS X 10.7+).

ffmpeg & libav are equivalent, and will not coexist.  They are full-featured, support a range of output devices, and include lots of interesting output pseudo-devices.

AVFoundation is OS X 10.7+ only, requires some crazy contortions to make it work, and does not at present support the tone generator, which is helpful for unit testing.

The approach is thus:

1. Use user-specified engine, if user gives such direction.
2. Use ffmpeg or libav, whichever is installed, if available.
3. Use AVFoundation only if neither ffmpeg nor libav are available.

Audio Output
------------
* Traditionally we support libao for output.
* AVFoundation handles audio output itself.
* ffmpeg and libav include support for some output schemes, and provide additional ones if prerequisite libraries are installed.
* SDL (Simple DirectMedia Layer) is a prerequisite for ffmpeg/libav audio output on OS X.
* For ffmpeg: `ffmpeg -devices` will list output devices available.
* For libav: `avplay` is only constructed if prerequisites are available.  The library supports ALSA and OSS natively, and nothing else for output.

The approach is thus:

1. If using AVFoundation, also include libao or libsdl to support the tone generator.  If the tone generator is excluded, drop all additional audio support; AVFoundation provides its own.
2. If ffmpeg is available, use `ffmpeg -devices` to check there are output devices.  If not, include libao; otherwise, use the built-in one.
3. Check for ALSA: presence of `alsa` utility and `/proc/asound/version`.  If found, expect libav built-in support.
4. Check for OSS: presence of `ossdetect` and `ossinfo` utilities.  If found, expect libav built-in support.
5. Build with libav and libao.

Looking forward, adding a SDL driver looks doable and would provide what looks like a commonplace alternative to libao.  In this case:

1. Use ffmpeg/libav built-in support if it’s there.
2. Use the tried-and-true libao if available.
3. Use SDL if it is available.
4. Fail; no audio device output device available.

Note that there may be rare cases where no audio out is needed, such as setting up an icecast/streaming service which will deliver audio to other machines for playback.  In general, however, this should be considered an error.

Manual Configuration
--------------------
Manual configuration may involve choosing the media engine:

	`--with-avfoundation` (implicitly excludes ffmpeg/libav)
	`--with-libav` (implicitly excludes avfoundation)

Excluding all media engines is an error.

Manual configuration may explicitly include or exclude any of the audio outputs.  Excluding all output devices, either manually or automatically, is an error.

A `--disable-sanity` option will reduce configuration error to warnings, allowing test builds and unusual configurations.