audio-channel-queue 1.12.1-beta.0 → 1.12.1-beta.3

package/README.md

@@ -5,20 +5,20 @@ The purpose of this package is to help manage the playback of audio files.
 
 📚 [Docs](https://tonycarpenter21.github.io/audio-queue-docs/)
 
-## 🌟 Key Features
+## Key Features
 
-- ✅ **Multi-channel queue management** - Independent audio queues for concurrent playback
-- ✅ **Pause/Resume functionality** - Full playback control for individual channels or all channels
-- ✅ **Volume control with ducking** - Dynamic volume management and automatic background audio reduction
-- ✅ **Loop support** - Seamless audio looping for background music and ambient sounds
-- ✅ **Priority queueing** - Add urgent audio to the front of any queue
-- ✅ **Real-time progress tracking** - Comprehensive playback monitoring and metadata
-- ✅ **Event-driven architecture** - Extensive callback system for UI integration
-- ✅ **TypeScript support** - Full type definitions and IntelliSense support
-- ✅ **Zero dependencies** - Lightweight and self-contained
-- ✅ **Backward compatible** - All existing APIs continue to work
+- **Multi-channel queue management** - Independent audio queues for concurrent playback
+- **Pause/Resume functionality** - Full playback control for individual channels or all channels
+- **Volume control with ducking** - Dynamic volume management, global volume control, and automatic background audio reduction
+- **Loop support** - Seamless audio looping for background music and ambient sounds
+- **Priority queueing** - Add urgent audio to the front of any queue
+- **Real-time progress tracking** - Comprehensive playback monitoring and metadata
+- **Event-driven architecture** - Extensive callback system for UI integration
+- **TypeScript support** - Full type definitions and IntelliSense support
+- **Zero dependencies** - Lightweight and self-contained
+- **Backward compatible** - All existing APIs continue to work
 
-This package offers TypeScript support 📘, boasts zero dependencies 🚫, and is released under the MIT license 📜. As an added bonus, it's NON-GMO 🌱 and 100% Free Range Organic 🐓.
+This package offers TypeScript support, has zero dependencies, and is released under the MIT license.
 
 To preview this package and see how it works with visualized code examples, check out the demo that can be found here: [Audio Channel Queue Demo](https://tonycarpenter21.github.io/audio-queue-demo/). (A link to the demo repo can be found here: [Audio Channel Queue Demo Repo](https://github.com/tonycarpenter21/audio-queue-demo).)
 
@@ -32,18 +32,18 @@ Documentation can be found [here](https://tonycarpenter21.github.io/audio-queue-
 
 This package is designed for **browser environments** and uses the Web Audio API (`HTMLAudioElement`). It is **not** intended for Node.js server-side use.
 
-### ✅ **Supported Browsers:**
+### **Supported Browsers:**
 - **Chrome 51+** (June 2016)
 - **Firefox 54+** (June 2017)  
 - **Safari 10+** (September 2016)
 - **Edge 15+** (April 2017)
 - **Mobile browsers** with HTML5 audio support
 
-### 🛠️ **Development Requirements:**
+### **Development Requirements:**
 - **Node.js 14+** (for building and testing only)
 - **TypeScript 4.5+** (included in devDependencies)
 
-### ⚠️ **Not Supported:**
+### **Not Supported:**
 - Node.js server environments (no HTMLAudioElement)
 - Internet Explorer (lacks ES6 support)
 - Web Workers (no DOM access)
@@ -197,6 +197,47 @@ await setAllChannelsVolume(0.6); // Set all channels to 60% volume
 await setAllChannelsVolume(0.0); // Mute all channels
 ```
 
+### Global Volume Control
+```typescript
+// Set a global volume multiplier that affects all channels while preserving their relative levels.
+setGlobalVolume(volume);
+await setGlobalVolume(0.5); // Set global volume to 50%
+```
+
+```typescript
+// Get the current global volume level.
+getGlobalVolume();
+const globalVol = getGlobalVolume(); // Returns current global volume (0-1)
+console.log(`Global volume: ${(getGlobalVolume() * 100).toFixed(0)}%`);
+```
+
+**How Global Volume Works:**
+The global volume acts as a **global volume multiplier** - it scales all channel volumes proportionally while preserving their individual settings. This is perfect for implementing a global volume slider in your UI.
+
+```typescript
+// Example: Setting up different audio types with a global volume control
+await setChannelVolume(0, 0.3); // SFX channel at 30%
+await setChannelVolume(1, 0.7); // Music channel at 70%
+await setChannelVolume(2, 0.5); // Voice channel at 50%
+
+// User adjusts global volume slider to 50%
+await setGlobalVolume(0.5);
+
+// Actual playback volumes become:
+// - SFX: 30% × 50% = 15%
+// - Music: 70% × 50% = 35%
+// - Voice: 50% × 50% = 25%
+
+// Channel volumes remain at their original settings (0.3, 0.7, 0.5)
+// So when global volume is increased, ratios are preserved
+await setGlobalVolume(1.0); // Back to full volume
+// - SFX: 30% × 100% = 30%
+// - Music: 70% × 100% = 70%
+// - Voice: 50% × 100% = 50%
+```
+
+**Note:** `setAllChannelsVolume()` sets all channels to the **same** volume, while `setGlobalVolume()` **multiplies** all channels by the same amount, preserving their relative differences.
+
 ### Volume Ducking (Background Audio Reduction)
 ```typescript
 // Automatically reduce other channels' volume when priority audio plays.

package/dist/core.js

@@ -318,9 +318,10 @@ const playAudioQueue = (channelNumber) => __awaiter(void 0, void 0, void 0, func
     if (!channel || channel.queue.length === 0)
         return;
     const currentAudio = channel.queue[0];
-    // Apply channel volume if not already set
+    // Apply channel volume with global volume multiplier if not already set
     if (currentAudio.volume === 1.0 && channel.volume !== undefined) {
-        currentAudio.volume = channel.volume;
+        const globalVolume = (0, volume_1.getGlobalVolume)();
+        currentAudio.volume = channel.volume * globalVolume;
     }
     (0, events_1.setupProgressTracking)(currentAudio, channelNumber, info_1.audioChannels);
     // Apply volume ducking when audio starts

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { queueAudio, queueAudioPriority, stopCurrentAudioInChannel, stopAllAudio
 export { clearQueueAfterCurrent, getQueueItemInfo, getQueueLength, removeQueuedItem, reorderQueue, swapQueueItems } from './queue-manipulation';
 export { getErrorRecovery, getRetryConfig, offAudioError, onAudioError, retryFailedAudio, setErrorRecovery, setRetryConfig } from './errors';
 export { getAllChannelsPauseState, isChannelPaused, pauseAllChannels, pauseAllWithFade, pauseChannel, pauseWithFade, resumeAllChannels, resumeAllWithFade, resumeChannel, resumeWithFade, togglePauseAllChannels, togglePauseAllWithFade, togglePauseChannel, togglePauseWithFade } from './pause';
-export { cancelAllVolumeTransitions, cancelVolumeTransition, clearVolumeDucking, getAllChannelsVolume, getChannelVolume, getFadeConfig, setAllChannelsVolume, setChannelVolume, setVolumeDucking, transitionVolume } from './volume';
+export { cancelAllVolumeTransitions, cancelVolumeTransition, clearVolumeDucking, getAllChannelsVolume, getChannelVolume, getFadeConfig, getGlobalVolume, setAllChannelsVolume, setChannelVolume, setGlobalVolume, setVolumeDucking, transitionVolume } from './volume';
 export { cleanupWebAudioNodes, createWebAudioNodes, getAudioContext, getWebAudioConfig, getWebAudioSupport, getWebAudioVolume, isIOSDevice, isWebAudioSupported, resumeAudioContext, setWebAudioConfig, setWebAudioVolume, shouldUseWebAudio } from './web-audio';
 export { getAllChannelsInfo, getCurrentAudioInfo, getQueueSnapshot, offAudioComplete, offAudioPause, offAudioProgress, offAudioResume, offAudioStart, offQueueChange, onAudioComplete, onAudioPause, onAudioProgress, onAudioResume, onAudioStart, onQueueChange } from './info';
 export { audioChannels } from './info';

package/dist/index.js

@@ -5,8 +5,8 @@
  * volume management with ducking, progress tracking, and comprehensive event system
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createWebAudioNodes = exports.cleanupWebAudioNodes = exports.transitionVolume = exports.setVolumeDucking = exports.setChannelVolume = exports.setAllChannelsVolume = exports.getFadeConfig = exports.getChannelVolume = exports.getAllChannelsVolume = exports.clearVolumeDucking = exports.cancelVolumeTransition = exports.cancelAllVolumeTransitions = exports.togglePauseWithFade = exports.togglePauseChannel = exports.togglePauseAllWithFade = exports.togglePauseAllChannels = exports.resumeWithFade = exports.resumeChannel = exports.resumeAllWithFade = exports.resumeAllChannels = exports.pauseWithFade = exports.pauseChannel = exports.pauseAllWithFade = exports.pauseAllChannels = exports.isChannelPaused = exports.getAllChannelsPauseState = exports.setRetryConfig = exports.setErrorRecovery = exports.retryFailedAudio = exports.onAudioError = exports.offAudioError = exports.getRetryConfig = exports.getErrorRecovery = exports.swapQueueItems = exports.reorderQueue = exports.removeQueuedItem = exports.getQueueLength = exports.getQueueItemInfo = exports.clearQueueAfterCurrent = exports.setChannelQueueLimit = exports.getQueueConfig = exports.setQueueConfig = exports.destroyAllChannels = exports.destroyChannel = exports.playAudioQueue = exports.stopAllAudio = exports.stopAllAudioInChannel = exports.stopCurrentAudioInChannel = exports.queueAudioPriority = exports.queueAudio = void 0;
-exports.GLOBAL_PROGRESS_KEY = exports.TimerType = exports.MAX_CHANNELS = exports.FadeType = exports.EasingType = exports.AudioErrorType = exports.validateAudioUrl = exports.sanitizeForDisplay = exports.getAudioInfoFromElement = exports.extractFileName = exports.createQueueSnapshot = exports.cleanWebpackFilename = exports.audioChannels = exports.onQueueChange = exports.onAudioStart = exports.onAudioResume = exports.onAudioProgress = exports.onAudioPause = exports.onAudioComplete = exports.offQueueChange = exports.offAudioStart = exports.offAudioResume = exports.offAudioProgress = exports.offAudioPause = exports.offAudioComplete = exports.getQueueSnapshot = exports.getCurrentAudioInfo = exports.getAllChannelsInfo = exports.shouldUseWebAudio = exports.setWebAudioVolume = exports.setWebAudioConfig = exports.resumeAudioContext = exports.isWebAudioSupported = exports.isIOSDevice = exports.getWebAudioVolume = exports.getWebAudioSupport = exports.getWebAudioConfig = exports.getAudioContext = void 0;
+exports.transitionVolume = exports.setVolumeDucking = exports.setGlobalVolume = exports.setChannelVolume = exports.setAllChannelsVolume = exports.getGlobalVolume = exports.getFadeConfig = exports.getChannelVolume = exports.getAllChannelsVolume = exports.clearVolumeDucking = exports.cancelVolumeTransition = exports.cancelAllVolumeTransitions = exports.togglePauseWithFade = exports.togglePauseChannel = exports.togglePauseAllWithFade = exports.togglePauseAllChannels = exports.resumeWithFade = exports.resumeChannel = exports.resumeAllWithFade = exports.resumeAllChannels = exports.pauseWithFade = exports.pauseChannel = exports.pauseAllWithFade = exports.pauseAllChannels = exports.isChannelPaused = exports.getAllChannelsPauseState = exports.setRetryConfig = exports.setErrorRecovery = exports.retryFailedAudio = exports.onAudioError = exports.offAudioError = exports.getRetryConfig = exports.getErrorRecovery = exports.swapQueueItems = exports.reorderQueue = exports.removeQueuedItem = exports.getQueueLength = exports.getQueueItemInfo = exports.clearQueueAfterCurrent = exports.setChannelQueueLimit = exports.getQueueConfig = exports.setQueueConfig = exports.destroyAllChannels = exports.destroyChannel = exports.playAudioQueue = exports.stopAllAudio = exports.stopAllAudioInChannel = exports.stopCurrentAudioInChannel = exports.queueAudioPriority = exports.queueAudio = void 0;
+exports.GLOBAL_PROGRESS_KEY = exports.TimerType = exports.MAX_CHANNELS = exports.FadeType = exports.EasingType = exports.AudioErrorType = exports.validateAudioUrl = exports.sanitizeForDisplay = exports.getAudioInfoFromElement = exports.extractFileName = exports.createQueueSnapshot = exports.cleanWebpackFilename = exports.audioChannels = exports.onQueueChange = exports.onAudioStart = exports.onAudioResume = exports.onAudioProgress = exports.onAudioPause = exports.onAudioComplete = exports.offQueueChange = exports.offAudioStart = exports.offAudioResume = exports.offAudioProgress = exports.offAudioPause = exports.offAudioComplete = exports.getQueueSnapshot = exports.getCurrentAudioInfo = exports.getAllChannelsInfo = exports.shouldUseWebAudio = exports.setWebAudioVolume = exports.setWebAudioConfig = exports.resumeAudioContext = exports.isWebAudioSupported = exports.isIOSDevice = exports.getWebAudioVolume = exports.getWebAudioSupport = exports.getWebAudioConfig = exports.getAudioContext = exports.createWebAudioNodes = exports.cleanupWebAudioNodes = void 0;
 // Core queue management functions
 var core_1 = require("./core");
 Object.defineProperty(exports, "queueAudio", { enumerable: true, get: function () { return core_1.queueAudio; } });
@@ -61,8 +61,10 @@ Object.defineProperty(exports, "clearVolumeDucking", { enumerable: true, get: fu
 Object.defineProperty(exports, "getAllChannelsVolume", { enumerable: true, get: function () { return volume_1.getAllChannelsVolume; } });
 Object.defineProperty(exports, "getChannelVolume", { enumerable: true, get: function () { return volume_1.getChannelVolume; } });
 Object.defineProperty(exports, "getFadeConfig", { enumerable: true, get: function () { return volume_1.getFadeConfig; } });
+Object.defineProperty(exports, "getGlobalVolume", { enumerable: true, get: function () { return volume_1.getGlobalVolume; } });
 Object.defineProperty(exports, "setAllChannelsVolume", { enumerable: true, get: function () { return volume_1.setAllChannelsVolume; } });
 Object.defineProperty(exports, "setChannelVolume", { enumerable: true, get: function () { return volume_1.setChannelVolume; } });
+Object.defineProperty(exports, "setGlobalVolume", { enumerable: true, get: function () { return volume_1.setGlobalVolume; } });
 Object.defineProperty(exports, "setVolumeDucking", { enumerable: true, get: function () { return volume_1.setVolumeDucking; } });
 Object.defineProperty(exports, "transitionVolume", { enumerable: true, get: function () { return volume_1.transitionVolume; } });
 // Web Audio API support functions

package/dist/volume.d.ts

@@ -74,6 +74,31 @@ export declare const getAllChannelsVolume: () => number[];
  * ```
  */
 export declare const setAllChannelsVolume: (volume: number) => Promise<void>;
+/**
+ * Sets the global volume multiplier that affects all channels
+ * This acts as a global volume control - individual channel volumes are multiplied by this value
+ * @param volume - Global volume level (0-1, will be clamped to this range)
+ * @example
+ * ```typescript
+ * // Set channel-specific volumes
+ * await setChannelVolume(0, 0.8); // SFX at 80%
+ * await setChannelVolume(1, 0.6); // Music at 60%
+ *
+ * // Apply global volume of 50% - all channels play at half their set volume
+ * await setGlobalVolume(0.5); // SFX now plays at 40%, music at 30%
+ * ```
+ */
+export declare const setGlobalVolume: (volume: number) => Promise<void>;
+/**
+ * Gets the current global volume multiplier
+ * @returns Current global volume level (0-1), defaults to 1.0
+ * @example
+ * ```typescript
+ * const globalVol = getGlobalVolume();
+ * console.log(`Global volume is ${globalVol * 100}%`);
+ * ```
+ */
+export declare const getGlobalVolume: () => number;
 /**
  * Configures volume ducking for channels. When the priority channel plays audio,
  * all other channels will be automatically reduced to the ducking volume level

package/dist/volume.js

@@ -12,7 +12,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cleanupWebAudioForAudio = exports.initializeWebAudioForAudio = exports.cancelAllVolumeTransitions = exports.cancelVolumeTransition = exports.restoreVolumeLevels = exports.applyVolumeDucking = exports.clearVolumeDucking = exports.setVolumeDucking = exports.setAllChannelsVolume = exports.getAllChannelsVolume = exports.getChannelVolume = exports.setChannelVolume = exports.transitionVolume = exports.getFadeConfig = void 0;
+exports.cleanupWebAudioForAudio = exports.initializeWebAudioForAudio = exports.cancelAllVolumeTransitions = exports.cancelVolumeTransition = exports.restoreVolumeLevels = exports.applyVolumeDucking = exports.clearVolumeDucking = exports.setVolumeDucking = exports.getGlobalVolume = exports.setGlobalVolume = exports.setAllChannelsVolume = exports.getAllChannelsVolume = exports.getChannelVolume = exports.setChannelVolume = exports.transitionVolume = exports.getFadeConfig = void 0;
 const types_1 = require("./types");
 const info_1 = require("./info");
 const web_audio_1 = require("./web-audio");
@@ -20,6 +20,11 @@ const web_audio_1 = require("./web-audio");
 const activeTransitions = new Map();
 // Track which timer type was used for each channel
 const timerTypes = new Map();
+/**
+ * Global volume multiplier that affects all channels
+ * Acts as a global volume control (0-1)
+ */
+let globalVolume = 1.0;
 /**
  * Global volume ducking configuration
  * Stores the volume ducking settings that apply to all channels
@@ -261,6 +266,48 @@ const setAllChannelsVolume = (volume) => __awaiter(void 0, void 0, void 0, funct
     yield Promise.all(promises);
 });
 exports.setAllChannelsVolume = setAllChannelsVolume;
+/**
+ * Sets the global volume multiplier that affects all channels
+ * This acts as a global volume control - individual channel volumes are multiplied by this value
+ * @param volume - Global volume level (0-1, will be clamped to this range)
+ * @example
+ * ```typescript
+ * // Set channel-specific volumes
+ * await setChannelVolume(0, 0.8); // SFX at 80%
+ * await setChannelVolume(1, 0.6); // Music at 60%
+ *
+ * // Apply global volume of 50% - all channels play at half their set volume
+ * await setGlobalVolume(0.5); // SFX now plays at 40%, music at 30%
+ * ```
+ */
+const setGlobalVolume = (volume) => __awaiter(void 0, void 0, void 0, function* () {
+    // Clamp to valid range
+    globalVolume = Math.max(0, Math.min(1, volume));
+    // Update all currently playing audio to reflect the new global volume
+    // Note: setVolumeForAudio internally multiplies channel.volume by globalVolume
+    const updatePromises = [];
+    info_1.audioChannels.forEach((channel, channelNumber) => {
+        if (channel && channel.queue.length > 0) {
+            const currentAudio = channel.queue[0];
+            updatePromises.push(setVolumeForAudio(currentAudio, channel.volume, channelNumber));
+        }
+    });
+    yield Promise.all(updatePromises);
+});
+exports.setGlobalVolume = setGlobalVolume;
+/**
+ * Gets the current global volume multiplier
+ * @returns Current global volume level (0-1), defaults to 1.0
+ * @example
+ * ```typescript
+ * const globalVol = getGlobalVolume();
+ * console.log(`Global volume is ${globalVol * 100}%`);
+ * ```
+ */
+const getGlobalVolume = () => {
+    return globalVolume;
+};
+exports.getGlobalVolume = getGlobalVolume;
 /**
  * Configures volume ducking for channels. When the priority channel plays audio,
  * all other channels will be automatically reduced to the ducking volume level
@@ -401,6 +448,8 @@ exports.restoreVolumeLevels = restoreVolumeLevels;
  * @internal
  */
 const transitionAudioVolume = (audio_1, targetVolume_1, ...args_1) => __awaiter(void 0, [audio_1, targetVolume_1, ...args_1], void 0, function* (audio, targetVolume, duration = 250, easing = types_1.EasingType.EaseOut, channelNumber) {
+    // Apply global volume multiplier
+    const actualTargetVolume = targetVolume * globalVolume;
     // Try to use Web Audio API if available and channel number is provided
     if (channelNumber !== undefined) {
         const channel = info_1.audioChannels[channelNumber];
@@ -408,23 +457,23 @@ const transitionAudioVolume = (audio_1, targetVolume_1, ...args_1) => __awaiter(
             const nodes = channel.webAudioNodes.get(audio);
             if (nodes) {
                 // Use Web Audio API for smooth transitions
-                (0, web_audio_1.setWebAudioVolume)(nodes.gainNode, targetVolume, duration);
+                (0, web_audio_1.setWebAudioVolume)(nodes.gainNode, actualTargetVolume, duration);
                 // Also update the audio element's volume property for consistency
-                audio.volume = targetVolume;
+                audio.volume = actualTargetVolume;
                 return;
             }
         }
     }
     // Fallback to standard HTMLAudioElement volume control with manual transition
     const startVolume = audio.volume;
-    const volumeDelta = targetVolume - startVolume;
+    const volumeDelta = actualTargetVolume - startVolume;
     // If no change needed, resolve immediately
     if (Math.abs(volumeDelta) < 0.001) {
         return Promise.resolve();
     }
     // Handle zero or negative duration - instant change
     if (duration <= 0) {
-        audio.volume = targetVolume;
+        audio.volume = actualTargetVolume;
         return Promise.resolve();
     }
     const startTime = performance.now();
@@ -522,23 +571,25 @@ const initializeWebAudioForChannel = (channelNumber) => __awaiter(void 0, void 0
 /**
  * Sets volume for an audio element using the appropriate method (Web Audio API or standard)
  * @param audio - The audio element to set volume for
- * @param volume - Volume level (0-1)
+ * @param volume - Channel volume level (0-1) - will be multiplied by global volume
  * @param channelNumber - The channel number this audio belongs to
  * @param transitionDuration - Optional transition duration in milliseconds
  * @internal
  */
 const setVolumeForAudio = (audio, volume, channelNumber, transitionDuration) => __awaiter(void 0, void 0, void 0, function* () {
     const channel = info_1.audioChannels[channelNumber];
+    // Apply global volume multiplier to the channel volume
+    const actualVolume = volume * globalVolume;
     // Use Web Audio API if available and initialized
     if ((channel === null || channel === void 0 ? void 0 : channel.webAudioContext) && channel.webAudioNodes) {
         const nodes = channel.webAudioNodes.get(audio);
         if (nodes) {
-            (0, web_audio_1.setWebAudioVolume)(nodes.gainNode, volume, transitionDuration);
+            (0, web_audio_1.setWebAudioVolume)(nodes.gainNode, actualVolume, transitionDuration);
             return;
         }
     }
     // Fallback to standard HTMLAudioElement volume control
-    audio.volume = volume;
+    audio.volume = actualVolume;
 });
 /**
  * Initializes Web Audio API nodes for a new audio element
@@ -559,8 +610,8 @@ const initializeWebAudioForAudio = (audio, channelNumber) => __awaiter(void 0, v
         const nodes = (0, web_audio_1.createWebAudioNodes)(audio, channel.webAudioContext);
         if (nodes) {
             channel.webAudioNodes.set(audio, nodes);
-            // Set initial volume to match channel volume
-            nodes.gainNode.gain.value = channel.volume;
+            // Set initial volume to match channel volume with global volume multiplier
+            nodes.gainNode.gain.value = channel.volume * globalVolume;
         }
     }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audio-channel-queue",
-  "version": "1.12.1-beta.0",
+  "version": "1.12.1-beta.3",
   "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

@@ -14,10 +14,11 @@ import {
 } from './events';
 import {
   applyVolumeDucking,
-  restoreVolumeLevels,
   cancelVolumeTransition,
+  cleanupWebAudioForAudio,
+  getGlobalVolume,
   initializeWebAudioForAudio,
-  cleanupWebAudioForAudio
+  restoreVolumeLevels
 } from './volume';
 import { setupAudioErrorHandling, handleAudioError } from './errors';
 
@@ -372,9 +373,10 @@ export const playAudioQueue = async (channelNumber: number): Promise<void> => {
 
   const currentAudio: HTMLAudioElement = channel.queue[0];
 
-  // Apply channel volume if not already set
+  // Apply channel volume with global volume multiplier if not already set
   if (currentAudio.volume === 1.0 && channel.volume !== undefined) {
-    currentAudio.volume = channel.volume;
+    const globalVolume: number = getGlobalVolume();
+    currentAudio.volume = channel.volume * globalVolume;
   }
 
   setupProgressTracking(currentAudio, channelNumber, audioChannels);

package/src/index.ts

@@ -66,8 +66,10 @@ export {
   getAllChannelsVolume,
   getChannelVolume,
   getFadeConfig,
+  getGlobalVolume,
   setAllChannelsVolume,
   setChannelVolume,
+  setGlobalVolume,
   setVolumeDucking,
   transitionVolume
 } from './volume';

package/src/volume.ts

@@ -26,6 +26,12 @@ const activeTransitions: Map<number, number> = new Map();
 // Track which timer type was used for each channel
 const timerTypes: Map<number, TimerType> = new Map();
 
+/**
+ * Global volume multiplier that affects all channels
+ * Acts as a global volume control (0-1)
+ */
+let globalVolume: number = 1.0;
+
 /**
  * Global volume ducking configuration
  * Stores the volume ducking settings that apply to all channels
@@ -293,6 +299,50 @@ export const setAllChannelsVolume = async (volume: number): Promise<void> => {
   await Promise.all(promises);
 };
 
+/**
+ * Sets the global volume multiplier that affects all channels
+ * This acts as a global volume control - individual channel volumes are multiplied by this value
+ * @param volume - Global volume level (0-1, will be clamped to this range)
+ * @example
+ * ```typescript
+ * // Set channel-specific volumes
+ * await setChannelVolume(0, 0.8); // SFX at 80%
+ * await setChannelVolume(1, 0.6); // Music at 60%
+ *
+ * // Apply global volume of 50% - all channels play at half their set volume
+ * await setGlobalVolume(0.5); // SFX now plays at 40%, music at 30%
+ * ```
+ */
+export const setGlobalVolume = async (volume: number): Promise<void> => {
+  // Clamp to valid range
+  globalVolume = Math.max(0, Math.min(1, volume));
+
+  // Update all currently playing audio to reflect the new global volume
+  // Note: setVolumeForAudio internally multiplies channel.volume by globalVolume
+  const updatePromises: Promise<void>[] = [];
+  audioChannels.forEach((channel: ExtendedAudioQueueChannel, channelNumber: number) => {
+    if (channel && channel.queue.length > 0) {
+      const currentAudio: HTMLAudioElement = channel.queue[0];
+      updatePromises.push(setVolumeForAudio(currentAudio, channel.volume, channelNumber));
+    }
+  });
+
+  await Promise.all(updatePromises);
+};
+
+/**
+ * Gets the current global volume multiplier
+ * @returns Current global volume level (0-1), defaults to 1.0
+ * @example
+ * ```typescript
+ * const globalVol = getGlobalVolume();
+ * console.log(`Global volume is ${globalVol * 100}%`);
+ * ```
+ */
+export const getGlobalVolume = (): number => {
+  return globalVolume;
+};
+
 /**
  * Configures volume ducking for channels. When the priority channel plays audio,
  * all other channels will be automatically reduced to the ducking volume level
@@ -457,6 +507,9 @@ const transitionAudioVolume = async (
   easing: EasingType = EasingType.EaseOut,
   channelNumber?: number
 ): Promise<void> => {
+  // Apply global volume multiplier
+  const actualTargetVolume: number = targetVolume * globalVolume;
+
   // Try to use Web Audio API if available and channel number is provided
   if (channelNumber !== undefined) {
     const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
@@ -464,9 +517,9 @@ const transitionAudioVolume = async (
       const nodes = channel.webAudioNodes.get(audio);
       if (nodes) {
         // Use Web Audio API for smooth transitions
-        setWebAudioVolume(nodes.gainNode, targetVolume, duration);
+        setWebAudioVolume(nodes.gainNode, actualTargetVolume, duration);
         // Also update the audio element's volume property for consistency
-        audio.volume = targetVolume;
+        audio.volume = actualTargetVolume;
         return;
       }
     }
@@ -474,7 +527,7 @@ const transitionAudioVolume = async (
 
   // Fallback to standard HTMLAudioElement volume control with manual transition
   const startVolume: number = audio.volume;
-  const volumeDelta: number = targetVolume - startVolume;
+  const volumeDelta: number = actualTargetVolume - startVolume;
 
   // If no change needed, resolve immediately
   if (Math.abs(volumeDelta) < 0.001) {
@@ -483,7 +536,7 @@ const transitionAudioVolume = async (
 
   // Handle zero or negative duration - instant change
   if (duration <= 0) {
-    audio.volume = targetVolume;
+    audio.volume = actualTargetVolume;
     return Promise.resolve();
   }
 
@@ -594,7 +647,7 @@ const initializeWebAudioForChannel = async (channelNumber: number): Promise<void
 /**
  * Sets volume for an audio element using the appropriate method (Web Audio API or standard)
  * @param audio - The audio element to set volume for
- * @param volume - Volume level (0-1)
+ * @param volume - Channel volume level (0-1) - will be multiplied by global volume
  * @param channelNumber - The channel number this audio belongs to
  * @param transitionDuration - Optional transition duration in milliseconds
  * @internal
@@ -607,17 +660,20 @@ const setVolumeForAudio = async (
 ): Promise<void> => {
   const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
 
+  // Apply global volume multiplier to the channel volume
+  const actualVolume: number = volume * globalVolume;
+
   // Use Web Audio API if available and initialized
   if (channel?.webAudioContext && channel.webAudioNodes) {
     const nodes = channel.webAudioNodes.get(audio);
     if (nodes) {
-      setWebAudioVolume(nodes.gainNode, volume, transitionDuration);
+      setWebAudioVolume(nodes.gainNode, actualVolume, transitionDuration);
       return;
     }
   }
 
   // Fallback to standard HTMLAudioElement volume control
-  audio.volume = volume;
+  audio.volume = actualVolume;
 };
 
 /**
@@ -643,8 +699,8 @@ export const initializeWebAudioForAudio = async (
     const nodes = createWebAudioNodes(audio, channel.webAudioContext);
     if (nodes) {
       channel.webAudioNodes.set(audio, nodes);
-      // Set initial volume to match channel volume
-      nodes.gainNode.gain.value = channel.volume;
+      // Set initial volume to match channel volume with global volume multiplier
+      nodes.gainNode.gain.value = channel.volume * globalVolume;
     }
   }
 };