[linux-audio-dev] XAP: a polemic

[David Olofson]

On Wednesday 18 December 2002 10.18, Tim Hockin wrote:
> > On Wednesday 18 December 2002 01.25, Tim Hockin wrote:
> > > > > 1) the host->tick_me(plugin, 100, cookie)  // call me back
> > > > > in 100 ticks - This could be a simple host-based
> > > > > time-management API - This depends on a 1-1 map between
> > > > > host and timeline, which I think is ok
> >
> > Doesn't work for *position* changes, though, which is what I was
> > really thinking about. If it turns out that you just missed the
> > event, should it be thrown away, kept indefinitely, adjusted to
> > the start of the current block, or quantized to the first beat
> > (or whatever) in the current block, or later blocks, or what?
>
> Or just toss away all tick_me events on a transport jump. Or see
> my other email about escrow - one API to say loop these events, and
> one to say toss them.

Or just one API that keeps some data you hand it, and lets you 
reevaluate prequeued events when needed? (See my previous reply on 
handling this.)


> I'm not really arguing for this, just playing it out..

Right. I think what has been discussed so far is best done in the 
SDK, though. Instead of the host, you'd talk to a private "object" 
that has a process() call you call first thing for every block. All 
info required is in your input event queues anyway.

In fact, the host does *not* have access to this info in any obvious 
way (would have to eavesdrop to get it), so this really belongs in 
the plugin.


> > > As long as it does not need to be special cased, I can buy
> > > this. Our notion of 'hints' has gotten pretty strange though.
> >
> > Hmm... Yes. What *are* they, actually? Do we need type hints as
> > well as other hints? Multiple hints per control?
>
> Well, I'd been assuming hints were strings, and controls could have
> multiple hints.  With things like TEMPO, etc, it is more than just
> a hint.  It has to be the right hint, datatype, range, etc. 
> Perhaps macros for declaring the most commonly hinted controls
>
> #define XAP_DECL_CTRL_TEMPO(name)	\
> 	XAP_float_ctrl name = { \
> 		... \
> 	}; \

Yeah...


> > Some catching up to do...? ;-)
>
> mostly caught up, and it seems we weren't far off the mark to start
> with. I'll summarize again here.  Please correct me if I am wrong
> or missed something:
>
>
> Time in XAP:
> -----
> SAMPLE_RATE:  all plugins know this from create()
>   - units: frames/sec (uint)

Yeah, but why not float? (Right, it's just a nominal sample rate, but 
anyway...)


> TEMPO:  a plugin can have a TEMPO control
>   - units: beats/sec (float)

Why not ticks/second, to avoid scaling when applying to position?


>   - deliver a TEMPO event at plugin init and whenever the tempo
> changes

Yep.


> TIMEBASE:  fixed value
>   - units: ticks/beat
>   - fixed at 1920

Yes.


> METER:  a plugin can have a METER control (or controls)
>   - units: beats/measure (float) and beat-note-size (float)
>   - another option: encode as a fixed-point value and int inside 32
> bits - deliver a METER event at plugin init and whenever the meter
> changes

Or a third option: Two floats. Beats/measure expressed as 
ticks/measure (multiply with 1920, that is). Note value expressed as 
length in ticks.


> TRANSPORT: a plugin can have a TRANSPORT control
>   - units: absolute ticks (float)

No, must be double. float isn't accurate enough for more than a few 
minutes. (Just 24 bits, and that corresponds to 5.8 minutes of 
counting samples at 48 kHz. Then you lose the first low bit...)


>   - deliver a TRANSPORT control when transport starts (start tick),
> stops (negative), jumps (new tick value)

I think thansport position and transport start/stop should be kept 
separate, to avoid the special case handling. Remember that extra 
event actions don't cost anything extra to decode. The switch() is 
just a single LUT anyway.

It might be interesting to explicitly tell plugins whether a 
transport change is because of a jump, or if it's just a resync. 
OTOH, what matters is the delta, and that's plugin dependent. Just 
check the delta if you're interested. (Even a resync can result in a 
skip of several samples, if the sequencer is syncing with something 
external! It's better done with tempo adjustments, though, but that's 
a sequencer implementation decision.)


> and periodically
> (recommend each beat or each measure)

We never know what beat or measure lengths people will use, so in's 
probably better to just send periodic resync approximately once per 
second or something like that. I would also recommend that resync is 
sent directly after tempo changes and tempo ramps. (Especially if we 
allow spline ramping of the tempo control...)


> There is then some mechanism to convert values.  This answer is
> still not clear yet.  Which exact transforms do we need to provide
> (SDK), and which data/transforms does the host/timeliner need to
> provide?

Here are the time domains represented in VST's time info:

	Domain		Our unit
	-------------------------------------------
	Audio time	(samples)

	System time	(seconds?)

	Musical time	(ticks; 1920/beat)

	SMPTE time	(frames)

	MIDI clock	(clocks at 24 ppq)


Not sure what the point is with the last one, though. Provided your 
sequencer is driven my external MIDI clock, this should be equivalent 
to Musical Time anyway. Otherwise, if there's no MIDI clock input, 
this would be undefined.

The "raw" MIDI clock that drives the sequencer? Would that apply to 
SMPTE time as well; ie do you want the SMPTE time as is, or as 
reconstructed by the sequencer after it's "sync filter"?


> Is meter simpler as QN/beat and beats/measure, with tempo = QN/sec
> and timebase=1920 ticks/QN ?

No QNs, please... A beat can be anything, and then QNs are irrelevant.


> It seems that this is how most
> everyone else does it.  Is it simpler, or is there a reason they
> do?

No rounding errors. :-)


> Now, correct me if I am wrong about any of this?  Let's wrap up the
> time discussion and get another draft out soon.  Lots more to do :)

Yeah. I think we basically have the conversion API left to do. There 
are some details for which I don't see obvious solutions right now.


//David Olofson - Programmer, Composer, Open Source Advocate

.- The Return of Audiality! --------------------------------.
| Free/Open Source Audio Engine for use in Games or Studio. |
| RT and off-line synth. Scripting. Sample accurate timing. |
`---------------------------> http://olofson.net/audiality -'
   --- http://olofson.net --- http://www.reologica.se ---