react-native-audio-api 0.11.0-alpha.1 → 0.11.0-alpha.10

package/src/AudioAPIModule/AudioAPIModule.ts

@@ -0,0 +1,122 @@
+import type { ShareableWorkletCallback } from '../interfaces';
+import { NativeAudioAPIModule } from '../specs';
+
+// Hint: Copied from react-native-worklets
+// Doesn't really matter what is inside, just need a unique type
+interface WorkletRuntime {
+  __hostObjectWorkletRuntime: never;
+  readonly name: string;
+}
+
+interface IWorkletsModule {
+  makeShareableCloneRecursive: (
+    workletCallback: ShareableWorkletCallback
+  ) => ShareableWorkletCallback;
+
+  createWorkletRuntime: (runtimeName: string) => WorkletRuntime;
+}
+
+class AudioAPIModule {
+  #workletsModule_: IWorkletsModule | null = null;
+  #canUseWorklets_ = false;
+  #workletsVersion = 'unknown';
+  #workletsAvailable_ = false;
+
+  public supportedWorkletsVersion = ['0.6.0', '0.6.1'];
+
+  constructor() {
+    // Important! Verify and import worklets first
+    // otherwise the native module installation might crash
+    // if react-native-worklets is not imported before audio-api
+    this.#verifyWorklets();
+
+    if (this.#verifyInstallation()) {
+      return;
+    }
+
+    if (!NativeAudioAPIModule) {
+      throw new Error(
+        `Failed to install react-native-audio-api: The native module could not be found.`
+      );
+    }
+
+    NativeAudioAPIModule.install();
+  }
+
+  #verifyWorklets(): boolean {
+    try {
+      const workletsPackage = require('react-native-worklets');
+      const workletsPackageJson = require('react-native-worklets/package.json');
+      this.#workletsVersion = workletsPackageJson.version;
+      this.#workletsAvailable_ = true;
+
+      this.#canUseWorklets_ = this.supportedWorkletsVersion.includes(
+        workletsPackageJson.version
+      );
+
+      if (this.#canUseWorklets_) {
+        this.#workletsModule_ = workletsPackage;
+      }
+
+      return this.#canUseWorklets_;
+    } catch {
+      this.#canUseWorklets_ = false;
+      return false;
+    }
+  }
+
+  #verifyInstallation(): boolean {
+    return (
+      global.createAudioContext != null &&
+      global.createOfflineAudioContext != null &&
+      global.createAudioRecorder != null &&
+      global.createAudioDecoder != null &&
+      global.createAudioStretcher != null &&
+      global.AudioEventEmitter != null
+    );
+  }
+
+  get workletsModule(): IWorkletsModule | null {
+    return this.#workletsModule_;
+  }
+
+  /**
+   * Indicates whether react-native-worklets are installed in matching version,
+   * for usage with react-native-audio-api.
+   */
+  get canUseWorklets(): boolean {
+    return this.#canUseWorklets_;
+  }
+
+  /** Returns the installed worklets version or 'unknown'. */
+  get workletsVersion(): string {
+    return this.#workletsVersion;
+  }
+
+  /**
+   * Indicates whether react-native-worklets are installed, regardless of
+   * version support. Useful for asserting compatibility.
+   */
+  get areWorkletsAvailable(): boolean {
+    return this.#workletsAvailable_;
+  }
+
+  /**
+   * Indicates whether the installed react-native-worklets version is supported.
+   * Useful for asserting compatibility.
+   */
+  get isWorkletsVersionSupported(): boolean {
+    // Note: if areWorkletsAvailable is true, canUseWorklets is equivalent to version check
+    return this.#canUseWorklets_;
+  }
+
+  public createAudioRuntime(): WorkletRuntime | null {
+    if (!this.#canUseWorklets_) {
+      return null;
+    }
+
+    return this.#workletsModule_!.createWorkletRuntime('AudioWorkletRuntime');
+  }
+}
+
+export default new AudioAPIModule();

package/src/AudioAPIModule/globals.d.ts

@@ -0,0 +1,33 @@
+import type {
+  IAudioContext,
+  IAudioDecoder,
+  IAudioEventEmitter,
+  IAudioRecorder,
+  IAudioStretcher,
+  IOfflineAudioContext,
+} from '../interfaces';
+
+/* eslint-disable no-var */
+declare global {
+  var createAudioContext: (
+    sampleRate: number,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    audioWorkletRuntime: any
+  ) => IAudioContext;
+  var createOfflineAudioContext: (
+    numberOfChannels: number,
+    length: number,
+    sampleRate: number,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    audioWorkletRuntime: any
+  ) => IOfflineAudioContext;
+
+  var createAudioRecorder: () => IAudioRecorder;
+
+  var createAudioDecoder: () => IAudioDecoder;
+
+  var createAudioStretcher: () => IAudioStretcher;
+
+  var AudioEventEmitter: IAudioEventEmitter;
+}
+/* eslint-disable no-var */

package/src/AudioAPIModule/index.ts

@@ -0,0 +1 @@
+export { default } from './AudioAPIModule';

package/src/api.ts

@@ -1,55 +1,4 @@
-import type {
-  IAudioContext,
-  IAudioDecoder,
-  IAudioEventEmitter,
-  IAudioRecorder,
-  IAudioStretcher,
-  IOfflineAudioContext,
-} from './interfaces';
-import { NativeAudioAPIModule } from './specs';
-
-/* eslint-disable no-var */
-declare global {
-  var createAudioContext: (
-    sampleRate: number,
-    initSuspended: boolean,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    audioWorkletRuntime: any
-  ) => IAudioContext;
-  var createOfflineAudioContext: (
-    numberOfChannels: number,
-    length: number,
-    sampleRate: number,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    audioWorkletRuntime: any
-  ) => IOfflineAudioContext;
-
-  var createAudioRecorder: () => IAudioRecorder;
-
-  var createAudioDecoder: () => IAudioDecoder;
-
-  var createAudioStretcher: () => IAudioStretcher;
-
-  var AudioEventEmitter: IAudioEventEmitter;
-}
-/* eslint-disable no-var */
-
-if (
-  global.createAudioContext == null ||
-  global.createOfflineAudioContext == null ||
-  global.createAudioRecorder == null ||
-  global.createAudioDecoder == null ||
-  global.createAudioStretcher == null ||
-  global.AudioEventEmitter == null
-) {
-  if (!NativeAudioAPIModule) {
-    throw new Error(
-      `Failed to install react-native-audio-api: The native module could not be found.`
-    );
-  }
-
-  NativeAudioAPIModule.install();
-}
+import './AudioAPIModule';
 
 export { default as AnalyserNode } from './core/AnalyserNode';
 export { default as AudioBuffer } from './core/AudioBuffer';
@@ -66,6 +15,7 @@ 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 ConvolverNode } from './core/ConvolverNode';
 export { default as GainNode } from './core/GainNode';
 export { default as OfflineAudioContext } from './core/OfflineAudioContext';
 export { default as OscillatorNode } from './core/OscillatorNode';
@@ -75,9 +25,28 @@ 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 AudioManager } from './system';
 
 export * from './errors';
 export * from './system/types';
 export * from './types';
+export { default as FilePreset } from './utils/filePresets';
+
+// Notification System
+export {
+  PlaybackNotificationManager,
+  RecordingNotificationManager,
+} from './system/notification';
+
+export {
+  NotificationManager,
+  PlaybackControlName,
+  PlaybackNotificationEventName,
+  PlaybackNotificationInfo,
+  RecordingControlName,
+  RecordingNotificationEventName,
+  RecordingNotificationInfo,
+  SimpleNotificationOptions,
+} from './system/notification';

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';
 
@@ -31,11 +32,16 @@ export {
   IOSMode,
   IOSOption,
   SessionOptions,
-  MediaState,
-  LockScreenInfo,
   PermissionStatus,
 } from './system/types';
 
+export {
+  PlaybackNotificationManager,
+  RecordingNotificationManager,
+} from './web-system';
+
+export * from './system/notification/types';
+
 export {
   IndexSizeError,
   InvalidAccessError,

package/src/core/AudioBufferBaseSourceNode.ts

@@ -51,4 +51,12 @@ export default class AudioBufferBaseSourceNode extends AudioScheduledSourceNode
   public set onPositionChangedInterval(value: number) {
     (this.node as IAudioBufferBaseSourceNode).onPositionChangedInterval = value;
   }
+
+  public getLatency(): number {
+    return (
+      (this.node as IAudioBufferBaseSourceNode).getOutputLatency() +
+      (this.node as IAudioBufferBaseSourceNode).getInputLatency() *
+        (this.node as IAudioBufferBaseSourceNode).playbackRate.value
+    );
+  }
 }

package/src/core/AudioBufferQueueSourceNode.ts

@@ -24,14 +24,20 @@ export default class AudioBufferQueueSourceNode extends AudioBufferBaseSourceNod
     (this.node as IAudioBufferQueueSourceNode).clearBuffers();
   }
 
-  public override start(when: number = 0): void {
+  public override start(when: number = 0, offset?: number): void {
     if (when < 0) {
       throw new RangeError(
         `when must be a finite non-negative number: ${when}`
       );
     }
 
-    (this.node as IAudioBufferQueueSourceNode).start(when);
+    if (offset && offset < 0) {
+      throw new RangeError(
+        `offset must be a finite non-negative number: ${offset}`
+      );
+    }
+
+    (this.node as IAudioBufferQueueSourceNode).start(when, offset);
   }
 
   public override stop(when: number = 0): void {

package/src/core/AudioContext.ts

@@ -1,9 +1,9 @@
+import AudioAPIModule from '../AudioAPIModule';
+import { NotSupportedError } from '../errors';
 import { IAudioContext } from '../interfaces';
-import BaseAudioContext from './BaseAudioContext';
 import AudioManager from '../system';
 import { AudioContextOptions } from '../types';
-import { NotSupportedError } from '../errors';
-import { isWorkletsAvailable, workletsModule } from '../utils';
+import BaseAudioContext from './BaseAudioContext';
 
 export default class AudioContext extends BaseAudioContext {
   constructor(options?: AudioContextOptions) {
@@ -16,15 +16,12 @@ export default class AudioContext extends BaseAudioContext {
         `The provided sampleRate is not supported: ${options.sampleRate}`
       );
     }
-    let audioRuntime = null;
-    if (isWorkletsAvailable) {
-      audioRuntime = workletsModule.createWorkletRuntime('AudioWorkletRuntime');
-    }
+
+    const audioRuntime = AudioAPIModule.createAudioRuntime();
 
     super(
       global.createAudioContext(
         options?.sampleRate || AudioManager.getDevicePreferredSampleRate(),
-        options?.initSuspended || false,
         audioRuntime
       )
     );

package/src/core/AudioNode.ts

@@ -23,7 +23,9 @@ export default class AudioNode {
     this.channelInterpretation = this.node.channelInterpretation;
   }
 
-  public connect(destination: AudioNode | AudioParam): AudioNode | AudioParam {
+  public connect(destination: AudioNode): AudioNode;
+  public connect(destination: AudioParam): void;
+  public connect(destination: AudioNode | AudioParam): AudioNode | void {
     if (this.context !== destination.context) {
       throw new InvalidAccessError(
         'Source and destination are from different BaseAudioContexts'
@@ -34,9 +36,8 @@ export default class AudioNode {
       this.node.connect(destination.audioParam);
     } else {
       this.node.connect(destination.node);
+      return destination;
     }
-
-    return destination;
   }
 
   public disconnect(destination?: AudioNode | AudioParam): void {

package/src/core/AudioParam.ts

@@ -33,7 +33,8 @@ export default class AudioParam {
       );
     }
 
-    this.audioParam.setValueAtTime(value, startTime);
+    const clampedTime = Math.max(startTime, this.context.currentTime);
+    this.audioParam.setValueAtTime(value, clampedTime);
 
     return this;
   }
@@ -45,7 +46,8 @@ export default class AudioParam {
       );
     }
 
-    this.audioParam.linearRampToValueAtTime(value, endTime);
+    const clampedTime = Math.max(endTime, this.context.currentTime);
+    this.audioParam.linearRampToValueAtTime(value, clampedTime);
 
     return this;
   }
@@ -54,13 +56,14 @@ export default class AudioParam {
     value: number,
     endTime: number
   ): AudioParam {
-    if (endTime < 0) {
+    if (endTime <= 0) {
       throw new RangeError(
         `endTime must be a finite non-negative number: ${endTime}`
       );
     }
 
-    this.audioParam.exponentialRampToValueAtTime(value, endTime);
+    const clampedTime = Math.max(endTime, this.context.currentTime);
+    this.audioParam.exponentialRampToValueAtTime(value, clampedTime);
 
     return this;
   }
@@ -78,11 +81,12 @@ export default class AudioParam {
 
     if (timeConstant < 0) {
       throw new RangeError(
-        `timeConstant must be a finite non-negative number: ${startTime}`
+        `timeConstant must be a finite non-negative number: ${timeConstant}`
       );
     }
 
-    this.audioParam.setTargetAtTime(target, startTime, timeConstant);
+    const clampedTime = Math.max(startTime, this.context.currentTime);
+    this.audioParam.setTargetAtTime(target, clampedTime, timeConstant);
 
     return this;
   }
@@ -98,9 +102,9 @@ export default class AudioParam {
       );
     }
 
-    if (duration < 0) {
+    if (duration <= 0) {
       throw new RangeError(
-        `duration must be a finite non-negative number: ${startTime}`
+        `duration must be a finite strictly-positive number: ${duration}`
       );
     }
 
@@ -108,7 +112,8 @@ export default class AudioParam {
       throw new InvalidStateError(`values must contain at least two values`);
     }
 
-    this.audioParam.setValueCurveAtTime(values, startTime, duration);
+    const clampedTime = Math.max(startTime, this.context.currentTime);
+    this.audioParam.setValueCurveAtTime(values, clampedTime, duration);
 
     return this;
   }
@@ -120,7 +125,8 @@ export default class AudioParam {
       );
     }
 
-    this.audioParam.cancelScheduledValues(cancelTime);
+    const clampedTime = Math.max(cancelTime, this.context.currentTime);
+    this.audioParam.cancelScheduledValues(clampedTime);
 
     return this;
   }
@@ -132,7 +138,8 @@ export default class AudioParam {
       );
     }
 
-    this.audioParam.cancelAndHoldAtTime(cancelTime);
+    const clampedTime = Math.max(cancelTime, this.context.currentTime);
+    this.audioParam.cancelAndHoldAtTime(clampedTime);
 
     return this;
   }

package/src/core/AudioRecorder.ts

@@ -1,66 +1,42 @@
 import { AudioEventEmitter, AudioEventSubscription } from '../events';
-import { OnAudioReadyEventType } from '../events/types';
+import {
+  OnAudioReadyEventType,
+  OnRecorderErrorEventType,
+} from '../events/types';
 import { IAudioRecorder } from '../interfaces';
 import {
-  AndroidFormat,
   AudioRecorderCallbackOptions,
   AudioRecorderFileOptions,
-  BitDepth,
   FileDirectory,
+  FileFormat,
   FileInfo,
-  IOSAudioQuality,
-  IOSFormat,
+  Result,
 } from '../types';
-import { encodeFlags } from '../utils';
+import FilePreset from '../utils/filePresets';
 import AudioBuffer from './AudioBuffer';
 import RecorderAdapterNode from './RecorderAdapterNode';
 
-function withDefaultOptions(inOptions: AudioRecorderFileOptions) {
+// Enforces default options, making sure that all properties are defined
+// for the contract with native code.
+function withDefaultOptions(
+  inOptions: AudioRecorderFileOptions
+): Required<AudioRecorderFileOptions> {
   return {
     directory: FileDirectory.Cache,
-    sampleRate: 48000,
-    channels: 2,
-    bitRate: 128000,
-    bitDepth: BitDepth.Bit24,
+    subDirectory: 'AudioAPI',
+    fileNamePrefix: 'recording_',
+    channelCount: 2,
+    format: FileFormat.M4A,
+    batchDurationSeconds: 0,
+    preset: FilePreset.High,
+    androidFlushIntervalMs: 500,
     ...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 onErrorSubscription: AudioEventSubscription | null = null;
   protected readonly recorder: IAudioRecorder;
   protected options_: AudioRecorderFileOptions | null = null;
   private isFileOutputEnabled: boolean = false;
@@ -73,18 +49,16 @@ export default class AudioRecorder {
     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);
+  enableFileOutput(
+    // TODO: Re-enable 'batchDurationSeconds' once supported
+    options?: Omit<AudioRecorderFileOptions, 'batchDurationSeconds'>
+  ): Result<{ path: string }> {
+    this.options_ = options || {};
+    const parsedOptions = withDefaultOptions(this.options_);
+    const result = this.recorder.enableFileOutput(parsedOptions);
     this.isFileOutputEnabled = true;
+
+    return result;
   }
 
   public get options(): AudioRecorderFileOptions | null {
@@ -98,17 +72,17 @@ export default class AudioRecorder {
   }
 
   /** Starts the audio recording process with configured output options */
-  start(): string | void {
+  start(): Result<{ path: string }> {
     if (!this.isFileOutputEnabled) {
       this.recorder.start();
-      return;
+      return { status: 'success', path: '' };
     }
 
     return this.recorder.start();
   }
 
   /** Stops the audio recording process and releases internal resources */
-  stop(): FileInfo {
+  stop(): Result<FileInfo> {
     return this.recorder.stop();
   }
 
@@ -132,17 +106,12 @@ export default class AudioRecorder {
    * @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.'
-      );
-    }
-
     if (node.wasConnected) {
       throw new Error(
         'RecorderAdapterNode cannot be connected more than once. Refer to the documentation for more details.'
       );
     }
+
     node.wasConnected = true;
     this.recorder.connect(node.getNode());
   }
@@ -176,13 +145,7 @@ export default class AudioRecorder {
   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.'
-      );
-    }
-
+  ): Result<void> {
     if (this.onAudioReadySubscription) {
       this.recorder.clearOnAudioReady();
       this.onAudioReadySubscription.remove();
@@ -198,7 +161,7 @@ export default class AudioRecorder {
         });
       });
 
-    this.recorder.setOnAudioReady({
+    return this.recorder.setOnAudioReady({
       sampleRate: options.sampleRate,
       bufferLength: options.bufferLength,
       channelCount: options.channelCount,
@@ -214,12 +177,6 @@ export default class AudioRecorder {
    * 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;
     }
@@ -241,4 +198,32 @@ export default class AudioRecorder {
   getCurrentDuration(): number {
     return this.recorder.getCurrentDuration();
   }
+
+  onError(callback: (error: OnRecorderErrorEventType) => void): void {
+    if (this.onErrorSubscription) {
+      this.recorder.clearOnError();
+      this.onErrorSubscription.remove();
+      this.onErrorSubscription = null;
+    }
+
+    this.onErrorSubscription = this.audioEventEmitter.addAudioEventListener(
+      'recorderError',
+      callback
+    );
+
+    this.recorder.setOnError({
+      callbackId: this.onErrorSubscription.subscriptionId,
+    });
+  }
+
+  clearOnError(): void {
+    if (!this.onErrorSubscription) {
+      return;
+    }
+
+    this.recorder.clearOnError();
+
+    this.onErrorSubscription.remove();
+    this.onErrorSubscription = null;
+  }
 }