API reference

import { analyse, chord, degree, frequency, loudness, mix, notes, parse, parseKey, Player, render } from "plonkjs";
import type { Analysis, Instrument, MixReport, NoteEvent, PlayerOptions, PlayOptions, SfxOptions, Song } from "plonkjs";

Player

new Player(options?: { context?: AudioContext; destination?: AudioNode; master?: boolean })

Member	Meaning
play(song, { fade?, at? })	Play a song from the top, or from step at, looping. Fades in over fade seconds. Replaces what was playing.
stop(fade = 0)	Stop, fading out over fade seconds.
tempo(scale)	Speed up or slow down from the next note: 1 is the song's own bpm.
layer(instrument, volume, fade = 0.5)	Fade one instrument's track to volume (0 to 1).
sfx(instrument, options)	Play a one-shot sound effect: by degree in the song's key (or note, freq), at velocity, for length seconds, optionally waiting for the next "step", "beat" or "bar" (quantize) and after that many steps more. Returns when it plays. Sound effects play even with the music faded out.
playing	Whether a song is playing.
played	The last 256 notes scheduled (music and sound effects), as NoteEvents.
context	The audio context in use.

Notes are scheduled 0.15 seconds ahead on the audio clock, so a slow frame in the game doesn't throw the music off.

Song

interface Song {
  bpm: number;
  swing?: number; // 0 to 0.5
  key?: string; // "C major", "A minor"...
  transpose?: number; // semitones
  instruments: Record<string, Instrument>;
  sections: Record<string, Record<string, string | string[]>>; // section -> instrument -> pattern (or variants)
  order: string[];
}

See Songs and patterns for the pattern notation and Instruments for Instrument.

Pure helpers

Function	Returns
notes(song, from, to)	Every NoteEvent starting in steps [from, to), looping through order.
parse(pattern)	The pattern's steps: a Step ({ freqs, velocity, length }) where something starts, null elsewhere. Throws on unreadable steps.
frequency(name)	A note name in Hz ("A4" is 440), or undefined.
chord(name)	A chord name with an octave ("Am7@3") as frequencies, or undefined.
degree(key, n, octave = 4)	Scale degree n of key in Hz (1 is the root, 8 an octave up).
parseKey(key)	A key's root and scale. SCALES lists the scales.
songSteps(song)	Steps in one pass of the song.
sectionSteps(section)	Steps in a section: its longest pattern.
stepSeconds(bpm)	Seconds per step (a sixteenth note).

Measuring

Function	Returns
mix(song, seconds = 20)	Renders the song and each instrument offline and returns a MixReport: the whole song's Analysis, each track's loudness and how far it sits under the mix, and plain-words warnings. Browser only (needs OfflineAudioContext).
render(song, seconds, only?)	The song (or only some instruments) rendered offline at 48 kHz, as channels of samples. Browser only.
analyse(channels, rate?)	An Analysis of samples: peakDb, clipped, lufs (ITU-R BS.1770), bands (low, mid, high shares) and silence. Pure: runs anywhere.
loudness(channels, rate?)	Integrated loudness in LUFS. Pure.

interface NoteEvent {
  time: number; // seconds from step 0
  instrument: string;
  freq: number; // Hz, or 0 for a drum hit
  duration: number; // seconds
  velocity: number; // 0 to 1
}