EZ Web Audio

Appearance

EZ Web Audio / AudioSprite

Class: AudioSprite ​

Defined in: packages/core/src/sprite.ts:160

AudioSprite enables playing segments of a single audio file by name.

Use sprites to bundle multiple short sounds into one file, reducing HTTP requests. Compatible with the audiosprite JSON format.

Example ​

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

const sprite = await createSprite('sounds.mp3', {
  spritemap: {
    laser: { start: 0, end: 0.3 },
    explosion: { start: 1.0, end: 2.5 },
    powerup: { start: 3.0, end: 3.5 }
  }
})

// Play specific sounds by name
sprite.play('laser')
sprite.play('explosion', { gain: 0.7 })

// Check available sprites
console.log(sprite.names) // ['laser', 'explosion', 'powerup']

Constructors ​

Constructor ​

new AudioSprite(audioContext, audioBuffer, manifest): AudioSprite

Defined in: packages/core/src/sprite.ts:171

Parameters ​

audioContext ​

AudioContext

audioBuffer ​

AudioBuffer

manifest ​

AudiospriteManifest

Returns ​

AudioSprite

Accessors ​

names ​

Get Signature ​

get names(): string[]

Defined in: packages/core/src/sprite.ts:215

List of available sprite names defined in the manifest.

Example ​
typescript
sprite.names.forEach(name => console.log(name))
Returns ​

string[]

Methods ​

dispose() ​

dispose(): void

Defined in: packages/core/src/sprite.ts:442

Release the audio buffer and stop all active sources.

After disposal, calling play() will throw an error. Use this to free memory when the sprite is no longer needed.

Returns ​

void

Example ​

typescript
const sprite = await createSprite('sounds.mp3', manifest)
sprite.play('laser')

// When done with the sprite
sprite.dispose()
// sprite.play('laser') // throws: AudioSprite has been disposed

getDuration() ​

getDuration(name): number

Defined in: packages/core/src/sprite.ts:249

Get the duration of a sprite in seconds.

Parameters ​

name ​

string

The sprite name

Returns ​

number

Duration in seconds

Throws ​

Error if sprite name not found

Example ​

typescript
const duration = sprite.getDuration('explosion')
console.log(`Explosion lasts ${duration} seconds`)

has() ​

has(name): boolean

Defined in: packages/core/src/sprite.ts:232

Check if a sprite with the given name exists.

Parameters ​

name ​

string

The sprite name to check

Returns ​

boolean

true if the sprite exists

Example ​

typescript
if (sprite.has('laser')) {
  sprite.play('laser')
}

play() ​

play(name, options): void

Defined in: packages/core/src/sprite.ts:281

Play a sprite by name.

Each call creates a new AudioBufferSourceNode, allowing concurrent playback of the same sprite. Use options to control gain and pan.

Parameters ​

name ​

string

The sprite name to play

options ​

SpritePlayOptions = {}

Optional gain (0-1) and pan (-1 to 1) settings

Returns ​

void

Throws ​

Error if sprite name not found

Example ​

typescript
// Simple playback
sprite.play('laser')

// With options
sprite.play('explosion', { gain: 0.5, pan: -0.5 })

// Rapid fire (each creates new source)
sprite.play('laser')
sprite.play('laser')
sprite.play('laser')

stop() ​

stop(name): void

Defined in: packages/core/src/sprite.ts:397

Stop all active playback of the named sprite.

Only useful for sprites defined with loop: true, since non-looping sprites stop automatically when their duration elapses.

Parameters ​

name ​

string

The sprite name to stop

Returns ​

void

Example ​

typescript
sprite.play('bgmusic') // starts looping
// later...
sprite.stop('bgmusic') // stops the loop

stopAll() ​

stopAll(): void

Defined in: packages/core/src/sprite.ts:420

Stop all active looping sprites.

Returns ​

void

Example ​

typescript
sprite.play('bgmusic')
sprite.play('ambient')
sprite.stopAll() // stops both