EZ Web Audio

Appearance

EZ Web Audio / Sampler

Class: Sampler ​

Defined in: packages/core/src/sampler.ts:35

Round-robin playback of multiple sounds.

Sampler holds multiple Sound instances and automatically alternates between them on each play() call. This creates realistic variation when playing repeated samples (e.g., multiple recordings of the same drum hit).

Example ​

typescript
import { createSampler } from 'ez-web-audio'

// Load multiple kick drum samples for variation
const kick = await createSampler([
  'kick-1.mp3',
  'kick-2.mp3',
  'kick-3.mp3'
])

// Each play() uses the next sample in rotation
kick.play() // plays kick-1
kick.play() // plays kick-2
kick.play() // plays kick-3
kick.play() // back to kick-1

Extended by ​

Constructors ​

Constructor ​

new Sampler(sounds, opts?): Sampler

Defined in: packages/core/src/sampler.ts:44

Parameters ​

sounds ​

Playable & Connectable[]

Sound instances to cycle through. Stored internally as a Set, so duplicate references silently collapse: [kick1, kick1, kick2] becomes a 2-item rotation (kick1, kick2), not the 3-hit weighting a caller passing the same instance twice would expect (R7 low). Pass distinct instances — e.g. separately-loaded copies of the same sample — if you want one sound to play more often than others in the rotation.

opts? ​

SamplerOptions

Returns ​

Sampler

Properties ​

name ​

name: string

Defined in: packages/core/src/sampler.ts:53

Optional name to aid in identification.

Accessors ​

gain ​

Get Signature ​

get gain(): number

Defined in: packages/core/src/sampler.ts:75

Gain level applied to each sample when played. This value is applied to the underlying Sound on every play() call, overriding any per-sound gain customization.

Validated the same way as Sampler.changeGainTo / BaseSound.changeGainTo: throws a ValidationError for negative values, warns on the console for values above 1 (R1#1 — previously this was a raw mutable field with no validation at all). Defaults to 1.

Returns ​

number

Set Signature ​

set gain(value): void

Defined in: packages/core/src/sampler.ts:79

Parameters ​
value ​

number

Returns ​

void

pan ​

Get Signature ​

get pan(): number

Defined in: packages/core/src/sampler.ts:92

Stereo pan position applied to each sample (-1 = left, 0 = center, 1 = right). This value is applied to the underlying Sound on every play() call, overriding any per-sound pan customization.

Validated the same way as Sampler.changePanTo / BaseSound.changePanTo: warns on the console for values outside [-1, 1] (R1#1). Defaults to 0.

Returns ​

number

Set Signature ​

set pan(value): void

Defined in: packages/core/src/sampler.ts:96

Parameters ​
value ​

number

Returns ​

void

Methods ​

changeGainTo() ​

changeGainTo(value): this

Defined in: packages/core/src/sampler.ts:108

Set the gain level applied to each sample. Equivalent to sampler.gain = value, provided for API symmetry with BaseSound.changeGainTo() / LayeredSound.changeGainTo().

Parameters ​

value ​

number

The gain value (0-1 typical range)

Returns ​

this

this for chaining

changePanTo() ​

changePanTo(value): this

Defined in: packages/core/src/sampler.ts:120

Set the pan position applied to each sample. Equivalent to sampler.pan = value, provided for API symmetry with BaseSound.changePanTo() / LayeredSound.changePanTo().

Parameters ​

value ​

number

The pan value (-1 to 1)

Returns ​

this

this for chaining

getSounds() ​

getSounds(): readonly Playable & Connectable[]

Defined in: packages/core/src/sampler.ts:208

Get a readonly snapshot of the sampler's sounds.

Returns a shallow copy as an array so callers can inspect which sounds are loaded without mutating the internal Set.

Returns ​

readonly Playable & Connectable[]

Readonly array of sounds in the sampler

Example ​

typescript
const sampler = await createSampler(['kick-1.mp3', 'kick-2.mp3'])
const sounds = sampler.getSounds()
console.log(sounds.length) // 2

play() ​

play(velocity): void

Defined in: packages/core/src/sampler.ts:149

Play the next sound in the rotation immediately.

Parameters ​

velocity ​

number = 1

Gain multiplier (0–1) applied on top of the sampler's gain. Defaults to 1 (no attenuation).

Returns ​

void

Example ​

typescript
sampler.play() // plays sound 1
sampler.play() // plays sound 2
sampler.play(0.4) // plays sound 3 at 40% of the sampler's gain (then wraps to 1)

playAt() ​

playAt(time, velocity): void

Defined in: packages/core/src/sampler.ts:186

Play the next sound at a specific AudioContext time.

Parameters ​

time ​

number

The AudioContext.currentTime value when to play

velocity ​

number = 1

Gain multiplier (0–1) applied on top of the sampler's gain. Defaults to 1 (no attenuation).

Returns ​

void

Example ​

typescript
const startTime = audioContext.currentTime + 1
sampler.playAt(startTime) // plays next sound at exactly startTime
sampler.playAt(startTime, 0.8) // plays next sound at exactly startTime at 80% gain

playIn() ​

playIn(seconds, velocity): void

Defined in: packages/core/src/sampler.ts:169

Play the next sound in the rotation after a delay.

Parameters ​

seconds ​

number

Number of seconds from now to play the sound

velocity ​

number = 1

Gain multiplier (0–1) applied on top of the sampler's gain. Defaults to 1 (no attenuation).

Returns ​

void

Example ​

typescript
sampler.playIn(0.5) // plays next sound in 0.5 seconds
sampler.playIn(0.5, 0.6) // plays next sound in 0.5 seconds at 60% gain