@ain1084/audio-worklet-stream 0.1.2

package/src/frame-buffer/buffer-factory.ts

@@ -0,0 +1,115 @@
+import { FrameBuffer } from './buffer'
+import { FrameBufferWriter } from './buffer-writer'
+
+/**
+ * Parameters for creating a FrameBuffer.
+ * @property frameBufferSize - The size of the frame buffer.
+ * @property channelCount - The number of audio channels.
+ */
+export type FrameBufferParams = Readonly<{
+  frameBufferSize: number
+  channelCount: number
+}>
+
+/**
+ * Parameters for creating a FillerFrameBuffer.
+ * @property channelCount - The number of audio channels.
+ * @property fillInterval - The interval in milliseconds for filling the buffer.
+ * @property sampleRate - The sample rate of the audio context.
+ * @property frameBufferChunks - The number of chunks in the frame buffer.
+ */
+export type FillerFrameBufferParams = Readonly<{
+  channelCount: number
+  fillInterval?: number
+  sampleRate?: number
+  frameBufferChunks?: number
+}>
+
+/**
+ * Configuration for a FrameBuffer.
+ * This configuration is returned by the createFrameBufferConfig function.
+ * @property sampleBuffer - The shared buffer for audio data frames.
+ * @property samplesPerFrame - The number of samples per frame.
+ * @property usedFramesInBuffer - The usage count of the frames in the buffer.
+ * @property totalReadFrames - The total frames read from the buffer.
+ * @property totalWriteFrames - The total frames written to the buffer.
+ */
+export type FrameBufferConfig = Readonly<{
+  sampleBuffer: Float32Array
+  samplesPerFrame: number
+  usedFramesInBuffer: Uint32Array
+  totalReadFrames: BigUint64Array
+  totalWriteFrames: BigUint64Array
+}>
+
+/**
+ * Configuration for a FillerFrameBuffer.
+ * This configuration is returned by the createFillerFrameBufferConfig function.
+ * @property sampleRate - The sample rate of the audio context.
+ * @property fillInterval - The interval in milliseconds for filling the buffer.
+ */
+export type FillerFrameBufferConfig = FrameBufferConfig & Readonly<{
+  sampleRate: number
+  fillInterval: number
+}>
+
+/**
+ * Creates a FrameBufferWriter instance.
+ * @param config - The configuration for the FrameBuffer.
+ * @returns A new instance of FrameBufferWriter.
+ */
+export const createFrameBufferWriter = (config: FrameBufferConfig): FrameBufferWriter => {
+  return new FrameBufferWriter(
+    new FrameBuffer(config.sampleBuffer, config.samplesPerFrame),
+    config.usedFramesInBuffer, config.totalWriteFrames,
+  )
+}
+
+/**
+ * FrameBufferFactory class
+ * Provides static methods to create frame buffer configurations and writers.
+ */
+export class FrameBufferFactory {
+  public static readonly DEFAULT_FILL_INTERVAL_MS = 20
+  public static readonly DEFAULT_FRAME_BUFFER_CHUNKS = 5
+  public static readonly PROCESS_UNIT = 128
+
+  /**
+   * Creates a FrameBufferConfig instance.
+   * @param params - The parameters for the FrameBuffer.
+   * @returns A new instance of FrameBufferConfig.
+   */
+  public static createFrameBufferConfig(params: FrameBufferParams): FrameBufferConfig {
+    return {
+      sampleBuffer: new Float32Array(
+        new SharedArrayBuffer(params.frameBufferSize * params.channelCount * Float32Array.BYTES_PER_ELEMENT),
+      ),
+      samplesPerFrame: params.channelCount,
+      usedFramesInBuffer: new Uint32Array(new SharedArrayBuffer(Uint32Array.BYTES_PER_ELEMENT)),
+      totalReadFrames: new BigUint64Array(new SharedArrayBuffer(BigUint64Array.BYTES_PER_ELEMENT)),
+      totalWriteFrames: new BigUint64Array(new SharedArrayBuffer(BigUint64Array.BYTES_PER_ELEMENT)),
+    }
+  }
+
+  /**
+   * Creates a FillerFrameBufferConfig instance.
+   * @param defaultSampleRate - The sample rate of the audio context.
+   * @param params - The parameters for the FillerFrameBuffer.
+   * @returns A new instance of FillerFrameBufferConfig.
+   */
+  public static createFillerFrameBufferConfig(defaultSampleRate: number, params: FillerFrameBufferParams): FillerFrameBufferConfig {
+    const sampleRate = params.sampleRate ?? defaultSampleRate
+    const intervalMillisecond = params.fillInterval ?? FrameBufferFactory.DEFAULT_FILL_INTERVAL_MS
+    const frameBufferSize = Math.floor(
+      sampleRate * intervalMillisecond / 1000 + (FrameBufferFactory.PROCESS_UNIT - 1),
+    ) & ~(FrameBufferFactory.PROCESS_UNIT - 1)
+    const frameBufferChunkCount = params.frameBufferChunks ?? FrameBufferFactory.DEFAULT_FRAME_BUFFER_CHUNKS
+    const config = FrameBufferFactory.createFrameBufferConfig(
+      { frameBufferSize: frameBufferSize * frameBufferChunkCount, channelCount: params.channelCount })
+    return {
+      ...config,
+      sampleRate,
+      fillInterval: intervalMillisecond,
+    }
+  }
+}

package/src/frame-buffer/buffer-filler.ts

@@ -0,0 +1,14 @@
+import type { FrameBufferWriter } from './buffer-writer'
+
+/**
+ * FrameBufferFiller interface
+ * This interface defines a method to fill audio frames into a buffer.
+ */
+export interface FrameBufferFiller {
+  /**
+   * Fill the buffer with audio frames using the provided writer.
+   * @param writer - An instance of FrameBufferWriter used to write audio frames to the buffer.
+   * @returns A boolean indicating whether to continue playback.
+   */
+  fill(writer: FrameBufferWriter): boolean
+}

package/src/frame-buffer/buffer-reader.ts

@@ -0,0 +1,56 @@
+import { enumFrames, type FrameCallback } from './buffer-utils'
+import { FrameBuffer } from './buffer'
+
+/**
+ * FrameBufferReader class
+ * This class reads audio frame data from a shared Float32Array buffer and processes it.
+ * The buffer usage is tracked using a Uint32Array.
+ */
+export class FrameBufferReader {
+  private readonly _frameBuffer: FrameBuffer
+  private readonly _usedFrameInBuffer: Uint32Array
+  private readonly _totalFrames: BigUint64Array
+  private _index: number = 0
+
+  /**
+   * Creates an instance of FrameBufferReader.
+   * @param frameBuffer - The shared buffer to read from.
+   * @param usedFrameInBuffer - The Uint32Array tracking the usage of the buffer.
+   * @param totalFrames - The BigUint64Array tracking the total frames read from the buffer.
+   */
+  constructor(frameBuffer: FrameBuffer, usedFrameInBuffer: Uint32Array, totalFrames: BigUint64Array) {
+    this._frameBuffer = frameBuffer
+    this._usedFrameInBuffer = usedFrameInBuffer
+    this._totalFrames = totalFrames
+  }
+
+  /**
+   * Get the number of available frames in the buffer.
+   * @returns The number of available frames in the buffer.
+   */
+  public get available(): number {
+    return Atomics.load(this._usedFrameInBuffer, 0)
+  }
+
+  /**
+   * Get the total number of frames read from the buffer.
+   * @returns The total number of frames read.
+   */
+  public get totalFrames(): bigint {
+    return this._totalFrames[0]
+  }
+
+  /**
+   * Reads audio frame data from the buffer and processes it using the provided callback.
+   * @param frameCallback - The callback function to process each section of the buffer.
+   * @returns The number of frames processed.
+   * @throws RangeError - If the processed length exceeds the part length.
+   */
+  public read(frameCallback: FrameCallback): number {
+    const result = enumFrames(this._frameBuffer, this._index, this.available, frameCallback)
+    this._index = result.nextIndex
+    Atomics.sub(this._usedFrameInBuffer, 0, result.frames)
+    Atomics.add(this._totalFrames, 0, BigInt(result.frames))
+    return result.frames
+  }
+}

package/src/frame-buffer/buffer-utils.ts

@@ -0,0 +1,48 @@
+import type { FrameBuffer } from './buffer'
+
+/**
+ * Type definition for the callback function used in enumFrames.
+ * The callback processes each section of the frame buffer.
+ * @param frame - An object containing:
+ *                - buffer: The FrameBuffer instance.
+ *                - index: The starting index in the buffer.
+ *                - frames: The number of frames in the section.
+ * @param offset - The offset in the buffer from the start of processing.
+ * @returns The number of frames processed.
+ */
+export type FrameCallback = (frame: { buffer: FrameBuffer, index: number, frames: number }, offset: number) => number
+
+/**
+ * Processes sections of a Float32Array buffer using a callback function.
+ * This function is intended for internal use only.
+ *
+ * @param buffer - The FrameBuffer to process. This buffer is expected to be shared.
+ * @param startIndex - The starting index in the buffer from where processing should begin.
+ * @param availableFrames - The total number of frames available to process in the buffer.
+ * @param frameCallback - The callback function to process each section of the buffer.
+ *                          It should return the number of frames processed.
+ * @returns An object containing:
+ *          - frames: The number of frames successfully processed.
+ *          - nextIndex: The index in the buffer for the next processing cycle.
+ * @throws RangeError - If the frameCallback returns a processed length greater than the part length.
+ */
+export const enumFrames = (buffer: FrameBuffer, startIndex: number, availableFrames: number, frameCallback: FrameCallback):
+{ frames: number, nextIndex: number } => {
+  let totalFrames = 0
+  while (totalFrames < availableFrames) {
+    // Determine the length of the current section to process
+    const sectionFrames = Math.min(buffer.length - startIndex, availableFrames - totalFrames)
+    // Process the current section using the frameCallback function
+    const processedFrames = frameCallback({ buffer, index: startIndex, frames: sectionFrames }, totalFrames)
+    // Ensure the processed length does not exceed the section length
+    if (processedFrames > sectionFrames) {
+      throw new RangeError(`Processed frames (${processedFrames}) exceeds section frames (${sectionFrames})`)
+    }
+    totalFrames += processedFrames
+    startIndex = (startIndex + processedFrames) % buffer.length
+    if (processedFrames < sectionFrames) {
+      break
+    }
+  }
+  return { frames: totalFrames, nextIndex: startIndex }
+}

package/src/frame-buffer/buffer-writer.ts

@@ -0,0 +1,56 @@
+import { enumFrames, type FrameCallback } from './buffer-utils'
+import { FrameBuffer } from './buffer'
+
+/**
+ * FrameBufferWriter class
+ * This class writes audio frame data to a shared Float32Array buffer.
+ * The buffer usage is tracked using a Uint32Array.
+ */
+export class FrameBufferWriter {
+  private readonly _frameBuffer: FrameBuffer
+  private readonly _usedFrameInBuffer: Uint32Array
+  private readonly _totalFrames: BigUint64Array
+  private _index: number = 0
+
+  /**
+   * Creates an instance of FrameBufferWriter.
+   * @param frameBuffer - The shared buffer to write to.
+   * @param usedFrameInBuffer - The Uint32Array tracking the usage of the buffer.
+   * @param totalFrames - The BigUint64Array tracking the total frames written to the buffer.
+   */
+  constructor(frameBuffer: FrameBuffer, usedFrameInBuffer: Uint32Array, totalFrames: BigUint64Array) {
+    this._frameBuffer = frameBuffer
+    this._usedFrameInBuffer = usedFrameInBuffer
+    this._totalFrames = totalFrames
+  }
+
+  /**
+   * Get the number of available spaces in the buffer.
+   * @returns The number of available spaces in the buffer.
+   */
+  public get available(): number {
+    return this._frameBuffer.length - Atomics.load(this._usedFrameInBuffer, 0)
+  }
+
+  /**
+   * Get the total number of frames written to the buffer.
+   * @returns The total number of frames written.
+   */
+  public get totalFrames(): bigint {
+    return this._totalFrames[0]
+  }
+
+  /**
+   * Write audio frame data to the buffer using the provided frameCallback.
+   * @param frameCallback - The frameCallback function to process each section of the buffer.
+   * @returns The number of frames processed.
+   * @throws RangeError - If the processed length exceeds the part length.
+   */
+  public write(frameCallback: FrameCallback): number {
+    const result = enumFrames(this._frameBuffer, this._index, this.available, frameCallback)
+    this._index = result.nextIndex
+    Atomics.add(this._usedFrameInBuffer, 0, result.frames)
+    Atomics.add(this._totalFrames, 0, BigInt(result.frames))
+    return result.frames
+  }
+}

package/src/frame-buffer/buffer.ts

@@ -0,0 +1,68 @@
+/**
+ * FrameBuffer class
+ * This class manages a buffer of audio frames.
+ */
+export class FrameBuffer {
+  private readonly _buffer: Float32Array
+  private readonly _samplesPerFrame: number
+  private readonly _length: number
+
+  /**
+   * Creates an instance of FrameBuffer.
+   * @param buffer - The Float32Array buffer to manage.
+   * @param samplesPerFrame - The number of samples per frame.
+   */
+  public constructor(buffer: Float32Array, samplesPerFrame: number) {
+    this._buffer = buffer
+    this._samplesPerFrame = samplesPerFrame
+    this._length = Math.floor(buffer.length / samplesPerFrame)
+  }
+
+  /**
+   * Sets the frame data in the buffer.
+   * @param index - The starting index in the buffer.
+   * @param samples - The samples to set in the buffer.
+   * @param sampleStart - The starting position in the samples array (default is 0).
+   * @param sampleCount - The number of samples to set (default is the length of the samples array).
+   * @returns A number of written frames.
+   * @throws Error - If the number of samples per frame does not match the specified number of samples.
+   */
+  public setFrames(index: number, samples: Float32Array, sampleStart: number = 0, sampleCount?: number): number {
+    index *= this._samplesPerFrame
+    const sampleEnd = Math.min((sampleCount !== undefined) ? (sampleStart + sampleCount) : samples.length, samples.length)
+    const frames = (sampleEnd - sampleStart) / this._samplesPerFrame
+    if (!Number.isInteger(frames)) {
+      throw new Error(`Error: The number of samples per frame does not match the specified number of samples. Expected samples per frame: ${this._samplesPerFrame}, but got: ${sampleEnd - sampleStart}.`)
+    }
+    for (let sampleIndex = sampleStart; sampleIndex < sampleEnd; ++sampleIndex, ++index) {
+      this._buffer[index] = samples[sampleIndex]
+    }
+    return frames
+  }
+
+  /**
+   * Converts the frame data to output.
+   * This method is intended to be called from within the process method of the AudioWorkletProcessor.
+   * It converts the interleaved frame data to the structure expected by the process method's outputs.
+   * @param frameIndex - The index of the frame to convert.
+   * @param frames - The number of frames to convert.
+   * @param output - The output array to store the converted data.
+   * @param outputOffset - The offset in the output array at which to start storing the data.
+   */
+  public convertToOutput(frameIndex: number, frames: number, output: Float32Array[], outputOffset: number): void {
+    const samplesPerFrame = this._samplesPerFrame
+    output.forEach((outputChannel, channelNumber) => {
+      for (let i = channelNumber, j = 0; j < frames; i += samplesPerFrame, ++j) {
+        outputChannel[outputOffset + j] = this._buffer[frameIndex + i]
+      }
+    })
+  }
+
+  /**
+   * Gets the length of the buffer in frames.
+   * @returns The length of the buffer in frames.
+   */
+  public get length(): number {
+    return this._length
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { StopEvent, UnderrunEvent } from './events'
+export type { OutputStreamNode } from './output-stream-node'
+export type { FrameBufferWriter } from './frame-buffer/buffer-writer'
+export type { FrameBufferFiller } from './frame-buffer/buffer-filler'
+export { StreamNodeFactory,
+  type ManualBufferNodeParams,
+  type TimedBufferNodeParams,
+} from './stream-node-factory'
+export { BufferFillWorker } from './write-strategy/worker/worker'

package/src/output-message.ts

@@ -0,0 +1,37 @@
+/**
+ * Messages sent from the processor to the main thread.
+ *
+ * @typeParam type - The type of message. Can be 'stop' or 'underrun'.
+ *
+ * For 'stop' messages:
+ * @property frames - The total frames processed when stopped.
+ *
+ * For 'underrun' messages:
+ * @property frames - The number of frames that have been underrun.
+ *
+ * Example:
+ * ```typescript
+ * const message: MessageToAudioNode = { type: 'stop', frames: 1000n };
+ * // or
+ * const message: MessageToAudioNode = { type: 'underrun', frames: 256 };
+ * ```
+ */
+export type MessageToAudioNode =
+  | { type: 'stop', frames: bigint }
+  | { type: 'underrun', frames: number }
+
+/**
+ * Messages sent from the main thread to the processor.
+ *
+ * @typeParam type - The type of message. Can be 'stop'.
+ *
+ * For 'stop' messages:
+ * @property frames - The position in frames to stop at.
+ *
+ * Example:
+ * ```typescript
+ * const message: MessageToProcessor = { type: 'stop', frames: 1000n };
+ * ```
+ */
+export type MessageToProcessor =
+  | { type: 'stop', frames: bigint }

package/src/output-stream-node.ts

@@ -0,0 +1,197 @@
+import type { MessageToProcessor, MessageToAudioNode } from './output-message'
+import type { OutputStreamProcessorOptions } from './output-stream-processor'
+import { PROCESSOR_NAME } from './constants'
+import { StopEvent, UnderrunEvent } from './events'
+import { BufferWriteStrategy } from './write-strategy/strategy'
+import { FrameBufferConfig } from './frame-buffer/buffer-factory'
+
+/**
+ * Stream state
+ * Represents the different states of the stream.
+ */
+export type StreamState =
+  // Initial state where playback can start
+  | 'ready'
+    // State where playback has started
+  | 'started'
+   // State where playback is stopping
+  | 'stopping'
+    // State where playback has stopped
+  | 'stopped'
+
+/**
+ * OutputStreamNode class
+ * This class extends AudioWorkletNode to handle audio processing.
+ * It manages a buffer using a FrameBufferWriter instance and tracks the current frame position.
+ */
+export class OutputStreamNode extends AudioWorkletNode {
+  private readonly _totalWriteFrames: BigUint64Array
+  private readonly _totalReadFrames: BigUint64Array
+  private readonly _strategy: BufferWriteStrategy
+  private _state: StreamState = 'ready'
+
+  /**
+   * Creates an instance of OutputStreamNode.
+   * @param baseAudioContext - The audio context to use.
+   * @param bufferConfig - The configuration for the buffer.
+   * @param strategy - The strategy for writing to the buffer.
+   */
+  protected constructor(
+    baseAudioContext: BaseAudioContext,
+    bufferConfig: FrameBufferConfig,
+    strategy: BufferWriteStrategy,
+  ) {
+    const processorOptions: OutputStreamProcessorOptions = {
+      ...bufferConfig,
+      totalFrames: bufferConfig.totalReadFrames,
+    }
+    super(baseAudioContext, PROCESSOR_NAME, {
+      outputChannelCount: [bufferConfig.samplesPerFrame],
+      processorOptions,
+    })
+    this._strategy = strategy
+    this._totalWriteFrames = bufferConfig.totalWriteFrames
+    this._totalReadFrames = bufferConfig.totalReadFrames
+    this.port.onmessage = this.handleMessage.bind(this)
+  }
+
+  /**
+   * Start playback.
+   * The node must be connected before starting playback using connect() method.
+   * Output samples must be written to the buffer before starting.
+   * Playback can only be started once. Once stopped, it cannot be restarted.
+   * @returns A boolean indicating whether the playback started successfully.
+   */
+  public start(): boolean {
+    if (this.numberOfOutputs === 0) {
+      throw new Error('Cannot start playback. Node is not connected.')
+    }
+    switch (this._state) {
+      case 'ready':
+        this._state = 'started'
+        if (!this._strategy.onStart(this)) {
+          this.stop(this.totalWriteFrames)
+        }
+        return true
+      case 'started':
+        return false
+      default:
+        throw new Error(`Cannot start playback. Current state: ${this._state}`)
+    }
+  }
+
+  /**
+   * Stop the node processing at a given frame position.
+   * Returns a Promise that resolves when the node has completely stopped.
+   * The node is disconnected once stopping is complete.
+   * @param frames - The frame position at which to stop the processing, in frames.
+   *                   If frames is 0 or if the current playback frame position has already passed the specified value,
+   *                   the node will stop immediately.
+   * @returns A promise that resolves when the node has stopped.
+   */
+  public stop(frames: bigint = BigInt(0)): Promise<void> {
+    switch (this._state) {
+      case 'started':
+        return new Promise((resolve) => {
+          this._state = 'stopping'
+          const message: MessageToProcessor = { type: 'stop', frames }
+          this.port.postMessage(message)
+          this.addEventListener(StopEvent.type, () => {
+            resolve()
+          }, { once: true })
+        })
+      case 'ready':
+        this.handleStopped()
+        break
+      default:
+        throw new Error(`Cannot stop playback. Current state: ${this._state}`)
+    }
+    return Promise.resolve()
+  }
+
+  /**
+   * Handles incoming messages from the audio processor.
+   * @param event - The message event from the processor.
+   */
+  private handleMessage(event: MessageEvent<MessageToAudioNode>): void {
+    switch (event.data.type) {
+      case 'stop':
+        this.handleStopped()
+        this.dispatchEvent(new StopEvent(event.data.frames))
+        break
+      case 'underrun':
+        this.dispatchEvent(new UnderrunEvent(event.data.frames))
+        break
+      default:
+        throw new Error(`Unexpected event value: ${event.data}`)
+    }
+  }
+
+  /**
+   * Handles the stopping of the node.
+   * Disconnects the node and closes the port.
+   */
+  private handleStopped() {
+    this._strategy.onStopped()
+    this.disconnect()
+    this.port.close()
+    this.port.onmessage = null
+    this._state = 'stopped'
+  }
+
+  /**
+   * Checks if playback has started.
+   * @returns A boolean indicating if playback has started.
+   */
+  public get isStart(): boolean {
+    return this._state === 'started'
+  }
+
+  /**
+   * Get the current frame position since the start of playback.
+   * The position is in frames and increases by 1 for each frame.
+   * It represents the total number of frames processed by the AudioWorkletProcessor.
+   * - AudioWorkletProcessor has read this total number of frames from the buffer.
+   *   It closely indicates the playback position in frames.
+   * - totalReadFrames will never exceed the number of frames written to the buffer,
+   *   ensuring it is always less than or equal to totalWriteFrames.
+   * - The difference between totalWriteFrames and totalReadFrames represents the delay
+   *   in samples before playback (excluding processing beyond the AudioNode).
+   * @returns The current frame position as a bigint.
+   */
+  public get totalReadFrames(): bigint {
+    return Atomics.load(this._totalReadFrames, 0)
+  }
+
+  /**
+   * Get the total number of frames written to the buffer.
+   * This reflects the total frames written by the BufferWriteStrategy.
+   * Note: The method of writing to the buffer is implemented by the BufferWriteStrategy.
+   * The OutputStreamNode itself does not modify this value.
+   * @returns The total number of frames written as a bigint.
+   */
+  public get totalWriteFrames(): bigint {
+    return Atomics.load(this._totalWriteFrames, 0)
+  }
+}
+
+/**
+ * OutputStreamNodeFactory class
+ * Factory class to create instances of OutputStreamNode.
+ */
+export class OutputStreamNodeFactory extends OutputStreamNode {
+  /**
+   * Creates an instance of OutputStreamNodeFactory.
+   * @param audioContext - The audio context to use.
+   * @param info - The configuration for the buffer.
+   * @param strategy - The strategy for writing to the buffer.
+   * @returns A promise that resolves to an instance of OutputStreamNodeFactory.
+   */
+  public static async create(audioContext: BaseAudioContext, info: FrameBufferConfig, strategy: BufferWriteStrategy): Promise<OutputStreamNode> {
+    const node = new OutputStreamNodeFactory(audioContext, info, strategy)
+    if (!(await strategy.onInit(node))) {
+      throw new Error('Failed to onPrepare.')
+    }
+    return node
+  }
+}