@idealyst/microphone 1.1.2

package/README.md

@@ -0,0 +1,225 @@
+# @idealyst/microphone
+
+Cross-platform microphone streaming library for React and React Native. Provides low-level access to raw PCM audio samples for real-time processing, speech recognition, audio visualization, and file recording.
+
+## Installation
+
+```bash
+# npm
+npm install @idealyst/microphone
+
+# yarn
+yarn add @idealyst/microphone
+```
+
+### React Native Setup
+
+For React Native, you also need to install the native audio streaming library:
+
+```bash
+yarn add react-native-live-audio-stream
+```
+
+#### iOS
+
+```bash
+cd ios && pod install
+```
+
+Add microphone permission to `Info.plist`:
+
+```xml
+<key>NSMicrophoneUsageDescription</key>
+<string>This app needs access to your microphone to record audio.</string>
+```
+
+#### Android
+
+Add permission to `AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+```
+
+## Quick Start
+
+### Streaming Audio Data
+
+```tsx
+import { useMicrophone, AUDIO_PROFILES } from '@idealyst/microphone';
+
+function VoiceInput() {
+  const {
+    isRecording,
+    level,
+    start,
+    stop,
+    subscribeToAudioData
+  } = useMicrophone({
+    config: AUDIO_PROFILES.speech,
+    autoRequestPermission: true,
+  });
+
+  useEffect(() => {
+    if (!isRecording) return;
+
+    return subscribeToAudioData((pcmData) => {
+      // Process raw PCM samples
+      console.log('Got', pcmData.samples.length, 'samples');
+
+      // Send to speech recognition API
+      sendToWhisperAPI(pcmData.buffer);
+    });
+  }, [isRecording, subscribeToAudioData]);
+
+  return (
+    <View>
+      <Button onPress={isRecording ? stop : start}>
+        {isRecording ? 'Stop' : 'Start'}
+      </Button>
+      <Text>Level: {Math.round(level.current * 100)}%</Text>
+    </View>
+  );
+}
+```
+
+### Recording to File
+
+```tsx
+import { useRecorder } from '@idealyst/microphone';
+
+function AudioRecorder() {
+  const { isRecording, duration, startRecording, stopRecording } = useRecorder();
+
+  const handleStop = async () => {
+    const result = await stopRecording();
+
+    // Get ArrayBuffer for upload
+    const data = await result.getArrayBuffer();
+    await uploadAudio(data);
+  };
+
+  return (
+    <View>
+      <Text>Duration: {Math.floor(duration / 1000)}s</Text>
+      <Button onPress={isRecording ? handleStop : () => startRecording()}>
+        {isRecording ? 'Stop' : 'Record'}
+      </Button>
+    </View>
+  );
+}
+```
+
+## Audio Profiles
+
+Pre-configured profiles for common use cases:
+
+```typescript
+import { AUDIO_PROFILES } from '@idealyst/microphone';
+
+// Speech recognition (Whisper, Google STT, etc.)
+AUDIO_PROFILES.speech     // 16kHz mono 16-bit
+
+// Music and high-quality audio
+AUDIO_PROFILES.highQuality // 44.1kHz stereo 16-bit
+
+// Real-time feedback with minimal latency
+AUDIO_PROFILES.lowLatency  // 16kHz mono, 256 buffer
+
+// Minimal bandwidth for voice calls
+AUDIO_PROFILES.minimal     // 8kHz mono 8-bit
+```
+
+## API Reference
+
+### useMicrophone Hook
+
+```typescript
+const {
+  // State
+  status,          // Full MicrophoneStatus object
+  isRecording,     // boolean
+  isPaused,        // boolean (native only)
+  level,           // AudioLevel { current, peak, rms, db }
+  error,           // MicrophoneError | null
+  permission,      // PermissionStatus
+
+  // Actions
+  start,           // (config?) => Promise<void>
+  stop,            // () => Promise<void>
+  pause,           // () => Promise<void> (native only)
+  resume,          // () => Promise<void> (native only)
+  requestPermission, // () => Promise<PermissionResult>
+  resetPeakLevel,  // () => void
+
+  // Data subscription
+  subscribeToAudioData, // (callback) => unsubscribe
+} = useMicrophone(options);
+```
+
+### useRecorder Hook
+
+```typescript
+const {
+  isRecording,     // boolean
+  duration,        // number (ms)
+  error,           // MicrophoneError | null
+
+  startRecording,  // (options?) => Promise<void>
+  stopRecording,   // () => Promise<RecordingResult>
+  cancelRecording, // () => Promise<void>
+} = useRecorder(options);
+```
+
+### PCMData Type
+
+```typescript
+interface PCMData {
+  buffer: ArrayBuffer;      // Raw PCM data
+  samples: TypedArray;      // Int8Array | Int16Array | Float32Array
+  timestamp: number;        // Capture time (ms since epoch)
+  config: AudioConfig;      // Audio configuration
+}
+```
+
+### AudioLevel Type
+
+```typescript
+interface AudioLevel {
+  current: number;  // 0.0 - 1.0
+  peak: number;     // 0.0 - 1.0 (since last reset)
+  rms: number;      // Root mean square
+  db: number;       // Decibels (-Infinity to 0)
+}
+```
+
+### RecordingResult Type
+
+```typescript
+interface RecordingResult {
+  uri: string;                    // Blob URL (web) or data URI (native)
+  duration: number;               // Duration in ms
+  size: number;                   // File size in bytes
+  config: AudioConfig;            // Audio config used
+  format: 'wav' | 'raw';          // Recording format
+
+  getArrayBuffer(): Promise<ArrayBuffer>;  // For upload/processing
+  getData(): Promise<Blob | string>;       // Blob (web) or base64 (native)
+}
+```
+
+## Platform Notes
+
+### Web
+- Uses Web Audio API with AudioWorklet for low-latency processing
+- Float32 samples internally, converted to requested bit depth
+- Pause is not supported (stops the stream)
+
+### React Native
+- Uses `react-native-live-audio-stream` for audio capture
+- 32-bit float not supported (falls back to 16-bit)
+- Pause/resume supported on native
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@idealyst/microphone",
+  "version": "1.1.2",
+  "description": "Cross-platform microphone streaming for React and React Native",
+  "documentation": "https://github.com/IdealystIO/idealyst-framework/tree/main/packages/microphone#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/microphone"
+  },
+  "author": "Your Name <your.email@example.com>",
+  "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-live-audio-stream": ">=1.1.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    },
+    "react-native-live-audio-stream": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.0",
+    "@types/react-native": "^0.73.0",
+    "react-native-live-audio-stream": "^1.1.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "react",
+    "react-native",
+    "microphone",
+    "audio",
+    "pcm",
+    "streaming",
+    "recording",
+    "cross-platform"
+  ]
+}

package/src/constants.ts

@@ -0,0 +1,73 @@
+import type {
+  AudioConfig,
+  SampleRate,
+  BitDepth,
+  ChannelCount,
+  AudioLevel,
+} from './types';
+
+export const DEFAULT_AUDIO_CONFIG: AudioConfig = {
+  sampleRate: 16000, // Optimal for speech recognition
+  channels: 1, // Mono
+  bitDepth: 16, // Standard CD quality per sample
+  bufferSize: 4096, // Balance between latency and CPU
+};
+
+export const DEFAULT_AUDIO_LEVEL: AudioLevel = {
+  current: 0,
+  peak: 0,
+  rms: 0,
+  db: -Infinity,
+};
+
+/**
+ * Pre-configured audio profiles for common use cases.
+ */
+export const AUDIO_PROFILES = {
+  /** Optimized for speech recognition (Whisper, Google STT, etc.) */
+  speech: {
+    sampleRate: 16000 as SampleRate,
+    channels: 1 as ChannelCount,
+    bitDepth: 16 as BitDepth,
+    bufferSize: 4096,
+  } satisfies AudioConfig,
+
+  /** Higher quality for music/audio visualization */
+  highQuality: {
+    sampleRate: 44100 as SampleRate,
+    channels: 2 as ChannelCount,
+    bitDepth: 16 as BitDepth,
+    bufferSize: 2048,
+  } satisfies AudioConfig,
+
+  /** Low latency for real-time feedback */
+  lowLatency: {
+    sampleRate: 16000 as SampleRate,
+    channels: 1 as ChannelCount,
+    bitDepth: 16 as BitDepth,
+    bufferSize: 256,
+  } satisfies AudioConfig,
+
+  /** Minimal bandwidth (voice calls, basic recording) */
+  minimal: {
+    sampleRate: 8000 as SampleRate,
+    channels: 1 as ChannelCount,
+    bitDepth: 8 as BitDepth,
+    bufferSize: 4096,
+  } satisfies AudioConfig,
+} as const;
+
+/**
+ * Maximum values for different bit depths.
+ * Used for normalization calculations.
+ */
+export const BIT_DEPTH_MAX_VALUES = {
+  8: 128,
+  16: 32768,
+  32: 1.0,
+} as const;
+
+/**
+ * Default level update interval in milliseconds.
+ */
+export const DEFAULT_LEVEL_UPDATE_INTERVAL = 100;

package/src/hooks/createUseMicrophoneHook.ts

@@ -0,0 +1,144 @@
+import { useState, useCallback, useEffect, useRef } from 'react';
+import type {
+  UseMicrophoneOptions,
+  UseMicrophoneResult,
+  AudioDataCallback,
+  MicrophoneStatus,
+  MicrophoneError,
+  AudioLevel,
+  PermissionResult,
+  AudioConfig,
+  IMicrophone,
+} from '../types';
+import { DEFAULT_AUDIO_CONFIG, DEFAULT_AUDIO_LEVEL } from '../constants';
+
+/**
+ * Factory function type for creating platform-specific microphone instances.
+ */
+export type CreateMicrophoneFactory = () => IMicrophone;
+
+/**
+ * Create the useMicrophone hook with a platform-specific factory.
+ */
+export function createUseMicrophoneHook(
+  createMicrophone: CreateMicrophoneFactory
+) {
+  return function useMicrophone(
+    options: UseMicrophoneOptions = {}
+  ): UseMicrophoneResult {
+    const {
+      config = {},
+      autoRequestPermission = false,
+      levelUpdateInterval = 100,
+    } = options;
+
+    const microphoneRef = useRef<IMicrophone | null>(null);
+    const configRef = useRef<Partial<AudioConfig>>(config);
+
+    // Update config ref when it changes
+    useEffect(() => {
+      configRef.current = config;
+    }, [config]);
+
+    const [status, setStatus] = useState<MicrophoneStatus>({
+      state: 'idle',
+      permission: 'undetermined',
+      isRecording: false,
+      duration: 0,
+      level: DEFAULT_AUDIO_LEVEL,
+      config: { ...DEFAULT_AUDIO_CONFIG, ...config },
+    });
+
+    const [level, setLevel] = useState<AudioLevel>(DEFAULT_AUDIO_LEVEL);
+    const [error, setError] = useState<MicrophoneError | null>(null);
+
+    // Initialize microphone instance
+    useEffect(() => {
+      const mic = createMicrophone();
+      microphoneRef.current = mic;
+
+      const unsubscribeState = mic.onStateChange((newStatus) => {
+        setStatus(newStatus);
+        if (newStatus.error) {
+          setError(newStatus.error);
+        }
+      });
+
+      const unsubscribeLevel = mic.onAudioLevel((newLevel) => {
+        setLevel(newLevel);
+      }, levelUpdateInterval);
+
+      const unsubscribeError = mic.onError((err) => {
+        setError(err);
+      });
+
+      // Check or request permission on mount
+      if (autoRequestPermission) {
+        mic.requestPermission().catch(() => {});
+      } else {
+        mic.checkPermission().catch(() => {});
+      }
+
+      return () => {
+        unsubscribeState();
+        unsubscribeLevel();
+        unsubscribeError();
+        mic.dispose();
+        microphoneRef.current = null;
+      };
+    }, [autoRequestPermission, levelUpdateInterval]);
+
+    const start = useCallback(
+      async (overrideConfig?: Partial<AudioConfig>) => {
+        setError(null);
+        const finalConfig = { ...configRef.current, ...overrideConfig };
+        await microphoneRef.current?.start(finalConfig);
+      },
+      []
+    );
+
+    const stop = useCallback(async () => {
+      await microphoneRef.current?.stop();
+    }, []);
+
+    const pause = useCallback(async () => {
+      await microphoneRef.current?.pause();
+    }, []);
+
+    const resume = useCallback(async () => {
+      await microphoneRef.current?.resume();
+    }, []);
+
+    const requestPermission = useCallback(async (): Promise<PermissionResult> => {
+      const result = await microphoneRef.current?.requestPermission();
+      return result ?? { status: 'unavailable', canAskAgain: false };
+    }, []);
+
+    const resetPeakLevel = useCallback(() => {
+      microphoneRef.current?.resetPeakLevel();
+    }, []);
+
+    const subscribeToAudioData = useCallback(
+      (callback: AudioDataCallback): (() => void) => {
+        return microphoneRef.current?.onAudioData(callback) ?? (() => {});
+      },
+      []
+    );
+
+    return {
+      status,
+      isRecording: status.isRecording,
+      isPaused: status.state === 'paused',
+      level,
+      error,
+      permission: status.permission,
+      start,
+      stop,
+      pause,
+      resume,
+      requestPermission,
+      resetPeakLevel,
+      subscribeToAudioData,
+    };
+  };
+}

package/src/hooks/createUseRecorderHook.ts

@@ -0,0 +1,101 @@
+import { useState, useCallback, useRef, useEffect } from 'react';
+import type {
+  UseRecorderOptions,
+  UseRecorderResult,
+  RecordingOptions,
+  RecordingResult,
+  MicrophoneError,
+  IRecorder,
+} from '../types';
+
+/**
+ * Factory function type for creating platform-specific recorder instances.
+ */
+export type CreateRecorderFactory = () => IRecorder;
+
+/**
+ * Create the useRecorder hook with a platform-specific factory.
+ */
+export function createUseRecorderHook(createRecorder: CreateRecorderFactory) {
+  return function useRecorder(
+    options: UseRecorderOptions = {}
+  ): UseRecorderResult {
+    const recorderRef = useRef<IRecorder | null>(null);
+    const optionsRef = useRef<RecordingOptions | undefined>(options.options);
+
+    // Update options ref when it changes
+    useEffect(() => {
+      optionsRef.current = options.options;
+    }, [options.options]);
+
+    const [isRecording, setIsRecording] = useState(false);
+    const [duration, setDuration] = useState(0);
+    const [error, setError] = useState<MicrophoneError | null>(null);
+
+    // Initialize recorder instance
+    useEffect(() => {
+      recorderRef.current = createRecorder();
+
+      return () => {
+        recorderRef.current?.dispose();
+        recorderRef.current = null;
+      };
+    }, []);
+
+    // Duration tracking
+    useEffect(() => {
+      if (!isRecording) {
+        return;
+      }
+
+      const interval = setInterval(() => {
+        if (recorderRef.current) {
+          setDuration(recorderRef.current.duration);
+        }
+      }, 100);
+
+      return () => clearInterval(interval);
+    }, [isRecording]);
+
+    const startRecording = useCallback(
+      async (overrideOptions?: RecordingOptions) => {
+        try {
+          setError(null);
+          const finalOptions = overrideOptions ?? optionsRef.current;
+          await recorderRef.current?.startRecording(finalOptions);
+          setIsRecording(true);
+          setDuration(0);
+        } catch (e) {
+          const err = e as MicrophoneError;
+          setError(err);
+          throw err;
+        }
+      },
+      []
+    );
+
+    const stopRecording = useCallback(async (): Promise<RecordingResult> => {
+      const result = await recorderRef.current?.stopRecording();
+      setIsRecording(false);
+      if (!result) {
+        throw new Error('No recording result');
+      }
+      return result;
+    }, []);
+
+    const cancelRecording = useCallback(async () => {
+      await recorderRef.current?.cancelRecording();
+      setIsRecording(false);
+      setDuration(0);
+    }, []);
+
+    return {
+      isRecording,
+      duration,
+      error,
+      startRecording,
+      stopRecording,
+      cancelRecording,
+    };
+  };
+}

package/src/hooks/index.native.ts

@@ -0,0 +1,2 @@
+export { useMicrophone } from './useMicrophone.native';
+export { useRecorder } from './useRecorder.native';

package/src/hooks/index.ts

@@ -0,0 +1,2 @@
+export { useMicrophone } from './useMicrophone.web';
+export { useRecorder } from './useRecorder.web';

package/src/hooks/index.web.ts

@@ -0,0 +1,2 @@
+export { useMicrophone } from './useMicrophone.web';
+export { useRecorder } from './useRecorder.web';

package/src/hooks/useMicrophone.native.ts

@@ -0,0 +1,45 @@
+import { createUseMicrophoneHook } from './createUseMicrophoneHook';
+import { createMicrophone } from '../microphone.native';
+
+/**
+ * React hook for microphone access on React Native platforms.
+ *
+ * @example
+ * ```tsx
+ * import { useMicrophone, AUDIO_PROFILES } from '@idealyst/microphone';
+ * import { View, Button, Text } from 'react-native';
+ *
+ * function VoiceInput() {
+ *   const {
+ *     isRecording,
+ *     level,
+ *     start,
+ *     stop,
+ *     subscribeToAudioData
+ *   } = useMicrophone({
+ *     config: AUDIO_PROFILES.speech,
+ *     autoRequestPermission: true,
+ *   });
+ *
+ *   useEffect(() => {
+ *     if (!isRecording) return;
+ *
+ *     return subscribeToAudioData((pcmData) => {
+ *       // Process audio data
+ *       console.log('Got', pcmData.samples.length, 'samples');
+ *     });
+ *   }, [isRecording, subscribeToAudioData]);
+ *
+ *   return (
+ *     <View>
+ *       <Button
+ *         title={isRecording ? 'Stop' : 'Start'}
+ *         onPress={isRecording ? stop : start}
+ *       />
+ *       <Text>Level: {Math.round(level.current * 100)}%</Text>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export const useMicrophone = createUseMicrophoneHook(createMicrophone);