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

TITLE:: FluidBufChroma
SUMMARY:: An histogram of pitch classes on a Buffer
CATEGORIES:: Libraries>FluidCorpusManipulation
RELATED::  Guides/FluidCorpusManipulation, Guides/FluidBufMultiThreading, Classes/FluidChroma

DESCRIPTION::
This class computes a histogram of the energy contained for each pitch class across the analysis frequency range. Also known as a chromagram, this typically allows you to get a contour of how much each semitone is represented in the spectrum over time. The number of bands (and, thus, pitch classes) and the central reference frequency can be adjusted.

The process will return a single multichannel buffer of STRONG::numChroma:: per input channel. Each frame represents a value, which is every hopSize.

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, processBlocking
	This is the method that calls for the chromagram 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 analysed. The different channels of multichannel buffers will be processing sequentially.

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

ARGUMENT:: numFrames
	How many frames should be processed.

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

ARGUMENT:: numChans
	For multichannel srcBuf, how many channel should be processed.

ARGUMENT:: features
	The destination buffer for the STRONG::numChroma:: to be written to.

ARGUMENT:: numChroma
	The number of chroma bands per octave. It will determine how many channels are output per input channel.

ARGUMENT:: ref
	The frequency of reference in Hz for the tuning of the middle A (default: 440 Hz)

ARGUMENT:: normalize
This flag enables the scaling of the output. It is off (0) by default. (1) will normalise each frame to sum to 1. (2) normalises each frame relative to the loudest chroma being 1.

ARGUMENT:: minFreq
	The lower frequency included in the analysis, in Hz.

ARGUMENT:: maxFreq
	The highest frequency included in the analysis, in Hz.

ARGUMENT:: windowSize
	The window size. As chroma computation 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 chroma computation 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:: padding
	Controls the zero-padding added to either end of the source buffer or segment. Possible values are 0 (no padding), 1 (default, half the window size), or 2 (window size - hop size). Padding ensures that all input samples are completely analysed: with no padding, the first analysis window starts at time 0, and the samples at either end will be tapered by the STFT windowing function. Mode 1 has the effect of centering the first sample in the analysis window and ensuring that the very start and end of the segment are accounted for in the analysis. Mode 2 can be useful when the overlap factor (window size / hop size) is greater than 2, to ensure that the input samples at either end of the segment are covered by the same number of analysis frames as the rest of the analysed material.

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 [features] as an argument.

returns:: an instance of the processor

EXAMPLES::

code::
// create some buffers
(
b = Buffer.read(s,File.realpath(FluidBufChroma.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Tremblay-SlideChoirAdd-M.wav");
c = Buffer.new(s);
)

// run the process with basic parameters
(
Routine{
	t = Main.elapsedTime;
	FluidBufChroma.process(s, b, features: c, windowSize: 4096).wait;
	(Main.elapsedTime - t).postln;
}.play
)

// listen to the source and look at the buffer
b.play;
c.plot
::

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

// load two very different files
(
b = Buffer.read(s,File.realpath(FluidBufChroma.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Tremblay-SA-UprightPianoPedalWide.wav");
c = Buffer.read(s,File.realpath(FluidBufChroma.class.filenameSymbol).dirname.withTrailingSlash ++ "../AudioFiles/Tremblay-AaS-AcousticStrums-M.wav");
)

// composite one on left one on right as test signals
FluidBufCompose.process(s, c, numFrames:b.numFrames, startFrame:555000,destStartChan:1, destination:b)
b.play

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

//run the process on them
(
Routine{
    t = Main.elapsedTime;
	FluidBufChroma.process(s, b, features: c, windowSize: 4096).wait;
    (Main.elapsedTime - t).postln;
}.play
)

// look at the buffer: 10 bands for left, then 10 bands for right
c.plot(separately:true)
::