Skip to main content

Utility Functions

Helper functions for common audio-related tasks like URL validation, filename extraction, and sanitization.

validateAudioUrl​

Validates an audio URL for security and correctness.

Syntax​

validateAudioUrl(url: string): string

Parameters​

  • url (string): The URL to validate

Returns​

  • string: The validated URL

Throws​

  • Error: If the URL is invalid or potentially malicious

Examples​

import { validateAudioUrl } from 'audioq';

// Valid URLs
validateAudioUrl('https://example.com/audio.mp3'); // OK
validateAudioUrl('./sounds/local.wav'); // OK

// Invalid URLs - will throw
validateAudioUrl('javascript:alert("XSS")'); // Throws: dangerous protocol
validateAudioUrl('../../../etc/passwd'); // Throws: path traversal

sanitizeForDisplay​

Sanitizes text for safe display in HTML contexts by escaping special characters.

Syntax​

sanitizeForDisplay(text: string): string

Parameters​

  • text (string): The text to sanitize

Returns​

  • string: Sanitized text safe for HTML display

Examples​

import { sanitizeForDisplay } from 'audioq';

// Escapes HTML characters
sanitizeForDisplay('<script>alert("XSS")</script>'); 
// Returns: '&lt;script&gt;alert("XSS")&lt;/script&gt;'

// Normal text unchanged
sanitizeForDisplay('normal-file.mp3'); // Returns: 'normal-file.mp3'

extractFileName​

Extracts the filename from a URL string.

Syntax​

extractFileName(url: string): string

Parameters​

  • url (string): The URL to extract filename from

Returns​

  • string: The extracted filename or 'unknown' if extraction fails

Examples​

import { extractFileName } from 'audioq';

extractFileName('https://example.com/audio/song.mp3'); // Returns: 'song.mp3'
extractFileName('/path/to/audio.wav'); // Returns: 'audio.wav'
extractFileName('track.mp3?version=2'); // Returns: 'track.mp3'

cleanWebpackFilename​

Removes webpack hash patterns from filenames.

Syntax​

cleanWebpackFilename(fileName: string): string

Parameters​

  • fileName (string): Filename that may contain webpack hashes

Returns​

  • string: Cleaned filename with hashes removed

Examples​

import { cleanWebpackFilename } from 'audioq';

cleanWebpackFilename('song.a1b2c3d4.mp3'); // Returns: 'song.mp3'
cleanWebpackFilename('notification.1a2b3c4d5e6f.wav'); // Returns: 'notification.wav'
cleanWebpackFilename('clean-file.mp3'); // Returns: 'clean-file.mp3' (unchanged)

getAudioInfoFromElement​

Extracts comprehensive audio information from an HTMLAudioElement.

Syntax​

getAudioInfoFromElement(
  audio: HTMLAudioElement,
  channelNumber?: number,
  audioChannels?: ExtendedAudioQueueChannel[]
): AudioInfo | null

Parameters​

  • audio (HTMLAudioElement): The audio element to extract info from
  • channelNumber (number, optional): Channel number for queue context
  • audioChannels (ExtendedAudioQueueChannel[], optional): Channels array for context

Returns​

  • AudioInfo | null: Audio information or null if invalid

Examples​

import { getAudioInfoFromElement } from 'audioq';

const audioElement = new Audio('song.mp3');
await audioElement.load(); // Ensure metadata is loaded

const info = getAudioInfoFromElement(audioElement);
if (info) {
  console.log(`Progress: ${info.progress * 100}%`);
  console.log(`Duration: ${info.duration}ms`);
}

createQueueSnapshot​

Creates a complete snapshot of a queue's current state.

Syntax​

createQueueSnapshot(
  channelNumber: number,
  audioChannels: ExtendedAudioQueueChannel[]
): QueueSnapshot | null

Parameters​

  • channelNumber (number): The channel to snapshot
  • audioChannels (ExtendedAudioQueueChannel[]): Array of audio channels

Returns​

  • QueueSnapshot | null: Queue snapshot or null if channel doesn't exist

Examples​

import { createQueueSnapshot, audioChannels } from 'audioq';

const snapshot = createQueueSnapshot(0, audioChannels);
if (snapshot) {
  console.log(`Queue has ${snapshot.totalItems} items`);
  console.log(`Currently playing: ${snapshot.items[0]?.fileName}`);
}

Best Practices​

  1. Always validate user-provided URLs with validateAudioUrl() before queuing
  2. Sanitize filenames before displaying in UI with sanitizeForDisplay()
  3. Use cleanWebpackFilename() for cleaner UI display of bundled assets
  4. Prefer higher-level APIs like getCurrentAudioInfo() over getAudioInfoFromElement()
  5. Load audio metadata before calling getAudioInfoFromElement() for accurate information

Next Steps​