@antha/audio 0.4.3 → 0.5.0

package/dist/audio-file.d.ts

@@ -1,4 +1,4 @@
-import { type PartialWithUndefined, type SelectFrom } from '@augment-vir/common';
+import { DeferredPromise, type PartialWithUndefined, type SelectFrom } from '@augment-vir/common';
 import { ListenTarget } from 'typed-event-target';
 import { type Codec } from './codecs.js';
 /**
@@ -166,6 +166,17 @@ export type AudioFileCache = {
         buffer: AudioBuffer;
     }>;
 };
+/**
+ * State tracked for an active or paused audio playback.
+ *
+ * @category Internal
+ */
+export type AudioPlayback = {
+    audioBuffer: AudioBuffer;
+    deferredPlayPromise: DeferredPromise<boolean>;
+    offsetSeconds: number;
+    startedAt: number;
+};
 /**
  * Allows creating an array of `AudioNode` instances ("effects") by passing the given `AudioContext`
  * to `createEffects`. The effects created by `createEffects`, if any, are then sequentially
@@ -241,7 +252,8 @@ export declare class AudioFile extends ListenTarget<AllAudioFileEvents> {
     readonly isDestroyed: boolean;
     readonly gainNode: GainNode;
     readonly sourceKey: string;
-    protected readonly activeBufferSources: Set<AudioBufferSourceNode>;
+    protected readonly activeBufferSources: Map<AudioBufferSourceNode, AudioPlayback>;
+    protected readonly pausedPlaybacks: Set<AudioPlayback>;
     constructor(params: AudioFileParams);
     /**
      * Load the audio file so it's ready to play. This will automatically be called on the first
@@ -260,6 +272,10 @@ export declare class AudioFile extends ListenTarget<AllAudioFileEvents> {
     play(): Promise<boolean>;
     /** Stops every active playback while preserving the loaded audio buffer. */
     stop(): void;
+    /** Pauses every active playback while preserving its current position. */
+    pause(): void;
+    /** Resumes every playback paused by {@link pause}. */
+    resume(): void;
     /** Destroys this audio file entirely; it cannot be used anymore. */
     destroy(): Promise<void>;
     /**
@@ -276,5 +292,7 @@ export declare class AudioFile extends ListenTarget<AllAudioFileEvents> {
     protected loadBase64(): ArrayBuffer;
     /** Load the audio file's `ArrayBuffer` from its source URL. */
     protected loadFromUrl(): Promise<ArrayBuffer>;
+    /** Starts an audio source for the supplied playback state. */
+    protected startPlayback(playback: AudioPlayback): void;
 }
 export {};

package/dist/audio-file.js

@@ -159,7 +159,8 @@ export class AudioFile extends ListenTarget {
     isDestroyed = false;
     gainNode;
     sourceKey;
-    activeBufferSources = new Set();
+    activeBufferSources = new Map();
+    pausedPlaybacks = new Set();
     constructor(params) {
         super();
         this.params = params;
@@ -228,26 +229,51 @@ export class AudioFile extends ListenTarget {
                 return false;
             }
         }
-        const deferredPlayPromise = new DeferredPromise();
-        const bufferSource = this.audioContext.createBufferSource();
-        bufferSource.buffer = audioBuffer;
-        bufferSource.connect(this.outputNode);
-        this.activeBufferSources.add(bufferSource);
-        bufferSource.addEventListener('ended', () => {
-            this.activeBufferSources.delete(bufferSource);
-            deferredPlayPromise.resolve(true);
-            this.dispatch(new AudioFilePlayEndEvent());
-        });
-        this.dispatch(new AudioFilePlayStartEvent());
-        bufferSource.start();
-        return deferredPlayPromise.promise;
+        const playback = {
+            audioBuffer,
+            deferredPlayPromise: new DeferredPromise(),
+            offsetSeconds: 0,
+            startedAt: this.audioContext.currentTime,
+        };
+        this.startPlayback(playback);
+        return playback.deferredPlayPromise.promise;
     }
     /** Stops every active playback while preserving the loaded audio buffer. */
     stop() {
+        const pausedPlaybacks = [...this.pausedPlaybacks];
         const activeBufferSources = [...this.activeBufferSources];
+        this.pausedPlaybacks.clear();
         this.activeBufferSources.clear();
-        activeBufferSources.forEach((bufferSource) => {
+        pausedPlaybacks.forEach((playback) => {
+            playback.deferredPlayPromise.resolve(true);
+            this.dispatch(new AudioFilePlayEndEvent());
+        });
+        activeBufferSources.forEach(([bufferSource, playback,]) => {
             bufferSource.stop();
+            playback.deferredPlayPromise.resolve(true);
+            this.dispatch(new AudioFilePlayEndEvent());
+        });
+    }
+    /** Pauses every active playback while preserving its current position. */
+    pause() {
+        [...this.activeBufferSources].forEach(([bufferSource, playback,]) => {
+            const offsetSeconds = Math.min(playback.audioBuffer.duration, playback.offsetSeconds + this.audioContext.currentTime - playback.startedAt);
+            if (offsetSeconds >= playback.audioBuffer.duration) {
+                return;
+            }
+            this.activeBufferSources.delete(bufferSource);
+            this.pausedPlaybacks.add({
+                ...playback,
+                offsetSeconds,
+            });
+            bufferSource.stop();
+        });
+    }
+    /** Resumes every playback paused by {@link pause}. */
+    resume() {
+        [...this.pausedPlaybacks].forEach((playback) => {
+            this.pausedPlaybacks.delete(playback);
+            this.startPlayback(playback);
         });
     }
     /** Destroys this audio file entirely; it cannot be used anymore. */
@@ -327,4 +353,21 @@ export class AudioFile extends ListenTarget {
     async loadFromUrl() {
         return await (await this.fetch(this.urlOrBase64)).arrayBuffer();
     }
+    /** Starts an audio source for the supplied playback state. */
+    startPlayback(playback) {
+        const bufferSource = this.audioContext.createBufferSource();
+        bufferSource.buffer = playback.audioBuffer;
+        bufferSource.connect(this.outputNode);
+        playback.startedAt = this.audioContext.currentTime;
+        this.activeBufferSources.set(bufferSource, playback);
+        bufferSource.addEventListener('ended', () => {
+            if (!this.activeBufferSources.delete(bufferSource)) {
+                return;
+            }
+            playback.deferredPlayPromise.resolve(true);
+            this.dispatch(new AudioFilePlayEndEvent());
+        });
+        this.dispatch(new AudioFilePlayStartEvent());
+        bufferSource.start(0, playback.offsetSeconds);
+    }
 }

package/dist/audio-player.d.ts

@@ -64,6 +64,18 @@ export declare class AudioPlayer extends ListenTarget<AllAudioFileEvents> {
     stopFiles(files: ReadonlyArray<Readonly<AudioSetupParams>>): void;
     /** Stops all active playback without unloading any audio files. */
     stopAllFiles(): void;
+    /** Pauses all active playback for an already-loaded audio file. */
+    pauseFile(file: Readonly<AudioSetupParams>): void;
+    /** Pauses all active playback for the given already-loaded audio files. */
+    pauseFiles(files: ReadonlyArray<Readonly<AudioSetupParams>>): void;
+    /** Pauses all active playback without unloading any audio files. */
+    pauseAllFiles(): void;
+    /** Resumes playback paused for an already-loaded audio file. */
+    resumeFile(file: Readonly<AudioSetupParams>): void;
+    /** Resumes playback paused for the given already-loaded audio files. */
+    resumeFiles(files: ReadonlyArray<Readonly<AudioSetupParams>>): void;
+    /** Resumes all playback paused through this {@link AudioPlayer}. */
+    resumeAllFiles(): void;
     /** Load a batch of audio files. */
     loadFiles(files: ReadonlyArray<Readonly<AudioSetupParams>>, options?: Readonly<PartialWithUndefined<{
         progressCallback: AudioLoadProgressCallback;

package/dist/audio-player.js

@@ -89,6 +89,40 @@ export class AudioPlayer extends ListenTarget {
             audioFile.stop();
         });
     }
+    /** Pauses all active playback for an already-loaded audio file. */
+    pauseFile(file) {
+        const sourceKey = createAudioSourceKey(file);
+        this.audioFiles[sourceKey]?.pause();
+    }
+    /** Pauses all active playback for the given already-loaded audio files. */
+    pauseFiles(files) {
+        files.forEach((file) => {
+            this.pauseFile(file);
+        });
+    }
+    /** Pauses all active playback without unloading any audio files. */
+    pauseAllFiles() {
+        getObjectTypedValues(this.audioFiles).forEach((audioFile) => {
+            audioFile.pause();
+        });
+    }
+    /** Resumes playback paused for an already-loaded audio file. */
+    resumeFile(file) {
+        const sourceKey = createAudioSourceKey(file);
+        this.audioFiles[sourceKey]?.resume();
+    }
+    /** Resumes playback paused for the given already-loaded audio files. */
+    resumeFiles(files) {
+        files.forEach((file) => {
+            this.resumeFile(file);
+        });
+    }
+    /** Resumes all playback paused through this {@link AudioPlayer}. */
+    resumeAllFiles() {
+        getObjectTypedValues(this.audioFiles).forEach((audioFile) => {
+            audioFile.resume();
+        });
+    }
     /** Load a batch of audio files. */
     async loadFiles(files, options = {}) {
         let loadedCount = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@antha/audio",
-    "version": "0.4.3",
+    "version": "0.5.0",
     "description": "An Antha mod for handling audio.",
     "keywords": [
         "vir",
@@ -37,7 +37,7 @@
         "@augment-vir/common": "^32.2.3"
     },
     "devDependencies": {
-        "@antha/engine": "^0.4.3",
+        "@antha/engine": "^0.5.0",
         "@augment-vir/test": "^32.2.3",
         "@web/dev-server-esbuild": "^2.0.0",
         "@web/test-runner": "^1.0.0",
@@ -46,7 +46,7 @@
         "typed-event-target": "^4.3.3"
     },
     "peerDependencies": {
-        "@antha/engine": "^0.4.3",
+        "@antha/engine": "^0.5.0",
         "element-vir": ">=26",
         "typed-event-target": ">=4.3"
     },