From dc45022e64e7c11a9b0c499a78c7438006abd2fc Mon Sep 17 00:00:00 2001 From: James Bradbury Date: Fri, 24 Jun 2022 13:51:49 +0100 Subject: [PATCH 1/5] [Release] 1.0.0 (#158) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * mfcc rst and sc help file * mfcc sc examples * mfcc output * mfcc helpfile readability * BufMFCC udpates * update bufonsetslice docs slightly (#87) * fix audio transport segmentation of discussion and desc * fix audio transport segmentation of discussion and desc (#88) * add missing see alsos * optional args: add to C++ wrapper * ParamDump and python: add choices param type * Json driver (#35) * Make jinja rendering conditional on driver having a template * minimal driver for raw JSON output * cmake target for raw JSON * fix cmake output directory * add command line option for raw * remove spurious item from raw driver * add back changes that dealt with conditional template rendering * add a github action for creating a basic API on actions Co-authored-by: James Bradbury * Update json_api.yml * Update json_api.yml * Update json_api.yml * change name of raw output to api.json * Update json_api.yml * remove indentation on api * typo in UMAP * [Docs] OnsetSlice and BufOnsetSlice (#91) * update bufonsetslice text * onsetslice update * ted's changes * copy changes to bufonsetslice also * revamp MelBands and BufMelBands RST, update SC example code * *melbands description * added a hyphen * pitch and buf pitch RST * added link to the learn page * edited normalize description * pitch sc help files * BufFlatten RST and SC examples * buf thresh * sc help file * typo in fluid pitch sc example code * bufthresh rst * typo * james' feedback * add .ds_store to gitignore * pa feedback * pa feedback * pa feedback * PA feedback * [Docs] Update Normalize Docs (#76) * update normalize entry * update description * pa's requests Co-authored-by: James Bradbury * [Docs] Slicer Feature Objects (#101) * add skeleton of bufnoveltyfeature * caveat novelty feature * add onset feature * remove space * add bufampfeature * realtime amp feature * update output of AmpFeature * clean up the language * caveats for bufonset feature * add onset feature * Add JSON generators for Slicers' feature counterparts * rt noveltyfeature * fix various errors * robots in disguise * change feature -> algorithm * cleanup noveltyfeature * make noveltyfeature more consistent * remove superfluous spaces * fix description * fix reference to buffer version in rt object * add padding * sc example code for slicer-features Co-authored-by: weefuzzy Co-authored-by: Ted Moore * changing preset and interface for noveltyslice examples * Add argument handlers for const DataSet / LabelSet * Max/PD: Generate docs for control-in objects (input size and autosize) * Enhance/max params (#104) * CMake: Centralise C++ version and set to 17 * Wrapper: Handle new LongRuntimeMax parameter type * Doc generators: Handle new LongRuntimeMax type + rules for args in Max/PD * Add a `striprst` jinja filter for removing rst markup in templates (#107) Such as Max object level description tags * UMAP cmake reference to python sorted * typo * Wrapper and doc-gen update for new `maxFFTSize` * Buf stats (#103) * BufStats RST * BufStats ⚠️ * bufstats supercollider examples * re-organized descriptions * added table back in * typo * added url * bufcompose update (#95) * PCA inverseTransformPoint (#97) * PCA inverseTransformPoint * added inverseTransform to PCA RST * off by one white space 😠 * normalize the desc/disc of mfcc entries (#113) * HPSS Help file (RST) and SC examples (#81) * HPSS rst edited and SC examples created * pa feedback * Enhance/generate stubs (#119) * CMake: Generate cpp stubs, smooth out API for dependent projects * Remove old stubs and scripts * CMake: Ensure correct MSVC runtime by default * Correct variable setting logic in macro * CI: Debug CMAKE_MODULE_PATH * CMake: Try setting module path using explicit source dir for core * CI Debug: Print core/scripts * CMake: Correct typo * CMake: MSVC with bigobj, tidy up messages * set explicit UTF8 encoding when opening text * explicitly use utf8 for writing as well as reading * MDS RST & SC example code (#121) * MLPClassifier SC example code * MLPClassifier SC example code ⚠️ * MLPs SC example code and RSTs ⚠️ * ⚠️ * ⚠️ * wip * MLP RSTs * [FIX] this commit adds code to the SC templates to allow enums in the RST to appear in the species data * feedback * hidden -> hiddenLayers * ⚠️ * sc example ⚠️ * sc example code * bump * typo * removed cosine * weefuzzy and james feedback * fixed plot size * MLPRegressor & MLPClassifier RSTs & SC example Code (#109) * MLPClassifier SC example code * MLPClassifier SC example code ⚠️ * MLPs SC example code and RSTs ⚠️ * ⚠️ * ⚠️ * wip * MLP RSTs * [FIX] this commit adds code to the SC templates to allow enums in the RST to appear in the species data * feedback * hidden -> hiddenLayers * Standardize RST & SC examples (#117) * Standardize RST & SC example code * removed the 'invert' argument * added discussion * RobustScale (#118) * ⚠️ * RobustScale RST * RobustScale SC example code * bump * added discussion * KNNClassifier RST and SC example code (#127) * KNN ⚠️ * reset knnregressor.rst * Stats RST & SC examples (#124) * Stats RST and SC code * stats rst and sc code * feedback * PCA RST and SC Examples (#116) * PCA RST * PCA SC example code * sc example code with whitening example * added discussion * james' feedback Co-authored-by: James Bradbury * Update Standardize.rst Fix indentation error that caused mis-parsing * maxFFTSize in SC driver is conditional on buffer-proc species (#129) * BufSTFT RST and SC example code (#112) * BufSTFT RST and SC example code * added discussion * typo * [Enhance] Learn platform link generation (#120) * update default transformer to handle learn links * update maxref template to acount for learn link * add link to templates discussion * compartmentalise the learn link derivation * update the supercollider driver which doesnt use default transform * use a regex instead of object map * update derivation of learn links * add test for link derivation * typo * bufnmf: adding resynthmode * resynthMode : camel case * Change size to history (#133) * BufNMFCross RST & SC example (#137) * NNDSVD (#138) * ⚠️ * BufNNDSVD RST & SC examples * NNDSVD RST with descriptions of method * add token for |buffer| * feedback Co-authored-by: James Bradbury * NMFMorph (& species transformer[0]) (#135) * NMFMorph RST and SC examples * NMFMorph * NMFMorph (and species transformer[0]) * separate discussion and description * added comment about why autoassign is set twice Co-authored-by: James Bradbury * put bar chart back in (#123) * KNNRegressor (#136) * KNNRegressor RST & SC examples * fixed sc code formatting * separate discussion and description! * (Buf)Transients(Slice) Family (#140) * transients RST * ⚠️ * ⚠️ * more sc examples for transients family * feedback from owen and alex * feedback round 1 * feedback * typos in rst * typos in knnclassifier~ (#142) * sc example code for BufNMF now includes resynthMode * deleted SC Guid YAML file * put spaces around hyperlinks * BufTransients SC example (Waveform only 2 sec.) * BufNNDSVD -> BufNMFSeed (#141) * change the doc * forgot to change the code sample file name * fix Loudness select in MLPRegressor example code * fix bad link in nmf morph (BufNMFCross was missing the buf part) * added inverse transform and inverse transform point to Normalize * better code for testing all flucoma objects help files * added argument k to KDTree RST * fixed a bad link in KNNClassifier RST * removed action arguments from RobustScale RST * fixed mistakes in RobustScale RST that was causing it to not render properly * added select argument to BufLoudness and Loudness RST (the rest coming soon...) * added pca whitening to PCA RST * adding select argument to appropriate RST files it would be nicer to have them in list form... TODO * added radius argument to KDTree RST * added channels argument to BufSelect RST * checked example code files that use 'select' for possible errors * found a bit more code needing resynthMode * [Enhance] Interp to Interplation in NMFMorph (#143) * typos in knnclassifier~ * change interp to interpolation for nmfmorph * SKMeans (#132) * skmeans doc commit * skmeans: attempt at better doc * example code a little more explicit * typos found in kmeans * update from @weefuzzy feedback - less untrue in most cases :) * transform -> encode * (Buf)AmpGate RST & SC examples (#122) * (Buf)AmpGate RST & SC examples * BufAmpGate help file ⚠️ * drum hit example ⚠️ * ⚠️ * gitignore to ignore vs code * pa feedback * added BufAmpGate maxSize parameter * [Fix] Fix Guide Links in RST (#147) * typos in knnclassifier~ * fix guide link * [Fix] LF line ending enforcement (#149) * typos in knnclassifier~ * enforce newline='\n' on template writing * interface changes * capitalise beatRemember * Fix `` links to `buffer~` for max doc * Mop up vestigial scdoc syntax * correct reference to "class" in description * [fix] typos and errors (#153) * various typos * remove hyphen * more typos * various typos/non-grammatical errors * typos in example code * remove bufNum * fix low/mid/ min/median confusion * [docs] Update see-also content (#155) * update seealso * realign table * [docs] Buffer clients link to buffer management tutorial (#157) * if client starts with buf link to buffer management tutorial * use full name of guide * use name of .maxvig rather than name attribute of * also dataset objects * proposed layout improvement (#154) * add outward links to RST and templat --- doc/AmpFeature.rst | 1 + doc/AmpGate.rst | 3 ++- doc/AmpSlice.rst | 9 +++++---- doc/AudioTransport.rst | 2 +- doc/BufAmpFeature.rst | 16 ++++++++++++++-- doc/BufAmpGate.rst | 5 +++-- doc/BufAmpSlice.rst | 9 +++++---- doc/BufAudioTransport.rst | 2 +- doc/BufChroma.rst | 17 ++++++++++++++--- doc/BufCompose.rst | 13 +++++++------ doc/BufFlatten.rst | 3 ++- doc/BufHPSS.rst | 8 ++++---- doc/BufLoudness.rst | 18 +++++++++++++++--- doc/BufMFCC.rst | 22 +++++++++++++++++----- doc/BufMelBands.rst | 19 +++++++++++++++---- doc/BufNMF.rst | 20 ++++++++++---------- doc/BufNMFCross.rst | 4 ++-- doc/BufNMFSeed.rst | 4 ++-- doc/BufNoveltyFeature.rst | 17 ++++++++++++++--- doc/BufNoveltySlice.rst | 10 +++++----- doc/BufOnsetFeature.rst | 19 +++++++++++++++---- doc/BufOnsetSlice.rst | 8 ++++---- doc/BufPitch.rst | 22 +++++++++++++++++----- doc/BufSTFT.rst | 16 ++++++++++++++-- doc/BufScale.rst | 1 + doc/BufSelect.rst | 1 + doc/BufSelectEvery.rst | 1 + doc/BufSines.rst | 4 ++-- doc/BufSpectralShape.rst | 19 +++++++++++++++---- doc/BufStats.rst | 12 ++++++------ doc/BufThreadDemo.rst | 9 +++------ doc/BufTransientSlice.rst | 8 ++++---- doc/BufTransients.rst | 10 +++++----- doc/Chroma.rst | 4 ++-- doc/DataSet.rst | 7 ++++--- doc/DataSetQuery.rst | 9 ++++----- doc/Gain.rst | 4 ++-- doc/Grid.rst | 2 +- doc/HPSS.rst | 4 ++-- doc/KMeans.rst | 8 ++++---- doc/KNNClassifier.rst | 2 +- doc/KNNRegressor.rst | 4 ++-- doc/LabelSet.rst | 2 +- doc/Loudness.rst | 5 +++-- doc/MDS.rst | 6 +++--- doc/MFCC.rst | 8 ++++---- doc/MLPClassifier.rst | 8 +++++--- doc/MLPRegressor.rst | 8 +++++--- doc/MelBands.rst | 2 +- doc/NMFFilter.rst | 10 +++++----- doc/NMFMatch.rst | 12 ++++++------ doc/Normalize.rst | 8 ++++---- doc/NoveltyFeature.rst | 4 ++-- doc/NoveltySlice.rst | 20 ++++++++++---------- doc/OnsetFeature.rst | 6 +++--- doc/OnsetSlice.rst | 6 +++--- doc/PCA.rst | 6 +++--- doc/Pitch.rst | 3 ++- doc/RobustScale.rst | 8 ++++---- doc/SKMeans.rst | 8 ++++---- doc/STFTPass.rst | 4 ++-- doc/Sines.rst | 4 ++-- doc/SpectralShape.rst | 12 ++++++------ doc/Standardize.rst | 10 +++++----- doc/Stats.rst | 2 +- doc/TransientSlice.rst | 14 +++++++------- doc/Transients.rst | 14 +++++++------- doc/UMAP.rst | 4 ++-- example-code/sc/BufAudioTransport.scd | 2 +- example-code/sc/BufNMF.scd | 6 +++--- example-code/sc/HPSS.scd | 4 ++-- example-code/sc/KDTree.scd | 14 +++++++------- example-code/sc/MFCC.scd | 10 ++++++---- example-code/sc/MLPClassifier.scd | 2 +- example-code/sc/NMFFilter.scd | 16 ++++++++-------- flucoma/doc/max/driver.py | 14 +++++++++++--- flucoma/doc/render.py | 2 +- flucoma/doc/rst/docutils.py | 13 ++++++++++++- flucoma/doc/rst/html.py | 19 ++++++++++++++++--- flucoma/doc/templates/maxref.xml | 6 ++++++ spellcheck.py | 18 ++++++++++++++++++ 81 files changed, 441 insertions(+), 255 deletions(-) create mode 100644 spellcheck.py diff --git a/doc/AmpFeature.rst b/doc/AmpFeature.rst index 37bacbe3..bfd3ebe3 100644 --- a/doc/AmpFeature.rst +++ b/doc/AmpFeature.rst @@ -3,6 +3,7 @@ :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation :see-also: AmpGate, AmpSlice, OnsetFeature, NoveltyFeature +:max-seealso: peakamp~, meter~, snapshot~, slide~ :description: Calculate the amplitude differential feature in realtime. :discussion: :fluid-obj:`AmpSlice` uses the differential between a fast and a slow envelope follower to determine changes in amplitude. This object calculates the amplitude differential and copies it to an output buffer. diff --git a/doc/AmpGate.rst b/doc/AmpGate.rst index 4066c394..4a95c649 100644 --- a/doc/AmpGate.rst +++ b/doc/AmpGate.rst @@ -3,7 +3,8 @@ :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation :see-also: BufAmpGate, AmpSlice, OnsetSlice, NoveltySlice, TransientSlice -:description: Absolute amplitude threshold gate detector on a real-time signal +:max-seealso: peakamp~, meter~, snapshot~, slide~ +:description: Absolute amplitude threshold gate detector on a realtime signal :discussion: AmpGate outputs a audio-rate, single-channel signal that is either 0, indicating the gate is closed, or 1, indicating the gate is open. The gate detects an onset (opens) when the internal envelope follower (controlled by ``rampUp`` and ``rampDown``) goes above a specified ``onThreshold`` (in dB) for at least ``minLengthAbove`` samples. The gate will stay open until the envelope follower goes below ``offThreshold`` (in dB) for at least ``minLengthBelow`` samples, which triggers an offset. diff --git a/doc/AmpSlice.rst b/doc/AmpSlice.rst index f4d773fb..1f8adfcb 100644 --- a/doc/AmpSlice.rst +++ b/doc/AmpSlice.rst @@ -3,11 +3,12 @@ :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation :see-also: BufAmpSlice, AmpGate, OnsetSlice, NoveltySlice, TransientSlice -:description: This class implements an amplitude-based slicer, with various customisable options and conditions to detect relative amplitude changes as onsets. +:max-seealso: peakamp~, meter~, snapshot~, slide~ +:description: Implements an amplitude-based slicer, with various customisable options and conditions to detect relative amplitude changes as onsets. :discussion: - FluidAmpSlice is based on two envelop followers on a highpassed version of the signal: one slow that gives the trend, and one fast. Each have features that will interact. The example code below is unfolding the various possibilites in order of complexity. + FluidAmpSlice is based on two envelope followers on a high-passed version of the signal: one slow that gives the trend, and one fast. Each has features that will interact. The example code below is unfolding the various possibilities in order of complexity. - The process will return an audio steam with single sample impulses at estimated starting points of the different slices. + The process will return an audio stream with single sample impulses at estimated starting points of the different slices. :output: An audio stream with square envelopes around the slices. The latency between the input and the output is **max(minLengthAbove + lookBack, max(minLengthBelow,lookAhead))**. @@ -34,7 +35,7 @@ :control offThreshold: - The threshold in dB of the relative envelope follower to reset, aka to allow the differential envelop to trigger again. + The threshold in dB of the relative envelope follower to reset, aka to allow the differential envelope to trigger again. :control floor: diff --git a/doc/AudioTransport.rst b/doc/AudioTransport.rst index acfcc371..489193d3 100644 --- a/doc/AudioTransport.rst +++ b/doc/AudioTransport.rst @@ -8,7 +8,7 @@ :discussion: Interpolates between the spectra of two sounds using the optimal transport algorithm. This enables morphing and hybridisation of the perceptual qualities of each source linearly. - See Henderson and Solomonm (2019) AUDIO TRANSPORT: A GENERALIZED PORTAMENTO VIA OPTIMAL TRANSPORT, DaFx + See Henderson and Solomon (2019) AUDIO TRANSPORT: A GENERALIZED PORTAMENTO VIA OPTIMAL TRANSPORT, DaFx https://arxiv.org/abs/1906.06763 diff --git a/doc/BufAmpFeature.rst b/doc/BufAmpFeature.rst index 715b8b69..0487ad75 100644 --- a/doc/BufAmpFeature.rst +++ b/doc/BufAmpFeature.rst @@ -3,6 +3,7 @@ :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation :see-also: BufAmpSlice, BufNoveltyFeature, BufAmpFeature, BufOnsetFeature +:max-seealso: peakamp~, meter~, snapshot~, slide~ :description: Calculate the amplitude differential feature used by :fluid-obj:`BufAmpSlice`. :discussion: :fluid-obj:`BufAmpSlice` uses the differential between a fast and a slow envelope follower to determine changes in amplitude. This object calculates the amplitude differential and copies it to an output buffer. @@ -28,7 +29,7 @@ :control numChans: - For multichannel sources, how many channel should be summed. + For multichannel sources, how many channels should be summed. :control features: @@ -60,7 +61,18 @@ :control 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. Padding ensures all values are analysed. Possible values are: + + :enum: + + :0: + No padding - The first analysis window starts at time 0, and the samples at either end will be tapered by the STFT windowing function. + + :1: + Half the window size - The first sample is centred in the analysis window ensuring that the start and end of the segment are accounted for in the analysis. + + :2: + Window size minus the hop size - 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. :control action: diff --git a/doc/BufAmpGate.rst b/doc/BufAmpGate.rst index 140e19cd..7718895f 100644 --- a/doc/BufAmpGate.rst +++ b/doc/BufAmpGate.rst @@ -1,8 +1,9 @@ -:digest: Gate Detection on a Bfufer +:digest: Gate Detection on a Buffer :species: buffer-proc :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation :see-also: AmpGate, BufAmpSlice, BufOnsetSlice, BufNoveltySlice, BufTransientSlice +:max-seealso: peakamp~, meter~, snapshot~, slide~ :description: Absolute amplitude threshold gate detector on audio in a buffer :discussion: @@ -79,7 +80,7 @@ :control highPassFreq: - The frequency of the fourth-order Linkwitz-Riley high-pass filter (https://en.wikipedia.org/wiki/Linkwitz%E2%80%93Riley_filter) applied to the signal signal to minimise low frequency intermodulation with very short ramp lengths. A frequency of 0 bypasses the filter. + The frequency of the fourth-order Linkwitz-Riley high-pass filter (https://en.wikipedia.org/wiki/Linkwitz%E2%80%93Riley_filter) applied to the signal to minimise low frequency intermodulation with very short ramp lengths. A frequency of 0 bypasses the filter. :control maxSize: diff --git a/doc/BufAmpSlice.rst b/doc/BufAmpSlice.rst index 1fc30e88..c2590a0e 100644 --- a/doc/BufAmpSlice.rst +++ b/doc/BufAmpSlice.rst @@ -3,9 +3,10 @@ :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation :see-also: AmpSlice, BufAmpGate, BufOnsetSlice, BufNoveltySlice, BufTransientSlice -:description: This class implements an amplitude-based slicer,with various customisable options and conditions to detect relative amplitude changes as onsets. +:max-seealso: peakamp~, meter~, snapshot~, slide~ +:description: Implements an amplitude-based slicer, with various customisable options and conditions to detect relative amplitude changes as onsets. :discussion: - FluidBufAmpSlice is based on two envelop followers on a highpassed version of the signal: one slow that gives the trend, and one fast. Each have features that will interact. The example code below is unfolding the various possibilites in order of complexity. + FluidBufAmpSlice is based on two envelope followers on a high-passed version of the signal: one slow that gives the trend, and one fast. Each has features that will interact. The example code below is unfolding the various possibilities in order of complexity. The process will return a buffer which contains indices (in sample) of estimated starting points of different slices. @@ -30,7 +31,7 @@ :control numChans: - For multichannel sources, how many channel should be summed. + For multichannel sources, how many channels should be summed. :control indices: @@ -58,7 +59,7 @@ :control offThreshold: - The threshold in dB of the relative envelope follower to reset, aka to allow the differential envelop to trigger again. + The threshold in dB of the relative envelope follower to reset, aka to allow the differential envelope to trigger again. :control floor: diff --git a/doc/BufAudioTransport.rst b/doc/BufAudioTransport.rst index 201c8c98..a9e67abe 100644 --- a/doc/BufAudioTransport.rst +++ b/doc/BufAudioTransport.rst @@ -9,7 +9,7 @@ :discussion: Interpolates between the spectra of two sounds using the optimal transport algorithm. This enables morphing and hybridisation of the perceptual qualities of each source linearly. - See Henderson and Solomonm (2019) AUDIO TRANSPORT: A GENERALIZED PORTAMENTO VIA OPTIMAL TRANSPORT, DaFx + See Henderson and Solomon (2019) AUDIO TRANSPORT: A GENERALIZED PORTAMENTO VIA OPTIMAL TRANSPORT, DaFx https://arxiv.org/abs/1906.06763 diff --git a/doc/BufChroma.rst b/doc/BufChroma.rst index 17c48f2b..552525e5 100644 --- a/doc/BufChroma.rst +++ b/doc/BufChroma.rst @@ -15,7 +15,7 @@ :control 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 processed sequentially. :control startFrame: @@ -31,7 +31,7 @@ :control numChans: - For multichannel srcBuf, how many channel should be processed. + For multichannel srcBuf, how many channels should be processed. :control features: @@ -71,7 +71,18 @@ :control 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. Padding ensures all values are analysed. Possible values are: + + :enum: + + :0: + No padding - The first analysis window starts at time 0, and the samples at either end will be tapered by the STFT windowing function. + + :1: + Half the window size - The first sample is centred in the analysis window ensuring that the start and end of the segment are accounted for in the analysis. + + :2: + Window size minus the hop size - 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. :control maxFFTSize: diff --git a/doc/BufCompose.rst b/doc/BufCompose.rst index d4d1cd66..8071832b 100644 --- a/doc/BufCompose.rst +++ b/doc/BufCompose.rst @@ -3,11 +3,12 @@ :sc-categories: Libraries>FluidDecomposition, UGens>Buffer :sc-related: Guides/FluidCorpusManipulation, Classes/Buffer :see-also: BufSelect, BufSelectEvery +:max-seealso: poke~, peek~, index~, buffer~ :description: A utility for manipulating the contents of buffers. :discussion: - This object is the swiss army knife for manipulating buffers and their contents. By specifing ranges of samples and channels to copy, as well as destination and source gains it can provide a powerful interface for performing actions such as a Left/Right to Mid/Side conversion and mixing down multichannel audio + This object is the swiss army knife for manipulating buffers and their contents. By specifying ranges of samples and channels to copy, as well as destination and source gains it can provide a powerful interface for performing actions such as a Left/Right to Mid/Side conversion and mixing down multichannel audio :process: This method triggers the compositing. @@ -16,7 +17,7 @@ :control source: - The bufNum of the source buffer. + The name of the source buffer. :control startFrame: @@ -24,7 +25,7 @@ :control numFrames: - The duration (in samples) to copy from the source buffer. The default (-1) copies the full lenght of the buffer. + The duration (in samples) to copy from the source buffer. The default (-1) copies the full length of the buffer. :control startChan: @@ -32,7 +33,7 @@ :control numChans: - The number of channels from which to copy in the source buffer. This parameter will wrap around the number of channels in the source buffer. The default (-1) copies all of the buffer's channel. + The number of channels from which to copy in the source buffer. This parameter will wrap around the number of channels in the source buffer. The default (-1) copies all of the buffer's channels. :control gain: @@ -40,7 +41,7 @@ :control destination: - The bufNum of the destination buffer. + The name of the destination buffer. :control destStartFrame: @@ -48,7 +49,7 @@ :control destStartChan: - The channel offest in the destination buffer to start writing the source at. The destination buffer will be resized if the number of channels to copy is overflowing. + The channel offset in the destination buffer to start writing the source at. The destination buffer will be resized if the number of channels to copy is overflowing. :control destGain: diff --git a/doc/BufFlatten.rst b/doc/BufFlatten.rst index aa1da78e..7a959fce 100644 --- a/doc/BufFlatten.rst +++ b/doc/BufFlatten.rst @@ -3,6 +3,7 @@ :sc-categories: FluidCorpusManipulation :sc-related: Classes/Buffer :see-also: BufCompose, BufStats +:max-seealso: poke~, peek~, index~, buffer~ :description: Flatten a multichannel |buffer| to a single channel. This can be useful to structure a buffer such that it can be added to a :fluid-obj:`DataSet` :discussion: @@ -42,7 +43,7 @@ :control startChan: - For multichannel ``source`` buffers, which which channel to begin the processing. The default is 0. + For multichannel ``source`` buffers, which channel to begin the processing. The default is 0. :control numChans: diff --git a/doc/BufHPSS.rst b/doc/BufHPSS.rst index 30f5e23c..a059a8db 100644 --- a/doc/BufHPSS.rst +++ b/doc/BufHPSS.rst @@ -9,13 +9,13 @@ HPSS takes in audio and divides it into two or three outputs, depending on the ``maskingMode`` * an harmonic component * a percussive component - * a residual of the previous two if ``maskingMode`` is set to 2 (inter-dependant thresholds). See below. + * a residual of the previous two if ``maskingMode`` is set to 2 (interdependent thresholds). See below. HPSS works by using median filters on the magnitudes of a spectrogram. It makes certain assumptions about what it is looking for in a sound: that in a spectrogram “percussive” elements tend to form vertical “ridges” (tall in frequency band, narrow in time), while stable “harmonic” elements tend to form horizontal “ridges” (narrow in frequency band, long in time). By using median filters across time and frequency respectively, we get initial estimates of the "harmonic-ness" and "percussive-ness" for every spectral bin of every spectral frame in the spectrogram. These are then combined into 'masks' that are applied to the original spectrogram in order to produce a harmonic and percussive output (and residual if ``maskingMode`` = 2). The maskingMode parameter provides different approaches to combining estimates and producing masks. Some settings (especially in modes 1 & 2) will provide better separation but with more artefacts. - Driedger (2014) suggests that the size of the median filters don't affect the outcome as much as the ``fftSize``. with large FFT sizes, short percussive sounds have less representation, therefore the harmonic component is more strongly represented. The result is that many of the percussive sounds leak into the harmonic component. Small FFT sizes have less resolution in the frequency domain and often lead to a blurring of horizontal structures, therefore harmonic sounds tend to leak into the percussive component. As with all FFT based-processes, finding an FFT size that balances spectral and temporal resolution for a given source sound will benefit the use of this object. + Driedger (2014) suggests that the size of the median filters don't affect the outcome as much as the ``fftSize``. With large FFT sizes, short percussive sounds have less representation, therefore the harmonic component is more strongly represented. The result is that many of the percussive sounds leak into the harmonic component. Small FFT sizes have less resolution in the frequency domain and often lead to a blurring of horizontal structures, therefore harmonic sounds tend to leak into the percussive component. As with all FFT based-processes, finding an FFT size that balances spectral and temporal resolution for a given source sound will benefit the use of this object. For more details visit https://learn.flucoma.org/reference/hpss @@ -74,13 +74,13 @@ :enum: :0: - Soft masks provide the fewest artefacts, but the weakest separation. Complimentary, soft masks are made for the harmonic and percussive parts by allocating some fraction of every magnitude in the spectrogram to each mask. The two resulting buffers will sum to exactly the original material. This mode uses soft mask in Fitzgerald's (2010) original method of 'Wiener-inspired' filtering. + Soft masks provide the fewest artefacts, but the weakest separation. Complimentary, soft masks are made for the harmonic and percussive parts by allocating some fraction of every magnitude in the spectrogram to each mask. The two resulting buffers will sum to exactly the original material. This mode uses a soft mask in Fitzgerald's (2010) original method of 'Wiener-inspired' filtering. :1: Binary masks provide better separation, but with more artefacts. The harmonic mask is constructed using a binary decision, based on whether a threshold is exceeded for every magnitude in the spectrogram (these are set using ``harmThreshFreq1``, ``harmThreshAmp1``, ``harmThreshFreq2``, ``harmThreshAmp2``, see below). The percussive mask is then formed as the inverse of the harmonic one, meaning that as above, the two components will sum to the original sound. :2: - Soft masks (with a third stream containing a residual component). First, binary masks are made separately for the harmonic and percussive components using different thresholds (set with the respective ``harmThresh-`` and ``percThresh-`` parameters below). Because these masks aren't guaranteed to represent the entire spectrogram, any residual energy is considered as a third output. The independently created binary masks are converted to soft masks at the end of the process so that everything null sums. + Soft masks (with a third stream containing a residual component). First, binary masks are made separately for the harmonic and percussive components using different thresholds (set with the respective ``harmThresh-`` and ``percThresh-`` parameters below). Because these masks aren't guaranteed to represent the entire spectrogram, any residual energy is considered as a third output. The independently created binary masks are converted to soft masks at the end of the process so that everything null-sums. :control harmThresh: diff --git a/doc/BufLoudness.rst b/doc/BufLoudness.rst index 9f6aaf11..05f1f680 100644 --- a/doc/BufLoudness.rst +++ b/doc/BufLoudness.rst @@ -3,6 +3,7 @@ :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation :see-also: Loudness, BufPitch, BufMelBands, BufMFCC, BufSpectralShape, BufStats +:max-seealso: peakamp~, meter~ :description: Two loudness descriptors, computing the true peak of the signal as well as applying the filters proposed by broadcasting standards to emulate the perception of amplitude. :discussion: The process will return a multichannel buffer with two channels per input channel, one for loudness and one for the true peak value of the frame, both in dBfs. @@ -17,7 +18,7 @@ :control source: - The index of the buffer to use as the source material to be described. The different channels of multichannel buffers will be processing sequentially. + The index of the buffer to use as the source material to be described. The different channels of multichannel buffers will be processed sequentially. :control startFrame: @@ -33,7 +34,7 @@ :control numChans: - For multichannel srcBuf, how many channel should be processed. + For multichannel srcBuf, how many channels should be processed. :control features: @@ -61,7 +62,18 @@ :control 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. Padding ensures all values are analysed. Possible values are: + + :enum: + + :0: + No padding - The first analysis window starts at time 0, and the samples at either end will be tapered by the STFT windowing function. + + :1: + Half the window size - The first sample is centred in the analysis window ensuring that the start and end of the segment are accounted for in the analysis. + + :2: + Window size minus the hop size - 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. :control maxWindowSize: diff --git a/doc/BufMFCC.rst b/doc/BufMFCC.rst index 164c5272..e537fbc7 100644 --- a/doc/BufMFCC.rst +++ b/doc/BufMFCC.rst @@ -6,11 +6,11 @@ :description: A classic timbral spectral descriptor, the Mel-Frequency Cepstral Coefficients (MFCCs). :discussion: - MFCC stands for Mel-Frequency Cepstral Coefficients ("cepstral" is pronounced like "kepstral"). This analysis is often used for timbral description and timbral comparison. It compresses the overall spectrum into a smaller number of coefficients that, when taken together, describe the general contour the the spectrum. + MFCC stands for Mel-Frequency Cepstral Coefficients ("cepstral" is pronounced like "kepstral"). This analysis is often used for timbral description and timbral comparison. It compresses the overall spectrum into a smaller number of coefficients that, when taken together, describe the general contour of the spectrum. - The MFCC values are derived by first computing a mel-frequency spectrum, just as in :fluid-obj:`MelBands`. ``numCoeffs`` coefficients are then calculated by using that mel-frequency spectrum as input to the discrete cosine transform. This means that the shape of the mel-frequency spectrum is compared to a number of cosine wave shapes (different cosines shapes created from different different frequencies). Each MFCC value (i.e., "coefficient") represents how similar the mel-frequency spectrum is to one of these cosine shapes. + The MFCC values are derived by first computing a mel-frequency spectrum, just as in :fluid-obj:`MelBands`. ``numCoeffs`` coefficients are then calculated by using that mel-frequency spectrum as input to the discrete cosine transform. This means that the shape of the mel-frequency spectrum is compared to a number of cosine wave shapes (different cosine shapes created from different frequencies). Each MFCC value (i.e., "coefficient") represents how similar the mel-frequency spectrum is to one of these cosine shapes. - Other that the 0th coefficient, MFCCs are unchanged by differences in the overall energy of the spectrum (which relates to how we perceive loudness). This means that timbres with similar spectral contours, but different volumes, will still have similar MFCC values, other than MFCC 0. To remove any indication of loudness but keep the information about timbre, we can ignore MFCC 0 by setting the parameter ``startCoeff`` to 1. + Other than the 0th coefficient, MFCCs are unchanged by differences in the overall energy of the spectrum (which relates to how we perceive loudness). This means that timbres with similar spectral contours, but different volumes, will still have similar MFCC values, other than MFCC 0. To remove any indication of loudness but keep the information about timbre, we can ignore MFCC 0 by setting the parameter ``startCoeff`` to 1. For more information visit https://learn.flucoma.org/reference/mfcc/. @@ -18,7 +18,7 @@ :control 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 processed sequentially. :control startFrame: @@ -74,4 +74,16 @@ :control 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 centring 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. Padding ensures all values are analysed. Possible values are: + + :enum: + + :0: + No padding - The first analysis window starts at time 0, and the samples at either end will be tapered by the STFT windowing function. + + :1: + Half the window size - The first sample is centred in the analysis window ensuring that the start and end of the segment are accounted for in the analysis. + + :2: + Window size minus the hop size - 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. + diff --git a/doc/BufMelBands.rst b/doc/BufMelBands.rst index 21256108..4b97b045 100644 --- a/doc/BufMelBands.rst +++ b/doc/BufMelBands.rst @@ -6,9 +6,9 @@ :description: Magnitudes for a number of perceptually-evenly spaced bands. :discussion: - :fluid-obj:`BufMelBands` returns a Mel-Frequency Spectrum comprised of the user-defined ``numBands``. The Mel-Frequency Spectrum is a histogram of FFT bins bundled according their relationship to the Mel scale ( https://en.wikipedia.org/wiki/Mel_scale ) which represents frequency space logarithmically, mimicking how humans perceive pitch distance. The name "Mel" derives from the word "melody". The Hz-to-Mel conversion used by :fluid-obj:`BufMelBands` is ``mel = 1127.01048 * log(hz / 700.0 + 1.0)``. + :fluid-obj:`BufMelBands` returns a Mel-Frequency Spectrum containing the user-defined ``numBands``. The Mel-Frequency Spectrum is a histogram of FFT bins bundled according to their relationship to the Mel scale ( https://en.wikipedia.org/wiki/Mel_scale ) which represents frequency space logarithmically, mimicking how humans perceive pitch distance. The name "Mel" derives from the word "melody". The Hz-to-Mel conversion used by :fluid-obj:`BufMelBands` is ``mel = 1127.01048 * log(hz / 700.0 + 1.0)``. - This implementation allows to select the range and number of bands dynamically. The ``numBands`` MelBands will be perceptually equally distributed between ``minFreq`` and ``maxFreq``. + This implementation allows selection of the range and number of bands dynamically. The ``numBands`` MelBands will be perceptually equally distributed between ``minFreq`` and ``maxFreq``. When using a high value for ``numBands``, you may end up with empty channels (filled with zeros) in the MelBands output. This is because there is not enough information in the FFT analysis to properly calculate values for every MelBand. Increasing the ``fftSize`` will ensure you have values for all the MelBands. @@ -20,7 +20,7 @@ :control 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 processed sequentially. :control startFrame: @@ -76,7 +76,18 @@ :control 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 centring 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. Padding ensures all values are analysed. Possible values are: + + :enum: + + :0: + No padding - The first analysis window starts at time 0, and the samples at either end will be tapered by the STFT windowing function. + + :1: + Half the window size - The first sample is centred in the analysis window ensuring that the start and end of the segment are accounted for in the analysis. + + :2: + Window size minus the hop size - 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. :control action: diff --git a/doc/BufNMF.rst b/doc/BufNMF.rst index eff0b87c..22719f65 100644 --- a/doc/BufNMF.rst +++ b/doc/BufNMF.rst @@ -7,14 +7,14 @@ :discussion: NMF has been a popular technique in signal processing research for things like source separation and transcription (see Smaragdis and Brown, Non-Negative Matrix Factorization for Polyphonic Music Transcription.), although its creative potential is so far relatively unexplored. - The algorithm takes a buffer in and divides it into a number of components, determined by the components argument. It works iteratively, by trying to find a combination of spectral templates ('bases') and envelopes ('activations') that yield the original magnitude spectrogram when added together. By and large, there is no unique answer to this question (i.e. there are different ways of accounting for an evolving spectrum in terms of some set of templates and envelopes). In its basic form, NMF is a form of unsupervised learning: it starts with some random data and then converges towards something that minimizes the distance between its generated data and the original:it tends to converge very quickly at first and then level out. Fewer iterations mean less processing, but also less predictable results. + The algorithm takes a buffer in and divides it into a number of components, determined by the components argument. It works iteratively, by trying to find a combination of spectral templates ('bases') and envelopes ('activations') that yield the original magnitude spectrogram when added together. By and large, there is no unique answer to this question (i.e. there are different ways of accounting for an evolving spectrum in terms of some set of templates and envelopes). In its basic form, NMF is a form of unsupervised learning: it starts with some random data and then converges towards something that minimises the distance between its generated data and the original:it tends to converge very quickly at first and then level out. Fewer iterations mean less processing, but also less predictable results. The object can return either or all of the following: * a spectral contour of each component in the form of a magnitude spectrogram (called a basis in NMF lingo); * an amplitude envelope of each component in the form of gains for each consecutive frame of the underlying spectrogram (called an activation in NMF lingo); - * an audio reconstruction of each components in the time domain. + * an audio reconstruction of each component in the time domain. - The bases and activations can be used to make a kind of vocoder based on what NMF has 'learned' from the original data. Alternatively, taking the matrix product of a basis and an activation will yield a synthetic magnitude spectrogram of a component (which could be reconsructed, given some phase informaiton from somewhere). + The bases and activations can be used to make a kind of vocoder based on what NMF has 'learned' from the original data. Alternatively, taking the matrix product of a basis and an activation will yield a synthetic magnitude spectrogram of a component (which could be reconstructed, given some phase information from somewhere). Some additional options and flexibility can be found through combinations of the basesMode and actMode arguments. If these flags are set to 1, the object expects to be supplied with pre-formed spectra (or envelopes) that will be used as seeds for the decomposition, providing more guided results. When set to 2, the supplied buffers won't be updated, so become templates to match against instead. Note that having both bases and activations set to 2 doesn't make sense, so the object will complain. @@ -32,7 +32,7 @@ :control source: - The index of the buffer to use as the source material to be decomposed through the NMF process. The different channels of multichannel buffers will be processing sequentially. + The index of the buffer to use as the source material to be decomposed through the NMF process. The different channels of multichannel buffers will be processed sequentially. :control startFrame: @@ -48,11 +48,11 @@ :control numChans: - For multichannel srcBuf, how many channel should be processed. + For multichannel srcBuf, how many channels should be processed. :control resynth: - The index of the buffer where the different reconstructed components will be reconstructed. The buffer will be resized to ``components * numChannelsProcessed`` channels and ``sourceDuration`` lenght. If ``nil`` is provided, the reconstruction will not happen. + The index of the buffer where the different reconstructed components will be reconstructed. The buffer will be resized to ``components * numChannelsProcessed`` channels and ``sourceDuration`` length. If ``nil`` is provided, the reconstruction will not happen. :control resynthMode: @@ -64,12 +64,12 @@ :control basesMode: - This flag decides of how the basis buffer passed as the previous argument is treated. + This flag decides how the basis buffer passed as the previous argument is treated. :enum: :0: - The bases are seeded randomly, and the resulting ones will be written after the process in the passed buffer. The buffer is resized to ``components * numChannelsProcessed`` channels and ``(fftSize / 2 + 1)`` lenght. + The bases are seeded randomly, and the resulting ones will be written after the process in the passed buffer. The buffer is resized to ``components * numChannelsProcessed`` channels and ``(fftSize / 2 + 1)`` length. :1: The passed buffer is considered as seed for the bases. Its dimensions should match the values above. The resulting bases will replace the seed ones. @@ -83,12 +83,12 @@ :control actMode: - This flag decides of how the activation buffer passed as the previous argument is treated. + This flag decides how the activation buffer passed as the previous argument is treated. :enum: :0: - The activations are seeded randomly, and the resulting ones will be written after the process in the passed buffer. The buffer is resized to ``components * numChannelsProcessed`` channels and ``(sourceDuration / hopsize + 1)`` lenght. + The activations are seeded randomly, and the resulting ones will be written after the process in the passed buffer. The buffer is resized to ``components * numChannelsProcessed`` channels and ``(sourceDuration / hopsize + 1)`` length. :1: The passed buffer is considered as seed for the activations. Its dimensions should match the values above. The resulting activations will replace the seed ones. diff --git a/doc/BufNMFCross.rst b/doc/BufNMFCross.rst index a8b8b24a..b6f3407b 100644 --- a/doc/BufNMFCross.rst +++ b/doc/BufNMFCross.rst @@ -34,7 +34,7 @@ :control continuity: - Promote the use of N successive source frames, giving greater continuity in the result. This can not be bigger than the sizes of the ``source`` buffer, but useful values tend to be much lower (in the tens). The default is 7. + Promote the use of N successive source frames, giving greater continuity in the result. This can not be bigger than the size of the ``source`` buffer, but useful values tend to be much lower (in the tens). The default is 7. :control iterations: @@ -50,4 +50,4 @@ :control fftSize: - The analsyis FFT size in samples The default of -1 indicates ``fftSize`` = ``windowSize`` + The analysis FFT size in samples The default of -1 indicates ``fftSize`` = ``windowSize`` diff --git a/doc/BufNMFSeed.rst b/doc/BufNMFSeed.rst index 1c4398dc..fdaa5abf 100644 --- a/doc/BufNMFSeed.rst +++ b/doc/BufNMFSeed.rst @@ -16,11 +16,11 @@ :control bases: - The |buffer| where the bases will be written to. These are suggested seed for a BufNMF process. The number of bases (i.e., channels) in this buffer when the process is complete is the number of components needed to cover the requested percentage of variance in the buffer. + The |buffer| where the bases will be written to. These bases are suggested seeds for a BufNMF process. The number of bases (i.e., channels) in this buffer when the process is complete is the number of components needed to cover the requested percentage of variance in the buffer. :control activations: - The |buffer| where the activations will be written to. These are suggested seed for a BufNMF process. The number of bases (i.e., channels) in this buffer when the process is complete is the number of components needed to cover the requested percentage of variance in the buffer. + The |buffer| where the activations will be written to. These bases are suggested seeds for a BufNMF process. The number of bases (i.e., channels) in this buffer when the process is complete is the number of components needed to cover the requested percentage of variance in the buffer. :control minComponents: diff --git a/doc/BufNoveltyFeature.rst b/doc/BufNoveltyFeature.rst index de152949..2516eaaa 100644 --- a/doc/BufNoveltyFeature.rst +++ b/doc/BufNoveltyFeature.rst @@ -32,7 +32,7 @@ :control numChans: - For multichannel srcBuf, how many channel should be summed. + For multichannel srcBuf, how many channels should be summed. :control features: @@ -65,7 +65,7 @@ :control 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. + The size of a smoothing filter that is applied on the novelty curve. A larger filter size allows for cleaner cuts on very sharp changes. :control windowSize: @@ -93,7 +93,18 @@ :control 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. Padding ensures all values are analysed. Possible values are: + + :enum: + + :0: + No padding - The first analysis window starts at time 0, and the samples at either end will be tapered by the STFT windowing function. + + :1: + Half the window size - The first sample is centred in the analysis window ensuring that the start and end of the segment are accounted for in the analysis. + + :2: + Window size minus the hop size - 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. :control action: diff --git a/doc/BufNoveltySlice.rst b/doc/BufNoveltySlice.rst index 824d45c4..4486eaf4 100644 --- a/doc/BufNoveltySlice.rst +++ b/doc/BufNoveltySlice.rst @@ -3,9 +3,9 @@ :sc-categories: Libraries>FluidDecomposition, UGens>Buffer :sc-related: Guides/FluidCorpusManipulation :see-also: NoveltySlice, BufAmpSlice, BufOnsetSlice, BufTransientSlice -:description: A non-real-time slicer using an algorithm assessing novelty in the signal to estimate the slicing points. +:description: A non-realtime slicer using an algorithm assessing novelty in the signal to estimate the slicing points. :discussion: - A novelty curve is 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. + A novelty curve is derived from running a kernel across the diagonal of the similarity matrix, and looking for peaks of changes. It implements the seminal results published in 'Automatic Audio Segmentation Using a Measure of Audio Novelty' by J Foote. The process will return a buffer which contains indices (in sample) of estimated starting points of different slices. @@ -31,7 +31,7 @@ :control numChans: - For multichannel srcBuf, how many channel should be summed. + For multichannel srcBuf, how many channels should be summed. :control indices: @@ -64,11 +64,11 @@ :control threshold: - The normalised threshold, between 0 an 1, on the novelty curve to consider it a segmentation point. + The normalised threshold, between 0 and 1, on the novelty curve to consider it a segmentation point. :control 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. + The size of a smoothing filter that is applied on the novelty curve. A larger filter size allows for cleaner cuts on very sharp changes. :control minSliceLength: diff --git a/doc/BufOnsetFeature.rst b/doc/BufOnsetFeature.rst index 56dc3826..b2fcc173 100644 --- a/doc/BufOnsetFeature.rst +++ b/doc/BufOnsetFeature.rst @@ -30,7 +30,7 @@ :control numChans: - For multichannel sources, how many channel should be summed. + For multichannel sources, how many channels should be summed. :control features: @@ -49,7 +49,7 @@ **HFC** thresholds on (sum of (squared magnitudes * binNum) / nBins) :2: - **SpectralFlux** thresholds on (diffence in magnitude between consecutive frames, half rectified) + **SpectralFlux** thresholds on (difference in magnitude between consecutive frames, half rectified) :3: **MKL** thresholds on (sum of log of magnitude ratio per bin) (or equivalently, sum of difference of the log magnitude per bin) (like Onsets mkl) @@ -74,7 +74,7 @@ :control 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. + The size of a smoothing filter that is applied on the novelty curve. A larger filter size allows for cleaner cuts on very sharp changes. :control frameDelta: @@ -98,7 +98,18 @@ :control 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. Padding ensures all values are analysed. Possible values are: + + :enum: + + :0: + No padding - The first analysis window starts at time 0, and the samples at either end will be tapered by the STFT windowing function. + + :1: + Half the window size - The first sample is centred in the analysis window ensuring that the start and end of the segment are accounted for in the analysis. + + :2: + Window size minus the hop size - 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. :control action: diff --git a/doc/BufOnsetSlice.rst b/doc/BufOnsetSlice.rst index 3b70e287..fdb51b8a 100644 --- a/doc/BufOnsetSlice.rst +++ b/doc/BufOnsetSlice.rst @@ -30,7 +30,7 @@ :control numChans: - For multichannel sources, how many channel should be summed. + For multichannel sources, how many channels should be summed. :control indices: @@ -49,7 +49,7 @@ **HFC** thresholds on (sum of (squared magnitudes * binNum) / nBins) :2: - **SpectralFlux** thresholds on (diffence in magnitude between consecutive frames, half rectified) + **SpectralFlux** thresholds on (difference in magnitude between consecutive frames, half rectified) :3: **MKL** thresholds on (sum of log of magnitude ratio per bin) (or equivalently, sum of difference of the log magnitude per bin) (like Onsets mkl) @@ -82,11 +82,11 @@ :control 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. + The size of a smoothing filter that is applied on the novelty curve. A larger filter size allows for cleaner cuts on very sharp changes. :control 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. + 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 distance between the comparison window in samples. :control windowSize: diff --git a/doc/BufPitch.rst b/doc/BufPitch.rst index f98d4926..376984e5 100644 --- a/doc/BufPitch.rst +++ b/doc/BufPitch.rst @@ -3,6 +3,7 @@ :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation, Classes/SpecCentroid, Classes/SpecFlatness, Classes/SpecCentroid, Classes/SpecPcile :see-also: Pitch, BufLoudness, BufMelBands, BufMFCC, BufSpectralShape, BufStats +:max-seealso: fzero~, retune~ :description: Three popular pitch descriptors, all of which compute frequency and the confidence that a pitch is present. :discussion: @@ -22,7 +23,7 @@ :control source: - The index of the buffer to use as the source material to be pitch-tracked. The different channels of multichannel buffers will be processing sequentially. + The index of the buffer to use as the source material to be pitch-tracked. The different channels of multichannel buffers will be processed sequentially. :control select: @@ -42,7 +43,7 @@ :control numChans: - For multichannel ``source``, how many channel should be processed. The default of -1 indicates to analyse through the last channel in the buffer. + For multichannel ``source``, how many channels should be processed. The default of -1 indicates to analyse through the last channel in the buffer. :control features: @@ -65,11 +66,11 @@ :control minFreq: - The minimum frequency that the algorithm will search for an estimated fundamental. This sets the lowest value that will be generated. The default is 20. + The minimum fundamental frequency that the algorithm withh search for. This sets the lowest value that will be generated. The default is 20. :control maxFreq: - The maximum frequency that the algorithm will search for an estimated fundamental. This sets the highest value that will be generated. The default is 10000. + The maximum fundamental frequency that the algorithm withh search for. This sets the highest value that will be generated. The default is 10000. :control unit: @@ -89,7 +90,18 @@ :control 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. Padding ensures all values are analysed. Possible values are: + + :enum: + + :0: + No padding - The first analysis window starts at time 0, and the samples at either end will be tapered by the STFT windowing function. + + :1: + Half the window size - The first sample is centred in the analysis window ensuring that the start and end of the segment are accounted for in the analysis. + + :2: + Window size minus the hop size - 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. :control maxFFTSize: diff --git a/doc/BufSTFT.rst b/doc/BufSTFT.rst index 7a7c7e4a..4b53e6ca 100644 --- a/doc/BufSTFT.rst +++ b/doc/BufSTFT.rst @@ -2,7 +2,8 @@ :species: buffer-proc :sc-categories: FluidCorpusManipulation :sc-related: Classes/Buffer -:see-also: +:see-also: +:max-seealso: pfft~ :description: Performs either a forward or inverse Short-Time Fourier Transform (STFT) on a single channel ``source`` |buffer|. @@ -65,4 +66,15 @@ :control 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. Padding ensures all values are analysed. Possible values are: + + :enum: + + :0: + No padding - The first analysis window starts at time 0, and the samples at either end will be tapered by the STFT windowing function. + + :1: + Half the window size - The first sample is centred in the analysis window ensuring that the start and end of the segment are accounted for in the analysis. + + :2: + Window size minus the hop size - 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. diff --git a/doc/BufScale.rst b/doc/BufScale.rst index 7b3fb0f0..950a542d 100644 --- a/doc/BufScale.rst +++ b/doc/BufScale.rst @@ -3,6 +3,7 @@ :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation, Guides/FluidBufMultiThreading :see-also: BufThresh, BufCompose, BufFlatten +:max-seealso: poke~, peek~, index~, buffer~ :description: Scale |buffer| values from an input range to an output range. :discussion: This object is for scaling |buffer| values. It copies data from a source |buffer| to a destination |buffer|, scaling the source from an input range to an output range. diff --git a/doc/BufSelect.rst b/doc/BufSelect.rst index 85baa0a8..f900c616 100644 --- a/doc/BufSelect.rst +++ b/doc/BufSelect.rst @@ -3,6 +3,7 @@ :sc-categories: FluidCorpusManipulation :sc-related: Classes/Buffer :see-also: BufSelectEvery +:max-seealso: poke~, peek~, index~, buffer~ :description: Copies sets of values from a buffer, described in terms of a list of frame indices and channel numbers. diff --git a/doc/BufSelectEvery.rst b/doc/BufSelectEvery.rst index 11bece20..57d17c9e 100644 --- a/doc/BufSelectEvery.rst +++ b/doc/BufSelectEvery.rst @@ -3,6 +3,7 @@ :sc-categories: FluidCorpusManipulation :sc-related: Classes/Buffer :see-also: BufSelect +:max-seealso: poke~, peek~, index~, buffer~ :description: Pick every N frames and / or channels from a buffer, described in terms of independent hop sizes for frames and channels diff --git a/doc/BufSines.rst b/doc/BufSines.rst index e262840b..efd0914e 100644 --- a/doc/BufSines.rst +++ b/doc/BufSines.rst @@ -20,7 +20,7 @@ :control source: - The index of the buffer to use as the source material to be decomposed through the sinusoidal modelling process. The different channels of multichannel buffers will be processing sequentially. + The index of the buffer to use as the source material to be decomposed through the sinusoidal modelling process. The different channels of multichannel buffers will be processed sequentially. :control startFrame: @@ -36,7 +36,7 @@ :control numChans: - For multichannel srcBuf, how many channel should be processed. + For multichannel srcBuf, how many channels should be processed. :control sines: diff --git a/doc/BufSpectralShape.rst b/doc/BufSpectralShape.rst index 9668c688..b8fbf5c5 100644 --- a/doc/BufSpectralShape.rst +++ b/doc/BufSpectralShape.rst @@ -10,7 +10,7 @@ * the four first statistical moments (https://en.wikipedia.org/wiki/Moment_(mathematics) ): * the spectral centroid (1) in Hertz. This is the point that splits the spectrum in 2 halves of equal energy. It is the weighted average of the magnitude spectrum. - * the spectral spread (2) in Hertz. This is the standard deviation of the spectrum envelop, or the average of the distance to the centroid. + * the spectral spread (2) in Hertz. This is the standard deviation of the spectrum envelope, or the average of the distance to the centroid. * the normalised skewness (3) as ratio. This indicates how tilted is the spectral curve in relation to the middle of the spectral frame, i.e. half of the Nyquist frequency. If it is below the frequency of the magnitude spectrum, it is positive. * the normalised kurtosis (4) as ratio. This indicates how focused is the spectral curve. If it is peaky, it is high. @@ -28,7 +28,7 @@ :control source: - The index of the buffer to use as the source material to be described through the various descriptors. The different channels of multichannel buffers will be processing sequentially. + The index of the buffer to use as the source material to be described through the various descriptors. The different channels of multichannel buffers will be processed sequentially. :control startFrame: @@ -44,7 +44,7 @@ :control numChans: - For multichannel srcBuf, how many channel should be processed. + For multichannel srcBuf, how many channels should be processed. :control features: @@ -84,7 +84,18 @@ :control 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. Padding ensures all values are analysed. Possible values are: + + :enum: + + :0: + No padding - The first analysis window starts at time 0, and the samples at either end will be tapered by the STFT windowing function. + + :1: + Half the window size - The first sample is centred in the analysis window ensuring that the start and end of the segment are accounted for in the analysis. + + :2: + Window size minus the hop size - 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. :control maxFFTSize: diff --git a/doc/BufStats.rst b/doc/BufStats.rst index 55729b40..45f002fd 100644 --- a/doc/BufStats.rst +++ b/doc/BufStats.rst @@ -14,11 +14,11 @@ For example if the input to :fluid-obj:`BufStats` is a three-channel buffer and ``numDerivs`` = 1 the output ``stats`` buffer would contain: - ========= ============ ============= ============= ======== =========== ======== ================= ==================== ===================== ===================== ================ =================== ================ - ch 0 mean ch 0 std dev ch 0 skewness ch 0 kurtosis ch 0 min ch 0 median ch 0 max ch 0 deriv 1 mean ch 0 deriv 1 std dev ch 0 deriv 1 skewness ch 0 deriv 1 kurtosis ch 0 deriv 1 min ch 0 deriv 1 median ch 0 deriv 1 max - ch 1 mean ch 1 std dev ch 1 skewness ch 1 kurtosis ch 1 min ch 1 median ch 1 max ch 1 deriv 1 mean ch 1 deriv 1 std dev ch 1 deriv 1 skewness ch 1 deriv 1 kurtosis ch 1 deriv 1 min ch 1 deriv 1 median ch 1 deriv 1 max - ch 2 mean ch 2 std dev ch 2 skewness ch 2 kurtosis ch 2 min ch 2 median ch 2 max ch 2 deriv 1 mean ch 2 deriv 1 std dev ch 2 deriv 1 skewness ch 2 deriv 1 kurtosis ch 2 deriv 1 min ch 2 deriv 1 median ch 2 deriv 1 max - ========= ============ ============= ============= ======== =========== ======== ================= ==================== ===================== ===================== ================ =================== ================ + ========= ============ ============= ============= ======== =========== ========= ================= ==================== ===================== ===================== ================ =================== ================= + ch 0 mean ch 0 std dev ch 0 skewness ch 0 kurtosis ch 0 low ch 0 middle ch 0 high ch 0 deriv 1 mean ch 0 deriv 1 std dev ch 0 deriv 1 skewness ch 0 deriv 1 kurtosis ch 0 deriv 1 low ch 0 deriv 1 middle ch 0 deriv 1 high + ch 1 mean ch 1 std dev ch 1 skewness ch 1 kurtosis ch 1 low ch 1 middle ch 1 high ch 1 deriv 1 mean ch 1 deriv 1 std dev ch 1 deriv 1 skewness ch 1 deriv 1 kurtosis ch 1 deriv 1 low ch 1 deriv 1 middle ch 1 deriv 1 high + ch 2 mean ch 2 std dev ch 2 skewness ch 2 kurtosis ch 2 low ch 2 middle ch 2 high ch 2 deriv 1 mean ch 2 deriv 1 std dev ch 2 deriv 1 skewness ch 2 deriv 1 kurtosis ch 2 deriv 1 low ch 2 deriv 1 middle ch 2 deriv 1 high + ========= ============ ============= ============= ======== =========== ========= ================= ==================== ===================== ===================== ================ =================== ================= :process: This is the method that calls for the statistical analysis to be calculated on ``source``. @@ -50,7 +50,7 @@ :control numDerivs: - The number of derivatives of the original time-series to compute statistics on. The default of 0 will compute statistics on no derivates, only the original time-series itself. Setting this parameter > 0 (maximum of 2) will return the same seven statistics computed on consecutive derivatives of the channel's time-series. (``numDerivs`` = 1 will return the channel's statistics and the statistics of the first derivative, ``numDerivs`` = 2 will return the channel's statistics and the statistics of the first and second derivatives.) The derivative statistics are useful to describe the rate of change of the time series. + The number of derivatives of the original time-series to compute statistics on. The default of 0 will compute statistics on no derivatives, only the original time-series itself. Setting this parameter > 0 (maximum of 2) will return the same seven statistics computed on consecutive derivatives of the channel's time-series. (``numDerivs`` = 1 will return the channel's statistics and the statistics of the first derivative, ``numDerivs`` = 2 will return the channel's statistics and the statistics of the first and second derivatives.) The derivative statistics are useful to describe the rate of change of the time series. :control low: diff --git a/doc/BufThreadDemo.rst b/doc/BufThreadDemo.rst index 60174273..15b815a4 100644 --- a/doc/BufThreadDemo.rst +++ b/doc/BufThreadDemo.rst @@ -4,18 +4,15 @@ :sc-related: Guides/FluidCorpusManipulation, Guides/FluidBufMultiThreading :see-also: :description: - This class implements a simple tutorial object to illustrate and experiment with the behaviour of the FluidBuf* objects. It simply starts a process that will, upon completion of its task, write a single value to the destination buffer. This is the general behaviour of much of the CPU consuming FluidBuf* objects. In this case, as a toy example, the task is simply just wait and do nothing, to simulate a task that would actually take that long in the background. + Implements a tutorial object to illustrate and experiment with the behaviour of the FluidBuf* objects. To simulate their behaviour in various blocking modes, the object after waiting for **time** milliseconds, return its delay length as a float writen at index [0] of the specified destination buffer. - The process will, after waiting for **time** milliseconds, return its delay length as a Float writen at index [0] of the specified destination buffer. - -:process: This is the method that calls for the job to be done. In this case, simply waiting **time** milliseconds before writing a value in the destination buffer. +:process: + This is the method that calls for the job to be done. In this case, simply waiting **time** milliseconds before writing a value in the destination buffer. :control result: - The destination buffer, where the value should be written at the end of the process. :control time: - The duration in milliseconds of the delay that the background thread will wait for before yielding the value to the destination buffer. diff --git a/doc/BufTransientSlice.rst b/doc/BufTransientSlice.rst index b59ced2f..2834e791 100644 --- a/doc/BufTransientSlice.rst +++ b/doc/BufTransientSlice.rst @@ -47,7 +47,7 @@ :control blockSize: - The size of audio chunk (in samples) on which the process is operating. This determines the maximum duration (in samples) of a detected transient, which cannot be more than than half of ``blockSize - order``. + The size of audio block (in samples) on which the process is operating. This determines the maximum duration (in samples) of a detected transient, which cannot be more than half of ``blockSize - order``. :control padSize: @@ -59,11 +59,11 @@ :control threshFwd: - The threshold applied to the smoothed forward prediction error for determining an onset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be detected as a transient. It allows tight start of the identification of the anomaly as it proceeds forward. + The threshold applied to the smoothed forward prediction error for determining an onset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be detected as a transient. It allows tight identification of the start of the anomaly as it proceeds forward. :control threshBack: - The threshold applied to the smoothed backward prediction error for determining an offset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be considered transient. When the smoothed error function goes below ``threshBack`` an offset is identified. As it proceeds backwards in time, it allows tight ending of the identification of the anomaly. + The threshold applied to the smoothed backward prediction error for determining an offset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be considered transient. When the smoothed error function goes below ``threshBack`` an offset is identified. As it proceeds backwards in time, it allows tight identification of the end of the anomaly. :control windowSize: @@ -71,7 +71,7 @@ :control clumpLength: - The window size in samples within which anomalous samples will be clumped together to avoid over detecting in time. This is similar to setting a minimum slice length. + The window size in samples within which anomalous samples will be clumped together to avoid over-detecting in time. This is similar to setting a minimum slice length. :control minSliceLength: diff --git a/doc/BufTransients.rst b/doc/BufTransients.rst index f3bacc32..81a7d999 100644 --- a/doc/BufTransients.rst +++ b/doc/BufTransients.rst @@ -21,7 +21,7 @@ :control source: - The |buffer| to use as the source material to detect transients in. The different channels of multichannel buffers will be processing sequentially. + The |buffer| to use as the source material to detect transients in. The different channels of multichannel buffers will be processed sequentially. :control startFrame: @@ -53,7 +53,7 @@ :control blockSize: - The size of audio chunk (in samples) on which the process is operating. This determines the maximum duration (in samples) of a detected transient, which cannot be more than than half of ``blockSize - order``. + The size of the audio block (in samples) on which the process is operating. This determines the maximum duration (in samples) of a detected transient, which cannot be more than half of ``blockSize - order``. :control padSize: @@ -65,11 +65,11 @@ :control threshFwd: - The threshold applied to the smoothed forward prediction error for determining an onset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be detected as a transient. It allows tight start of the identification of the anomaly as it proceeds forward. + The threshold applied to the smoothed forward prediction error for determining an onset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be detected as a transient. It allows tight identification of the start of the anomaly as it proceeds forward. :control threshBack: - The threshold applied to the smoothed backward prediction error for determining an offset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be considered transient. When the smoothed error function goes below ``threshBack`` an offset is identified. As it proceeds backwards in time, it allows tight ending of the identification of the anomaly. + The threshold applied to the smoothed backward prediction error for determining an offset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be considered transient. When the smoothed error function goes below ``threshBack`` an offset is identified. As it proceeds backwards in time, it allows tight identification of the end of the anomaly. :control windowSize: @@ -77,4 +77,4 @@ :control clumpLength: - The window size in samples within which anomalous samples will be clumped together to avoid over detecting in time. This is like setting a minimum transient length. + The window size in samples within which anomalous samples will be clumped together to avoid over-detecting in time. This is like setting a minimum transient length. diff --git a/doc/Chroma.rst b/doc/Chroma.rst index 8a25e8da..fff1de18 100644 --- a/doc/Chroma.rst +++ b/doc/Chroma.rst @@ -1,4 +1,4 @@ -:digest: A histogram of pitch classes in Real-Time +:digest: A histogram of pitch classes in Realtime :species: descriptor :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation, Classes/FluidMFCC @@ -7,7 +7,7 @@ :discussion: 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 stream 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. :process: The audio rate in, control rate out version of the object. :output: A KR signal of maxNumChroma channels, giving the measure amplitudes for each chroma bin. The latency is windowSize. diff --git a/doc/DataSet.rst b/doc/DataSet.rst index 4fe119ce..8cda70f1 100644 --- a/doc/DataSet.rst +++ b/doc/DataSet.rst @@ -2,7 +2,8 @@ :species: data :sc-categories: UGens>FluidManipulation :sc-related: Classes/FluidLabelSet, Classes/FluidKDTree, Classes/FluidKNNClassifier, Classes/FluidKNNRegressor, Classes/FluidKMeans -:see-also: +:see-also: LabelSet, DataSetQuery +:max-seealso: coll, dict :description: FluidDataSet is a container associating data points with identifiers. @@ -62,7 +63,7 @@ :arg labelSet: The FluidLabelSet in which to dump the point's IDs associated with their reference frame number (or channel number if transposed). - Dump the content of the dataset to a |buffer|, with optional transposition, and a map of frames/channel to the original IDs as a FluidLabelSet. + Dump the content of the dataset to a |buffer|, with optional transposition, and a map of frames/channels to the original IDs as a FluidLabelSet. :message fromBuffer: @@ -78,7 +79,7 @@ :arg labelSet: The FluidLabelSet to export to. Its content will be replaced. - Export to the dataset identifier to a FluidLabelSet. + Export the dataset identifier to a FluidLabelSet. :message merge: diff --git a/doc/DataSetQuery.rst b/doc/DataSetQuery.rst index bd494e1a..29d5d939 100644 --- a/doc/DataSetQuery.rst +++ b/doc/DataSetQuery.rst @@ -2,10 +2,9 @@ :species: data :sc-categories: UGens>FluidManipulation :sc-related: Classes/FluidDataSet -:see-also: -:description: A selection of columns and a set of conditions that match rows of a FluidDataSet. Use to filter and search in a database of descriptors. - - +:see-also: DataSet, LabelSet +:max-seealso: coll, dict +:description: A selection of columns and a set of conditions that match rows of a FluidDataSet. Used to filter and search in a database of descriptors. :message addColumn: @@ -73,7 +72,7 @@ :arg action: Run when done - Clear the query, remove all columns, filters and limit. + Clear the query, remove all columns, filters and limits. :message transform: diff --git a/doc/Gain.rst b/doc/Gain.rst index 153a4719..3454dc19 100644 --- a/doc/Gain.rst +++ b/doc/Gain.rst @@ -1,8 +1,8 @@ -:digest: Real-Time Buffered Gain Changer +:digest: Realtime Buffered Gain Changer :species: transformer :sc-categories: UGens>Algebraic, Libraries>FluidDecomposition, UGens>Buffer :sc-related: Guides/FluidCorpusManipulation,Classes/UnaryOpFunction -:description: This class implements a sanity test for the FluCoMa Real-Time Client Wrapper. +:description: This class implements a sanity test for the FluCoMa Realtime Client Wrapper. :see-also: :discussion: :process: The audio rate version of the object. diff --git a/doc/Grid.rst b/doc/Grid.rst index bb9c8c11..9a675c1e 100644 --- a/doc/Grid.rst +++ b/doc/Grid.rst @@ -5,7 +5,7 @@ :see-also: UMAP, MDS, PCA, DataSet :description: Maps a set of 2D points in a :fluid-obj:`DataSet` to a rectangular grid. :discussion: - :fluid-obj:`Grid` transforms a two-dimensional dataset into a grid using a variant of the Jonker-Volgenant algorithm (https://www.gwern.net/docs/statistics/decision/1987-jonker.pdf). This can be useful to generate compact grid layouts from the output of dimensionality reduction algorithms such as :fluid-obj:`UMAP`, :fluid-obj:`PCA` or :fluid-obj:`MDS` and for making uniformally distributed spaces out of any two-dimensional dataset. + :fluid-obj:`Grid` transforms a two-dimensional dataset into a grid using a variant of the Jonker-Volgenant algorithm (https://www.gwern.net/docs/statistics/decision/1987-jonker.pdf). This can be useful to generate compact grid layouts from the output of dimensionality reduction algorithms such as :fluid-obj:`UMAP`, :fluid-obj:`PCA` or :fluid-obj:`MDS` and for making uniformly distributed spaces out of any two-dimensional dataset. This approach is similar to projects like CloudToGrid ( https://github.com/kylemcdonald/CloudToGrid/ ), RasterFairy ( https://github.com/Quasimondo/RasterFairy ) or IsoMatch ( https://github.com/ohadf/isomatch ). diff --git a/doc/HPSS.rst b/doc/HPSS.rst index 0783455e..7fe5ab80 100644 --- a/doc/HPSS.rst +++ b/doc/HPSS.rst @@ -14,7 +14,7 @@ The maskingMode parameter provides different approaches to combining estimates and producing masks. Some settings (especially in modes 1 & 2) will provide better separation but with more artefacts. - Driedger (2014) suggests that the size of the median filters don't affect the outcome as much as the ``fftSize``. with large FFT sizes, short percussive sounds have less representation, therefore the harmonic component is more strongly represented. The result is that many of the percussive sounds leak into the harmonic component. Small FFT sizes have less resolution in the frequency domain and often lead to a blurring of horizontal structures, therefore harmonic sounds tend to leak into the percussive component. As with all FFT based-processes, finding an FFT size that balances spectral and temporal resolution for a given source sound will benefit the use of this object. + Driedger (2014) suggests that the size of the median filters don't affect the outcome as much as the ``fftSize``. With large FFT sizes, short percussive sounds have less representation, therefore the harmonic component is more strongly represented. The result is that many of the percussive sounds leak into the harmonic component. Small FFT sizes have less resolution in the frequency domain and often lead to a blurring of horizontal structures, therefore harmonic sounds tend to leak into the percussive component. As with all FFT based-processes, finding an FFT size that balances spectral and temporal resolution for a given source sound will benefit the use of this object. For more details visit https://learn.flucoma.org/reference/hpss @@ -50,7 +50,7 @@ Binary masks provide better separation, but with more artefacts. The harmonic mask is constructed using a binary decision, based on whether a threshold is exceeded for every magnitude in the spectrogram (these are set using ``harmThreshFreq1``, ``harmThreshAmp1``, ``harmThreshFreq2``, ``harmThreshAmp2``, see below). The percussive mask is then formed as the inverse of the harmonic one, meaning that as above, the two components will sum to the original sound. :2: - Soft masks (with a third stream containing a residual component). First, binary masks are made separately for the harmonic and percussive components using different thresholds (set with the respective ``harmThresh-`` and ``percThresh-`` parameters below). Because these masks aren't guaranteed to represent the entire spectrogram, any residual energy is considered as a third output. The independently created binary masks are converted to soft masks at the end of the process so that everything null sums. + Soft masks (with a third stream containing a residual component). First, binary masks are made separately for the harmonic and percussive components using different thresholds (set with the respective ``harmThresh-`` and ``percThresh-`` parameters below). Because these masks aren't guaranteed to represent the entire spectrogram, any residual energy is considered as a third output. The independently created binary masks are converted to soft masks at the end of the process so that everything null-sums. :control harmThresh: diff --git a/doc/KMeans.rst b/doc/KMeans.rst index eab47d5a..295f2f02 100644 --- a/doc/KMeans.rst +++ b/doc/KMeans.rst @@ -2,14 +2,14 @@ :species: data :sc-categories: FluidManipulation :sc-related: Classes/FluidDataSet, Classes/FluidLabelSet, Classes/FluidKNNClassifier, Classes/FluidKNNRegressor, Classes/FluidSKMeans -:see-also: SKMeans, KNNClassifier, MLPClassifier, DataSet +:see-also: SKMeans, KNNClassifier, MLPClassifier, DataSet, LabelSet :description: Uses the K-means algorithm to learn clusters from a :fluid-obj:`DataSet`. :discussion: - :fluid-obj:`KMeans` facilitates learning of clusters from a :fluid-obj:`DataSet`. This allows you to assign each point in the data a discrete membership to a group or cluster. The algorithm works by paritioning points into discrete clumps that ideally have *equal variance*. See the scitkit-learn reference for a more technical explanation: https://scikit-learn.org/stable/modules/clustering.html#k-means + ``KMeans`` facilitates learning of clusters from a :fluid-obj:`DataSet`. This allows you to assign each point in the data a discrete membership to a group or cluster. The algorithm works by partitioning points into discrete clumps that ideally have *equal variance*. See the Scitkit-learn reference for a more technical explanation: https://scikit-learn.org/stable/modules/clustering.html#k-means :control numClusters: @@ -45,7 +45,7 @@ :arg action: A function to run when the server responds - Run :fluid-obj:`KMeans#*fit` and :fluid-obj:`KMeans#*predict` in a single pass: i.e. train the model on the incoming :fluid-obj:`DataSet` and then return the learned clustering to the passed :fluid-obj:`LabelSet` + Run ``fit`` and ``predict`` in a single pass: i.e. train the model on the incoming :fluid-obj:`DataSet` and then return the learned clustering to the passed :fluid-obj:`LabelSet` :message predictPoint: @@ -73,7 +73,7 @@ :arg action: A function to run when the server responds - Run :fluid-obj:`KMeans#*fit` and :fluid-obj:`KMeans#*transform` in a single pass: i.e. train the model on the incoming :fluid-obj:`DataSet` and then return its cluster-distance space in the destination :fluid-obj:`DataSet` + Run ``fit`` and ``transform`` in a single pass: i.e. train the model on the incoming :fluid-obj:`DataSet` and then return its cluster-distance space in the destination :fluid-obj:`DataSet` :message transformPoint: diff --git a/doc/KNNClassifier.rst b/doc/KNNClassifier.rst index 1e945f7a..61e7591c 100644 --- a/doc/KNNClassifier.rst +++ b/doc/KNNClassifier.rst @@ -2,7 +2,7 @@ :species: data :sc-categories: Classification, KNN :sc-related: Classes/FluidKNNRegressor, Classes/FluidDataSet, Classes/FluidLabelSet, Classes/FluidMLPClassifier -:see-also: +:see-also: KNNRegressor, DataSet, MLPClassifier :description: A nearest neighbour classifier using a :fluid-obj:`KDTree` . :discussion: diff --git a/doc/KNNRegressor.rst b/doc/KNNRegressor.rst index 88377761..12caa16a 100644 --- a/doc/KNNRegressor.rst +++ b/doc/KNNRegressor.rst @@ -2,7 +2,7 @@ :species: data :sc-categories: Regression :sc-related: Classes/FluidKNNClassifier, Classes/FluidDataSet -:see-also: +:see-also: KNNClassifier, DataSet, MLPRegressor :description: Regression between DataSets using weighted average of neighbours :discussion: @@ -18,7 +18,7 @@ :control weight: - Whether to weight neighbours by distance when producing new point. The default is 1 (true). + Whether to weight neighbours by distance when predicting new points. The default is 1 (true). :message fit: diff --git a/doc/LabelSet.rst b/doc/LabelSet.rst index 0bb70d4e..c6dcd77e 100644 --- a/doc/LabelSet.rst +++ b/doc/LabelSet.rst @@ -63,7 +63,7 @@ :arg action: A function to run when the export is done. - Export to the dataset identifier to a FluidLabelSet. + Export the dataset identifier to a FluidLabelSet. :message write: diff --git a/doc/Loudness.rst b/doc/Loudness.rst index ef154657..4e4970c4 100644 --- a/doc/Loudness.rst +++ b/doc/Loudness.rst @@ -1,13 +1,14 @@ -:digest: A Loudness and True-Peak Descriptor in Real-Time +:digest: A Loudness and True-Peak Descriptor in Realtime :species: descriptor :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation :see-also: BufLoudness, Pitch, MelBands, MFCC, SpectralShape +:max-seealso: peakamp~, meter~ :description: Two loudness descriptors, with a ITU BS 1770 mode :discussion: Computes the true peak of the signal as well as applying the filters proposed by broadcasting standards to emulate the perception of amplitude. - The process will return a multichannel control steam with [loudness, truepeak] values, both in dBFS, which will be repeated if no change happens within the algorithm, i.e. when the hopSize is larger than the signal vector size. More information on broadcasting standardisation of loudness measurement is available at the reference page ( https://tech.ebu.ch/docs/tech/tech3341.pdf ) and in more musician-friendly explantions here (http://designingsound.org/2013/02/06/loudness-and-metering-part-1/). + The process will return a multichannel control stream with [loudness, truepeak] values, both in dBFS, which will be repeated if no change happens within the algorithm, i.e. when the hopSize is larger than the signal vector size. More information on broadcasting standardisation of loudness measurement is available at the reference page ( https://tech.ebu.ch/docs/tech/tech3341.pdf ) and in more musician-friendly explantions here (http://designingsound.org/2013/02/06/loudness-and-metering-part-1/). :process: The audio rate in, control rate out version of the object. :output: A 2-channel KR signal with the [pitch, confidence] descriptors. The latency is windowSize. diff --git a/doc/MDS.rst b/doc/MDS.rst index 5e335099..c0e1d385 100644 --- a/doc/MDS.rst +++ b/doc/MDS.rst @@ -2,7 +2,7 @@ :species: data :sc-categories: Dimensionality Reduction, Data Processing :sc-related: Classes/FluidMDS, Classes/FluidDataSet -:see-also: +:see-also: UMAP, PCA, DataSet :description: Dimensionality Reduction of a :fluid-obj:`DataSet` Using Multidimensional Scaling @@ -29,7 +29,7 @@ **Symmetric Kullback Leibler Divergence:** Because the first part of this computation uses the logarithm of the values, using the Symmetric Kullback Leibler Divergence only makes sense with non-negative data. https://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence#Symmetrised_divergence - .. **Cosine Distance:** Cosine Distance considers each data point a vector in Cartesian space and computes the angle between the two points. It first normalizes these vectors so they both sit on the unit circle and then finds the dot product of the two vectors which returns a calculation of the angle. Therefore this measure does not consider the magnitudes of the vectors when computing distance. https://en.wikipedia.org/wiki/Cosine_similarity (This article describes the cosine _similarity_, as opposed to distance, however since the cosine similarity is always between -1 and 1, the distance is computed as 1 - cosine similarity, which will always range from a minimum distance of 0 to a maximum distance of 2.) + .. **Cosine Distance:** Cosine Distance considers each data point a vector in Cartesian space and computes the angle between the two points. It first normalises these vectors so they both sit on the unit circle and then finds the dot product of the two vectors which returns a calculation of the angle. Therefore this measure does not consider the magnitudes of the vectors when computing distance. https://en.wikipedia.org/wiki/Cosine_similarity (This article describes the cosine _similarity_, as opposed to distance, however since the cosine similarity is always between -1 and 1, the distance is computed as 1 - cosine similarity, which will always range from a minimum distance of 0 to a maximum distance of 2.) :control numDimensions: @@ -57,7 +57,7 @@ Minkowski Min Distance :5: - Symmetric Kullback Leibler Divergance + Symmetric Kullback Leibler Divergence .. :6: .. Cosine Distance diff --git a/doc/MFCC.rst b/doc/MFCC.rst index 1d66a941..8d4af55f 100644 --- a/doc/MFCC.rst +++ b/doc/MFCC.rst @@ -1,4 +1,4 @@ -:digest: Mel-Frequency Cepstral Coefficients as Spectral Descriptors in Real-Time +:digest: Mel-Frequency Cepstral Coefficients as Spectral Descriptors in Realtime :species: descriptor :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation @@ -6,11 +6,11 @@ :description: A classic timbral audio descriptor, the Mel-Frequency Cepstral Coefficients (MFCCs). :discussion: - MFCC stands for Mel-Frequency Cepstral Coefficients ("cepstral" is pronounced like "kepstral"). This analysis is often used for timbral description and timbral comparison. It compresses the overall spectrum into a smaller number of coefficients that, when taken together, describe the general contour the the spectrum. + MFCC stands for Mel-Frequency Cepstral Coefficients ("cepstral" is pronounced like "kepstral"). This analysis is often used for timbral description and timbral comparison. It compresses the overall spectrum into a smaller number of coefficients that, when taken together, describe the general contour of the spectrum. - The MFCC values are derived by first computing a mel-frequency spectrum, just as in :fluid-obj:`MelBands`. ``numCoeffs`` coefficients are then calculated by using that mel-frequency spectrum as input to the discrete cosine transform. This means that the shape of the mel-frequency spectrum is compared to a number of cosine wave shapes (different cosines shapes created from different different frequencies). Each MFCC value (i.e., "coefficient") represents how similar the mel-frequency spectrum is to one of these cosine shapes. + The MFCC values are derived by first computing a mel-frequency spectrum, just as in :fluid-obj:`MelBands`. ``numCoeffs`` coefficients are then calculated by using that mel-frequency spectrum as input to the discrete cosine transform. This means that the shape of the mel-frequency spectrum is compared to a number of cosine wave shapes (different cosine shapes created from different frequencies). Each MFCC value (i.e., "coefficient") represents how similar the mel-frequency spectrum is to one of these cosine shapes. - Other that the 0th coefficient, MFCCs are unchanged by differences in the overall energy of the spectrum (which relates to how we perceive loudness). This means that timbres with similar spectral contours, but different volumes, will still have similar MFCC values, other than MFCC 0. To remove any indication of loudness but keep the information about timbre, we can ignore MFCC 0 by setting the parameter ``startCoeff`` to 1. + Other than the 0th coefficient, MFCCs are unchanged by differences in the overall energy of the spectrum (which relates to how we perceive loudness). This means that timbres with similar spectral contours, but different volumes, will still have similar MFCC values, other than MFCC 0. To remove any indication of loudness but keep the information about timbre, we can ignore MFCC 0 by setting the parameter ``startCoeff`` to 1. .. only_in:: sc diff --git a/doc/MLPClassifier.rst b/doc/MLPClassifier.rst index 6ed5fece..36860881 100644 --- a/doc/MLPClassifier.rst +++ b/doc/MLPClassifier.rst @@ -2,15 +2,17 @@ :species: data :sc-categories: Machine learning :sc-related: Classes/FluidMLPRegressor, Classes/FluidDataSet, Classes/FluidLabelSet -:see-also: +:see-also: MLPRegressor, KNNClassifier, DataSet, LabelSet :description: - Perform classification between a :fluid-obj:`DataSet` and a :fluid-obj:`LabelSet` using a Multi-Layer Perception neural network. + Perform classification between a :fluid-obj:`DataSet` and a :fluid-obj:`LabelSet` using a Multi-Layer Perceptron neural network. :discussion: For a thorough explanation of how this object works and more information on the parameters, visit the page on **MLP Training** (https://learn.flucoma.org/learn/mlp-training) and **MLP Parameters** (https://learn.flucoma.org/learn/mlp-parameters). + Also visit the classification tutorial: (https://learn.flucoma.org/learn/classification-neural-network/) + :control hiddenLayers: An array of numbers that specifies the internal structure of the neural network. Each number in the list represents one hidden layer of the neural network, the value of which is the number of neurons in that layer. Changing this will reset the neural network, clearing any learning that has happened. @@ -35,7 +37,7 @@ :control maxIter: - The number of epochs to train for when ``fit`` is called on the object. An epoch is consists of training on all the data points one time. + The number of epochs to train for when ``fit`` is called on the object. An epoch consists of training on all the data points one time. :control learnRate: diff --git a/doc/MLPRegressor.rst b/doc/MLPRegressor.rst index 5041a14d..91ce0e9b 100644 --- a/doc/MLPRegressor.rst +++ b/doc/MLPRegressor.rst @@ -2,15 +2,17 @@ :species: data :sc-categories: Machine learning :sc-related: Classes/FluidMLPClassifier, Classes/FluidDataSet -:see-also: +:see-also: KNNRegressor, DataSet, MLPClassifier :description: - Perform regression between :fluid-obj:`DataSet`\s using a Multi-Layer Perception neural network. + Perform regression between :fluid-obj:`DataSet`\s using a Multi-Layer Perceptron neural network. :discussion: For a thorough explanation of how this object works and more information on the parameters, visit the page on **MLP Training** (https://learn.flucoma.org/learn/mlp-training) and **MLP Parameters** (https://learn.flucoma.org/learn/mlp-parameters). + Also visit the regression tutorial: (https://learn.flucoma.org/learn/classification-neural-network/) + :control hiddenLayers: An array of numbers that specifies the internal structure of the neural network. Each number in the list represents one hidden layer of the neural network, the value of which is the number of neurons in that layer. Changing this will reset the neural network, clearing any learning that has happened. @@ -47,7 +49,7 @@ :control maxIter: - The number of epochs to train for when ``fit`` is called on the object. An epoch is consists of training on all the data points one time. + The number of epochs to train for when ``fit`` is called on the object. An epoch consists of training on all the data points one time. :control learnRate: diff --git a/doc/MelBands.rst b/doc/MelBands.rst index fa1e4566..9c40ba2b 100644 --- a/doc/MelBands.rst +++ b/doc/MelBands.rst @@ -6,7 +6,7 @@ :description: Magnitudes for a number of perceptually-evenly spaced bands. :discussion: - :fluid-obj:`MelBands` returns a Mel-Frequency Spectrum comprised of the user-defined ``numBands``. The Mel-Frequency Spectrum is a histogram of FFT bins bundled according their relationship to the Mel scale ( https://en.wikipedia.org/wiki/Mel_scale ) which represents frequency space logarithmically, mimicking how humans perceive pitch distance. The name "Mel" derives from the word "melody". The Hz-to-Mel conversion used by :fluid-obj:`MelBands` is ``mel = 1127.01048 * log(hz / 700.0 + 1.0)``. This implementation allows to select the range and number of bands dynamically. + :fluid-obj:`MelBands` returns a Mel-Frequency Spectrum comprised of the user-defined ``numBands``. The Mel-Frequency Spectrum is a histogram of FFT bins bundled according their relationship to the Mel scale ( https://en.wikipedia.org/wiki/Mel_scale ) which represents frequency space logarithmically, mimicking how humans perceive pitch distance. The name "Mel" derives from the word "melody". The Hz-to-Mel conversion used by :fluid-obj:`MelBands` is ``mel = 1127.01048 * log(hz / 700.0 + 1.0)``. This implementation allows the selection of the range and number of bands dynamically. When using a high value for ``numBands``, you may end up with empty channels (filled with zeros) in the MelBands output. This is because there is not enough information in the FFT analysis to properly calculate values for every MelBand. Increasing the ``fftSize`` will ensure you have values for all the MelBands. diff --git a/doc/NMFFilter.rst b/doc/NMFFilter.rst index a3ea2055..d45e7b5e 100644 --- a/doc/NMFFilter.rst +++ b/doc/NMFFilter.rst @@ -1,19 +1,19 @@ -:digest: Real-Time Non-Negative Matrix Factorisation with Fixed Bases +:digest: Realtime Non-Negative Matrix Factorisation with Fixed Bases :species: transformer :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation :see-also: NMFMatch, BufNMF :description: Decomposes and resynthesises a signal against a set of spectral templates :discussion: - This uses an slimmed-down version of Nonnegative Matrix Factorisation (NMF, see Lee, Daniel D., and H. Sebastian Seung. 1999. ‘Learning the Parts of Objects by Non-Negative Matrix Factorization’. Nature 401 (6755): 788–91. https://doi.org/10.1038/44565) + This uses a slimmed-down version of Nonnegative Matrix Factorisation (NMF, see Lee, Daniel D., and H. Sebastian Seung. 1999. ‘Learning the Parts of Objects by Non-Negative Matrix Factorization’. Nature 401 (6755): 788–91. https://doi.org/10.1038/44565) - It outputs as a signal the resynthesis of the best factorisation. The spectral templates are presumed to have been produced by the offline NMF process, BufNMF, and must be the correct size with respect to the FFT settings being used (FFT size / 2 + 1 frames long). The components of the decomposition is determined by the number of channels in the supplied buffer of templates, up to a maximum set by the maxComponents parameter. + It outputs as a signal the resynthesis of the best factorisation. The spectral templates are presumed to have been produced by the offline NMF process, BufNMF, and must be the correct size with respect to the FFT settings being used (FFT size / 2 + 1 frames long). The components of the decomposition are determined by the number of channels in the supplied buffer of templates, up to a maximum set by the maxComponents parameter. NMF has been a popular technique in signal processing research for things like source separation and transcription (see e.g. Smaragdis and Brown, Non-Negative Matrix Factorization for Polyphonic Music Transcription.), although its creative potential is so far relatively unexplored. It works iteratively, by trying to find a combination of amplitudes ('activations') that yield the original magnitude spectrogram of the audio input when added together. By and large, there is no unique answer to this question (i.e. there are different ways of accounting for an evolving spectrum in terms of some set of templates and envelopes). In its basic form, NMF is a form of unsupervised learning: it starts with some random data and then converges towards something that minimizes the distance between its generated data and the original:it tends to converge very quickly at first and then level out. Fewer iterations mean less processing, but also less predictable results. The whole process can be related to a channel vocoder where, instead of fixed bandpass filters, we get more complex filter shapes and the activations correspond to channel envelopes. -:process: The real-time processing method. It takes an audio input, and will yield a audio stream in the form of a multichannel array of size maxComponents . If the bases buffer has fewer than maxComponents channels, the remaining outputs will be zeroed. +:process: The realtime processing method. It takes an audio input, and will yield an audio stream in the form of a multichannel array of size maxComponents . If the bases buffer has fewer than maxComponents channels, the remaining outputs will be zeroed. :output: A multichannel kr output, giving for each basis component the activation amount. @@ -35,7 +35,7 @@ :control windowSize: - The number of samples that are analysed at a time. A lower number yields greater temporal resolution, at the expense of spectral resoultion, and vice-versa. + The number of samples that are analysed at a time. A lower number yields greater temporal resolution, at the expense of spectral resolution, and vice-versa. :control hopSize: diff --git a/doc/NMFMatch.rst b/doc/NMFMatch.rst index 570585bb..7c17d10d 100644 --- a/doc/NMFMatch.rst +++ b/doc/NMFMatch.rst @@ -1,19 +1,19 @@ -:digest: Real-Time Non-Negative Matrix Factorisation with Fixed Bases +:digest: Realtime Non-Negative Matrix Factorisation with Fixed Bases :species: descriptor :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation :see-also: NMFFilter, BufNMF :description: Matches an incoming audio signal against a set of spectral templates :discussion: - This uses an slimmed-down version of Nonnegative Matrix Factorisation (NMF, Lee, Daniel D., and H. Sebastian Seung. 1999. ‘Learning the Parts of Objects by Non-Negative Matrix Factorization’. Nature 401 (6755): 788–91. https://doi.org/10.1038/44565.) + This uses a slimmed-down version of Nonnegative Matrix Factorisation (NMF, Lee, Daniel D., and H. Sebastian Seung. 1999. ‘Learning the Parts of Objects by Non-Negative Matrix Factorization’. Nature 401 (6755): 788–91. https://doi.org/10.1038/44565.) - It outputs at kr the degree of detected match for each template (the activation amount, in NMF-terms). The spectral templates are presumed to have been produced by the offline NMF process (BufNMF), and must be the correct size with respect to the FFT settings being used (FFT size / 2 + 1 frames long). The components of the decomposition is determined by the number of channels in the supplied buffer of templates, up to a maximum set by the maxComponents parameter. + It outputs at kr the degree of detected match for each template (the activation amount, in NMF-terms). The spectral templates are presumed to have been produced by the offline NMF process (BufNMF), and must be the correct size with respect to the FFT settings being used (FFT size / 2 + 1 frames long). The components of the decomposition are determined by the number of channels in the supplied buffer of templates, up to a maximum set by the maxComponents parameter. NMF has been a popular technique in signal processing research for things like source separation and transcription (see e.g Smaragdis and Brown, Non-Negative Matrix Factorization for Polyphonic Music Transcription.), although its creative potential is so far relatively unexplored. It works iteratively, by trying to find a combination of amplitudes ('activations') that yield the original magnitude spectrogram of the audio input when added together. By and large, there is no unique answer to this question (i.e. there are different ways of accounting for an evolving spectrum in terms of some set of templates and envelopes). In its basic form, NMF is a form of unsupervised learning: it starts with some random data and then converges towards something that minimizes the distance between its generated data and the original:it tends to converge very quickly at first and then level out. Fewer iterations mean less processing, but also less predictable results. The whole process can be related to a channel vocoder where, instead of fixed bandpass filters, we get more complex filter shapes and the activations correspond to channel envelopes. -:process: The real-time processing method. It takes an audio or control input, and will yield a control stream in the form of a multichannel array of size maxComponents . If the bases buffer has fewer than maxComponents channels, the remaining outputs will be zeroed. +:process: The realtime processing method. It takes an audio or control input, and will yield a control stream in the form of a multichannel array of size maxComponents . If the bases buffer has fewer than maxComponents channels, the remaining outputs will be zeroed. :output: A multichannel kr output, giving for each basis component the activation amount. @@ -27,7 +27,7 @@ :control maxComponents: - The maximum number of elements the NMF algorithm will try to divide the spectrogram of the source in. This dictates the number of output channelsfor the ugen. This cannot be modulated. + The maximum number of elements the NMF algorithm will try to divide the spectrogram of the source in. This dictates the number of output channels. This cannot be modulated. :control iterations: @@ -35,7 +35,7 @@ :control windowSize: - The number of samples that are analysed at a time. A lower number yields greater temporal resolution, at the expense of spectral resoultion, and vice-versa. + The number of samples that are analysed at a time. A lower number yields greater temporal resolution, at the expense of spectral resolution, and vice-versa. :control hopSize: diff --git a/doc/Normalize.rst b/doc/Normalize.rst index d0ddc278..404a46e0 100644 --- a/doc/Normalize.rst +++ b/doc/Normalize.rst @@ -30,7 +30,7 @@ :arg destDataSet: The :fluid-obj:`DataSet` to populate with normalized data - Transform a :fluid-obj:`DataSet` using learned extrema from :fluid-obj:`Normalize#fit` and copy the results to the destination :fluid-obj:`DataSet`. + Transform a :fluid-obj:`DataSet` using learned extrema from ``fit`` and copy the results to the destination :fluid-obj:`DataSet`. :message fitTransform: @@ -48,7 +48,7 @@ :arg action: A function to run when processing is complete - Un-normalize :fluid-obj:`DataSet`, using the learned statistics from a previous call to :fluid-obj:`Normalize#fit`. + Un-normalize :fluid-obj:`DataSet`, using the learned statistics from a previous call to ``fit``. :message transformPoint: @@ -56,7 +56,7 @@ :arg destBuffer: A |buffer| to contain the normalized value - Normalize a single data point, using the learned extrema from a previous call to :fluid-obj:`Normalize#fit` + Normalize a single data point, using the learned extrema from a previous call to ``fit`` :message inverseTransformPoint: @@ -66,4 +66,4 @@ :arg action: A function to run when processing is complete - Un-normalize a data point, using the learned statistics from a previous call to :fluid-obj:`Normalize#fit` \ No newline at end of file + Un-normalize a data point, using the learned statistics from a previous call to ``fit`` \ No newline at end of file diff --git a/doc/NoveltyFeature.rst b/doc/NoveltyFeature.rst index 65b3b6e3..b30c6431 100644 --- a/doc/NoveltyFeature.rst +++ b/doc/NoveltyFeature.rst @@ -35,11 +35,11 @@ :control 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. + 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. :control 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. + The size of a smoothing filter that is applied on the novelty curve. A larger filter size allows for cleaner cuts on very sharp changes. :control windowSize: diff --git a/doc/NoveltySlice.rst b/doc/NoveltySlice.rst index 14d325cc..6880fbdf 100644 --- a/doc/NoveltySlice.rst +++ b/doc/NoveltySlice.rst @@ -1,13 +1,13 @@ -:digest: Real-Time Novelty-Based Slicer +:digest: Realtime Novelty-Based Slicer :species: slicer :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation :see-also: BufNoveltySlice, OnsetSlice, AmpSlice, TransientSlice -:description: A real-time slicer using an algorithm assessing novelty in the signal to estimate the slicing points. +:description: A realtime slicer using an algorithm assessing novelty in the signal to estimate the slicing points. :discussion: - A novelty curve is derived from running a kernel across the diagonal of the similarity matrix, and looking for peak of changes. It implements the algorithm published in 'Automatic Audio Segmentation Using a Measure of Audio Novelty' by J Foote. + A novelty curve is derived from running a kernel across the diagonal of the similarity matrix, and looking for peaks of changes. It implements the algorithm published in 'Automatic Audio Segmentation Using a Measure of Audio Novelty' by J Foote. - The process will return an audio steam with single sample impulses at estimated starting points of the different slices. + The process will return an audio stream with single sample impulses at estimated starting points of the different slices. :output: An audio stream with impulses at detected transients. The latency between the input and the output is hopSize * (((kernelSize+1)/2).asInteger + ((filterSize + 1) / 2).asInteger + 1) samples at maximum. @@ -23,19 +23,19 @@ :enum: :0: - Spectrum – The magnitude of the full spectrum. + Spectrum - The magnitude of the full spectrum. :1: - MFCC – 13 Mel-Frequency Cepstrum Coefficients. + MFCC - 13 Mel-Frequency Cepstrum Coefficients. :2: Chroma - The contour of a 12-band chromagram. :3: - Pitch – The pitch and its confidence. + Pitch - The pitch and its confidence. :4: - Loudness – The true peak and loudness. + Loudness - The true peak and loudness. :control kernelSize: @@ -43,11 +43,11 @@ :control threshold: - The normalised threshold, between 0 an 1, on the novelty curve to consider it a segmentation point. + The normalised threshold, between 0 and 1, on the novelty curve to consider it a segmentation point. :control 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. + The size of a smoothing filter that is applied on the novelty curve. A larger filter size allows for cleaner cuts on very sharp changes. :control minSliceLength: diff --git a/doc/OnsetFeature.rst b/doc/OnsetFeature.rst index ae9cdd3c..bcc03e5a 100644 --- a/doc/OnsetFeature.rst +++ b/doc/OnsetFeature.rst @@ -25,7 +25,7 @@ **HFC** thresholds on (sum of (squared magnitudes * binNum) / nBins) :2: - **SpectralFlux** thresholds on (diffence in magnitude between consecutive frames, half rectified) + **SpectralFlux** thresholds on (difference in magnitude between consecutive frames, half rectified) :3: **MKL** thresholds on (sum of log of magnitude ratio per bin) (or equivalently, sum of difference of the log magnitude per bin) (like Onsets mkl) @@ -50,11 +50,11 @@ :control 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. + The size of a smoothing filter that is applied on the novelty curve. A larger filter size allows for cleaner cuts on very sharp changes. :control 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. + 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 distance between the comparison window in samples. :control windowSize: diff --git a/doc/OnsetSlice.rst b/doc/OnsetSlice.rst index 2c640c81..4042256e 100644 --- a/doc/OnsetSlice.rst +++ b/doc/OnsetSlice.rst @@ -1,4 +1,4 @@ -:digest: Spectral Difference-Based Real-Time Audio Slicer +:digest: Spectral Difference-Based Realtime Audio Slicer :species: slicer :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation @@ -30,7 +30,7 @@ **HFC** thresholds on (sum of (squared magnitudes * binNum) / nBins) :2: - **SpectralFlux** thresholds on (diffence in magnitude between consecutive frames, half rectified) + **SpectralFlux** thresholds on (difference in magnitude between consecutive frames, half rectified) :3: **MKL** thresholds on (sum of log of magnitude ratio per bin) (or equivalently, sum of difference of the log magnitude per bin) (like Onsets mkl) @@ -63,7 +63,7 @@ :control 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. + The size of a smoothing filter that is applied on the novelty curve. A larger filter size allows for cleaner cuts on very sharp changes. :control frameDelta: diff --git a/doc/PCA.rst b/doc/PCA.rst index 351fcd41..2160b024 100644 --- a/doc/PCA.rst +++ b/doc/PCA.rst @@ -2,7 +2,7 @@ :species: data :sc-categories: Dimensionality Reduction, Data Processing :sc-related: Classes/FluidMDS, Classes/FluidDataSet -:see-also: +:see-also: UMAP, MDS, DataSet :description: Principal Components Analysis (PCA) of a :fluid-obj:`DataSet`. @@ -54,7 +54,7 @@ :arg action: Run when done - :fluid-obj:`PCA#fit` and :fluid-obj:`PCA#transform` in a single pass. Returns the fraction (between 0 and 1) of explained variance. + ``fit`` and ``transform`` in a single pass. Returns the fraction (between 0 and 1) of explained variance. :message transformPoint: @@ -64,7 +64,7 @@ :arg action: Run when done - Given a trained model, transform the data point in ``sourceBuffer`` from the original dimensional space to ``numDimensions`` in PCA-space and write into ``destBuffer``. + Given a trained model, transform the data point in ``sourceBuffer`` from the original dimensional space to ``numDimensions`` in PCA-space and write the result into ``destBuffer``. :message inverseTransformPoint: diff --git a/doc/Pitch.rst b/doc/Pitch.rst index 1c5c6ebd..877caebd 100644 --- a/doc/Pitch.rst +++ b/doc/Pitch.rst @@ -3,6 +3,7 @@ :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation, Classes/Pitch :see-also: BufPitch, MFCC, MelBands, Loudness, SpectralShape +:max-seealso: fzero~, retune~ :description: Three popular monophonic pitch descriptors, all of which compute frequency and confidence. :discussion: @@ -53,7 +54,7 @@ :control unit: - The unit of the pitch output. The default of 0 indicates to output in Hz. A value of 1 will output MIDI note values. + The unit of the pitch output. The default of 0 indicates output in Hz. A value of 1 will output MIDI note values. :control windowSize: diff --git a/doc/RobustScale.rst b/doc/RobustScale.rst index 6cbd308a..6c7f044e 100644 --- a/doc/RobustScale.rst +++ b/doc/RobustScale.rst @@ -2,7 +2,7 @@ :species: data :sc-categories: FluidManipulation :sc-related: Classes/FluidStandardize, Classes/FluidNormalize, Classes/FluidDataSet -:see-also: +:see-also: Normalize, Standardize :description: Apply Robust Scaling to a :fluid-obj:`DataSet` based on statistics of the data such that each dimension has a median centred on 0 and a range of 1 from the ``low`` percentile to the ``high`` percentile. @@ -33,7 +33,7 @@ :arg destDataSet: The :fluid-obj:`DataSet` to write the scaled data to. - Scale a :fluid-obj:`DataSet` into another :fluid-obj:`DataSet`, using the learned statistics from the previous call to :fluid-obj:`RobustScale#fit` + Scale a :fluid-obj:`DataSet` into another :fluid-obj:`DataSet`, using the learned statistics from the previous call to ``fit`` :message inverseTransform: @@ -41,7 +41,7 @@ :arg destDataSet: The :fluid-obj:`DataSet` to write the scaled data to. - Inverse scale a :fluid-obj:`DataSet` into another :fluid-obj:`DataSet`: going from the range of the scaled data back to the range of the data that was used in the previous call to :fluid-obj:`RobustScale#fit` + Inverse scale a :fluid-obj:`DataSet` into another :fluid-obj:`DataSet`: going from the range of the scaled data back to the range of the data that was used in the previous call to ``fit`` :message fitTransform: @@ -57,7 +57,7 @@ :arg destBuffer: A |buffer| to write the scaled values to - Scale a data point, using the learned statistics from the previous call to :fluid-obj:`RobustScale#fit` + Scale a data point, using the learned statistics from the previous call to ``fit`` :message inverseTransformPoint: diff --git a/doc/SKMeans.rst b/doc/SKMeans.rst index 949764a2..af0a8ac2 100644 --- a/doc/SKMeans.rst +++ b/doc/SKMeans.rst @@ -9,7 +9,7 @@ :discussion: - :fluid-obj:`SKMeans` is an implementation of KMeans based on cosine distances instead of euclidian ones, measuring the angles between the normalised vectors. + :fluid-obj:`SKMeans` is an implementation of KMeans based on cosine distances instead of euclidean ones, measuring the angles between the normalised vectors. One common application of spherical KMeans is to try and learn features directly from input data (via a :fluid-obj:`DataSet`) without supervision. See this reference for a more technical explanation: https://machinelearningcatalogue.com/algorithm/alg_spherical-k-means.html and https://www-cs.stanford.edu/~acoates/papers/coatesng_nntot2012.pdf for feature extractions. :control numClusters: @@ -50,7 +50,7 @@ :arg action: A function to run when the server responds - Run :fluid-obj:`KMeans#*fit` and :fluid-obj:`KMeans#*predict` in a single pass: i.e. train the model on the incoming :fluid-obj:`DataSet` and then return the learned clustering to the passed :fluid-obj:`LabelSet` + Run ``fit`` and ``predict`` in a single pass: i.e. train the model on the incoming :fluid-obj:`DataSet` and then return the learned clustering to the passed :fluid-obj:`LabelSet` :message predictPoint: @@ -78,7 +78,7 @@ :arg action: A function to run when the server responds - Run :fluid-obj:`SKMeans#*fit` and :fluid-obj:`SKMeans#*encode` in a single pass: i.e. train the model on the incoming :fluid-obj:`DataSet` and then return its encoded cluster-activation space in the destination :fluid-obj:`DataSet` + Run ``fit`` and ``encode`` in a single pass: i.e. train the model on the incoming :fluid-obj:`DataSet` and then return its encoded cluster-activation space in the destination :fluid-obj:`DataSet` :message encodePoint: @@ -104,7 +104,7 @@ :arg action: A function to run when complete. - Overwrites the means (centroids) of each cluster, and declare the object trained. + Overwrites the means (centroids) of each cluster, and declares the object trained. :message clear: diff --git a/doc/STFTPass.rst b/doc/STFTPass.rst index ac6c305f..9264b0d9 100644 --- a/doc/STFTPass.rst +++ b/doc/STFTPass.rst @@ -1,9 +1,9 @@ -:digest: Real-Time FFT/IFFT return trip. +:digest: Realtime FFT/IFFT return trip. :species: transformer :sc-categories: UGens>Algebraic, Libraries>FluidDecomposition, UGens>Buffer :sc-related: Guides/FluidCorpusManipulation,Classes/UnaryOpFunction :see-also: -:description: This class implements a sanity test for the FluCoMa Real-Time Client FFT/IFFT Wrapper. +:description: This class implements a sanity test for the FluCoMa Realtime Client FFT/IFFT Wrapper. :discussion: :process: The audio rate version of the object. :output: Same as input, delayed by the windowSize. diff --git a/doc/Sines.rst b/doc/Sines.rst index c1fccb24..c3a1c457 100644 --- a/doc/Sines.rst +++ b/doc/Sines.rst @@ -23,7 +23,7 @@ :control bandwidth: - The number of bins used to resynthesises a peak. It has an effect on CPU cost: the widest is more accurate but more computationally expensive. It is capped at (fftSize / 2) + 1. + The number of bins used to resynthesise a peak. It has an effect on CPU cost: the widest is more accurate but more computationally expensive. It is capped at (fftSize / 2) + 1. :control detectionThreshold: @@ -39,7 +39,7 @@ :control minTrackLen: - The minimum duration, in spectral frames, for a sinusoidal track to be accepted as a partial. It allows to remove bubbly pitchy artefactss, but is more CPU intensive and might reject quick pitch material. + The minimum duration, in spectral frames, for a sinusoidal track to be accepted as a partial. It allows to remove bubbly pitchy artefacts, but is more CPU intensive and might reject quick pitch material. :control trackingMethod: diff --git a/doc/SpectralShape.rst b/doc/SpectralShape.rst index 96100dd5..981f3b9d 100644 --- a/doc/SpectralShape.rst +++ b/doc/SpectralShape.rst @@ -1,4 +1,4 @@ -:digest: Seven Spectral Shape Descriptors in Real-Time +:digest: Seven Spectral Shape Descriptors in Realtime :species: descriptor :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation, Classes/SpecCentroid, Classes/SpecFlatness, Classes/SpecCentroid, Classes/SpecPcile @@ -10,18 +10,18 @@ * the four first statistical moments (``_), more commonly known as: * the spectral centroid (1) in Hertz. This is the point that splits the spectrum in 2 halves of equal energy. It is the weighted average of the magnitude spectrum. - * the spectral spread (2) in Hertz. This is the standard deviation of the spectrum envelop, or the average of the distance to the centroid. + * the spectral spread (2) in Hertz. This is the standard deviation of the spectrum envelope, or the average of the distance to the centroid. * the normalised skewness (3) as ratio. This indicates how tilted is the spectral curve in relation to the middle of the spectral frame, i.e. half of the Nyquist frequency. If it is below the frequency of the magnitude spectrum, it is positive. - * the normalised kurtosis (4) as ratio. This indicates how focused is the spectral curve. If it is peaky, it is high. + * the normalised kurtosis (4) as ratio. This indicates how focused the spectral curve is. If it is peaky, the value is high. * the rolloff (5) in Hertz. This indicates the frequency under which 95% of the energy is included. - * the flatness (6) in dB. This is the ratio of geometric mean of the magnitude, over the arithmetic mean of the magnitudes. It yields a very approximate measure on how noisy a signal is. - * the crest (7) in dB. This is the ratio of the loudest magnitude over the RMS of the whole frame. A high number is an indication of a loud peak poking out from the overal spectral curve. + * the flatness (6) in dB. This is the ratio of geometric mean to the magnitude, over the arithmetic mean of the magnitudes. It yields a very approximate measure on how noisy a signal is. + * the crest (7) in dB. This is the ratio of the loudest magnitude over the RMS of the whole frame. A high number is an indication of a loud peak poking out from the overall spectral curve. The drawings in Peeters 2003 ( http://recherche.ircam.fr/anasyn/peeters/ARTICLES/Peeters_2003_cuidadoaudiofeatures.pdf ) are useful, as are the commented examples below. For the mathematically-inclined reader, the tutorials and code offered here ( https://www.audiocontentanalysis.org/ ) are interesting to further the understanding. For examples of the impact of computing the moments in power magnitudes, and/or in exponential frequency scale, please refer to the helpfile. - The process will return a multichannel control steam with the seven values, 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 stream with the seven values, which will be repeated if no change happens within the algorithm, i.e. when the hopSize is larger than the signal vector size. :process: The audio rate in, control rate out version of the object. :output: A 7-channel KR signal with the seven spectral shape descriptors. The latency is windowSize. diff --git a/doc/Standardize.rst b/doc/Standardize.rst index 0c7e4b0c..3f1575cf 100644 --- a/doc/Standardize.rst +++ b/doc/Standardize.rst @@ -2,7 +2,7 @@ :species: data :sc-categories: FluidManipulation :sc-related: Classes/FluidDataSet, Classes/FluidStandardize -:see-also: +:see-also: Normalize, RobustScale :description: Standardize a :fluid-obj:`DataSet`. Rescale using its mean(s) and standard deviation(s) in each dimension, such that each dimension has a mean of 0 and a standard deviation of 1. @@ -24,7 +24,7 @@ :arg action: A function to run when processing is complete - Standardize a :fluid-obj:`DataSet`, using the learned statistics from a previous call to :fluid-obj:`Standardize#fit` + Standardize a :fluid-obj:`DataSet`, using the learned statistics from a previous call to ``fit`` :message fitTransform: @@ -44,7 +44,7 @@ :arg action: A function to run when processing is complete - Un-standardize a :fluid-obj:`DataSet`, using the learned statistics from a previous call to :fluid-obj:`Standardize#fit`. + Un-standardize a :fluid-obj:`DataSet`, using the learned statistics from a previous call to ``fit``. :message transformPoint: @@ -54,7 +54,7 @@ :arg action: A function to run when processing is complete - Standardize a data point, using the learned statistics from a previous call to :fluid-obj:`Standardize#fit` + Standardize a data point, using the learned statistics from a previous call to ``fit`` :message inverseTransformPoint: @@ -64,4 +64,4 @@ :arg action: A function to run when processing is complete - Un-standardize a data point, using the learned statistics from a previous call to :fluid-obj:`Standardize#fit` + Un-standardize a data point, using the learned statistics from a previous call to ``fit`` diff --git a/doc/Stats.rst b/doc/Stats.rst index 60d470b2..6f1d1c87 100644 --- a/doc/Stats.rst +++ b/doc/Stats.rst @@ -2,7 +2,7 @@ :species: descriptor :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation -:see-also: BufStats, Standardize +:see-also: BufStats, Standardize, Normalize, RobustScale :description: Computes the rolling mean and sample standard deviation over a given window for multichannel control inputs. :discussion: diff --git a/doc/TransientSlice.rst b/doc/TransientSlice.rst index 21a0c706..ebb5fbcb 100644 --- a/doc/TransientSlice.rst +++ b/doc/TransientSlice.rst @@ -1,16 +1,16 @@ -:digest: Transient-Based Real-Time Audio Slicer +:digest: Transient-Based Realtime Audio Slicer :species: slicer :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation :see-also: BufTransientSlice, AmpSlice, NoveltySlice, OnsetSlice -:description: A real-time transient-based slice extractor +:description: A realtime transient-based slice extractor :discussion: TransientSlice identifies slice points in a real time signal by implementing a "de-clicking" algorithm based on the assumption that a transient is a sample or series of samples that are anomalous when compared to surrounding samples. It creates a model of the time series of samples, so that when a given sample doesn't fit the model (its "error" or anomalous-ness goes above ``threshFwd``) it is determined to be a transient and a slice point is identified. The series of samples determined to be a transient will continue until the error goes below ``threshBack``, indicating that the samples are again more in-line with the model. - The process will return an audio steam with single sample impulses at estimated starting points of the different slices. + The process will return an audio stream with single sample impulses at estimated starting points of the different slices. The algorithm implemented is from chapter 5 of "Digital Audio Restoration" by Godsill, Simon J., Rayner, Peter J.W. with some bespoke improvements on the detection function tracking. @@ -27,7 +27,7 @@ :control blockSize: - The size of audio chunk (in samples) on which the process is operating. This determines the maximum duration (in samples) of a detected transient, which cannot be more than than half of ``blockSize - order``. High values are more cpu intensive. + The size of audio block (in samples) on which the process is operating. This determines the maximum duration (in samples) of a detected transient, which cannot be more than half of ``blockSize - order``. High values are more cpu intensive. :control padSize: @@ -39,11 +39,11 @@ :control threshFwd: - The threshold applied to the smoothed forward prediction error for determining an onset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be detected as a transient. It allows tight start of the identification of the anomaly as it proceeds forward. + The threshold applied to the smoothed forward prediction error for determining an onset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be detected as a transient. It allows tight identification of the start of the anomaly as it proceeds forward. :control threshBack: - The threshold applied to the smoothed backward prediction error for determining an offset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be considered transient. When the smoothed error function goes below ``threshBack`` an offset is identified. As it proceeds backwards in time, it allows tight ending of the identification of the anomaly. + The threshold applied to the smoothed backward prediction error for determining an offset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be considered transient. When the smoothed error function goes below ``threshBack`` an offset is identified. As it proceeds backwards in time, it allows tight identification of the end of the anomaly. :control windowSize: @@ -51,7 +51,7 @@ :control clumpLength: - The window size in samples within which anomalous samples will be clumped together to avoid over detecting in time. This is similar to setting a minimum slice length. + The window size in samples within which anomalous samples will be clumped together to avoid over-detecting in time. This is similar to setting a minimum slice length. :control minSliceLength: diff --git a/doc/Transients.rst b/doc/Transients.rst index b10ad537..7a8696b2 100644 --- a/doc/Transients.rst +++ b/doc/Transients.rst @@ -1,14 +1,14 @@ -:digest: Real-Time Transient Modeller and Extractor +:digest: Realtime Transient Modeller and Extractor :species: transformer :sc-categories: Libraries>FluidDecomposition :sc-related: Guides/FluidCorpusManipulation -:see-also: BufTransients,Sines,HPSS +:see-also: BufTransients, Sines, HPSS :description: Separate transients from a signal. :discussion: This implements a "de-clicking" algorithm based on the assumption that a transient is a sample or series of samples that are anomalous when compared to surrounding samples. It creates a model of the time series of samples, so that when a given sample doesn't fit the model (its "error" or anomalous-ness goes above ``threshFwd``) it is determined to be a transient. The series of samples determined to be a transient will continue until the error goes below ``threshBack``, indicating that the samples are again more in-line with the model. - The algorithm then estimates what should have happened during the transient period if the signal had followed its non-anomalous path, and resynthesises this estimate to create the residual output. The transient output is ``input signal - residual signal``, such that summed output of the object (``transients + residual``) can still null-sum with the input. + The algorithm then estimates what should have happened during the transient period if the signal had followed its non-anomalous path, and resynthesises this estimate to create the residual output. The transient output is ``input signal - residual signal``, such that the summed output of the object (``transients + residual``) can null-sum with the input. The algorithm will take an audio in, and will divide it in two outputs: * the transients, estimated from the signal and extracted from it @@ -29,7 +29,7 @@ :control blockSize: - The size of audio chunk (in samples) on which the process is operating. This determines the maximum duration (in samples) of a detected transient, which cannot be more than than half of ``blockSize - order``. High values are more cpu intensive. + The size of audio block (in samples) on which the process is operating. This determines the maximum duration (in samples) of a detected transient, which cannot be more than half of ``blockSize - order``. High values are more cpu intensive. :control padSize: @@ -41,11 +41,11 @@ :control threshFwd: - The threshold applied to the smoothed forward prediction error for determining an onset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be detected as a transient. It allows tight start of the identification of the anomaly as it proceeds forward. + The threshold applied to the smoothed forward prediction error for determining an onset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be detected as a transient. It allows tight identification of the start of the anomaly as it proceeds forward. :control threshBack: - The threshold applied to the smoothed backward prediction error for determining an offset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be considered transient. When the smoothed error function goes below ``threshBack`` an offset is identified. As it proceeds backwards in time, it allows tight ending of the identification of the anomaly. + The threshold applied to the smoothed backward prediction error for determining an offset. The units are roughly in standard deviations, thus can be considered how "deviant", or anomalous, the signal must be to be considered transient. When the smoothed error function goes below ``threshBack`` an offset is identified. As it proceeds backwards in time, it allows tight identification of the end of the anomaly. :control windowSize: @@ -53,4 +53,4 @@ :control clumpLength: - The window size in samples within which anomalous samples will be clumped together to avoid over detecting in time. This is like setting a minimum transient length. + The window size in samples within which anomalous samples will be clumped together to avoid over-detecting in time. This is like setting a minimum transient length. diff --git a/doc/UMAP.rst b/doc/UMAP.rst index 22280246..50a5f186 100644 --- a/doc/UMAP.rst +++ b/doc/UMAP.rst @@ -2,7 +2,7 @@ :species: data :sc-categories: Dimensionality Reduction, Data Processing :sc-related: Classes/FluidMDS, Classes/FluidDataSet -:see-also: +:see-also: MDS, PCA, DataSet :description: Reduce the dimensions of a :fluid-obj:`DataSet` using the Uniform Manifold Approximation and Projection (UMAP) algorithm. :discussion: Performs dimensionality reduction of a :fluid-obj:`DataSet` using Uniform Manifold Approximation and Projection (UMAP) @@ -21,7 +21,7 @@ :control numNeighbours: - The number of neighbours considered by the algorithm to balance local vs global structures to conserve. Low values will prioritise preserving local structure, high values will help preserving the global structure. + The number of neighbours considered by the algorithm to balance local vs global structures to conserve. Low values will prioritise preservation of the local structure while high values will prioritise preservation of the global structure. :control minDist: diff --git a/example-code/sc/BufAudioTransport.scd b/example-code/sc/BufAudioTransport.scd index 41a2269e..b5fab464 100644 --- a/example-code/sc/BufAudioTransport.scd +++ b/example-code/sc/BufAudioTransport.scd @@ -16,7 +16,7 @@ b.play c.play d.play -// note that the process is quantized by the spectral bins. For an example of the pros and cons of these settings on this given process, please see the real-time FluidAudioTransport helpfile. +// note that the process is quantized by the spectral bins. For an example of the pros and cons of these settings on this given process, please see the realtime FluidAudioTransport helpfile. // more interesting sources: two cardboard bowing gestures ( diff --git a/example-code/sc/BufNMF.scd b/example-code/sc/BufNMF.scd index 4168a88c..8cfd3891 100644 --- a/example-code/sc/BufNMF.scd +++ b/example-code/sc/BufNMF.scd @@ -84,7 +84,7 @@ FluidWaveform(featuresBuffer:~bases,bounds:Rect(0,0,1200,300)); ~resynth.play; // ======== to further understand NMF's bases and activations, consider one more object: FluidNMFFilter ========== -// FluidNMFFilter will use the bases (spectral templates) of a FluidBufNMF analysis to filter (i.e., decompose) real-time audio +// FluidNMFFilter will use the bases (spectral templates) of a FluidBufNMF analysis to filter (i.e., decompose) realtime audio // for example, if we use the bases from the ~drums analysis above, it will separate the snare from the kick & hi hat like before // this time you'll hear one in each stereo channel (again, results may vary) @@ -97,9 +97,9 @@ FluidWaveform(featuresBuffer:~bases,bounds:Rect(0,0,1200,300)); }.play; ) -// if we play a different source through FluidNMFFilter, it will try to decompose that real-time signal according to the bases +// if we play a different source through FluidNMFFilter, it will try to decompose that realtime signal according to the bases // it is given (in our case the bases from the drum loop) -~song = Buffer.readChannel(s,FluidFilesPath("Tremblay-beatRemember.wav"),channels:[0]); +~song = Buffer.readChannel(s,FluidFilesPath("Tremblay-BeatRemember.wav"),channels:[0]); ( { diff --git a/example-code/sc/HPSS.scd b/example-code/sc/HPSS.scd index c0988de2..c4986268 100644 --- a/example-code/sc/HPSS.scd +++ b/example-code/sc/HPSS.scd @@ -54,7 +54,7 @@ STRONG::Masking Modes:: CODE:: //load a soundfile to play -~buf = Buffer.readChannel(s,FluidFilesPath("Tremblay-beatRemember.wav"),channels:[0]); +~buf = Buffer.readChannel(s,FluidFilesPath("Tremblay-BeatRemember.wav"),channels:[0]); // ==================== masking mode = 0: soft mask ======================= // masking mode 0 uses a soft mask to separate the two components @@ -115,7 +115,7 @@ STRONG::Latency and Null-Sum Test:: CODE:: -~buf = Buffer.readChannel(s,FluidFilesPath("Tremblay-beatRemember.wav"),channels:[0]); +~buf = Buffer.readChannel(s,FluidFilesPath("Tremblay-BeatRemember.wav"),channels:[0]); // add a latency to the processed signal of (((harmFilterSize - 1) * hopSize) + windowSize) samples // this should output silence (because the null-summing is working)! diff --git a/example-code/sc/KDTree.scd b/example-code/sc/KDTree.scd index 9fd67db3..e29e857d 100644 --- a/example-code/sc/KDTree.scd +++ b/example-code/sc/KDTree.scd @@ -26,7 +26,7 @@ fork{ ( ~p = [ 1.0.linrand,1.0.linrand ]; ~tmpbuf = Buffer.loadCollection(s, ~p, 1, { - ~tree.kNearest(~tmpbuf,{ |a|a.postln;~nearest = a;}) + ~tree.kNearest(~tmpbuf, action:{ |a|a.postln;~nearest = a;}) }); ) @@ -40,21 +40,21 @@ fork{ } ) // Distances of the nearest points -~tree.kNearestDist(~tmpbuf, { |a| a.postln }); +~tree.kNearestDist(~tmpbuf, action:{ |a| a.postln }); // Explore changing the number of neighbourgs ~tree.numNeighbours = 11; // note that this value needs to be sent to the server -~tree.kNearest(~tmpbuf,{ |a|a.postln;}); +~tree.kNearest(~tmpbuf, action:{ |a|a.postln;}); ~tree.numNeighbours = 0; // 0 will return all items in order of distance -~tree.kNearest(~tmpbuf,{ |a|a.postln;}); +~tree.kNearest(~tmpbuf, action:{ |a|a.postln;}); // Limit the search to an acceptable distance in a radius // Define a point, and observe typical distance values ~p = [ 0.4,0.4]; ( ~tmpbuf = Buffer.loadCollection(s, ~p, 1, { - ~tree.kNearest(~tmpbuf,{ |a|a.postln;}); - ~tree.kNearestDist(~tmpbuf,{ |a|a.postln;}); + ~tree.kNearest(~tmpbuf, action:{ |a|a.postln;}); + ~tree.kNearestDist(~tmpbuf, action:{ |a|a.postln;}); }); ) @@ -63,7 +63,7 @@ fork{ // FluidKDTree will return only values that are within that radius, up to numNeighbours values ( ~tmpbuf = Buffer.loadCollection(s, ~p, 1, { - ~tree.kNearest(~tmpbuf,{ |a|a.postln;}); + ~tree.kNearest(~tmpbuf, action:{ |a|a.postln;}); }); ) :: diff --git a/example-code/sc/MFCC.scd b/example-code/sc/MFCC.scd index 37d6a88d..d5d60b5e 100644 --- a/example-code/sc/MFCC.scd +++ b/example-code/sc/MFCC.scd @@ -1,7 +1,7 @@ code:: -// a window to watch the MFCC analyses in real-time +// a window to watch the MFCC analyses in realtime ( ~win = Window("MFCCs Monitor",Rect(0,0,800,400)).front; ~ms = MultiSliderView(~win,Rect(0,0,~win.bounds.width,~win.bounds.height)).elasticMode_(1).isFilled_(1); @@ -71,7 +71,7 @@ OSCdef(\mfccs,{ ) :: -STRONG::Comparing MFCC Analyses in real-time:: +STRONG::Comparing MFCC Analyses in realtime:: CODE:: // we'll compare trombone to trombone (but at different playback rates to fake 2 different players @@ -147,8 +147,10 @@ CODE:: arg key; labels["data"][key] = [key[0..2]]; }; - ~plotter = FluidPlotter(bounds:Rect(0,0,800,800),dict:dict); // plot it: bass analyses will be one color, boxes will be another - ~plotter.categories_(labels); + { + ~plotter = FluidPlotter(bounds:Rect(0,0,800,800),dict:dict); // plot it: bass analyses will be one color, boxes will be another + ~plotter.categories_(labels); + }.defer; }); ) diff --git a/example-code/sc/MLPClassifier.scd b/example-code/sc/MLPClassifier.scd index 304e0e24..d8a2b360 100644 --- a/example-code/sc/MLPClassifier.scd +++ b/example-code/sc/MLPClassifier.scd @@ -1,4 +1,4 @@ -strong::Real-Time Tweaking Parameters:: +strong::Realtime Tweaking Parameters:: code:: s.boot; diff --git a/example-code/sc/NMFFilter.scd b/example-code/sc/NMFFilter.scd index a36b448e..69caf880 100644 --- a/example-code/sc/NMFFilter.scd +++ b/example-code/sc/NMFFilter.scd @@ -30,13 +30,13 @@ fork{ // If the process did not separate out the kick drum, hi hat, and snare drum (in any order) very well, try it again until it does. // It will be useful going forward to have bases that pretty well represent these drum instruments. -// FluidNMFFilter will use the bases (spectral templates) of a FluidBufNMF analysis to filter (i.e., decompose) real-time audio +// FluidNMFFilter will use the bases (spectral templates) of a FluidBufNMF analysis to filter (i.e., decompose) realtime audio // First, we'll just send the same drum loop through FluidNMFFilter to hear it in action: ( fork{ ~n_components.do{ arg i; - "decomposed part #% filtered in real-time using FluidNMFFilter".format(i+1).postln; + "decomposed part #% filtered in realtime using FluidNMFFilter".format(i+1).postln; { var src = PlayBuf.ar(1,~drums,BufRateScale.ir(~drums),doneAction:2); var sig = FluidNMFFilter.ar(src,~bases,~n_components)[i]; @@ -48,7 +48,7 @@ fork{ ) /* It is seprating the drum instrument components just like it did with FluidBufNMF--the difference here is that it is -happening in real-time. */ +happening in realtime. */ // This means one could different FX to each instrument: @@ -69,7 +69,7 @@ happening in real-time. */ ) /* This also means that one could send a live input audio signal through FluidNMFFilter and get these -drum instruments similarly decomposed into separate audio streams in *real-time*. */ +drum instruments similarly decomposed into separate audio streams in *realtime*. */ /* To test an idea like this, we could train it on just the first few seconds of this drum loop (like a training set when using a neural network) and then see how it peforms on audio it hasn't seen before: the rest of the drum loop (similar to using @@ -92,7 +92,7 @@ FluidBufNMF.processBlocking(s,~drums_training,bases:~bases_from_training,compone fork{ 3.do{ arg i; - "decomposed part #% filtered in real-time using FluidNMFFilter\n\tIt has never heard this part of the drum loop!\n".format(i+1).postln; + "decomposed part #% filtered in realtime using FluidNMFFilter\n\tIt has never heard this part of the drum loop!\n".format(i+1).postln; { var src = PlayBuf.ar(1,~drums_testing,BufRateScale.ir(~drums_testing),doneAction:2); var sig = FluidNMFFilter.ar(src,~bases_from_training,3)[i]; @@ -103,16 +103,16 @@ fork{ }; ) -// If we play a different source through FluidNMFFilter, it will try to decompose that real-time signal according to the bases +// If we play a different source through FluidNMFFilter, it will try to decompose that realtime signal according to the bases // it is given (in our case the bases from the drum loop) -~song = Buffer.readChannel(s,FluidFilesPath("Tremblay-beatRemember.wav"),channels:[0]); +~song = Buffer.readChannel(s,FluidFilesPath("Tremblay-BeatRemember.wav"),channels:[0]); ( fork{ ~n_components.do{ arg i; - "decomposed part #% filtered in real-time using FluidNMFFilter".format(i+1).postln; + "decomposed part #% filtered in realtime using FluidNMFFilter".format(i+1).postln; { var src = PlayBuf.ar(1,~song,BufRateScale.ir(~song),doneAction:2); var sig = FluidNMFFilter.ar(src,~bases,~n_components)[i]; diff --git a/flucoma/doc/max/driver.py b/flucoma/doc/max/driver.py index 3fcf8209..a77d995a 100644 --- a/flucoma/doc/max/driver.py +++ b/flucoma/doc/max/driver.py @@ -9,7 +9,7 @@ import json from docutils import nodes - +import logging from flucoma.doc.rst.html import FluidHTMLWriter, rst_filter from .. transformers import default_transform from .defaults import defaults @@ -18,12 +18,19 @@ def buffer_reference_role(role, rawtext, text, lineno, inliner, options={}, content=[]): return 'buffer~' +def visit_object_reference(self, node): + # node[:] = [nodes.raw('',node.astext(), format='html')] + # self.body.append(self.starttag(node, 'o')) + # self.body.append('') + self.body.append(f'{node.astext()}') + def max_visit_flucoma_reference(self, node, data, transform_name): if transform_name: if(node.astext()) in data: name = max_object_namer(data[node.astext()]) - else: + else: name = f'Unresolved lookup ({node.astext()})' + logging.warn(name) else: name = node.astext() @@ -101,6 +108,7 @@ def write_max_indices(idx,program_args): 'rst_render': rst_filter, 'write_cross_ref': (max_visit_flucoma_reference, max_depart_flucoma_reference), + 'write_object_ref': visit_object_reference, 'topic_extension': 'maxvig.xml', 'topic_subdir': 'vignettes', 'client_subdir': '', @@ -108,5 +116,5 @@ def write_max_indices(idx,program_args): 'transform': transform_data, 'post': write_max_indices, 'defaults': defaults, - 'buffer-string':'buffer~' + 'buffer-string':':object-link:`buffer~`' } diff --git a/flucoma/doc/render.py b/flucoma/doc/render.py index e3b5fde2..3465f37c 100644 --- a/flucoma/doc/render.py +++ b/flucoma/doc/render.py @@ -34,7 +34,7 @@ def setup_jinja(client_index, args, driver): examples_path = (args.doc_path.resolve() / '../example-code' / args.host).resolve() e = Environment( loader = FileSystemLoader([args.template_path, examples_path]), - autoescape=select_autoescape(['html','xml']), + autoescape=select_autoescape(disabled_extensions=('html','xml','schelp')), trim_blocks=True, lstrip_blocks=True ) """ diff --git a/flucoma/doc/rst/docutils.py b/flucoma/doc/rst/docutils.py index a020ec5f..324b843a 100644 --- a/flucoma/doc/rst/docutils.py +++ b/flucoma/doc/rst/docutils.py @@ -29,10 +29,21 @@ def fluid_topic_role(role, rawtext, text, lineno, inliner, node = nodes.reference(rawtext,utils.unescape(text), **options) return [node], [] +def object_link_role(role, rawtext, text, lineno, inliner, + options={}, content=[]): + """ + Create a link to another (non-flucoma) CCE object. + Basically this is all to sort out linking to buffer~ in the Max docs + """ + options['object-link'] = 1 + roles.set_classes(options) + node = nodes.reference(rawtext,utils.unescape(text), **options) + return [node], [] + def register_custom_roles(): roles.register_local_role('fluid-obj', fluid_object_role) roles.register_local_role('fluid-topic', fluid_topic_role) - + roles.register_local_role('object-link',object_link_role) class OnlyDirective(Directive): final_argument_whitespace = True diff --git a/flucoma/doc/rst/html.py b/flucoma/doc/rst/html.py index df698c09..6350e39b 100644 --- a/flucoma/doc/rst/html.py +++ b/flucoma/doc/rst/html.py @@ -30,6 +30,8 @@ def visit_reference(self,node): self.visit_flucoma_reference(node) elif 'flucoma-topic' in node: self.visit_flucoma_topic(node) + elif 'object-link' in node: + self.visit_object_link(node) else: super().visit_reference(node) @@ -59,7 +61,12 @@ def visit_flucoma_topic(self,node): f = partial(driver['write_cross_ref'][0], data = index, transform_name = False) f(self,node) - + + def visit_object_link(self,node): + f = driver['write_object_ref'] + f(self,node) + raise nodes.SkipNode; + def depart_flucoma_reference(self,node): partial(driver['write_cross_ref'][1], data = index)(self,node) @@ -86,9 +93,15 @@ def rst_filter(ctx,value): driver = ctx.parent['driver'] index = ctx.parent['index'] + raw_role=""" +.. role:: raw-html(raw) + :format: html\n +""" + # value = raw_role + value value += f"\n\n.. |buffer| replace:: {driver.get('buffer-string','buffer')}\n" - + # logging.warn(value) + #stop docutils mirroing warnings to console, but we probably want to see errors settings = {'report_level':Reporter.ERROR_LEVEL,'flucoma-host':ctx['host']} @@ -96,7 +109,7 @@ def rst_filter(ctx,value): writer = FluidHTMLWriter(index, driver), reader = LoggingDocutilsReader(), settings_overrides=settings) - + # logging.warn(tre['fragment']) return Markup(tre['fragment']) diff --git a/flucoma/doc/templates/maxref.xml b/flucoma/doc/templates/maxref.xml index 48774a7b..58cd5ac1 100644 --- a/flucoma/doc/templates/maxref.xml +++ b/flucoma/doc/templates/maxref.xml @@ -167,5 +167,11 @@ under the European Union’s Horizon 2020 research and innovation programme {% for s in max_seealso %} {% endfor %} + {%- if client_name.startswith('Buf') or species == 'data' -%} + + {%- endif -%} + {%- if client_name.startswith('BufCompose') -%} + + {%- endif -%} diff --git a/spellcheck.py b/spellcheck.py new file mode 100644 index 00000000..52a02ac0 --- /dev/null +++ b/spellcheck.py @@ -0,0 +1,18 @@ +from spellchecker import SpellChecker +from pathlib import Path + +spell = SpellChecker() + +files = [x for x in Path("doc").rglob("*.rst")] + + +for page in files: + with open(page) as text: + lines = text.readlines(); + for i, line in enumerate(lines): + word_array = line.split(' ') + word_array = [x.replace(':', '') for x in word_array] + word_array = [x for x in word_array if x != ''] + badspell = spell.unknown(word_array) + for word in badspell: + print(page.name, word) From 8be7c7893fcbb753254a157bfbf423233dc6d7c7 Mon Sep 17 00:00:00 2001 From: James Bradbury Date: Thu, 30 Jun 2022 12:27:34 +0100 Subject: [PATCH 2/5] sample -> samples --- doc/BufAmpFeature.rst | 2 +- doc/BufAmpSlice.rst | 6 +++--- doc/BufChroma.rst | 2 +- doc/BufLoudness.rst | 2 +- doc/BufNMF.rst | 2 +- doc/BufNoveltyFeature.rst | 2 +- doc/BufNoveltySlice.rst | 6 +++--- doc/BufOnsetFeature.rst | 2 +- doc/BufOnsetSlice.rst | 4 ++-- doc/BufSines.rst | 2 +- doc/BufSpectralShape.rst | 2 +- 11 files changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/BufAmpFeature.rst b/doc/BufAmpFeature.rst index 0487ad75..b289cdda 100644 --- a/doc/BufAmpFeature.rst +++ b/doc/BufAmpFeature.rst @@ -17,7 +17,7 @@ :control startFrame: - Where in the srcBuf should the slicing process start, in sample. + Where in the srcBuf should the slicing process start, in samples. :control numFrames: diff --git a/doc/BufAmpSlice.rst b/doc/BufAmpSlice.rst index c2590a0e..c0ad977f 100644 --- a/doc/BufAmpSlice.rst +++ b/doc/BufAmpSlice.rst @@ -8,7 +8,7 @@ :discussion: FluidBufAmpSlice is based on two envelope followers on a high-passed version of the signal: one slow that gives the trend, and one fast. Each has features that will interact. The example code below is unfolding the various possibilities in order of complexity. - The process will return a buffer which contains indices (in sample) of estimated starting points of different slices. + The process will return a buffer which contains indices (in samples) of estimated starting points of different slices. :output: Nothing, as the destination buffer is declared in the function call. @@ -19,7 +19,7 @@ :control startFrame: - Where in the srcBuf should the slicing process start, in sample. + Where in the srcBuf should the slicing process start, in samples. :control numFrames: @@ -35,7 +35,7 @@ :control 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. + The index of the buffer where the indices (in samples) of the estimated starting points of slices will be written. The first and last points are always the boundary points of the analysis. :control fastRampUp: diff --git a/doc/BufChroma.rst b/doc/BufChroma.rst index 552525e5..8e26bcec 100644 --- a/doc/BufChroma.rst +++ b/doc/BufChroma.rst @@ -19,7 +19,7 @@ :control startFrame: - Where in the srcBuf should the process start, in sample. + Where in the srcBuf should the process start, in samples. :control numFrames: diff --git a/doc/BufLoudness.rst b/doc/BufLoudness.rst index 05f1f680..d8f92b9b 100644 --- a/doc/BufLoudness.rst +++ b/doc/BufLoudness.rst @@ -22,7 +22,7 @@ :control startFrame: - Where in the srcBuf should the process start, in sample. + Where in the srcBuf should the process start, in samples. :control numFrames: diff --git a/doc/BufNMF.rst b/doc/BufNMF.rst index 22719f65..6c158ac9 100644 --- a/doc/BufNMF.rst +++ b/doc/BufNMF.rst @@ -36,7 +36,7 @@ :control startFrame: - Where in the srcBuf should the NMF process start, in sample. + Where in the srcBuf should the NMF process start, in samples. :control numFrames: diff --git a/doc/BufNoveltyFeature.rst b/doc/BufNoveltyFeature.rst index 2516eaaa..bae96acd 100644 --- a/doc/BufNoveltyFeature.rst +++ b/doc/BufNoveltyFeature.rst @@ -20,7 +20,7 @@ :control startFrame: - Where in the srcBuf should the slicing process start, in sample. + Where in the srcBuf should the slicing process start, in samples. :control numFrames: diff --git a/doc/BufNoveltySlice.rst b/doc/BufNoveltySlice.rst index 4486eaf4..f224b65c 100644 --- a/doc/BufNoveltySlice.rst +++ b/doc/BufNoveltySlice.rst @@ -7,7 +7,7 @@ :discussion: A novelty curve is derived from running a kernel across the diagonal of the similarity matrix, and looking for peaks of changes. It implements the seminal results published in 'Automatic Audio Segmentation Using a Measure of Audio Novelty' by J Foote. - The process will return a buffer which contains indices (in sample) of estimated starting points of different slices. + The process will return a buffer which contains indices (in samples) of estimated starting points of different slices. :process: This is the method that calls for the slicing to be calculated on a given source buffer. :output: Nothing, as the various destination buffers are declared in the function call. @@ -19,7 +19,7 @@ :control startFrame: - Where in the srcBuf should the slicing process start, in sample. + Where in the srcBuf should the slicing process start, in samples. :control numFrames: @@ -35,7 +35,7 @@ :control 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. + The index of the buffer where the indices (in samples) of the estimated starting points of slices will be written. The first and last points are always the boundary points of the analysis. :control algorithm: diff --git a/doc/BufOnsetFeature.rst b/doc/BufOnsetFeature.rst index b2fcc173..30743117 100644 --- a/doc/BufOnsetFeature.rst +++ b/doc/BufOnsetFeature.rst @@ -18,7 +18,7 @@ :control startFrame: - Where in the srcBuf should the slicing process start, in sample. + Where in the srcBuf should the slicing process start, in samples. :control numFrames: diff --git a/doc/BufOnsetSlice.rst b/doc/BufOnsetSlice.rst index fdb51b8a..81201975 100644 --- a/doc/BufOnsetSlice.rst +++ b/doc/BufOnsetSlice.rst @@ -18,7 +18,7 @@ :control startFrame: - Where in the srcBuf should the slicing process start, in sample. + Where in the srcBuf should the slicing process start, in samples. :control numFrames: @@ -34,7 +34,7 @@ :control 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. + The index of the buffer where the indices (in samples) of the estimated starting points of slices will be written. The first and last points are always the boundary points of the analysis. :control metric: diff --git a/doc/BufSines.rst b/doc/BufSines.rst index efd0914e..dde4b9b0 100644 --- a/doc/BufSines.rst +++ b/doc/BufSines.rst @@ -24,7 +24,7 @@ :control startFrame: - Where in the srcBuf should the process start, in sample. + Where in the srcBuf should the process start, in samples. :control numFrames: diff --git a/doc/BufSpectralShape.rst b/doc/BufSpectralShape.rst index b8fbf5c5..054a304a 100644 --- a/doc/BufSpectralShape.rst +++ b/doc/BufSpectralShape.rst @@ -32,7 +32,7 @@ :control startFrame: - Where in the srcBuf should the process start, in sample. + Where in the srcBuf should the process start, in samples. :control numFrames: From f19fa2fef04107b7a3fd8dbd60ca0802e9347d68 Mon Sep 17 00:00:00 2001 From: James Bradbury Date: Thu, 30 Jun 2022 12:27:51 +0100 Subject: [PATCH 3/5] The index of the buffer -> The buffer --- doc/BufAmpFeature.rst | 4 ++-- doc/BufAmpSlice.rst | 4 ++-- doc/BufChroma.rst | 2 +- doc/BufHPSS.rst | 8 ++++---- doc/BufLoudness.rst | 2 +- doc/BufMFCC.rst | 2 +- doc/BufMelBands.rst | 2 +- doc/BufNMF.rst | 8 ++++---- doc/BufNoveltyFeature.rst | 4 ++-- doc/BufNoveltySlice.rst | 4 ++-- doc/BufOnsetFeature.rst | 4 ++-- doc/BufOnsetSlice.rst | 4 ++-- doc/BufPitch.rst | 2 +- doc/BufSines.rst | 6 +++--- doc/BufSpectralShape.rst | 2 +- 15 files changed, 29 insertions(+), 29 deletions(-) diff --git a/doc/BufAmpFeature.rst b/doc/BufAmpFeature.rst index b289cdda..f82d45f3 100644 --- a/doc/BufAmpFeature.rst +++ b/doc/BufAmpFeature.rst @@ -13,7 +13,7 @@ :control 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. + The buffer to use as the source material to be sliced through novelty identification. The different channels of multichannel buffers will be summed. :control startFrame: @@ -33,7 +33,7 @@ :control features: - The index of the buffer where the amplitude differential feature will be copied to. + The buffer where the amplitude differential feature will be copied to. :control fastRampUp: diff --git a/doc/BufAmpSlice.rst b/doc/BufAmpSlice.rst index c0ad977f..96394ca3 100644 --- a/doc/BufAmpSlice.rst +++ b/doc/BufAmpSlice.rst @@ -15,7 +15,7 @@ :control 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. + The buffer to use as the source material to be sliced through novelty identification. The different channels of multichannel buffers will be summed. :control startFrame: @@ -35,7 +35,7 @@ :control indices: - The index of the buffer where the indices (in samples) of the estimated starting points of slices will be written. The first and last points are always the boundary points of the analysis. + The buffer where the indices (in samples) of the estimated starting points of slices will be written. The first and last points are always the boundary points of the analysis. :control fastRampUp: diff --git a/doc/BufChroma.rst b/doc/BufChroma.rst index 8e26bcec..3d220b44 100644 --- a/doc/BufChroma.rst +++ b/doc/BufChroma.rst @@ -15,7 +15,7 @@ :control source: - The index of the buffer to use as the source material to be analysed. The different channels of multichannel buffers will be processed sequentially. + The buffer to use as the source material to be analysed. The different channels of multichannel buffers will be processed sequentially. :control startFrame: diff --git a/doc/BufHPSS.rst b/doc/BufHPSS.rst index a059a8db..f93252ae 100644 --- a/doc/BufHPSS.rst +++ b/doc/BufHPSS.rst @@ -29,7 +29,7 @@ :control source: - The index of the buffer to use as the source material. The channels of multichannel buffers will be processed sequentially. + The buffer to use as the source material. The channels of multichannel buffers will be processed sequentially. :control startFrame: @@ -49,15 +49,15 @@ :control harmonic: - The index of the buffer where the extracted harmonic component will be reconstructed. + The buffer where the extracted harmonic component will be reconstructed. :control percussive: - The index of the buffer where the extracted percussive component will be reconstructed. + The buffer where the extracted percussive component will be reconstructed. :control residual: - The index of the buffer where the residual component will be reconstructed in mode 2. + The buffer where the residual component will be reconstructed in mode 2. :control harmFilterSize: diff --git a/doc/BufLoudness.rst b/doc/BufLoudness.rst index d8f92b9b..6575cc0e 100644 --- a/doc/BufLoudness.rst +++ b/doc/BufLoudness.rst @@ -18,7 +18,7 @@ :control source: - The index of the buffer to use as the source material to be described. The different channels of multichannel buffers will be processed sequentially. + The buffer to use as the source material to be described. The different channels of multichannel buffers will be processed sequentially. :control startFrame: diff --git a/doc/BufMFCC.rst b/doc/BufMFCC.rst index e537fbc7..f4eacb6e 100644 --- a/doc/BufMFCC.rst +++ b/doc/BufMFCC.rst @@ -18,7 +18,7 @@ :control source: - The index of the buffer to use as the source material to be analysed. The different channels of multichannel buffers will be processed sequentially. + The buffer to use as the source material to be analysed. The different channels of multichannel buffers will be processed sequentially. :control startFrame: diff --git a/doc/BufMelBands.rst b/doc/BufMelBands.rst index 4b97b045..720f7fc4 100644 --- a/doc/BufMelBands.rst +++ b/doc/BufMelBands.rst @@ -20,7 +20,7 @@ :control source: - The index of the buffer to use as the source material to be analysed. The different channels of multichannel buffers will be processed sequentially. + The buffer to use as the source material to be analysed. The different channels of multichannel buffers will be processed sequentially. :control startFrame: diff --git a/doc/BufNMF.rst b/doc/BufNMF.rst index 6c158ac9..975c5793 100644 --- a/doc/BufNMF.rst +++ b/doc/BufNMF.rst @@ -32,7 +32,7 @@ :control source: - The index of the buffer to use as the source material to be decomposed through the NMF process. The different channels of multichannel buffers will be processed sequentially. + The buffer to use as the source material to be decomposed through the NMF process. The different channels of multichannel buffers will be processed sequentially. :control startFrame: @@ -52,7 +52,7 @@ :control resynth: - The index of the buffer where the different reconstructed components will be reconstructed. The buffer will be resized to ``components * numChannelsProcessed`` channels and ``sourceDuration`` length. If ``nil`` is provided, the reconstruction will not happen. + The buffer where the different reconstructed components will be reconstructed. The buffer will be resized to ``components * numChannelsProcessed`` channels and ``sourceDuration`` length. If ``nil`` is provided, the reconstruction will not happen. :control resynthMode: @@ -60,7 +60,7 @@ :control bases: - The index of the buffer where the different bases will be written to and/or read from: the behaviour is set in the following argument. If ``nil`` is provided, no bases will be returned. + The buffer where the different bases will be written to and/or read from: the behaviour is set in the following argument. If ``nil`` is provided, no bases will be returned. :control basesMode: @@ -79,7 +79,7 @@ :control activations: - The index of the buffer where the different activations will be written to and/or read from: the behaviour is set in the following argument. If ``nil`` is provided, no activation will be returned. + The buffer where the different activations will be written to and/or read from: the behaviour is set in the following argument. If ``nil`` is provided, no activation will be returned. :control actMode: diff --git a/doc/BufNoveltyFeature.rst b/doc/BufNoveltyFeature.rst index bae96acd..492602a9 100644 --- a/doc/BufNoveltyFeature.rst +++ b/doc/BufNoveltyFeature.rst @@ -16,7 +16,7 @@ :control 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. + The buffer to use as the source material to be sliced through novelty identification. The different channels of multichannel buffers will be summed. :control startFrame: @@ -36,7 +36,7 @@ :control features: - The index of the buffer where the novelty feature will be written. + The buffer where the novelty feature will be written. :control algorithm: diff --git a/doc/BufNoveltySlice.rst b/doc/BufNoveltySlice.rst index f224b65c..a1283793 100644 --- a/doc/BufNoveltySlice.rst +++ b/doc/BufNoveltySlice.rst @@ -15,7 +15,7 @@ :control 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. + The buffer to use as the source material to be sliced through novelty identification. The different channels of multichannel buffers will be summed. :control startFrame: @@ -35,7 +35,7 @@ :control indices: - The index of the buffer where the indices (in samples) of the estimated starting points of slices will be written. The first and last points are always the boundary points of the analysis. + The buffer where the indices (in samples) of the estimated starting points of slices will be written. The first and last points are always the boundary points of the analysis. :control algorithm: diff --git a/doc/BufOnsetFeature.rst b/doc/BufOnsetFeature.rst index 30743117..c8816816 100644 --- a/doc/BufOnsetFeature.rst +++ b/doc/BufOnsetFeature.rst @@ -14,7 +14,7 @@ :control 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. + The buffer to use as the source material to be sliced through novelty identification. The different channels of multichannel buffers will be summed. :control startFrame: @@ -34,7 +34,7 @@ :control features: - The index of the buffer where the onset features will be written to. + The buffer where the onset features will be written to. :control metric: diff --git a/doc/BufOnsetSlice.rst b/doc/BufOnsetSlice.rst index 81201975..3edb0d44 100644 --- a/doc/BufOnsetSlice.rst +++ b/doc/BufOnsetSlice.rst @@ -14,7 +14,7 @@ :control 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. + The buffer to use as the source material to be sliced through novelty identification. The different channels of multichannel buffers will be summed. :control startFrame: @@ -34,7 +34,7 @@ :control indices: - The index of the buffer where the indices (in samples) of the estimated starting points of slices will be written. The first and last points are always the boundary points of the analysis. + The buffer where the indices (in samples) of the estimated starting points of slices will be written. The first and last points are always the boundary points of the analysis. :control metric: diff --git a/doc/BufPitch.rst b/doc/BufPitch.rst index 376984e5..dd443856 100644 --- a/doc/BufPitch.rst +++ b/doc/BufPitch.rst @@ -23,7 +23,7 @@ :control source: - The index of the buffer to use as the source material to be pitch-tracked. The different channels of multichannel buffers will be processed sequentially. + The buffer to use as the source material to be pitch-tracked. The different channels of multichannel buffers will be processed sequentially. :control select: diff --git a/doc/BufSines.rst b/doc/BufSines.rst index dde4b9b0..752ad72c 100644 --- a/doc/BufSines.rst +++ b/doc/BufSines.rst @@ -20,7 +20,7 @@ :control source: - The index of the buffer to use as the source material to be decomposed through the sinusoidal modelling process. The different channels of multichannel buffers will be processed sequentially. + The buffer to use as the source material to be decomposed through the sinusoidal modelling process. The different channels of multichannel buffers will be processed sequentially. :control startFrame: @@ -40,11 +40,11 @@ :control sines: - The index of the buffer where the extracted sinusoidal component will be reconstructed. + The buffer where the extracted sinusoidal component will be reconstructed. :control residual: - The index of the buffer where the residual of the sinusoidal component will be reconstructed. + The buffer where the residual of the sinusoidal component will be reconstructed. :control bandwidth: diff --git a/doc/BufSpectralShape.rst b/doc/BufSpectralShape.rst index 054a304a..09206ea0 100644 --- a/doc/BufSpectralShape.rst +++ b/doc/BufSpectralShape.rst @@ -28,7 +28,7 @@ :control source: - The index of the buffer to use as the source material to be described through the various descriptors. The different channels of multichannel buffers will be processed sequentially. + The buffer to use as the source material to be described through the various descriptors. The different channels of multichannel buffers will be processed sequentially. :control startFrame: From 2a82405a60fdb8043851669b0087994d79e60a4b Mon Sep 17 00:00:00 2001 From: James Bradbury Date: Thu, 30 Jun 2022 12:30:24 +0100 Subject: [PATCH 4/5] process -> processed --- doc/BufTransientSlice.rst | 2 +- doc/BufTransients.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/BufTransientSlice.rst b/doc/BufTransientSlice.rst index 2834e791..c251092a 100644 --- a/doc/BufTransientSlice.rst +++ b/doc/BufTransientSlice.rst @@ -27,7 +27,7 @@ :control numFrames: - How many frames of ``source`` should be process. The default of -1 indicates to process through the end of the buffer. + How many frames of ``source`` should be processed. The default of -1 indicates to process through the end of the buffer. :control startChan: diff --git a/doc/BufTransients.rst b/doc/BufTransients.rst index 81a7d999..b05948f5 100644 --- a/doc/BufTransients.rst +++ b/doc/BufTransients.rst @@ -29,7 +29,7 @@ :control numFrames: - How many frames of ``source`` should be process. The default of -1 indicates to process through the end of the buffer. + How many frames of ``source`` should be processed. The default of -1 indicates to process through the end of the buffer. :control startChan: From 8956894db77a823e0901d494c9613c6ddb535025 Mon Sep 17 00:00:00 2001 From: James Bradbury Date: Thu, 30 Jun 2022 12:35:48 +0100 Subject: [PATCH 5/5] various other typos --- doc/AmpGate.rst | 2 +- doc/AudioTransport.rst | 2 +- doc/BufAmpGate.rst | 2 +- doc/BufAudioTransport.rst | 2 +- doc/BufChroma.rst | 2 +- doc/BufCompose.rst | 2 +- doc/BufHPSS.rst | 2 +- doc/BufLoudness.rst | 4 ++-- doc/BufMFCC.rst | 2 +- doc/BufMelBands.rst | 2 +- doc/BufNMF.rst | 2 +- doc/BufNMFSeed.rst | 2 +- doc/BufNoveltyFeature.rst | 2 +- doc/BufNoveltySlice.rst | 2 +- doc/BufOnsetFeature.rst | 2 +- doc/BufOnsetSlice.rst | 2 +- doc/BufPitch.rst | 2 +- doc/BufSines.rst | 2 +- doc/BufSpectralShape.rst | 2 +- doc/Chroma.rst | 2 +- doc/HPSS.rst | 2 +- doc/MFCC.rst | 2 +- doc/MelBands.rst | 2 +- doc/NMFFilter.rst | 2 +- doc/NMFMatch.rst | 2 +- doc/NoveltyFeature.rst | 2 +- doc/NoveltySlice.rst | 2 +- doc/OnsetFeature.rst | 2 +- doc/OnsetSlice.rst | 2 +- doc/Pitch.rst | 2 +- doc/Sines.rst | 2 +- doc/SpectralShape.rst | 2 +- 32 files changed, 33 insertions(+), 33 deletions(-) diff --git a/doc/AmpGate.rst b/doc/AmpGate.rst index 4a95c649..b3e34d57 100644 --- a/doc/AmpGate.rst +++ b/doc/AmpGate.rst @@ -7,7 +7,7 @@ :description: Absolute amplitude threshold gate detector on a realtime signal :discussion: - AmpGate outputs a audio-rate, single-channel signal that is either 0, indicating the gate is closed, or 1, indicating the gate is open. The gate detects an onset (opens) when the internal envelope follower (controlled by ``rampUp`` and ``rampDown``) goes above a specified ``onThreshold`` (in dB) for at least ``minLengthAbove`` samples. The gate will stay open until the envelope follower goes below ``offThreshold`` (in dB) for at least ``minLengthBelow`` samples, which triggers an offset. + AmpGate outputs an audio-rate, single-channel signal that is either 0, indicating the gate is closed, or 1, indicating the gate is open. The gate detects an onset (opens) when the internal envelope follower (controlled by ``rampUp`` and ``rampDown``) goes above a specified ``onThreshold`` (in dB) for at least ``minLengthAbove`` samples. The gate will stay open until the envelope follower goes below ``offThreshold`` (in dB) for at least ``minLengthBelow`` samples, which triggers an offset. The latency between the input and the output is **max(minLengthAbove + lookBack, max(minLengthBelow,lookAhead))**. diff --git a/doc/AudioTransport.rst b/doc/AudioTransport.rst index 489193d3..d25c2f08 100644 --- a/doc/AudioTransport.rst +++ b/doc/AudioTransport.rst @@ -26,7 +26,7 @@ :control hopSize: - The window hop size in samples. As HPSS relies on spectral frames, we need to move the window forward. It can be any size but low overlap may create audible artefacts. The -1 default value will default to half of windowSize (overlap of 2). + The window hop size in samples. As HPSS relies on spectral frames, we need to move the window forward. It can be any size, but low overlap may create audible artefacts. The -1 default value will default to half of windowSize (overlap of 2). :control fftSize: diff --git a/doc/BufAmpGate.rst b/doc/BufAmpGate.rst index 7718895f..5d8f9b7f 100644 --- a/doc/BufAmpGate.rst +++ b/doc/BufAmpGate.rst @@ -36,7 +36,7 @@ :control indices: - The buffer to write the gate information into. Buffer will be resized appropriately so each frame contains an onset (opening) position on channel 0 and the corresponding offset (closing) position on channel 1 (both in samples). The buffer will have as many frames as gate events detected. + The buffer to write the gate information into. Buffer will be resized appropriately so that each frame contains an onset (opening) position on channel 0 and the corresponding offset (closing) position on channel 1 (both in samples). The buffer will have as many frames as gate events detected. :control rampUp: diff --git a/doc/BufAudioTransport.rst b/doc/BufAudioTransport.rst index a9e67abe..5407f4a7 100644 --- a/doc/BufAudioTransport.rst +++ b/doc/BufAudioTransport.rst @@ -67,7 +67,7 @@ :control 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). + 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). :control fftSize: diff --git a/doc/BufChroma.rst b/doc/BufChroma.rst index 3d220b44..cce64ac9 100644 --- a/doc/BufChroma.rst +++ b/doc/BufChroma.rst @@ -63,7 +63,7 @@ :control 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. + 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. :control fftSize: diff --git a/doc/BufCompose.rst b/doc/BufCompose.rst index 8071832b..20bbd476 100644 --- a/doc/BufCompose.rst +++ b/doc/BufCompose.rst @@ -8,7 +8,7 @@ A utility for manipulating the contents of buffers. :discussion: - This object is the swiss army knife for manipulating buffers and their contents. By specifying ranges of samples and channels to copy, as well as destination and source gains it can provide a powerful interface for performing actions such as a Left/Right to Mid/Side conversion and mixing down multichannel audio + This object is a low-level tool for manipulating buffers and their contents. By specifying ranges of samples and channels to copy, as well as destination and source gains it can provide a powerful interface for performing actions such as a Left/Right to Mid/Side conversion and mixing down multichannel audio :process: This method triggers the compositing. diff --git a/doc/BufHPSS.rst b/doc/BufHPSS.rst index f93252ae..050e40a9 100644 --- a/doc/BufHPSS.rst +++ b/doc/BufHPSS.rst @@ -96,7 +96,7 @@ :control hopSize: - The hop size in samples. As HPSS relies on spectral frames, we need to move the window forward. It can be any size but low overlap may create audible artefacts. + The hop size in samples. As HPSS relies on spectral frames, we need to move the window forward. It can be any size, but low overlap may create audible artefacts. :control fftSize: diff --git a/doc/BufLoudness.rst b/doc/BufLoudness.rst index 6575cc0e..f4689a75 100644 --- a/doc/BufLoudness.rst +++ b/doc/BufLoudness.rst @@ -54,11 +54,11 @@ :control windowSize: - The size of the window on which the computation is done. By default 1024 to be similar with all other FluCoMa objects, the EBU specifies 400ms, which is 17640 samples at 44100. + The size of the window on which the computation is done. By default, 1024 to be similar with all other FluCoMa objects, the EBU specifies 400ms, which is 17640 samples at 44100. :control hopSize: - How much the buffered window moves forward, in samples. By default 512 to be similar with all other FluCoMa objects, the EBU specifies 100ms, which is 4410 samples at 44100. + How much the buffered window moves forward, in samples. By default, 512 to be similar with all other FluCoMa objects, the EBU specifies 100ms, which is 4410 samples at 44100. :control padding: diff --git a/doc/BufMFCC.rst b/doc/BufMFCC.rst index f4eacb6e..2dd46480 100644 --- a/doc/BufMFCC.rst +++ b/doc/BufMFCC.rst @@ -66,7 +66,7 @@ :control hopSize: - The window hop size. As MFCC 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 MFCC 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). :control fftSize: diff --git a/doc/BufMelBands.rst b/doc/BufMelBands.rst index 720f7fc4..99e4beeb 100644 --- a/doc/BufMelBands.rst +++ b/doc/BufMelBands.rst @@ -68,7 +68,7 @@ :control hopSize: - The window hop size. As this analysis 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 this analysis 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). :control fftSize: diff --git a/doc/BufNMF.rst b/doc/BufNMF.rst index 975c5793..73030081 100644 --- a/doc/BufNMF.rst +++ b/doc/BufNMF.rst @@ -110,7 +110,7 @@ :control hopSize: - The window hop size. As NMF relies on spectral frames, we need to move the window forward. It can be any size but low overlap will create audible artefacts. + The window hop size. As NMF relies on spectral frames, we need to move the window forward. It can be any size, but low overlap will create audible artefacts. :control fftSize: diff --git a/doc/BufNMFSeed.rst b/doc/BufNMFSeed.rst index fdaa5abf..3bf6cc0c 100644 --- a/doc/BufNMFSeed.rst +++ b/doc/BufNMFSeed.rst @@ -58,7 +58,7 @@ :control hopSize: - The window hop size. 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. 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). :control fftSize: diff --git a/doc/BufNoveltyFeature.rst b/doc/BufNoveltyFeature.rst index 492602a9..b8b66665 100644 --- a/doc/BufNoveltyFeature.rst +++ b/doc/BufNoveltyFeature.rst @@ -73,7 +73,7 @@ :control hopSize: - The window hop size. As novelty 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 window hop size. As novelty estimation relies on spectral frames, we need to move the window forward. It can be any size, but low overlap will create audible artefacts. :control fftSize: diff --git a/doc/BufNoveltySlice.rst b/doc/BufNoveltySlice.rst index a1283793..aee2531f 100644 --- a/doc/BufNoveltySlice.rst +++ b/doc/BufNoveltySlice.rst @@ -80,7 +80,7 @@ :control hopSize: - The window hop size. As novelty 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 window hop size. As novelty estimation relies on spectral frames, we need to move the window forward. It can be any size, but low overlap will create audible artefacts. :control fftSize: diff --git a/doc/BufOnsetFeature.rst b/doc/BufOnsetFeature.rst index c8816816..bcb73785 100644 --- a/doc/BufOnsetFeature.rst +++ b/doc/BufOnsetFeature.rst @@ -86,7 +86,7 @@ :control 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). + 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). :control fftSize: diff --git a/doc/BufOnsetSlice.rst b/doc/BufOnsetSlice.rst index 3edb0d44..1891d621 100644 --- a/doc/BufOnsetSlice.rst +++ b/doc/BufOnsetSlice.rst @@ -94,7 +94,7 @@ :control 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). + 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). :control fftSize: diff --git a/doc/BufPitch.rst b/doc/BufPitch.rst index dd443856..679cc7a7 100644 --- a/doc/BufPitch.rst +++ b/doc/BufPitch.rst @@ -82,7 +82,7 @@ :control 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 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. :control fftSize: diff --git a/doc/BufSines.rst b/doc/BufSines.rst index 752ad72c..2077c530 100644 --- a/doc/BufSines.rst +++ b/doc/BufSines.rst @@ -88,7 +88,7 @@ :control 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 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. :control fftSize: diff --git a/doc/BufSpectralShape.rst b/doc/BufSpectralShape.rst index 09206ea0..453e2bd9 100644 --- a/doc/BufSpectralShape.rst +++ b/doc/BufSpectralShape.rst @@ -76,7 +76,7 @@ :control 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 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. :control fftSize: diff --git a/doc/Chroma.rst b/doc/Chroma.rst index fff1de18..2606e173 100644 --- a/doc/Chroma.rst +++ b/doc/Chroma.rst @@ -47,7 +47,7 @@ :control 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). + 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). :control fftSize: diff --git a/doc/HPSS.rst b/doc/HPSS.rst index 7fe5ab80..313a90da 100644 --- a/doc/HPSS.rst +++ b/doc/HPSS.rst @@ -66,7 +66,7 @@ :control 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). + 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). :control fftSize: diff --git a/doc/MFCC.rst b/doc/MFCC.rst index 8d4af55f..b5d994e5 100644 --- a/doc/MFCC.rst +++ b/doc/MFCC.rst @@ -60,7 +60,7 @@ :control hopSize: - The window hop size. As MFCC 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 MFCC 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). :control fftSize: diff --git a/doc/MelBands.rst b/doc/MelBands.rst index 9c40ba2b..9fff6005 100644 --- a/doc/MelBands.rst +++ b/doc/MelBands.rst @@ -49,7 +49,7 @@ :control hopSize: - The window hop size. As spectral description 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 spectral description 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). :control fftSize: diff --git a/doc/NMFFilter.rst b/doc/NMFFilter.rst index d45e7b5e..55469bc3 100644 --- a/doc/NMFFilter.rst +++ b/doc/NMFFilter.rst @@ -39,7 +39,7 @@ :control hopSize: - The window hop size. As NMF 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 NMF 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). :control fftSize: diff --git a/doc/NMFMatch.rst b/doc/NMFMatch.rst index 7c17d10d..3b69ab41 100644 --- a/doc/NMFMatch.rst +++ b/doc/NMFMatch.rst @@ -39,7 +39,7 @@ :control hopSize: - The window hop size. As NMF 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 NMF 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). :control fftSize: diff --git a/doc/NoveltyFeature.rst b/doc/NoveltyFeature.rst index b30c6431..963b167f 100644 --- a/doc/NoveltyFeature.rst +++ b/doc/NoveltyFeature.rst @@ -47,7 +47,7 @@ :control hopSize: - The window hop size. As novelty 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 window hop size. As novelty estimation relies on spectral frames, we need to move the window forward. It can be any size, but low overlap will create audible artefacts. :control fftSize: diff --git a/doc/NoveltySlice.rst b/doc/NoveltySlice.rst index 6880fbdf..c3213aa6 100644 --- a/doc/NoveltySlice.rst +++ b/doc/NoveltySlice.rst @@ -59,7 +59,7 @@ :control 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). + 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). :control fftSize: diff --git a/doc/OnsetFeature.rst b/doc/OnsetFeature.rst index bcc03e5a..072d15c5 100644 --- a/doc/OnsetFeature.rst +++ b/doc/OnsetFeature.rst @@ -62,7 +62,7 @@ :control 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). + 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). :control fftSize: diff --git a/doc/OnsetSlice.rst b/doc/OnsetSlice.rst index 4042256e..f22fcc04 100644 --- a/doc/OnsetSlice.rst +++ b/doc/OnsetSlice.rst @@ -75,7 +75,7 @@ :control 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). + 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). :control fftSize: diff --git a/doc/Pitch.rst b/doc/Pitch.rst index 877caebd..45b0166b 100644 --- a/doc/Pitch.rst +++ b/doc/Pitch.rst @@ -62,7 +62,7 @@ :control 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). + 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). :control fftSize: diff --git a/doc/Sines.rst b/doc/Sines.rst index c3a1c457..3ada0b89 100644 --- a/doc/Sines.rst +++ b/doc/Sines.rst @@ -63,7 +63,7 @@ :control 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). + 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). :control fftSize: diff --git a/doc/SpectralShape.rst b/doc/SpectralShape.rst index 981f3b9d..790aa43f 100644 --- a/doc/SpectralShape.rst +++ b/doc/SpectralShape.rst @@ -57,7 +57,7 @@ :control 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). + 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). :control fftSize: