react-native-audio-api 0.11.0-alpha.1 → 0.11.0-nightly-9f40b78-20251108

package/scripts/validate-worklets-version.js

@@ -0,0 +1,28 @@
+'use strict';
+const semverPrerelease = require('semver/functions/prerelease');
+const validWorkletsVersions = [
+  '0.6.0',
+  '0.6.1',
+];
+
+function validateVersion() {
+  let workletsVersion;
+  try {
+    const { version } = require('react-native-worklets/package.json');
+    workletsVersion = version;
+  } catch (e) {
+    return false;
+  }
+  if (semverPrerelease(workletsVersion)) {
+    return true;
+  }
+
+  return validWorkletsVersions.includes(workletsVersion);
+}
+
+if (!validateVersion()) {
+  console.warn(
+    '[RNAudioApi] Incompatible version of react-native-audio-worklets detected. Please install a compatible version if you want to use worklet nodes in react-native-audio-api.',
+  );
+  process.exit(1);
+}

package/src/api.ts

@@ -1,12 +1,13 @@
+import { NativeAudioAPIModule } from './specs';
+import { AudioRecorderOptions } from './types';
 import type {
   IAudioContext,
   IAudioDecoder,
-  IAudioEventEmitter,
   IAudioRecorder,
   IAudioStretcher,
   IOfflineAudioContext,
+  IAudioEventEmitter,
 } from './interfaces';
-import { NativeAudioAPIModule } from './specs';
 
 /* eslint-disable no-var */
 declare global {
@@ -24,7 +25,7 @@ declare global {
     audioWorkletRuntime: any
   ) => IOfflineAudioContext;
 
-  var createAudioRecorder: () => IAudioRecorder;
+  var createAudioRecorder: (options: AudioRecorderOptions) => IAudioRecorder;
 
   var createAudioDecoder: () => IAudioDecoder;
 
@@ -51,33 +52,59 @@ if (
   NativeAudioAPIModule.install();
 }
 
-export { default as AnalyserNode } from './core/AnalyserNode';
+export { default as WorkletNode } from './core/WorkletNode';
+export { default as WorkletSourceNode } from './core/WorkletSourceNode';
+export { default as WorkletProcessingNode } from './core/WorkletProcessingNode';
+export { default as RecorderAdapterNode } from './core/RecorderAdapterNode';
 export { default as AudioBuffer } from './core/AudioBuffer';
-export { default as AudioBufferQueueSourceNode } from './core/AudioBufferQueueSourceNode';
 export { default as AudioBufferSourceNode } from './core/AudioBufferSourceNode';
+export { default as AudioBufferQueueSourceNode } from './core/AudioBufferQueueSourceNode';
 export { default as AudioContext } from './core/AudioContext';
-export { decodeAudioData, decodePCMInBase64 } from './core/AudioDecoder';
+export { default as OfflineAudioContext } from './core/OfflineAudioContext';
 export { default as AudioDestinationNode } from './core/AudioDestinationNode';
 export { default as AudioNode } from './core/AudioNode';
+export { default as AnalyserNode } from './core/AnalyserNode';
 export { default as AudioParam } from './core/AudioParam';
-export { default as AudioRecorder } from './core/AudioRecorder';
 export { default as AudioScheduledSourceNode } from './core/AudioScheduledSourceNode';
-export { default as changePlaybackSpeed } from './core/AudioStretcher';
 export { default as BaseAudioContext } from './core/BaseAudioContext';
 export { default as BiquadFilterNode } from './core/BiquadFilterNode';
-export { default as ConstantSourceNode } from './core/ConstantSourceNode';
 export { default as GainNode } from './core/GainNode';
-export { default as OfflineAudioContext } from './core/OfflineAudioContext';
 export { default as OscillatorNode } from './core/OscillatorNode';
-export { default as RecorderAdapterNode } from './core/RecorderAdapterNode';
 export { default as StereoPannerNode } from './core/StereoPannerNode';
+export { default as AudioRecorder } from './core/AudioRecorder';
 export { default as StreamerNode } from './core/StreamerNode';
-export { default as WorkletNode } from './core/WorkletNode';
-export { default as WorkletProcessingNode } from './core/WorkletProcessingNode';
-export { default as WorkletSourceNode } from './core/WorkletSourceNode';
-export { default as useSystemVolume } from './hooks/useSystemVolume';
+export { default as ConstantSourceNode } from './core/ConstantSourceNode';
 export { default as AudioManager } from './system';
+export { default as ConvolverNode } from './core/ConvolverNode';
+export { default as useSystemVolume } from './hooks/useSystemVolume';
+export { decodeAudioData, decodePCMInBase64 } from './core/AudioDecoder';
+export { default as changePlaybackSpeed } from './core/AudioStretcher';
+
+export {
+  OscillatorType,
+  BiquadFilterType,
+  ChannelCountMode,
+  ChannelInterpretation,
+  ContextState,
+  WindowType,
+  PeriodicWaveConstraints,
+  AudioWorkletRuntime,
+} from './types';
+
+export {
+  IOSCategory,
+  IOSMode,
+  IOSOption,
+  SessionOptions,
+  MediaState,
+  LockScreenInfo,
+  PermissionStatus,
+} from './system/types';
 
-export * from './errors';
-export * from './system/types';
-export * from './types';
+export {
+  IndexSizeError,
+  InvalidAccessError,
+  InvalidStateError,
+  RangeError,
+  NotSupportedError,
+} from './errors';

package/src/api.web.ts

@@ -13,6 +13,7 @@ export { default as GainNode } from './web-core/GainNode';
 export { default as OscillatorNode } from './web-core/OscillatorNode';
 export { default as StereoPannerNode } from './web-core/StereoPannerNode';
 export { default as ConstantSourceNode } from './web-core/ConstantSourceNode';
+export { default as ConvolverNode } from './web-core/ConvolverNode';
 
 export * from './web-core/custom';
 

package/src/core/AudioContext.ts

@@ -3,7 +3,7 @@ import BaseAudioContext from './BaseAudioContext';
 import AudioManager from '../system';
 import { AudioContextOptions } from '../types';
 import { NotSupportedError } from '../errors';
-import { isWorkletsAvailable, workletsModule } from '../utils';
+import { isWorkletsVersionSupported, workletsModule } from '../utils';
 
 export default class AudioContext extends BaseAudioContext {
   constructor(options?: AudioContextOptions) {
@@ -17,7 +17,8 @@ export default class AudioContext extends BaseAudioContext {
       );
     }
     let audioRuntime = null;
-    if (isWorkletsAvailable) {
+
+    if (isWorkletsVersionSupported) {
       audioRuntime = workletsModule.createWorkletRuntime('AudioWorkletRuntime');
     }
 

package/src/core/AudioRecorder.ts

@@ -1,143 +1,30 @@
-import { AudioEventEmitter, AudioEventSubscription } from '../events';
-import { OnAudioReadyEventType } from '../events/types';
 import { IAudioRecorder } from '../interfaces';
-import {
-  AndroidFormat,
-  AudioRecorderCallbackOptions,
-  AudioRecorderFileOptions,
-  BitDepth,
-  FileDirectory,
-  FileInfo,
-  IOSAudioQuality,
-  IOSFormat,
-} from '../types';
-import { encodeFlags } from '../utils';
+import { AudioRecorderOptions } from '../types';
 import AudioBuffer from './AudioBuffer';
+import { OnAudioReadyEventType } from '../events/types';
+import { AudioEventEmitter } from '../events';
 import RecorderAdapterNode from './RecorderAdapterNode';
 
-function withDefaultOptions(inOptions: AudioRecorderFileOptions) {
-  return {
-    directory: FileDirectory.Cache,
-    sampleRate: 48000,
-    channels: 2,
-    bitRate: 128000,
-    bitDepth: BitDepth.Bit24,
-    ...inOptions,
-    ios: {
-      format: IOSFormat.M4A,
-      quality: IOSAudioQuality.High,
-      ...(inOptions.ios ?? {}),
-    },
-    android: {
-      format: AndroidFormat.M4A,
-      ...(inOptions.android ?? {}),
-    },
-  };
-}
-
-function parseFileOptions(inOptions: AudioRecorderFileOptions) {
-  const { sampleRate, channels, bitRate, directory, bitDepth, ios, android } =
-    withDefaultOptions(inOptions);
-
-  const iosFlags = encodeFlags(
-    ios.format,
-    ios.quality,
-    ios.flacCompressionLevel || 0,
-    directory,
-    bitDepth
-  );
-
-  // TODO: ensure directory and bitDepth are last in the bitmask
-  const androidFlags = encodeFlags(android.format, directory, bitDepth);
-
-  return {
-    sampleRate,
-    channels,
-    bitRate,
-    ios: iosFlags,
-    android: androidFlags,
-  };
-}
-
 export default class AudioRecorder {
-  protected onAudioReadySubscription: AudioEventSubscription | null = null;
   protected readonly recorder: IAudioRecorder;
-  protected options_: AudioRecorderFileOptions | null = null;
-  private isFileOutputEnabled: boolean = false;
 
-  protected readonly audioEventEmitter = new AudioEventEmitter(
+  private readonly audioEventEmitter = new AudioEventEmitter(
     global.AudioEventEmitter
   );
 
-  constructor() {
-    this.recorder = global.createAudioRecorder();
-  }
-
-  enableFileOutput(options: AudioRecorderFileOptions): void {
-    if (this.recorder.isRecording()) {
-      throw new Error(
-        'Cannot enable file output while recording is in progress. Please stop the recorder before changing output options.'
-      );
-    }
-
-    this.options_ = options;
-
-    const parsedOptions = parseFileOptions(options);
-    this.recorder.enableFileOutput(parsedOptions);
-    this.isFileOutputEnabled = true;
+  constructor(options: AudioRecorderOptions) {
+    this.recorder = global.createAudioRecorder(options);
   }
 
-  public get options(): AudioRecorderFileOptions | null {
-    return this.options_;
+  public start(): void {
+    this.recorder.start();
   }
 
-  disableFileOutput(): void {
-    this.options_ = null;
-    this.recorder.disableFileOutput();
-    this.isFileOutputEnabled = false;
+  public stop(): void {
+    this.recorder.stop();
   }
 
-  /** Starts the audio recording process with configured output options */
-  start(): string | void {
-    if (!this.isFileOutputEnabled) {
-      this.recorder.start();
-      return;
-    }
-
-    return this.recorder.start();
-  }
-
-  /** Stops the audio recording process and releases internal resources */
-  stop(): FileInfo {
-    return this.recorder.stop();
-  }
-
-  /** Pauses the audio recording process without tearing down anything */
-  pause(): void {
-    this.recorder.pause();
-  }
-
-  /** Resumes the audio recording process after being paused */
-  resume(): void {
-    this.recorder.resume();
-  }
-
-  /**
-   * Connects a {@link RecorderAdapterNode} to the recorder’s audio graph.
-   *
-   * Each node can only be connected once. Attempting to connect a node multiple
-   * times will throw an error.
-   *
-   * @param node - The adapter node to connect to the recorder.
-   * @throws If the node has already been connected.
-   */
-  connect(node: RecorderAdapterNode): void {
-    if (this.recorder.isRecording()) {
-      throw new Error(
-        'Cannot connect adapter node while recording is in progress. Please stop the recorder before connecting new nodes.'
-      );
-    }
-
+  public connect(node: RecorderAdapterNode): void {
     if (node.wasConnected) {
       throw new Error(
         'RecorderAdapterNode cannot be connected more than once. Refer to the documentation for more details.'
@@ -147,98 +34,24 @@ export default class AudioRecorder {
     this.recorder.connect(node.getNode());
   }
 
-  /**
-   * Disconnects the recorder from all connected adapter nodes.
-   *
-   * After calling this method, any connected {@link RecorderAdapterNode} will no
-   * longer receive audio data until reconnected.
-   */
-  disconnect(): void {
+  public disconnect(): void {
     this.recorder.disconnect();
   }
 
-  /**
-   * Registers a callback to receive raw audio data during an active recording
-   * session.
-   *
-   * The callback is periodically invoked with audio buffers that match the
-   * preferred configuration provided in `options`. These parameters (sample
-   * rate, buffer length, and channel count) guide how audio data is chunked and
-   * delivered, though the exact values may vary depending on device
-   * capabilities. Values may vary depending on device capabilities.
-   *
-   * @param options - Preferred configuration for the audio buffers delivered to
-   *   the callback.
-   * @param callback - Function invoked each time a new audio buffer is
-   *   available. The callback receives an {@link OnAudioReadyEventType} object
-   *   containing the audio data and associated metadata.
-   */
-  onAudioReady(
-    options: AudioRecorderCallbackOptions,
-    callback: (event: OnAudioReadyEventType) => void
-  ): void {
-    if (this.recorder.isRecording()) {
-      throw new Error(
-        'Cannot set onAudioReady callback while recording is in progress. Please stop the recorder before setting a new callback.'
-      );
-    }
-
-    if (this.onAudioReadySubscription) {
-      this.recorder.clearOnAudioReady();
-      this.onAudioReadySubscription.remove();
-      this.onAudioReadySubscription = null;
-    }
-
-    this.onAudioReadySubscription =
-      this.audioEventEmitter.addAudioEventListener('audioReady', (event) => {
-        const audioBuffer = new AudioBuffer(event.buffer);
-        callback({
-          ...event,
-          buffer: audioBuffer,
-        });
+  public onAudioReady(callback: (event: OnAudioReadyEventType) => void): void {
+    const onAudioReadyCallback = (event: OnAudioReadyEventType) => {
+      callback({
+        buffer: new AudioBuffer(event.buffer),
+        numFrames: event.numFrames,
+        when: event.when,
       });
+    };
 
-    this.recorder.setOnAudioReady({
-      sampleRate: options.sampleRate,
-      bufferLength: options.bufferLength,
-      channelCount: options.channelCount,
-      callbackId: this.onAudioReadySubscription.subscriptionId,
-    });
-  }
-
-  /**
-   * Removes the previously registered audio data callback, if any.
-   *
-   * This stops further `onAudioReady` events from being delivered during
-   * recording. Calling this method is safe even if no callback is currently
-   * registered.
-   */
-  clearOnAudioReady(): void {
-    if (this.recorder.isRecording()) {
-      throw new Error(
-        'Cannot clear onAudioReady callback while recording is in progress. Please stop the recorder before clearing the callback.'
-      );
-    }
-
-    if (!this.onAudioReadySubscription) {
-      return;
-    }
-
-    this.recorder.clearOnAudioReady();
-
-    this.onAudioReadySubscription.remove();
-    this.onAudioReadySubscription = null;
-  }
-
-  isRecording(): boolean {
-    return this.recorder.isRecording();
-  }
-
-  isPaused(): boolean {
-    return this.recorder.isPaused();
-  }
+    const subscription = this.audioEventEmitter.addAudioEventListener(
+      'audioReady',
+      onAudioReadyCallback
+    );
 
-  getCurrentDuration(): number {
-    return this.recorder.getCurrentDuration();
+    this.recorder.onAudioReady = subscription.subscriptionId;
   }
 }

package/src/core/BaseAudioContext.ts

@@ -5,13 +5,15 @@ import {
   ContextState,
   PeriodicWaveConstraints,
   AudioWorkletRuntime,
+  ConvolverNodeOptions,
 } from '../types';
-import { isWorkletsAvailable, workletsModule } from '../utils';
+import { assertWorkletsEnabled, workletsModule } from '../utils';
 import WorkletSourceNode from './WorkletSourceNode';
 import WorkletProcessingNode from './WorkletProcessingNode';
 import AnalyserNode from './AnalyserNode';
 import AudioBuffer from './AudioBuffer';
 import AudioBufferQueueSourceNode from './AudioBufferQueueSourceNode';
+import ConvolverNode from './ConvolverNode';
 import AudioBufferSourceNode from './AudioBufferSourceNode';
 import AudioDestinationNode from './AudioDestinationNode';
 import BiquadFilterNode from './BiquadFilterNode';
@@ -84,30 +86,24 @@ export default class BaseAudioContext {
         `The buffer length provided (${bufferLength}) can not be less than 1`
       );
     }
-
-    if (isWorkletsAvailable) {
-      const shareableWorklet = workletsModule.makeShareableCloneRecursive(
-        (audioBuffers: Array<ArrayBuffer>, channelCount: number) => {
-          'worklet';
-          const floatAudioData: Array<Float32Array> = audioBuffers.map(
-            (buffer) => new Float32Array(buffer)
-          );
-          callback(floatAudioData, channelCount);
-        }
-      );
-      return new WorkletNode(
-        this,
-        this.context.createWorkletNode(
-          shareableWorklet,
-          workletRuntime === 'UIRuntime',
-          bufferLength,
-          inputChannelCount
-        )
-      );
-    }
-    /// User does not have worklets as a dependency so he cannot use the worklet API.
-    throw new Error(
-      '[RnAudioApi] Worklets are not available, please install react-native-worklets as a dependency. Refer to documentation for more details.'
+    assertWorkletsEnabled();
+    const shareableWorklet = workletsModule.makeShareableCloneRecursive(
+      (audioBuffers: Array<ArrayBuffer>, channelCount: number) => {
+        'worklet';
+        const floatAudioData: Array<Float32Array> = audioBuffers.map(
+          (buffer) => new Float32Array(buffer)
+        );
+        callback(floatAudioData, channelCount);
+      }
+    );
+    return new WorkletNode(
+      this,
+      this.context.createWorkletNode(
+        shareableWorklet,
+        workletRuntime === 'UIRuntime',
+        bufferLength,
+        inputChannelCount
+      )
     );
   }
 
@@ -120,35 +116,30 @@ export default class BaseAudioContext {
     ) => void,
     workletRuntime: AudioWorkletRuntime = 'AudioRuntime'
   ): WorkletProcessingNode {
-    if (isWorkletsAvailable) {
-      const shareableWorklet = workletsModule.makeShareableCloneRecursive(
-        (
-          inputBuffers: Array<ArrayBuffer>,
-          outputBuffers: Array<ArrayBuffer>,
-          framesToProcess: number,
-          currentTime: number
-        ) => {
-          'worklet';
-          const inputData: Array<Float32Array> = inputBuffers.map(
-            (buffer) => new Float32Array(buffer, 0, framesToProcess)
-          );
-          const outputData: Array<Float32Array> = outputBuffers.map(
-            (buffer) => new Float32Array(buffer, 0, framesToProcess)
-          );
-          callback(inputData, outputData, framesToProcess, currentTime);
-        }
-      );
-      return new WorkletProcessingNode(
-        this,
-        this.context.createWorkletProcessingNode(
-          shareableWorklet,
-          workletRuntime === 'UIRuntime'
-        )
-      );
-    }
-    /// User does not have worklets as a dependency so he cannot use the worklet API.
-    throw new Error(
-      '[RnAudioApi] Worklets are not available, please install react-native-worklets as a dependency. Refer to documentation for more details.'
+    assertWorkletsEnabled();
+    const shareableWorklet = workletsModule.makeShareableCloneRecursive(
+      (
+        inputBuffers: Array<ArrayBuffer>,
+        outputBuffers: Array<ArrayBuffer>,
+        framesToProcess: number,
+        currentTime: number
+      ) => {
+        'worklet';
+        const inputData: Array<Float32Array> = inputBuffers.map(
+          (buffer) => new Float32Array(buffer, 0, framesToProcess)
+        );
+        const outputData: Array<Float32Array> = outputBuffers.map(
+          (buffer) => new Float32Array(buffer, 0, framesToProcess)
+        );
+        callback(inputData, outputData, framesToProcess, currentTime);
+      }
+    );
+    return new WorkletProcessingNode(
+      this,
+      this.context.createWorkletProcessingNode(
+        shareableWorklet,
+        workletRuntime === 'UIRuntime'
+      )
     );
   }
 
@@ -161,12 +152,7 @@ export default class BaseAudioContext {
     ) => void,
     workletRuntime: AudioWorkletRuntime = 'AudioRuntime'
   ): WorkletSourceNode {
-    if (!isWorkletsAvailable) {
-      /// User does not have worklets as a dependency so he cannot use the worklet API.
-      throw new Error(
-        '[RnAudioApi] Worklets are not available, please install react-native-worklets as a dependency. Refer to documentation for more details.'
-      );
-    }
+    assertWorkletsEnabled();
     const shareableWorklet = workletsModule.makeShareableCloneRecursive(
       (
         audioBuffers: Array<ArrayBuffer>,
@@ -289,4 +275,25 @@ export default class BaseAudioContext {
   createAnalyser(): AnalyserNode {
     return new AnalyserNode(this, this.context.createAnalyser());
   }
+
+  createConvolver(options?: ConvolverNodeOptions): ConvolverNode {
+    if (options?.buffer) {
+      const numberOfChannels = options.buffer.numberOfChannels;
+      if (
+        numberOfChannels !== 1 &&
+        numberOfChannels !== 2 &&
+        numberOfChannels !== 4
+      ) {
+        throw new NotSupportedError(
+          `The number of channels provided (${numberOfChannels}) in impulse response for ConvolverNode buffer must be 1 or 2 or 4.`
+        );
+      }
+    }
+    const buffer = options?.buffer ?? null;
+    const disableNormalization = options?.disableNormalization ?? false;
+    return new ConvolverNode(
+      this,
+      this.context.createConvolver(buffer?.buffer, disableNormalization)
+    );
+  }
 }

package/src/core/ConvolverNode.ts

@@ -0,0 +1,35 @@
+import { IConvolverNode } from '../interfaces';
+import BaseAudioContext from './BaseAudioContext';
+import AudioNode from './AudioNode';
+import AudioBuffer from './AudioBuffer';
+
+export default class ConvolverNode extends AudioNode {
+  constructor(context: BaseAudioContext, node: IConvolverNode) {
+    super(context, node);
+    this.normalize = node.normalize;
+  }
+
+  public get buffer(): AudioBuffer | null {
+    const buffer = (this.node as IConvolverNode).buffer;
+    if (!buffer) {
+      return null;
+    }
+    return new AudioBuffer(buffer);
+  }
+
+  public set buffer(buffer: AudioBuffer | null) {
+    if (!buffer) {
+      (this.node as IConvolverNode).buffer = null;
+      return;
+    }
+    (this.node as IConvolverNode).buffer = buffer.buffer;
+  }
+
+  public get normalize(): boolean {
+    return (this.node as IConvolverNode).normalize;
+  }
+
+  public set normalize(value: boolean) {
+    (this.node as IConvolverNode).normalize = value;
+  }
+}

package/src/core/OfflineAudioContext.ts

@@ -3,7 +3,7 @@ import BaseAudioContext from './BaseAudioContext';
 import { OfflineAudioContextOptions } from '../types';
 import { InvalidStateError, NotSupportedError } from '../errors';
 import AudioBuffer from './AudioBuffer';
-import { isWorkletsAvailable, workletsModule } from '../utils';
+import { isWorkletsVersionSupported, workletsModule } from '../utils';
 
 export default class OfflineAudioContext extends BaseAudioContext {
   private isSuspended: boolean;
@@ -18,7 +18,7 @@ export default class OfflineAudioContext extends BaseAudioContext {
     arg2?: number
   ) {
     let audioRuntime = null;
-    if (isWorkletsAvailable) {
+    if (isWorkletsVersionSupported) {
       audioRuntime = workletsModule.createWorkletRuntime('AudioWorkletRuntime');
     }
 

package/src/events/types.ts

@@ -49,27 +49,9 @@ export interface OnEndedEventType extends EventEmptyType {
   isLast: boolean | undefined;
 }
 
-/**
- * Represents the data payload received by the audio recorder callback each time
- * a new audio buffer becomes available during recording.
- */
 export interface OnAudioReadyEventType {
-  /**
-   * The audio buffer containing the recorded PCM data. This buffer includes one
-   * or more channels of floating-point samples in the range of -1.0 to 1.0.
-   */
   buffer: AudioBuffer;
-
-  /**
-   * The number of audio frames contained in this buffer. A frame represents a
-   * single sample across all channels.
-   */
   numFrames: number;
-
-  /**
-   * The timestamp (in seconds) indicating when this buffer was captured,
-   * relative to the start of the recording session.
-   */
   when: number;
 }