TITLE:: FluidNoveltySlice
SUMMARY:: Real-Time Novelty-Based Slicer
CATEGORIES:: Libraries>FluidDecomposition
RELATED:: Guides/FluCoMa, Guides/FluidDecomposition

DESCRIPTION::
This class implements a real-time slicer using an algorithm assessing novelty in the signal to estimate the slicing points. A novelty curve is being derived from running a kernel across the diagonal of the similarity matrix, and looking for peak of changes. It implements the seminal results published in  'Automatic Audio Segmentation Using a Measure of Audio Novelty' by J Foote.  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 an audio steam with sample-long impulses at estimated starting points of the different slices.


CLASSMETHODS::

METHOD:: ar
	The audio rate version of the object.

ARGUMENT:: in
	The audio to be processed.

ARGUMENT:: feature
	The feature on which novelty is computed.
		table::
	##0 || Spectrum || The magnitude of the full spectrum.
	##1 || MFCC || 13 Mel-Frequency Cepstrum Coefficients.
	##2 || Pitch || The pitch and its confidence.
	##3 || Loudness || The TruePeak and Loudness.
::
ARGUMENT:: kernelSize
	The granularity of the window in which the algorithm looks for change, in samples. A small number will be sensitive to short term changes, and a large number should look for long term changes.

ARGUMENT:: threshold
	The normalised threshold, between 0 an 1, on the novelty curve to consider it a segmentation point.

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:: minSliceLength
	The minimum duration of a slice in number of hopSize.

ARGUMENT:: windowSize
	The window size. As sinusoidal estimation 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 windowSize.

ARGUMENT:: maxFFTSize
	How large can the FFT be, by allocating memory at instantiation time. This cannot be modulated.

ARGUMENT:: maxKernelSize
	This cannot be modulated.

ARGUMENT:: maxFilterSize
	This cannot be modulated.

RETURNS::
	An audio stream with impulses at detected transients. The latency between the input and the output is STRONG::windowSize + (hopSize * (((kernelSize+1)/2) + (filterSize / 2))):: samples at minimum.

EXAMPLES::

code::
//load some sounds
b = Buffer.read(s,File.realpath(FluidNoveltySlice.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Nicol-LoopE-M.wav");

// basic param (the process add a latency of windowSize samples
{var sig = PlayBuf.ar(1,b,loop:1); [FluidNoveltySlice.ar(sig,0,11,0.33) * 0.5, DelayN.ar(sig, 1, (1024 + (512 * (((11+1)/2) + (1 / 2))))/ s.sampleRate, 0.2)]}.play

// other parameters
{var sig = PlayBuf.ar(1,b,loop:1); [FluidNoveltySlice.ar(sig, 1, 31, 0.0035, 4, 100, 128, 32) * 0.5, DelayN.ar(sig, 1, (128 + (32 * (((31+1)/2) + (4 / 2))))/ s.sampleRate,0.2)]}.play

// More musical, novelty-trigged autopan
(
{
    var sig, trig, syncd, pan;
    sig = PlayBuf.ar(1,b,loop:1);
    trig = FluidNoveltySlice.ar(sig, 0, 11, 0.25, 5, 1, 128, 32);
    syncd = DelayN.ar(sig, 1, (128 + (32 * (((11+1)/2) + (5 / 2))))/ s.sampleRate);
    pan = TRand.ar(-1,1,trig);
    Pan2.ar(syncd,pan);
}.play
)
::