Foundation.SoundController

Used to load, unload, play, loop, pause, resume, and stop sound cues. This implementation uses HTMLAudioElements under the hood. Perfect stitching for looped sounds is unlikely.

To allow a sound to play over itself when needed, multiple instances of any sound can be loaded. Play / loop calls will transparently select the first instance that is available for playback. The more instances of a sound you load, them more instances you can have playing over each other (obviously!) but keep in mind there's a memory footprint for every instance loaded.


Example

// Create a new sound controller
var sc = new Foundation.SoundController();

// Load an MP3 file at its original volume (1 instance)
sc.load('originalVolume', './path/to/some.mp3');

// Load an MP3 file at half its original volume (1 instance) 
sc.load('halfVolume', './path/to/some.mp3', 1, 0.5);

// Play both
sc.play('originalVolume');
sc.play('halfVolume'); // This will play at half the volume of above

// Set global volume
sc.volume = 0.5;

// Play both
sc.play('originalVolume'); // Now at half of original volume
sc.play('halfVolume');     // Now at quarter of original volume

// Set both sounds looping
sc.loop('originalVolume');
sc.loop('halfVolume');

// Play will fail as there is only one instance of 'origialVolume', 
// and it is currently looping
sc.play('originalVolume'); 

// Load another audio file (2 instances)
sc.load('anotherSound', './path/to/someOther.mp3', 2);

// Loop an instance of the new sound
sc.loop('anotherSound');

// Play the other instance (will succeed)
sc.play('anotherSound'); 


Implementation Details

Reference paths

  • '/foundation/_digest.ts'
  • '/foundation/core/actors/_digest.ts'
  • '/foundation/core/actors/SoundController.ts'

Extends

This type extends:

[@TODO consider changing below implementations]

equals() calls will always be false. clone() calls return null.

Implements

This type does not implement any interfaces (except those in the base).


Public Properties

volume: number

  • Get or set the global volume in the range 0 - 1 (clamped when setting).

Instance Methods

load(key: string, path: string, instances: number = 1, balanceVolume: number = 1): void

  • Load a new audio sample for playback, passing path to the audio file. The asset will be accessible with the provided key.
  • Optionally, the number of instances to load (default: 1) can be specified. Multiple instances allow for overplaying.
  • The last parameter can be used to reduce the clip volume against global volume. See example code at the top of this page for an example. This value is clamped to 0 - 1 in setting.

unload(key: string): void

  • Frees all instances of the named sound, making them eligible for garbage collection.

hasKey(key: string): boolean

  • Returns true if key exists in the controller and has instances.

play(key: string): boolean

  • Play the first available instance of the key sound.
  • The sound will play once.
  • If no instances are available to play (all playing / looping at call time), then no audio will be played.
  • Returns true if playback was started.

loop(key: string): boolean

  • Play the first available instance of the key sound.
  • The sound will loop until explicitly stopped or paused.
  • If no instances are available to play (all playing / looping at call time), then no audio will be played.
  • Returns true if playback was started.

stop(key: string): void

  • Hard stop all playing key instances and reset them for future play calls.

pause(key: string): void

  • Pause all playing key instances.
  • Instances will not be reset, and can be resumed with a resume(key) call.

resume(key: string): void

  • Resume all key instances which were previously paused.

stopAll(): void

  • Hard stop all instances of all sounds in the controller.
  • All sounds will be reset for future play calls.

pauseAll(): void

  • Pause all instances of all sounds in the controller.
  • No sounds will be reset and can be resumed with a resumeAll() call.

resumeAll(): void

  • Resume all instances of all sounds in the controller which were previously paused.