react-native-audio-api 0.11.0-nightly-95f9c99-20251215 → 0.11.0-nightly-dd83923-20251216

package/src/interfaces.ts

@@ -1,10 +1,14 @@
 import { AudioEventCallback, AudioEventName } from './events/types';
-import {
+import type {
+  AudioRecorderCallbackOptions,
+  AudioRecorderFileOptions,
   BiquadFilterType,
   ChannelCountMode,
   ChannelInterpretation,
   ContextState,
+  FileInfo,
   OscillatorType,
+  Result,
   WindowType,
 } from './types';
 
@@ -285,14 +289,39 @@ export interface IWorkletSourceNode extends IAudioScheduledSourceNode {}
 
 export interface IWorkletProcessingNode extends IAudioNode {}
 
+export interface IAudioRecorderCallbackOptions
+  extends AudioRecorderCallbackOptions {
+  callbackId: string;
+}
+
 export interface IAudioRecorder {
-  start: () => void;
-  stop: () => void;
+  // default recorder methods
+  start: () => Result<{ path: string }>;
+  stop: () => Result<FileInfo>;
+  isRecording: () => boolean;
+  isPaused: () => boolean;
+
+  enableFileOutput: (
+    options: AudioRecorderFileOptions
+  ) => Result<{ path: string }>;
+  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) => Result<void>;
+  clearOnAudioReady: () => void;
+
+  setOnError: (options: { callbackId: string }) => void;
+  clearOnError: () => void;
+
+  getCurrentDuration: () => number;
+  getFilePath: () => string | null;
 }
 
 export interface IAudioDecoder {

package/src/specs/NativeAudioAPIModule.ts

@@ -1,7 +1,7 @@
 'use strict';
-import { TurboModuleRegistry } from 'react-native';
 import type { TurboModule } from 'react-native';
-import { PermissionStatus, AudioDevicesInfo } from '../system/types';
+import { TurboModuleRegistry } from 'react-native';
+import { AudioDevicesInfo, PermissionStatus } from '../system/types';
 
 type OptionsMap = { [key: string]: string | boolean | number | undefined };
 type NotificationOpResponse = { success: boolean; error?: string };

package/src/system/notification/PlaybackNotificationManager.ts

@@ -1,11 +1,11 @@
-import { NativeAudioAPIModule } from '../../specs';
 import { AudioEventEmitter, AudioEventSubscription } from '../../events';
+import { NativeAudioAPIModule } from '../../specs';
 import type {
+  NotificationEvents,
   NotificationManager,
-  PlaybackNotificationInfo,
   PlaybackControlName,
   PlaybackNotificationEventName,
-  NotificationEvents,
+  PlaybackNotificationInfo,
 } from './types';
 
 /// Manager for media playback notifications with controls and MediaSession integration.
@@ -18,8 +18,8 @@ class PlaybackNotificationManager
     >
 {
   private notificationKey = 'playback';
-  private isRegistered = false;
-  private isShown = false;
+  private isRegistered_ = false;
+  private isShown_ = false;
   private audioEventEmitter: AudioEventEmitter;
 
   constructor() {
@@ -28,7 +28,7 @@ class PlaybackNotificationManager
 
   /// Register the playback notification (must be called before showing).
   async register(): Promise<void> {
-    if (this.isRegistered) {
+    if (this.isRegistered_) {
       console.warn('PlaybackNotification is already registered');
       return;
     }
@@ -46,12 +46,12 @@ class PlaybackNotificationManager
       throw new Error(result.error);
     }
 
-    this.isRegistered = true;
+    this.isRegistered_ = true;
   }
 
   /// Show the notification with initial metadata.
   async show(info: PlaybackNotificationInfo): Promise<void> {
-    if (!this.isRegistered) {
+    if (!this.isRegistered_) {
       throw new Error(
         'PlaybackNotification must be registered before showing. Call register() first.'
       );
@@ -70,12 +70,12 @@ class PlaybackNotificationManager
       throw new Error(result.error);
     }
 
-    this.isShown = true;
+    this.isShown_ = true;
   }
 
   /// Update the notification with new metadata or state.
   async update(info: PlaybackNotificationInfo): Promise<void> {
-    if (!this.isShown) {
+    if (!this.isShown_) {
       console.warn('PlaybackNotification is not shown. Call show() first.');
       return;
     }
@@ -96,7 +96,7 @@ class PlaybackNotificationManager
 
   /// Hide the notification (can be shown again later).
   async hide(): Promise<void> {
-    if (!this.isShown) {
+    if (!this.isShown_) {
       return;
     }
 
@@ -112,16 +112,16 @@ class PlaybackNotificationManager
       throw new Error(result.error);
     }
 
-    this.isShown = false;
+    this.isShown_ = false;
   }
 
   /// Unregister the notification (must register again to use).
   async unregister(): Promise<void> {
-    if (!this.isRegistered) {
+    if (!this.isRegistered_) {
       return;
     }
 
-    if (this.isShown) {
+    if (this.isShown_) {
       await this.hide();
     }
 
@@ -137,7 +137,7 @@ class PlaybackNotificationManager
       throw new Error(result.error);
     }
 
-    this.isRegistered = false;
+    this.isRegistered_ = false;
   }
 
   /// Enable or disable a specific playback control.
@@ -145,7 +145,7 @@ class PlaybackNotificationManager
     control: PlaybackControlName,
     enabled: boolean
   ): Promise<void> {
-    if (!this.isRegistered) {
+    if (!this.isRegistered_) {
       console.warn('PlaybackNotification is not registered');
       return;
     }
@@ -176,6 +176,10 @@ class PlaybackNotificationManager
     );
   }
 
+  isRegistered(): boolean {
+    return this.isRegistered_;
+  }
+
   /// Add an event listener for notification actions.
   addEventListener<T extends PlaybackNotificationEventName>(
     eventName: T,

package/src/system/notification/RecordingNotificationManager.ts

@@ -1,12 +1,12 @@
 import { Platform } from 'react-native';
-import { NativeAudioAPIModule } from '../../specs';
 import { AudioEventEmitter, AudioEventSubscription } from '../../events';
+import { NativeAudioAPIModule } from '../../specs';
 import type {
+  NotificationEvents,
   NotificationManager,
-  RecordingNotificationInfo,
   RecordingControlName,
   RecordingNotificationEventName,
-  NotificationEvents,
+  RecordingNotificationInfo,
 } from './types';
 
 /// Manager for recording notifications with controls.
@@ -18,9 +18,10 @@ class RecordingNotificationManager
       RecordingNotificationEventName
     >
 {
+  private isRegistered_ = false;
+  private isShown_ = false;
+
   private notificationKey = 'recording';
-  private isRegistered = false;
-  private isShown = false;
   private audioEventEmitter: AudioEventEmitter;
   private isIOS = Platform.OS === 'ios';
 
@@ -30,14 +31,14 @@ class RecordingNotificationManager
 
   /// Register the recording notification (must be called before showing).
   async register(): Promise<void> {
-    if (this.isRegistered) {
+    if (this.isRegistered_) {
       console.warn('RecordingNotification is already registered');
       return;
     }
 
     // Recording notifications are only supported on Android
     if (this.isIOS) {
-      this.isRegistered = true;
+      this.isRegistered_ = true;
       return;
     }
 
@@ -54,12 +55,12 @@ class RecordingNotificationManager
       throw new Error(result.error);
     }
 
-    this.isRegistered = true;
+    this.isRegistered_ = true;
   }
 
   /// Show the notification with initial metadata.
   async show(info: RecordingNotificationInfo): Promise<void> {
-    if (!this.isRegistered) {
+    if (!this.isRegistered_) {
       throw new Error(
         'RecordingNotification must be registered before showing. Call register() first.'
       );
@@ -67,7 +68,7 @@ class RecordingNotificationManager
 
     // Recording notifications are only supported on Android
     if (this.isIOS) {
-      this.isShown = true;
+      this.isShown_ = true;
       return;
     }
 
@@ -84,12 +85,12 @@ class RecordingNotificationManager
       throw new Error(result.error);
     }
 
-    this.isShown = true;
+    this.isShown_ = true;
   }
 
   /// Update the notification with new metadata or state.
   async update(info: RecordingNotificationInfo): Promise<void> {
-    if (!this.isShown) {
+    if (!this.isShown_) {
       console.warn('RecordingNotification is not shown. Call show() first.');
       return;
     }
@@ -115,13 +116,13 @@ class RecordingNotificationManager
 
   /// Hide the notification (can be shown again later).
   async hide(): Promise<void> {
-    if (!this.isShown) {
+    if (!this.isShown_) {
       return;
     }
 
     // Recording notifications are only supported on Android
     if (this.isIOS) {
-      this.isShown = false;
+      this.isShown_ = false;
       return;
     }
 
@@ -137,22 +138,22 @@ class RecordingNotificationManager
       throw new Error(result.error);
     }
 
-    this.isShown = false;
+    this.isShown_ = false;
   }
 
   /// Unregister the notification (must register again to use).
   async unregister(): Promise<void> {
-    if (!this.isRegistered) {
+    if (!this.isRegistered_) {
       return;
     }
 
-    if (this.isShown) {
+    if (this.isShown_) {
       await this.hide();
     }
 
     // Recording notifications are only supported on Android
     if (this.isIOS) {
-      this.isRegistered = false;
+      this.isRegistered_ = false;
       return;
     }
 
@@ -168,7 +169,7 @@ class RecordingNotificationManager
       throw new Error(result.error);
     }
 
-    this.isRegistered = false;
+    this.isRegistered_ = false;
   }
 
   /// Enable or disable a specific recording control.
@@ -176,7 +177,7 @@ class RecordingNotificationManager
     control: RecordingControlName,
     enabled: boolean
   ): Promise<void> {
-    if (!this.isRegistered) {
+    if (!this.isRegistered_) {
       console.warn('RecordingNotification is not registered');
       return;
     }
@@ -205,7 +206,7 @@ class RecordingNotificationManager
   async isActive(): Promise<boolean> {
     // Recording notifications are only supported on Android
     if (this.isIOS) {
-      return this.isShown;
+      return this.isShown_;
     }
 
     if (!NativeAudioAPIModule) {
@@ -217,6 +218,10 @@ class RecordingNotificationManager
     );
   }
 
+  isRegistered(): boolean {
+    return this.isRegistered_;
+  }
+
   /// Add an event listener for notification actions.
   addEventListener<T extends RecordingNotificationEventName>(
     eventName: T,

package/src/system/notification/SimpleNotificationManager.ts

@@ -1,5 +1,5 @@
-import { NativeAudioAPIModule } from '../../specs';
 import { AudioEventEmitter, AudioEventSubscription } from '../../events';
+import { NativeAudioAPIModule } from '../../specs';
 import type { NotificationManager, SimpleNotificationOptions } from './types';
 
 /// Simple notification manager for basic notifications with title and text.
@@ -13,9 +13,10 @@ class SimpleNotificationManager
       never
     >
 {
+  private isRegistered_ = false;
+  private isShown_ = false;
+
   private notificationKey = 'simple';
-  private isRegistered = false;
-  private isShown = false;
   private audioEventEmitter: AudioEventEmitter;
 
   constructor() {
@@ -24,7 +25,7 @@ class SimpleNotificationManager
 
   /// Register the simple notification (must be called before showing).
   async register(): Promise<void> {
-    if (this.isRegistered) {
+    if (this.isRegistered_) {
       console.warn('SimpleNotification is already registered');
       return;
     }
@@ -42,12 +43,12 @@ class SimpleNotificationManager
       throw new Error(result.error);
     }
 
-    this.isRegistered = true;
+    this.isRegistered_ = true;
   }
 
   /// Show the notification with initial options.
   async show(options: SimpleNotificationOptions): Promise<void> {
-    if (!this.isRegistered) {
+    if (!this.isRegistered_) {
       throw new Error(
         'SimpleNotification must be registered before showing. Call register() first.'
       );
@@ -66,12 +67,12 @@ class SimpleNotificationManager
       throw new Error(result.error);
     }
 
-    this.isShown = true;
+    this.isShown_ = true;
   }
 
   /// Update the notification with new options.
   async update(options: SimpleNotificationOptions): Promise<void> {
-    if (!this.isShown) {
+    if (!this.isShown_) {
       console.warn('SimpleNotification is not shown. Call show() first.');
       return;
     }
@@ -92,7 +93,7 @@ class SimpleNotificationManager
 
   /// Hide the notification (can be shown again later).
   async hide(): Promise<void> {
-    if (!this.isShown) {
+    if (!this.isShown_) {
       return;
     }
 
@@ -108,16 +109,16 @@ class SimpleNotificationManager
       throw new Error(result.error);
     }
 
-    this.isShown = false;
+    this.isShown_ = false;
   }
 
   /// Unregister the notification (must register again to use).
   async unregister(): Promise<void> {
-    if (!this.isRegistered) {
+    if (!this.isRegistered_) {
       return;
     }
 
-    if (this.isShown) {
+    if (this.isShown_) {
       await this.hide();
     }
 
@@ -133,7 +134,7 @@ class SimpleNotificationManager
       throw new Error(result.error);
     }
 
-    this.isRegistered = false;
+    this.isRegistered_ = false;
   }
 
   /// Check if the notification is currently active.
@@ -147,6 +148,10 @@ class SimpleNotificationManager
     );
   }
 
+  isRegistered(): boolean {
+    return this.isRegistered_;
+  }
+
   /// Add an event listener (SimpleNotification doesn't emit events).
   addEventListener<T extends never>(
     _eventName: T,

package/src/system/notification/types.ts

@@ -97,6 +97,7 @@ export type RecordingNotificationEventName = keyof RecordingNotificationEvent;
 
 export type NotificationEvents = PlaybackNotificationEvent &
   RecordingNotificationEvent;
+
 export type NotificationEventName = keyof NotificationEvents;
 
 export type NotificationCallback<Name extends NotificationEventName> = (

package/src/types.ts

@@ -1,5 +1,9 @@
 import AudioBuffer from './core/AudioBuffer';
 
+export type Result<T> =
+  | ({ status: 'success' } & T)
+  | { status: 'error'; message: string };
+
 export type ChannelCountMode = 'max' | 'clamped-max' | 'explicit';
 
 export type ChannelInterpretation = 'speakers' | 'discrete';
@@ -14,7 +18,7 @@ export type BiquadFilterType =
   | 'notch'
   | 'allpass';
 
-export type ContextState = 'running' | 'closed' | `suspended`;
+export type ContextState = 'running' | 'closed' | 'suspended';
 
 export type AudioWorkletRuntime = 'AudioRuntime' | 'UIRuntime';
 
@@ -39,9 +43,69 @@ export interface OfflineAudioContextOptions {
   sampleRate: number;
 }
 
-export interface AudioRecorderOptions {
+export enum FileDirectory {
+  Document = 0,
+  Cache = 1,
+}
+
+export enum FileFormat {
+  Wav = 0,
+  Caf = 1,
+  M4A = 2,
+  Flac = 3,
+}
+
+export enum IOSAudioQuality {
+  Min = 0,
+  Low = 1,
+  Medium = 2,
+  High = 3,
+  Max = 4,
+}
+
+export enum BitDepth {
+  Bit16 = 0,
+  Bit24 = 1,
+  Bit32 = 2,
+}
+
+export enum FlacCompressionLevel {
+  L0 = 0,
+  L1 = 1,
+  L2 = 2,
+  L3 = 3,
+  L4 = 4,
+  L5 = 5,
+  L6 = 6,
+  L7 = 7,
+  L8 = 8,
+}
+
+export interface FilePresetType {
+  bitRate: number;
   sampleRate: number;
-  bufferLengthInSamples: number;
+  bitDepth: BitDepth;
+  iosQuality: IOSAudioQuality;
+  flacCompressionLevel: FlacCompressionLevel;
+}
+
+export interface AudioRecorderFileOptions {
+  channelCount?: number;
+  batchDurationSeconds?: number;
+
+  format?: FileFormat;
+  preset?: FilePresetType;
+
+  directory?: FileDirectory;
+  subDirectory?: string;
+  fileNamePrefix?: string;
+  androidFlushIntervalMs?: number;
+}
+
+export interface FileInfo {
+  path: string;
+  size: number;
+  duration: number;
 }
 
 export type WindowType = 'blackman' | 'hann';
@@ -57,6 +121,28 @@ export interface ConvolverNodeOptions {
   disableNormalization?: boolean;
 }
 
+export interface AudioRecorderCallbackOptions {
+  /**
+   * The desired sample rate (in Hz) for audio buffers delivered to the
+   * recording callback. Common values include 44100 or 48000 Hz. The actual
+   * sample rate may differ depending on hardware and system capabilities.
+   */
+  sampleRate: number;
+
+  /**
+   * The preferred size of each audio buffer, expressed as the number of samples
+   * per channel. Smaller buffers reduce latency but increase CPU load, while
+   * larger buffers improve efficiency at the cost of higher latency.
+   */
+  bufferLength: number;
+
+  /**
+   * The desired number of audio channels per buffer. Typically 1 for mono or 2
+   * for stereo recordings.
+   */
+  channelCount: number;
+}
+
 export interface IIRFilterNodeOptions {
   feedforward: number[];
   feedback: number[];

package/src/utils/filePresets.ts

@@ -0,0 +1,47 @@
+import {
+  BitDepth,
+  FilePresetType,
+  FlacCompressionLevel,
+  IOSAudioQuality,
+} from '../types';
+
+const LowQuality: FilePresetType = {
+  sampleRate: 22050,
+  bitRate: 48000,
+  bitDepth: BitDepth.Bit16,
+  flacCompressionLevel: FlacCompressionLevel.L0,
+  iosQuality: IOSAudioQuality.Low,
+};
+
+const MediumQuality: FilePresetType = {
+  sampleRate: 44100,
+  bitRate: 128000,
+  bitDepth: BitDepth.Bit16,
+  flacCompressionLevel: FlacCompressionLevel.L3,
+  iosQuality: IOSAudioQuality.Medium,
+};
+
+const HighQuality: FilePresetType = {
+  sampleRate: 48000,
+  bitRate: 192000,
+  bitDepth: BitDepth.Bit24,
+  flacCompressionLevel: FlacCompressionLevel.L5,
+  iosQuality: IOSAudioQuality.High,
+};
+
+const LosslessQuality: FilePresetType = {
+  sampleRate: 48000,
+  bitRate: 320000,
+  bitDepth: BitDepth.Bit24,
+  flacCompressionLevel: FlacCompressionLevel.L8,
+  iosQuality: IOSAudioQuality.High,
+};
+
+const FilePreset = {
+  Low: LowQuality,
+  Medium: MediumQuality,
+  High: HighQuality,
+  Lossless: LosslessQuality,
+} as const;
+
+export default FilePreset;

package/src/web-system/notification/PlaybackNotificationManager.ts

@@ -4,11 +4,11 @@
 
 import type { AudioEventSubscription } from '../../events';
 import type {
+  NotificationEvents,
   NotificationManager,
-  PlaybackNotificationInfo,
   PlaybackControlName,
   PlaybackNotificationEventName,
-  NotificationEvents,
+  PlaybackNotificationInfo,
 } from '../../system';
 
 /// Mock Manager for playback notifications. Does nothing.
@@ -20,8 +20,8 @@ class PlaybackNotificationManager
       PlaybackNotificationEventName
     >
 {
-  private isRegistered = false;
-  private isShown = false;
+  private isRegistered_ = false;
+  private isShown_ = false;
 
   constructor() {}
 
@@ -41,7 +41,11 @@ class PlaybackNotificationManager
   ): Promise<void> {}
 
   async isActive(): Promise<boolean> {
-    return this.isShown;
+    return this.isShown_;
+  }
+
+  isRegistered(): boolean {
+    return this.isRegistered_;
   }
 
   addEventListener<T extends PlaybackNotificationEventName>(