flucoma-sc/release-packaging/HelpSource/Classes/FluidBufOnsetSlice.schelp

TITLE:: FluidBufOnsetSlice
SUMMARY:: Spectral Difference-Based Audio Buffer Slicer
CATEGORIES:: Libraries>FluidDecomposition
RELATED:: Guides/FluCoMa, Guides/FluidDecomposition, Guides/FluidBufMultiThreading

DESCRIPTION::
This class implements many spectral-based onset detection metrics, most of them taken from the literature. (http://www.dafx.ca/proceedings/papers/p_133.pdf) Some are already available in SuperCollider's LINK::Classes/Onsets:: object yet not as offline processes. It is part of the LINK:: Guides/FluidDecomposition:: of LINK:: Guides/FluCoMa::. For more explanations, learning material, and discussions on its musicianly uses, visit http://www.flucoma.org/

The process will return a buffer which contains indices (in sample) of estimated starting points of different slices.

STRONG::Threading::

By default, this UGen spawns a new thread to avoid blocking the server command queue, so it is free to go about with its business. For a more detailed discussion of the available threading and monitoring options, including the two undocumented Class Methods below (.processBlocking and .kr) please read the guide LINK::Guides/FluidBufMultiThreading::.

CLASSMETHODS::

METHOD:: process
	This is the method that calls for the slicing to be calculated on a given source buffer.

ARGUMENT:: server
	The server on which the buffers to be processed are allocated.

ARGUMENT:: source
	The index of the buffer to use as the source material to be sliced through novelty identification. The different channels of multichannel buffers will be summed.

ARGUMENT:: startFrame
	Where in the srcBuf should the slicing process start, in sample.

ARGUMENT:: numFrames
	How many frames should be processed.

ARGUMENT:: startChan
	For multichannel sources, which channel should be processed.

ARGUMENT:: numChans
	For multichannel sources, how many channel should be summed.

ARGUMENT:: indices
	The index of the buffer where the indices (in sample) of the estimated starting points of slices will be written. The first and last points are always the boundary points of the analysis.

ARGUMENT:: metric
	The metric used to derive a difference curve between spectral frames. It can be any of the following:
		TABLE::
		##0 || Energy || thresholds on (sum of squares of magnitudes / nBins) (like Onsets \power)
		##1 || HFC || thresholds on (sum of (squared magnitudes * binNum) / nBins)
		##2 || SpectralFlux || thresholds on (diffence in magnitude between consecutive frames, half rectified)
		##3 || MKL || thresholds on (sum of log of magnitude ratio per bin) (or equivalent: sum of difference of the log magnitude per bin) (like Onsets \mkl)
		##4 || IS || (WILL PROBABLY BE REMOVED) Itakura - Saito divergence (see literature)
		##5 || Cosine || thresholds on (cosine distance between comparison frames)
		##6 || PhaseDev || takes the past 2 frames, projects to the current, as anticipated if it was a steady state, then compute the sum of the differences, on which it thresholds (like Onsets \phase)
		##7 || WPhaseDev || same as PhaseDev, but weighted by the magnitude in order to remove chaos noise floor (like Onsets \wphase)
		##8 || ComplexDev || same as PhaseDev, but in the complex domain - the anticipated amp is considered steady, and the phase is projected, then a complex subtraction  is done with the actual present frame. The sum of magnitudes is used to threshold (like Onsets \complex)
		##9 || RComplexDev || same as above, but rectified (like Onsets \rcomplex)
		::

ARGUMENT:: threshold
The thresholding of a new slice. Value ranges are different for each metric, from 0 upwards.

ARGUMENT:: minSliceLength
	The minimum duration of a slice in number of hopSize.

ARGUMENT:: filterSize
	The size of a smoothing filter that is applied on the novelty curve. A larger filter filter size allows for cleaner cuts on very sharp changes.

ARGUMENT:: frameDelta
		For certain metrics (HFC, SpectralFlux, MKL, Cosine), the distance does not have to be computed between consecutive frames. By default (0) it is, otherwise this sets the distane between the comparison window in samples.

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 spectral differencing 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 windowSize.

ARGUMENT:: action
		A Function to be evaluated once the offline process has finished and indices instance variables have been updated on the client side. The function will be passed indices as an argument.

RETURNS::
	Nothing, as the destination buffer is declared in the function call.

EXAMPLES::

CODE::
(
//prep some buffers
b = Buffer.read(s,File.realpath(FluidBufOnsetSlice.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Nicol-LoopE-M.wav");
c = Buffer.new(s);
)

(
// with basic params
Routine{
	t = Main.elapsedTime;
	FluidBufOnsetSlice.process(s,b, indices: c, threshold:0.5);
	(Main.elapsedTime - t).postln;
}.play
)

//check the number of slices: it is the number of frames in the transBuf minus the boundary index.
c.query;

//loops over a splice with the MouseX
(
{
	BufRd.ar(1, b,
		Phasor.ar(0,1,
			BufRd.kr(1, c,
				MouseX.kr(0, BufFrames.kr(c) - 1), 0, 1),
			BufRd.kr(1, c,
				MouseX.kr(1, BufFrames.kr(c)), 0, 1),
			BufRd.kr(1,c,
				MouseX.kr(0, BufFrames.kr(c) - 1), 0, 1)), 0, 1);
		}.play;
)
::

STRONG::A stereo buffer example.::
CODE::

// make a stereo buffer
b = Buffer.alloc(s,88200,2);

// add some stereo clicks and listen to them
((0..3)*22050+11025).do({|item,index| b.set(item+(index%2), 1.0)})
b.play

// create a new buffer as destinations
c = Buffer.new(s);

//run the process on them
(
// with basic params
Routine{
    t = Main.elapsedTime;
    FluidBufOnsetSlice.process(s,b, indices: c, threshold:0.00001);
    (Main.elapsedTime - t).postln;
}.play
)

// list the indicies of detected attacks - the two input channels have been summed
c.getn(0,c.numFrames,{|item|(item * 2).postln;})
::