@ain1084/audio-worklet-stream 0.1.2

package/src/output-stream-processor.ts

@@ -0,0 +1,124 @@
+import { FrameBufferReader } from './frame-buffer/buffer-reader'
+import { PROCESSOR_NAME } from './constants'
+import type { MessageToAudioNode, MessageToProcessor } from './output-message'
+import { FrameBuffer } from './frame-buffer/buffer'
+
+/**
+ * Options for the OutputStreamProcessor
+ * @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 totalFrames - The current position in the buffer, in frames.
+ */
+export type OutputStreamProcessorOptions = Readonly<{
+  sampleBuffer: Float32Array
+  samplesPerFrame: number
+  usedFramesInBuffer: Uint32Array
+  totalFrames: BigUint64Array
+}>
+
+const createFrameBufferReader = (options: OutputStreamProcessorOptions) => {
+  return new FrameBufferReader(
+    new FrameBuffer(options.sampleBuffer, options.samplesPerFrame),
+    options.usedFramesInBuffer, options.totalFrames,
+  )
+}
+
+/**
+ * OutputStreamProcessor class
+ * This class extends AudioWorkletProcessor to process audio data.
+ * It uses a FrameBufferReader instance to read from a shared buffer and manage the audio data.
+ */
+class OutputStreamProcessor extends AudioWorkletProcessor {
+  private readonly _frameReader: FrameBufferReader
+  private _shouldStop = false
+  private _stopFrames: bigint | undefined
+  private _underrunFrames = 0
+
+  /**
+   * Creates an instance of OutputStreamProcessor.
+   * @param options - The options for the processor, including shared buffers.
+   */
+  constructor(options: AudioWorkletNodeOptions) {
+    super()
+    this._frameReader = createFrameBufferReader(options.processorOptions as OutputStreamProcessorOptions)
+    this.port.onmessage = this.handleMessage.bind(this)
+  }
+
+  /**
+   * Handles incoming messages from the audio node.
+   * @param event - The message event from the audio node.
+   */
+  private handleMessage(event: MessageEvent<MessageToProcessor>): void {
+    if (event.data.type !== 'stop') {
+      throw new Error(`Unexpected message type: ${event.data.type}`)
+    }
+    const frames = event.data.frames
+    if (frames <= 0) {
+      this._shouldStop = true
+    }
+    else {
+      this._stopFrames = frames
+    }
+  }
+
+  /**
+   * Updates the underrun frame count.
+   * If underrunFrames is provided and not zero, it adds to the current underrun frame count.
+   * If underrunFrames is 0, it indicates that the underrun state has been resolved,
+   * and the total underrun frame count is sent to the main thread before being reset.
+   * @param underrunFrames - The number of underrun frames to add (default is 0).
+   */
+  private updateUnderrun(underrunFrames: number = 0): void {
+    if (underrunFrames !== 0) {
+      this._underrunFrames += underrunFrames
+      return
+    }
+    if (this._underrunFrames === 0) {
+      return
+    }
+    this.port.postMessage({ type: 'underrun', frames: this._underrunFrames } as MessageToAudioNode)
+    this._underrunFrames = 0
+  }
+
+  /**
+   * Checks the stop condition.
+   * @param totalFrames - The total number of frames processed so far.
+   */
+  private checkStopCondition(totalFrames: bigint) {
+    if (this._stopFrames !== undefined && totalFrames >= this._stopFrames) {
+      this._shouldStop = true
+    }
+  }
+
+  /**
+   * Processes the audio data.
+   * @param _inputs - The input audio data.
+   * @param outputs - The output audio data.
+   * @returns A boolean indicating whether to continue processing.
+   */
+  process(_inputs: Float32Array[][], outputs: Float32Array[][]): boolean {
+    const output = outputs[0]
+    const readFrames = this._frameReader.read((frame, offset) => {
+      const frames = Math.min(frame.frames, output[0].length - offset)
+      frame.buffer.convertToOutput(frame.index, frames, output, offset)
+      return frames
+    })
+    const totalFrames = this._frameReader.totalFrames
+    this.checkStopCondition(totalFrames)
+    if (this._shouldStop) {
+      this.updateUnderrun()
+      this.port.postMessage({ type: 'stop', frames: totalFrames } as MessageToAudioNode)
+      this.port.close()
+      return false
+    }
+    const underrunFrames = output[0].length - readFrames
+    // It seems process may be called before connect?
+    if (totalFrames !== BigInt(0)) {
+      this.updateUnderrun(underrunFrames)
+    }
+    return true
+  }
+}
+
+registerProcessor(PROCESSOR_NAME, OutputStreamProcessor)

package/src/stream-node-factory.ts

@@ -0,0 +1,161 @@
+import processor from './output-stream-processor?worker&url'
+import { ManualBufferWriteStrategy } from './write-strategy/manual'
+import { FrameBufferFactory } from './frame-buffer/buffer-factory'
+import type { OutputStreamNode, OutputStreamNodeFactory } from './output-stream-node'
+import { TimedBufferWriteStrategy } from './write-strategy/timed'
+import type { FrameBufferFiller } from './frame-buffer/buffer-filler'
+import { FrameBufferWriter } from './frame-buffer/buffer-writer'
+import { WorkerBufferWriteStrategy } from './write-strategy/worker/strategy'
+
+/**
+ * Parameters for creating a manual buffer node.
+ */
+export type ManualBufferNodeParams = Readonly<{
+  /** The number of audio channels. */
+  channelCount: number
+  /** The size of the frame buffer in frames. */
+  frameBufferSize: number
+}>
+
+/**
+ * Parameters for creating a timed buffer node.
+ */
+export type TimedBufferNodeParams = Readonly<{
+  /** The number of audio channels. */
+  channelCount: number
+  /** Optional. The number of chunks in the frame buffer. */
+  frameBufferChunks?: number
+  /** Optional. The interval in milliseconds for filling the buffer. */
+  fillInterval?: number
+  /** Optional. The sample rate of the audio context. */
+  sampleRate?: number
+}>
+
+/**
+ * Parameters for creating a worker buffer node.
+ */
+export type WorkerBufferNodeParams<T> = TimedBufferNodeParams & Readonly<{
+  /** Parameters specific to the filler used in the worker. */
+  fillerParams: T
+}>
+
+/**
+ * StreamNodeFactory class
+ * Factory class to create instances of OutputStreamNode with specific BufferWriteStrategy.
+ * This class provides methods to create different types of OutputStreamNodes,
+ * such as those using manual, timed, or worker-based buffer writing strategies.
+ */
+export class StreamNodeFactory {
+  private _audioContext: AudioContext
+  private readonly _outputStreamNodeFactory: typeof OutputStreamNodeFactory
+
+  /**
+   * Constructor for StreamNodeFactory.
+   * @param context - The AudioContext to use.
+   * @param outputStreamNodeFactory - The factory for creating OutputStreamNode instances.
+   */
+  private constructor(context: AudioContext, outputStreamNodeFactory: typeof OutputStreamNodeFactory) {
+    this._audioContext = context
+    this._outputStreamNodeFactory = outputStreamNodeFactory
+  }
+
+  /**
+   * Create an instance of StreamNodeFactory.
+   * This method loads necessary modules and creates node creators.
+   * @param context - The AudioContext to use.
+   * @returns A promise that resolves to an instance of StreamNodeFactory.
+   * @throws Error - If module loading fails.
+   */
+  public static async create(context: AudioContext): Promise<StreamNodeFactory> {
+    try {
+      const loadResults = await Promise.all([
+        context.audioWorklet.addModule(processor),
+        import('./output-stream-node'),
+      ])
+      return new StreamNodeFactory(context, loadResults[1].OutputStreamNodeFactory)
+    }
+    catch (error) {
+      throw new Error('Failed to load modules: ' + error)
+    }
+  }
+
+  /**
+   * Creates an OutputStreamNode with manual buffer writing strategy.
+   * @param params - The parameters for manual buffer node creation.
+   * @returns A promise that resolves to an OutputStreamNode and FrameBufferWriter instance.
+   */
+  public async createManualBufferNode(params: ManualBufferNodeParams): Promise<[OutputStreamNode, FrameBufferWriter]> {
+    if (params.channelCount <= 0 || !Number.isInteger(params.channelCount)) {
+      throw new Error('Invalid channelCount: must be a positive integer.')
+    }
+    if (params.frameBufferSize <= 0 || !Number.isInteger(params.frameBufferSize)) {
+      throw new Error('Invalid frameBufferSize: must be a positive integer.')
+    }
+    const bufferConfig = FrameBufferFactory.createFrameBufferConfig({ ...params })
+    const strategy = new ManualBufferWriteStrategy(bufferConfig)
+    return [await this._outputStreamNodeFactory.create(this.audioContext, bufferConfig, strategy), strategy.writer]
+  }
+
+  /**
+   * Creates an OutputStreamNode with timed buffer writing strategy.
+   * @param frameFiller - The FrameBufferFiller instance.
+   * @param params - The parameters for timed buffer node creation.
+   * @returns A promise that resolves to an OutputStreamNode instance.
+   */
+  public async createTimedBufferNode(
+    frameFiller: FrameBufferFiller, params: TimedBufferNodeParams,
+  ): Promise<OutputStreamNode> {
+    StreamNodeFactory.validateTimedBufferNodeParams(params)
+    if (typeof frameFiller !== 'object' || frameFiller === null) {
+      throw new Error('Invalid frameFiller: must be an object.')
+    }
+    const config = FrameBufferFactory.createFillerFrameBufferConfig(this._audioContext.sampleRate, { ...params })
+    const strategy = new TimedBufferWriteStrategy(config, frameFiller)
+    return this._outputStreamNodeFactory.create(this.audioContext, config, strategy)
+  }
+
+  /**
+   * Creates an OutputStreamNode with worker buffer writing strategy.
+   * @param worker - The worker instance.
+   * @param params - The parameters for worker buffer node creation.
+   * @returns A promise that resolves to an OutputStreamNode instance.
+   */
+  public async createWorkerBufferNode<FillerParams>(
+    worker: new () => Worker, params: WorkerBufferNodeParams<FillerParams>,
+  ): Promise<OutputStreamNode> {
+    StreamNodeFactory.validateTimedBufferNodeParams(params)
+    const config = FrameBufferFactory.createFillerFrameBufferConfig(this._audioContext.sampleRate, { ...params })
+    const strategy = new WorkerBufferWriteStrategy<FillerParams>(config, worker, params.fillerParams)
+    return this._outputStreamNodeFactory.create(this._audioContext, config, strategy)
+  }
+
+  /**
+   * Validates the parameters for timed buffer node creation.
+   * @param params - The parameters to validate.
+   * @throws Error - If validation fails.
+   */
+  private static validateTimedBufferNodeParams(params: TimedBufferNodeParams): void {
+    // Check if 'channelCount' is a positive integer
+    if (!Number.isInteger(params.channelCount) || params.channelCount <= 0) {
+      throw new Error('Invalid channelCount: must be a positive integer.')
+    }
+
+    // Check if 'fillInterval' is a positive number if provided
+    if (params.fillInterval !== undefined && (typeof params.fillInterval !== 'number' || params.fillInterval <= 0)) {
+      throw new Error('Invalid fillInterval: must be a positive number.')
+    }
+
+    // Check if 'frameBufferChunks' is a positive integer if provided
+    if (params.frameBufferChunks !== undefined && (!Number.isInteger(params.frameBufferChunks) || params.frameBufferChunks <= 0)) {
+      throw new Error('Invalid frameBufferChunks: must be a positive integer.')
+    }
+  }
+
+  /**
+   * Get the AudioContext associated with this factory.
+   * @returns The AudioContext instance.
+   */
+  public get audioContext(): BaseAudioContext {
+    return this._audioContext
+  }
+}

package/src/write-strategy/manual.ts

@@ -0,0 +1,50 @@
+import { BufferWriteStrategy } from './strategy'
+import { createFrameBufferWriter, FrameBufferConfig } from '../frame-buffer/buffer-factory'
+import { FrameBufferWriter } from '../frame-buffer/buffer-writer'
+
+/**
+  * ManualBufferWriteStrategy class
+  * Implements the BufferWriteStrategy interface for manually writing to the buffer.
+  */
+export class ManualBufferWriteStrategy implements BufferWriteStrategy {
+  private readonly _writer: FrameBufferWriter
+
+  /**
+   * Creates an instance of ManualBufferWriteStrategy.
+   * @param config - The configuration for the frame buffer.
+   */
+  constructor(config: FrameBufferConfig) {
+    this._writer = createFrameBufferWriter(config)
+  }
+
+  /**
+   * Gets the FrameBufferWriter instance.
+   * @returns The FrameBufferWriter instance.
+   */
+  public get writer(): FrameBufferWriter {
+    return this._writer
+  }
+
+  /**
+   * Initializes the strategy.
+   * @param node - The OutputStreamNode instance.
+   * @returns A promise that resolves to true when initialization is complete.
+   */
+  async onInit(/* node: OutputStreamNode */): Promise<boolean> {
+    return true
+  }
+
+  /**
+   * Starts the strategy.
+   * @param node - The OutputStreamNode instance.
+   * @returns A boolean indicating whether the strategy started successfully.
+   */
+  onStart(/* node: OutputStreamNode */): boolean {
+    return true
+  }
+
+  /**
+   * Stops the strategy.
+   */
+  onStopped(): void {}
+}

package/src/write-strategy/strategy.ts

@@ -0,0 +1,26 @@
+import type { OutputStreamNode } from '../output-stream-node'
+
+/**
+ * BufferWriteStrategy interface
+ * Defines the methods for buffer writing strategies.
+ */
+export interface BufferWriteStrategy {
+  /**
+   * Initializes the strategy.
+   * @param node - The OutputStreamNode instance.
+   * @returns A promise that resolves to true when initialization is complete.
+   */
+  onInit(node: OutputStreamNode): Promise<boolean>
+
+  /**
+   * Starts the strategy.
+   * @param node - The OutputStreamNode instance.
+   * @returns A boolean indicating whether the strategy started successfully.
+   */
+  onStart(node: OutputStreamNode): boolean
+
+  /**
+   * Stops the strategy.
+   */
+  onStopped(): void
+}

package/src/write-strategy/timed.ts

@@ -0,0 +1,103 @@
+import { BufferWriteStrategy } from './strategy'
+import { createFrameBufferWriter, FillerFrameBufferConfig } from '../frame-buffer/buffer-factory'
+import { FrameBufferWriter } from '../frame-buffer/buffer-writer'
+import { FrameBufferFiller } from '../frame-buffer/buffer-filler'
+import { OutputStreamNode } from '../output-stream-node'
+
+/**
+ * PlayContext class
+ * Manages the buffer filling process using a timer.
+ */
+class PlayContext {
+  private _timerId: number = 0
+
+  /**
+   * Creates an instance of PlayContext.
+   * @param node - The OutputStreamNode instance.
+   * @param writer - The FrameBufferWriter instance.
+   * @param filler - The FrameBufferFiller instance.
+   * @param fillInterval - The interval in milliseconds for filling the buffer.
+   */
+  constructor(node: OutputStreamNode, writer: FrameBufferWriter, filler: FrameBufferFiller, fillInterval: number) {
+    this._timerId = window.setInterval(() => {
+      if (!this._timerId || !node.isStart) {
+        return
+      }
+      try {
+        if (!filler.fill(writer)) {
+          node.stop(writer.totalFrames)
+        }
+      }
+      catch (error) {
+        this.cleanup()
+        node.stop()
+      }
+    }, fillInterval)
+  }
+
+  /**
+   * Cleans up the timer.
+   */
+  public cleanup() {
+    if (this._timerId) {
+      clearInterval(this._timerId)
+      this._timerId = 0
+    }
+  }
+}
+
+/**
+ * TimedBufferWriteStrategy class
+ * Implements the BufferWriteStrategy interface using a timer to manage buffer filling.
+ */
+export class TimedBufferWriteStrategy implements BufferWriteStrategy {
+  private readonly _writer: FrameBufferWriter
+  private readonly _filler: FrameBufferFiller
+  private readonly _interval: number
+  private readonly _isContinuePlayback: boolean
+  private _context: PlayContext | null = null
+
+  /**
+   * Creates an instance of TimedBufferWriteStrategy.
+   * @param config - The configuration for the filler frame buffer.
+   * @param filler - The FrameBufferFiller instance.
+   */
+  constructor(config: FillerFrameBufferConfig, filler: FrameBufferFiller) {
+    this._writer = createFrameBufferWriter(config)
+    this._filler = filler
+    this._interval = config.fillInterval
+    this._isContinuePlayback = this._filler.fill(this._writer)
+  }
+
+  /**
+   * Initializes the strategy.
+   * @returns A promise that resolves to true when initialization is complete.
+   */
+  async onInit(/* node: OutputStreamNode */): Promise<boolean> {
+    return true
+  }
+
+  /**
+   * Starts the strategy.
+   * @param node - The OutputStreamNode instance.
+   * @returns A boolean indicating whether the strategy started successfully.
+   */
+  onStart(node: OutputStreamNode): boolean {
+    if (this._context) {
+      throw new Error('Invalid state: context is not null.')
+    }
+    if (!this._isContinuePlayback) {
+      return false
+    }
+    this._context = new PlayContext(node, this._writer, this._filler, this._interval)
+    return true
+  }
+
+  /**
+   * Stops the strategy.
+   */
+  onStopped(): void {
+    this._context?.cleanup()
+    this._context = null
+  }
+}

package/src/write-strategy/worker/message.ts

@@ -0,0 +1,48 @@
+import type { FillerFrameBufferConfig } from '../../frame-buffer/buffer-factory'
+
+/**
+ * Message sent from the main thread to the worker.
+ *
+ * @typeParam FillerParams - The type of the parameters for the FrameBufferFiller.
+ *
+ * For 'init' messages:
+ * @property config - The configuration for the filler frame buffer.
+ * @property fillerParams - The parameters for the FrameBufferFiller.
+ *
+ * For 'start' messages:
+ *
+ * For 'stop' messages:
+ *
+ * Example:
+ * ```typescript
+ * const message: MessageToWorker<YourFillerParams> = {
+ *   type: 'init',
+ *   config: yourConfig,
+ *   fillerParams: yourFillerParams,
+ * };
+ * ```
+ */
+export type MessageToWorker<FillerParams> =
+  | { type: 'init', config: FillerFrameBufferConfig, fillerParams: FillerParams }
+  | { type: 'start' }
+  | { type: 'stop' }
+
+/**
+ * Message sent from the worker to the main thread.
+ *
+ * For 'init-done' messages:
+ *
+ * For 'stop' messages:
+ * @property stopFrames - The position in frames to stop at.
+ *
+ * Example:
+ * ```typescript
+ * const message: MessageToStrategy = {
+ *   type: 'stop',
+ *   stopFrames: 1000n,
+ * };
+ * ```
+ */
+export type MessageToStrategy =
+  | { type: 'init-done' }
+  | { type: 'stop', stopFrames: bigint }

package/src/write-strategy/worker/strategy.ts

@@ -0,0 +1,154 @@
+import type { BufferWriteStrategy } from '../strategy'
+import type { FillerFrameBufferConfig } from '../../frame-buffer/buffer-factory'
+import type { MessageToStrategy, MessageToWorker } from './message'
+import type { OutputStreamNode } from '../../output-stream-node'
+
+/**
+ * Parameters for creating a PlayContext.
+ * @property node - The OutputStreamNode instance.
+ * @property config - The FillerFrameBufferConfig instance.
+ * @property workerConstructor - The constructor for the Worker.
+ * @property fillerParam - The parameters for the FrameBufferFiller.
+ */
+type PlayerContextParams<FillerParams> = Readonly<{
+  node: OutputStreamNode
+  config: FillerFrameBufferConfig
+  workerConstructor: new () => Worker
+  fillerParam: FillerParams
+}>
+
+/**
+ * PlayContext class
+ * Manages the buffer filling process within a web worker.
+ */
+class Context<FillerParams> {
+  private readonly _node: OutputStreamNode
+  private readonly _config: FillerFrameBufferConfig
+  private readonly _fillerParam: FillerParams
+  private readonly _worker: Worker
+
+  /**
+   * Creates an instance of PlayContext.
+   * @param params - The parameters for the PlayContext.
+   */
+  private constructor(params: PlayerContextParams<FillerParams>) {
+    this._node = params.node
+    this._config = params.config
+    this._worker = new params.workerConstructor()
+    this._fillerParam = params.fillerParam
+    this._worker.onmessage = this.handleWorkerMessage.bind(this)
+  }
+
+  /**
+   * Creates and initializes an instance of PlayContext.
+   * @param params - The parameters for the PlayContext.
+   * @returns A promise that resolves to an instance of PlayContext.
+   */
+  public static async create<FillerParams>(params: PlayerContextParams<FillerParams>) {
+    const instance = new Context(params)
+    await instance.init()
+    return instance
+  }
+
+  /**
+   * Handles messages from the worker.
+   * @param ev - The message event from the worker.
+   */
+  private handleWorkerMessage(ev: MessageEvent<MessageToStrategy>): void {
+    if (ev.data.type === 'stop') {
+      this._node.stop(ev.data.stopFrames)
+    }
+  }
+
+  /**
+   * Initializes the PlayContext by sending the 'init' message to the worker.
+   * @returns A promise that resolves when initialization is complete.
+   */
+  private init() {
+    return new Promise<void>((resolve) => {
+      const message: MessageToWorker<FillerParams> = {
+        type: 'init',
+        config: this._config,
+        fillerParams: this._fillerParam,
+      }
+      this._worker.postMessage(message)
+      const listener = (ev: MessageEvent<MessageToStrategy>) => {
+        if (ev.data.type === 'init-done') {
+          this._worker.removeEventListener('message', listener)
+          resolve()
+        }
+      }
+      this._worker.addEventListener('message', listener)
+    })
+  }
+
+  /**
+   * Starts the buffer filling process by sending the 'start' message to the worker.
+   */
+  public start() {
+    const message: MessageToWorker<FillerParams> = {
+      type: 'start',
+    }
+    this._worker.postMessage(message)
+  }
+
+  /**
+   * Stops the worker and terminates it.
+   */
+  public stopped() {
+    this._worker.onmessage = null
+    this._worker.terminate()
+  }
+}
+
+/**
+ * WorkerBufferWriteStrategy class
+ * Implements the BufferWriteStrategy interface using a web worker to manage buffer filling.
+ */
+export class WorkerBufferWriteStrategy<FillerParam> implements BufferWriteStrategy {
+  private readonly _createPlayContext: (node: OutputStreamNode) => Promise<Context<FillerParam>>
+  private _context: Context<FillerParam> | null = null
+
+  /**
+   * Creates an instance of WorkerBufferWriteStrategy.
+   * @param config - The configuration for the filler frame buffer.
+   * @param workerConstructor - The constructor for the Worker.
+   * @param fillerParam - The parameters for the FrameBufferFiller.
+   */
+  constructor(config: FillerFrameBufferConfig, workerConstructor: new () => Worker, fillerParam: FillerParam) {
+    this._createPlayContext = (node: OutputStreamNode) => Context.create<FillerParam>({ node, config, workerConstructor, fillerParam })
+  }
+
+  /**
+   * Initializes the strategy.
+   * @param node - The OutputStreamNode instance.
+   * @returns A promise that resolves to true when initialization is complete.
+   */
+  async onInit(node: OutputStreamNode): Promise<boolean> {
+    this._context = await this._createPlayContext(node)
+    return true
+  }
+
+  /**
+   * Starts the strategy.
+   * @param node - The OutputStreamNode instance.
+   * @returns A boolean indicating whether the strategy started successfully.
+   */
+  onStart(/* node: OutputStreamNode */): boolean {
+    if (!this._context) {
+      throw new Error('Invalid state: context is null.')
+    }
+    this._context.start()
+    return true
+  }
+
+  /**
+   * Stops the strategy.
+   */
+  onStopped(): void {
+    if (!this._context) {
+      throw new Error('Invalid state: context is null.')
+    }
+    this._context.stopped()
+  }
+}