EZ Web Audio

Appearance

EZ Web Audio / BeatTrack

Class: BeatTrack ​

Defined in: beat-track.ts:52

Drum machine lane with rhythmic beat patterns.

BeatTrack manages an array of Beat instances for creating drum patterns. It extends Sampler for round-robin sample variation and adds tempo-synced playback with beat events for visual synchronization.

Example ​

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

const kick = await createBeatTrack(['kick.mp3'], { numBeats: 8 })

// Set a basic 4-on-the-floor pattern
kick.beats[0].active = true  // beat 1
kick.beats[2].active = true  // beat 3
kick.beats[4].active = true  // beat 5
kick.beats[6].active = true  // beat 7

kick.playBeats(120, 1/4) // Play quarter notes at 120 BPM

// Listen for beat events
kick.on('beat', (e) => {
  console.log(`Beat ${e.detail.beatIndex}`)
})

Extends ​

Constructors ​

Constructor ​

new BeatTrack(audioContext, sounds, opts?): BeatTrack

Defined in: beat-track.ts:75

Parameters ​

audioContext ​

AudioContext

sounds ​

Playable & Connectable[]

opts? ​

BeatTrackOptions

Returns ​

BeatTrack

Overrides ​

Sampler.constructor

Properties ​

duration ​

duration: number = 100

Defined in: beat-track.ts:110

How long (in milliseconds) the isPlaying flag stays true after a beat plays. Useful for visual feedback in the UI.

Default ​

ts
100

gain ​

gain: number = 1

Defined in: sampler.ts:49

Gain level applied to each sample when played.

Default ​

ts
1

Inherited from ​

Sampler.gain

name ​

name: string

Defined in: sampler.ts:43

Optional name to aid in identification.

Inherited from ​

Sampler.name

numBeats ​

numBeats: number = 4

Defined in: beat-track.ts:103

Number of beats in this track.

Default ​

ts
4

pan ​

pan: number = 0

Defined in: sampler.ts:55

Stereo pan position applied to each sample (-1 = left, 0 = center, 1 = right).

Default ​

ts
0

Inherited from ​

Sampler.pan

Accessors ​

beats ​

Get Signature ​

get beats(): Beat[]

Defined in: beat-track.ts:130

Array of Beat instances in this track.

The array length always matches numBeats. Beats are reused when the count changes, preserving their active state.

Example ​
typescript
// Toggle individual beats
track.beats[0].active = true
track.beats[1].active = false

// Check all beat states
track.beats.forEach((beat, i) => {
  console.log(`Beat ${i}: ${beat.active ? 'on' : 'off'}`)
})
Returns ​

Beat[]

Methods ​

addEventListener() ​

addEventListener<K>(type, listener, options?): void

Defined in: beat-track.ts:413

Add a typed event listener for BeatTrack lifecycle events.

Type Parameters ​

K ​

K extends keyof BeatTrackEventMap

Parameters ​

type ​

K

Event type: 'beat', 'stop', 'pause', 'resume'

listener ​

(event) => void

Handler function

options? ​

Standard addEventListener options

boolean | AddEventListenerOptions

Returns ​

void

getSounds() ​

getSounds(): readonly Playable & Connectable[]

Defined in: sampler.ts:127

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

Inherited from ​

Sampler.getSounds

off() ​

off<K>(type, listener): this

Defined in: beat-track.ts:468

Unsubscribe from an event. Supports chaining.

Type Parameters ​

K ​

K extends keyof BeatTrackEventMap

Parameters ​

type ​

K

Event type to unsubscribe from

listener ​

(event) => void

Handler function to remove

Returns ​

this

this for chaining

on() ​

on<K>(type, listener): this

Defined in: beat-track.ts:453

Subscribe to an event. Supports chaining.

Type Parameters ​

K ​

K extends keyof BeatTrackEventMap

Parameters ​

type ​

K

Event type: 'beat', 'stop', 'pause', 'resume'

listener ​

(event) => void

Handler function

Returns ​

this

this for chaining

Example ​

typescript
track.on('beat', (e) => {
  console.log(`Beat ${e.detail.beatIndex}`)
  highlightBeat(e.detail.beatIndex)
}).on('stop', () => {
  console.log('Stopped')
})

once() ​

once<K>(type, listener): this

Defined in: beat-track.ts:490

Subscribe to an event once. Handler is removed after first invocation.

Type Parameters ​

K ​

K extends keyof BeatTrackEventMap

Parameters ​

type ​

K

Event type to listen for

listener ​

(event) => void

Handler function (called only once)

Returns ​

this

this for chaining

Example ​

typescript
track.once('stop', () => {
  console.log('Track stopped for the first time')
})

pause() ​

pause(): void

Defined in: beat-track.ts:251

Pause playback at the current position.

Emits a 'pause' event with the current beat index. Use resume() to continue from where you left off.

Returns ​

void

Example ​

typescript
track.pause()
// later...
track.resume()

play() ​

play(): void

Defined in: sampler.ts:79

Play the next sound in the rotation immediately.

Returns ​

void

Example ​

typescript
sampler.play() // plays sound 1
sampler.play() // plays sound 2
sampler.play() // plays sound 3 (then wraps to 1)

Inherited from ​

Sampler.play

playActiveBeats() ​

playActiveBeats(bpm, noteType): void

Defined in: beat-track.ts:196

Start playing only active beats in the pattern continuously.

Same as playBeats(), but only plays beats where active === true. Inactive beats become rests (silence), maintaining timing.

Parameters ​

bpm ​

number

Tempo in beats per minute

noteType ​

number

Rhythmic subdivision as a fraction. Common values: 1/4 (quarter notes), 1/8 (eighth notes), 1/16 (sixteenth notes). The beat duration in seconds is calculated as: (240 * noteType) / bpm.

Returns ​

void

Example ​

typescript
// Set up a pattern with rests
track.beats[0].active = true
track.beats[2].active = true
track.playActiveBeats(120, 1/4)  // Only beats 0 and 2 play

playAt() ​

playAt(time): void

Defined in: sampler.ts:108

Play the next sound at a specific AudioContext time.

Parameters ​

time ​

number

The AudioContext.currentTime value when to play

Returns ​

void

Example ​

typescript
const startTime = audioContext.currentTime + 1
sampler.playAt(startTime) // plays next sound at exactly startTime

Inherited from ​

Sampler.playAt

playBeats() ​

playBeats(bpm, noteType): void

Defined in: beat-track.ts:165

Start playing all beats in the pattern continuously.

Starts a lookahead scheduler that triggers beats at precise audio times. Emits 'beat' events for UI synchronization.

Parameters ​

bpm ​

number

Tempo in beats per minute

noteType ​

number

Rhythmic subdivision as a fraction. Common values: 1/4 (quarter notes), 1/8 (eighth notes), 1/16 (sixteenth notes). The beat duration in seconds is calculated as: (240 * noteType) / bpm.

Returns ​

void

Example ​

typescript
track.playBeats(120, 1/4)  // 120 BPM, quarter notes
track.playBeats(140, 1/8)  // 140 BPM, eighth notes

playIn() ​

playIn(seconds): void

Defined in: sampler.ts:93

Play the next sound in the rotation after a delay.

Parameters ​

seconds ​

number

Number of seconds from now to play the sound

Returns ​

void

Example ​

typescript
sampler.playIn(0.5) // plays next sound in 0.5 seconds

Inherited from ​

Sampler.playIn

removeEventListener() ​

removeEventListener<K>(type, listener, options?): void

Defined in: beat-track.ts:428

Remove a typed event listener.

Type Parameters ​

K ​

K extends keyof BeatTrackEventMap

Parameters ​

type ​

K

Event type to unsubscribe from

listener ​

(event) => void

Handler function to remove

options? ​

Standard removeEventListener options

boolean | EventListenerOptions

Returns ​

void

resume() ​

resume(): void

Defined in: beat-track.ts:280

Resume playback from where it was paused.

Emits a 'resume' event with the beat index where playback resumes. Has no effect if not paused.

Returns ​

void

Example ​

typescript
track.pause()
// ...user clicks play button...
track.resume() // continues from paused position

setTempo() ​

setTempo(bpm): void

Defined in: beat-track.ts:312

Change the tempo while playing.

The new tempo takes effect on the next scheduled beat.

Parameters ​

bpm ​

number

New tempo in beats per minute

Returns ​

void

Example ​

typescript
track.playBeats(120, 1/4)
// later, speed up...
track.setTempo(140)

stop() ​

stop(): void

Defined in: beat-track.ts:221

Stop playback and reset to the beginning.

Emits a 'stop' event. Use pause() instead if you want to resume later.

Returns ​

void

Example ​

typescript
track.stop()
track.on('stop', () => console.log('Stopped'))