@idealyst/audio 1.2.48

package/src/hooks/usePlayer.ts

@@ -0,0 +1,247 @@
+/**
+ * usePlayer Hook
+ *
+ * Provides audio playback functionality for files and PCM streaming.
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import type {
+  UsePlayerOptions,
+  UsePlayerResult,
+  PlayerStatus,
+  AudioError,
+  AudioConfig,
+} from '../types';
+import {
+  DEFAULT_PLAYER_STATUS,
+  DEFAULT_POSITION_UPDATE_INTERVAL,
+} from '../constants';
+import { getAudioContext } from '../context';
+import { createPlayer } from '../playback';
+
+export function usePlayer(options: UsePlayerOptions = {}): UsePlayerResult {
+  const {
+    autoPlay = false,
+    volume: initialVolume = 1.0,
+    positionUpdateInterval = DEFAULT_POSITION_UPDATE_INTERVAL,
+  } = options;
+
+  const [status, setStatus] = useState<PlayerStatus>({
+    ...DEFAULT_PLAYER_STATUS,
+    volume: initialVolume,
+  });
+
+  const audioContextRef = useRef(getAudioContext());
+  const playerRef = useRef<ReturnType<typeof createPlayer> | null>(null);
+  const mountedRef = useRef(true);
+  const autoPlayPendingRef = useRef(false);
+
+  // Initialize player lazily
+  const getPlayer = useCallback(() => {
+    if (!playerRef.current) {
+      playerRef.current = createPlayer(audioContextRef.current);
+      // Set initial volume
+      playerRef.current.setVolume(initialVolume);
+    }
+    return playerRef.current;
+  }, [initialVolume]);
+
+  // Load file
+  const loadFile = useCallback(async (uri: string) => {
+    const player = getPlayer();
+    const audioContext = audioContextRef.current;
+
+    // Ensure audio context is initialized
+    if (!audioContext.isInitialized) {
+      await audioContext.initialize();
+    }
+
+    await player.loadFile(uri);
+
+    if (autoPlay) {
+      autoPlayPendingRef.current = true;
+    }
+  }, [getPlayer, autoPlay]);
+
+  // Unload
+  const unload = useCallback(() => {
+    const player = playerRef.current;
+    if (player) {
+      player.unload();
+    }
+  }, []);
+
+  // Load PCM stream
+  const loadPCMStream = useCallback(async (config: AudioConfig) => {
+    const player = getPlayer();
+    const audioContext = audioContextRef.current;
+
+    // Ensure audio context is initialized
+    if (!audioContext.isInitialized) {
+      await audioContext.initialize();
+    }
+
+    await player.loadPCMStream(config);
+
+    if (autoPlay) {
+      autoPlayPendingRef.current = true;
+    }
+  }, [getPlayer, autoPlay]);
+
+  // Feed PCM data
+  const feedPCMData = useCallback((data: ArrayBuffer | Int16Array) => {
+    const player = playerRef.current;
+    if (player) {
+      player.feedPCMData(data);
+    }
+  }, []);
+
+  // Flush
+  const flush = useCallback(async () => {
+    const player = playerRef.current;
+    if (player) {
+      await player.flush();
+    }
+  }, []);
+
+  // Play
+  const play = useCallback(async () => {
+    const player = getPlayer();
+    await player.play();
+  }, [getPlayer]);
+
+  // Pause
+  const pause = useCallback(() => {
+    const player = playerRef.current;
+    if (player) {
+      player.pause();
+    }
+  }, []);
+
+  // Stop
+  const stop = useCallback(() => {
+    const player = playerRef.current;
+    if (player) {
+      player.stop();
+    }
+  }, []);
+
+  // Seek
+  const seek = useCallback(async (positionMs: number) => {
+    const player = playerRef.current;
+    if (player) {
+      await player.seek(positionMs);
+    }
+  }, []);
+
+  // Set volume
+  const setVolume = useCallback((vol: number) => {
+    const player = playerRef.current;
+    if (player) {
+      player.setVolume(vol);
+    }
+  }, []);
+
+  // Toggle mute
+  const toggleMute = useCallback(() => {
+    const player = playerRef.current;
+    if (player) {
+      player.setMuted(!status.muted);
+    }
+  }, [status.muted]);
+
+  // Setup on mount
+  useEffect(() => {
+    mountedRef.current = true;
+
+    const player = getPlayer();
+
+    // Subscribe to state changes
+    const unsubState = player.onStateChange((newStatus) => {
+      if (mountedRef.current) {
+        setStatus(newStatus);
+
+        // Handle autoplay
+        if (autoPlayPendingRef.current && newStatus.state === 'ready') {
+          autoPlayPendingRef.current = false;
+          player.play().catch(console.error);
+        }
+      }
+    });
+
+    // Subscribe to position updates
+    const unsubPosition = player.onPosition((position) => {
+      if (mountedRef.current) {
+        setStatus((prev) => ({ ...prev, position }));
+      }
+    }, positionUpdateInterval);
+
+    // Subscribe to buffer changes
+    const unsubBuffer = player.onBufferChange((buffered) => {
+      if (mountedRef.current) {
+        setStatus((prev) => ({ ...prev, buffered }));
+      }
+    });
+
+    // Subscribe to ended event
+    const unsubEnded = player.onEnded(() => {
+      if (mountedRef.current) {
+        // Status will be updated via onStateChange
+      }
+    });
+
+    return () => {
+      mountedRef.current = false;
+      unsubState();
+      unsubPosition();
+      unsubBuffer();
+      unsubEnded();
+
+      // Dispose player on unmount
+      if (playerRef.current) {
+        playerRef.current.dispose();
+        playerRef.current = null;
+      }
+    };
+  }, [getPlayer, positionUpdateInterval]);
+
+  // Derived state
+  const isPlaying = status.isPlaying;
+  const isPaused = status.isPaused;
+  const isLoading = status.state === 'loading';
+  const position = status.position;
+  const duration = status.duration;
+  const volume = status.volume;
+  const error = status.error || null;
+
+  return {
+    // State
+    status,
+    isPlaying,
+    isPaused,
+    isLoading,
+    position,
+    duration,
+    volume,
+    error,
+
+    // File playback
+    loadFile,
+    unload,
+
+    // PCM streaming
+    loadPCMStream,
+    feedPCMData,
+    flush,
+
+    // Playback control
+    play,
+    pause,
+    stop,
+    seek,
+
+    // Volume
+    setVolume,
+    toggleMute,
+  };
+}

package/src/hooks/useRecorder.ts

@@ -0,0 +1,176 @@
+/**
+ * useRecorder Hook
+ *
+ * Provides recording functionality with PCM data streaming.
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import type {
+  UseRecorderOptions,
+  UseRecorderResult,
+  RecorderStatus,
+  PermissionStatus,
+  AudioLevel,
+  AudioError,
+  AudioConfig,
+  RecorderDataCallback,
+} from '../types';
+import {
+  DEFAULT_RECORDER_STATUS,
+  DEFAULT_AUDIO_LEVEL,
+  DEFAULT_LEVEL_UPDATE_INTERVAL,
+} from '../constants';
+import { getAudioContext } from '../context';
+import { createRecorder } from '../recording';
+
+export function useRecorder(options: UseRecorderOptions = {}): UseRecorderResult {
+  const {
+    config,
+    autoRequestPermission = false,
+    levelUpdateInterval = DEFAULT_LEVEL_UPDATE_INTERVAL,
+  } = options;
+
+  const [status, setStatus] = useState<RecorderStatus>(DEFAULT_RECORDER_STATUS);
+
+  const audioContextRef = useRef(getAudioContext());
+  const recorderRef = useRef<ReturnType<typeof createRecorder> | null>(null);
+  const mountedRef = useRef(true);
+
+  // Initialize recorder lazily
+  const getRecorder = useCallback(() => {
+    if (!recorderRef.current) {
+      recorderRef.current = createRecorder(audioContextRef.current);
+    }
+    return recorderRef.current;
+  }, []);
+
+  // Check permission
+  const checkPermission = useCallback(async (): Promise<PermissionStatus> => {
+    const recorder = getRecorder();
+    return recorder.checkPermission();
+  }, [getRecorder]);
+
+  // Request permission
+  const requestPermission = useCallback(async (): Promise<PermissionStatus> => {
+    const recorder = getRecorder();
+    return recorder.requestPermission();
+  }, [getRecorder]);
+
+  // Start recording
+  const start = useCallback(async (startConfig?: Partial<AudioConfig>) => {
+    const recorder = getRecorder();
+    const audioContext = audioContextRef.current;
+
+    // Ensure audio context is initialized
+    if (!audioContext.isInitialized) {
+      await audioContext.initialize();
+    }
+
+    await recorder.start(startConfig || config);
+  }, [getRecorder, config]);
+
+  // Stop recording
+  const stop = useCallback(async () => {
+    const recorder = getRecorder();
+    await recorder.stop();
+  }, [getRecorder]);
+
+  // Pause recording
+  const pause = useCallback(async () => {
+    const recorder = getRecorder();
+    await recorder.pause();
+  }, [getRecorder]);
+
+  // Resume recording
+  const resume = useCallback(async () => {
+    const recorder = getRecorder();
+    await recorder.resume();
+  }, [getRecorder]);
+
+  // Subscribe to data
+  const subscribeToData = useCallback((callback: RecorderDataCallback): (() => void) => {
+    const recorder = getRecorder();
+    return recorder.onData(callback);
+  }, [getRecorder]);
+
+  // Reset peak level
+  const resetPeakLevel = useCallback(() => {
+    const recorder = recorderRef.current;
+    if (recorder) {
+      recorder.resetPeakLevel();
+    }
+  }, []);
+
+  // Setup on mount
+  useEffect(() => {
+    mountedRef.current = true;
+
+    const recorder = getRecorder();
+
+    // Subscribe to state changes
+    const unsubState = recorder.onStateChange((newStatus) => {
+      if (mountedRef.current) {
+        setStatus(newStatus);
+      }
+    });
+
+    // Subscribe to level updates
+    const unsubLevel = recorder.onLevel((level) => {
+      if (mountedRef.current) {
+        setStatus((prev) => ({ ...prev, level }));
+      }
+    }, levelUpdateInterval);
+
+    // Auto request permission if enabled
+    if (autoRequestPermission) {
+      requestPermission().catch(console.error);
+    }
+
+    return () => {
+      mountedRef.current = false;
+      unsubState();
+      unsubLevel();
+
+      // Dispose recorder on unmount
+      if (recorderRef.current) {
+        recorderRef.current.dispose();
+        recorderRef.current = null;
+      }
+    };
+  }, [getRecorder, autoRequestPermission, requestPermission, levelUpdateInterval]);
+
+  // Derived state
+  const isRecording = status.isRecording;
+  const isPaused = status.isPaused;
+  const permission = status.permission;
+  const duration = status.duration;
+  const level = status.level;
+  const error = status.error || null;
+
+  return {
+    // State
+    status,
+    isRecording,
+    isPaused,
+    permission,
+    duration,
+    level,
+    error,
+
+    // Actions
+    start,
+    stop,
+    pause,
+    resume,
+
+    // Permissions
+    checkPermission,
+    requestPermission,
+
+    // Data subscription
+    subscribeToData,
+
+    // Utilities
+    resetPeakLevel,
+  };
+}

package/src/index.native.ts

@@ -0,0 +1,114 @@
+/**
+ * @idealyst/audio
+ *
+ * Unified audio package for recording and playback on web and native.
+ * Native implementation using react-native-audio-api.
+ */
+
+// Types
+export type {
+  // Audio configuration
+  SampleRate,
+  BitDepth,
+  ChannelCount,
+  AudioConfig,
+
+  // Audio session (native)
+  AudioSessionCategory,
+  AudioSessionCategoryOption,
+  AudioSessionMode,
+  AudioSessionConfig,
+  AudioSessionState,
+  AudioSessionInterruption,
+  AudioSessionRouteChange,
+
+  // PCM data
+  PCMData,
+  AudioLevel,
+
+  // Recorder
+  RecorderState,
+  PermissionStatus,
+  RecorderStatus,
+  RecorderDataCallback,
+  RecorderLevelCallback,
+  RecorderStateCallback,
+  IRecorder,
+
+  // Player
+  PlayerState,
+  PlayerStatus,
+  PlayerStateCallback,
+  PlayerPositionCallback,
+  PlayerBufferCallback,
+  PlayerEndedCallback,
+  IPlayer,
+
+  // Audio context
+  IAudioContext,
+  IAudioSessionManager,
+
+  // Errors
+  AudioErrorCode,
+  AudioError,
+
+  // Hook types
+  UseAudioOptions,
+  UseAudioResult,
+  UseRecorderOptions,
+  UseRecorderResult,
+  UsePlayerOptions,
+  UsePlayerResult,
+
+  // Presets
+  AudioProfiles,
+  SessionPresets,
+} from './types';
+
+// Constants
+export {
+  // Audio profiles
+  AUDIO_PROFILES,
+
+  // Session presets
+  SESSION_PRESETS,
+
+  // Defaults
+  DEFAULT_AUDIO_CONFIG,
+  DEFAULT_AUDIO_LEVEL,
+  DEFAULT_RECORDER_STATUS,
+  DEFAULT_PLAYER_STATUS,
+  DEFAULT_SESSION_STATE,
+  DEFAULT_LEVEL_UPDATE_INTERVAL,
+  DEFAULT_POSITION_UPDATE_INTERVAL,
+} from './constants';
+
+// Context (native)
+export { getAudioContext, NativeAudioContextManager } from './context/index.native';
+
+// Session (native)
+export { getAudioSessionManager, NativeAudioSessionManager } from './session/index.native';
+
+// Recording (native)
+export { createRecorder, NativeRecorder } from './recording/index.native';
+
+// Playback (native)
+export { createPlayer, NativePlayer } from './playback/index.native';
+
+// Hooks
+export { useAudio, useRecorder, usePlayer } from './hooks';
+
+// Utilities
+export {
+  createAudioError,
+  pcmToFloat32,
+  float32ToInt16,
+  resampleLinear,
+  calculateAudioLevels,
+  clamp,
+  durationToSamples,
+  samplesToDuration,
+  createWavHeader,
+  arrayBufferToBase64,
+  base64ToArrayBuffer,
+} from './utils';

package/src/index.ts

@@ -0,0 +1,114 @@
+/**
+ * @idealyst/audio
+ *
+ * Unified audio package for recording and playback on web and native.
+ * Web implementation using Web Audio API.
+ */
+
+// Types
+export type {
+  // Audio configuration
+  SampleRate,
+  BitDepth,
+  ChannelCount,
+  AudioConfig,
+
+  // Audio session (native)
+  AudioSessionCategory,
+  AudioSessionCategoryOption,
+  AudioSessionMode,
+  AudioSessionConfig,
+  AudioSessionState,
+  AudioSessionInterruption,
+  AudioSessionRouteChange,
+
+  // PCM data
+  PCMData,
+  AudioLevel,
+
+  // Recorder
+  RecorderState,
+  PermissionStatus,
+  RecorderStatus,
+  RecorderDataCallback,
+  RecorderLevelCallback,
+  RecorderStateCallback,
+  IRecorder,
+
+  // Player
+  PlayerState,
+  PlayerStatus,
+  PlayerStateCallback,
+  PlayerPositionCallback,
+  PlayerBufferCallback,
+  PlayerEndedCallback,
+  IPlayer,
+
+  // Audio context
+  IAudioContext,
+  IAudioSessionManager,
+
+  // Errors
+  AudioErrorCode,
+  AudioError,
+
+  // Hook types
+  UseAudioOptions,
+  UseAudioResult,
+  UseRecorderOptions,
+  UseRecorderResult,
+  UsePlayerOptions,
+  UsePlayerResult,
+
+  // Presets
+  AudioProfiles,
+  SessionPresets,
+} from './types';
+
+// Constants
+export {
+  // Audio profiles
+  AUDIO_PROFILES,
+
+  // Session presets
+  SESSION_PRESETS,
+
+  // Defaults
+  DEFAULT_AUDIO_CONFIG,
+  DEFAULT_AUDIO_LEVEL,
+  DEFAULT_RECORDER_STATUS,
+  DEFAULT_PLAYER_STATUS,
+  DEFAULT_SESSION_STATE,
+  DEFAULT_LEVEL_UPDATE_INTERVAL,
+  DEFAULT_POSITION_UPDATE_INTERVAL,
+} from './constants';
+
+// Context
+export { getAudioContext, WebAudioContextManager } from './context';
+
+// Session
+export { getAudioSessionManager, WebAudioSessionManager } from './session';
+
+// Recording
+export { createRecorder, WebRecorder } from './recording';
+
+// Playback
+export { createPlayer, WebPlayer } from './playback';
+
+// Hooks
+export { useAudio, useRecorder, usePlayer } from './hooks';
+
+// Utilities
+export {
+  createAudioError,
+  pcmToFloat32,
+  float32ToInt16,
+  resampleLinear,
+  calculateAudioLevels,
+  clamp,
+  durationToSamples,
+  samplesToDuration,
+  createWavHeader,
+  arrayBufferToBase64,
+  base64ToArrayBuffer,
+} from './utils';

package/src/index.web.ts

@@ -0,0 +1,8 @@
+/**
+ * @idealyst/audio
+ *
+ * Unified audio package for recording and playback on web and native.
+ * Explicit web export.
+ */
+
+export * from './index';