excalibur 0.32.0-alpha.1601 → 0.32.0-alpha.17

package/CHANGELOG.md

@@ -17,6 +17,17 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 
 
+- Added new parameter to `ex.Sounds` to schedule start time, this allows you to synchronize playback of multiple audio tracks
+  ```typescript
+  const start500MsFromNow = AudioContextFactory.currentTime() + 500;
+
+  Resources.MusicSurface.play({ volume: .5, scheduledStartTime: start500MsFromNow });
+  // Start layered tracks at 0 volume so they are synchronized
+  Resources.MusicIndDrums.play({ volume: 0, scheduledStartTime: start500MsFromNow });
+  Resources.MusicIndTopper.play({ volume: 0, scheduledStartTime: start500MsFromNow });
+  Resources.MusicGroovyDrums.play({ volume: 0, scheduledStartTime: start500MsFromNow });
+  Resources.MusicGroovyTopper.play({ volume: 0, scheduledStartTime: start500MsFromNow });
+  ```
 - Added new Timer events! 
   ```typescript
   const timer = new ex.Timer({...});

package/build/dist/Resources/Sound/AudioContext.d.ts

@@ -4,4 +4,8 @@
 export declare class AudioContextFactory {
     private static _INSTANCE?;
     static create(): AudioContext;
+    /**
+     * Return the current audio context time in millseconds
+     */
+    static currentTime(): number;
 }

package/build/dist/Resources/Sound/Sound.d.ts

@@ -1,5 +1,6 @@
 import type { Audio } from '../../Interfaces/Audio';
 import type { Engine } from '../../Engine';
+import { WebAudioInstance } from './WebAudioInstance';
 import { NativeSoundEvent, NativeSoundProcessedEvent } from '../../Events/MediaEvents';
 import type { Loadable } from '../../Interfaces/Index';
 import { Logger } from '../../Util/Log';
@@ -61,6 +62,26 @@ export interface SoundOptions {
      */
     position?: number;
 }
+export interface PlayOptions {
+    /**
+     * Volume to play between [0, 1]
+     */
+    volume?: number;
+    /**
+     * Schedule time to play in milliseconds from the audio context origin
+     *
+     * Compute using the audio context
+     *
+     * ```typescript
+     * const sound: Sound = ...;
+     * const oneThousandMillisecondsFromNow = AudioContextFactory.currentTime + 1000;
+     *
+     * sound.play({ scheduledStartTime: oneThousandMillisecondsFromNow });
+     *
+     * ```
+     */
+    scheduledStartTime?: number;
+}
 /**
  * The {@apilink Sound} object allows games built in Excalibur to load audio
  * components, from soundtracks to sound effects. {@apilink Sound} is an {@apilink Loadable}
@@ -105,6 +126,20 @@ export declare class Sound implements Audio, Loadable<AudioBuffer> {
      */
     get bustCache(): boolean;
     set bustCache(val: boolean);
+    /**
+     * Schedule time to play in milliseconds from the audio context origin
+     *
+     * Compute using the audio context
+     *
+     * ```typescript
+     * const sound: Sound = ...;
+     * const oneThousandMillisecondsFromNow = AudioContextFactory.currentTime + 1000;
+     *
+     * sound.scheduledStartTime = oneThousandMillisecondsFromNow;
+     *
+     * ```
+     */
+    scheduledStartTime: number;
     private _loop;
     private _volume;
     private _isStopped;
@@ -136,7 +171,7 @@ export declare class Sound implements Audio, Loadable<AudioBuffer> {
      * Play the sound, returns a promise that resolves when the sound is done playing
      * An optional volume argument can be passed in to play the sound. Max volume is 1.0
      */
-    play(volume?: number): Promise<boolean>;
+    play(volumeOrConfig?: number | PlayOptions): Promise<boolean>;
     /**
      * Stop the sound, and do not rewind
      */
@@ -160,7 +195,7 @@ export declare class Sound implements Audio, Loadable<AudioBuffer> {
      * Get Id of provided AudioInstance in current trackList
      * @param track {@apilink Audio} which Id is to be given
      */
-    getTrackId(track: Audio): number;
+    getTrackId(track: WebAudioInstance): number;
     private _resumePlayback;
     /**
      * Starts playback, returns a promise that resolves when playback is complete

package/build/dist/Resources/Sound/WebAudioInstance.d.ts

@@ -45,4 +45,5 @@ export declare class WebAudioInstance implements Audio {
     private _playbackRate;
     set playbackRate(playbackRate: number);
     get playbackRate(): number;
+    scheduledStartTime: number;
 }

package/build/dist/excalibur.development.js

@@ -1,4 +1,4 @@
-/*! excalibur - 0.32.0-alpha.1601+6319a6b - 2025-12-19
+/*! excalibur - 0.32.0-alpha.17+d1b9643 - 2025-12-22
 https://github.com/excaliburjs/Excalibur
 Copyright (c) 2025 Excalibur.js <https://github.com/excaliburjs/Excalibur/graphs/contributors>
 Licensed BSD-2-Clause
@@ -23444,6 +23444,12 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
       }
       return this._INSTANCE;
     }
+    /**
+     * Return the current audio context time in millseconds
+     */
+    static currentTime() {
+      return AudioContextFactory.create().currentTime * 1e3;
+    }
   }
   function isLegacyWebAudioSource(source) {
     return !!source.playbackState;
@@ -23606,9 +23612,9 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
                 this._createNewBufferSource();
                 this._handleEnd();
                 if (this.loop) {
-                  this._instance.start(0, data.pausedAt * this._playbackRate);
+                  this._instance.start(this.scheduledStartTime, data.pausedAt * this._playbackRate);
                 } else {
-                  this._instance.start(0, data.pausedAt * this._playbackRate, this.duration);
+                  this._instance.start(this.scheduledStartTime, data.pausedAt * this._playbackRate, this.duration);
                 }
                 data.startedAt = this._audioContext.currentTime - data.pausedAt;
                 data.pausedAt = 0;
@@ -23658,6 +23664,7 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
       this._playStarted = () => {
       };
       this._playbackRate = 1;
+      this.scheduledStartTime = 0;
       this._createNewBufferSource();
     }
     _createNewBufferSource() {
@@ -23855,6 +23862,7 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
     constructor(...pathsOrSoundOption) {
       this.events = new EventEmitter();
       this.logger = Logger.getInstance();
+      this.scheduledStartTime = 0;
       this._loop = false;
       this._volume = 1;
       this._isStopped = false;
@@ -24023,7 +24031,7 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
      * Play the sound, returns a promise that resolves when the sound is done playing
      * An optional volume argument can be passed in to play the sound. Max volume is 1.0
      */
-    play(volume) {
+    play(volumeOrConfig) {
       if (!this.isLoaded()) {
         this.logger.warn("Cannot start playing. Resource", this.path, "is not loaded yet");
         return Promise.resolve(true);
@@ -24032,14 +24040,21 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
         this.logger.warn("Cannot start playing. Engine is in a stopped state.");
         return Promise.resolve(false);
       }
-      this.volume = volume != null ? volume : this.volume;
+      let scheduledStart = 0;
+      if (volumeOrConfig instanceof Object) {
+        const { volume, scheduledStartTime } = volumeOrConfig;
+        scheduledStart = (scheduledStartTime != null ? scheduledStartTime : 0) / 1e3 || scheduledStart;
+        this.volume = volume != null ? volume : this.volume;
+      } else {
+        this.volume = volumeOrConfig != null ? volumeOrConfig : this.volume;
+      }
       if (this.isPaused()) {
         return this._resumePlayback();
       } else {
         if (this.position) {
           this.seek(this.position);
         }
-        return this._startPlayback();
+        return this._startPlayback(scheduledStart);
       }
     }
     /**
@@ -24109,10 +24124,11 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
     getTrackId(track) {
       return this._tracks.indexOf(track);
     }
-    async _resumePlayback() {
+    async _resumePlayback(scheduledStart = 0) {
       if (this.isPaused()) {
         const resumed = [];
         for (const track of this._tracks) {
+          track.scheduledStartTime = scheduledStart;
           resumed.push(
             track.play().then(() => {
               this._tracks.splice(this.getTrackId(track), 1);
@@ -24129,8 +24145,9 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
     /**
      * Starts playback, returns a promise that resolves when playback is complete
      */
-    async _startPlayback() {
+    async _startPlayback(scheduledStartTime = 0) {
       const track = this._getTrackInstance(this.data);
+      track.scheduledStartTime = scheduledStartTime;
       const complete = await track.play(() => {
         this.events.emit("playbackstart", new NativeSoundEvent(this, track));
         this.logger.debug("Playing new instance for sound", this.path);
@@ -33614,7 +33631,7 @@ Read more about this issue at https://excaliburjs.com/docs/performance`
       this._count += count;
     }
   }
-  const EX_VERSION = "0.32.0-alpha.1601+6319a6b";
+  const EX_VERSION = "0.32.0-alpha.17+d1b9643";
   polyfill();
   exports2.ActionCompleteEvent = ActionCompleteEvent;
   exports2.ActionContext = ActionContext;

package/build/dist/excalibur.js

@@ -1,4 +1,4 @@
-/*! excalibur - 0.32.0-alpha.1601+6319a6b - 2025-12-19
+/*! excalibur - 0.32.0-alpha.17+d1b9643 - 2025-12-22
 https://github.com/excaliburjs/Excalibur
 Copyright (c) 2025 Excalibur.js <https://github.com/excaliburjs/Excalibur/graphs/contributors>
 Licensed BSD-2-Clause
@@ -23444,6 +23444,12 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
       }
       return this._INSTANCE;
     }
+    /**
+     * Return the current audio context time in millseconds
+     */
+    static currentTime() {
+      return AudioContextFactory.create().currentTime * 1e3;
+    }
   }
   function isLegacyWebAudioSource(source) {
     return !!source.playbackState;
@@ -23606,9 +23612,9 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
                 this._createNewBufferSource();
                 this._handleEnd();
                 if (this.loop) {
-                  this._instance.start(0, data.pausedAt * this._playbackRate);
+                  this._instance.start(this.scheduledStartTime, data.pausedAt * this._playbackRate);
                 } else {
-                  this._instance.start(0, data.pausedAt * this._playbackRate, this.duration);
+                  this._instance.start(this.scheduledStartTime, data.pausedAt * this._playbackRate, this.duration);
                 }
                 data.startedAt = this._audioContext.currentTime - data.pausedAt;
                 data.pausedAt = 0;
@@ -23658,6 +23664,7 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
       this._playStarted = () => {
       };
       this._playbackRate = 1;
+      this.scheduledStartTime = 0;
       this._createNewBufferSource();
     }
     _createNewBufferSource() {
@@ -23855,6 +23862,7 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
     constructor(...pathsOrSoundOption) {
       this.events = new EventEmitter();
       this.logger = Logger.getInstance();
+      this.scheduledStartTime = 0;
       this._loop = false;
       this._volume = 1;
       this._isStopped = false;
@@ -24023,7 +24031,7 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
      * Play the sound, returns a promise that resolves when the sound is done playing
      * An optional volume argument can be passed in to play the sound. Max volume is 1.0
      */
-    play(volume) {
+    play(volumeOrConfig) {
       if (!this.isLoaded()) {
         this.logger.warn("Cannot start playing. Resource", this.path, "is not loaded yet");
         return Promise.resolve(true);
@@ -24032,14 +24040,21 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
         this.logger.warn("Cannot start playing. Engine is in a stopped state.");
         return Promise.resolve(false);
       }
-      this.volume = volume != null ? volume : this.volume;
+      let scheduledStart = 0;
+      if (volumeOrConfig instanceof Object) {
+        const { volume, scheduledStartTime } = volumeOrConfig;
+        scheduledStart = (scheduledStartTime != null ? scheduledStartTime : 0) / 1e3 || scheduledStart;
+        this.volume = volume != null ? volume : this.volume;
+      } else {
+        this.volume = volumeOrConfig != null ? volumeOrConfig : this.volume;
+      }
       if (this.isPaused()) {
         return this._resumePlayback();
       } else {
         if (this.position) {
           this.seek(this.position);
         }
-        return this._startPlayback();
+        return this._startPlayback(scheduledStart);
       }
     }
     /**
@@ -24109,10 +24124,11 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
     getTrackId(track) {
       return this._tracks.indexOf(track);
     }
-    async _resumePlayback() {
+    async _resumePlayback(scheduledStart = 0) {
       if (this.isPaused()) {
         const resumed = [];
         for (const track of this._tracks) {
+          track.scheduledStartTime = scheduledStart;
           resumed.push(
             track.play().then(() => {
               this._tracks.splice(this.getTrackId(track), 1);
@@ -24129,8 +24145,9 @@ If you want to do custom drawing, use Actor.graphics, or any onPreDraw or onPost
     /**
      * Starts playback, returns a promise that resolves when playback is complete
      */
-    async _startPlayback() {
+    async _startPlayback(scheduledStartTime = 0) {
       const track = this._getTrackInstance(this.data);
+      track.scheduledStartTime = scheduledStartTime;
       const complete = await track.play(() => {
         this.events.emit("playbackstart", new NativeSoundEvent(this, track));
         this.logger.debug("Playing new instance for sound", this.path);
@@ -33614,7 +33631,7 @@ Read more about this issue at https://excaliburjs.com/docs/performance`
       this._count += count;
     }
   }
-  const EX_VERSION = "0.32.0-alpha.1601+6319a6b";
+  const EX_VERSION = "0.32.0-alpha.17+d1b9643";
   polyfill();
   exports2.ActionCompleteEvent = ActionCompleteEvent;
   exports2.ActionContext = ActionContext;