Help/UGens/Analysis/Pitch.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta http-equiv="Content-Style-Type" content="text/css">
   6 <title></title>
   7 <meta name="Generator" content="Cocoa HTML Writer">
   8 <meta name="CocoaVersion" content="824.48">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 18.0px Helvetica}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #606060}
  16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #ad140d}
  17 span.s1 {color: #4e6a26}
  18 span.s2 {color: #001bb9}
  19 span.s3 {color: #000000}
  20 span.Apple-tab-span {white-space:pre}
  21 </style>
  22 </head>
  23 <body>
  24 <p class="p1"><b>Pitch<span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>autocorrelation pitch follower</b></p>
  25 <p class="p2"><br></p>
  26 <p class="p3"><b>#freq, hasFreq = Pitch.kr(in, initFreq, minFreq, maxFreq, execFreq, maxBinsPerOctave, median, ampThreshold, peakThreshold, downSample, clar)</b></p>
  27 <p class="p2"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span></p>
  28 <p class="p3">This is a better pitch follower than <b>ZeroCrossing</b>, but more costly of CPU. For most purposes the default settings can be used and only <b>in</b> needs to be supplied. Pitch returns two values (via an Array of OutputProxys, see the OutputProxy help file), a <b>freq</b> which is the pitch estimate and <b>hasFreq</b>, which tells whether a pitch was found. Some vowels are still problematic, for instance a wide open mouth sound somewhere between a low pitched short <span class="s1">'a'</span><span class="Apple-converted-space">  </span>sound as in <span class="s1">'sat'</span>, and long <span class="s1">'i'</span> sound as in <span class="s1">'fire'</span>, contains enough overtone energy to confuse the algorithm.<span class="Apple-converted-space"> </span></p>
  29 <p class="p2"><br></p>
  30 <p class="p3"><b>Examples: (use headphones!)</b></p>
  31 <p class="p2"><br></p>
  32 <p class="p4"><br></p>
  33 <p class="p5">s = <span class="s2">Server</span>.local;</p>
  34 <p class="p4"><br></p>
  35 <p class="p5">(</p>
  36 <p class="p6"><span class="s2">SynthDef</span><span class="s3">(</span>"pitchFollow1"<span class="s3">,{</span></p>
  37 <p class="p5"><span class="Apple-tab-span">     </span><span class="s2">var</span> in, amp, freq, hasFreq, out;</p>
  38 <p class="p5"><span class="Apple-tab-span">     </span>in = <span class="s2">Mix</span>.new(<span class="s2">SoundIn</span>.ar([0,1]));</p>
  39 <p class="p5"><span class="Apple-tab-span">     </span>amp = <span class="s2">Amplitude</span>.kr(in, 0.05, 0.05);</p>
  40 <p class="p5"><span class="Apple-tab-span">     </span># freq, hasFreq = <span class="s2">Pitch</span>.kr(in, ampThreshold: 0.02, median: 7);</p>
  41 <p class="p7"><span class="s3"><span class="Apple-tab-span">    </span></span>//freq = Lag.kr(freq.cpsmidi.round(1).midicps, 0.05);</p>
  42 <p class="p5"><span class="Apple-tab-span">     </span>out = <span class="s2">Mix</span>.new(<span class="s2">VarSaw</span>.ar(freq * [0.5,1,2], 0, <span class="s2">LFNoise1</span>.kr(0.3,0.1,0.1), amp));</p>
  43 <p class="p5"><span class="Apple-tab-span">     </span>6.do({</p>
  44 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>out = <span class="s2">AllpassN</span>.ar(out, 0.040, [0.040.rand,0.040.rand], 2)</p>
  45 <p class="p5"><span class="Apple-tab-span">     </span>});</p>
  46 <p class="p5"><span class="Apple-tab-span">     </span><span class="s2">Out</span>.ar(0,out)</p>
  47 <p class="p5">}).play(s);</p>
  48 <p class="p5">)</p>
  49 <p class="p4"><br></p>
  50 <p class="p5">(</p>
  51 <p class="p6"><span class="s2">SynthDef</span><span class="s3">(</span>"pitchFollow2"<span class="s3">,{</span></p>
  52 <p class="p5"><span class="Apple-tab-span">     </span><span class="s2">var</span> in, amp, freq, hasFreq, out;</p>
  53 <p class="p5"><span class="Apple-tab-span">     </span>in = <span class="s2">Mix</span>.new(<span class="s2">SoundIn</span>.ar([0,1]));</p>
  54 <p class="p5"><span class="Apple-tab-span">     </span>amp = <span class="s2">Amplitude</span>.kr(in, 0.05, 0.05);</p>
  55 <p class="p5"><span class="Apple-tab-span">     </span># freq, hasFreq = <span class="s2">Pitch</span>.kr(in, ampThreshold: 0.02, median: 7);</p>
  56 <p class="p5"><span class="Apple-tab-span">     </span>out = <span class="s2">CombC</span>.ar(<span class="s2">LPF</span>.ar(in, 1000), 0.1, (2 * freq).reciprocal, -6).distort * 0.05;</p>
  57 <p class="p5"><span class="Apple-tab-span">     </span>6.do({</p>
  58 <p class="p5"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>out = <span class="s2">AllpassN</span>.ar(out, 0.040, [0.040.rand,0.040.rand], 2)</p>
  59 <p class="p5"><span class="Apple-tab-span">     </span>});</p>
  60 <p class="p5"><span class="Apple-tab-span">     </span><span class="s2">Out</span>.ar(0,out);</p>
  61 <p class="p5">}).play(s);</p>
  62 <p class="p5">)</p>
  63 <p class="p2"><br></p>
  64 <p class="p2"><br></p>
  65 <p class="p3"><b>How it works:</b></p>
  66 <p class="p3">The pitch follower executes periodically at the rate specified by <b>execFreq </b>in cps. <b>execFreq</b> is clipped to be between <b>minFreq</b> and <b>maxFreq</b> . First it detects whether the input peak to peak amplitude is above the <b>ampThreshold</b>. If it is not then no pitch estimation is performed, <b>hasFreq</b> is set to zero and <b>freq</b> is held at its previous value. It performs an autocorrelation on the input and looks for the first peak after the peak around the lag of zero that is above <b>peakThreshold</b> times the amplitude of the peak at lag zero.<span class="Apple-converted-space"> </span></p>
  67 <p class="p2"><br></p>
  68 <p class="p3">If the <b>clar</b> argument is greater than zero (it is zero by default) then <b>hasFreq</b> is given additional detail. Rather than simply being 1 when a pitch is detected, it is a "clarity" measure in the range between zero and one. (Technically, it's the height of the autocorrelation peak normalised by the height of the zero-lag peak.) It therefore gives a kind of measure of "purity" of the pitched signal.</p>
  69 <p class="p2"><br></p>
  70 <p class="p3">Using a <b>peakThreshold</b> of one half does a pretty good job of eliminating overtones, and finding the first peak above that threshold rather than the absolute maximum peak does a good job of eliminating estimates that are actually multiple periods of the wave.<span class="Apple-converted-space"> </span></p>
  71 <p class="p2"><br></p>
  72 <p class="p3">The autocorrelation is done coarsely at first using a maximum of <b>maxBinsPerOctave</b> lags until the peak is located. Then a fine resolution search is performed until the peak is found. (Note that maxBinsPerOctave does NOT affect the final pitch resolution; a fine resolution search is always performed. Setting maxBinsPerOctave larger will cause the coarse search to take longer, and setting it smaller will cause the fine search to take longer.)</p>
  73 <p class="p2"><br></p>
  74 <p class="p3">The three values around the peak are used to find a fractional lag value for the pitch. If the pitch frequency is higher than <b>maxFreq</b>, or if no peak is found above <b>minFreq</b>, then <b>hasFreq</b> is set to zero and <b>freq</b> is held at its previous value.</p>
  75 <p class="p2"><br></p>
  76 <p class="p3">It is possible to put a median filter of length <b>median</b> on the output estimation so that outliers and jitter can be eliminated. This will however add latency to the pitch estimation for new pitches, because the median filter will have to become half filled with new values before the new one becomes the median value. If median is set to one then that is equivalent to no filter, which is the default.</p>
  77 <p class="p2"><br></p>
  78 <p class="p3">When an in range peak is found, it is inserted into the median filter, a new pitch is read out of the median filter and output as <b>freq</b>, and <b>hasFreq</b> is set to one.</p>
  79 <p class="p2"><br></p>
  80 <p class="p3">It is possible to down sample the input signal by an integer factor <b>downSample </b>in order to reduce CPU overhead. This will also reduce the pitch resolution.</p>
  81 <p class="p2"><br></p>
  82 <p class="p3">Until Pitch finds a pitch for the first time, it will output <b>initFreq</b>.</p>
  83 <p class="p2"><br></p>
  84 <p class="p3">None of these settings are time variable.</p>
  85 <p class="p2"><br></p>
  86 <p class="p3"><b>Default Argument values:</b></p>
  87 <p class="p3"><span class="Apple-tab-span">     </span>initFreq = 440.0</p>
  88 <p class="p3"><span class="Apple-tab-span">     </span>minFreq = 60.0</p>
  89 <p class="p3"><span class="Apple-tab-span">     </span>maxFreq = 4000.0</p>
  90 <p class="p3"><span class="Apple-tab-span">     </span>execFreq = 100.0</p>
  91 <p class="p3"><span class="Apple-tab-span">     </span>maxBinsPerOctave = 16</p>
  92 <p class="p3"><span class="Apple-tab-span">     </span>median = 1</p>
  93 <p class="p3"><span class="Apple-tab-span">     </span>ampThreshold = 0.01</p>
  94 <p class="p3"><span class="Apple-tab-span">     </span>peakThreshold = 0.5</p>
  95 <p class="p3"><span class="Apple-tab-span">     </span>downSample = 1</p>
  96 <p class="p3"><span class="Apple-tab-span">     </span>clar = 0</p>
  97 <p class="p2"><br></p>
  98 </body>
  99 </html>