Elementary Audio Kit

Musical abstractions for Elementary Audio - timing, sequencing, and instruments.

Note: This library is in early development. APIs may change.

What is this?

Elementary Audio Kit provides higher-level building blocks for creating music applications with Elementary Audio. While Elementary gives you powerful DSP primitives, this library adds the musical concepts you need to build sequencers, drum machines, and synthesizers.

Think of it like this:

• @elemaudio/core → Low-level DSP primitives (like Core Audio)
• @elementary-audio-kit/core → Musical abstractions (like AudioKit)

Installation

npm install @elementary-audio-kit/core @elemaudio/core

Features

Timing

Beat clocks, transport control, quantization, and groove utilities.

import { createTransport, TimeSignatures } from '@elementary-audio-kit/core';
import { el } from '@elemaudio/core';

// Create a transport at 120 BPM in 4/4 time
const transport = createTransport({
  bpm: el.const({ key: 'bpm', value: 120 }),
  playing: el.const({ key: 'playing', value: 1 }),
  timeSignature: TimeSignatures.common,
});

// Use transport signals
transport.clock;      // Pulse on each beat
transport.clock16th;  // Pulse on each 16th note
transport.beat;       // Current beat count (0, 1, 2, ...)
transport.bar;        // Current bar count
transport.beatInBar;  // Beat within current bar (0-3 in 4/4)

Sequencing

Step sequencers, trigger patterns, and Euclidean rhythms.

import { euclideanTrigger, triggerPattern, patternFromString } from '@elementary-audio-kit/core';

// Euclidean rhythm - 5 hits distributed over 8 steps
const hihatTrigger = euclideanTrigger(5, 8, transport.clock);

// Manual trigger pattern
const kickTrigger = triggerPattern(
  [true, false, false, false, true, false, false, false],
  transport.clock
);

// String notation (x = hit, - = rest)
const snareTrigger = triggerPattern(
  patternFromString('----x-------x---'),
  transport.clock16th
);

Putting it together

import { createTransport, euclideanTrigger, triggerPattern } from '@elementary-audio-kit/core';
import { el } from '@elemaudio/core';

// Setup transport
const bpm = el.const({ key: 'bpm', value: 120 });
const playing = el.const({ key: 'playing', value: 1 });
const transport = createTransport({ bpm, playing });

// Create drum pattern
const kick = el.mul(
  el.sample({ path: 'kick', mode: 'trigger' },
    triggerPattern([true, false, false, false], transport.clock), 1),
  0.9
);

const hihat = el.mul(
  el.sample({ path: 'hihat', mode: 'trigger' },
    euclideanTrigger(5, 8, transport.clock), 1),
  0.4
);

// Mix and render
const mix = el.add(kick, hihat);
core.render(mix, mix);

API Reference

Timing Module

import { ... } from '@elementary-audio-kit/core/timing';

| Function | Description | |----------|-------------| | beatClock(bpm) | Creates a pulse train at the given BPM | | subdivisionClock(bpm, subdivision) | Creates a faster clock (2=8ths, 4=16ths) | | gatedClock(clock, gate) | Clock that only ticks when gate is high | | beatCounter(clock) | Counts beats from a clock signal | | barCounter(beats, beatsPerBar) | Returns current bar number | | beatInBar(beats, beatsPerBar) | Returns beat position within bar | | createTransport(config) | Creates a complete transport with all signals | | quantize(value, gridSize) | Snaps a value to the nearest grid point | | beatsToMs(beats, bpm) | Converts beats to milliseconds | | swing(clock, amount) | Adds swing to a clock signal | | accentPattern(clock, velocities) | Creates a velocity accent pattern |

Sequencing Module

import { ... } from '@elementary-audio-kit/core/sequencing';

| Function | Description | |----------|-------------| | stepSequencer(values, clock) | Cycles through values on each clock tick | | triggerPattern(hits, clock) | Creates a trigger pattern (1s and 0s) | | velocityPattern(velocities, clock) | Creates a velocity pattern (0-1 values) | | euclidean(hits, steps) | Generates a Euclidean rhythm pattern | | euclideanTrigger(hits, steps, clock) | Creates an Elementary signal from Euclidean pattern | | presetTrigger(preset, clock) | Creates a trigger from a named preset | | rotatePattern(pattern, steps) | Rotates a pattern by N steps | | patternFromString(notation) | Parses 'x--x--x-' notation to boolean array |

Roadmap

• [ ] Instruments: Sampler, MonoSynth, PolySynth, DrumMachine
• [ ] Effects: Tempo-synced delay, reverb, chorus
• [ ] MIDI: Note scheduling, CC mapping
• [ ] React hooks: useTransport, useSequencer (separate package)

Contributing

Contributions are welcome! This project aims to make Elementary Audio more accessible by providing musical building blocks that are missing from the core library.

License

MIT