@hkdigital/lib-core 0.4.26 → 0.4.28

package/dist/network/loaders/audio/AudioScene.svelte.d.ts

@@ -8,25 +8,23 @@
  * @property {AudioLoader} audioLoader
  * @property {SourceConfig} [config]
  */
-export default class AudioScene {
-    state: string;
-    loaded: boolean;
+export default class AudioScene extends SceneBase {
     muted: boolean;
     targetGain: number;
     /**
-   * Get audio scene loading progress
-   */
-    get progress(): {
-        totalBytesLoaded: number;
-        totalSize: number;
-        sourcesLoaded: number;
-        numberOfSources: number;
-    };
+     * Get the array of memory sources managed by this scene
+     *
+     * @returns {MemorySource[]}
+     */
+    get sources(): MemorySource[];
     /**
-     * Start loading all audio sources
+     * Extract the audio loader from a source object
+     *
+     * @param {MemorySource} source
+     *
+     * @returns {AudioLoader}
      */
-    load(): void;
-    destroy(): void;
+    getLoaderFromSource(source: MemorySource): AudioLoader;
     /**
      * Add in-memory audio source
      * - Uses an AudioLoader instance to load audio data from network
@@ -56,18 +54,33 @@ export default class AudioScene {
      */
     setAudioContext(audioContext?: AudioContext): void;
     /**
-     * Set target gain
+     * Set target gain (volume level) for all audio in this scene
+     * - Currently applies immediately, but "target" allows for future
+     *   smooth transitions using Web Audio API's gain scheduling
+     * - Range: 0.0 (silence) to 1.0 (original) to 1.0+ (amplified)
      *
-     * @param {number} value
+     * @param {number} value - Target gain value (0.0 to 1.0+)
      */
     setTargetGain(value: number): void;
     /**
-     * Get the scene gain
+     * Get the current target gain (volume level)
      *
-     * @returns {number} value
+     * @returns {number} Target gain value (0.0 to 1.0+)
      */
     getTargetGain(): number;
+    /**
+     * Mute all audio in this scene
+     * - Saves current volume level for restoration
+     * - Sets target gain to 0 (silence)
+     * - Safe to call multiple times
+     */
     mute(): void;
+    /**
+     * Unmute all audio in this scene
+     * - Restores volume level from before muting
+     * - Safe to call multiple times
+     * - No effect if scene is not currently muted
+     */
     unmute(): void;
     #private;
 }
@@ -80,4 +93,5 @@ export type MemorySource = {
     audioLoader: AudioLoader;
     config?: SourceConfig;
 };
+import SceneBase from '../base/SceneBase.svelte.js';
 import AudioLoader from './AudioLoader.svelte.js';

package/dist/network/loaders/audio/AudioScene.svelte.js

@@ -1,15 +1,6 @@
 import * as expect from '../../../util/expect.js';
 
-import { LoadingStateMachine } from '../../../state/machines.js';
-
-import {
-	STATE_INITIAL,
-	STATE_LOADING,
-	STATE_LOADED,
-	LOAD,
-	LOADED
-} from '../../../state/machines.js';
-
+import SceneBase from '../base/SceneBase.svelte.js';
 import AudioLoader from './AudioLoader.svelte.js';
 
 /**
@@ -24,15 +15,7 @@ import AudioLoader from './AudioLoader.svelte.js';
  * @property {SourceConfig} [config]
  */
 
-export default class AudioScene {
-	#state = new LoadingStateMachine();
-
-	// @note this exported state is set by onenter
-	state = $state(STATE_INITIAL);
-
-	loaded = $derived.by(() => {
-		return this.state === STATE_LOADED;
-	});
+export default class AudioScene extends SceneBase {
 
 	#targetGain = $state(1);
 
@@ -51,92 +34,35 @@ export default class AudioScene {
 	/** @type {MemorySource[]} */
 	#memorySources = $state([]);
 
-	#progress = $derived.by(() => {
-		// console.log('update progress');
-
-		let totalSize = 0;
-		let totalBytesLoaded = 0;
-		let sourcesLoaded = 0;
-
-		const sources = this.#memorySources;
-		const numberOfSources = sources.length;
-
-		for (let j = 0; j < numberOfSources; j++) {
-			const source = sources[j];
-			const { audioLoader } = source;
-
-			const { bytesLoaded, size, loaded } = audioLoader.progress;
-
-			totalSize += size;
-			totalBytesLoaded += bytesLoaded;
-
-			if (loaded) {
-				sourcesLoaded++;
-			}
-		} // end for
-
-		return {
-			totalBytesLoaded,
-			totalSize,
-			sourcesLoaded,
-			numberOfSources
-		};
-	});
 
 	/**
 	 * Construct AudioScene
 	 */
 	constructor() {
-		const state = this.#state;
-
-		$effect(() => {
-			if (state.current === STATE_LOADING) {
-				// console.log(
-				//   'progress',
-				//   JSON.stringify($state.snapshot(this.#progress))
-				// );
-
-				const { sourcesLoaded, numberOfSources } = this.#progress;
-
-				if (sourcesLoaded === numberOfSources) {
-					// console.debug(`AudioScene: ${numberOfSources} sources loaded`);
-					this.#state.send(LOADED);
-				}
-			}
-		});
-
-		state.onenter = ( currentState ) => {
-      // console.log('onenter', currentState );
-
-			if(currentState === STATE_LOADING )
-			{
-				// console.log('AudioScene:loading');
-				this.#startLoading();
-			}
-
-			this.state = state.current;
-		};
+		super();
 	}
 
-	/* ==== Common loader interface */
+	/* ==== SceneBase implementation */
 
 	/**
-   * Get audio scene loading progress
-   */
-  get progress() {
-    return this.#progress;
-  }
-
-	/**
-	 * Start loading all audio sources
+	 * Get the array of memory sources managed by this scene
+	 *
+	 * @returns {MemorySource[]}
 	 */
-	load() {
-		this.#state.send(LOAD);
+	get sources() {
+		return this.#memorySources;
 	}
 
-	destroy() {
-		// TODO: disconnect all audio sources?
-		// TODO: Unload AUdioLoaders?
+	/**
+	 * Extract the audio loader from a source object
+	 *
+	 * @param {MemorySource} source
+	 *
+	 * @returns {AudioLoader}
+	 */
+	// eslint-disable-next-line no-unused-vars
+	getLoaderFromSource(source) {
+		return source.audioLoader;
 	}
 
 	/* ==== Source definitions */
@@ -204,20 +130,16 @@ export default class AudioScene {
 		this.#audioContext = audioContext;
 	}
 
-	async #startLoading() {
-		// console.log('#startLoading');
-
-		for (const { audioLoader } of this.#memorySources) {
-		  audioLoader.load();
-		}
-	}
 
 	/* ==== Audio specific */
 
 	/**
-	 * Set target gain
+	 * Set target gain (volume level) for all audio in this scene
+	 * - Currently applies immediately, but "target" allows for future 
+	 *   smooth transitions using Web Audio API's gain scheduling
+	 * - Range: 0.0 (silence) to 1.0 (original) to 1.0+ (amplified)
 	 *
-	 * @param {number} value
+	 * @param {number} value - Target gain value (0.0 to 1.0+)
 	 */
 	setTargetGain( value ) {
 		this.#targetGain = value;
@@ -227,15 +149,21 @@ export default class AudioScene {
 	}
 
 	/**
-	 * Get the scene gain
+	 * Get the current target gain (volume level)
 	 *
-	 * @returns {number} value
+	 * @returns {number} Target gain value (0.0 to 1.0+)
 	 */
 	getTargetGain()
 	{
 		return this.#targetGain;
 	}
 
+	/**
+	 * Mute all audio in this scene
+	 * - Saves current volume level for restoration
+	 * - Sets target gain to 0 (silence)
+	 * - Safe to call multiple times
+	 */
 	mute() {
 		if( this.muted )
 		{
@@ -246,6 +174,12 @@ export default class AudioScene {
 		this.setTargetGain(0);
 	}
 
+	/**
+	 * Unmute all audio in this scene
+	 * - Restores volume level from before muting
+	 * - Safe to call multiple times
+	 * - No effect if scene is not currently muted
+	 */
 	unmute() {
 		if( !this.muted )
 		{

package/dist/network/loaders/audio/README.md

@@ -0,0 +1,195 @@
+# Audio Loaders
+
+Audio loading and scene management for web applications using the Web Audio API.
+
+## Overview
+
+The audio loading system consists of two main components:
+
+- **AudioLoader** - Loads individual audio files from network sources
+- **AudioScene** - Manages collections of audio sources with centralized playback control
+
+## AudioScene
+
+`AudioScene` extends `SceneBase` to provide audio-specific functionality including volume control, muting, and Web Audio API integration.
+
+### Key Features
+
+- **Scene-wide volume control** via gain nodes
+- **Mute/unmute functionality** with volume restoration
+- **Web Audio API integration** for precise audio control
+- **Multiple audio source management** with unified loading states
+- **Audio context management** with automatic creation or custom injection
+
+### Audio Context Usage
+
+AudioScene uses the Web Audio API's `AudioContext` for advanced audio processing:
+
+```javascript
+const audioScene = new AudioScene();
+
+// Option 1: Use automatic context creation (default)
+audioScene.load(); // Creates AudioContext internally
+
+// Option 2: Provide your own context for integration
+const customContext = new AudioContext();
+audioScene.setAudioContext(customContext);
+```
+
+### Volume Control (Target Gain)
+
+The scene uses a "target gain" system based on Web Audio API's gain scheduling:
+
+- **Target Gain**: The desired volume level that the audio system transitions towards
+  - `0.0` = silence (muted)
+  - `1.0` = original volume  
+  - `> 1.0` = amplified (use carefully to avoid distortion)
+
+**Why "Target"?**
+The Web Audio API allows smooth transitions between gain values over time. When you set a target gain, the audio system can gradually transition from the current level to the target level, preventing audio pops and clicks.
+
+```javascript
+// Set immediate volume change to 50%
+audioScene.setTargetGain(0.5);
+
+// Future: Could support smooth transitions
+// gainNode.gain.setTargetAtTime(0.5, audioContext.currentTime, 0.3);
+
+// Get current target volume
+const volume = audioScene.getTargetGain(); // 0.5
+
+// Mute (remembers previous volume)
+audioScene.mute();
+
+// Restore previous volume
+audioScene.unmute();
+```
+
+The current implementation sets gain immediately, but the "target" naming prepares for potential smooth volume transitions in future versions.
+
+### Audio Source Management
+
+Define audio sources before loading:
+
+```javascript
+// Add audio sources
+audioScene.defineMemorySource({
+  label: 'background-music',
+  url: '/audio/bg-music.mp3'
+});
+
+audioScene.defineMemorySource({
+  label: 'sound-effect',
+  url: '/audio/beep.wav'
+});
+
+// Load all sources
+audioScene.load();
+
+// Wait for loading completion
+await waitForState(() => audioScene.loaded);
+```
+
+### Playback
+
+Get playable audio sources after loading:
+
+```javascript
+// Get a source node for one-time playback
+const sourceNode = await audioScene.getSourceNode('sound-effect');
+
+// Play immediately
+sourceNode.start();
+
+// Play with delay
+sourceNode.start(audioContext.currentTime + 0.5);
+
+// Cleanup is automatic when playback ends
+```
+
+### Web Audio API Architecture
+
+```
+AudioSources → GainNode → AudioContext.destination → Speakers
+                  ↑
+            Volume Control
+```
+
+Each audio source connects through a gain node that provides scene-wide volume control before reaching the audio output.
+
+### State Management
+
+AudioScene inherits state management from SceneBase:
+
+- `STATE_INITIAL` - Scene created, sources defined
+- `STATE_LOADING` - Audio files downloading
+- `STATE_LOADED` - All sources ready for playback
+- `STATE_ABORTING` - Canceling downloads
+- `STATE_ABORTED` - Downloads canceled
+
+### Preloading with Progress and Abort
+
+AudioScene supports convenient preloading with automatic progress tracking:
+
+```javascript
+// Basic preload - returns promise and abort function
+const { promise, abort } = audioScene.preload();
+
+// Preload with options
+const { promise, abort } = audioScene.preload({
+  timeoutMs: 5000,  // Timeout after 5 seconds
+  onProgress: (progress) => {
+    console.log(`Loading: ${progress.sourcesLoaded}/${progress.numberOfSources}`);
+    console.log(`Bytes: ${progress.totalBytesLoaded}/${progress.totalSize}`);
+  }
+});
+
+// Wait for completion
+try {
+  const loadedScene = await promise;
+  console.log('All audio loaded successfully!');
+} catch (error) {
+  console.error('Preload failed:', error.message);
+}
+
+// Can abort anytime
+document.getElementById('cancelBtn').onclick = () => abort();
+```
+
+**Preload Features:**
+- **Promise-based**: Returns `{ promise, abort }` object
+- **Progress tracking**: Optional callback with loading progress
+- **Timeout support**: Configurable timeout with automatic abort
+- **Manual abort**: Call `abort()` function to cancel loading
+- **Error handling**: Promise rejects on timeout, abort, or loading errors
+
+### Progress Tracking
+
+Monitor loading progress across all sources:
+
+```javascript
+const progress = audioScene.progress;
+console.log(`${progress.sourcesLoaded}/${progress.numberOfSources} loaded`);
+console.log(`${progress.totalBytesLoaded}/${progress.totalSize} bytes`);
+```
+
+## Best Practices
+
+1. **Audio Context Lifecycle**: Create AudioContext in response to user interaction to avoid browser autoplay restrictions
+
+2. **Memory Management**: Audio sources are loaded into memory - consider file sizes for mobile devices
+
+3. **Source Node Usage**: Each `getSourceNode()` call creates a new playable instance - don't reuse source nodes
+
+4. **Volume Levels**: Keep target gain ≤ 1.0 to avoid audio clipping and distortion
+
+5. **Error Handling**: Check scene state before attempting playback
+
+```javascript
+if (audioScene.loaded) {
+  const source = await audioScene.getSourceNode('audio-label');
+  source.start();
+} else {
+  console.warn('Audio scene not ready for playback');
+}
+```

package/dist/network/loaders/base/SceneBase.svelte.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Base class for scene loaders that manage collections of media sources
+ */
+export default class SceneBase {
+    state: string;
+    loaded: boolean;
+    /**
+     * Get the array of sources managed by this scene
+     *
+     * @returns {Array} Array of source objects
+     */
+    get sources(): any[];
+    /**
+     * Extract the loader from a source object
+     *
+     * @param {*} source
+     *
+     * @returns {*} Loader object with progress and state properties
+     */
+    getLoaderFromSource(source: any): any;
+    /**
+     * Get scene loading progress
+     */
+    get progress(): {
+        totalBytesLoaded: number;
+        totalSize: number;
+        sourcesLoaded: number;
+        numberOfSources: number;
+    };
+    /**
+     * Get scene abort progress
+     */
+    get abortProgress(): {
+        sourcesAborted: number;
+        numberOfSources: number;
+    };
+    /**
+     * Start loading all sources
+     */
+    load(): void;
+    /**
+     * Abort loading all sources
+     */
+    abort(): void;
+    /**
+     * Preload all sources with progress tracking and abort capability
+     * - Starts loading and waits for completion
+     * - Supports timeout and progress callbacks
+     * - Returns object with promise and abort function
+     *
+     * @param {object} [options]
+     * @param {number} [options.timeoutMs=10000] - Timeout in milliseconds
+     * @param {Function} [options.onProgress] - Progress callback function
+     *
+     * @returns {object} Object with promise and abort function
+     * @returns {Promise<SceneBase>} returns.promise - Promise that resolves when loaded
+     * @returns {Function} returns.abort - Function to abort preloading
+     */
+    preload({ timeoutMs, onProgress }?: {
+        timeoutMs?: number;
+        onProgress?: Function;
+    }): object;
+    destroy(): void;
+    #private;
+}