@idealyst/audio 1.2.107 → 1.2.108

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/audio",
-  "version": "1.2.107",
+  "version": "1.2.108",
   "description": "Unified cross-platform audio for React and React Native - recording, playback, and PCM streaming",
   "documentation": "https://github.com/IdealystIO/idealyst-framework/tree/main/packages/audio#readme",
   "readme": "README.md",

package/src/background/BackgroundRecorder.native.ts

@@ -0,0 +1,324 @@
+/**
+ * Native Background Recorder
+ *
+ * Wraps an IRecorder with React Native AppState awareness to manage
+ * background recording lifecycle. The underlying react-native-audio-api
+ * handles the actual background execution (foreground service on Android,
+ * background audio mode on iOS).
+ */
+
+import { AppState, type AppStateStatus as RNAppStateStatus } from 'react-native';
+import type {
+  IBackgroundRecorder,
+  IRecorder,
+  IAudioContext,
+  BackgroundRecorderStatus,
+  BackgroundRecorderConfig,
+  BackgroundLifecycleCallback,
+  BackgroundLifecycleInfo,
+  BackgroundStatusCallback,
+  RecorderDataCallback,
+  RecorderLevelCallback,
+  RecorderStatus,
+  AudioConfig,
+  PermissionStatus,
+  AppStateStatus,
+} from '../types';
+import { DEFAULT_BACKGROUND_RECORDER_STATUS, SESSION_PRESETS } from '../constants';
+import { getAudioSessionManager } from '../session/index.native';
+import { createRecorder } from '../recording/index.native';
+
+export class NativeBackgroundRecorder implements IBackgroundRecorder {
+  readonly recorder: IRecorder;
+
+  private sessionManager = getAudioSessionManager();
+  private config: BackgroundRecorderConfig;
+
+  private _status: BackgroundRecorderStatus = { ...DEFAULT_BACKGROUND_RECORDER_STATUS };
+  private appStateSubscription: { remove: () => void } | null = null;
+  private interruptionUnsubscribe: (() => void) | null = null;
+  private recorderStateUnsubscribe: (() => void) | null = null;
+  private maxDurationTimer: ReturnType<typeof setTimeout> | null = null;
+  private backgroundStartTime: number | null = null;
+
+  private lifecycleCallbacks = new Set<BackgroundLifecycleCallback>();
+  private statusCallbacks = new Set<BackgroundStatusCallback>();
+
+  constructor(audioContext: IAudioContext, config: BackgroundRecorderConfig = {}) {
+    this.config = config;
+
+    // Create the underlying recorder
+    this.recorder = createRecorder(audioContext);
+
+    // Subscribe to inner recorder state changes to keep status in sync
+    this.recorderStateUnsubscribe = this.recorder.onStateChange(
+      (innerStatus: RecorderStatus) => {
+        this.updateStatus({
+          ...innerStatus,
+          // Preserve background-specific fields
+          appState: this._status.appState,
+          isInBackground: this._status.isInBackground,
+          wasInterrupted: this._status.wasInterrupted,
+          backgroundSince: this._status.backgroundSince,
+          backgroundDuration: this._status.backgroundDuration,
+        });
+      },
+    );
+
+    // Listen to AppState changes
+    this.appStateSubscription = AppState.addEventListener('change', this.handleAppStateChange);
+
+    // Listen to audio session interruptions (phone calls, Siri, etc.)
+    this.interruptionUnsubscribe = this.sessionManager.onInterruption((interruption) => {
+      if (interruption.type === 'began') {
+        this.updateStatus({ wasInterrupted: true });
+        this.fireLifecycle({
+          event: 'interrupted',
+          timestamp: Date.now(),
+        });
+      } else if (interruption.type === 'ended') {
+        this.fireLifecycle({
+          event: 'interruptionEnded',
+          timestamp: Date.now(),
+          shouldResume: interruption.shouldResume,
+        });
+      }
+    });
+  }
+
+  get status(): BackgroundRecorderStatus {
+    return { ...this._status };
+  }
+
+  // -- Proxied recording control --
+
+  async start(configOverride?: Partial<AudioConfig>): Promise<void> {
+    // Configure audio session for background if needed
+    if (this.config.autoConfigureSession !== false) {
+      const sessionConfig = this.config.session ?? SESSION_PRESETS.backgroundRecord;
+      await this.sessionManager.configure(sessionConfig);
+    }
+
+    // Reset background state for new recording session
+    this.updateStatus({
+      wasInterrupted: false,
+      backgroundDuration: 0,
+      backgroundSince: null,
+    });
+
+    await this.recorder.start(configOverride ?? this.config.audio);
+  }
+
+  async stop(): Promise<void> {
+    this.clearMaxDurationTimer();
+    const wasInBackground = this._status.isInBackground;
+
+    await this.recorder.stop();
+
+    if (wasInBackground) {
+      this.fireLifecycle({
+        event: 'stopped',
+        timestamp: Date.now(),
+        backgroundDuration: this._status.backgroundDuration,
+      });
+    }
+  }
+
+  async pause(): Promise<void> {
+    await this.recorder.pause();
+  }
+
+  async resume(): Promise<void> {
+    await this.recorder.resume();
+  }
+
+  // -- Proxied permission --
+
+  async checkPermission(): Promise<PermissionStatus> {
+    return this.recorder.checkPermission();
+  }
+
+  async requestPermission(): Promise<PermissionStatus> {
+    return this.recorder.requestPermission();
+  }
+
+  // -- Proxied data streaming --
+
+  onData(callback: RecorderDataCallback): () => void {
+    return this.recorder.onData(callback);
+  }
+
+  onLevel(callback: RecorderLevelCallback, intervalMs?: number): () => void {
+    return this.recorder.onLevel(callback, intervalMs);
+  }
+
+  // -- Background-specific --
+
+  onLifecycle(callback: BackgroundLifecycleCallback): () => void {
+    this.lifecycleCallbacks.add(callback);
+    return () => {
+      this.lifecycleCallbacks.delete(callback);
+    };
+  }
+
+  onStatusChange(callback: BackgroundStatusCallback): () => void {
+    this.statusCallbacks.add(callback);
+    return () => {
+      this.statusCallbacks.delete(callback);
+    };
+  }
+
+  resetPeakLevel(): void {
+    this.recorder.resetPeakLevel();
+  }
+
+  dispose(): void {
+    this.clearMaxDurationTimer();
+
+    if (this.appStateSubscription) {
+      this.appStateSubscription.remove();
+      this.appStateSubscription = null;
+    }
+
+    if (this.interruptionUnsubscribe) {
+      this.interruptionUnsubscribe();
+      this.interruptionUnsubscribe = null;
+    }
+
+    if (this.recorderStateUnsubscribe) {
+      this.recorderStateUnsubscribe();
+      this.recorderStateUnsubscribe = null;
+    }
+
+    this.lifecycleCallbacks.clear();
+    this.statusCallbacks.clear();
+    this.recorder.dispose();
+  }
+
+  // -- Private --
+
+  private handleAppStateChange = (nextAppState: RNAppStateStatus): void => {
+    const mappedState = this.mapAppState(nextAppState);
+    const previousState = this._status.appState;
+    const isRecording = this._status.isRecording;
+
+    this.updateStatus({ appState: mappedState });
+
+    // Transition: foreground -> background
+    if (
+      previousState === 'active' &&
+      (mappedState === 'background' || mappedState === 'inactive')
+    ) {
+      this.backgroundStartTime = Date.now();
+      this.updateStatus({
+        isInBackground: true,
+        backgroundSince: this.backgroundStartTime,
+      });
+
+      if (isRecording) {
+        this.fireLifecycle({
+          event: 'backgrounded',
+          timestamp: Date.now(),
+        });
+
+        this.startMaxDurationTimer();
+      }
+    }
+
+    // Transition: background -> foreground
+    if (
+      (previousState === 'background' || previousState === 'inactive') &&
+      mappedState === 'active'
+    ) {
+      const bgDuration = this.backgroundStartTime
+        ? Date.now() - this.backgroundStartTime
+        : 0;
+
+      this.clearMaxDurationTimer();
+
+      this.updateStatus({
+        isInBackground: false,
+        backgroundSince: null,
+        backgroundDuration: this._status.backgroundDuration + bgDuration,
+      });
+
+      this.backgroundStartTime = null;
+
+      if (isRecording) {
+        this.fireLifecycle({
+          event: 'foregrounded',
+          timestamp: Date.now(),
+          backgroundDuration: bgDuration,
+        });
+      }
+    }
+  };
+
+  private mapAppState(rnState: RNAppStateStatus): AppStateStatus {
+    switch (rnState) {
+      case 'active':
+        return 'active';
+      case 'background':
+        return 'background';
+      case 'inactive':
+        return 'inactive';
+      case 'unknown':
+        return 'unknown';
+      case 'extension':
+        return 'extension';
+      default:
+        return 'unknown';
+    }
+  }
+
+  private startMaxDurationTimer(): void {
+    this.clearMaxDurationTimer();
+
+    const maxDuration = this.config.maxBackgroundDuration;
+    if (!maxDuration || maxDuration <= 0) return;
+
+    this.maxDurationTimer = setTimeout(() => {
+      this.fireLifecycle({
+        event: 'maxDurationReached',
+        timestamp: Date.now(),
+        backgroundDuration: maxDuration,
+      });
+      this.stop().catch(console.error);
+    }, maxDuration);
+  }
+
+  private clearMaxDurationTimer(): void {
+    if (this.maxDurationTimer) {
+      clearTimeout(this.maxDurationTimer);
+      this.maxDurationTimer = null;
+    }
+  }
+
+  private fireLifecycle(info: BackgroundLifecycleInfo): void {
+    this.lifecycleCallbacks.forEach((cb) => {
+      try {
+        cb(info);
+      } catch (e) {
+        console.error('[BackgroundRecorder] Error in lifecycle callback:', e);
+      }
+    });
+  }
+
+  private updateStatus(partial: Partial<BackgroundRecorderStatus>): void {
+    this._status = { ...this._status, ...partial };
+    this.statusCallbacks.forEach((cb) => {
+      try {
+        cb(this._status);
+      } catch (e) {
+        console.error('[BackgroundRecorder] Error in status callback:', e);
+      }
+    });
+  }
+}
+
+export function createBackgroundRecorder(
+  audioContext: IAudioContext,
+  config?: BackgroundRecorderConfig,
+): IBackgroundRecorder {
+  return new NativeBackgroundRecorder(audioContext, config);
+}

package/src/background/BackgroundRecorder.web.ts

@@ -0,0 +1,127 @@
+/**
+ * Web Background Recorder (graceful degradation)
+ *
+ * On web, there is no "background" concept for apps.
+ * This wraps the web recorder and provides the same interface,
+ * but background lifecycle events never fire.
+ */
+
+import type {
+  IBackgroundRecorder,
+  IAudioContext,
+  BackgroundRecorderStatus,
+  BackgroundRecorderConfig,
+  BackgroundLifecycleCallback,
+  BackgroundStatusCallback,
+  RecorderDataCallback,
+  RecorderLevelCallback,
+  RecorderStatus,
+  AudioConfig,
+  PermissionStatus,
+} from '../types';
+import { DEFAULT_BACKGROUND_RECORDER_STATUS } from '../constants';
+import { createRecorder } from '../recording';
+
+export class WebBackgroundRecorder implements IBackgroundRecorder {
+  readonly recorder;
+
+  private _status: BackgroundRecorderStatus = { ...DEFAULT_BACKGROUND_RECORDER_STATUS };
+  private statusCallbacks = new Set<BackgroundStatusCallback>();
+  private recorderStateUnsubscribe: (() => void) | null = null;
+
+  constructor(audioContext: IAudioContext, _config?: BackgroundRecorderConfig) {
+    this.recorder = createRecorder(audioContext);
+
+    this.recorderStateUnsubscribe = this.recorder.onStateChange(
+      (innerStatus: RecorderStatus) => {
+        this.updateStatus({
+          ...innerStatus,
+          appState: 'active',
+          isInBackground: false,
+          wasInterrupted: false,
+          backgroundSince: null,
+          backgroundDuration: 0,
+        });
+      },
+    );
+  }
+
+  get status(): BackgroundRecorderStatus {
+    return { ...this._status };
+  }
+
+  async start(config?: Partial<AudioConfig>): Promise<void> {
+    await this.recorder.start(config);
+  }
+
+  async stop(): Promise<void> {
+    await this.recorder.stop();
+  }
+
+  async pause(): Promise<void> {
+    await this.recorder.pause();
+  }
+
+  async resume(): Promise<void> {
+    await this.recorder.resume();
+  }
+
+  async checkPermission(): Promise<PermissionStatus> {
+    return this.recorder.checkPermission();
+  }
+
+  async requestPermission(): Promise<PermissionStatus> {
+    return this.recorder.requestPermission();
+  }
+
+  onData(callback: RecorderDataCallback): () => void {
+    return this.recorder.onData(callback);
+  }
+
+  onLevel(callback: RecorderLevelCallback, intervalMs?: number): () => void {
+    return this.recorder.onLevel(callback, intervalMs);
+  }
+
+  onLifecycle(_callback: BackgroundLifecycleCallback): () => void {
+    // No-op on web — background events never fire
+    return () => {};
+  }
+
+  onStatusChange(callback: BackgroundStatusCallback): () => void {
+    this.statusCallbacks.add(callback);
+    return () => {
+      this.statusCallbacks.delete(callback);
+    };
+  }
+
+  resetPeakLevel(): void {
+    this.recorder.resetPeakLevel();
+  }
+
+  dispose(): void {
+    if (this.recorderStateUnsubscribe) {
+      this.recorderStateUnsubscribe();
+      this.recorderStateUnsubscribe = null;
+    }
+    this.statusCallbacks.clear();
+    this.recorder.dispose();
+  }
+
+  private updateStatus(partial: Partial<BackgroundRecorderStatus>): void {
+    this._status = { ...this._status, ...partial };
+    this.statusCallbacks.forEach((cb) => {
+      try {
+        cb(this._status);
+      } catch (e) {
+        console.error('[BackgroundRecorder] Error in status callback:', e);
+      }
+    });
+  }
+}
+
+export function createBackgroundRecorder(
+  audioContext: IAudioContext,
+  config?: BackgroundRecorderConfig,
+): IBackgroundRecorder {
+  return new WebBackgroundRecorder(audioContext, config);
+}

package/src/background/index.native.ts

@@ -0,0 +1 @@
+export { NativeBackgroundRecorder, createBackgroundRecorder } from './BackgroundRecorder.native';

package/src/background/index.ts

@@ -0,0 +1 @@
+export { WebBackgroundRecorder, createBackgroundRecorder } from './BackgroundRecorder.web';

package/src/constants.ts

@@ -4,6 +4,7 @@ import type {
   RecorderStatus,
   PlayerStatus,
   AudioSessionState,
+  BackgroundRecorderStatus,
   AudioProfiles,
   SessionPresets,
 } from './types';
@@ -105,6 +106,14 @@ export const SESSION_PRESETS: SessionPresets = {
     categoryOptions: ['defaultToSpeaker', 'allowBluetooth', 'allowBluetoothA2DP', 'mixWithOthers'],
     active: true,
   },
+
+  /** For background audio recording (STT, voice memos, transcription) */
+  backgroundRecord: {
+    category: 'playAndRecord',
+    mode: 'spokenAudio',
+    categoryOptions: ['defaultToSpeaker', 'allowBluetooth', 'allowBluetoothA2DP', 'mixWithOthers'],
+    active: true,
+  },
 };
 
 // ============================================
@@ -159,3 +168,16 @@ export const BIT_DEPTH_MAX_VALUES = {
   16: 32768,
   32: 1.0,
 } as const;
+
+// ============================================
+// BACKGROUND RECORDER DEFAULTS
+// ============================================
+
+export const DEFAULT_BACKGROUND_RECORDER_STATUS: BackgroundRecorderStatus = {
+  ...DEFAULT_RECORDER_STATUS,
+  appState: 'active',
+  isInBackground: false,
+  wasInterrupted: false,
+  backgroundSince: null,
+  backgroundDuration: 0,
+};

package/src/hooks/index.ts

@@ -1,3 +1,4 @@
 export { useAudio } from './useAudio';
 export { useRecorder } from './useRecorder';
 export { usePlayer } from './usePlayer';
+export { useBackgroundRecorder } from './useBackgroundRecorder';

package/src/hooks/useBackgroundRecorder.ts

@@ -0,0 +1,194 @@
+/**
+ * useBackgroundRecorder Hook
+ *
+ * Provides recording functionality with PCM data streaming and
+ * background lifecycle awareness. On native, detects app state
+ * transitions and fires lifecycle callbacks. On web, works
+ * identically to useRecorder (background events never fire).
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import type {
+  UseBackgroundRecorderOptions,
+  UseBackgroundRecorderResult,
+  BackgroundRecorderStatus,
+  PermissionStatus,
+  AudioConfig,
+  RecorderDataCallback,
+  BackgroundLifecycleCallback,
+  IBackgroundRecorder,
+} from '../types';
+import {
+  DEFAULT_BACKGROUND_RECORDER_STATUS,
+  DEFAULT_LEVEL_UPDATE_INTERVAL,
+} from '../constants';
+import { getAudioContext } from '../context';
+import { createBackgroundRecorder } from '../background';
+
+export function useBackgroundRecorder(
+  options: UseBackgroundRecorderOptions = {},
+): UseBackgroundRecorderResult {
+  const {
+    config,
+    session,
+    autoRequestPermission = false,
+    levelUpdateInterval = DEFAULT_LEVEL_UPDATE_INTERVAL,
+    maxBackgroundDuration,
+    autoConfigureSession = true,
+    onLifecycleEvent,
+  } = options;
+
+  const [status, setStatus] = useState<BackgroundRecorderStatus>(
+    DEFAULT_BACKGROUND_RECORDER_STATUS,
+  );
+
+  const audioContextRef = useRef(getAudioContext());
+  const bgRecorderRef = useRef<IBackgroundRecorder | null>(null);
+  const mountedRef = useRef(true);
+  const lifecycleCallbackRef = useRef<BackgroundLifecycleCallback | undefined>(onLifecycleEvent);
+
+  // Keep lifecycle callback ref up to date
+  lifecycleCallbackRef.current = onLifecycleEvent;
+
+  // Initialize background recorder lazily
+  const getBgRecorder = useCallback(() => {
+    if (!bgRecorderRef.current) {
+      bgRecorderRef.current = createBackgroundRecorder(audioContextRef.current, {
+        audio: config,
+        session,
+        maxBackgroundDuration,
+        autoConfigureSession,
+      });
+    }
+    return bgRecorderRef.current;
+  }, [config, session, maxBackgroundDuration, autoConfigureSession]);
+
+  // Check permission
+  const checkPermission = useCallback(async (): Promise<PermissionStatus> => {
+    return getBgRecorder().checkPermission();
+  }, [getBgRecorder]);
+
+  // Request permission
+  const requestPermission = useCallback(async (): Promise<PermissionStatus> => {
+    return getBgRecorder().requestPermission();
+  }, [getBgRecorder]);
+
+  // Start recording
+  const start = useCallback(async (startConfig?: Partial<AudioConfig>) => {
+    const bgRecorder = getBgRecorder();
+    const audioContext = audioContextRef.current;
+
+    // Ensure audio context is initialized
+    if (!audioContext.isInitialized) {
+      await audioContext.initialize();
+    }
+
+    await bgRecorder.start(startConfig ?? config);
+  }, [getBgRecorder, config]);
+
+  // Stop recording
+  const stop = useCallback(async () => {
+    await getBgRecorder().stop();
+  }, [getBgRecorder]);
+
+  // Pause recording
+  const pause = useCallback(async () => {
+    await getBgRecorder().pause();
+  }, [getBgRecorder]);
+
+  // Resume recording
+  const resume = useCallback(async () => {
+    await getBgRecorder().resume();
+  }, [getBgRecorder]);
+
+  // Subscribe to data
+  const subscribeToData = useCallback((callback: RecorderDataCallback): (() => void) => {
+    return getBgRecorder().onData(callback);
+  }, [getBgRecorder]);
+
+  // Reset peak level
+  const resetPeakLevel = useCallback(() => {
+    if (bgRecorderRef.current) {
+      bgRecorderRef.current.resetPeakLevel();
+    }
+  }, []);
+
+  // Setup on mount
+  useEffect(() => {
+    mountedRef.current = true;
+
+    const bgRecorder = getBgRecorder();
+
+    // Subscribe to background status changes
+    const unsubStatus = bgRecorder.onStatusChange((newStatus) => {
+      if (mountedRef.current) {
+        setStatus(newStatus);
+      }
+    });
+
+    // Subscribe to level updates
+    const unsubLevel = bgRecorder.onLevel((level) => {
+      if (mountedRef.current) {
+        setStatus((prev) => ({ ...prev, level }));
+      }
+    }, levelUpdateInterval);
+
+    // Subscribe to lifecycle events and forward to callback
+    const unsubLifecycle = bgRecorder.onLifecycle((info) => {
+      if (mountedRef.current && lifecycleCallbackRef.current) {
+        lifecycleCallbackRef.current(info);
+      }
+    });
+
+    // Auto request permission if enabled
+    if (autoRequestPermission) {
+      requestPermission().catch(console.error);
+    }
+
+    return () => {
+      mountedRef.current = false;
+      unsubStatus();
+      unsubLevel();
+      unsubLifecycle();
+
+      // Dispose background recorder on unmount
+      if (bgRecorderRef.current) {
+        bgRecorderRef.current.dispose();
+        bgRecorderRef.current = null;
+      }
+    };
+  }, [getBgRecorder, autoRequestPermission, requestPermission, levelUpdateInterval]);
+
+  return {
+    // Standard recorder state
+    status,
+    isRecording: status.isRecording,
+    isPaused: status.isPaused,
+    permission: status.permission,
+    duration: status.duration,
+    level: status.level,
+    error: status.error ?? null,
+
+    // Background-specific state
+    isInBackground: status.isInBackground,
+    wasInterrupted: status.wasInterrupted,
+    backgroundDuration: status.backgroundDuration,
+    appState: status.appState,
+
+    // Actions
+    start,
+    stop,
+    pause,
+    resume,
+
+    // Permissions
+    checkPermission,
+    requestPermission,
+
+    // Data subscription
+    subscribeToData,
+
+    // Utilities
+    resetPeakLevel,
+  };
+}

package/src/index.native.ts

@@ -63,6 +63,18 @@ export type {
   // Presets
   AudioProfiles,
   SessionPresets,
+
+  // Background recorder
+  AppStateStatus,
+  BackgroundRecorderStatus,
+  BackgroundLifecycleEvent,
+  BackgroundLifecycleInfo,
+  BackgroundLifecycleCallback,
+  BackgroundStatusCallback,
+  BackgroundRecorderConfig,
+  IBackgroundRecorder,
+  UseBackgroundRecorderOptions,
+  UseBackgroundRecorderResult,
 } from './types';
 
 // Constants
@@ -81,6 +93,7 @@ export {
   DEFAULT_SESSION_STATE,
   DEFAULT_LEVEL_UPDATE_INTERVAL,
   DEFAULT_POSITION_UPDATE_INTERVAL,
+  DEFAULT_BACKGROUND_RECORDER_STATUS,
 } from './constants';
 
 // Context (native)
@@ -95,8 +108,11 @@ export { createRecorder, NativeRecorder } from './recording/index.native';
 // Playback (native)
 export { createPlayer, NativePlayer } from './playback/index.native';
 
+// Background Recording (native)
+export { createBackgroundRecorder, NativeBackgroundRecorder } from './background/index.native';
+
 // Hooks
-export { useAudio, useRecorder, usePlayer } from './hooks';
+export { useAudio, useRecorder, usePlayer, useBackgroundRecorder } from './hooks';
 
 // Utilities
 export {

package/src/index.ts

@@ -63,6 +63,18 @@ export type {
   // Presets
   AudioProfiles,
   SessionPresets,
+
+  // Background recorder
+  AppStateStatus,
+  BackgroundRecorderStatus,
+  BackgroundLifecycleEvent,
+  BackgroundLifecycleInfo,
+  BackgroundLifecycleCallback,
+  BackgroundStatusCallback,
+  BackgroundRecorderConfig,
+  IBackgroundRecorder,
+  UseBackgroundRecorderOptions,
+  UseBackgroundRecorderResult,
 } from './types';
 
 // Constants
@@ -81,6 +93,7 @@ export {
   DEFAULT_SESSION_STATE,
   DEFAULT_LEVEL_UPDATE_INTERVAL,
   DEFAULT_POSITION_UPDATE_INTERVAL,
+  DEFAULT_BACKGROUND_RECORDER_STATUS,
 } from './constants';
 
 // Context
@@ -95,8 +108,11 @@ export { createRecorder, WebRecorder } from './recording';
 // Playback
 export { createPlayer, WebPlayer } from './playback';
 
+// Background Recording (web)
+export { createBackgroundRecorder, WebBackgroundRecorder } from './background';
+
 // Hooks
-export { useAudio, useRecorder, usePlayer } from './hooks';
+export { useAudio, useRecorder, usePlayer, useBackgroundRecorder } from './hooks';
 
 // Utilities
 export {

package/src/index.web.ts

@@ -63,6 +63,18 @@ export type {
   // Presets
   AudioProfiles,
   SessionPresets,
+
+  // Background recorder
+  AppStateStatus,
+  BackgroundRecorderStatus,
+  BackgroundLifecycleEvent,
+  BackgroundLifecycleInfo,
+  BackgroundLifecycleCallback,
+  BackgroundStatusCallback,
+  BackgroundRecorderConfig,
+  IBackgroundRecorder,
+  UseBackgroundRecorderOptions,
+  UseBackgroundRecorderResult,
 } from './types';
 
 // Constants
@@ -81,6 +93,7 @@ export {
   DEFAULT_SESSION_STATE,
   DEFAULT_LEVEL_UPDATE_INTERVAL,
   DEFAULT_POSITION_UPDATE_INTERVAL,
+  DEFAULT_BACKGROUND_RECORDER_STATUS,
 } from './constants';
 
 // Context
@@ -95,8 +108,11 @@ export { createRecorder, WebRecorder } from './recording';
 // Playback
 export { createPlayer, WebPlayer } from './playback';
 
+// Background Recording (web)
+export { createBackgroundRecorder, WebBackgroundRecorder } from './background';
+
 // Hooks
-export { useAudio, useRecorder, usePlayer } from './hooks';
+export { useAudio, useRecorder, usePlayer, useBackgroundRecorder } from './hooks';
 
 // Utilities
 export {

package/src/types.ts

@@ -324,6 +324,9 @@ export type AudioErrorCode =
   | 'BUFFER_UNDERRUN'
   // Recording errors
   | 'RECORDING_ERROR'
+  // Background errors
+  | 'BACKGROUND_NOT_SUPPORTED'
+  | 'BACKGROUND_MAX_DURATION'
   // General errors
   | 'INITIALIZATION_FAILED'
   | 'INVALID_STATE'
@@ -469,4 +472,162 @@ export interface SessionPresets {
   voiceChat: AudioSessionConfig;
   ambient: AudioSessionConfig;
   default: AudioSessionConfig;
+  backgroundRecord: AudioSessionConfig;
+}
+
+// ============================================
+// BACKGROUND RECORDER TYPES
+// ============================================
+
+export type AppStateStatus = 'active' | 'background' | 'inactive' | 'unknown' | 'extension';
+
+/**
+ * Extended recorder status with background lifecycle state.
+ */
+export interface BackgroundRecorderStatus extends RecorderStatus {
+  /** Current app state */
+  appState: AppStateStatus;
+
+  /** Whether the recorder is currently operating in background */
+  isInBackground: boolean;
+
+  /** Whether the recording was interrupted by the OS (phone call, Siri, etc.) */
+  wasInterrupted: boolean;
+
+  /** Timestamp when the app last entered background, or null */
+  backgroundSince: number | null;
+
+  /** Total time spent recording in background (ms) */
+  backgroundDuration: number;
+}
+
+/** Lifecycle event types fired by the background recorder */
+export type BackgroundLifecycleEvent =
+  | 'backgrounded'
+  | 'foregrounded'
+  | 'interrupted'
+  | 'interruptionEnded'
+  | 'maxDurationReached'
+  | 'stopped';
+
+export interface BackgroundLifecycleInfo {
+  event: BackgroundLifecycleEvent;
+  timestamp: number;
+  /** Duration spent in background when foregrounded (ms) */
+  backgroundDuration?: number;
+  /** Whether the OS suggested resuming after interruption */
+  shouldResume?: boolean;
+}
+
+export type BackgroundLifecycleCallback = (info: BackgroundLifecycleInfo) => void;
+export type BackgroundStatusCallback = (status: BackgroundRecorderStatus) => void;
+
+export interface BackgroundRecorderConfig {
+  /** Audio configuration for recording */
+  audio?: Partial<AudioConfig>;
+
+  /** Audio session configuration for background recording.
+   *  Defaults to SESSION_PRESETS.backgroundRecord */
+  session?: Partial<AudioSessionConfig>;
+
+  /** Maximum duration to record in background (ms). undefined = no limit */
+  maxBackgroundDuration?: number;
+
+  /** Whether to automatically configure the audio session for background.
+   *  Default: true */
+  autoConfigureSession?: boolean;
+}
+
+/**
+ * Background-aware recorder interface.
+ * Composes an IRecorder with AppState lifecycle management.
+ */
+export interface IBackgroundRecorder {
+  /** The wrapped recorder instance */
+  readonly recorder: IRecorder;
+
+  /** Background-aware status */
+  readonly status: BackgroundRecorderStatus;
+
+  // Recording control (proxied to inner recorder)
+  start(config?: Partial<AudioConfig>): Promise<void>;
+  stop(): Promise<void>;
+  pause(): Promise<void>;
+  resume(): Promise<void>;
+
+  // Permission (proxied)
+  checkPermission(): Promise<PermissionStatus>;
+  requestPermission(): Promise<PermissionStatus>;
+
+  // Data streaming (proxied)
+  onData(callback: RecorderDataCallback): () => void;
+  onLevel(callback: RecorderLevelCallback, intervalMs?: number): () => void;
+
+  // Background-specific
+  onLifecycle(callback: BackgroundLifecycleCallback): () => void;
+  onStatusChange(callback: BackgroundStatusCallback): () => void;
+
+  // Cleanup
+  resetPeakLevel(): void;
+  dispose(): void;
+}
+
+// ============================================
+// BACKGROUND RECORDER HOOK TYPES
+// ============================================
+
+export interface UseBackgroundRecorderOptions {
+  /** Audio configuration */
+  config?: Partial<AudioConfig>;
+
+  /** Audio session configuration for background recording */
+  session?: Partial<AudioSessionConfig>;
+
+  /** Auto request permission on mount */
+  autoRequestPermission?: boolean;
+
+  /** Level update interval in ms. Default: 100 */
+  levelUpdateInterval?: number;
+
+  /** Maximum background recording duration (ms). undefined = no limit */
+  maxBackgroundDuration?: number;
+
+  /** Whether to auto-configure audio session. Default: true */
+  autoConfigureSession?: boolean;
+
+  /** Called on background lifecycle events */
+  onLifecycleEvent?: BackgroundLifecycleCallback;
+}
+
+export interface UseBackgroundRecorderResult {
+  // Standard recorder state
+  status: BackgroundRecorderStatus;
+  isRecording: boolean;
+  isPaused: boolean;
+  permission: PermissionStatus;
+  duration: number;
+  level: AudioLevel;
+  error: AudioError | null;
+
+  // Background-specific state
+  isInBackground: boolean;
+  wasInterrupted: boolean;
+  backgroundDuration: number;
+  appState: AppStateStatus;
+
+  // Actions
+  start: (config?: Partial<AudioConfig>) => Promise<void>;
+  stop: () => Promise<void>;
+  pause: () => Promise<void>;
+  resume: () => Promise<void>;
+
+  // Permissions
+  checkPermission: () => Promise<PermissionStatus>;
+  requestPermission: () => Promise<PermissionStatus>;
+
+  // Data subscription
+  subscribeToData: (callback: RecorderDataCallback) => () => void;
+
+  // Utilities
+  resetPeakLevel: () => void;
 }