This library uses modern Web APIs and is designed for contemporary browsers only. Tested and confirmed working on:

Legend:

• ✅: Confirmed and working without issues
• 🔺: Confirmed with limitations (e.g., unstable in background operation)
• ❓: Not yet confirmed

Note: Compatibility with Safari on iOS has not been confirmed due to lack of test devices.

To check compatibility in your environment, please run the demo in the example directory.

You need to add @ain1084/audio-worklet-stream to the optimizeDeps.exclude section in vite.config.ts. Furthermore, include the necessary COOP (Cross-Origin Opener Policy) and COEP (Cross-Origin Embedder Policy) settings to enable the use of SharedArrayBuffer.

vite.config.ts

import { defineConfig } from 'vite'

export default defineConfig({
  optimizeDeps: {
    exclude: ['@ain1084/audio-worklet-stream']
  },
  plugins: [
    {
      name: 'configure-response-headers',
      configureServer: (server) => {
        server.middlewares.use((_req, res, next) => {
          res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
          res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
          next()
        })
      },
    },
  ],
})
Copy

If you are using Nuxt3, add it under vite in nuxt.config.ts.

nuxt.config.ts

export default defineNuxtConfig({
  vite: {
    optimizeDeps: {
      exclude: ['@ain1084/audio-worklet-stream']
    },
    plugins: [
      {
        name: 'configure-response-headers',
        configureServer: (server) => {
          server.middlewares.use((_req, res, next) => {
            res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
            res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
            next()
          })
        },
      },
    ],
  },
  nitro: {
    rollupConfig: {
      external: '@ain1084/audio-worklet-stream',
    },
    routeRules: {
      '/**': {
        headers: {
          'Cross-Origin-Embedder-Policy': 'require-corp',
          'Cross-Origin-Opener-Policy': 'same-origin',
        },
      },
    },
  },
})
Copy

Understanding these parameters is crucial for optimal audio performance:

channelCount (All strategies)

• Specifies the number of audio channels (e.g., 2 for stereo).
• Determines the sample composition within each frame.

frameBufferSize (Manual strategy only)

• Defines the size of the ring buffer in frames.
• For continuous streaming, new frames must be supplied before buffer depletion.
• Larger size: Less susceptible to interruptions, but increases latency.
• Smaller size: Requires more frequent writes, potentially increasing CPU load.
• Manual strategy: Must be specified.
• Timed/Worker strategies: Calculated internally based on fillInterval.

fillInterval (Timed and Worker strategies only)

• Specifies the interval for buffer refill timer.
• Default: 20ms.

frameBufferChunks (Timed and Worker strategies only)

• Specifies the number of chunks in the total buffer size.
• Default: 5.

Example calculation: For 48kHz sample rate and 20ms fillInterval:

• One chunk size = 48000 * 0.02 = 960 frames
• Total buffer size with default 5 chunks = 960 * 5 = 4800 frames

The actual values may slightly differ from the above because they are rounded up to 128 frame units.

The example can be found at example.

The provided example demonstrates how to use the library to manually write audio frames to a buffer. It includes:

• Main Application (example/src/main.ts): Sets up and starts the audio stream using different buffer writing strategies.
• Sine Wave Filler (example/src/sine-wave-frame-buffer-filler.ts): Implements a frame buffer filler that generates a sine wave.
• Sine Wave Generator (example/src/sine-wave-generator.ts): Generates sine wave values for the buffer filler.
• Worker (example/src/worker.ts): Sets up a worker to handle buffer filling tasks.
• HTML Entry Point (example/index.html): Provides the HTML structure and buttons to control the audio stream.

For more details, refer to the example/README.md.

This guide provides tips and best practices for optimizing the performance of your audio application using the Audio Worklet Stream Library.

Batch Processing

Our library is optimized for processing audio frames in large batches. To maximize performance:

1. When implementing your own audio generation or processing logic, work with larger chunks of audio data whenever possible.
2. Utilize the library's ability to handle multiple frames at once in your buffer filling strategies.

Buffer Size Considerations

• Larger buffer sizes can improve performance but may increase latency.
• Experiment with different buffer sizes to find the optimal balance between performance and latency for your specific use case.

Worker-Based Strategy

For the most stable playback, especially in scenarios where the main thread might be busy:

1. Use the Worker-based buffer writing strategy.
2. Implement computationally intensive tasks within the Worker to avoid impacting the main thread.

Memory Management

• When working with multiple audio streams, be mindful of memory usage.
• For scenarios requiring numerous concurrent audio streams, pay attention to the creation and resource management of each stream. Consider properly releasing unused streams when necessary.

Avoid Frequent AudioContext Creation

• Creating new AudioContext instances is expensive. Reuse existing contexts when possible.
• If your application requires multiple audio streams, try to use a single AudioContext for all of them.

Profiling and Monitoring

• Use browser developer tools to profile your application and identify performance bottlenecks.
• Monitor CPU usage and audio underruns to ensure smooth playback.

By following these guidelines, you can ensure that your audio application runs efficiently and provides a smooth user experience.

This guide covers advanced usage scenarios and techniques for the Audio Worklet Stream Library.

Advanced Worker Usage

For complex audio processing tasks:

1. Create a custom Worker that extends BufferFillWorker.
2. Implement advanced audio processing algorithms within the Worker.
3. Use SharedArrayBuffer for efficient data sharing between the main thread and the Worker.

Handling Multiple Audio Streams

When working with multiple audio streams:

1. Create separate OutputStreamNode instances for each stream.
2. Manage their lifecycle and synchronization carefully.
3. Consider implementing a mixer if you need to combine multiple streams.

Integrating with Other Web Audio API Features

You can combine this library with other Web Audio API features:

1. Connect the OutputStreamNode to other AudioNodes for additional processing.
2. Use AnalyserNode for visualizations.
3. Implement spatial audio using PannerNode.

Error Handling and Debugging

For robust applications:

1. Implement comprehensive error handling, especially for Worker-based strategies.
2. Use the UnderrunEvent to detect and handle buffer underruns.
3. Implement logging or metrics collection for performance monitoring.

These advanced techniques will help you leverage the full power of the Audio Worklet Stream Library in complex audio applications.

This guide helps you troubleshoot common issues when using the Audio Worklet Stream Library.

Audio Playback Issues

No Sound

1. Check if your AudioContext is in the 'running' state. It may need to be resumed after user interaction.
2. Ensure your OutputStreamNode is properly connected to the AudioContext destination.
3. Verify that you're writing audio data to the buffer correctly.

Choppy or Glitchy Playback

1. Increase your buffer size to reduce the chance of underruns.
2. If using the Timed strategy, consider switching to the Worker strategy for more stable playback.
3. Check your system's CPU usage. High CPU usage can cause audio glitches.

Buffer Underruns

If you're experiencing frequent UnderrunEvents:

1. Increase your buffer size.
2. Optimize your audio data generation/loading process.
3. If using the Manual strategy, ensure you're writing to the buffer frequently enough.

Worker-Related Issues

Worker Not Starting

1. Ensure your Worker file is in the correct location and properly bundled.
2. Check for any console errors related to Worker initialization.

Data Not Being Processed in Worker

1. Verify that your FrameBufferFiller implementation in the Worker is correct.
2. Check the message passing between the main thread and the Worker.

Browser Compatibility Issues

Feature Not Working in Specific Browsers

1. Refer to the Browser Compatibility table in the README.
2. Ensure you're using the latest version of the browser.
3. Check if the required features (like SharedArrayBuffer) are enabled in the browser.

Build and Integration Issues

Module Not Found Errors

1. Ensure @ain1084/audio-worklet-stream is properly installed.
2. Check your bundler configuration, especially the optimizeDeps.exclude setting in Vite.

Browser Errors

1. Verify that you've set the correct COOP (Cross-Origin Opener Policy) and COEP (Cross-Origin Embedder Policy) headers as described in the installation instructions.
2. If using a development server, ensure it's configured to send the required headers.

Performance Issues

If you're experiencing poor performance:

1. Profile your application using browser developer tools.
2. Consider using the Worker strategy for computationally intensive tasks.
3. Optimize your audio processing algorithms.

If you're still facing issues after trying these solutions, please open an issue on our GitHub repository with a detailed description of the problem and steps to reproduce it.

SSR and Import Errors with ESM Modules

When using @ain1084/audio-worklet-stream in a Nuxt 3 project, you may encounter issues during SSR (Server-Side Rendering) or when importing the package as an ESM module. This can result in errors like:

[nuxt] [request error] [unhandled] [500] Cannot find module '/path/to/node_modules/@ain1084/audio-worklet-stream/dist/esm/events' imported from '/path/to/node_modules/@ain1084/audio-worklet-stream/dist/esm/index.js'
Copy

Workarounds

1. Disable SSR for the Component

   You can disable SSR for the component that uses the package. This can be done by using <client-only>:

   
     
   
   Copy

2. Use ssr: false in nuxt.config.ts

   You can disable SSR for the entire project in nuxt.config.ts:

   export default defineNuxtConfig({
     ssr: false,
     // other configurations
   })
   Copy

3. Use import.meta.server and import.meta.client

   For a more granular control, you can use import.meta.server and import.meta.client to conditionally import the module only on the client-side. Note that this method is more complex compared to 1 and 2:

   if (import.meta.client) {
     const { StreamNodeFactory } = await import('@ain1084/audio-worklet-stream');
     // Use StreamNodeFactory
   }
   Copy

Example Configuration

To ensure proper operation, it is essential to use ssr: false or <client-only> for components and to exclude @ain1084/audio-worklet-stream from Vite's optimization in your nuxt.config.ts:

export default defineNuxtConfig({
  ssr: false, // or use <client-only> for specific components
  vite: {
    optimizeDeps: {
      exclude: ['@ain1084/audio-worklet-stream']
    },
    plugins: [
      {
        name: 'configure-response-headers',
        configureServer: (server) => {
          server.middlewares.use((_req, res, next) => {
            res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
            res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
            next()
          })
        },
      },
    ],
  },
  nitro: {
    rollupConfig: {
      external: '@ain1084/audio-worklet-stream',
    },
    // Ensure COEP and COOP settings for SharedArrayBuffer
    routeRules: {
      '/**': {
        headers: {
          'Cross-Origin-Embedder-Policy': 'require-corp',
          'Cross-Origin-Opener-Policy': 'same-origin',
        },
      },
    },
  },
})
Copy