Skip to main content

Sound <TName>

The Sound object allows games built in Excalibur to load audio components, from soundtracks to sound effects. Sound is an Loadable which means it can be passed to a Loader to pre-load before a game or level.

Implements

Index

Constructors

Properties

Accessors

Methods

Constructors

publicconstructor

  • Construct a Sound from an options object with an explicit name. The class generic TName is inferred from the name literal when one is provided.

    Type parameters

    • TName: string = string

    Parameters

    Returns Sound<TName>

Properties

publicdata

data: AudioBuffer

Data associated with a loadable

publicevents

events: EventEmitter<SoundEvents> = ...

publiclogger

logger: Logger = ...

publicmaxConcurrentTracks

maxConcurrentTracks: number = Infinity

publicreadonlyname

name: TName

The registered name of this Sound. Either the explicit name option or the basename-without-extension of the selected path. Used as the default key when registered with a SoundManager.

publicoptionalonPlay

onPlay?: AudioGraphBuilder

Optional hook to wire custom Web Audio nodes between this sound's source and its output, runs each time a track (re)starts. See AudioGraphBuilder.

publicposition

position: number | undefined

Position in seconds new tracks start from, see PlayOptions.position for a one-off

publicvoiceStealing

voiceStealing: boolean = false

Accessors

publicbustCache

  • get bustCache(): boolean
  • set bustCache(val: boolean): void

  • Should excalibur add a cache busting querystring? By default false. Must be set before loading

    Returns boolean

  • Parameters

    • val: boolean

    Returns void

publicduration

  • get duration(): number | undefined
  • set duration(duration: number | undefined): void

  • Get the duration that this audio should play. If unset the total natural playback duration will be used.

    Returns number | undefined

  • Set the duration that this audio should play. If unset the total natural playback duration will be used.

    Note: if you seek to a specific point the duration will start from that point, for example

    If you have a 10 second clip, seek to 5 seconds, then set the duration to 2, it will play the clip from 5-7 seconds.

    Parameters

    • duration: number | undefined

    Returns void

publicinstances

publicloop

  • get loop(): boolean
  • set loop(value: boolean): void

  • Returns boolean

  • Indicates whether the clip should loop when complete

    Parameters

    • value: boolean

      Set the looping flag

    Returns void

publicoutput

  • get output(): GainNode

  • The GainNode every track of this sound is mixed into, carrying Sound.volume. Connected straight to the audio context destination until a SoundManager re-routes it through its mixer graph.

    Returns GainNode

publicpath

  • get path(): string
  • set path(val: string): void

  • Returns string

  • Parameters

    • val: string

    Returns void

publicpitch

  • get pitch(): number
  • set pitch(pitch: number): void

  • Pitch shift in cents (semitones are 100 cents). Default 0 (no change). Backed by AudioBufferSourceNode.detune; composes with Sound.playbackRate. Note: changing pitch also affects playback speed (this is a Web Audio limitation).

    Returns number

  • Parameters

    • pitch: number

    Returns void

publicplaybackRate

  • get playbackRate(): number
  • set playbackRate(playbackRate: number): void

  • Returns number

  • Parameters

    • playbackRate: number

    Returns void

publicvolume

  • get volume(): number
  • set volume(value: number): void

  • Returns number

  • Volume [0-1] applied to every track of this sound, ramped smoothly while playing

    Parameters

    • value: number

    Returns void

Methods

publicdecodeAudio

  • decodeAudio(data: ArrayBuffer): Promise<AudioBuffer>

  • Parameters

    • data: ArrayBuffer

    Returns Promise<AudioBuffer>

publicemit

  • emit<TEventName>(eventName: TEventName, event: SoundEvents[TEventName]): void
  • emit(eventName: string, event?: any): void

publicgetPlaybackPosition

  • getPlaybackPosition(trackId?: number): number

  • Return the current playback time of the playing track in seconds from the start.

    Optionally specify the track to query if multiple are playing at once.

    Parameters

    • trackId: number = 0

    Returns number

publicgetTotalPlaybackDuration

  • getTotalPlaybackDuration(): number

  • Returns number

publicgetTrackId

publicinstanceCount

  • instanceCount(): number

  • Returns how many tracks of the sound currently exist (playing or paused)

    Returns number

publicisLoaded

  • isLoaded(): boolean

  • Returns true if the loadable is loaded

    Returns boolean

publicisPaused

  • isPaused(): boolean

  • Returns boolean

publicisPlaying

  • isPlaying(): boolean

  • Whether or not the sound is playing right now

    Returns boolean

publicisStopped

  • isStopped(): boolean

  • Returns boolean

publicload

  • load(): Promise<AudioBuffer>

  • Begins loading the resource and returns a promise to be resolved on completion

    Returns Promise<AudioBuffer>

publicoff

  • off<TEventName>(eventName: TEventName, handler: Handler<SoundEvents[TEventName]>): void
  • off(eventName: string, handler: Handler<unknown>): void
  • off(eventName: string): void

publicon

publiconce

publicpause

  • pause(): void

  • Stop the sound, and do not rewind

    Returns void

publicplay

  • play(options?: PlayOptions): Promise<boolean>
  • play(volume: number): Promise<boolean>

  • Play a new track of this sound, returns a promise that resolves when that track is done playing (false if the play was dropped, e.g. by Sound.maxConcurrentTracks).

    Options apply to this track only and never change the Sound's own configuration:

    sound.play();                                   // the sound as configured
sound.play({ volume: 0.3, pitch: -200 });       // quieter and lower, this time only
sound.play({ position: 2, duration: 1 });       // one second starting two seconds in

    To continue paused tracks use Sound.resume, to get a handle on the track use Sound.start.

    Parameters

    Returns Promise<boolean>

publicplayingCount

  • playingCount(): number

  • Returns how many tracks of the sound are currently playing

    Returns number

publicresume

  • resume(): Promise<boolean>

  • Resume every paused (or seeked) track, resolves when they are done playing. Resolves false immediately if nothing was paused.

    Returns Promise<boolean>

publicseek

  • seek(position: number, trackId?: number): void

  • Seek a track to a position in seconds, the track is paused until the next Sound.resume.

    If no track exists one is created so that seek(); resume() starts from the position.

    Parameters

    • position: number
    • trackId: number = 0

    Returns void

publicstart

  • Like Sound.play but returns the SoundTrack synchronously so it can be stopped, seeked or adjusted while it plays. Returns null if the play was dropped.

    const footstep = sound.start({ volume: 0.5 });
footstep?.stop();
await footstep?.done;

    Parameters

    Returns SoundTrack | null

publicstop

  • stop(): void

  • Stop the sound if it is currently playing and rewind the track. If the sound is not playing, rewinds the track.

    Returns void

publicwireEngine

  • wireEngine(engine: Engine): void

  • Parameters

    Returns void

staticcanPlayFile

  • canPlayFile(file: string): boolean

  • Whether or not the browser can play this file as HTML5 Audio

    Parameters

    • file: string

    Returns boolean

staticcanPlayMime

  • canPlayMime(mime: string): boolean

  • Parameters

    • mime: string

    Returns boolean

publicstaticfromBlob

  • fromBlob(blob: Blob): Promise<Sound<string>>

  • Parameters

    • blob: Blob

    Returns Promise<Sound<string>>

Page Options