HelpSource/Classes/Onsets.schelp

   1 class:: Onsets
   2 summary:: Onset detector
   3 categories:: UGens>Analysis
   4 related:: Classes/BeatTrack, Classes/Loudness, Classes/MFCC, Classes/Pitch, Classes/KeyTrack
   5
   6 description::
   7 An onset detector for musical audio signals - detects the beginning of notes/drumbeats/etc. Outputs a control-rate trigger signal which is 1 when an onset is detected, and 0 otherwise.
   8
   9 For more details of all the processes involved, the different onset detection functions, and their evaluation, see:
  10
  11 D. Stowell and M. D. Plumbley. Adaptive whitening for improved real-time audio onset detection. emphasis::Proceedings of the International Computer Music Conference (ICMC'07)::, Copenhagen, Denmark, August 2007. [http://www.elec.qmul.ac.uk/digitalmusic/papers/2007/StowellPlumbley07-icmc.pdf]
  12
  13 classmethods::
  14 private:: categories
  15
  16 method:: kr
  17
  18 argument:: chain
  19 an FFT chain.
  20 argument:: threshold
  21 the detection threshold, typically between 0 and 1, although in rare cases you may find values outside this range useful.
  22 argument:: odftype
  23 chooses which emphasis::onset detection function:: is used. In many cases the default will be fine. The following choices are available:
  24
  25 definitionlist::
  26 ## code::\power:: || generally OK, good for percussive input, and also very efficient
  27 ## code::\magsum:: || generally OK, good for percussive input, and also very efficient
  28 ## code::\complex:: || performs generally very well, but more CPU-intensive
  29 ## code::\rcomplex:: || performs generally very well, and slightly more efficient than code::\complex::
  30 ## code::\phase:: || generally good, especially for tonal input, medium efficiency
  31 ## code::\wphase:: || generally very good, especially for tonal input, medium efficiency
  32 ## code::\mkl:: || generally very good, medium efficiency, pretty different from the other methods
  33 ::
  34
  35 discussion::
  36 For the FFT chain, you should typically use a frame size of 512 or 1024 (at 44.1 kHz sampling rate) and 50% hop size (which is the default setting in SC). For different sampling rates choose an FFT size to cover a similar time-span (around 10 to 20 ms).
  37
  38 The onset detection should work well for a general range of monophonic and polyphonic audio signals. The onset detection is purely based on signal analysis and does not make use of any "top-down" inferences such as tempo.
  39
  40 Which onset detection function should you choose? The differences aren't large, so I'd recommend you stick with the default code::\rcomplex:: unless you find specific problems with it. Then maybe try code::\wphase::. The code::\mkl:: type is a bit different from the others so maybe try that too. They all have slightly different characteristics, and in tests perform at a similar quality level.
  41
  42 subsection:: Advanced features
  43
  44 Further options are available, which you are welcome to explore if you want. They are numbers that modulate the behaviour of the onset detector:
  45
  46 list::
  47 ## strong::relaxtime:: and strong::floor:: are parameters to the whitening process used, a kind of normalisation of the FFT signal. (Note: in \mkl mode these are not used.)
  48         list::
  49         ## strong::relaxtime:: specifies the time (in seconds) for the normalisation to "forget" about a recent onset. If you find too much re-triggering (e.g. as a note dies away unevenly) then you might wish to increase this value.
  50         ## strong::floor:: is a lower limit, connected to the idea of how quiet the sound is expected to get without becoming indistinguishable from noise. For some cleanly-recorded classical music with wide dynamic variations, I found it helpful to go down as far as 0.000001.
  51         ::
  52 ## strong::mingap:: specifies a minimum gap (in FFT frames) between onset detections, a brute-force way to prevent too many doubled detections.
  53 ## strong::medianspan:: specifies the size (in FFT frames) of the median window used for smoothing the detection function before triggering.
  54 ::
  55
  56 examples::
  57 code::
  58 (
  59 s.boot.doWhenBooted {
  60         // Prepare the buffers
  61         b = Buffer.alloc(s, 512);
  62         // Feel free to load a more interesting clip!
  63         // a11wlk01 is not an ideal example of musical onsets.
  64         d = Buffer.read(s, Platform.resourceDir +/+ "sounds/a11wlk01.wav");
  65 };
  66 )
  67
  68 ////////////////////////////////////////////////////////////////////////////////////////////////
  69 // Move the mouse to vary the threshold
  70 (
  71 x = {
  72         var sig, chain, onsets, pips;
  73
  74         // A simple generative signal
  75         sig = LPF.ar(Pulse.ar(TIRand.kr(63, 75, Impulse.kr(2)).midicps), LFNoise2.kr(0.5).exprange(100, 10000)) * Saw.ar(2).range(0, 1);
  76         // or, uncomment this line if you want to play the buffer in
  77         //sig = PlayBuf.ar(1, d, BufRateScale.kr(d), loop: 1);
  78
  79         chain = FFT(b, sig);
  80
  81         onsets = Onsets.kr(chain, MouseX.kr(0,1), \rcomplex);
  82
  83         // You'll hear percussive "ticks" whenever an onset is detected
  84         pips = WhiteNoise.ar(EnvGen.kr(Env.perc(0.001, 0.1, 0.2), onsets));
  85         Out.ar(0, Pan2.ar(sig, -0.75, 0.2) + Pan2.ar(pips, 0.75, 1));
  86 }.play;
  87 )
  88 x.free; // Free the synth
  89
  90 ////////////////////////////////////////////////////////////////////////////////////////////////
  91 // Or we could expand this multichannel, run a series of different thresholds at the same time,
  92 // to sonify the effect of the threshold value.
  93 // A little hard to listen to at first: try and identify a pitch at which the best sort of
  94 // detection is happening.
  95 // You'll hear "bobbling" at low pitches where the threshold is definitely too low.
  96
  97 (
  98 var threshes = (0.1, 0.2 .. 1);
  99 x = {
 100         var sig, chain, onsets, pips;
 101
 102         // A simple generative signal
 103         sig = LPF.ar(Pulse.ar(TIRand.kr(63, 75, Impulse.kr(2)).midicps), LFNoise2.kr(0.5).exprange(100, 10000)) * Saw.ar(2).range(0, 1);
 104         // or, uncomment this line if you want to play the buffer in
 105         //sig = PlayBuf.ar(1, d, BufRateScale.kr(d), loop: 1);
 106
 107         chain = FFT(b, sig);
 108
 109         onsets = Onsets.kr(chain, threshes, \rcomplex);
 110
 111         // Generate pips at a variety of pitches
 112         pips = SinOsc.ar((threshes).linexp(0, 1, 440, 3520), 0, EnvGen.kr(Env.perc(0.001, 0.1, 0.5), onsets)).mean;
 113         Out.ar(0, Pan2.ar(sig, -0.75, 0.2) + Pan2.ar(pips, 0.75, 1));
 114 }.play;
 115 )
 116
 117 x.free; // Free the synth
 118 [b, d].do(_.free); // Free the buffers
 119 ::
 120