Audio Frame Buffer

Audio Frame Buffer is a multi-channel ring buffer library designed to handle audio frame data. This library is optimized for audio data buffering and is specifically designed for Single Producer, Single Consumer (SPSC) scenarios.

Features

• Multi-Channel Support: Handles multi-channel audio data and allows buffer operations on a frame-by-frame basis.
• Thread-Safe Sharing: Enables efficient audio processing in multithreaded environments by safely sharing data across threads through the FrameBufferContext.

Installation

npm install @ain1084/audio-frame-buffer

Basic Usage

In this example, we demonstrate how to:

1. Create an FrameBufferContext, which contains the shared configuration and buffer used for audio processing.
2. Initialize FrameBufferReader and FrameBufferWriter instances for reading and writing frame data.
3. Use read and write methods with callbacks to process and store audio frames in blocks.

Creating an FrameBufferContext

import { createFrameBufferContext, FrameBufferParams } from '@ain1084/audio-frame-buffer'

const params: FrameBufferParams = {
  frameCount: 1024,
  channelCount: 2
}

const context = createFrameBufferContext(params)

Using FrameBufferReader / FrameBufferWriter

import { FrameBufferReader, FrameBufferWriter } from '@ain1084/audio-frame-buffer'

const reader = new FrameBufferReader(context)
const writer = new FrameBufferWriter(context)

// Reading data
const framesRead = reader.read((segment, offset) => {
  // `segment` provides methods to access frame data in a structured way.
  for (let frame = 0; frame < segment.frameCount; frame++) {
    for (let channel = 0; channel < segment.channels; channel++) {
      const sample = segment.get(frame, channel)
      // Process the sample as needed
    }
  }
  return segment.frameCount // Return the number of frames processed
})

// Writing data
const framesWritten = writer.write((segment, offset) => {
  // Write data to each frame and channel
  for (let frame = 0; frame < segment.frameCount; frame++) {
    for (let channel = 0; channel < segment.channels; channel++) {
      segment.set(frame, channel, offset + frame * segment.channels + channel)
    }
  }
  return segment.frameCount // Return the number of frames written
})

Differences from a Standard Ring Buffer

Unlike standard ring buffers, which typically use push/pop operations for single-element access, Audio Frame Buffer is designed to read and write data in blocks (multiple frames) using a callback function. This design choice offers specific benefits for handling continuous data streams, like audio data:

• Efficiency: Block-based processing reduces the overhead associated with single-frame operations.
• Real-Time Processing: In audio processing, handling data in larger segments improves real-time performance.
• Seamless Wrapping: When the ring buffer wraps around, readable/writable segments may be split into two parts within the buffer. The read and write operations handle this division automatically and return contiguous subarrays, so the user can access the segments without additional complexity.

API Documentation

For more detailed documentation on the API, including parameter descriptions and usage details, please refer to the API Documentation.

Important Notes

• SPSC: This package is designed for Single Producer, Single Consumer (SPSC) use. Only one instance of each Reader and Writer should be created; multiple instances may result in unexpected behavior.

• Thread Safety: FrameBufferContext uses SharedArrayBuffer to safely share data across multiple threads.

• Browser Requirements (COOP/COEP): To use SharedArrayBuffer, the following HTTP headers must be set:

  • COOP (Cross-Origin-Opener-Policy):

    Cross-Origin-Opener-Policy: same-origin

  • COEP (Cross-Origin-Embedder-Policy):

    Cross-Origin-Embedder-Policy: require-corp

  These settings enable SharedArrayBuffer and allow for safe multi-threaded data sharing. For details, refer to the MDN Web Docs - SharedArrayBuffer.

Detailed API Reference

For a full API reference, please see the documentation here.

Contribution

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

This project is licensed under multiple licenses:

You can choose either license depending on your project needs.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.