Audio

import { type AudioManagerOptions, AudioManager, AudioManagerGlobal } from "@arclockproject/common/library/Audio";

For examples and live demos, see the Audio guide.

AudioManagerOptions

Type

type AudioManagerOptions

Options for new AudioManager().

Properties

• cache? (object) — Limits how many <audio> elements one-shot sounds keep per file. Single-instance sounds always use one element, so this doesn't apply to them. Leave it out for no limit.

  • maxInstances (number) — Most elements kept per file. When this many exist and none is free, onMax runs before another is created.

    Example: with maxInstances: 10, onMax runs before the 11th would be created.

    1 or lower still allows 1 element.

  • onMax ("drop" | "throw" | ((path: string, count: number) => boolean | void)) — What to do when the limit is reached:

    • "drop": don't create the element. The sound doesn't play.
    • "throw": throw an Error from play.
    • A function: called with the file path and the number of elements for it. Return true to drop the sound. Any other return value, including none, creates the element and plays the sound.

AudioManager

Class

class AudioManager

Plays sound files using <audio> elements, with fade in and out.

There are two kinds of sounds:

• One-shot (default): each play starts the file from the beginning, and overlapping plays of the same file are allowed. Good for clicks and effects. The number of overlapping plays can be limited with the cache option.
• Single instance (singleInstance: true): one shared element per file, which resumes where it stopped and can be stopped with stopInstance. Good for music and ambience.

Most apps use the shared AudioManagerGlobal instead of creating their own.

Constructor

new AudioManager(options: AudioManagerOptions = { cache: { maxInstances: 11, onMax: (path, count) => console.warn(`Cache for '${path}' exceeded 10 instances (${count})!`), }, })

Parameters

• options? (AudioManagerOptions, default { cache: { maxInstances: 11, onMax: (path, count) => console.warn(`Cache for '${path}' exceeded 10 instances (${count})!`), }, }) — Leave it out to keep the old behaviour: a console warning once a file has more than 10 one-shot elements, with no limit on how many are created. Pass {} for no limit and no warnings.

Properties

• maxVolume (number, default 1) — Volume sounds play at, from 0 to 1. Change it with setMaxVolume.
• options (AudioManagerOptions) — Options passed to the constructor. Changes apply to the next play.

AudioManager.setMaxVolume()

AudioManager.setMaxVolume(volume: number): void

Sets the volume for all sounds. Single-instance sounds that are playing change right away, and any fade on them stops.

Parameters

• volume (number) — From 0 (silent) to 1 (full).

AudioManager.play()

AudioManager.play(path: string | string, options?: { singleInstance?: boolean; loop?: boolean; gradual?: boolean; speed?: number; preservesPitch?: boolean }): void

Plays the file at path.

Parameters

• path (string | string) — URL of the audio file.
• options? (object) — How to play it. All are optional.
  • singleInstance? (boolean) — Use one shared element for this file, which resumes instead of restarting. Needed for stopInstance.
  • loop? (boolean) — Repeat when it reaches the end.
  • gradual? (boolean) — Fade in instead of starting at full volume.
  • speed? (number) — Playback rate, where 1 is normal speed.
  • preservesPitch? (boolean) — Keep the pitch the same when speed is not 1.

Example

AudioManagerGlobal.play("/sounds/click.mp3");
AudioManagerGlobal.play("/music/theme.mp3", { singleInstance: true, loop: true, gradual: true });

AudioManager.stopAllInstances()

AudioManager.stopAllInstances(data?: { gradual?: boolean }): void

Stops every single-instance sound. One-shot sounds keep playing.

Parameters

• data? (object) — Optional settings.
  • gradual? (boolean) — Fade out instead of stopping at once.

AudioManager.stopInstance()

AudioManager.stopInstance(path: string, data?: { gradual?: boolean }): void

Pauses the single-instance sound for path. Playing it again resumes from the same position. Has no effect on one-shot sounds.

Parameters

• path (string) — The same URL that was passed to play.
• data? (object) — Optional settings.
  • gradual? (boolean) — Fade out instead of stopping at once.

Example

AudioManagerGlobal.stopInstance("/music/theme.mp3", { gradual: true });

AudioManagerGlobal

Instance of AudioManager

Shared AudioManager for the whole app, so volume and single-instance sounds are managed in one place.

Default configuration:

• Warn when single sound has more then 10 instances
• No instance limit for single sound

Example

import { AudioManagerGlobal } from "@arclockproject/common/library/Audio";

AudioManagerGlobal.play("/sounds/click.mp3");