Naming Conventions for Audio Objects

Consistent naming and adherence to common conventions is important to make
the entire audio library usable. Audio objects should also attempt to follow
Arduino's Library Style Guidelines.

The audio library's mission it to enable Arduino users of all skill levels to
easily create awesome, great sounding audio projects. Objects should be designed
to provide easy to understand functions that avoid exposing users to complex
details, even when doing so requires a (reasonable) trade-off involving extra code, memory
or processor usage.

All audio library objects are to be instantiated by the user's sketch.
None are created in advance with fixed names, like Serial1, Serial2, etc.

Object Naming

Every object begins with "Audio", followed by a category name, which is followed by
one of more names that describe its function. Each name is capitalized. When more
names are used, the earlier names form a sub-category, and each successive name is
more specific.

The category names are:

Input: Receive signals or real-time data

Output: Transmit signals or real-time data

Play: Read data from storage media

Record: Write data to storage media

Mixer: Add multiple audio streams

Analyze: Make information about audio available to the Arduino sketch

Synth: Create audio

Filter: Modify audio spectrum by filtering

Effect: Modify audio, pretty much anything other than filtering

Control: Control external audio processing hardware

Within the Play and Record categories, typically the first name indicates the
type of media used. If the media supports multiple formats, the second name
indicates the data format used.

Function & Parameter Conventions

Functions which accept parameters or return information about audio levels
should do so using float variables that range from 0 to 1.0.
In cases where negative numbers are appropriate, floats from -1.0 to 1.0
are used. Internally, the library manipulates audio data as 16 bit signed
integers, but every attempt should be made to provide a conceptual interface
to Arduino sketches of audio data, levels ranging from from 0 to 1 or -1 to +1.

Likewise, parameters relating to gain, amplification, levels or attenuation
should be expressed as floating point numbers in the functions accessible
to Arduino sketches. Internally, the library may use inline functions to
convert from float to its internal fixed point representation, allowing the
compiler to optimize away the floating point math in the case of constants.
See the AudioMixer4 object for an example of this inline function optimization.

All other parameters to functions should be expressed in the most natural
units, even if extra conversion is needed between the Arduino-visible units
and the library's internal representation.

Playback Control & Status

Play category objects should implement these functions.

myObject.play(something);

Begin playing "something" from the media. If the object
was already playing, it is stopped, then this new audio begins
playing as soon as possible.

myObject.isPlaying();

Returns true if the object is playing sound: copying
from the media to its output channel(s).

myObject.stop();

Stops playing.

myObject.positionMillis();

Returns the current offset from the beginning of playback,
in milliseconds.

myObject.lengthMillis();

Returns the total length of the currently playing data,
in milliseconds.

Analysis Output

myObject.available();

When new data becomes available for the Arduino sketch, the
available function should return true, or non-zero, once. This is a slight
departure from Arduino's Stream class, where available returns the amount of
data waiting to be read. Most audio analysis will return one to several pieces
of data at regular intervals, where the user will often not be interested in
accessing some of the optional items.

myObject.read(optional);

Analysis results should be accessible by the read() function,
perhaps taking an optional parameter when the analysis produces more than
one piece of output data. While the usage is conceptually similar to Stream's
read() function, the model is available() signals once the arrival of a new
set of data, which can then be accessed in any order using read().