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

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;
+  }
 }

package/src/core/BaseAudioContext.ts

@@ -1,29 +1,39 @@
-import { InvalidAccessError, NotSupportedError } from '../errors';
+import AudioAPIModule from '../AudioAPIModule';
+import {
+  InvalidAccessError,
+  InvalidStateError,
+  NotSupportedError,
+} from '../errors';
 import { IBaseAudioContext } from '../interfaces';
 import {
   AudioBufferBaseSourceNodeOptions,
+  AudioWorkletRuntime,
   ContextState,
+  ConvolverNodeOptions,
+  IIRFilterNodeOptions,
   PeriodicWaveConstraints,
-  AudioWorkletRuntime,
 } from '../types';
-import { isWorkletsAvailable, workletsModule } from '../utils';
-import WorkletSourceNode from './WorkletSourceNode';
-import WorkletProcessingNode from './WorkletProcessingNode';
+import { assertWorkletsEnabled } from '../utils';
 import AnalyserNode from './AnalyserNode';
 import AudioBuffer from './AudioBuffer';
 import AudioBufferQueueSourceNode from './AudioBufferQueueSourceNode';
 import AudioBufferSourceNode from './AudioBufferSourceNode';
+import { decodeAudioData, decodePCMInBase64 } from './AudioDecoder';
 import AudioDestinationNode from './AudioDestinationNode';
 import BiquadFilterNode from './BiquadFilterNode';
 import ConstantSourceNode from './ConstantSourceNode';
+import ConvolverNode from './ConvolverNode';
+import DelayNode from './DelayNode';
 import GainNode from './GainNode';
+import IIRFilterNode from './IIRFilterNode';
 import OscillatorNode from './OscillatorNode';
 import PeriodicWave from './PeriodicWave';
 import RecorderAdapterNode from './RecorderAdapterNode';
 import StereoPannerNode from './StereoPannerNode';
 import StreamerNode from './StreamerNode';
 import WorkletNode from './WorkletNode';
-import { decodeAudioData, decodePCMInBase64 } from './AudioDecoder';
+import WorkletProcessingNode from './WorkletProcessingNode';
+import WorkletSourceNode from './WorkletSourceNode';
 
 export default class BaseAudioContext {
   readonly destination: AudioDestinationNode;
@@ -79,14 +89,17 @@ export default class BaseAudioContext {
         `The number of input channels provided (${inputChannelCount}) can not be less than 1 or greater than 32`
       );
     }
+
     if (bufferLength < 1) {
       throw new NotSupportedError(
         `The buffer length provided (${bufferLength}) can not be less than 1`
       );
     }
 
-    if (isWorkletsAvailable) {
-      const shareableWorklet = workletsModule.makeShareableCloneRecursive(
+    assertWorkletsEnabled();
+
+    const shareableWorklet =
+      AudioAPIModule.workletsModule!.makeShareableCloneRecursive(
         (audioBuffers: Array<ArrayBuffer>, channelCount: number) => {
           'worklet';
           const floatAudioData: Array<Float32Array> = audioBuffers.map(
@@ -95,19 +108,15 @@ export default class BaseAudioContext {
           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.'
+
+    return new WorkletNode(
+      this,
+      this.context.createWorkletNode(
+        shareableWorklet,
+        workletRuntime === 'UIRuntime',
+        bufferLength,
+        inputChannelCount
+      )
     );
   }
 
@@ -120,8 +129,10 @@ export default class BaseAudioContext {
     ) => void,
     workletRuntime: AudioWorkletRuntime = 'AudioRuntime'
   ): WorkletProcessingNode {
-    if (isWorkletsAvailable) {
-      const shareableWorklet = workletsModule.makeShareableCloneRecursive(
+    assertWorkletsEnabled();
+
+    const shareableWorklet =
+      AudioAPIModule.workletsModule!.makeShareableCloneRecursive(
         (
           inputBuffers: Array<ArrayBuffer>,
           outputBuffers: Array<ArrayBuffer>,
@@ -138,17 +149,13 @@ export default class BaseAudioContext {
           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.'
+
+    return new WorkletProcessingNode(
+      this,
+      this.context.createWorkletProcessingNode(
+        shareableWorklet,
+        workletRuntime === 'UIRuntime'
+      )
     );
   }
 
@@ -161,26 +168,23 @@ 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 =
+      AudioAPIModule.workletsModule!.makeShareableCloneRecursive(
+        (
+          audioBuffers: Array<ArrayBuffer>,
+          framesToProcess: number,
+          currentTime: number,
+          startOffset: number
+        ) => {
+          'worklet';
+          const floatAudioData: Array<Float32Array> = audioBuffers.map(
+            (buffer) => new Float32Array(buffer)
+          );
+          callback(floatAudioData, framesToProcess, currentTime, startOffset);
+        }
       );
-    }
-    const shareableWorklet = workletsModule.makeShareableCloneRecursive(
-      (
-        audioBuffers: Array<ArrayBuffer>,
-        framesToProcess: number,
-        currentTime: number,
-        startOffset: number
-      ) => {
-        'worklet';
-        const floatAudioData: Array<Float32Array> = audioBuffers.map(
-          (buffer) => new Float32Array(buffer)
-        );
-        callback(floatAudioData, framesToProcess, currentTime, startOffset);
-      }
-    );
+
     return new WorkletSourceNode(
       this,
       this.context.createWorkletSourceNode(
@@ -199,7 +203,11 @@ export default class BaseAudioContext {
   }
 
   createStreamer(): StreamerNode {
-    return new StreamerNode(this, this.context.createStreamer());
+    const streamer = this.context.createStreamer();
+    if (!streamer) {
+      throw new NotSupportedError('StreamerNode requires FFmpeg build');
+    }
+    return new StreamerNode(this, streamer);
   }
 
   createConstantSource(): ConstantSourceNode {
@@ -210,6 +218,11 @@ export default class BaseAudioContext {
     return new GainNode(this, this.context.createGain());
   }
 
+  createDelay(maxDelayTime?: number): DelayNode {
+    const maxTime = maxDelayTime ?? 1.0;
+    return new DelayNode(this, this.context.createDelay(maxTime));
+  }
+
   createStereoPanner(): StereoPannerNode {
     return new StereoPannerNode(this, this.context.createStereoPanner());
   }
@@ -218,6 +231,38 @@ export default class BaseAudioContext {
     return new BiquadFilterNode(this, this.context.createBiquadFilter());
   }
 
+  createIIRFilter(options: IIRFilterNodeOptions): IIRFilterNode {
+    const feedforward = options.feedforward;
+    const feedback = options.feedback;
+    if (feedforward.length < 1 || feedforward.length > 20) {
+      throw new NotSupportedError(
+        `The provided feedforward array has length (${feedforward.length}) outside the range [1, 20]`
+      );
+    }
+    if (feedback.length < 1 || feedback.length > 20) {
+      throw new NotSupportedError(
+        `The provided feedback array has length (${feedback.length}) outside the range [1, 20]`
+      );
+    }
+
+    if (feedforward.every((value) => value === 0)) {
+      throw new InvalidStateError(
+        `Feedforward array must contain at least one non-zero value`
+      );
+    }
+
+    if (feedback[0] === 0) {
+      throw new InvalidStateError(
+        `First value of feedback array cannot be zero`
+      );
+    }
+
+    return new IIRFilterNode(
+      this,
+      this.context.createIIRFilter(feedforward, feedback)
+    );
+  }
+
   createBufferSource(
     options?: AudioBufferBaseSourceNodeOptions
   ): AudioBufferSourceNode {
@@ -289,4 +334,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).setBuffer(null);
+      return;
+    }
+    (this.node as IConvolverNode).setBuffer(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/DelayNode.ts

@@ -0,0 +1,13 @@
+import { IDelayNode } from '../interfaces';
+import AudioNode from './AudioNode';
+import AudioParam from './AudioParam';
+import BaseAudioContext from './BaseAudioContext';
+
+export default class DelayNode extends AudioNode {
+  readonly delayTime: AudioParam;
+
+  constructor(context: BaseAudioContext, delay: IDelayNode) {
+    super(context, delay);
+    this.delayTime = new AudioParam(delay.delayTime, context);
+  }
+}