Merge pull request #652 from tidalcycles/understand-pitch

Understand pitch

website/src/components/LeftSidebar/LeftSidebar.astro

@@ -47,10 +47,11 @@ const sidebar = SIDEBAR[langCode];
 </nav>
 
 <script is:inline>
-  window.addEventListener('DOMContentLoaded', () => {
-    var target = document.querySelector('[aria-current="page"]');
-    if (target && target.offsetTop > window.innerHeight - 100) {
-      document.querySelector('.nav-groups').scrollTop = target.offsetTop;
-    }
-  });
+window.addEventListener('DOMContentLoaded', () => {
+  var target = document.querySelector('[aria-current="page"]');
+  const nav = document.querySelector('.nav-groups');
+  if (nav && target && target.offsetTop > window.innerHeight - 100) {
+    nav.scrollTop = target.offsetTop;
+  }
+});
 </script>

website/src/components/PitchSlider.jsx

@@ -0,0 +1,268 @@
+import useEvent from '@strudel.cycles/react/src/hooks/useEvent.mjs';
+import useFrame from '@strudel.cycles/react/src/hooks/useFrame.mjs';
+import { getAudioContext } from '@strudel.cycles/webaudio';
+import { midi2note } from '@strudel.cycles/core';
+import { useState, useRef, useEffect } from 'react';
+import Claviature from '@components/Claviature';
+
+let Button = (props) => <button {...props} className="bg-lineHighlight p-2 rounded-md color-foreground" />;
+
+function plotValues(ctx, values, min, max, color) {
+  let { width, height } = ctx.canvas;
+  ctx.strokeStyle = color;
+  const thickness = 8;
+  ctx.lineWidth = thickness;
+  ctx.beginPath();
+
+  let x = (f) => ((f - min) / (max - min)) * width;
+  let y = (i) => (1 - i / values.length) * height;
+  values.forEach((f, i, a) => {
+    ctx.lineTo(x(f), y(i));
+  });
+  ctx.stroke();
+}
+
+function getColor(cssVariable) {
+  if (typeof document === 'undefined') {
+    return 'white';
+  }
+  const dummyElement = document.createElement('div');
+  dummyElement.style.color = cssVariable;
+  // Append the dummy element to the document body
+  document.body.appendChild(dummyElement);
+  // Get the computed style of the dummy element
+  const styles = getComputedStyle(dummyElement);
+  // Get the value of the CSS variable
+  const color = styles.getPropertyValue(cssVariable);
+  document.body.removeChild(dummyElement);
+  return color;
+}
+
+let pitchColor = '#eab308';
+let frequencyColor = '#3b82f6';
+
+export function PitchSlider({
+  buttons = [],
+  animatable = false,
+  plot = false,
+  showPitchSlider = false,
+  showFrequencySlider = false,
+  pitchStep = '0.001',
+  min = 55,
+  max = 7040,
+  initial = 220,
+  baseFrequency = min,
+  zeroOffset = 0,
+  claviature,
+}) {
+  const oscRef = useRef();
+  const activeRef = useRef();
+  const freqRef = useRef(initial);
+  const historyRef = useRef([freqRef.current]);
+  const frameRef = useRef();
+  const canvasRef = useRef();
+  const [hz, setHz] = useState(freqRef.current);
+
+  useEffect(() => {
+    freqRef.current = hz;
+  }, [hz]);
+
+  useEvent('mouseup', () => {
+    oscRef.current?.stop();
+    activeRef.current = false;
+  });
+
+  let freqSlider2freq = (progress) => min + progress * (max - min);
+  let pitchSlider2freq = (progress) => min * 2 ** (progress * Math.log2(max / min));
+  let freq2freqSlider = (freq) => (freq - min) / (max - min);
+  let freq2pitchSlider = (freq) => {
+    const [minOct, maxOct] = [Math.log2(min), Math.log2(max)];
+    return (Math.log2(freq) - minOct) / (maxOct - minOct);
+  };
+
+  const freqSlider = freq2freqSlider(hz);
+  const pitchSlider = freq2pitchSlider(hz);
+
+  let startOsc = (hz) => {
+    if (oscRef.current) {
+      oscRef.current.stop();
+    }
+    oscRef.current = getAudioContext().createOscillator();
+    oscRef.current.frequency.value = hz;
+    oscRef.current.connect(getAudioContext().destination);
+    oscRef.current.start();
+    activeRef.current = true;
+    setHz(hz);
+  };
+
+  let startSweep = (exp = false) => {
+    let f = min;
+    startOsc(f);
+    const frame = () => {
+      if (f < max) {
+        if (!exp) {
+          f += 10;
+        } else {
+          f *= 1.01;
+        }
+        oscRef.current.frequency.value = f;
+        frameRef.current = requestAnimationFrame(frame);
+      } else {
+        oscRef.current.stop();
+        cancelAnimationFrame(frameRef.current);
+      }
+      setHz(f);
+    };
+    requestAnimationFrame(frame);
+  };
+
+  useFrame(() => {
+    historyRef.current.push(freqRef.current);
+    historyRef.current = historyRef.current.slice(-1000);
+    if (canvasRef.current) {
+      let ctx = canvasRef.current.getContext('2d');
+      ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
+      if (showFrequencySlider) {
+        plotValues(ctx, historyRef.current, min, max, frequencyColor);
+      }
+      if (showPitchSlider) {
+        const [minOct, maxOct] = [Math.log2(min), Math.log2(max)];
+        let perceptual = historyRef.current.map((v) => Math.log2(v));
+        plotValues(ctx, perceptual, minOct, maxOct, pitchColor);
+      }
+    }
+  }, plot);
+
+  let handleChangeFrequency = (f) => {
+    setHz(f);
+    if (oscRef.current) {
+      oscRef.current.frequency.value = f;
+    }
+  };
+  let handleMouseDown = () => {
+    cancelAnimationFrame(frameRef.current);
+    startOsc(hz);
+  };
+
+  let exponent, activeNote, activeNoteLabel;
+  if (showPitchSlider) {
+    const expOffset = baseFrequency ? Math.log2(baseFrequency / min) : 0;
+    exponent = freq2pitchSlider(hz) * Math.log2(max / min) - expOffset;
+    let semitones = parseFloat((exponent * 12).toFixed(2));
+    if (zeroOffset) {
+      semitones = semitones + zeroOffset;
+      const isWhole = Math.round(semitones) === semitones;
+      activeNote = midi2note(Math.round(semitones));
+      activeNoteLabel = (!isWhole ? '~' : '') + activeNote;
+      semitones = !isWhole ? semitones.toFixed(2) : semitones;
+      exponent = (
+        <>
+          ({zeroOffset} - <span className="text-yellow-500">{semitones}</span>)/12
+        </>
+      );
+    } else if (semitones % 12 === 0) {
+      exponent = <span className="text-yellow-500">{semitones / 12}</span>;
+    } else if (semitones % 1 === 0) {
+      exponent = (
+        <>
+          <span className="text-yellow-500">{semitones}</span>/12
+        </>
+      );
+    } else {
+      exponent = <span className="text-yellow-500">{exponent.toFixed(2)}</span>;
+    }
+  }
+  return (
+    <>
+      <span className="font-mono">
+        {showFrequencySlider && <span className="text-blue-500">{hz.toFixed(0)}Hz</span>}
+        {showFrequencySlider && showPitchSlider && <> = </>}
+        {showPitchSlider && (
+          <>
+            {baseFrequency || min}Hz * 2<sup>{exponent}</sup>
+          </>
+        )}
+      </span>
+      {claviature && (
+        <>
+          {' '}
+          = <span className="text-yellow-500">{activeNoteLabel}</span>
+        </>
+      )}
+      <div>
+        {showFrequencySlider && (
+          <div className="flex space-x-1 items-center">
+            <input
+              type="range"
+              value={freqSlider}
+              min={0}
+              max={1}
+              step={0.001}
+              onMouseDown={handleMouseDown}
+              className={`block w-full max-w-[600px] accent-blue-500 `}
+              onChange={(e) => {
+                const f = freqSlider2freq(parseFloat(e.target.value));
+                handleChangeFrequency(f);
+              }}
+            />
+          </div>
+        )}
+        {showPitchSlider && (
+          <div>
+            <input
+              type="range"
+              value={pitchSlider}
+              min={0}
+              max={1}
+              //step=".001"
+              step={pitchStep}
+              onMouseDown={handleMouseDown}
+              className={`block w-full max-w-[600px] accent-yellow-500`}
+              onChange={(e) => {
+                const f = pitchSlider2freq(parseFloat(e.target.value));
+                handleChangeFrequency(f);
+              }}
+            />
+          </div>
+        )}
+      </div>
+      <div className="px-2">
+        {plot && <canvas ref={canvasRef} className="w-full max-w-[584px] h-[300px]" height="600" width={800} />}
+      </div>
+      <div className="space-x-2">
+        {animatable && (
+          <Button onClick={() => startSweep()}>
+            <span style={{ color: '#3b82f6' }}>Frequency Sweep</span>
+          </Button>
+        )}
+        {animatable && (
+          <Button onClick={() => startSweep(true)}>
+            <span style={{ color: '#eab308' }}>Pitch Sweep</span>
+          </Button>
+        )}
+        {buttons.map((f, i) => (
+          <Button key={(f, i)} onMouseDown={() => startOsc(f)}>
+            {f}Hz
+          </Button>
+        ))}
+      </div>
+      {claviature && (
+        <Claviature
+          onMouseDown={(note) => {
+            const f = 440 * 2 ** ((note - 69) / 12);
+            handleChangeFrequency(f);
+            cancelAnimationFrame(frameRef.current);
+            startOsc(f);
+          }}
+          options={{
+            range: ['A1', 'A5'],
+            scaleY: 0.75,
+            scaleX: 0.86,
+            colorize: activeNote ? [{ keys: [activeNote], color: '#eab308' }] : [],
+            labels: activeNote ? { [activeNote]: activeNote } : {},
+          }}
+        />
+      )}
+    </>
+  );
+}

website/src/config.ts

@@ -89,6 +89,7 @@ export const SIDEBAR: Sidebar = {
       { text: 'Accumulation', link: 'learn/accumulation' },
       { text: 'Tonal Functions', link: 'learn/tonal' },
     ],
+    Understand: [{ text: 'Pitch', link: 'understand/pitch' }],
     Development: [
       { text: 'REPL', link: 'technical-manual/repl' },
       { text: 'Sounds', link: 'technical-manual/sounds' },

website/src/pages/understand/pitch.mdx

@@ -0,0 +1,169 @@
+---
+title: Understanding Pitch
+layout: ../../layouts/MainLayout.astro
+---
+
+import { MiniRepl } from '../../docs/MiniRepl';
+import { PitchSlider } from '../../components/PitchSlider';
+import Box from '@components/Box.astro';
+
+# Understanding Pitch
+
+Let's learn how pitch works! The slider below controls the <span style="color:#3b82f6;">frequency</span> of an oscillator, producing a pitch:
+
+{/* <PitchSlider client:load showFrequencySlider plot /> */}
+
+<PitchSlider client:load showFrequencySlider min={20} max={20000} />
+
+- Drag the slider to hear a pitch
+- Move the slider to change the pitch
+- Observe how the Hz number changes
+- <span className="text-red-300">Caution</span>: The higher frequencies could be disturbing for children or animals!
+
+The Hz number is the frequency of the pitch you're hearing.
+The higher the frequency, the higher the pitch and vice versa.
+A pitch occurs whenever something is vibrating / oscillating at a frequency, in this case it's your speaker.
+The unit **Hz** describes how many times that oscillation happens per second.
+Our eyes are too slow to actually see the oscillation on the speaker, but we can <a href="https://www.youtube.com/watch?v=CDMBWw7OuJQ" target="_blank">see it in slow motion</a>.
+
+<Box>
+
+The hearing range of a newborn is said to be between 20Hz and 20000Hz.
+The upper limit decreases with age. What's your upper limit?
+
+</Box>
+
+In Strudel, we can play frequencies directly with the `freq` control:
+
+<MiniRepl client:visible tune={`freq("200 [300,500] 400 [500,<600 670 712 670>]")`} />
+
+## Frequency vs Pitch Perception
+
+Maybe you have already noticed that the <span style="color:#3b82f6;">frequency slider</span> is "lopsided",
+meaning the pitch changes more in the left region and less in the right region.<br/>
+To make that more obvious, let's add a <span style="color:#eab308">pitch slider</span>
+that controls the frequency on a different scale:
+
+<PitchSlider animatable plot showFrequencySlider showPitchSlider client:load />
+
+Try out the buttons above to sweep through the frequency range in 2 different ways:
+
+- Frequency Sweep: <span style="color:#3b82f6;">frequency rises linear</span> , <span style="color:#eab308">pitch rises logarithmic</span>
+- Pitch Sweep: <span style="color:#3b82f6;">frequency rises exponential</span> , <span style="color:#eab308">pitch rises linear</span>
+
+<Box>
+
+Don't be scared of these mathematical terms:
+
+- "logarithmic" is just a fancy way of saying "it starts fast and slows down"
+- "exponential" is just a fancy way of saying "it starts slow and gets faster"
+
+</Box>
+
+Most of the time, we might want to control pitch in a way that matches our perception,
+which is what the <span style="color:#eab308">pitch slider</span> does.
+
+## From Hz to Semitones
+
+Because Hz does not match our perception, let's try to find a unit for pitch that matches.
+To approach that unit of pitch, let's look at how frequency behaves when it is doubled:
+
+<PitchSlider client:load showPitchSlider showFrequencySlider pitchStep={1 / 7} />
+
+- Use the now stepped pitch slider above
+- Can you hear how these pitches seem related to each other?
+
+<Box>
+
+In musical terms, a pitch with double the frequency of another is an `octave` higher.
+
+</Box>
+
+Because octaves are pretty far apart, octaves are typically divided into 12 smaller parts:
+
+<PitchSlider client:load showPitchSlider showFrequencySlider pitchStep={1 / 12} min={440} max={880} initial={440} />
+
+This step is also called a semitone, which is the most common division of pitched music.
+For example, the keys on a piano keyboard are also divided into semitones.
+
+In Strudel, we could do that with `freq` like this:
+
+<MiniRepl
+  client:visible
+  tune={`freq(
+  "0 4 7 12"
+  .fmap(n => 440 * 2**(n/12))
+)`}
+/>
+
+Of course, this can be written shorter with note, as we will see below.
+
+## From Semitones to MIDI numbers
+
+Now we know what the distance of a semitone is.
+Above, we used an arbitrary base frequency of 440Hz, which means the exponent 0 is equal to 440Hz.
+Typically, 440Hz is standardized to the number 69, which leads to this calculation:
+
+<PitchSlider
+  client:load
+  showPitchSlider
+  showFrequencySlider
+  baseFrequency={440}
+  zeroOffset={69}
+  pitchStep={1 / 12 / 7}
+  min={440 / 8}
+  max={7040}
+  initial={440}
+/>
+
+The yellow number is now a MIDI number, covering more than the whole human hearing range with numbers from 0 to 127.
+In Strudel, we can use MIDI numbers inside `note`:
+
+<MiniRepl client:visible tune={`note("69 73 76 81")`} />
+
+## From MIDI numbers to notes
+
+In western music theory, notes are used instead of numbers.
+For each midi number, there is at least one note label:
+
+<PitchSlider
+  client:load
+  showPitchSlider
+  showFrequencySlider
+  baseFrequency={440}
+  zeroOffset={69}
+  pitchStep={1 / 48}
+  min={440 / 8}
+  max={880}
+  initial={440}
+  claviature
+/>
+
+A full note label consists of a letter (A-G), 0 or more accidentals (b | #) and an octave number.
+This system is also known as [Scientific Pitch Notation](https://en.wikipedia.org/wiki/Scientific_pitch_notation).
+In Strudel, these note labels can also be used inside `note` as an alternative to midi numbers:
+
+<MiniRepl client:visible tune={`note("A4 C#5 E5 A5").piano()`} />
+
+## Open Questions
+
+Now that we have learned about different representations of pitch, there are still open questions:
+
+- Why 12 notes? What about different divisions of the octave?
+- Why are notes labeled as they are? Why only 7 letters?
+- Are there other labeling systems?
+- What about Just Intonation Systems?
+- What about Timbre?
+
+All those questions are important to ask and will be answered in another article.
+
+## Definition
+
+At first, I wanted to start this article with a definition, but then thought it might be a good idea to focus on intuitive exploration.
+Maybe you now understand this definition much better:
+
+<Box>
+
+From [wikipedia](<https://en.wikipedia.org/wiki/Pitch_(music)>): "Pitch is a perceptual property of sounds that allows their ordering on a frequency-related scale, or more commonly, pitch is the quality that makes it possible to judge sounds as "higher" and "lower" in the sense associated with musical melodies."
+
+</Box>