Live Demo

Aion is a purely functional audio engine in roughly 100 LoC¹.

Traditional audio engines are imperative: they process chunks of data and maintain a hidden, internal state.

Aion is declarative: it treats audio as a mapping from $T \rightarrow \mathbb{R}^2$. Because there is no hidden state, "time" becomes just another variable you can multiply, offset, or reverse. This allows for complex temporal structures, like a delay that contains a reversed version of itself, to be expressed in just a few lines of code.

It's also lavishly inefficient and more of a thought experiment than anything usable.

Example: Fully self-contained sine oscillator with a repeating pluck envelope and a delay effect.

new AionHost().start(`
const osc = (t, hz) => Math.sin(t * hz * 2 * Math.PI)   // a simple sine oscillator
const pluck = (t) => Math.exp(-5 * (t % 0.5))           // a 2Hz repeating pluck envelope

(t) => {
  if (t < 0) return [0, 0]                              // guarding against infinite recursion
  const dry = osc(t, 220) * pluck(t) * 0.2              // producing a dry signal
  const [wetL, wetR] = $(t - 0.125)                     // jumping back in time by 125ms
  return [dry + 0.9 * wetL, dry + 0.9 * wetR]           // producing the final output signal
}`)

The Aion "audio engine" compiles JavaScript code that evaluates to an expression and executes it in an AudioWorklet. The expression has the type (t: number) -> [number, number] and can itself be evaluated using the $ symbol. The engine prepends a standard library to the user-provided code, exported as Æ and A.

Functions are expected to be pure.

In computer programming, a pure function is a function that has the following properties:

1. the function return values are identical for identical arguments (no variation with local static variables, non-local variables, mutable reference arguments or input streams, i.e., referential transparency), and
2. the function has no side effects (no mutation of non-local variables, mutable reference arguments or input/output streams).

-- Pure Function on Wikipedia

This results in interesting properties. For example, when editing code, delay lines that typically hold past samples update as if that note was played in the past. You can jump backwards and forwards in time at will and play sections in reverse, or at a different local tempo.

Functions of the Aion standard library are typically of the form f(I) -> (t) -> O. This makes them composable.

For example, a naive sum and product of audio samples can be implemented as:

const mul =
  (...fs) =>
  (t) =>
    fs.reduce(
      (acc, f) => {
        const [l, r] = f(t)
        return [acc[0] * l, acc[1] * r]
      },
      [1, 1]
    )
const sum =
  (...fs) =>
  (t) =>
    fs.reduce(
      (acc, f) => {
        const [l, r] = f(t)
        return [acc[0] + l, acc[1] + r]
      },
      [0, 0]
    )

You could then combine these:

const cnst = (t, v) => v // produce a constant
const sin = (t, hz) => Math.sin(t * hz * 2 * Math.PI) // produce a sine wave
const saw = (t, hz) => { // produce a saw wave
  const p = t * hz
  return 2 * (p - Math.floor(p)) - 1
} 
const synth = (hz, osc) => (t) => [osc(t, hz), osc(t, hz)] // convert an oscillator to a stereo signal
sum(
  // add the signals together
  mul(synth(440, sin), synth(0.125, cnst)), //   adjust the vol of the sine
  mul(synth(110, saw), synth(0.125, cnst)) //   adjust the vol of the saw
)

Because f is pure, you can evaluate f at any point in time and as many times as you want.

Typically, a delay in an audio engine is O(n) whereas the example above is O(n * cost(f)) because we re-evaluate f every time. This can snowball pretty quickly if you place, for example, a delay in a delay. Many effects, such as a chorus, use the concept of a delay internally.

Most of the time it's enough if a function is observationally pure under monotonic forward time.

The Aion standard library prefixes all functions with this property with an i. Æ.delay is pure but O(n * cost(f)), Æ.idelay is O(n) but only observationally pure under monotonic forward time.

Practically it means: we can buffer data unless you jump backwards in time. A buffer is cleared when a discontinuity in t is observed. To buffer data, we use the Æ.ibuf function.

Every function is implemented pure unless it's not feasible from a performance perspective.

The standard library is exported as Æ and A.

Type Aliases:

• Pair: [number, number] (stereo sample)
• Osc: (t: number, hz: number) -> number
• Env: (t: number) -> number

Globals:

• L and R: The left and right array indices
• TAU: 2 * Math.PI
• SEMIS: Semitones from C; example: SEMIS.D is 2
• ZERO: [0,0]
• NULL_VOICE: () -> ZERO
• sampleRate: The current sample rate in Hz
• $: The compiled expression itself

Every oscillator has the form Osc.

{
  triggerTime: number = 0,          // at what time to trigger; 0 before triggerTime
  releaseTime: number = Infinity,   // at what time to release
  attackSec:   number,              // attack in sec
  decaySec:    number,              // decay in sec
  sustain:     number,              // sustain level
  releaseSec:  number,              // release time in sec; 0 after releaseTime+releaseSec
}

Note: Sections receive local time starting at 0 for each section.

const tempo = Æ.tempoBpm(120)
const bar = (n) => n * Æ.sec("1/1", tempo)

const intro = Æ.seq(...)
const verse = Æ.seq(...)
const bridge = Æ.sum(Æ.seq(...), Æ.seq(...))

Æ.song(
  Æ.section(intro, bar(2)),
  Æ.section(verse, bar(8)),
  Æ.section(bridge, bar(4)),
  ...
)

We define tempo as { value(t) -> bpm, phase(t) -> beats elapsed }. Each combinator carries its own analytic integral so that step sequencers can function under tempo variation.

Tempos are combinators and can therefore be chained.

// slight wobble of 2bpm at 0.5hz around 120bpm
const tempo = Æ.tempoLfo(Æ.tempoBpm(120), 2, 0.5)

General Usage

• let g = ibuf(f) creates a buffer, g(t) fills the buffer forward to Math.round(t * sampleRate) and returns the current sample.
• g.at(frame) returns a past sample (zero outside the buffer window).
• g.buf / g.cap expose the raw stereo-interleaved Float64Array for hot loops.

Example

const buf = Æ.ibuf(A.pluck(440, A.sin), 1) // create a buffer for one second
const out = Æ.alloc()                      // pre-allocate sample pair (optional; purely for perf reasons)

(t) => {
  buf(t)                                           // update the buffer
  const currentFrame = Math.round(t * sampleRate)  // compute the current frame
  ;[out[L], out[R]] = buf.at(currentFrame)         // read the signal
  // [...]                                         // do something with the signal...
  return out
}

polyseq backtracks at most min(maxVoices, voices.length) voices. The same voice is never evaluated twice so that impure functions behave as expected.

Note: Voices receive local time starting at 0 for each voice. null in the array is converted to NULL_VOICE.

shuffle(amount) delays every odd step by stretching each even/odd pair into long-short timing. amount is clamped to [-0.95, 0.95]; 0 is straight timing and the default 1 / 3 creates a 2:1 triplet shuffle. Use it as Æ.seq(vs, "1/16", tempo, Æ.shuffle()), Æ.polyseq(vs, "1/16", tempo, Æ.shuffle()), or Æ.polyseq(vs, "1/16", tempo, 4, Æ.shuffle()).

{
  wave:      Osc                        = Æ.saw
  cutoffHz:  Env | number               = 800
  envModOct: Env | number               = 3
  q:         Env | number               = 6
  decaySec:  Env | number               = 0.3
  accent:    bool | (t: number) -> bool = false
}

{
  decay: number = 0.998
}

{
  env:         Env          = Æ.adsr(...)
  ratio:       Env | number = 2
  modIndex:    Env | number = 4
  modDecaySec: Env | number = 0.3
}

{
  attackSec:     number = 0.002
  decaySec:      number = 0.3
  tuneHz:        number = 50
  pitchDecaySec: number = 0.05
}

{
  attackSec: number = 0.001
  decaySec:  number = 0.18
  tuneHz:    number = 180
  noiseAmt:  number = 0.7
  snap:      number = 0.35
}

{
  open:      bool   = false
  attackSec: number = 0.001
  decaySec:  number = 0.05   // 0.35 if open: true
  shimmerHz: number = 7000
  tone:      number = 0.18
}

{
  thresholdDb: number              = -20
  ratio:       number              = 4
  kneeDb:      number              = 6
  attackSec:   number              = 0.005
  releaseSec:  number              = 0.1
  makeupDb:    number              = 0
  sidechain:   (t: number) -> Pair = f
  capacitySec: number              = 0.5
}

¹: The optional standard lib clocks in with another 1k LoC