Readme Documentation Draft -1

src/lib/free-queue/README.md

@@ -1 +1,114 @@
-### Work In Progress ....
+# FreeQueue: Ring-Buffer Library for AudioWorklet
+
+## Introduction
+
+This library provides two classes, `FreeQueue` and `FreeQueueSAB`, designed to handle audio buffering using WebAssembly (WASM) and SharedArrayBuffer (SAB) respectively. These classes offer efficient ways to manage audio data, making them suitable for applications requiring low-latency audio processing.
+
+A ring buffer is particularly beneficial in audio applications because it provides flexibility and smooth integration with other system components. Although a ring buffer may introduce more latency compared to non-buffering solutions, a well-implemented ring buffer minimizes this latency while maintaining efficient data handling.
+
+### Features
+
+- Efficient audio buffering using WASM (`FreeQueue`) and SharedArrayBuffer (`FreeQueueSAB`).
+- Supports multiple audio channels.
+- Designed for single-producer/single-consumer scenarios.
+- Provides atomic operations for safe access across threads.
+
+## Installation
+
+To use this library, you need to include it in your project. You can do this by cloning the repository and importing the classes into your project.
+
+```bash
+git clone https://github.com/GoogleChromeLabs/web-audio-samples.git
+```
+
+Then, import the classes into your project:
+
+````js
+import { FreeQueue } from './path/to/freequeue';
+import { FreeQueueSAB } from './path/to/freequeuesab';
+````
+
+## Usage
+
+### FreeQueue
+
+The FreeQueue class is designed to work with WebAssembly (WASM) for efficient audio data handling.
+
+#### Constructor
+
+```js 
+new FreeQueue(wasmModule, length, channelCount, maxChannelCount)
+```
+
+- `wasmModule`: WASM module generated by Emscripten.
+- `length`: Buffer frame length.
+- `channelCount`: Number of audio channels.
+- `maxChannelCount (optional)`: Maximum number of audio channels.
+
+#### Methods
+
+- `adaptChannel(newChannelCount)`: Adjusts the current channel count to a new value.
+- `getChannelData(channelIndex)`: Returns a Float32Array for a given channel index or the entire channel data array.
+- `getHeapAddress()`: Returns the base address of the allocated memory space in the WASM heap.
+- `free()`: Frees the allocated memory space in the WASM heap.
+- `push(arraySequence)`: Pushes a sequence of Float32Array to the buffer.
+- `pull(arraySequence)`: Pulls data out of the buffer into a given sequence of Float32Array.
+
+#### Example 
+
+```js 
+const wasmModule = ...; // Initialize your WASM module
+const bufferLength = 1024;
+const channelCount = 2;
+
+const freeQueue = new FreeQueue(wasmModule, bufferLength, channelCount);
+
+// Push data
+const dataToPush = [new Float32Array(bufferLength), new Float32Array(bufferLength)];
+freeQueue.push(dataToPush);
+
+// Pull data
+const dataToPull = [new Float32Array(bufferLength), new Float32Array(bufferLength)];
+freeQueue.pull(dataToPull);
+```
+
+### FreeQueueSAB
+
+The FreeQueueSAB class uses SharedArrayBuffer for efficient audio data handling between threads.
+
+#### Constructor
+
+```js 
+new FreeQueueSAB(size, channelCount = 1)
+```
+
+- `size`: Frame buffer length.
+- `channelCount (optional)`: Total channel count.
+
+
+#### Methods
+
+- `static fromPointers(queuePointers)`: Creates a FreeQueue instance from pointers.
+- `push(input, blockLength)`: Pushes data into the queue.
+- `pull(output, blockLength)`: Pulls data out of the queue.
+- `printAvailableReadAndWrite()`: Prints currently available read and write indices.
+- `getAvailableSamples()`: Returns the number of samples available for reading.
+- `isFrameAvailable(size)`: Checks if a frame of the given size is available.
+- `getBufferLength()`: Returns the buffer length.
+
+#### Example
+
+```js 
+const size = 1024;
+const channelCount = 2;
+
+const freeQueueSAB = new FreeQueueSAB(size, channelCount);
+
+// Push data
+const input = [new Float32Array(size), new Float32Array(size)];
+freeQueueSAB.push(input, size);
+
+// Pull data
+const output = [new Float32Array(size), new Float32Array(size)];
+freeQueueSAB.pull(output, size);
+```