tur-signal

Typed Signal Function (SF) library for Turmeric: oscillators (including FM and PM), one-pole / biquad / state-variable / ladder filters, delays and combs, colored noise, sample buffers and buffer scanning (nearest, linear, cubic and windowed-sinc interpolation), MIDI note / Hz conversion, Scala .scl / .kbm tunings with tuning-aware note / Hz conversion, shapers, ADSR envelopes, and SF-pipeline composition.

Status

Runs end-to-end against turmeric main (checked with v0.65.2). All twelve modules tur check clean, all twelve examples run and print the values in their comments, and the full tests/signal/ suite passes:

$ tur test tests/signal
PASS test_buffer
PASS test_compose
PASS test_core
PASS test_delay
PASS test_envelope
PASS test_filter
PASS test_hf_osc
PASS test_noise
PASS test_osc
PASS test_pitch
PASS test_shaper
PASS test_tuning
............
12 tests, 12 passed, 0 failed

Not provided: Karplus-Strong and granular synthesis, band-limited wavetable sets, saturating (analog-modeled) filters, voice management / poly-synths / sequencers (the guide shows a melody and a cycle built from the parts), and audio device or file output. The guide walks every module with runnable examples.

Concepts

A Signal A is conceptually a function from time to a value: (fn [t :float] A). The common case is Signal Sample, where a sample is a :float: (fn [t :float] :float).

An SF A B (Signal Function) maps a signal to a signal. Every oscillator, filter, and shaper constructor returns an SF; apply it to a signal to get a signal back:

(let [tone   ((sine 440.0 0.0) (constant 0.0))   ;; SF applied -> Signal
      shaped ((gain 0.5) tone)]                   ;; SF applied -> Signal
  (sample shaped 0.0))                            ;; sample the result

The Pair-consuming mixers (mix, add, multiply) consume the Signal (Pair Sample Sample) shape produced by pair-signals.

Calling conventions worth knowing

A few constructors need a specific call shape:

• Captureless shapers (invert, abs-sf, add, multiply) take no parameters. Bind the SF to a name first, then apply it -- applying the bare (invert) result inline does not compile:

  (let [iv (invert)]
    (sample (iv (constant 0.5)) 0.0))   ;; -0.5
  

• effects-chain returns the chained signal as a raw pointer. Re-bind the result as a ^fat signal before sampling:

  (let [^fat out : (fn [float] float)
             (effects-chain (vec-of (gain 0.5) (low-pass 0.3)) osc)]
    (sample out 0.0))
  

  map-signal returns an ordinary signal; sample it directly.

• ADSRParams is a :copy struct; build it with make-struct and pass it by value to adsr-fixed / adsr-gen.

• Sample rates come first in every constructor that takes one ((biquad-lp 48000.0 1200.0 0.7071), (delay 48000.0 0.25)), except the hf-osc oscillators, which take it last.

Module layout

signal/core

signal/osc

The four shapes are SF () Sample -- they ignore their input signal.

These are the naive shapes: right for control signals (LFOs), but they alias at audio rate. For hearing-range pitches use signal/hf-osc.

The two modulation oscillators are SF Sample Sample: their input signal is the modulator.

For a sine modulator they are the same sound: FM by D*cos(2*pi*fm*t) is PM by (D/fm)*sin(2*pi*fm*t), which test_osc checks.

signal/hf-osc

Band-limited oscillators (PolyBLEP / PolyBLAMP) for hearing-range pitches. Each takes the sample rate the signal will be sampled at, so it can size the edge correction to one sample period. See the guide's section 2b for the measured aliasing reduction.

signal/filter

Every filter is stateful; each application owns its own state cell. Every constructor that takes Hz takes the sample rate first. Cutoffs are clamped to [0, 0.49 * sample-rate] and q to at least 0.01; a biquad given a non-positive sample rate passes its input through.

signal/delay

Ring-buffer effects. Two layers: the *-n constructors take the delay in whole samples and need no sample rate; the bare ones take (sample-rate seconds ...) -- sample-rate in Hz, like signal/hf-osc -- and round seconds * sample-rate to the nearest sample. Delays clamp to [1, 16777216] samples.

Feedback gains are not clamped: |g| >= 1 grows without bound.

signal/noise

Generators: apply the SF to any signal (it is ignored), e.g. ((pink 1) (constant 0.0)). Output is always within [-1, 1].

Grey noise is a psychoacoustic equal-loudness curve rather than a slope and is not provided.

Purity. (white seed) keeps its PRNG state in a private cell: its effect row is #fx{} and a seed always yields the same samples. The *-from constructors (white-from, pink-from, ...) instead take a source src : (fn [] #fx{e} float) of raw white samples and return a signal whose row is #fx{e}. Pass (rng seed) and it stays pure; pass an entropy read or a live input and it is honestly #fx{IO}, and the compiler rejects using it from a function declared #fx{} (TUR-E0009). Row checking needs a recent compiler: turmeric v0.55 does not enforce it, v0.64 does.

signal/buffer

A Buffer is a fixed-length array of samples (up to 16777216), shared by handle and living for the process. scan reads one as a signal.

Scanned by a sawtooth at f Hz, a one-cycle buffer is an f Hz wavetable oscillator; a recording scanned once per its duration plays back looped, and faster or slower ramps transpose it like tape.

All four reads return the stored sample on the grid. Off it, on a 440 Hz recording at 48 kHz, nearest is good to 3e-2, linear to 4e-4 and cubic and sinc to 3e-6; on a 16.8 kHz one (0.35 cycles per sample) only sinc stays close (4e-6, against 0.36 for cubic). The sinc read costs about 20 times a linear one. None of them filters: scanning faster than one sample per sample period still aliases what the buffer holds above the new Nyquist.

signal/pitch

Twelve-tone equal temperament, A4 = 440 Hz = note 69 (middle C is note 60). Note numbers are floats: each 1.0 is a semitone. Both are plain :float -> :float functions; lift one onto a signal with map-signal.

For any other tuning, see signal/tuning's mtof-tuned / ftom-tuned.

signal/tuning

A tuning in Scala's terms: a scale (pitches above 1/1, the last the period it repeats at) played through a keymap (which note plays which degree, and which note sounds at which frequency). Scales, keymaps and tunings are immutable handles that live for the process.

(tuning-new (scale-edo 12) (keymap-linear 60 69 440.0)) makes mtof-tuned equal mtof. Mappings whose formal octave is the scale's size (the normal case) agree note for note with the Surge tuning-library; where they differ (a mapping written for another scale), this follows the Scala format's definition of the formal octave. The first/last-note fields are kept and written back but mtof-tuned retunes every note.

A program that uses the String results loads stdlib/string.tur before its defmodule, as signal/tuning does, so both share one String type.

Stateful signals are pull-order dependent

Every filter, every delay effect, every noise generator and fm-sine advance their internal state once per sample call and ignore t. Sample each instance exactly once per sample period, in order. Feeding one instance to two consumers (for example both halves of pair-signals) advances it twice, so each consumer sees only part of the stream and a delay's effective length changes. Build one instance per consumer, or render the signal into a Buffer and scan that. The other oscillators, the shapers, the envelopes and the scans are pure functions of t and have no such restriction.

signal/shaper

signal/envelope

signal/compose

Installation

In your build.tur :spices block:

(defpackage my-app
  :spices #map{
    "signal" #map{:url    "https://github.com/turmeric-lang/turmeric-spices"
                  :ref    "main"
                  :subdir "spices/signal"}
  })

Then tur fetch. There is no signal-v* release tag yet, so track main.

Quick start

(defmodule my/app
  (import signal/core     :refer [constant sample pair-signals])
  (import signal/osc      :refer [sine])
  (import signal/filter   :refer [biquad-lp])
  (import signal/shaper   :refer [multiply])
  (import signal/envelope :refer [ADSRParams adsr-fixed])
  (import signal/pitch    :refer [mtof])

  (defn main [] : int
    ;; A constant, and an A4 sine a quarter cycle in: its peak.
    (println (sample (constant 0.5) 0.0))               ;; 0.5
    (let [a4 ((sine (mtof 69.0) 0.0) (constant 0.0))]
      (println (sample a4 (/ 0.25 440.0))))             ;; 1

    ;; Filters are stateful: each sample call advances them.
    (let [lp ((biquad-lp 48000.0 1000.0 0.7071) (constant 1.0))]
      (println (sample lp 0.0))                         ;; 0.00391612
      (println (sample lp 0.0)))                        ;; 0.0188575

    ;; A voice: an A3 sine times the envelope of a half-second note.  At a
    ;; crest of the sine during the sustain, it reads the sustain level.
    (let [env   ((adsr-fixed (make-struct ADSRParams 0.01 0.1 0.6 0.2) 0.5)
                 (constant 0.0))
          a3    ((sine (mtof 57.0) 0.0) (constant 0.0))
          ml    (multiply)
          voice (ml (pair-signals a3 env))]
      (println (sample env 0.005))                      ;; 0.5 (half way up the attack)
      (println (sample voice (+ 0.25 (/ 0.25 220.0)))))  ;; 0.6
    0))

defmodule my/app
  import signal/core     :refer [constant sample pair-signals]
  import signal/osc      :refer [sine]
  import signal/filter   :refer [biquad-lp]
  import signal/shaper   :refer [multiply]
  import signal/envelope :refer [ADSRParams adsr-fixed]
  import signal/pitch    :refer [mtof]

  defn main [] : int
    ;; A constant, and an A4 sine a quarter cycle in: its peak.
    println $ sample constant(0.5) 0.0                ;; 0.5
    let [a4 (sine(mtof(69.0) 0.0) constant(0.0))]
      println $ sample a4 {0.25 / 440.0}              ;; 1

    ;; Filters are stateful: each sample call advances them.
    let [lp (biquad-lp(48000.0 1000.0 0.7071) constant(1.0))]
      println $ sample lp 0.0                         ;; 0.00391612
      println $ sample lp 0.0                         ;; 0.0188575

    ;; A voice: an A3 sine times the envelope of a half-second note.  At a
    ;; crest of the sine during the sustain, it reads the sustain level.
    let [env   (adsr-fixed(make-struct(ADSRParams 0.01 0.1 0.6 0.2) 0.5)
                 constant(0.0))
         a3    (sine(mtof(57.0) 0.0) constant(0.0))
         ml    multiply()
         voice ml(pair-signals(a3 env))]
      println $ sample env 0.005                      ;; 0.5 (half way up the attack)
      println $ sample voice {0.25 + {0.25 / 220.0}}  ;; 0.6
    0

Examples

Twelve runnable examples live under examples/:

cd spices/signal
tur run examples/01_constant_and_time.tur     # constant + time-signal
tur run examples/02_oscillators.tur           # sine/square/sawtooth/triangle at audible pitches
tur run examples/03_filters_and_shapers.tur   # filters + scalar shapers
tur run examples/04_envelopes.tur             # ADSR
tur run examples/05_simple_voice.tur          # an A3 voice: oscillator, chain, envelope
tur run examples/06_hf_oscillators.tur        # naive vs band-limited sawtooth at 7.9 kHz
tur run examples/07_delay_and_noise.tur       # delay, comb, allpass, colored noise
tur run examples/08_filters.tur               # biquads, state-variable sweep, ladder
tur run examples/09_modulation_and_buffers.tur  # ring, AM, PM, FM, wavetable, tape
tur run examples/10_pitch_and_sequences.tur   # mtof/ftom, a melody in order, a cycle
tur run examples/11_interpolation.tur         # nearest/linear/cubic/sinc reads, a note table
tur run examples/12_tunings.tur               # 19-EDO, just intonation on the white keys, .scl/.kbm

Each prints sample values that match the hand-computed references in its comments.

Development

cd spices/signal
for f in src/signal/*.tur; do tur check "$f"; done   # all clean
tur test tests/signal                                 # all pass

Modules that call libm (signal/osc, signal/hf-osc, signal/filter, signal/shaper, signal/buffer, signal/pitch) carry a __tur_autolink__: -lm directive so any program importing them links against the math library automatically.

See also

• Guide
• API reference
• Source: https://github.com/turmeric-lang/turmeric-spices/tree/main/spices/signal