How does this look for a start? Please send me fixes and missing topics. Keep in mind this is an OVERVIEW doc, not a full API guide. :) Tim (it's 3:00 am - goodnight!) The XAP Audio Pluing API An Overview $Id: xap_overview.txt,v 1.1 2003/01/15 10:55:50 thockin Exp $ Guilty Parties ---- XAP is a combined effort of many people on the linux-audio-dev (linux-audio-dev(a)music.columbia.edu) mailing list. The discussion is open, and anyone interested is welcome to join in. Goals ---- The main goal of this API is to provide an API that is full-featured enough to be the primary plugin system for audio creation and playback applications, while remaining as simple, lightweight, and self-contained as possible. Terminology ---- * Plugin: A chunk of code, loaded or not, that implements this API (e.g. a .so file or a running instance). * Host The program responsible for loading and controlling Plugins. * Instrument/Source: An instance of a Plugin that supports the instrument API and is used to generate audio signals. Many Instruments will implement audio output but not input, though they may support both and be used an an Effect, too. * Effect: An instance of a Plugin that supports both audio input and output. * Output/Sink: An instance of a Plugin that can act as a terminator for a chain of Plugins. Many Outputs will will support audio input but not output, though they may support both and be used as an Effect, too. * Voice: A playing sound within an Instrument. Instruments may have multiple Voices, or only one Voice. A Voice may be silent but still active. * Event: A time-stamped notification of some change of something. * Control: A knob, button, slider, or virtual thing that modifies behavior of the Plugin. Controls can be master (e.g. master volume), per-Channel (e.g. channel pressure) or per-Voice (e.g. aftertouch). * Port: An audio input or output. //FIXME: some big ones are missing: VVID, Channel, EventQueue, Tick, // Cuepoint Overview ---- Plugins are loaded from shared object files. A shared object file holds one or more plugin descriptors, accessed by index. Each descriptor holds all the information about a single plugin - it's identification, capabilities, controls, and access methods. XAP plugins are always in one of two states - ACTIVE or INACTIVE. Hosts load Plugins, instantiate them, establish Port and EventQueue connections, and activate them. Once active, a Plugin expects to be run repeatedly on small blocks of data. Events ---- Almost everything that happens during the ACTIVE state is communicated via Events. The Host can send Events to Plugins, Plugins can send Events to the Host, and Plugins can send Events to other Plugins (if they are so connected). XAP hosts have a running timer (unsigned) which counts sample-frames since some arbitrary start point. The start point is irrelevant, only the passing of audio-time matters. All Events are time-stamped, giving XAP plugins sample-accurate handling of events. Controls ---- XAP uses Controls as abstract carriers of Plugin parameters and other information. Controls are the way Events are transferred. Controls can represent things like knobs and buttons, but they can also represent things like MIDI-compatible aftertouch or channel pressure. Not only do they represent audio parameters, but they can represent chunks of system information, such as tempo or transport position. Controls come in a few datatype flavors, and have min/max limits and default values, as well as hints to the host about what they are. Tempo and Meter ---- XAP uses Controls for transmitting tempo and meter information. If a Plugin defines a TEMPO control, it can expect to receive tempo events on that control. The Host must define some unit of measurement, a Tick, which represents the smalles granularity the host wants to work with. This is the basis for tempo and meter. Control: TEMPO Type: double Units: ticks/sec Range: [-inf, inf] Events: Hosts must send a TEMPO Event at Plugin init and when tempo changes. Control: METER Type: double Units: ticks/measure Range: [0.0, inf] Events: Hosts must send a METER Event at Plugin init and when meter changes. Hosts should send a METER Event periodically, such as every measure or once per second. Control: METERBASE Type: double Units: beats/whole-note Range: [1.0, inf] Events: Hosts must send a METERBASE Event at Plugin init and when meter changes. Sequencer Control ---- XAP plugins may be aware of certain sequencer events, such as transport changes, positional jumps., and loop-points. These data are received on Controls. Control: POSITION Type: double Units: ticks Range: [0.0, inf] Events: Hosts must send a POSITION Event at Plugin init, when transport starts, and when transport jumps. Hosts should send a POSITION Event periodically, such as every beat, every measure or once per second. Control: TRANSPORT Type: bool Units: on/off Events: Hosts must send a TRANSPORT Event at Plugin init and when transport state changes. Control: CUEPOINT Type: double Units: ticks Range: [0.0, inf] Events: Hosts must send a CUEPOINT Event when Cuepoints are added, changed, or removed. Control: SPEED Type: double Units: scalar Range: [-inf, inf] Events: Hosts must send a SPEED Event at Plugin init and when play speed changes. //FIXME: Voices and VVIDS //FIXME: Event types? //FIXME: Control types? //FIXME: Host call backs //FIXME: Time conversion //FIXME: Threading //FIXME: RT //FIXME: Channels //FIXME: MIDI