From f7e1f4c4aaefe088ccdb24a050e033b8ac6c32da Mon Sep 17 00:00:00 2001 From: Ted Moore Date: Thu, 3 Feb 2022 13:17:17 -0500 Subject: [PATCH] FluidChroma and FluidBufChroma help files alignment --- release-packaging/Classes/FluidBufChroma.sc | 6 +- release-packaging/Classes/FluidChroma.sc | 2 +- .../HelpSource/Classes/FluidBufChroma.schelp | 306 ++++++++++++++++-- .../HelpSource/Classes/FluidChroma.schelp | 121 +++++-- 4 files changed, 381 insertions(+), 54 deletions(-) diff --git a/release-packaging/Classes/FluidBufChroma.sc b/release-packaging/Classes/FluidBufChroma.sc index a31fe02..ed8fba5 100644 --- a/release-packaging/Classes/FluidBufChroma.sc +++ b/release-packaging/Classes/FluidBufChroma.sc @@ -1,5 +1,5 @@ FluidBufChroma : FluidBufProcessor { - *kr { |source, startFrame = 0, numFrames = -1, startChan = 0, numChans = -1, features, numChroma = 12, ref = 440, minFreq = 0, maxFreq = -1, normalize = 0, windowSize = 1024, hopSize = -1, fftSize = -1, padding = 1, trig = 1, blocking = 0| + *kr { |source, startFrame = 0, numFrames = -1, startChan = 0, numChans = -1, features, numChroma = 12, ref = 440, normalize = 0,minFreq = 0,maxFreq = -1, windowSize = 1024, hopSize = -1, fftSize = -1, padding = 1, trig = 1, blocking = 0| var maxFFTSize = if (fftSize == -1) {windowSize.nextPowerOfTwo} {fftSize}; @@ -12,7 +12,7 @@ FluidBufChroma : FluidBufProcessor { ^FluidProxyUgen.kr(\FluidBufChromaTrigger,-1, source, startFrame, numFrames, startChan, numChans, features, padding, numChroma, ref, normalize, minFreq, maxFreq, numChroma, windowSize, hopSize, fftSize, maxFFTSize, trig, blocking); } - *process { |server, source, startFrame = 0, numFrames = -1, startChan = 0, numChans = -1, features, numChroma = 12, ref = 440, minFreq = 0, maxFreq = -1, normalize = 0, windowSize = 1024, hopSize = -1, fftSize = -1, padding = 1, freeWhenDone = true, action| + *process { |server, source, startFrame = 0, numFrames = -1, startChan = 0, numChans = -1, features, numChroma = 12, ref = 440, normalize = 0,minFreq = 0,maxFreq = -1, windowSize = 1024, hopSize = -1, fftSize = -1, padding = 1, freeWhenDone = true, action| var maxFFTSize = if (fftSize == -1) {windowSize.nextPowerOfTwo} {fftSize}; @@ -29,7 +29,7 @@ FluidBufChroma : FluidBufProcessor { ); } - *processBlocking { |server, source, startFrame = 0, numFrames = -1, startChan = 0, numChans = -1, features, numChroma = 12, ref = 440, minFreq = 0, maxFreq = -1, normalize = 0, windowSize = 1024, hopSize = -1, fftSize = -1, padding = 1, freeWhenDone = true, action| + *processBlocking { |server, source, startFrame = 0, numFrames = -1, startChan = 0, numChans = -1, features, numChroma = 12, ref = 440, normalize = 0,minFreq = 0,maxFreq = -1, windowSize = 1024, hopSize = -1, fftSize = -1, padding = 1, freeWhenDone = true, action| var maxFFTSize = if (fftSize == -1) {windowSize.nextPowerOfTwo} {fftSize}; diff --git a/release-packaging/Classes/FluidChroma.sc b/release-packaging/Classes/FluidChroma.sc index 77b8806..50c1a7a 100644 --- a/release-packaging/Classes/FluidChroma.sc +++ b/release-packaging/Classes/FluidChroma.sc @@ -1,6 +1,6 @@ FluidChroma : FluidRTMultiOutUGen { - *kr { arg in = 0, numChroma = 12, ref = 440, minFreq = 0, maxFreq = -1, normalize = 0, windowSize = 1024, hopSize = -1, fftSize = -1, maxFFTSize = 16384, maxNumChroma = 120; + *kr { arg in = 0, numChroma = 12, ref = 440, normalize = 0, minFreq = 0, maxFreq = -1, windowSize = 1024, hopSize = -1, fftSize = -1, maxNumChroma = 120, maxFFTSize = 16384; ^this.multiNew('control', in.asAudioRateInput(this), numChroma, ref, normalize, minFreq, maxFreq, maxNumChroma, windowSize, hopSize, fftSize, maxFFTSize); } diff --git a/release-packaging/HelpSource/Classes/FluidBufChroma.schelp b/release-packaging/HelpSource/Classes/FluidBufChroma.schelp index 43f71c5..25fd4ea 100644 --- a/release-packaging/HelpSource/Classes/FluidBufChroma.schelp +++ b/release-packaging/HelpSource/Classes/FluidBufChroma.schelp @@ -1,78 +1,328 @@ TITLE:: FluidBufChroma -SUMMARY:: An histogram of pitch classes on a Buffer +SUMMARY:: A histogram of pitch classes on a Buffer CATEGORIES:: Libraries>FluidCorpusManipulation -RELATED:: Guides/FluidCorpusManipulation, Guides/FluidBufMultiThreading, Classes/FluidChroma - +RELATED:: Classes/FluidChroma,Classes/FluidBufPitch,Classes/FluidBufLoudness,Classes/FluidBufMFCC,Classes/FluidBufSpectralShape,Classes/FluidBufStats,Guides/FluidCorpusManipulationToolkit,Classes/FluidBufMFCC 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 chroma bins (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. + + This class computes a histogram of the energy contained for each pitch class across the analysis frequency range. + -STRONG::Threading:: + + 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 chroma bins (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. -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. + Processs the source LINK::Classes/Buffer:: on the LINK::Classes/Server::. CODE::processBlocking:: will execute directly in the server command FIFO, whereas CODE::process:: will delegate to a separate worker thread. The latter is generally only worthwhile for longer-running jobs where you don't wish to tie up the server. ARGUMENT:: server - The server on which the buffers to be processed are allocated. + The LINK::Classes/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. + + + 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. + + + Where in the srcBuf should the process start, in sample. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 0 + + :: ARGUMENT:: numFrames - How many frames should be processed. + + + How many frames should be processed. + ARGUMENT:: startChan - For multichannel srcBuf, which channel should be processed first. + + + For multichannel srcBuf, which channel should be processed first. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 0 + + :: ARGUMENT:: numChans - For multichannel srcBuf, how many channel should be processed. + + + For multichannel srcBuf, how many channel should be processed. + ARGUMENT:: features - The destination buffer for the STRONG::numChroma:: to be written to. + + + The destination buffer for the STRONG::numChroma:: to be written to. + ARGUMENT:: numChroma - The number of chroma bins per octave. It will determine how many channels are output per input channel. + + + The number of chroma bins per octave. It will determine how many channels are output per input channel. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 2 + + ## + Maximum: CODE::maxNumChroma:: + + :: ARGUMENT:: ref - The frequency of reference in Hz for the tuning of the middle A (default: 440 Hz) + + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 0 + + ## + Maximum: 22000 + + :: + +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 bin being 1. + ARGUMENT:: minFreq - The lower frequency included in the analysis, in Hz. + + + The lower frequency included in the analysis, in Hz. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 0 + + :: ARGUMENT:: maxFreq - The highest frequency included in the analysis, in 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 bin being 1. + + The highest frequency included in the analysis, in Hz. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: -1 + + :: 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 + + + The window size. As chroma description relies on spectral frames, we need to decide what precision we give it spectrally and temporally, in line with Gabor Uncertainty principles. LINK::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). + + + The window hop size. As chroma description relies on spectral frames, we need to move the window forward. It can be any size but low overlap will create audible artefacts. + 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. + + + 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. + 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. + + 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 + Free the server instance when processing complete. Default CODE::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. + 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 CODE::[features]:: as an argument. + +RETURNS:: An instance of the processor + +METHOD:: kr + Trigger the equivalent behaviour to CODE::processBlocking / process:: from a LINK::Classes/Synth::. Can be useful for expressing a sequence of buffer and data processing jobs to execute. Note that the work still executes on the server command FIFO (not the audio thread), and it is the caller's responsibility to manage the sequencing, using the CODE::done:: status of the various UGens. +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. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 0 + + :: + +ARGUMENT:: numFrames + + + How many frames should be processed. + + +ARGUMENT:: startChan + + + For multichannel srcBuf, which channel should be processed first. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 0 + + :: + +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 bins per octave. It will determine how many channels are output per input channel. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 2 + + ## + Maximum: CODE::maxNumChroma:: + + :: + +ARGUMENT:: ref + + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 0 + + ## + Maximum: 22000 + + :: + +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 bin being 1. + + +ARGUMENT:: minFreq + + + The lower frequency included in the analysis, in Hz. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 0 + + :: + +ARGUMENT:: maxFreq + + + The highest frequency included in the analysis, in Hz. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: -1 + + :: + +ARGUMENT:: windowSize + + + The window size. As chroma description relies on spectral frames, we need to decide what precision we give it spectrally and temporally, in line with Gabor Uncertainty principles. LINK::http://www.subsurfwiki.org/wiki/Gabor_uncertainty:: + + +ARGUMENT:: hopSize + + + The window hop size. As chroma description relies on spectral frames, we need to move the window forward. It can be any size but low overlap will create audible artefacts. + + +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. + + +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:: trig + A CODE::kr:: signal that will trigger execution + +ARGUMENT:: blocking + Whether to execute this process directly on the server command FIFO or delegate to a worker thread. See CODE::processBlocking/process:: for caveats. + + +INSTANCEMETHODS:: +METHOD:: kr + Returns a UGen that reports the progress of the running task when executing in a worker thread. Calling code::scope:: with this can be used for a convinient progress monitor -returns:: an instance of the processor +METHOD:: cancel + Cancels non-blocking processing +METHOD:: wait + When called in the context of a LINK::Classes/Routine:: (it won't work otherwise), will block execution until the processor has finished. This can be convinient for writing sequences of processes more linearly than using lots of nested actions. + EXAMPLES:: code:: diff --git a/release-packaging/HelpSource/Classes/FluidChroma.schelp b/release-packaging/HelpSource/Classes/FluidChroma.schelp index a476b9d..ece7bf4 100644 --- a/release-packaging/HelpSource/Classes/FluidChroma.schelp +++ b/release-packaging/HelpSource/Classes/FluidChroma.schelp @@ -1,57 +1,134 @@ TITLE:: FluidChroma -SUMMARY:: An histogram of pitch classes in Real-Time +SUMMARY:: A histogram of pitch classes in Real-Time CATEGORIES:: Libraries>FluidCorpusManipulation -RELATED:: Guides/FluidCorpusManipulation, Classes/FluidBufChroma - +RELATED:: Classes/FluidBufChroma,Classes/FluidPitch,Classes/FluidLoudness,Classes/FluidMFCC,Classes/FluidSpectralShape,Guides/FluidCorpusManipulationToolkit,Classes/FluidMFCC 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 chroma bins (and, thus, pitch classes) and the central reference frequency can be adjusted. -It is part of the LINK:: Guides/FluidCorpusManipulation##Fluid Corpus Manipulation Toolkit::. For more explanations, learning material, and discussions on its musicianly uses, visit http://www.flucoma.org/ + + 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 chroma bins (and, thus, pitch classes) and the central reference frequency can be adjusted. + + The process will return a multichannel control steam of size maxNumChroma, which will be repeated if no change happens within the algorithm, i.e. when the hopSize is larger than the signal vector size. -The process will return a multichannel control steam of size STRONG::maxNumChroma::, which will be repeated if no change happens within the algorithm, i.e. when the hopSize is larger than the server's kr period. CLASSMETHODS:: METHOD:: kr - The audio rate in, control rate out version of the object. ARGUMENT:: in - The audio to be processed. + + Audio-rate signal to analyze ARGUMENT:: numChroma - The number of chroma bins per octave. It will determine how many channels of the output stream are filled. + + + The number of chroma bins per octave. It will determine how many channels are output per input channel. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 2 + + ## + Maximum: CODE::maxNumChroma:: + + :: ARGUMENT:: ref - The reference frequency in Hz for the tuning to middle A (default: 440 Hz) + + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 0 + + ## + Maximum: 22000 + + :: + +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 bin being 1. + ARGUMENT:: minFreq - The lower frequency included in the analysis, in Hz. + + + The lower frequency included in the analysis, in Hz. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 0 + + :: ARGUMENT:: maxFreq - The highest frequency included in the analysis, in 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 bin being 1. + + The highest frequency included in the analysis, in Hz. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: -1 + + :: 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 + + + 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. LINK::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). + + + 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. + + 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 default to windowSize. + + ARGUMENT:: maxNumChroma - The maximum number of chroma bins. This sets the number of channels of the output stream, and therefore cannot be modulated. -RETURNS:: - A KR signal of STRONG::maxNumChroma:: channels, giving the measure amplitudes for each chroma bin. The latency is windowSize. + + The maximum number of chroma bins. This sets the number of channels of the output stream, and therefore cannot be modulated. + + STRONG::Constraints:: + + LIST:: + ## + Minimum: 2 + + ## + Maximum: (max FFFT Size / 2) + 1`` (see maxFFTSize) + + :: + +ARGUMENT:: maxFFTSize + + + How large can the FFT be, by allocating memory at instantiation time. This cannot be modulated. + + +INSTANCEMETHODS:: + EXAMPLES:: code::