[linux-audio-dev] anaheim

[Tim Hockin]

> assuming i can book one, i would appreciate it if tim (hockin) could


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 at 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