audio-channel-queue 1.12.0 → 1.12.1-beta.2

package/dist/web-audio.js

@@ -0,0 +1,327 @@
+"use strict";
+/**
+ * @fileoverview Web Audio API support for enhanced volume control on iOS and other platforms
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cleanupWebAudioNodes = exports.resumeAudioContext = exports.getWebAudioVolume = exports.setWebAudioVolume = exports.createWebAudioNodes = exports.getAudioContext = exports.getWebAudioConfig = exports.setWebAudioConfig = exports.getWebAudioSupport = exports.shouldUseWebAudio = exports.isWebAudioSupported = exports.isIOSDevice = void 0;
+/**
+ * Global Web Audio API configuration
+ */
+let webAudioConfig = {
+    autoDetectIOS: true,
+    enabled: true,
+    forceWebAudio: false
+};
+/**
+ * Detects if the current device is iOS
+ * @returns True if the device is iOS, false otherwise
+ * @example
+ * ```typescript
+ * if (isIOSDevice()) {
+ *   console.log('Running on iOS device');
+ * }
+ * ```
+ */
+const isIOSDevice = () => {
+    if (typeof navigator === 'undefined')
+        return false;
+    // Modern approach using User-Agent Client Hints API
+    const navWithUA = navigator;
+    if ('userAgentData' in navigator && navWithUA.userAgentData) {
+        return navWithUA.userAgentData.platform === 'iOS';
+    }
+    // Fallback to userAgent string parsing
+    const userAgent = navigator.userAgent || '';
+    const isIOS = /iPad|iPhone|iPod/.test(userAgent);
+    // Additional check for modern iPads that report as Mac
+    const isMacWithTouch = /Macintosh/.test(userAgent) && 'maxTouchPoints' in navigator && navigator.maxTouchPoints > 1;
+    return isIOS || isMacWithTouch;
+};
+exports.isIOSDevice = isIOSDevice;
+/**
+ * Checks if Web Audio API is available in the current environment
+ * @returns True if Web Audio API is supported, false otherwise
+ * @example
+ * ```typescript
+ * if (isWebAudioSupported()) {
+ *   console.log('Web Audio API is available');
+ * }
+ * ```
+ */
+const isWebAudioSupported = () => {
+    if (typeof window === 'undefined') {
+        // In Node.js environment (tests), check if Web Audio API globals are available
+        const globalThis = global;
+        return (typeof globalThis.AudioContext !== 'undefined' ||
+            typeof globalThis.webkitAudioContext !== 'undefined');
+    }
+    const windowWithWebkit = window;
+    return (typeof AudioContext !== 'undefined' ||
+        typeof windowWithWebkit.webkitAudioContext !== 'undefined');
+};
+exports.isWebAudioSupported = isWebAudioSupported;
+/**
+ * Determines if Web Audio API should be used based on configuration and device detection
+ * @returns True if Web Audio API should be used, false otherwise
+ * @example
+ * ```typescript
+ * if (shouldUseWebAudio()) {
+ *   // Use Web Audio API for volume control
+ * }
+ * ```
+ */
+const shouldUseWebAudio = () => {
+    if (!webAudioConfig.enabled)
+        return false;
+    if (!(0, exports.isWebAudioSupported)())
+        return false;
+    if (webAudioConfig.forceWebAudio)
+        return true;
+    if (webAudioConfig.autoDetectIOS && (0, exports.isIOSDevice)())
+        return true;
+    return false;
+};
+exports.shouldUseWebAudio = shouldUseWebAudio;
+/**
+ * Gets information about Web Audio API support and usage
+ * @returns Object containing Web Audio API support information
+ * @example
+ * ```typescript
+ * const support = getWebAudioSupport();
+ * console.log(`Using Web Audio: ${support.usingWebAudio}`);
+ * console.log(`Reason: ${support.reason}`);
+ * ```
+ */
+const getWebAudioSupport = () => {
+    const available = (0, exports.isWebAudioSupported)();
+    const isIOS = (0, exports.isIOSDevice)();
+    const usingWebAudio = (0, exports.shouldUseWebAudio)();
+    let reason = '';
+    if (!webAudioConfig.enabled) {
+        reason = 'Web Audio API disabled in configuration';
+    }
+    else if (!available) {
+        reason = 'Web Audio API not supported in this environment';
+    }
+    else if (webAudioConfig.forceWebAudio) {
+        reason = 'Web Audio API forced via configuration';
+    }
+    else if (isIOS && webAudioConfig.autoDetectIOS) {
+        reason = 'iOS device detected - using Web Audio API for volume control';
+    }
+    else {
+        reason = 'Using standard HTMLAudioElement volume control';
+    }
+    return {
+        available,
+        isIOS,
+        reason,
+        usingWebAudio
+    };
+};
+exports.getWebAudioSupport = getWebAudioSupport;
+/**
+ * Configures Web Audio API usage
+ * @param config - Configuration options for Web Audio API
+ * @example
+ * ```typescript
+ * // Force Web Audio API usage on all devices
+ * setWebAudioConfig({ forceWebAudio: true });
+ *
+ * // Disable Web Audio API entirely
+ * setWebAudioConfig({ enabled: false });
+ * ```
+ */
+const setWebAudioConfig = (config) => {
+    webAudioConfig = Object.assign(Object.assign({}, webAudioConfig), config);
+};
+exports.setWebAudioConfig = setWebAudioConfig;
+/**
+ * Gets the current Web Audio API configuration
+ * @returns Current Web Audio API configuration
+ * @example
+ * ```typescript
+ * const config = getWebAudioConfig();
+ * console.log(`Web Audio enabled: ${config.enabled}`);
+ * ```
+ */
+const getWebAudioConfig = () => {
+    return Object.assign({}, webAudioConfig);
+};
+exports.getWebAudioConfig = getWebAudioConfig;
+/**
+ * Creates or gets an AudioContext for Web Audio API operations
+ * @returns AudioContext instance or null if not supported
+ * @example
+ * ```typescript
+ * const context = getAudioContext();
+ * if (context) {
+ *   console.log('Audio context created successfully');
+ * }
+ * ```
+ */
+const getAudioContext = () => {
+    if (!(0, exports.isWebAudioSupported)())
+        return null;
+    try {
+        // In Node.js environment (tests), return null to allow mocking
+        if (typeof window === 'undefined') {
+            return null;
+        }
+        // Use existing AudioContext or create new one
+        const windowWithWebkit = window;
+        const AudioContextClass = window.AudioContext || windowWithWebkit.webkitAudioContext;
+        return new AudioContextClass();
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.warn('Failed to create AudioContext:', error);
+        return null;
+    }
+};
+exports.getAudioContext = getAudioContext;
+/**
+ * Creates Web Audio API nodes for an audio element
+ * @param audioElement - The HTML audio element to create nodes for
+ * @param audioContext - The AudioContext to use
+ * @returns Web Audio API node set or null if creation fails
+ * @example
+ * ```typescript
+ * const audio = new Audio('song.mp3');
+ * const context = getAudioContext();
+ * if (context) {
+ *   const nodes = createWebAudioNodes(audio, context);
+ *   if (nodes) {
+ *     nodes.gainNode.gain.value = 0.5; // Set volume to 50%
+ *   }
+ * }
+ * ```
+ */
+const createWebAudioNodes = (audioElement, audioContext) => {
+    try {
+        // Create media element source node
+        const sourceNode = audioContext.createMediaElementSource(audioElement);
+        // Create gain node for volume control
+        const gainNode = audioContext.createGain();
+        // Connect source to gain node
+        sourceNode.connect(gainNode);
+        // Connect gain node to destination (speakers)
+        gainNode.connect(audioContext.destination);
+        return {
+            gainNode,
+            sourceNode
+        };
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.warn('Failed to create Web Audio nodes:', error);
+        return null;
+    }
+};
+exports.createWebAudioNodes = createWebAudioNodes;
+/**
+ * Sets volume using Web Audio API gain node
+ * @param gainNode - The gain node to set volume on
+ * @param volume - Volume level (0-1)
+ * @param transitionDuration - Optional transition duration in milliseconds
+ * @example
+ * ```typescript
+ * const nodes = createWebAudioNodes(audio, context);
+ * if (nodes) {
+ *   setWebAudioVolume(nodes.gainNode, 0.5); // Set to 50% volume
+ *   setWebAudioVolume(nodes.gainNode, 0.2, 300); // Fade to 20% over 300ms
+ * }
+ * ```
+ */
+const setWebAudioVolume = (gainNode, volume, transitionDuration) => {
+    const clampedVolume = Math.max(0, Math.min(1, volume));
+    const currentTime = gainNode.context.currentTime;
+    if (transitionDuration && transitionDuration > 0) {
+        // Smooth transition using Web Audio API's built-in scheduling
+        gainNode.gain.cancelScheduledValues(currentTime);
+        gainNode.gain.setValueAtTime(gainNode.gain.value, currentTime);
+        gainNode.gain.linearRampToValueAtTime(clampedVolume, currentTime + transitionDuration / 1000);
+    }
+    else {
+        // Instant change
+        gainNode.gain.cancelScheduledValues(currentTime);
+        gainNode.gain.setValueAtTime(clampedVolume, currentTime);
+    }
+};
+exports.setWebAudioVolume = setWebAudioVolume;
+/**
+ * Gets the current volume from a Web Audio API gain node
+ * @param gainNode - The gain node to get volume from
+ * @returns Current volume level (0-1)
+ * @example
+ * ```typescript
+ * const nodes = createWebAudioNodes(audio, context);
+ * if (nodes) {
+ *   const volume = getWebAudioVolume(nodes.gainNode);
+ *   console.log(`Current volume: ${volume * 100}%`);
+ * }
+ * ```
+ */
+const getWebAudioVolume = (gainNode) => {
+    return gainNode.gain.value;
+};
+exports.getWebAudioVolume = getWebAudioVolume;
+/**
+ * Resumes an AudioContext if it's in suspended state (required for autoplay policy)
+ * @param audioContext - The AudioContext to resume
+ * @returns Promise that resolves when context is resumed
+ * @example
+ * ```typescript
+ * const context = getAudioContext();
+ * if (context) {
+ *   await resumeAudioContext(context);
+ * }
+ * ```
+ */
+const resumeAudioContext = (audioContext) => __awaiter(void 0, void 0, void 0, function* () {
+    if (audioContext.state === 'suspended') {
+        try {
+            yield audioContext.resume();
+        }
+        catch (error) {
+            // eslint-disable-next-line no-console
+            console.warn('Failed to resume AudioContext:', error);
+            // Don't throw - handle gracefully and continue
+        }
+    }
+});
+exports.resumeAudioContext = resumeAudioContext;
+/**
+ * Cleans up Web Audio API nodes and connections
+ * @param nodes - The Web Audio API node set to clean up
+ * @example
+ * ```typescript
+ * const nodes = createWebAudioNodes(audio, context);
+ * if (nodes) {
+ *   // Use nodes...
+ *   cleanupWebAudioNodes(nodes); // Clean up when done
+ * }
+ * ```
+ */
+const cleanupWebAudioNodes = (nodes) => {
+    try {
+        // Disconnect all nodes
+        nodes.sourceNode.disconnect();
+        nodes.gainNode.disconnect();
+    }
+    catch (error) {
+        // Ignore errors during cleanup
+        // eslint-disable-next-line no-console
+        console.warn('Error during Web Audio cleanup:', error);
+    }
+};
+exports.cleanupWebAudioNodes = cleanupWebAudioNodes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audio-channel-queue",
-  "version": "1.12.0",
+  "version": "1.12.1-beta.2",
   "description": "Allows you to queue audio files to different playback channels.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,7 +10,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "prepare": "npm run build",
+    "prepare": "husky",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
@@ -26,6 +26,7 @@
     "publish:minor": "npm version minor && npm run publish:release",
     "publish:major": "npm version major && npm run publish:release",
     "publish:release": "npm run validate && npm run build && npm publish",
+    "publish:beta": "npm version prerelease --preid=beta && npm publish --tag beta",
     "publish:dry": "npm run validate && npm run build && npm publish --dry-run"
   },
   "repository": {
@@ -49,8 +50,10 @@
   },
   "devDependencies": {
     "@types/jest": "^29.5.13",
+    "husky": "^9.1.7",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "lint-staged": "^16.2.7",
     "rimraf": "^6.0.1",
     "ts-jest": "^29.2.5",
     "typescript": "^5.6.2",

package/src/core.ts

@@ -12,7 +12,13 @@ import {
   setupProgressTracking,
   cleanupProgressTracking
 } from './events';
-import { applyVolumeDucking, restoreVolumeLevels, cancelVolumeTransition } from './volume';
+import {
+  applyVolumeDucking,
+  restoreVolumeLevels,
+  cancelVolumeTransition,
+  initializeWebAudioForAudio,
+  cleanupWebAudioForAudio
+} from './volume';
 import { setupAudioErrorHandling, handleAudioError } from './errors';
 
 /**
@@ -283,6 +289,9 @@ export const queueAudio = async (
     await handleAudioError(audio, channelNumber, validatedUrl, error);
   });
 
+  // Initialize Web Audio API support if needed
+  await initializeWebAudioForAudio(audio, channelNumber);
+
   // Apply options if provided
   if (options) {
     if (typeof options.loop === 'boolean') {
@@ -440,6 +449,7 @@ export const playAudioQueue = async (channelNumber: number): Promise<void> => {
         // For non-looping audio, remove from queue and play next
         currentAudio.pause();
         cleanupProgressTracking(currentAudio, channelNumber, audioChannels);
+        cleanupWebAudioForAudio(currentAudio, channelNumber);
         channel.queue.shift();
         channel.isPaused = false; // Reset pause state
 

package/src/errors.ts

@@ -34,8 +34,6 @@ let globalErrorRecovery: ErrorRecoveryOptions = {
 
 const retryAttempts: WeakMap<HTMLAudioElement, number> = new WeakMap();
 
-const loadTimeouts: WeakMap<HTMLAudioElement, number> = new WeakMap();
-
 /**
  * Subscribes to audio error events for a specific channel
  * @param channelNumber - The channel number to listen to (defaults to 0)
@@ -310,42 +308,8 @@ export const setupAudioErrorHandling = (
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
   if (!channel) return;
 
-  // Set up loading timeout with test environment compatibility
-  let timeoutId: number;
-  if (typeof setTimeout !== 'undefined') {
-    timeoutId = setTimeout(() => {
-      if (audio.networkState === HTMLMediaElement.NETWORK_LOADING) {
-        const timeoutError = new Error(
-          `Audio loading timeout after ${globalRetryConfig.timeoutMs}ms`
-        );
-        handleAudioError(audio, channelNumber, originalUrl, timeoutError);
-      }
-    }, globalRetryConfig.timeoutMs) as unknown as number;
-
-    loadTimeouts.set(audio, timeoutId);
-  }
-
-  // Clear timeout when metadata loads successfully
-  const handleLoadSuccess = (): void => {
-    if (typeof setTimeout !== 'undefined') {
-      const timeoutId = loadTimeouts.get(audio);
-      if (timeoutId) {
-        clearTimeout(timeoutId);
-        loadTimeouts.delete(audio);
-      }
-    }
-  };
-
   // Handle various error events
   const handleError = (_event: Event): void => {
-    if (typeof setTimeout !== 'undefined') {
-      const timeoutId = loadTimeouts.get(audio);
-      if (timeoutId) {
-        clearTimeout(timeoutId);
-        loadTimeouts.delete(audio);
-      }
-    }
-
     const error = new Error(`Audio loading failed: ${audio.error?.message || 'Unknown error'}`);
     handleAudioError(audio, channelNumber, originalUrl, error);
   };
@@ -364,8 +328,6 @@ export const setupAudioErrorHandling = (
   audio.addEventListener('error', handleError);
   audio.addEventListener('abort', handleAbort);
   audio.addEventListener('stalled', handleStall);
-  audio.addEventListener('loadedmetadata', handleLoadSuccess);
-  audio.addEventListener('canplay', handleLoadSuccess);
 
   // Custom play error handling
   if (onError) {
@@ -423,7 +385,7 @@ export const handleAudioError = async (
     currentAttempts < retryConfig.maxRetries &&
     globalErrorRecovery.autoRetry
   ) {
-    const delay = retryConfig.exponentialBackoff
+    const delay: number = retryConfig.exponentialBackoff
       ? retryConfig.baseDelay * Math.pow(2, currentAttempts)
       : retryConfig.baseDelay;
 
@@ -481,21 +443,11 @@ export const createProtectedAudioElement = async (
   const audio = new Audio();
 
   return new Promise((resolve, reject) => {
-    const cleanup = (): void => {
-      const timeoutId = loadTimeouts.get(audio);
-      if (timeoutId) {
-        clearTimeout(timeoutId);
-        loadTimeouts.delete(audio);
-      }
-    };
-
     const handleSuccess = (): void => {
-      cleanup();
       resolve(audio);
     };
 
     const handleError = (error: Error): void => {
-      cleanup();
       reject(error);
     };
 

package/src/index.ts

@@ -66,12 +66,30 @@ export {
   getAllChannelsVolume,
   getChannelVolume,
   getFadeConfig,
+  getGlobalVolume,
   setAllChannelsVolume,
   setChannelVolume,
+  setGlobalVolume,
   setVolumeDucking,
   transitionVolume
 } from './volume';
 
+// Web Audio API support functions
+export {
+  cleanupWebAudioNodes,
+  createWebAudioNodes,
+  getAudioContext,
+  getWebAudioConfig,
+  getWebAudioSupport,
+  getWebAudioVolume,
+  isIOSDevice,
+  isWebAudioSupported,
+  resumeAudioContext,
+  setWebAudioConfig,
+  setWebAudioVolume,
+  shouldUseWebAudio
+} from './web-audio';
+
 // Audio information and progress tracking functions
 export {
   getAllChannelsInfo,
@@ -122,12 +140,15 @@ export type {
   FadeConfig,
   ProgressCallback,
   QueueChangeCallback,
+  QueueConfig,
   QueueItem,
   QueueManipulationResult,
   QueueSnapshot,
   RetryConfig,
   VolumeConfig,
-  QueueConfig
+  WebAudioConfig,
+  WebAudioNodeSet,
+  WebAudioSupport
 } from './types';
 
 // Enums and constants

package/src/types.ts

@@ -285,6 +285,42 @@ export interface ErrorRecoveryOptions {
  */
 export type AudioErrorCallback = (errorInfo: AudioErrorInfo) => void;
 
+/**
+ * Web Audio API configuration options
+ */
+export interface WebAudioConfig {
+  /** Whether to automatically use Web Audio API on iOS devices */
+  autoDetectIOS: boolean;
+  /** Whether Web Audio API support is enabled */
+  enabled: boolean;
+  /** Whether to force Web Audio API usage on all devices */
+  forceWebAudio: boolean;
+}
+
+/**
+ * Web Audio API support information
+ */
+export interface WebAudioSupport {
+  /** Whether Web Audio API is available in the current environment */
+  available: boolean;
+  /** Whether the current device is iOS */
+  isIOS: boolean;
+  /** Whether Web Audio API is currently being used */
+  usingWebAudio: boolean;
+  /** Reason for current Web Audio API usage state */
+  reason: string;
+}
+
+/**
+ * Web Audio API node set for audio element control
+ */
+export interface WebAudioNodeSet {
+  /** Gain node for volume control */
+  gainNode: GainNode;
+  /** Media element source node */
+  sourceNode: MediaElementAudioSourceNode;
+}
+
 /**
  * Extended audio channel with comprehensive queue management, callback support, and state tracking
  */
@@ -317,6 +353,10 @@ export interface ExtendedAudioQueueChannel {
   retryConfig?: RetryConfig;
   /** Current volume level for the channel (0-1) */
   volume: number;
+  /** Web Audio API context for this channel */
+  webAudioContext?: AudioContext;
+  /** Map of Web Audio API nodes for each audio element */
+  webAudioNodes?: Map<HTMLAudioElement, WebAudioNodeSet>;
 }
 
 /**