Skip to main content

Installation

Install with npm​

npm install audioq

Install with yarn​

yarn add audioq

Install with pnpm​

pnpm add audioq

Requirements​

Environment Requirements​

  • Browser environment (not Node.js server-side)
  • HTML5 audio support (available in all modern browsers)

Development Requirements​

  • Node.js 14+ (for building and testing only)
  • TypeScript 4.5+ (optional, but recommended)

Basic Setup​

import { 
  queueAudio, 
  setChannelVolume, 
  pauseChannel,
  onAudioStart 
} from 'audioq';

// Start using immediately!
await queueAudio('./sounds/welcome.mp3');

CommonJS​

const { 
  queueAudio, 
  setChannelVolume, 
  pauseChannel 
} = require('audioq');

// Start using immediately!
await queueAudio('./sounds/welcome.mp3');

UMD (Browser Script Tag)​

<script src="node_modules/audioq/dist/index.umd.js"></script>
<script>
  // Available as global AudioChannelQueue
  await AudioChannelQueue.queueAudio('./sounds/welcome.mp3');
</script>

TypeScript Configuration​

Add Type Declarations for Audio Files​

If you're importing audio files directly, create a custom.d.ts file in your project root:

custom.d.ts
declare module '*.mp3' {
  const src: string;
  export default src;
}

declare module '*.wav' {
  const src: string;
  export default src;
}

declare module '*.ogg' {
  const src: string;
  export default src;
}

declare module '*.m4a' {
  const src: string;
  export default src;
}

TypeScript Configuration​

Update your tsconfig.json to include type declarations:

tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["DOM", "DOM.Iterable"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": [
    "src/**/*",
    "custom.d.ts"
  ]
}

Audio File Preparation​

Supported Formats​

AudioQ supports all formats that the browser's HTMLAudioElement supports:

  • MP3 - Universal support, good compression
  • WAV - Uncompressed, high quality, larger files
  • OGG - Open source format, good compression
  • M4A/AAC - Good compression, widely supported
  • WEBM - Modern format, excellent compression

Format Recommendations​

Use CaseRecommended FormatWhy
Music/BackgroundMP3 or M4AGood compression, universal support
Short Sound EffectsWAVNo compression artifacts, fast loading
Voice/SpeechMP3Good compression for speech
Game AudioWAV or OGGLow latency, good quality

Build Tool Configuration​

Webpack​

Audio files are typically handled by webpack's asset handling:

webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.(mp3|wav|ogg|m4a)$/,
        type: 'asset/resource',
        generator: {
          filename: 'audio/[name][ext]'
        }
      }
    ]
  }
};

Vite​

Vite handles audio files out of the box:

vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  assetsInclude: ['**/*.mp3', '**/*.wav', '**/*.ogg', '**/*.m4a']
});

Create React App​

CRA handles audio files by default when imported:

import welcomeSound from './audio/welcome.mp3';
import { queueAudio } from 'audioq';

// Use the imported path
await queueAudio(welcomeSound);

Verify Installation​

Create a simple test to verify everything is working:

test-audio.ts
import { queueAudio, onAudioStart } from 'audioq';

// Set up event listener
onAudioStart(0, (info) => {
  console.log('Audio started:', info.fileName);
  console.log('Duration:', info.duration, 'ms');
});

// Test with a simple audio file
export async function testAudio(): Promise<void> {
  try {
    await queueAudio('./audio/test-sound.mp3');
    console.log('AudioQ is working!');
  } catch (error) {
    console.error('Error playing audio:', error);
  }
}

// Call the test
await testAudio();

Troubleshooting Installation​

Common Issues​

"Module not found" error

# Clear npm cache and reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

TypeScript import errors

  • Ensure you have the custom.d.ts file for audio imports
  • Check that TypeScript can find the module types

Audio files not loading

  • Verify your build tool is configured to handle audio assets
  • Check that file paths are correct relative to your build output

Browser compatibility issues

  • Verify you're using a supported browser
  • Check the browser console for specific error messages

Getting Help​

If you're still having issues:

  1. Check the troubleshooting guide
  2. Search existing issues
  3. Open a new issue with:
    • Your environment details (OS, browser, Node.js version)
    • Build tool configuration
    • Error messages
    • Minimal reproduction example

Next Steps​

Now that you have AudioQ installed, let's create your first audio queue:

Quick Start Guide - Build your first audio application in 5 minutes