Class: SampledNote

Defined in: packages/core/src/sampled-note.ts:30

A Sound with musical identity.

SampledNote extends Sound with musical properties (letter, accidental, octave, frequency) via the MusicallyAware mixin. Used in Font collections where each sound represents a specific musical note.

Example

typescript

import { createFont } from 'ez-web-audio'

// SampledNote is typically created via createFont(), not directly
const piano = await createFont('piano.js')
const noteA4 = piano.getNote('A4')

// Access musical properties
console.log(noteA4?.frequency)   // 440
console.log(noteA4?.identifier)  // "A4"
console.log(noteA4?.letter)      // "A"
console.log(noteA4?.octave)      // "4"

// Use Sound methods
noteA4?.changeGainTo(0.5)
noteA4?.play()

Extends

MusicalIdentity<typeof Sound, this> & Sound<BaseSoundEventMap, this>

Indexable

[key: string]: any

Constructors

Constructor

new SampledNote(audioContext, audioBuffer, opts?): SampledNote

Defined in: packages/core/src/sound.ts:87

Create a Sound instance.

Note: Use createSound factory function instead of calling this directly.

Parameters

audioContext

AudioContext

The AudioContext to use for audio operations

audioBuffer

AudioBuffer

The decoded audio data to play

opts?

BaseSoundOptions

Optional configuration (name, setTimeout override)

Returns

SampledNote

Inherited from

MusicallyAware(Sound).constructor

Properties

_analyzer

protected _analyzer: Analyzer | null = null

Defined in: packages/core/src/base-sound.ts:161

Inherited from

MusicallyAware(Sound)._analyzer

_destination

protected _destination: AudioNode

Defined in: packages/core/src/base-sound.ts:154

Inherited from

MusicallyAware(Sound)._destination

_isPlaying

protected _isPlaying: boolean = false

Defined in: packages/core/src/base-sound.ts:84

Inherited from

MusicallyAware(Sound)._isPlaying

_targetGain

protected _targetGain: number = 1

Defined in: packages/core/src/base-sound.ts:107

The user's intended gain level (0–1). Tracks the last value set via changeGainTo() / volume setter so that gain can be restored after a fadeOut() or Oscillator anti-click stop that ramps gainNode.gain to 0.

Inherited from

MusicallyAware(Sound)._targetGain

accidental

accidental: Accidental = ''

Defined in: packages/core/src/musical-identity.ts:110

The accidental: "" (natural), "b" (flat), or "#" (sharp). For note "Ab5", this would be "b".

Inherited from

MusicallyAware(Sound).accidental

audioBuffer

readonly audioBuffer: AudioBuffer

Defined in: packages/core/src/sound.ts:87

The decoded audio data to play

Inherited from

MusicallyAware(Sound).audioBuffer

audioContext

readonly audioContext: AudioContext

Defined in: packages/core/src/base-sound.ts:218

Inherited from

MusicallyAware(Sound).audioContext

audioSourceNode

audioSourceNode: AudioBufferSourceNode

Defined in: packages/core/src/sound.ts:36

The underlying AudioBufferSourceNode that plays the audio.

Inherited from

MusicallyAware(Sound).audioSourceNode

clearTimeout()

protected clearTimeout: (id) => void

Defined in: packages/core/src/base-sound.ts:97

Parameters

id

number

Returns

void

Inherited from

MusicallyAware(Sound).clearTimeout

controller

protected controller: SoundController

Defined in: packages/core/src/sound.ts:39

Controller for managing gain, pan, and other audio parameters.

Inherited from

MusicallyAware(Sound).controller

debug?

optional debug: boolean

Defined in: packages/core/src/base-sound.ts:216

Default

undefined (follows global debug mode)

Example

sound.debug = true  // enable debug for this sound
sound.debug = false // silence this sound even when global debug is on

Inherited from

MusicallyAware(Sound).debug

effectChainInput

protected effectChainInput: GainNode

Defined in: packages/core/src/base-sound.ts:147

Inherited from

MusicallyAware(Sound).effectChainInput

effects

protected effects: Effect[] = []

Defined in: packages/core/src/base-sound.ts:140

Inherited from

MusicallyAware(Sound).effects

gainNode

protected gainNode: GainNode

Defined in: packages/core/src/base-sound.ts:93

The GainNode controlling this sound's volume.

For simple volume control, use changeGainTo() or update('gain'). For advanced routing, use getGainNode().

Inherited from

MusicallyAware(Sound).gainNode

letter

letter: NoteLetter = 'A'

Defined in: packages/core/src/musical-identity.ts:104

The note letter (A-G). For note "Ab5", this would be "A".

Inherited from

MusicallyAware(Sound).letter

name

name: string

Defined in: packages/core/src/musical-identity.ts:121

Inherited from

Note.name

octave

octave: Octave = '0'

Defined in: packages/core/src/musical-identity.ts:115

The octave (0-8). For note "Ab5", this would be "5".

Inherited from

MusicallyAware(Sound).octave

pannerNode

protected pannerNode: StereoPannerNode

Defined in: packages/core/src/base-sound.ts:95

Inherited from

MusicallyAware(Sound).pannerNode

setTimeout()

protected setTimeout: (fn, delayMillis) => number

Defined in: packages/core/src/base-sound.ts:96

Parameters

fn

() => void

delayMillis

number

Returns

number

Inherited from

MusicallyAware(Sound).setTimeout

startedPlayingAt

protected startedPlayingAt: number = 0

Defined in: packages/core/src/base-sound.ts:99

Inherited from

MusicallyAware(Sound).startedPlayingAt

startOffset

protected startOffset: number = 0

Defined in: packages/core/src/base-sound.ts:170

Offset in seconds from the beginning of the audio buffer where playback starts. Used internally by Track for seek/resume functionality.

Default

See

https://developer.mozilla.org/en-US/docs/Web/API/AudioScheduledSourceNode/start

Inherited from

MusicallyAware(Sound).startOffset

Accessors

_isLooping

Get Signature

get protected _isLooping(): boolean

Defined in: packages/core/src/sound.ts:74

Returns whether this sound is set to loop. Used by BaseSound.playAt() to skip the duration timeout when looping is enabled.

Returns

boolean

Inherited from

MusicallyAware(Sound)._isLooping

disposed

Get Signature

get disposed(): boolean

Defined in: packages/core/src/base-sound.ts:1174

Whether this instance has been disposed.

Once disposed, the instance cannot be used for playback. Create a new instance if you need to play the sound again.

Example

typescript

sound.dispose()
console.log(sound.disposed) // true

Returns

boolean

Inherited from

MusicallyAware(Sound).disposed

duration

Get Signature

get duration(): TimeObject

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

Get the duration of the audio buffer.

Returns a TimeObject with the duration in multiple formats:

raw: Duration in seconds
string: Formatted as 'MM:SS'
pojo: Object with minutes and seconds properties

Example

typescript

const sound = await createSound('song.mp3')
console.log(sound.duration.raw)    // 180.5
console.log(sound.duration.string) // '3:00'
console.log(sound.duration.pojo)   // { minutes: 3, seconds: 0 }

Returns

TimeObject

Inherited from

MusicallyAware(Sound).duration

durationRaw

Get Signature

get durationRaw(): number

Defined in: packages/core/src/sound.ts:187

Get the duration of the audio buffer in seconds.

Use this instead of duration.raw in performance-sensitive code paths to avoid allocating a TimeObject.

Returns

number

Inherited from

MusicallyAware(Sound).durationRaw

frequency

Get Signature

get frequency(): number

Defined in: packages/core/src/musical-identity.ts:144

The frequency of the note in hertz.

Computed from the note identifier using standard piano frequencies. Setting this value updates all other properties to match.

Example

typescript

note.frequency = 440 // Sets to A4
console.log(note.identifier) // "A4"

Returns

number

Set Signature

set frequency(value): void

Defined in: packages/core/src/musical-identity.ts:159

Setting frequency resolves to the nearest tabled note within FREQUENCY_MATCH_TOLERANCE_CENTS cents (a computed/synthesized frequency rarely lands on an exact table value). If nothing is close enough, a warning is logged and the identifier is left unchanged rather than silently going stale.

Parameters

value

number

Returns

void

Inherited from

MusicallyAware(Sound).frequency

identifier

Get Signature

get identifier(): "C0" | "Db0" | "C#0" | "D0" | "Eb0" | "D#0" | "E0" | "F0" | "Gb0" | "F#0" | "G0" | "Ab0" | "G#0" | "A0" | "Bb0" | "A#0" | "B0" | "C1" | "Db1" | "C#1" | "D1" | "Eb1" | "D#1" | "E1" | "F1" | "Gb1" | "F#1" | "G1" | "Ab1" | "G#1" | "A1" | "Bb1" | "A#1" | "B1" | "C2" | "Db2" | "C#2" | "D2" | "Eb2" | "D#2" | "E2" | "F2" | "Gb2" | "F#2" | "G2" | "Ab2" | "G#2" | "A2" | "Bb2" | "A#2" | "B2" | "C3" | "Db3" | "C#3" | "D3" | "Eb3" | "D#3" | "E3" | "F3" | "Gb3" | "F#3" | "G3" | "Ab3" | "G#3" | "A3" | "Bb3" | "A#3" | "B3" | "C4" | "Db4" | "C#4" | "D4" | "Eb4" | "D#4" | "E4" | "F4" | "Gb4" | "F#4" | "G4" | "Ab4" | "G#4" | "A4" | "Bb4" | "A#4" | "B4" | "C5" | "Db5" | "C#5" | "D5" | "Eb5" | "D#5" | "E5" | "F5" | "Gb5" | "F#5" | "G5" | "Ab5" | "G#5" | "A5" | "Bb5" | "A#5" | "B5" | "C6" | "Db6" | "C#6" | "D6" | "Eb6" | "D#6" | "E6" | "F6" | "Gb6" | "F#6" | "G6" | "Ab6" | "G#6" | "A6" | "Bb6" | "A#6" | "B6" | "C7" | "Db7" | "C#7" | "D7" | "Eb7" | "D#7" | "E7" | "F7" | "Gb7" | "F#7" | "G7" | "Ab7" | "G#7" | "A7" | "Bb7" | "A#7" | "B7" | "C8" | "Db8" | "C#8" | "D8" | "Eb8" | "D#8"

Defined in: packages/core/src/musical-identity.ts:210

The full note identifier (e.g., "A4", "Bb3", "C#5").

Computed from letter, accidental, and octave. Setting this value updates all other properties to match.

Example

typescript

note.identifier = 'Bb3'
console.log(note.letter)     // "B"
console.log(note.accidental) // "b"
console.log(note.octave)     // "3"
console.log(note.frequency)  // 233.08

Returns

"C0" | "Db0" | "C#0" | "D0" | "Eb0" | "D#0" | "E0" | "F0" | "Gb0" | "F#0" | "G0" | "Ab0" | "G#0" | "A0" | "Bb0" | "A#0" | "B0" | "C1" | "Db1" | "C#1" | "D1" | "Eb1" | "D#1" | "E1" | "F1" | "Gb1" | "F#1" | "G1" | "Ab1" | "G#1" | "A1" | "Bb1" | "A#1" | "B1" | "C2" | "Db2" | "C#2" | "D2" | "Eb2" | "D#2" | "E2" | "F2" | "Gb2" | "F#2" | "G2" | "Ab2" | "G#2" | "A2" | "Bb2" | "A#2" | "B2" | "C3" | "Db3" | "C#3" | "D3" | "Eb3" | "D#3" | "E3" | "F3" | "Gb3" | "F#3" | "G3" | "Ab3" | "G#3" | "A3" | "Bb3" | "A#3" | "B3" | "C4" | "Db4" | "C#4" | "D4" | "Eb4" | "D#4" | "E4" | "F4" | "Gb4" | "F#4" | "G4" | "Ab4" | "G#4" | "A4" | "Bb4" | "A#4" | "B4" | "C5" | "Db5" | "C#5" | "D5" | "Eb5" | "D#5" | "E5" | "F5" | "Gb5" | "F#5" | "G5" | "Ab5" | "G#5" | "A5" | "Bb5" | "A#5" | "B5" | "C6" | "Db6" | "C#6" | "D6" | "Eb6" | "D#6" | "E6" | "F6" | "Gb6" | "F#6" | "G6" | "Ab6" | "G#6" | "A6" | "Bb6" | "A#6" | "B6" | "C7" | "Db7" | "C#7" | "D7" | "Eb7" | "D#7" | "E7" | "F7" | "Gb7" | "F#7" | "G7" | "Ab7" | "G#7" | "A7" | "Bb7" | "A#7" | "B7" | "C8" | "Db8" | "C#8" | "D8" | "Eb8" | "D#8"

Set Signature

set identifier(value): void

Defined in: packages/core/src/musical-identity.ts:232

Parameters

value

Returns

void

Inherited from

MusicallyAware(Sound).identifier

isPlaying

Get Signature

get isPlaying(): boolean

Defined in: packages/core/src/base-sound.ts:1115

Whether the sound is currently playing.

Example

typescript

if (sound.isPlaying) {
  await sound.stop()
}

Returns

boolean

Inherited from

MusicallyAware(Sound).isPlaying

loop

Get Signature

get loop(): boolean

Defined in: packages/core/src/sound.ts:61

Enable or disable native looping for this sound.

When loop is true, the audio replays from the beginning when it reaches the end, providing gapless looping via the native AudioBufferSourceNode.loop property. Call stop() to end looped playback.

Example

typescript

const sfx = await createSound('rain.mp3')
sfx.loop = true
sfx.play() // plays continuously until stop()

// Stop looped playback
await sfx.stop()

Returns

boolean

Set Signature

set loop(value): void

Defined in: packages/core/src/sound.ts:65

Parameters

value

boolean

Returns

void

Inherited from

MusicallyAware(Sound).loop

percentGain

Get Signature

get percentGain(): number

Defined in: packages/core/src/base-sound.ts:1127

Current gain as a percentage (0-100).

Example

typescript

console.log(`Volume: ${sound.percentGain}%`) // "Volume: 50%"

Returns

number

Inherited from

MusicallyAware(Sound).percentGain

volume

Get Signature

get volume(): number

Defined in: packages/core/src/base-sound.ts:1150

Alias for gain. Get/set the volume (0 = silent, 1 = full volume).

Values above 1 amplify the signal and may cause distortion. The setter delegates to changeGainTo(), which throws if the value is negative and warns if it exceeds 1.

Inherited by Sound, Track, and Oscillator.

Example

typescript

sound.volume = 0.5  // set to half volume
console.log(sound.volume) // 0.5

// Works on all BaseSound subclasses
const osc = await createOscillator()
osc.volume = 0.8

Returns

number

Set Signature

set volume(value): void

Defined in: packages/core/src/base-sound.ts:1154

Parameters

value

number

Returns

void

Inherited from

MusicallyAware(Sound).volume

Methods

_clearListeners()

protected _clearListeners(): void

Defined in: packages/core/src/events/typed-event-emitter.ts:192

Remove every listener registered through this emitter (via addEventListener(), on(), or once()), regardless of how many or what event type they're bound to.

Native EventTarget has no removeAllListeners(). This works around that by aborting a shared AbortSignal threaded through every addEventListener() call this class makes, then swapping in a fresh AbortController so the instance can keep accepting new listeners afterward (e.g. if it's reused before being garbage collected).

Subclasses call this from their dispose() alongside neutering dispatchEvent — the neuter stops future emits, this stops stale listener closures from being retained/invoked at all.

Returns

void

Inherited from

MusicallyAware(Sound)._clearListeners

_onPlaybackStarted()

protected _onPlaybackStarted(): void

Defined in: packages/core/src/sampled-note.ts:46

Schedule a short gain fade that lands just before the buffer runs out.

Soundfont samples are often trimmed hard at the end; without this, a note that plays to its natural end truncates audibly. Skipped for very short buffers (percussive one-shots) where a 150ms fade would eat the sound.

Returns

void

Overrides

MusicallyAware(Sound)._onPlaybackStarted

addEffect()

addEffect(effect, position?): this

Defined in: packages/core/src/base-sound.ts:401

Add an effect to the effect chain. Effects persist across multiple play() calls.

Parameters

effect

Effect

The Effect instance to add

position?

number

Optional index to insert at (defaults to end of chain)

Returns

this

this for chaining

Example

const filter = createFilterEffect('lowpass', { frequency: 1000 })
sound.addEffect(filter)

Inherited from

MusicallyAware(Sound).addEffect

addEffects()

addEffects(effects, position?): this

Defined in: packages/core/src/base-sound.ts:471

Add multiple effects to the effect chain in one call. The chain is rewired only once after all effects are added, which is more efficient than calling addEffect() multiple times.

Parameters

effects

Effect[]

Array of Effect instances to add

position?

number

Optional index to insert at (defaults to end of chain)

Returns

this

this for chaining

Example

typescript

const filter = createFilterEffect('lowpass', { frequency: 800 })
const boost = createGainEffect(1.5)
sound.addEffects([filter, boost])

Inherited from

MusicallyAware(Sound).addEffects

addEventListener()

Call Signature

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

Defined in: packages/core/src/events/typed-event-emitter.ts:44

Add a typed event listener for known event types. Overloaded to provide type safety for known event types while remaining compatible with the native EventTarget API.

Type Parameters

K

K extends "play" | "dispose" | "stop" | "end"

Parameters

type

K

The event type (key of TMap)

listener

(event) => void

Typed event handler

options?

Standard addEventListener options

boolean | AddEventListenerOptions

Returns

void

Inherited from

MusicallyAware(Sound).addEventListener

Call Signature

addEventListener(type, listener, options?): void

Defined in: packages/core/src/events/typed-event-emitter.ts:49

Add a typed event listener for known event types. Overloaded to provide type safety for known event types while remaining compatible with the native EventTarget API.

Parameters

type

string

The event type (key of TMap)

listener

Typed event handler

EventListenerOrEventListenerObject | null

options?

Standard addEventListener options

boolean | AddEventListenerOptions

Returns

void

Inherited from

MusicallyAware(Sound).addEventListener

changeGainTo()

changeGainTo(value): this

Defined in: packages/core/src/base-sound.ts:693

Set the gain (volume) immediately.

Convenience method for update('gain').to(value).as('ratio').

Parameters

value

number

Gain from 0 (silent) to 1 (full volume)

Returns

this

this for chaining

Example

typescript

sound.changeGainTo(0.5)  // Half volume
sound.changeGainTo(0)    // Muted
sound.changeGainTo(1)    // Full volume

Inherited from

MusicallyAware(Sound).changeGainTo

changePanTo()

changePanTo(value): this

Defined in: packages/core/src/base-sound.ts:670

Set the pan position immediately.

Convenience method for update('pan').to(value).as('ratio').

Parameters

value

number

Pan position from -1 (left) to 1 (right), 0 is center

Returns

this

this for chaining

Example

typescript

sound.changePanTo(-1)  // Hard left
sound.changePanTo(0)   // Center
sound.changePanTo(1)   // Hard right

Inherited from

MusicallyAware(Sound).changePanTo

dispose()

dispose(): void

Defined in: packages/core/src/base-sound.ts:1270

Dispose this sound instance, releasing all audio resources.

Disconnects all audio nodes, clears the effect chain, cancels pending timeouts, and marks the instance as unusable. After disposing, calling play() will throw an error.

Dispose is idempotent — calling it multiple times is safe.

After disposal, event listeners registered via on() / addEventListener() will no longer fire. To free listener references for garbage collection, call off() for each listener before calling dispose().

Returns

void

Example

typescript

const sound = await createSound('click.mp3')
await sound.play()

// When done with the sound
sound.dispose()
console.log(sound.disposed) // true

// Attempting to play after dispose will throw
// sound.play() // throws Error: Cannot play a disposed sound

Inherited from

MusicallyAware(Sound).dispose

emit()

protected emit<K>(type, detail): void

Defined in: packages/core/src/events/typed-event-emitter.ts:95

Emit a typed event with the given detail.

Creates a CustomEvent with the provided detail and dispatches it on this target. Subclasses call this internally to fire lifecycle events.

Type Parameters

K

K extends "play" | "dispose" | "stop" | "end"

Parameters

type

K

The event type to emit (key of TMap)

detail

BaseSoundEventMap[K]["detail"]

The event detail object (typed by TMap)

Returns

void

Inherited from

MusicallyAware(Sound).emit

fadeIn()

fadeIn(duration): Promise<void>

Defined in: packages/core/src/base-sound.ts:1202

Fade in the sound from silence to its current gain over duration seconds, then play.

Schedules a gain ramp from 0 to the current gain value and calls play(). The current gain is restored after playback — use changeGainTo() to set a target volume before calling fadeIn().

Parameters

duration

number

Fade-in duration in seconds

Returns

Promise<void>

Promise that resolves when playback begins

Example

typescript

const sound = await createSound('music.mp3')
await sound.fadeIn(2) // fade in over 2 seconds

Inherited from

MusicallyAware(Sound).fadeIn

fadeOut()

fadeOut(duration): Promise<void>

Defined in: packages/core/src/base-sound.ts:1225

Fade out the sound from its current gain to silence over duration seconds, then stop.

If the sound is not playing, this is a no-op. Returns a Promise that resolves after the fade completes and stop() has been called.

Parameters

duration

number

Fade-out duration in seconds

Returns

Promise<void>

Promise that resolves when the fade and stop are complete

Example

typescript

const sound = await createSound('music.mp3')
await sound.play()
await sound.fadeOut(2) // fade out over 2 seconds then stop

Inherited from

MusicallyAware(Sound).fadeOut

getAnalyzer()

getAnalyzer(): Analyzer | null

Defined in: packages/core/src/base-sound.ts:578

Get the currently attached analyzer, if any.

Returns

Analyzer | null

The attached Analyzer instance, or null if none attached

Inherited from

MusicallyAware(Sound).getAnalyzer

getEffects()

getEffects(): readonly Effect[]

Defined in: packages/core/src/base-sound.ts:514

Get a readonly copy of the current effects array.

Returns

readonly Effect[]

Shallow copy of the effects array

Inherited from

MusicallyAware(Sound).getEffects

getGainNode()

getGainNode(): GainNode

Defined in: packages/core/src/base-sound.ts:597

Get the GainNode for this sound.

Provides controlled access to the underlying GainNode for advanced audio routing scenarios (e.g., crossfading between tracks). For simple volume control, use changeGainTo() or update('gain').

Returns

GainNode

The GainNode controlling this sound's volume

Example

typescript

const node = sound.getGainNode()
node.gain.linearRampToValueAtTime(0, ctx.currentTime + 2)

Inherited from

MusicallyAware(Sound).getGainNode

getPannerNode()

getPannerNode(): StereoPannerNode

Defined in: packages/core/src/base-sound.ts:610

Get the StereoPannerNode for this sound.

Provides controlled access to the underlying StereoPannerNode for advanced audio routing scenarios (e.g., LFO modulation of pan position). For simple pan control, use changePanTo() or update('pan').

Returns

StereoPannerNode

The StereoPannerNode controlling this sound's pan position

Inherited from

MusicallyAware(Sound).getPannerNode

later()

protected later(fn): void

Defined in: packages/core/src/base-sound.ts:1158

Parameters

fn

() => void

Returns

void

Inherited from

MusicallyAware(Sound).later

off()

off<K>(type, listener): this

Defined in: packages/core/src/events/typed-event-emitter.ts:167

Unsubscribe from an event.

Note: Due to native EventTarget limitations, you must provide the same listener function reference that was used when subscribing.

Type Parameters

K

K extends "play" | "dispose" | "stop" | "end"

Parameters

type

K

The event type to unsubscribe from

listener

(event) => void

The event handler function to remove

Returns

this

this for chaining

Example

typescript

const handler = (e) => console.log(e.detail)
emitter.on('play', handler)
// later...
emitter.off('play', handler)

Inherited from

MusicallyAware(Sound).off

on()

on<K>(type, listener): this

Defined in: packages/core/src/events/typed-event-emitter.ts:116

Subscribe to one or more events. Supports chaining.

Type Parameters

K

K extends "play" | "dispose" | "stop" | "end"

Parameters

type

The event type(s) to subscribe to (key or array of keys of TMap)

K | K[]

listener

(event) => void

The event handler function

Returns

this

this for chaining

Example

typescript

emitter.on('play', handlePlay).on('stop', handleStop)
emitter.on(['play', 'stop'], handleBoth)

Inherited from

MusicallyAware(Sound).on

once()

once<K>(type, listener): this

Defined in: packages/core/src/events/typed-event-emitter.ts:141

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

Type Parameters

K

K extends "play" | "dispose" | "stop" | "end"

Parameters

type

K

The event type to subscribe to

listener

(event) => void

The event handler function

Returns

this

this for chaining

Example

typescript

emitter.once('end', () => console.log('Finished'))

Inherited from

MusicallyAware(Sound).once

onPlayRamp()

onPlayRamp(type, rampType?): object

Defined in: packages/core/src/base-sound.ts:794

Schedule a parameter ramp when play() is called.

Use this for smooth transitions like vibrato, tremolo, or automation.

Parameters

type

SoundControlType

The parameter to ramp ('gain' or 'pan')

rampType?

RampType

Type of ramp curve ('linear' or 'exponential')

Returns

object

Fluent builder for setting start value, end value, and duration

from()

from: (startValue) => object

Parameters

startValue

number

Returns

object

to()

to: (endValue) => object

Parameters

endValue

number

Returns

object

in()

in: (endTime) => void

Parameters

endTime

number

Returns

void

Remarks

Important: Schedules are consumed after each play() call. The ramp set via onPlayRamp() is applied once when play() runs, then cleared. If you need the same ramp on every play, call onPlayRamp() again before each play() call.

typescript

// This fade-out only applies to the FIRST play:
sound.onPlayRamp('gain', 'linear').from(1).to(0).in(2)
sound.play() // fades out over 2 seconds
sound.play() // no fade — schedule was consumed

// To repeat, re-schedule before each play:
function playWithFadeOut() {
  sound.onPlayRamp('gain', 'linear').from(1).to(0).in(2)
  sound.play()
}

Example

typescript

// Fade out over 2 seconds
sound.onPlayRamp('gain', 'linear').from(1).to(0).in(2)
sound.play()

// Pan sweep from left to right over 4 seconds
sound.onPlayRamp('pan', 'linear').from(-1).to(1).in(4)
sound.play()

Inherited from

MusicallyAware(Sound).onPlayRamp

onPlaySet()

onPlaySet(type): object

Defined in: packages/core/src/base-sound.ts:746

Schedule a parameter value to be set when play() is called.

Use this for fade-ins, fade-outs, or precise parameter timing. The value is applied relative to when play() is called.

Parameters

type

SoundControlType

The parameter to control ('gain' or 'pan')

Returns

object

Fluent builder for setting value and timing

to()

to: (value) => object

Parameters

value

number

Returns

object

at()

at: (time) => void

Parameters

time

number

Returns

void

endingAt()

endingAt: (time, rampType?) => void

Parameters

time

number

rampType?

RampType

Returns

void

Remarks

Important: Schedules are consumed after each play() call. The values set via onPlaySet() are applied once when play() runs, then cleared. If you need the same schedule on every play, call onPlaySet() again before each play() call.

typescript

// This fade-in only applies to the FIRST play:
sound.onPlaySet('gain').to(0).at(0)
sound.onPlaySet('gain').to(1).endingAt(0.5, 'linear')
sound.play() // fades in
sound.play() // no fade — schedule was consumed

// To repeat the schedule, re-call onPlaySet() before each play():
function playWithFadeIn() {
  sound.onPlaySet('gain').to(0).at(0)
  sound.onPlaySet('gain').to(1).endingAt(0.5, 'linear')
  sound.play()
}

Example

typescript

// Fade in: start at 0, ramp to 1 over 0.5 seconds
sound.onPlaySet('gain').to(0).at(0)
sound.onPlaySet('gain').to(1).endingAt(0.5, 'linear')
sound.play()

// Start panned left, move to center over 2 seconds
sound.onPlaySet('pan').to(-1).at(0)
sound.onPlaySet('pan').to(0).endingAt(2, 'linear')
sound.play()

Inherited from

MusicallyAware(Sound).onPlaySet

play()

play(): Promise<void>

Defined in: packages/core/src/base-sound.ts:819

Play the sound immediately.

Resumes the AudioContext if suspended, sets up the audio source, and starts playback. For finite-duration sounds (Sound, Track), automatically schedules an 'end' event when playback completes.

Returns

Promise<void>

Promise that resolves when playback begins

Example

typescript

const sound = await createSound('click.mp3')
await sound.play()

Inherited from

MusicallyAware(Sound).play

playAt()

playAt(time): Promise<void>

Defined in: packages/core/src/base-sound.ts:895

Play the audio source at a specific time.

This is the underlying method for all play variants. Time is measured in seconds from when the AudioContext was created (audioContext.currentTime).

Parameters

time

number

The AudioContext time when playback should start

Returns

Promise<void>

Example

typescript

// Play immediately
sound.playAt(audioContext.currentTime)

// Play in 2 seconds
sound.playAt(audioContext.currentTime + 2)

// Sync multiple sounds
const startTime = audioContext.currentTime + 0.1
sound1.playAt(startTime)
sound2.playAt(startTime)

Inherited from

MusicallyAware(Sound).playAt

playFor()

playFor(duration): void

Defined in: packages/core/src/base-sound.ts:849

Play for a specific duration, then stop automatically.

Parameters

duration

number

Seconds of playback before stopping

Returns

void

Example

typescript

// Play for 3 seconds
sound.playFor(3)

Inherited from

MusicallyAware(Sound).playFor

playIn()

playIn(when): void

Defined in: packages/core/src/base-sound.ts:834

Schedule playback after a delay.

Parameters

when

number

Seconds from now until playback starts

Returns

void

Example

typescript

// Play in 2 seconds
sound.playIn(2)

Inherited from

MusicallyAware(Sound).playIn

playInAndStopAfter()

playInAndStopAfter(playIn, stopAfter): void

Defined in: packages/core/src/base-sound.ts:868

Play after a delay, then stop after a duration.

Combines playIn() and stopIn() for precise timed playback.

Parameters

playIn

number

Seconds from now until playback starts

stopAfter

number

Seconds of playback before stopping (from play start)

Returns

void

Example

typescript

// Start in 1 second, play for 3 seconds
sound.playInAndStopAfter(1, 3)

Inherited from

MusicallyAware(Sound).playInAndStopAfter

removeEffect()

removeEffect(effect): this

Defined in: packages/core/src/base-sound.ts:435

Remove an effect from the effect chain.

Parameters

effect

Effect

The Effect instance to remove

Returns

this

this for chaining

Example

sound.removeEffect(filter)

Inherited from

MusicallyAware(Sound).removeEffect

removeEventListener()

Call Signature

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

Defined in: packages/core/src/events/typed-event-emitter.ts:70

Remove a typed event listener for known event types. Overloaded to provide type safety for known event types while remaining compatible with the native EventTarget API.

Type Parameters

K

K extends "play" | "dispose" | "stop" | "end"

Parameters

type

K

The event type (key of TMap)

listener

(event) => void

Typed event handler to remove

options?

Standard removeEventListener options

boolean | EventListenerOptions

Returns

void

Inherited from

MusicallyAware(Sound).removeEventListener

Call Signature

removeEventListener(type, listener, options?): void

Defined in: packages/core/src/events/typed-event-emitter.ts:75

Remove a typed event listener for known event types. Overloaded to provide type safety for known event types while remaining compatible with the native EventTarget API.

Parameters

type

string

The event type (key of TMap)

listener

Typed event handler to remove

EventListenerOrEventListenerObject | null

options?

Standard removeEventListener options

boolean | EventListenerOptions

Returns

void

Inherited from

MusicallyAware(Sound).removeEventListener

rewireEffects()

rewireEffects(): void

Defined in: packages/core/src/base-sound.ts:540

Re-wire the effect chain. Call this after toggling effect.bypass to update the audio routing.

Returns

void

Inherited from

MusicallyAware(Sound).rewireEffects

setAnalyzer()

setAnalyzer(analyzer): this

Defined in: packages/core/src/base-sound.ts:567

Attach an analyzer to this sound for visualization. The analyzer is inserted at the end of the signal chain (after effects and panner, before destination), showing the fully processed signal.

The analyzer is a passthrough node - audio flows through it unchanged while providing frequency and waveform data for visualization.

Parameters

analyzer

The Analyzer instance to attach, or null to detach

Analyzer | null

Returns

this

this for chaining

Example

const analyzer = createAnalyzer(audioContext, { fftSize: 2048 })
sound.setAnalyzer(analyzer)

function draw() {
  const freqData = analyzer.getFrequencyData()
  // Draw frequency bars
  requestAnimationFrame(draw)
}

Inherited from

MusicallyAware(Sound).setAnalyzer

setDestination()

setDestination(node): this

Defined in: packages/core/src/base-sound.ts:530

Set a custom destination for audio output instead of audioContext.destination. Useful for routing to sub-mixes, analyzers, or other processing chains.

Parameters

node

AudioNode

The AudioNode to route output to

Returns

this

this for chaining

Example

const analyzer = audioContext.createAnalyser()
analyzer.connect(audioContext.destination)
sound.setDestination(analyzer)

Inherited from

MusicallyAware(Sound).setDestination

setup()

protected setup(): void

Defined in: packages/core/src/sound.ts:103

Set up a new AudioBufferSourceNode for playback. Called automatically before each play() - creates fresh source nodes since AudioBufferSourceNode is single-use.

Returns

void

Inherited from

MusicallyAware(Sound).setup

stop()

stop(): Promise<void>

Defined in: packages/core/src/base-sound.ts:1101

Stop the sound immediately.

Emits a 'stop' event. Safe to call when not playing (no-op).

Returns

Promise<void>

Promise that resolves when the stop is processed

Example

typescript

await sound.stop()

Inherited from

MusicallyAware(Sound).stop

stopAt()

stopAt(time): Promise<void>

Defined in: packages/core/src/base-sound.ts:1037

Stop the audio source at a specific time.

This is the underlying method for all stop variants. Time is measured in seconds from when the AudioContext was created (audioContext.currentTime).

Parameters

time

number

The AudioContext time when playback should stop

Returns

Promise<void>

Example

typescript

// Stop immediately
sound.stopAt(audioContext.currentTime)

// Stop in 5 seconds
sound.stopAt(audioContext.currentTime + 5)

Inherited from

MusicallyAware(Sound).stopAt

stopIn()

stopIn(seconds): Promise<void>

Defined in: packages/core/src/base-sound.ts:1016

Stop the audio source after a delay.

Parameters

seconds

number

Seconds from now until playback stops

Returns

Promise<void>

Example

typescript

sound.play()
// Stop after 5 seconds
sound.stopIn(5)

Inherited from

MusicallyAware(Sound).stopIn

update()

update(type): object

Defined in: packages/core/src/base-sound.ts:632

Update an audio parameter immediately.

Returns a fluent builder for setting the parameter value. Use .to(value) to set the value, then .as(unit) for unit interpretation.

Parameters

type

SoundControlType

The parameter to update ('gain' or 'pan')

Returns

object

Fluent builder for setting the value

to()

to: (value) => object

Parameters

value

number

Returns

object

as()

as: (method) => void

Parameters

method

RatioType

Returns

void

Example

typescript

// Set gain to 50%
sound.update('gain').to(0.5).as('ratio')

// Set pan to left
sound.update('pan').to(-1).as('ratio')

Inherited from

MusicallyAware(Sound).update

wireConnections()

protected wireConnections(): void

Defined in: packages/core/src/sound.ts:175

Wire audio source to the effect chain input.

Returns

void

Inherited from

MusicallyAware(Sound).wireConnections

Class: SampledNote ​

Example ​

Extends ​

Indexable ​

Constructors ​

Constructor ​

Parameters ​

audioContext ​

audioBuffer ​

opts? ​

Returns ​

Inherited from ​

Properties ​

_analyzer ​

Inherited from ​

_destination ​

Inherited from ​

_isPlaying ​

Inherited from ​

_targetGain ​

Inherited from ​

accidental ​

Inherited from ​

audioBuffer ​

Inherited from ​

audioContext ​

Inherited from ​

audioSourceNode ​

Inherited from ​

clearTimeout() ​

Parameters ​

id ​

Returns ​

Inherited from ​

controller ​

Inherited from ​

debug? ​

Default ​

Example ​

Inherited from ​

effectChainInput ​

Inherited from ​

effects ​

Inherited from ​

gainNode ​

Inherited from ​

letter ​

Inherited from ​

name ​

Inherited from ​

octave ​

Inherited from ​

pannerNode ​

Inherited from ​

setTimeout() ​

Parameters ​

fn ​

delayMillis ​

Returns ​

Inherited from ​

startedPlayingAt ​

Inherited from ​

startOffset ​

Default ​

See ​

Inherited from ​

Accessors ​

_isLooping ​

Get Signature ​

Returns ​

Inherited from ​

disposed ​

Get Signature ​

Example ​

Returns ​

Inherited from ​

duration ​

Get Signature ​

Example ​

Returns ​

Class: SampledNote

Example

Extends

Indexable

Constructors

Constructor

Parameters

audioContext

audioBuffer

opts?

Returns

Inherited from

Properties

_analyzer

Inherited from

_destination

Inherited from

_isPlaying

Inherited from

_targetGain

Inherited from

accidental

Inherited from

audioBuffer

Inherited from

audioContext

Inherited from

audioSourceNode

Inherited from

clearTimeout()

Parameters

id

Returns

Inherited from

controller

Inherited from

debug?

Default

Example

Inherited from

effectChainInput

Inherited from

effects

Inherited from

gainNode

Inherited from

letter

Inherited from

name

Inherited from

octave

Inherited from

pannerNode

Inherited from

setTimeout()

Parameters

fn

delayMillis

Returns

Inherited from

startedPlayingAt

Inherited from

startOffset

Default

See

Inherited from

Accessors

_isLooping

Get Signature

Returns

Inherited from

disposed

Get Signature

Example

Returns

Inherited from

duration

Get Signature

Example

Returns