audio-channel-queue 1.10.0 → 1.11.0

package/README.md

@@ -362,12 +362,24 @@ onAudioStart(channelNumber, callback);
 onAudioStart(0, (info) => console.log(`Started: ${info.fileName}`)); // Log audio starts
 ```
 
+```typescript
+// Unsubscribe from audio start events (removes ALL start callbacks for the channel)
+offAudioStart(channelNumber);
+offAudioStart(0); // Stop receiving all start notifications for channel 0
+```
+
 ```typescript
 // Subscribe to audio completion events.
 onAudioComplete(channelNumber, callback);
 onAudioComplete(0, (info) => logPlayHistory(info)); // Track completed audio
 ```
 
+```typescript
+// Unsubscribe from audio completion events (removes ALL complete callbacks for the channel)
+offAudioComplete(channelNumber);
+offAudioComplete(0); // Stop receiving all completion notifications for channel 0
+```
+
 ```typescript
 // Subscribe to audio pause events.
 onAudioPause(channelNumber, callback);

package/dist/core.d.ts

@@ -73,10 +73,10 @@ export declare const queueAudioPriority: (audioUrl: string, channelNumber?: numb
 /**
  * Plays the audio queue for a specific channel
  * @param channelNumber - The channel number to play
- * @returns Promise that resolves when the current audio finishes playing
+ * @returns Promise that resolves when the audio starts playing (setup complete)
  * @example
  * ```typescript
- * await playAudioQueue(0); // Play queue for channel 0
+ * await playAudioQueue(0); // Start playing queue for channel 0
  * ```
  */
 export declare const playAudioQueue: (channelNumber: number) => Promise<void>;

package/dist/core.js

@@ -279,12 +279,8 @@ const queueAudio = (audioUrl_1, ...args_1) => __awaiter(void 0, [audioUrl_1, ...
     (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
     // Start playing if this is the first item and channel isn't paused
     if (channel.queue.length === 1 && !channel.isPaused) {
-        // Use setTimeout to ensure the queue change event is emitted first
-        setTimeout(() => {
-            (0, exports.playAudioQueue)(channelNumber).catch((error) => {
-                (0, errors_1.handleAudioError)(audio, channelNumber, validatedUrl, error);
-            });
-        }, 0);
+        // Await the audio setup to complete before resolving queueAudio
+        yield (0, exports.playAudioQueue)(channelNumber);
     }
 });
 exports.queueAudio = queueAudio;
@@ -309,10 +305,10 @@ exports.queueAudioPriority = queueAudioPriority;
 /**
  * Plays the audio queue for a specific channel
  * @param channelNumber - The channel number to play
- * @returns Promise that resolves when the current audio finishes playing
+ * @returns Promise that resolves when the audio starts playing (setup complete)
  * @example
  * ```typescript
- * await playAudioQueue(0); // Play queue for channel 0
+ * await playAudioQueue(0); // Start playing queue for channel 0
  * ```
  */
 const playAudioQueue = (channelNumber) => __awaiter(void 0, void 0, void 0, function* () {
@@ -331,6 +327,7 @@ const playAudioQueue = (channelNumber) => __awaiter(void 0, void 0, void 0, func
         let hasStarted = false;
         let metadataLoaded = false;
         let playStarted = false;
+        let setupComplete = false;
         // Check if we should fire onAudioStart (both conditions met)
         const tryFireAudioStart = () => {
             if (!hasStarted && metadataLoaded && playStarted) {
@@ -341,6 +338,11 @@ const playAudioQueue = (channelNumber) => __awaiter(void 0, void 0, void 0, func
                     fileName: (0, utils_1.extractFileName)(currentAudio.src),
                     src: currentAudio.src
                 }, info_1.audioChannels);
+                // Resolve setup promise when audio start event is fired
+                if (!setupComplete) {
+                    setupComplete = true;
+                    resolve();
+                }
             }
         };
         // Event handler for when metadata loads (duration becomes available)
@@ -371,7 +373,6 @@ const playAudioQueue = (channelNumber) => __awaiter(void 0, void 0, void 0, func
                 catch (error) {
                     yield (0, errors_1.handleAudioError)(currentAudio, channelNumber, currentAudio.src, error);
                 }
-                resolve();
             }
             else {
                 // For non-looping audio, remove from queue and play next
@@ -384,7 +385,6 @@ const playAudioQueue = (channelNumber) => __awaiter(void 0, void 0, void 0, func
                 (0, events_1.emitQueueChange)(channelNumber, info_1.audioChannels);
                 // Play next audio immediately if there's more in queue
                 yield (0, exports.playAudioQueue)(channelNumber);
-                resolve();
             }
         });
         // Add event listeners
@@ -398,7 +398,10 @@ const playAudioQueue = (channelNumber) => __awaiter(void 0, void 0, void 0, func
         // Enhanced play with error handling
         currentAudio.play().catch((error) => __awaiter(void 0, void 0, void 0, function* () {
             yield (0, errors_1.handleAudioError)(currentAudio, channelNumber, currentAudio.src, error);
-            resolve(); // Resolve to prevent hanging
+            if (!setupComplete) {
+                setupComplete = true;
+                resolve(); // Resolve gracefully instead of rejecting
+            }
         }));
     });
 });

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { clearQueueAfterCurrent, getQueueItemInfo, getQueueLength, removeQueuedI
 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 { clearVolumeDucking, fadeVolume, getAllChannelsVolume, getChannelVolume, getFadeConfig, setAllChannelsVolume, setChannelVolume, setVolumeDucking, transitionVolume, cancelVolumeTransition, cancelAllVolumeTransitions } from './volume';
-export { getAllChannelsInfo, getCurrentAudioInfo, getQueueSnapshot, offAudioPause, offAudioProgress, offAudioResume, offQueueChange, onAudioComplete, onAudioPause, onAudioProgress, onAudioResume, onAudioStart, onQueueChange } from './info';
+export { getAllChannelsInfo, getCurrentAudioInfo, getQueueSnapshot, offAudioComplete, offAudioPause, offAudioProgress, offAudioResume, offAudioStart, offQueueChange, onAudioComplete, onAudioPause, onAudioProgress, onAudioResume, onAudioStart, onQueueChange } from './info';
 export { audioChannels } from './info';
 export { cleanWebpackFilename, createQueueSnapshot, extractFileName, getAudioInfoFromElement, sanitizeForDisplay, validateAudioUrl } from './utils';
 export type { AudioCompleteCallback, AudioCompleteInfo, AudioErrorCallback, AudioErrorInfo, AudioInfo, AudioPauseCallback, AudioQueueOptions, AudioResumeCallback, AudioStartCallback, AudioStartInfo, ChannelFadeState, ErrorRecoveryOptions, ExtendedAudioQueueChannel, FadeConfig, ProgressCallback, QueueChangeCallback, QueueItem, QueueManipulationResult, QueueSnapshot, RetryConfig, VolumeConfig, QueueConfig } from './types';

package/dist/index.js

@@ -6,7 +6,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getAllChannelsInfo = exports.cancelAllVolumeTransitions = exports.cancelVolumeTransition = exports.transitionVolume = exports.setVolumeDucking = exports.setChannelVolume = exports.setAllChannelsVolume = exports.getFadeConfig = exports.getChannelVolume = exports.getAllChannelsVolume = exports.fadeVolume = exports.clearVolumeDucking = 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.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.offAudioResume = exports.offAudioProgress = exports.offAudioPause = exports.getQueueSnapshot = exports.getCurrentAudioInfo = void 0;
+exports.GLOBAL_PROGRESS_KEY = exports.TimerType = exports.MAX_CHANNELS = exports.FadeType = exports.EasingType = 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 = void 0;
 // Core queue management functions
 var core_1 = require("./core");
 Object.defineProperty(exports, "queueAudio", { enumerable: true, get: function () { return core_1.queueAudio; } });
@@ -71,9 +71,11 @@ var info_1 = require("./info");
 Object.defineProperty(exports, "getAllChannelsInfo", { enumerable: true, get: function () { return info_1.getAllChannelsInfo; } });
 Object.defineProperty(exports, "getCurrentAudioInfo", { enumerable: true, get: function () { return info_1.getCurrentAudioInfo; } });
 Object.defineProperty(exports, "getQueueSnapshot", { enumerable: true, get: function () { return info_1.getQueueSnapshot; } });
+Object.defineProperty(exports, "offAudioComplete", { enumerable: true, get: function () { return info_1.offAudioComplete; } });
 Object.defineProperty(exports, "offAudioPause", { enumerable: true, get: function () { return info_1.offAudioPause; } });
 Object.defineProperty(exports, "offAudioProgress", { enumerable: true, get: function () { return info_1.offAudioProgress; } });
 Object.defineProperty(exports, "offAudioResume", { enumerable: true, get: function () { return info_1.offAudioResume; } });
+Object.defineProperty(exports, "offAudioStart", { enumerable: true, get: function () { return info_1.offAudioStart; } });
 Object.defineProperty(exports, "offQueueChange", { enumerable: true, get: function () { return info_1.offQueueChange; } });
 Object.defineProperty(exports, "onAudioComplete", { enumerable: true, get: function () { return info_1.onAudioComplete; } });
 Object.defineProperty(exports, "onAudioPause", { enumerable: true, get: function () { return info_1.onAudioPause; } });

package/dist/info.d.ts

@@ -2,6 +2,29 @@
  * @fileoverview Audio information and progress tracking functions for the audio-channel-queue package
  */
 import { AudioInfo, QueueSnapshot, ProgressCallback, QueueChangeCallback, AudioStartCallback, AudioCompleteCallback, AudioPauseCallback, AudioResumeCallback, ExtendedAudioQueueChannel } from './types';
+/**
+ * Gets the current list of whitelisted channel properties
+ * This is automatically derived from the ExtendedAudioQueueChannel interface
+ * @returns Array of whitelisted property names
+ * @internal
+ */
+export declare const getWhitelistedChannelProperties: () => string[];
+/**
+ * Returns the list of non-whitelisted properties found on a specific channel
+ * These are properties that will trigger warnings when modified directly
+ * @param channelNumber - The channel number to inspect (defaults to 0)
+ * @returns Array of property names that are not in the whitelist, or empty array if channel doesn't exist
+ * @example
+ * ```typescript
+ * // Add some custom property to a channel
+ * (audioChannels[0] as any).customProperty = 'test';
+ *
+ * const nonWhitelisted = getNonWhitelistedChannelProperties(0);
+ * console.log(nonWhitelisted); // ['customProperty']
+ * ```
+ * @internal
+ */
+export declare const getNonWhitelistedChannelProperties: (channelNumber?: number) => string[];
 /**
  * Global array to store audio channels with their queues and callback management
  * Each channel maintains its own audio queue and event callback sets
@@ -176,3 +199,21 @@ export declare const offAudioPause: (channelNumber: number) => void;
  * ```
  */
 export declare const offAudioResume: (channelNumber: number) => void;
+/**
+ * Removes audio start event listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offAudioStart(0); // Stop receiving start notifications for channel 0
+ * ```
+ */
+export declare const offAudioStart: (channelNumber: number) => void;
+/**
+ * Removes audio complete event listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offAudioComplete(0); // Stop receiving completion notifications for channel 0
+ * ```
+ */
+export declare const offAudioComplete: (channelNumber: number) => void;

package/dist/info.js

@@ -3,11 +3,71 @@
  * @fileoverview Audio information and progress tracking functions for the audio-channel-queue package
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.offAudioResume = exports.offAudioPause = exports.onAudioResume = exports.onAudioPause = exports.onAudioComplete = exports.onAudioStart = exports.offQueueChange = exports.onQueueChange = exports.onAudioProgress = exports.getQueueSnapshot = exports.getAllChannelsInfo = exports.getCurrentAudioInfo = exports.audioChannels = void 0;
+exports.offAudioComplete = exports.offAudioStart = exports.offAudioResume = exports.offAudioPause = exports.onAudioResume = exports.onAudioPause = exports.onAudioComplete = exports.onAudioStart = exports.offQueueChange = exports.onQueueChange = exports.onAudioProgress = exports.getQueueSnapshot = exports.getAllChannelsInfo = exports.getCurrentAudioInfo = exports.audioChannels = exports.getNonWhitelistedChannelProperties = exports.getWhitelistedChannelProperties = void 0;
 exports.offAudioProgress = offAudioProgress;
 const types_1 = require("./types");
 const utils_1 = require("./utils");
 const events_1 = require("./events");
+/**
+ * Gets the current list of whitelisted channel properties
+ * This is automatically derived from the ExtendedAudioQueueChannel interface
+ * @returns Array of whitelisted property names
+ * @internal
+ */
+const getWhitelistedChannelProperties = () => {
+    // Create a sample channel object to extract property names
+    const sampleChannel = {
+        audioCompleteCallbacks: new Set(),
+        audioErrorCallbacks: new Set(),
+        audioPauseCallbacks: new Set(),
+        audioResumeCallbacks: new Set(),
+        audioStartCallbacks: new Set(),
+        isPaused: false,
+        progressCallbacks: new Map(),
+        queue: [],
+        queueChangeCallbacks: new Set(),
+        volume: 1.0
+    };
+    // Get all property names from the interface (including optional ones)
+    const propertyNames = [
+        ...Object.getOwnPropertyNames(sampleChannel),
+        // Add optional properties that might not be present on the sample
+        'fadeState',
+        'isLocked',
+        'maxQueueSize',
+        'retryConfig',
+        'volumeConfig' // Legacy property that might still be used
+    ];
+    return [...new Set(propertyNames)]; // Remove duplicates
+};
+exports.getWhitelistedChannelProperties = getWhitelistedChannelProperties;
+/**
+ * Returns the list of non-whitelisted properties found on a specific channel
+ * These are properties that will trigger warnings when modified directly
+ * @param channelNumber - The channel number to inspect (defaults to 0)
+ * @returns Array of property names that are not in the whitelist, or empty array if channel doesn't exist
+ * @example
+ * ```typescript
+ * // Add some custom property to a channel
+ * (audioChannels[0] as any).customProperty = 'test';
+ *
+ * const nonWhitelisted = getNonWhitelistedChannelProperties(0);
+ * console.log(nonWhitelisted); // ['customProperty']
+ * ```
+ * @internal
+ */
+const getNonWhitelistedChannelProperties = (channelNumber = 0) => {
+    const channel = exports.audioChannels[channelNumber];
+    if (!channel) {
+        return [];
+    }
+    const whitelistedProperties = (0, exports.getWhitelistedChannelProperties)();
+    const allChannelProperties = Object.getOwnPropertyNames(channel);
+    // Filter out properties that are in the whitelist
+    const nonWhitelistedProperties = allChannelProperties.filter((property) => !whitelistedProperties.includes(property));
+    return nonWhitelistedProperties;
+};
+exports.getNonWhitelistedChannelProperties = getNonWhitelistedChannelProperties;
 /**
  * Global array to store audio channels with their queues and callback management
  * Each channel maintains its own audio queue and event callback sets
@@ -35,8 +95,9 @@ exports.audioChannels = new Proxy([], {
             return new Proxy(value, {
                 set(channelTarget, channelProp, channelValue) {
                     // Allow internal modifications but warn about direct property changes
-                    if (typeof channelProp === 'string' &&
-                        !['queue', 'volume', 'isPaused', 'isLocked', 'volumeConfig'].includes(channelProp)) {
+                    // Use the automatically-derived whitelist from the interface
+                    const whitelistedProperties = (0, exports.getWhitelistedChannelProperties)();
+                    if (typeof channelProp === 'string' && !whitelistedProperties.includes(channelProp)) {
                         // eslint-disable-next-line no-console
                         console.warn(`Warning: Direct modification of channel.${channelProp} detected. ` +
                             'Use API functions for safer channel management.');
@@ -429,3 +490,33 @@ const offAudioResume = (channelNumber) => {
     channel.audioResumeCallbacks.clear();
 };
 exports.offAudioResume = offAudioResume;
+/**
+ * Removes audio start event listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offAudioStart(0); // Stop receiving start notifications for channel 0
+ * ```
+ */
+const offAudioStart = (channelNumber) => {
+    const channel = exports.audioChannels[channelNumber];
+    if (!(channel === null || channel === void 0 ? void 0 : channel.audioStartCallbacks))
+        return;
+    channel.audioStartCallbacks.clear();
+};
+exports.offAudioStart = offAudioStart;
+/**
+ * Removes audio complete event listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offAudioComplete(0); // Stop receiving completion notifications for channel 0
+ * ```
+ */
+const offAudioComplete = (channelNumber) => {
+    const channel = exports.audioChannels[channelNumber];
+    if (!(channel === null || channel === void 0 ? void 0 : channel.audioCompleteCallbacks))
+        return;
+    channel.audioCompleteCallbacks.clear();
+};
+exports.offAudioComplete = offAudioComplete;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audio-channel-queue",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Allows you to queue audio files to different playback channels.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/core.ts

@@ -320,12 +320,8 @@ export const queueAudio = async (
 
   // Start playing if this is the first item and channel isn't paused
   if (channel.queue.length === 1 && !channel.isPaused) {
-    // Use setTimeout to ensure the queue change event is emitted first
-    setTimeout(() => {
-      playAudioQueue(channelNumber).catch((error: Error) => {
-        handleAudioError(audio, channelNumber, validatedUrl, error);
-      });
-    }, 0);
+    // Await the audio setup to complete before resolving queueAudio
+    await playAudioQueue(channelNumber);
   }
 };
 
@@ -354,10 +350,10 @@ export const queueAudioPriority = async (
 /**
  * Plays the audio queue for a specific channel
  * @param channelNumber - The channel number to play
- * @returns Promise that resolves when the current audio finishes playing
+ * @returns Promise that resolves when the audio starts playing (setup complete)
  * @example
  * ```typescript
- * await playAudioQueue(0); // Play queue for channel 0
+ * await playAudioQueue(0); // Start playing queue for channel 0
  * ```
  */
 export const playAudioQueue = async (channelNumber: number): Promise<void> => {
@@ -381,6 +377,7 @@ export const playAudioQueue = async (channelNumber: number): Promise<void> => {
     let hasStarted: boolean = false;
     let metadataLoaded: boolean = false;
     let playStarted: boolean = false;
+    let setupComplete: boolean = false;
 
     // Check if we should fire onAudioStart (both conditions met)
     const tryFireAudioStart = (): void => {
@@ -396,6 +393,12 @@ export const playAudioQueue = async (channelNumber: number): Promise<void> => {
           },
           audioChannels
         );
+
+        // Resolve setup promise when audio start event is fired
+        if (!setupComplete) {
+          setupComplete = true;
+          resolve();
+        }
       }
     };
 
@@ -433,7 +436,6 @@ export const playAudioQueue = async (channelNumber: number): Promise<void> => {
         } catch (error) {
           await handleAudioError(currentAudio, channelNumber, currentAudio.src, error as Error);
         }
-        resolve();
       } else {
         // For non-looping audio, remove from queue and play next
         currentAudio.pause();
@@ -448,7 +450,6 @@ export const playAudioQueue = async (channelNumber: number): Promise<void> => {
 
         // Play next audio immediately if there's more in queue
         await playAudioQueue(channelNumber);
-        resolve();
       }
     };
 
@@ -465,7 +466,10 @@ export const playAudioQueue = async (channelNumber: number): Promise<void> => {
     // Enhanced play with error handling
     currentAudio.play().catch(async (error: Error) => {
       await handleAudioError(currentAudio, channelNumber, currentAudio.src, error);
-      resolve(); // Resolve to prevent hanging
+      if (!setupComplete) {
+        setupComplete = true;
+        resolve(); // Resolve gracefully instead of rejecting
+      }
     });
   });
 };

package/src/index.ts

@@ -78,9 +78,11 @@ export {
   getAllChannelsInfo,
   getCurrentAudioInfo,
   getQueueSnapshot,
+  offAudioComplete,
   offAudioPause,
   offAudioProgress,
   offAudioResume,
+  offAudioStart,
   offQueueChange,
   onAudioComplete,
   onAudioPause,

package/src/info.ts

@@ -18,6 +18,73 @@ import {
 import { getAudioInfoFromElement, createQueueSnapshot } from './utils';
 import { setupProgressTracking, cleanupProgressTracking } from './events';
 
+/**
+ * Gets the current list of whitelisted channel properties
+ * This is automatically derived from the ExtendedAudioQueueChannel interface
+ * @returns Array of whitelisted property names
+ * @internal
+ */
+export const getWhitelistedChannelProperties = (): string[] => {
+  // Create a sample channel object to extract property names
+  const sampleChannel: ExtendedAudioQueueChannel = {
+    audioCompleteCallbacks: new Set(),
+    audioErrorCallbacks: new Set(),
+    audioPauseCallbacks: new Set(),
+    audioResumeCallbacks: new Set(),
+    audioStartCallbacks: new Set(),
+    isPaused: false,
+    progressCallbacks: new Map(),
+    queue: [],
+    queueChangeCallbacks: new Set(),
+    volume: 1.0
+  };
+
+  // Get all property names from the interface (including optional ones)
+  const propertyNames = [
+    ...Object.getOwnPropertyNames(sampleChannel),
+    // Add optional properties that might not be present on the sample
+    'fadeState',
+    'isLocked',
+    'maxQueueSize',
+    'retryConfig',
+    'volumeConfig' // Legacy property that might still be used
+  ];
+
+  return [...new Set(propertyNames)]; // Remove duplicates
+};
+
+/**
+ * Returns the list of non-whitelisted properties found on a specific channel
+ * These are properties that will trigger warnings when modified directly
+ * @param channelNumber - The channel number to inspect (defaults to 0)
+ * @returns Array of property names that are not in the whitelist, or empty array if channel doesn't exist
+ * @example
+ * ```typescript
+ * // Add some custom property to a channel
+ * (audioChannels[0] as any).customProperty = 'test';
+ *
+ * const nonWhitelisted = getNonWhitelistedChannelProperties(0);
+ * console.log(nonWhitelisted); // ['customProperty']
+ * ```
+ * @internal
+ */
+export const getNonWhitelistedChannelProperties = (channelNumber: number = 0): string[] => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel) {
+    return [];
+  }
+
+  const whitelistedProperties: string[] = getWhitelistedChannelProperties();
+  const allChannelProperties: string[] = Object.getOwnPropertyNames(channel);
+
+  // Filter out properties that are in the whitelist
+  const nonWhitelistedProperties: string[] = allChannelProperties.filter(
+    (property: string) => !whitelistedProperties.includes(property)
+  );
+
+  return nonWhitelistedProperties;
+};
+
 /**
  * Global array to store audio channels with their queues and callback management
  * Each channel maintains its own audio queue and event callback sets
@@ -56,10 +123,10 @@ export const audioChannels: ExtendedAudioQueueChannel[] = new Proxy(
             channelValue: unknown
           ): boolean {
             // Allow internal modifications but warn about direct property changes
-            if (
-              typeof channelProp === 'string' &&
-              !['queue', 'volume', 'isPaused', 'isLocked', 'volumeConfig'].includes(channelProp)
-            ) {
+            // Use the automatically-derived whitelist from the interface
+            const whitelistedProperties = getWhitelistedChannelProperties();
+
+            if (typeof channelProp === 'string' && !whitelistedProperties.includes(channelProp)) {
               // eslint-disable-next-line no-console
               console.warn(
                 `Warning: Direct modification of channel.${channelProp} detected. ` +
@@ -484,3 +551,33 @@ export const offAudioResume = (channelNumber: number): void => {
 
   channel.audioResumeCallbacks.clear();
 };
+
+/**
+ * Removes audio start event listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offAudioStart(0); // Stop receiving start notifications for channel 0
+ * ```
+ */
+export const offAudioStart = (channelNumber: number): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel?.audioStartCallbacks) return;
+
+  channel.audioStartCallbacks.clear();
+};
+
+/**
+ * Removes audio complete event listeners for a specific channel
+ * @param channelNumber - The channel number
+ * @example
+ * ```typescript
+ * offAudioComplete(0); // Stop receiving completion notifications for channel 0
+ * ```
+ */
+export const offAudioComplete = (channelNumber: number): void => {
+  const channel: ExtendedAudioQueueChannel = audioChannels[channelNumber];
+  if (!channel?.audioCompleteCallbacks) return;
+
+  channel.audioCompleteCallbacks.clear();
+};