Additive Synthesis Waveform Visualisation

Math essence

y(t) = sum a_i sin(2π f_i (t + x/W) + phi_i); amplitudes normalised so sum |a_i| = 1; detune in [-0.5, 0.5] per oscillator. Fundamental scaled by (i+1) for a harmonic stack; phases randomised at reset.

Parameters

Reference

First 60 lines of reference.py. Full source: library_external/openprocessing_p5js/SoundWaveform/reference.py

from __future__ import annotations

from typing import ClassVar

import numpy as np


class SoundWaveform:
    """Additive-synthesis waveform visualisation: sum of N sine waves at
    different frequencies / amplitudes / phases.

    This is the visual half of the canonical Processing Sound library
    Example 01
    (<https://processing.org/tutorials/sound> — "Five sine waves layered to
    construct a cluster of frequencies") and its p5.js port. The audio
    identity is

        y(t) = A * sum_{i=0..N-1} a_i * sin(2π f_i t + phi_i)

    with amplitudes normalised so the peak-to-peak stays bounded
    (``sum |a_i| = 1``). step(n) advances time; render() draws an envelope-
    coloured stack of the individual sines plus the composite waveform.

    Each sine is rendered as a 1-px polyline coloured by its hue, and the
    composite waveform is drawn on top in white. The result is the iconic
    "wave packet" / additive-synthesis display that has been the entry
    point for every coding musician learning Processing or p5.js.
    """

    family: ClassVar[str] = "openprocessing_p5js"
    sketch: ClassVar[str] = "soundWaveform"

    def __init__(
        self,
        dim: int = 512,
        num_sines: int = 7,
        fundamental: float = 1.5,
        detune: float = 0.05,
        speed: float = 0.06,
        bg_color: tuple[int, int, int] = (8, 10, 22),
        composite_color: tuple[int, int, int] = (240, 240, 240),
        seed: int | None = None,
    ) -> None:
        self.dim = dim
        self.num_sines = num_sines
        self.fundamental = fundamental
        self.detune = detune
        self.speed = speed
        self.bg_color = np.array(bg_color, dtype=np.float32)
        self.composite_color = np.array(composite_color, dtype=np.float32)
        self._seed = seed
        self.reset()

    def reset(self, seed: int | None = None) -> None:
        if seed is not None:
            self._seed = seed
        self.rng = np.random.default_rng(self._seed)
        self.canvas = np.tile(self.bg_color, (self.dim, self.dim, 1))
        self._tick = 0
        self._t = 0.0