@idealyst/audio 1.2.48

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@idealyst/audio",
+  "version": "1.2.48",
+  "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",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "react-native": "src/index.native.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IdealystIO/idealyst-framework.git",
+    "directory": "packages/audio"
+  },
+  "author": "Idealyst <contact@idealyst.io>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "react-native": "./src/index.native.ts",
+      "browser": "./src/index.web.ts",
+      "import": "./src/index.ts",
+      "require": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "prepublishOnly": "echo 'Publishing TypeScript source directly'",
+    "publish:npm": "npm publish"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-native": ">=0.60.0",
+    "react-native-audio-api": ">=0.4.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    },
+    "react-native-audio-api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.0",
+    "@types/react-native": "^0.73.0",
+    "react-native-audio-api": "^0.4.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "react",
+    "react-native",
+    "audio",
+    "recording",
+    "playback",
+    "pcm",
+    "streaming",
+    "microphone",
+    "cross-platform",
+    "web-audio-api"
+  ]
+}

package/src/constants.ts

@@ -0,0 +1,161 @@
+import type {
+  AudioConfig,
+  AudioLevel,
+  RecorderStatus,
+  PlayerStatus,
+  AudioSessionState,
+  AudioProfiles,
+  SessionPresets,
+} from './types';
+
+// ============================================
+// AUDIO CONFIGURATION DEFAULTS
+// ============================================
+
+export const DEFAULT_AUDIO_CONFIG: AudioConfig = {
+  sampleRate: 16000,
+  channels: 1,
+  bitDepth: 16,
+};
+
+/**
+ * Pre-configured audio profiles for common use cases.
+ */
+export const AUDIO_PROFILES: AudioProfiles = {
+  /** Optimized for speech/voice (AI assistants, TTS, STT) */
+  speech: {
+    sampleRate: 16000,
+    channels: 1,
+    bitDepth: 16,
+  },
+
+  /** Higher quality for music playback */
+  highQuality: {
+    sampleRate: 44100,
+    channels: 2,
+    bitDepth: 16,
+  },
+
+  /** Professional audio quality */
+  studio: {
+    sampleRate: 48000,
+    channels: 2,
+    bitDepth: 16,
+  },
+
+  /** Low bandwidth (phone calls, basic voice) */
+  phone: {
+    sampleRate: 8000,
+    channels: 1,
+    bitDepth: 16,
+  },
+};
+
+// ============================================
+// AUDIO SESSION DEFAULTS
+// ============================================
+
+export const DEFAULT_SESSION_STATE: AudioSessionState = {
+  isActive: false,
+  category: 'soloAmbient',
+  mode: 'default',
+  categoryOptions: [],
+};
+
+/**
+ * Pre-configured audio session presets for common use cases.
+ */
+export const SESSION_PRESETS: SessionPresets = {
+  /** For apps that only play audio (music players, podcasts) */
+  playback: {
+    category: 'playback',
+    mode: 'default',
+    categoryOptions: [],
+    active: true,
+  },
+
+  /** For apps that only record audio */
+  record: {
+    category: 'record',
+    mode: 'default',
+    categoryOptions: [],
+    active: true,
+  },
+
+  /** For voice chat / VoIP applications */
+  voiceChat: {
+    category: 'playAndRecord',
+    mode: 'voiceChat',
+    categoryOptions: ['defaultToSpeaker', 'allowBluetooth', 'allowBluetoothA2DP'],
+    active: true,
+  },
+
+  /** For apps that mix with other audio (games with sound effects) */
+  ambient: {
+    category: 'ambient',
+    mode: 'default',
+    categoryOptions: ['mixWithOthers'],
+    active: true,
+  },
+
+  /** Default for simultaneous playback and recording (AI assistants) */
+  default: {
+    category: 'playAndRecord',
+    mode: 'default',
+    categoryOptions: ['defaultToSpeaker', 'allowBluetooth', 'allowBluetoothA2DP', 'mixWithOthers'],
+    active: true,
+  },
+};
+
+// ============================================
+// RECORDER DEFAULTS
+// ============================================
+
+export const DEFAULT_AUDIO_LEVEL: AudioLevel = {
+  current: 0,
+  peak: 0,
+  rms: 0,
+  db: -Infinity,
+};
+
+export const DEFAULT_RECORDER_STATUS: RecorderStatus = {
+  state: 'idle',
+  isRecording: false,
+  isPaused: false,
+  permission: 'undetermined',
+  duration: 0,
+  level: DEFAULT_AUDIO_LEVEL,
+  config: DEFAULT_AUDIO_CONFIG,
+};
+
+export const DEFAULT_LEVEL_UPDATE_INTERVAL = 100;
+export const DEFAULT_BUFFER_SIZE = 4096;
+
+// ============================================
+// PLAYER DEFAULTS
+// ============================================
+
+export const DEFAULT_PLAYER_STATUS: PlayerStatus = {
+  state: 'idle',
+  isPlaying: false,
+  isPaused: false,
+  duration: 0,
+  position: 0,
+  buffered: 0,
+  volume: 1.0,
+  muted: false,
+};
+
+export const DEFAULT_VOLUME = 1.0;
+export const DEFAULT_POSITION_UPDATE_INTERVAL = 100;
+export const MIN_BUFFER_THRESHOLD_MS = 100;
+
+// ============================================
+// UTILITY CONSTANTS
+// ============================================
+
+export const BIT_DEPTH_MAX_VALUES = {
+  8: 128,
+  16: 32768,
+  32: 1.0,
+} as const;

package/src/context/AudioContext.native.ts

@@ -0,0 +1,84 @@
+/**
+ * Native Audio Context Manager
+ *
+ * Manages a shared AudioContext using react-native-audio-api for both
+ * recording and playback on React Native.
+ */
+
+import { AudioContext as RNAudioContext } from 'react-native-audio-api';
+import type { IAudioContext } from '../types';
+
+class NativeAudioContextManager implements IAudioContext {
+  private context: RNAudioContext | null = null;
+  private _isInitialized = false;
+
+  get sampleRate(): number {
+    return this.context?.sampleRate ?? 44100;
+  }
+
+  get currentTime(): number {
+    return this.context?.currentTime ?? 0;
+  }
+
+  get isInitialized(): boolean {
+    return this._isInitialized && this.context !== null;
+  }
+
+  async initialize(): Promise<void> {
+    if (this.context) {
+      return;
+    }
+
+    // Create the react-native-audio-api AudioContext
+    this.context = new RNAudioContext();
+    this._isInitialized = true;
+  }
+
+  getContext(): RNAudioContext | null {
+    return this.context;
+  }
+
+  async suspend(): Promise<void> {
+    // react-native-audio-api may not support suspend directly
+    // This is a no-op for now
+  }
+
+  async resume(): Promise<void> {
+    // react-native-audio-api may not support resume directly
+    // This is a no-op for now
+  }
+
+  async close(): Promise<void> {
+    if (this.context) {
+      // Note: react-native-audio-api may not have a close method
+      // We just null out the reference
+      this.context = null;
+      this._isInitialized = false;
+    }
+  }
+}
+
+// Singleton instance
+let instance: NativeAudioContextManager | null = null;
+
+/**
+ * Get the shared AudioContext manager instance.
+ */
+export function getAudioContext(): IAudioContext {
+  if (!instance) {
+    instance = new NativeAudioContextManager();
+  }
+  return instance;
+}
+
+/**
+ * Dispose the shared AudioContext.
+ */
+export async function disposeAudioContext(): Promise<void> {
+  if (instance) {
+    await instance.close();
+    instance = null;
+  }
+}
+
+export { NativeAudioContextManager };

package/src/context/AudioContext.web.ts

@@ -0,0 +1,97 @@
+/**
+ * Web Audio Context Manager
+ *
+ * Manages a shared AudioContext for both recording and playback on web.
+ */
+
+import type { IAudioContext } from '../types';
+
+class WebAudioContextManager implements IAudioContext {
+  private context: AudioContext | null = null;
+  private _isInitialized = false;
+
+  get sampleRate(): number {
+    return this.context?.sampleRate ?? 44100;
+  }
+
+  get currentTime(): number {
+    return this.context?.currentTime ?? 0;
+  }
+
+  get isInitialized(): boolean {
+    return this._isInitialized && this.context !== null;
+  }
+
+  async initialize(): Promise<void> {
+    if (this.context) {
+      // Already initialized, just resume if suspended
+      if (this.context.state === 'suspended') {
+        await this.context.resume();
+      }
+      return;
+    }
+
+    // Create the AudioContext
+    const AudioContextClass = window.AudioContext || (window as any).webkitAudioContext;
+    if (!AudioContextClass) {
+      throw new Error('Web Audio API is not supported in this browser');
+    }
+
+    this.context = new AudioContextClass();
+    this._isInitialized = true;
+
+    // Resume if needed (some browsers require user interaction)
+    if (this.context.state === 'suspended') {
+      await this.context.resume();
+    }
+  }
+
+  getContext(): AudioContext | null {
+    return this.context;
+  }
+
+  async suspend(): Promise<void> {
+    if (this.context && this.context.state === 'running') {
+      await this.context.suspend();
+    }
+  }
+
+  async resume(): Promise<void> {
+    if (this.context && this.context.state === 'suspended') {
+      await this.context.resume();
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.context) {
+      await this.context.close();
+      this.context = null;
+      this._isInitialized = false;
+    }
+  }
+}
+
+// Singleton instance
+let instance: WebAudioContextManager | null = null;
+
+/**
+ * Get the shared AudioContext manager instance.
+ */
+export function getAudioContext(): IAudioContext {
+  if (!instance) {
+    instance = new WebAudioContextManager();
+  }
+  return instance;
+}
+
+/**
+ * Dispose the shared AudioContext.
+ */
+export async function disposeAudioContext(): Promise<void> {
+  if (instance) {
+    await instance.close();
+    instance = null;
+  }
+}
+
+export { WebAudioContextManager };

package/src/context/index.native.ts

@@ -0,0 +1 @@
+export { getAudioContext, disposeAudioContext, NativeAudioContextManager } from './AudioContext.native';

package/src/context/index.ts

@@ -0,0 +1 @@
+export { getAudioContext, disposeAudioContext, WebAudioContextManager } from './AudioContext.web';

package/src/hooks/index.ts

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

package/src/hooks/useAudio.ts

@@ -0,0 +1,129 @@
+/**
+ * useAudio Hook
+ *
+ * Provides access to the shared audio context and session management.
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import type {
+  UseAudioOptions,
+  UseAudioResult,
+  AudioSessionState,
+  AudioSessionConfig,
+} from '../types';
+import { DEFAULT_SESSION_STATE, SESSION_PRESETS } from '../constants';
+import { getAudioContext } from '../context';
+import { getAudioSessionManager } from '../session';
+
+export function useAudio(options: UseAudioOptions = {}): UseAudioResult {
+  const { session, initializeOnMount = true } = options;
+
+  const [isInitialized, setIsInitialized] = useState(false);
+  const [sessionState, setSessionState] = useState<AudioSessionState>(DEFAULT_SESSION_STATE);
+  const [outputs, setOutputs] = useState<string[]>([]);
+
+  const audioContextRef = useRef(getAudioContext());
+  const sessionManagerRef = useRef(getAudioSessionManager());
+  const mountedRef = useRef(true);
+
+  // Initialize audio context and session
+  const initialize = useCallback(async () => {
+    try {
+      const audioContext = audioContextRef.current;
+      const sessionManager = sessionManagerRef.current;
+
+      // Initialize audio context
+      if (!audioContext.isInitialized) {
+        await audioContext.initialize();
+      }
+
+      // Configure session if provided
+      if (session) {
+        await sessionManager.configure(session);
+      } else {
+        // Use default preset
+        await sessionManager.configure(SESSION_PRESETS.default);
+      }
+
+      // Activate session
+      await sessionManager.activate();
+
+      if (mountedRef.current) {
+        setIsInitialized(true);
+        setSessionState(sessionManager.state);
+        setOutputs(sessionManager.getCurrentOutputs());
+      }
+    } catch (error) {
+      console.error('Failed to initialize audio:', error);
+      throw error;
+    }
+  }, [session]);
+
+  // Configure audio session
+  const configureSession = useCallback(async (config: Partial<AudioSessionConfig>) => {
+    const sessionManager = sessionManagerRef.current;
+    await sessionManager.configure(config);
+    if (mountedRef.current) {
+      setSessionState(sessionManager.state);
+    }
+  }, []);
+
+  // Suspend audio context
+  const suspend = useCallback(async () => {
+    const audioContext = audioContextRef.current;
+    await audioContext.suspend();
+  }, []);
+
+  // Resume audio context
+  const resume = useCallback(async () => {
+    const audioContext = audioContextRef.current;
+    await audioContext.resume();
+  }, []);
+
+  // Setup on mount
+  useEffect(() => {
+    mountedRef.current = true;
+
+    if (initializeOnMount) {
+      initialize().catch(console.error);
+    }
+
+    // Subscribe to session changes
+    const sessionManager = sessionManagerRef.current;
+
+    const unsubInterruption = sessionManager.onInterruption((interruption) => {
+      if (mountedRef.current) {
+        // Handle interruption (e.g., phone call)
+        if (interruption.type === 'began') {
+          // Audio was interrupted
+          console.log('Audio session interrupted');
+        } else if (interruption.type === 'ended' && interruption.shouldResume) {
+          // Resume audio if appropriate
+          console.log('Audio session interruption ended, should resume');
+        }
+      }
+    });
+
+    const unsubRouteChange = sessionManager.onRouteChange((change) => {
+      if (mountedRef.current) {
+        setOutputs(change.currentOutputs);
+      }
+    });
+
+    return () => {
+      mountedRef.current = false;
+      unsubInterruption();
+      unsubRouteChange();
+    };
+  }, [initializeOnMount, initialize]);
+
+  return {
+    isInitialized,
+    sessionState,
+    outputs,
+    initialize,
+    configureSession,
+    suspend,
+    resume,
+  };
+}