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

TITLE:: FluidBufTransientSlice
SUMMARY:: Buffer-Based Transient-Based Slicer
CATEGORIES:: Libraries>FluidDecomposition, UGens>Buffer
RELATED:: Guides/FluCoMa, Guides/FluidDecomposition, Classes/FluidBufTransients


DESCRIPTION::
This class implements a non-real-time transient-based slice extractor relying on the same algorithm than Classes/FluidBufTransients using clicks/transients/derivation/anomaly in the signal to estimate the slicing points. It is part of the Fluid Decomposition Toolkit of the FluCoMa project.footnote::This  was made possible thanks to the FluCoMa project ( http://www.flucoma.org/ ) funded by the European Research Council ( https://erc.europa.eu/ ) under the European Union’s Horizon 2020 research and innovation programme (grant agreement No 725899).::

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


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 transient 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 srcBuf, which channel should be processed.

ARGUMENT:: numChans
	For multichannel srcBuf, 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:: order
	The order in samples of the impulse response filter used to model the estimated continuous signal. It is how many previous samples are used by the algorithm to predict the next one as reference for the model. The higher the order, the more accurate is its spectral definition, not unlike fft, improving low frequency resolution, but it differs in that it is not conected to its temporal resolution.

ARGUMENT:: blockSize
	The size in samples of frame on which it the algorithm is operating. High values are more cpu intensive, and also determines the maximum transient size, which will not be allowed to be more than half that lenght in size.

ARGUMENT:: padSize
	The size of the handles on each sides of the block simply used for analysis purpose and avoid boundary issues.

ARGUMENT:: skew
	The nervousness of the bespoke detection function with values from -10 to 10. It allows to decide how peaks are amplified or smoothed before the thresholding. High values increase the sensitivity to small variations.

ARGUMENT:: threshFwd
	The threshold of the onset of the smoothed error function. It allows tight start of the identification of the anomaly as it proceeds forward.

ARGUMENT:: threshBack
	The threshold of the offset of the smoothed error function. As it proceeds backwards in time, it allows tight ending of the identification of the anomaly.

ARGUMENT:: windowSize
	The averaging window of the error detection function. It needs smoothing as it is very jittery. The longer the window, the less precise, but the less false positives.

ARGUMENT:: clumpLength
	The window size in sample within which positive detections will be clumped together to avoid overdetecting in time.

ARGUMENT:: minSliceLength
	The minimum duration of a slice in samples.

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::
// load some buffers
(
b = Buffer.read(s,File.realpath(FluidBufTransientSlice.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Tremblay-AaS-SynthTwoVoices-M.wav");
c = Buffer.new(s);
)

// with basic parameters (wait for the computation time to appear)
(
	Routine{
	t = Main.elapsedTime;
	FluidBufTransientSlice.process(s,b, indices:c);
	(Main.elapsedTime - t).postln;
}.play
)

//check the number of slices
c.query;

//loops over a splice
(
{
    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;
)

// with everything changed to make it much better, at the cost of computation time (only 10 seconds are processed here, again wait for the (longer) computation time to appear)
(
Routine{
	t = Main.elapsedTime;
	FluidBufTransientSlice.process(s,b, 0, 220500, 0, 1, c, 200, 2048, 1024, 1, 3, 1, 15, 30, 4410);
	(Main.elapsedTime - t).postln;
}.play
)

// play with the same player above to hear the segmentation difference
::

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;
    FluidBufTransientSlice.process(s,b, indices: c, threshFwd: 1.2);
    (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.postln;})
::