react-native-audio-api 0.10.0-nightly-c815c40-20251026 → 0.11.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-audio-api",
-  "version": "0.10.0-nightly-c815c40-20251026",
+  "version": "0.11.0-alpha.0",
   "description": "react-native-audio-api provides system for controlling audio in React Native environment compatible with Web Audio API specification",
   "bin": {
     "setup-rn-audio-api-web": "./scripts/setup-rn-audio-api-web.js"
@@ -35,9 +35,6 @@
     "!**/.*",
     "!**/node_modules",
     "scripts/setup-rn-audio-api-web.js",
-    "scripts/rnaa_utils.rb",
-    "scripts/validate-worklets-version.js",
-    "scripts/download-prebuilt-binaries.sh",
     "app.plugin.js"
   ],
   "scripts": {
@@ -91,7 +88,7 @@
     "@babel/core": "^7.25.2",
     "@babel/preset-env": "^7.25.3",
     "@babel/types": "^7.20.0",
-    "@commitlint/config-conventional": "^17.0.2",
+    "@commitlint/config-conventional": "17.0.2",
     "@evilmartians/lefthook": "^1.5.0",
     "@expo/config-plugins": "^9.0.0",
     "@expo/config-types": "^53.0.4",
@@ -108,7 +105,7 @@
     "@types/react": "^19.1.1",
     "@types/react-test-renderer": "^19.1.0",
     "babel-plugin-module-resolver": "^4.1.0",
-    "commitlint": "^17.0.2",
+    "commitlint": "17.0.2",
     "del-cli": "^5.1.0",
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^8.3.0",
@@ -130,7 +127,7 @@
     "react-native": "0.82.0",
     "react-native-builder-bob": "0.33.1",
     "turbo": "^1.10.7",
-    "typescript": "5.8.3"
+    "typescript": "~5.8.3"
   },
   "react-native-builder-bob": {
     "source": "src",

package/src/api.ts

@@ -1,13 +1,12 @@
-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 {
@@ -25,7 +24,7 @@ declare global {
     audioWorkletRuntime: any
   ) => IOfflineAudioContext;
 
-  var createAudioRecorder: (options: AudioRecorderOptions) => IAudioRecorder;
+  var createAudioRecorder: () => IAudioRecorder;
 
   var createAudioDecoder: () => IAudioDecoder;
 
@@ -52,58 +51,33 @@ if (
   NativeAudioAPIModule.install();
 }
 
-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 AnalyserNode } from './core/AnalyserNode';
 export { default as AudioBuffer } from './core/AudioBuffer';
-export { default as AudioBufferSourceNode } from './core/AudioBufferSourceNode';
 export { default as AudioBufferQueueSourceNode } from './core/AudioBufferQueueSourceNode';
+export { default as AudioBufferSourceNode } from './core/AudioBufferSourceNode';
 export { default as AudioContext } from './core/AudioContext';
-export { default as OfflineAudioContext } from './core/OfflineAudioContext';
+export { decodeAudioData, decodePCMInBase64 } from './core/AudioDecoder';
 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 ConstantSourceNode } from './core/ConstantSourceNode';
-export { default as AudioManager } from './system';
+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 { 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 { default as AudioManager } from './system';
 
-export {
-  IndexSizeError,
-  InvalidAccessError,
-  InvalidStateError,
-  RangeError,
-  NotSupportedError,
-} from './errors';
+export * from './errors';
+export * from './system/types';
+export * from './types';

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 { isWorkletsVersionSupported, workletsModule } from '../utils';
+import { isWorkletsAvailable, workletsModule } from '../utils';
 
 export default class AudioContext extends BaseAudioContext {
   constructor(options?: AudioContextOptions) {
@@ -17,8 +17,7 @@ export default class AudioContext extends BaseAudioContext {
       );
     }
     let audioRuntime = null;
-
-    if (isWorkletsVersionSupported) {
+    if (isWorkletsAvailable) {
       audioRuntime = workletsModule.createWorkletRuntime('AudioWorkletRuntime');
     }
 

package/src/core/AudioRecorder.ts

@@ -1,30 +1,134 @@
+import { AudioEventEmitter, AudioEventSubscription } from '../events';
+import { OnAudioReadyEventType } from '../events/types';
 import { IAudioRecorder } from '../interfaces';
-import { AudioRecorderOptions } from '../types';
+import {
+  AndroidFormat,
+  AudioRecorderCallbackOptions,
+  AudioRecorderFileOptions,
+  BitDepth,
+  FileDirectory,
+  IOSAudioQuality,
+  IOSFormat,
+} from '../types';
+import { encodeFlags } from '../utils';
 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 readonly audioEventEmitter = new AudioEventEmitter(
+  protected readonly audioEventEmitter = new AudioEventEmitter(
     global.AudioEventEmitter
   );
 
-  constructor(options: AudioRecorderOptions) {
-    this.recorder = global.createAudioRecorder(options);
+  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);
+  }
+
+  public get options(): AudioRecorderFileOptions | null {
+    return this.options_;
+  }
+
+  disableFileOutput(): void {
+    this.options_ = null;
+    this.recorder.disableFileOutput();
+  }
+
+  /** Starts the audio recording process with configured output options */
   public start(): void {
     this.recorder.start();
   }
 
-  public stop(): void {
-    this.recorder.stop();
+  /** Stops the audio recording process and releases internal resources */
+  public stop(): void | string {
+    return this.recorder.stop();
+  }
+
+  /** Pauses the audio recording process without tearing down anything */
+  public pause(): void {
+    this.recorder.pause();
   }
 
+  /** Resumes the audio recording process after being paused */
+  public 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.
+   */
   public 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.'
+      );
+    }
+
     if (node.wasConnected) {
       throw new Error(
         'RecorderAdapterNode cannot be connected more than once. Refer to the documentation for more details.'
@@ -34,24 +138,90 @@ 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.
+   */
   public disconnect(): void {
     this.recorder.disconnect();
   }
 
-  public onAudioReady(callback: (event: OnAudioReadyEventType) => void): void {
-    const onAudioReadyCallback = (event: OnAudioReadyEventType) => {
-      callback({
-        buffer: new AudioBuffer(event.buffer),
-        numFrames: event.numFrames,
-        when: event.when,
+  /**
+   * 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.
+   */
+  public 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,
+        });
       });
-    };
 
-    const subscription = this.audioEventEmitter.addAudioEventListener(
-      'audioReady',
-      onAudioReadyCallback
-    );
+    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.
+   */
+  public 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;
+  }
 
-    this.recorder.onAudioReady = subscription.subscriptionId;
+  public isRecording(): boolean {
+    return this.recorder.isRecording();
   }
 }

package/src/core/BaseAudioContext.ts

@@ -6,7 +6,7 @@ import {
   PeriodicWaveConstraints,
   AudioWorkletRuntime,
 } from '../types';
-import { assertWorkletsEnabled, workletsModule } from '../utils';
+import { isWorkletsAvailable, workletsModule } from '../utils';
 import WorkletSourceNode from './WorkletSourceNode';
 import WorkletProcessingNode from './WorkletProcessingNode';
 import AnalyserNode from './AnalyserNode';
@@ -84,24 +84,30 @@ export default class BaseAudioContext {
         `The buffer length provided (${bufferLength}) can not be less than 1`
       );
     }
-    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
-      )
+
+    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.'
     );
   }
 
@@ -114,30 +120,35 @@ export default class BaseAudioContext {
     ) => void,
     workletRuntime: AudioWorkletRuntime = 'AudioRuntime'
   ): WorkletProcessingNode {
-    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'
-      )
+    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.'
     );
   }
 
@@ -150,7 +161,12 @@ export default class BaseAudioContext {
     ) => void,
     workletRuntime: AudioWorkletRuntime = 'AudioRuntime'
   ): WorkletSourceNode {
-    assertWorkletsEnabled();
+    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.'
+      );
+    }
     const shareableWorklet = workletsModule.makeShareableCloneRecursive(
       (
         audioBuffers: Array<ArrayBuffer>,

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 { isWorkletsVersionSupported, workletsModule } from '../utils';
+import { isWorkletsAvailable, 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 (isWorkletsVersionSupported) {
+    if (isWorkletsAvailable) {
       audioRuntime = workletsModule.createWorkletRuntime('AudioWorkletRuntime');
     }
 

package/src/events/types.ts

@@ -49,9 +49,27 @@ 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;
 }
 

package/src/interfaces.ts

@@ -1,5 +1,5 @@
 import { AudioEventCallback, AudioEventName } from './events/types';
-import {
+import type {
   BiquadFilterType,
   ChannelCountMode,
   ChannelInterpretation,
@@ -250,14 +250,57 @@ export interface IWorkletSourceNode extends IAudioScheduledSourceNode {}
 
 export interface IWorkletProcessingNode extends IAudioNode {}
 
+type IOSAudioRecorderFileDescriptor = number;
+type AndroidAudioRecorderFileDescriptor = number;
+
+interface IAudioRecorderFileOptions {
+  sampleRate: number;
+  channels: number;
+  bitRate: number;
+  /**
+   * IOS specific file recording options
+   *
+   * - `format` - IOSFormat, bitmask 0 x 0000000F
+   * - `quality` - IOSAudioQuality, bitmask 0 x 000000F0
+   * - `flacCompressionLevel` - FlacCompressionLevel, bitmask 0 x 00000F00
+   * - `directory` - FileDirectory, bitmask 0 x 0000F000
+   * - `bitDepth` - BitDepth, bitmask 0 x 000F0000
+   */
+  ios: IOSAudioRecorderFileDescriptor;
+  /**
+   * Android specific file recording options
+   *
+   * - He he
+   */
+  android: AndroidAudioRecorderFileDescriptor;
+}
+
+interface IAudioRecorderCallbackOptions {
+  sampleRate: number;
+  bufferLength: number;
+  channelCount: number;
+  callbackId: string;
+}
+
 export interface IAudioRecorder {
+  // default recorder methods
   start: () => void;
-  stop: () => void;
+  stop: () => string | void;
+  isRecording: () => boolean;
+
+  enableFileOutput: (options: IAudioRecorderFileOptions) => void;
+  disableFileOutput: () => void;
+
+  // pause and resume methods for file recording
+  pause: () => void;
+  resume: () => void;
+
+  // Graph integration methods
   connect: (node: IRecorderAdapterNode) => void;
   disconnect: () => void;
 
-  // passing subscriptionId(uint_64 in cpp, string in js) to the cpp
-  onAudioReady: string;
+  setOnAudioReady: (options: IAudioRecorderCallbackOptions) => void;
+  clearOnAudioReady: () => void;
 }
 
 export interface IAudioDecoder {