Naming Conventions for Audio Objects
DRAFT Information on this page is tentative. Please discuss on the forum.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
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().