EZ Web Audio / Oscillator

Class: Oscillator

Defined in: oscillator.ts:122

Synthesizer that generates audio from oscillator waveforms.

Oscillator creates sound from scratch using sine, square, sawtooth, or triangle waves. Supports ADSR envelopes for professional-quality synthesis, filters for tone shaping, and all the gain/pan controls from BaseSound.

Unlike Sound which plays pre-recorded audio, Oscillator generates audio in real-time. Oscillators have infinite duration and must be explicitly stopped.

Example

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

// Simple sine wave at 440Hz (A4)
const synth = await createOscillator({ frequency: 440, type: 'sine' })
synth.play()
setTimeout(() => synth.stop(), 500)

// With ADSR envelope for piano-like decay
const piano = await createOscillator({
  frequency: 440,
  type: 'triangle',
  envelope: { attack: 0.01, decay: 0.1, sustain: 0.7, release: 0.3 }
})
piano.play()
setTimeout(() => piano.stop(), 500) // Release phase plays after stop

// With lowpass filter
const muted = await createOscillator({
  frequency: 440,
  type: 'sawtooth',
  lowpass: { frequency: 800, q: 1 }
})
muted.play()

Extends

• BaseSound

Constructors

Constructor

new Oscillator(audioContext, options?): Oscillator

Defined in: oscillator.ts:149

Create an Oscillator instance.

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

Parameters

audioContext

AudioContext

The AudioContext to use for audio operations

options?

OscillatorOptions

Oscillator configuration (frequency, type, filters, envelope)

Returns

Oscillator

Overrides

BaseSound.constructor

Properties

_analyzer

protected _analyzer: Analyzer | null = null

Defined in: base-sound.ts:114

Inherited from

BaseSound._analyzer

---

_destination

protected _destination: AudioNode

Defined in: base-sound.ts:107

Inherited from

BaseSound._destination

---

_isPlaying

protected _isPlaying: boolean = false

Defined in: base-sound.ts:70

Inherited from

BaseSound._isPlaying

---

audioContext

audioContext: AudioContext

Defined in: base-sound.ts:165

Inherited from

BaseSound.audioContext

---

audioSourceNode

audioSourceNode: OscillatorNode

Defined in: oscillator.ts:124

The underlying OscillatorNode that generates the audio signal.

Overrides

BaseSound.audioSourceNode

---

controller

protected controller: OscillatorController

Defined in: oscillator.ts:136

Controller for managing gain, pan, frequency, and detune parameters.

Overrides

BaseSound.controller

---

debug?

optional debug: boolean

Defined in: base-sound.ts:163

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

BaseSound.debug

---

effectChainInput

protected effectChainInput: GainNode

Defined in: base-sound.ts:100

Inherited from

BaseSound.effectChainInput

---

effects

protected effects: Effect[] = []

Defined in: base-sound.ts:93

Inherited from

BaseSound.effects

---

freq

protected freq: number

Defined in: oscillator.ts:133

Base frequency in Hz.

---

gainNode

protected gainNode: GainNode

Defined in: base-sound.ts:78

The GainNode controlling this sound's volume.

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

Inherited from

BaseSound.gainNode

---

name

name: string

Defined in: base-sound.ts:149

Inherited from

BaseSound.name

---

pannerNode

protected pannerNode: StereoPannerNode

Defined in: base-sound.ts:80

Inherited from

BaseSound.pannerNode

---

setTimeout()

protected setTimeout: (fn, delayMillis) => number

Defined in: base-sound.ts:81

Parameters

fn

() => void

delayMillis

number

Returns

number

Inherited from

BaseSound.setTimeout

---

startedPlayingAt

protected startedPlayingAt: number = 0

Defined in: base-sound.ts:82

Inherited from

BaseSound.startedPlayingAt

---

startOffset

protected startOffset: number = 0

Defined in: base-sound.ts:123

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

Default

0

See

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

Inherited from

BaseSound.startOffset

Accessors

duration

Get Signature

get duration(): TimeObject

Defined in: oscillator.ts:323

Get the duration of the oscillator.

Oscillators have no inherent duration - they play indefinitely until stopped. Returns Infinity to indicate continuous playback, distinguishing from finite Sound/Track durations.

Example

const osc = await createOscillator({ frequency: 440 })
console.log(osc.duration.raw) // Infinity

// Oscillators must be explicitly stopped
osc.play()
setTimeout(() => osc.stop(), 1000)

Returns

TimeObject

Overrides

BaseSound.duration

---

isPlaying

Get Signature

get isPlaying(): boolean

Defined in: base-sound.ts:1082

Whether the sound is currently playing.

Example

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

Returns

boolean

Inherited from

BaseSound.isPlaying

---

percentGain

Get Signature

get percentGain(): number

Defined in: base-sound.ts:1094

Current gain as a percentage (0-100).

Example

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

Returns

number

Inherited from

BaseSound.percentGain

Methods

_onPlaybackStarted()

protected _onPlaybackStarted(): void

Defined in: base-sound.ts:986

Hook method called after playback starts. Override in subclasses to add behavior that runs for all play variants.

Returns

void

Inherited from

BaseSound._onPlaybackStarted

---

addEffect()

addEffect(effect, position?): this

Defined in: base-sound.ts:344

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(audioContext, 'lowpass', { frequency: 1000 })
sound.addEffect(filter)

Inherited from

BaseSound.addEffect

---

addEffects()

addEffects(effects, position?): this

Defined in: base-sound.ts:414

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

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

Inherited from

BaseSound.addEffects

---

addEventListener()

Call Signature

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

Defined in: base-sound.ts:555

Add a typed event listener for sound lifecycle events. Overloaded to provide type safety for known event types while remaining compatible with EventTarget.

Type Parameters

K

K extends keyof SoundEventMap

Parameters

type

K

The event type ('play', 'stop', 'end', etc.)

listener

(event) => void

The event handler function

options?

Standard addEventListener options

boolean | AddEventListenerOptions

Returns

void

Inherited from

BaseSound.addEventListener

Call Signature

addEventListener(type, listener, options?): void

Defined in: base-sound.ts:560

Add a typed event listener for sound lifecycle events. Overloaded to provide type safety for known event types while remaining compatible with EventTarget.

Parameters

type

string

The event type ('play', 'stop', 'end', etc.)

listener

The event handler function

EventListenerOrEventListenerObject | null

options?

Standard addEventListener options

boolean | AddEventListenerOptions

Returns

void

Inherited from

BaseSound.addEventListener

---

changeGainTo()

changeGainTo(value): this

Defined in: base-sound.ts:750

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

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

Inherited from

BaseSound.changeGainTo

---

changePanTo()

changePanTo(value): this

Defined in: base-sound.ts:730

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

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

Inherited from

BaseSound.changePanTo

---

emit()

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

Defined in: base-sound.ts:606

Emit a typed event with the given detail.

Type Parameters

K

K extends keyof SoundEventMap

Parameters

type

K

The event type to emit

detail

SoundEventMap[K]["detail"]

The event detail object

Returns

void

Inherited from

BaseSound.emit

---

getAnalyzer()

getAnalyzer(): Analyzer | null

Defined in: base-sound.ts:521

Get the currently attached analyzer, if any.

Returns

Analyzer | null

The attached Analyzer instance, or null if none attached

Inherited from

BaseSound.getAnalyzer

---

getEffects()

getEffects(): readonly Effect[]

Defined in: base-sound.ts:457

Get a readonly copy of the current effects array.

Returns

readonly Effect[]

Shallow copy of the effects array

Inherited from

BaseSound.getEffects

---

getFilters()

getFilters(): readonly BiquadFilterNode[]

Defined in: oscillator.ts:302

Get a readonly snapshot of the oscillator's filter nodes.

Returns a shallow copy of the internal filters array so callers can inspect filter state (type, frequency, Q) without mutating the chain.

Returns

readonly BiquadFilterNode[]

Readonly array of BiquadFilterNode instances

Example

const osc = await createOscillator({
  frequency: 440,
  lowpass: { frequency: 800, q: 1 },
  highpass: { frequency: 200 }
})
const filters = osc.getFilters()
console.log(filters.length) // 2
console.log(filters[0].type) // 'highpass'

---

getGainNode()

getGainNode(): GainNode

Defined in: base-sound.ts:540

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

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

Inherited from

BaseSound.getGainNode

---

later()

protected later(fn): void

Defined in: base-sound.ts:1098

Parameters

fn

() => void

Returns

void

Inherited from

BaseSound.later

---

off()

off<K>(type, listener): this

Defined in: base-sound.ts:681

Unsubscribe from an event.

Note: Due to native EventTarget limitations, you must provide the same listener function reference that was used when subscribing. To remove listeners, store the function reference when adding it.

Type Parameters

K

K extends keyof SoundEventMap

Parameters

type

K

The event type to unsubscribe from

listener

(event) => void

The event handler function to remove

Returns

this

this for chaining

Example

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

Inherited from

BaseSound.off

---

on()

on<K>(type, listener): this

Defined in: base-sound.ts:629

Subscribe to one or more events. Supports chaining.

Type Parameters

K

K extends keyof SoundEventMap

Parameters

type

The event type(s) to subscribe to

K | K[]

listener

(event) => void

The event handler function

Returns

this

this for chaining

Example

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

Inherited from

BaseSound.on

---

once()

once<K>(type, listener): this

Defined in: base-sound.ts:654

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

Type Parameters

K

K extends keyof SoundEventMap

Parameters

type

K

The event type to subscribe to

listener

(event) => void

The event handler function

Returns

this

this for chaining

Example

sound.once('end', () => console.log('Playback finished'));

Inherited from

BaseSound.once

---

onPlayRamp()

onPlayRamp(type, rampType?): object

Defined in: oscillator.ts:221

Schedule a parameter ramp when play() is called.

Parameters

type

ControlType

The parameter to ramp ('gain', 'pan', 'frequency', 'detune')

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

Example

// Vibrato effect: ramp frequency up and down
osc.onPlayRamp('frequency', 'linear').from(440).to(450).in(0.1)
osc.play()

Overrides

BaseSound.onPlayRamp

---

onPlaySet()

onPlaySet(type): object

Defined in: oscillator.ts:203

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

Oscillator supports additional parameters beyond Sound:

• 'gain': Volume level (0-1)
• 'pan': Stereo position (-1 to 1)
• 'frequency': Oscillator frequency in Hz
• 'detune': Detune in cents

Parameters

type

ControlType

The parameter to control

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

Example

// Start at frequency 220, glide up to 440 over 0.5 seconds
osc.onPlaySet('frequency').to(220).at(0)
osc.onPlaySet('frequency').to(440).endingAt(0.5, 'linear')
osc.play()

Overrides

BaseSound.onPlaySet

---

play()

play(): Promise<void>

Defined in: base-sound.ts:837

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

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

Inherited from

BaseSound.play

---

playAt()

playAt(time): Promise<void>

Defined in: base-sound.ts:913

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

// 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

BaseSound.playAt

---

playFor()

playFor(duration): void

Defined in: base-sound.ts:867

Play for a specific duration, then stop automatically.

Parameters

duration

number

Seconds of playback before stopping

Returns

void

Example

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

Inherited from

BaseSound.playFor

---

playIn()

playIn(when): void

Defined in: base-sound.ts:852

Schedule playback after a delay.

Parameters

when

number

Seconds from now until playback starts

Returns

void

Example

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

Inherited from

BaseSound.playIn

---

playInAndStopAfter()

playInAndStopAfter(playIn, stopAfter): void

Defined in: base-sound.ts:886

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

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

Inherited from

BaseSound.playInAndStopAfter

---

removeEffect()

removeEffect(effect): this

Defined in: base-sound.ts:378

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

BaseSound.removeEffect

---

removeEventListener()

Call Signature

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

Defined in: base-sound.ts:582

Remove a typed event listener for sound lifecycle events. Overloaded to provide type safety for known event types while remaining compatible with EventTarget.

Type Parameters

K

K extends keyof SoundEventMap

Parameters

type

K

The event type ('play', 'stop', 'end', etc.)

listener

(event) => void

The event handler function to remove

options?

Standard removeEventListener options

boolean | EventListenerOptions

Returns

void

Inherited from

BaseSound.removeEventListener

Call Signature

removeEventListener(type, listener, options?): void

Defined in: base-sound.ts:587

Remove a typed event listener for sound lifecycle events. Overloaded to provide type safety for known event types while remaining compatible with EventTarget.

Parameters

type

string

The event type ('play', 'stop', 'end', etc.)

listener

The event handler function to remove

EventListenerOrEventListenerObject | null

options?

Standard removeEventListener options

boolean | EventListenerOptions

Returns

void

Inherited from

BaseSound.removeEventListener

---

rewireEffects()

rewireEffects(): void

Defined in: base-sound.ts:483

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

Returns

void

Inherited from

BaseSound.rewireEffects

---

setAnalyzer()

setAnalyzer(analyzer): this

Defined in: base-sound.ts:510

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

BaseSound.setAnalyzer

---

setDestination()

setDestination(node): this

Defined in: base-sound.ts:473

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

BaseSound.setDestination

---

setup()

protected setup(): void

Defined in: oscillator.ts:230

Set up a fresh OscillatorNode for playback. Called automatically before each play() since OscillatorNode is single-use.

Returns

void

Overrides

BaseSound.setup

---

stop()

stop(): Promise<void>

Defined in: oscillator.ts:374

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

await sound.stop()

Overrides

BaseSound.stop

---

stopAt()

stopAt(time): Promise<void>

Defined in: oscillator.ts:362

Stop the oscillator at a specific AudioContext time.

Applies a quick 10ms gain fade-out before stopping to prevent click/pop artifacts from abrupt waveform cutoff. If an ADSR envelope is active, the fade-out is skipped since the envelope's release handles it.

Parameters

time

number

The AudioContext time when playback should stop

Returns

Promise<void>

Overrides

BaseSound.stopAt

---

stopIn()

stopIn(seconds): Promise<void>

Defined in: base-sound.ts:1002

Stop the audio source after a delay.

Parameters

seconds

number

Seconds from now until playback stops

Returns

Promise<void>

Example

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

Inherited from

BaseSound.stopIn

---

update()

update(type): object

Defined in: base-sound.ts:707

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

ControlType

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

// 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

BaseSound.update

---

wireConnections()

protected wireConnections(): void

Defined in: oscillator.ts:261

Wire oscillator through filters to effect chain.

Returns

void

Overrides

BaseSound.wireConnections