Bounce REPL

API Reference

All namespaces and functions available in the Bounce interactive REPL. Top-level expressions are auto-awaited, so await is optional.

sn — Sample Namespace

The sn namespace is the primary entry point for loading and managing audio samples. Call sn.help() in the REPL to print a live summary.

sn.read(path: string) → SamplePromise

Load an audio file from path into the sample store and return a SamplePromise that resolves to a Sample object. If the file has been read before its metadata is returned from the SQLite cache immediately.

REPL

const s = sn.read("./kick.wav")
s  // prints: Sample { hash: "a1b2…", duration: 0.52s, channels: 1, sr: 44100 }

Parameter	Type	Description
path	string	Absolute or relative path to a WAV, AIFF, FLAC, or MP3 file.

sn.load(hash: string) → SamplePromise

Load a previously-seen sample by its content hash. Useful for re-opening samples across sessions without remembering the original file path.

REPL

const s = sn.load("a1b2c3d4")

Parameter	Type	Description
hash	string	SHA-based content hash as shown in the Sample object summary.

sn.ls(dir?: string) → LsResultPromise

List audio files and subdirectories in dir (defaults to the current working directory).

REPL

sn.ls("./samples")

sn.glob(pattern: string) → GlobResultPromise

Return all audio files matching a glob pattern. Supports ** recursive matching.

REPL

sn.glob("./drums/**/*.wav")

Parameter	Type	Description
pattern	string	Glob pattern relative to the current working directory.

Sample object

The Sample object is returned by sn.read() and sn.load(). Printing it in the REPL shows a one-line summary of its most important properties.

sample.onsets(options?) → OnsetFeaturePromise

sample.onsets(options?: OnsetOptions) → OnsetFeaturePromise

Run FluCoMa onset detection on the sample. Slice markers are immediately reflected in any waveform visualisation that is already open.

REPL

const onsets = sample.onsets({ threshold: 0.3, minSliceLength: 4410 })

Option	Type	Description
threshold	number	Onset sensitivity threshold (0–1). Default `0.5`.
minSliceLength	number	Minimum slice length in samples. Default `2205`.

sample.nmf(options?: NmfOptions) → NmfResultPromise

Run Non-negative Matrix Factorisation on the sample to decompose it into n spectral components and their activations.

REPL

const nmf = sample.nmf({ components: 4 })
nmf.play(0)   // play component 0

Option	Type	Description
components	number	Number of NMF components to extract. Default `4`.
iterations	number	Number of NMF iterations. Default `100`.

sample.novelty(options?: NoveltyOptions) → NoveltyFeaturePromise

Slice the sample using FluCoMa novelty-based segmentation, which detects structural changes in spectral content.

REPL

const nx = sample.novelty({ threshold: 0.4 })

Option	Type	Description
threshold	number	Novelty sensitivity (0–1). Default `0.5`.
filterSize	number	Size of the novelty kernel. Default `3`.

vis — Visualisation Namespace

vis.waveform(sample: Sample) → WaveformScene

Create a waveform scene for sample and return it. Call .show() to render it in the terminal canvas.

REPL

vis.waveform(sample).show()

Playback

sample.play() → void

Play the full sample through the audio engine.

REPL

sample.play()

sample.stop() → void

Stop any active playback for this sample.

REPL

sample.stop()

help()

sn.help() | vis.help() | sample.help()

Every namespace and returned object exposes a help() method that prints a usage summary directly in the terminal.

REPL

sn.help()
// sn — sample namespace
//   sn.read(path)   load a sample from disk
//   sn.load(hash)   load a sample by content hash
//   sn.ls(dir?)     list audio files
//   sn.glob(pat)    glob for audio files