TITLE:: FluidBufAudioTransport
summary:: Interpolate between buffers
categories:: FluidManipulation
related:: Classes/FluidAudioTransport

DESCRIPTION::
Interpolates between the spectra of two sounds using the Optimal Transport algorithm

See
Henderson and Solomonm (2019) AUDIO TRANSPORT: A GENERALIZED PORTAMENTO VIA OPTIMAL TRANSPORT, DaFx

CLASSMETHODS::

METHOD:: process, processBlocking
Process two audio link::Classes/Buffer::

ARGUMENT:: server
The server the process runs on

ARGUMENT:: source1
The first source buffer

ARGUMENT:: startFrame1
offset into the first source buffer (samples)

ARGUMENT:: numFrames1
number of samples to use from first source buffer

ARGUMENT:: startChan1
starting channel of first source buffer

ARGUMENT:: numChans1
number of channels to process in first source buffer

ARGUMENT:: source2
the second source buffer

ARGUMENT:: startFrame2
offset into the second source buffer (samples)

ARGUMENT:: numFrames2
number of samples to process from second buffer

ARGUMENT:: startChan2
starting channel for second buffer

ARGUMENT:: numChans2
number of channels to process in second buffer

ARGUMENT:: destination
buffer for interpolated audio

ARGUMENT:: interpolation
The amount to interpolate between A and B (0-1, 0 = A, 1 = B)

ARGUMENT:: bandwidth
The width in bins of an ideal sine wave, which is correlated with the spectrum for peak detection. Larger values provide enhanced resolution, at a computational cost.

ARGUMENT:: windowSize
	The window size. As spectral differencing relies on spectral frames, we need to decide what precision we give it spectrally and temporally, in line with Gabor Uncertainty principles. http://www.subsurfwiki.org/wiki/Gabor_uncertainty

ARGUMENT:: hopSize
	The window hop size. As sinusoidal estimation relies on spectral frames, we need to move the window forward. It can be any size but low overlap will create audible artefacts. The -1 default value will default to half of windowSize (overlap of 2).

ARGUMENT:: fftSize
	The inner FFT/IFFT size. It should be at least 4 samples long, at least the size of the window, and a power of 2. Making it larger allows an oversampling of the spectral precision. The -1 default value will use the next power of 2 equal or above the highest of windowSize and (bandwidth - 1) * 2.

ARGUMENT:: freeWhenDone
Free the server instance when processing complete. Default true

ARGUMENT:: action
	A Function to be evaluated once the offline process has finished and all Buffer's instance variables have been updated on the client side. The function will be passed [destination] as an argument.

INSTANCEMETHODS::

private:: synth, server

EXAMPLES::

code::
//Didactic:
//Make 2 sinewave sources to be interpolated
(
b = Buffer.loadCollection(s, FloatArray.fill(44100, {|a|(a / pi).sin * 0.1}));
c = Buffer.loadCollection(s, FloatArray.fill(44100, {|a|(a / pi / 2).sin * 0.02}));
d = Buffer.new
)

//make an sound interpolating their spectrum
FluidBufAudioTransport.process(s,b,source2:c,destination:d,interpolation:0.5,action:{"Ding".postln})

// listen to the source and the result
b.play
c.play
d.updateInfo
d.play

// more interesting sources: two cardboard bowing gestures
(
b = Buffer.read(s,File.realpath(FluidBufAudioTransport.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Green-Box641.wav");
c = Buffer.read(s,File.realpath(FluidBufAudioTransport.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Green-Box639.wav");
d = Buffer.new
)

// listen to the source
b.play
c.play

// process and listen
FluidBufAudioTransport.process(s,b,source2:c,destination:d,interpolation:0.5,action:{"Ding".postln})
d.play
// try various interpolation factors (0.1 and 0.9 are quite good
::