samer@0: % playaudio_async - Play stream of audio data asynchronously
samer@0: %
samer@0: % playaudio :: 
samer@0: %    X:seq [[N]]    ~'sequence of arrays',
samer@0: %    R:nonneg       ~'sampling rate',
samer@0: %    options {
samer@0: %       maxbuf  :: natural/2*max(size(X))   ~'maximum buffer size';
samer@0: %       hook    :: (iterator(S)->iterator(T)) ~'fn to build iterator';
samer@0: %       onstart :: A -> action      ~'called BEFORE timer starts';
samer@0: %       onstop  :: A -> action      ~'called AFTER timer stops';
samer@0: %       onfinish:: A -> action      ~'called when end of signal reached';
samer@0: %       defer   :: bool / 0         ~'if 1, don't start the timer'
samer@0: %    }
samer@0: % -> sched(S) ~'scheduler api functions',
samer@0: %    (S -> [[N]]) ~'function to recover audio from iterator state'.
samer@0: %
samer@0: % iterator(S) ::= cell {(S->action S)~'state transformer', S~'initial state'}.
samer@0: %
samer@0: % sched(S) ::= struct {
samer@0: %		dispose   :: unit -> action unit;
samer@0: %		isrunning :: unit -> action bool;
samer@0: %		startat	 :: real -> action unit;
samer@0: %		start		 :: unit -> action unit;
samer@0: %		stop		 :: unit -> action unit;
samer@0: %		rewind	 :: unit -> action unit;
samer@0: %		getstate	 :: unit -> action S;
samer@0: %		setstate	 :: S    -> action unit
samer@0: % }.
samer@0: %
samer@0: % The 'hook' option gives the caller an opportunity to elaborate on the
samer@0: % 'iterator' used to drive the audio playback. The 'iterator' is a cell
samer@0: % array contain a state transformer function and initial state. The caller
samer@0: % can use this to build a more complex iterator the does other things
samer@0: % for each buffer of samples.
samer@0: %
samer@0: % The third return value is a function which can be used in a state
samer@0: % transformer function to recover a buffer of audio samples from the
samer@0: % current state.
samer@0: %
samer@0: % NB: all the audio buffers must be the same size for this to work.
samer@0: % NB: the rewind function should only be called when the timer is stopped.
samer@2: function [Sched,GetData]=playaudio_async(Y,Snk,varargin)
samer@0: 	[Sched,GetData]=playaudio_unfold(size(Y,2),@decons,Y,Snk),varargin{:});
samer@0: end