[linux-audio-dev] Plugin APIs (again)

[Tim Hockin]

So, I'm incorporating the things that were discussed this week into my API
proposal.  It's starting to take shape, and I really appreciate the feedback
I got (why I can't get that level of feedback even at work, is beyond me).

I've hit a couple of large questions that I want to bounce off you all.

Per-voice controls vs. Master controls:
----
This is what I am thinking:  One of the flags on each control is whether it
is a CTRL_MASTER, or a CTRL_VOICE (or both).  This allows the plugin to
define a ctrl labelled (for example) VELOCITY and the host can connect it to
any MIDI input, if it wants.

Let's assume a plugin provides a control named FOO which is both VOICE and
MASTER.  Let's assume the current state of FOO is the value 50.0.  Let's
assume the sequencer triggers a voice and sets FOO for that voice to 80.0.
The user then turns the master FOO down to 0.  What happens to the value of
the voice's FOO.
	a) goes to 0
	b) ends up at 30.0
	c) stays at 80.0

Maybe controls that are both MASTER and VOICE should be absolute values for
MASTER and scalars against the MASTER value per-voice?

Needs discussion.

Triggering a voice
----
I see a few methods, each has pros and cons.

	1) * Host calls plug->note_on(timestamp, note, velocity), and 
	     gets a voice-id.
	   * Host sends n VOICE_PARAM events to set up any params it wants
	   * Host calls plug->run()
	   * Plugin activates the voice at the right timestamp with the
	     right params.
	   * Host calls plug->get_polyphony() to know how many voices are
	     playing.
	   * Host calls plug->voice_off(voice, velocity)
	
	2) * Host sends a VOICE_ON event with a negative voice-id and params 
	     velocity and note
	   * Host sends n VOICE_PARAM events for the negative voice-id
	   * Host calls plug->run()
	   * Plugin receives the VOICE_ON, allocates a voice-id, and and
	     sends a VOICE_ON event with the real voice-id and the negative
	     bogus one back to the host.
	   * Host sends a VOICE_OFF event to the plugin to end a voice,
	     plugin ACKs by sending it back.
	   * Plugin sends a VOICE_OFF event to the host if a voice is done
	     before the host sends VOICE_OFF (short sample, etc)
	   * Host keeps a count of voices, increment on VOICE_ON, decrement
	     on VOICE_OFF.

Modifications on those two:
	a) Same as #1 but with no voice_off() method - use VOICE_OFF events
	instead.

	b) Modification on #1 and #2 - don't pass velocity and pitch params,
	   instead have them as controls
	c) Same as b, except Velocity is not a continuous control - pass
	   velocity but keep pitch as a control (possibly pitch and
	   pitch-bend being different?  not sure).


Preset and state save/restore
----
Should each plugin provide serialize() and deserialize() methods (thus
storing plugin state from the plugin itself in an arbitrary string) or
should the host be expected to write-out each control's data?

I'm leaning towards serialize/deserialize.

So, I'm looking for ideas and discussion!

Tim