skip navigational linksPJRC
Shopping Cart Download Website
Home Products Teensy Blog Forum
You are here: Teensy Teensyduino Libraries Audio Naming

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:

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().

Control Objects

TODO: much work needed here....