@idealyst/microphone 1.1.2

package/src/types.ts

@@ -0,0 +1,316 @@
+// ============================================
+// AUDIO CONFIGURATION
+// ============================================
+
+export type SampleRate = 8000 | 16000 | 22050 | 44100 | 48000;
+export type BitDepth = 8 | 16 | 32;
+export type ChannelCount = 1 | 2;
+
+export interface AudioConfig {
+  /** Sample rate in Hz. Default: 16000 (speech-optimized) */
+  sampleRate: SampleRate;
+
+  /** Number of audio channels. Default: 1 (mono) */
+  channels: ChannelCount;
+
+  /** Bits per sample. Default: 16 */
+  bitDepth: BitDepth;
+
+  /**
+   * Buffer size for audio processing (samples per callback).
+   * Lower = more responsive, higher CPU. Higher = less CPU, more latency.
+   * Web: Must be power of 2 (256, 512, 1024, 2048, 4096).
+   * Native: Approximate target, actual may vary.
+   * Default: 4096
+   */
+  bufferSize: number;
+}
+
+// ============================================
+// PCM DATA TYPES
+// ============================================
+
+export interface PCMData {
+  /** Raw PCM samples as ArrayBuffer */
+  buffer: ArrayBuffer;
+
+  /** TypedArray view for easy sample access based on bit depth */
+  samples: Int8Array | Int16Array | Float32Array;
+
+  /** Timestamp when this buffer was captured (ms since epoch) */
+  timestamp: number;
+
+  /** Audio configuration this data was captured with */
+  config: AudioConfig;
+}
+
+export interface AudioLevel {
+  /** Current audio level (0.0 - 1.0, normalized) */
+  current: number;
+
+  /** Peak audio level since last reset (0.0 - 1.0) */
+  peak: number;
+
+  /** RMS (root mean square) level for more accurate metering */
+  rms: number;
+
+  /** Decibel value (-Infinity to 0) */
+  db: number;
+}
+
+// ============================================
+// PERMISSION TYPES
+// ============================================
+
+export type PermissionStatus =
+  | 'granted'
+  | 'denied'
+  | 'undetermined'
+  | 'blocked' // User denied and "don't ask again" on native
+  | 'unavailable'; // No microphone hardware/not supported
+
+export interface PermissionResult {
+  status: PermissionStatus;
+  canAskAgain: boolean;
+}
+
+// ============================================
+// MICROPHONE STATE
+// ============================================
+
+export type MicrophoneState =
+  | 'idle' // Not started
+  | 'starting' // Initializing
+  | 'recording' // Actively capturing
+  | 'paused' // Paused (native only - web must stop/start)
+  | 'stopping' // Cleaning up
+  | 'error'; // Error state
+
+export interface MicrophoneStatus {
+  state: MicrophoneState;
+
+  /** Current permission status */
+  permission: PermissionStatus;
+
+  /** Whether recording is active */
+  isRecording: boolean;
+
+  /** Duration of current recording session in milliseconds */
+  duration: number;
+
+  /** Current audio level metrics */
+  level: AudioLevel;
+
+  /** Error if state is 'error' */
+  error?: MicrophoneError;
+
+  /** Current audio configuration */
+  config: AudioConfig;
+}
+
+// ============================================
+// ERROR HANDLING
+// ============================================
+
+export type MicrophoneErrorCode =
+  | 'PERMISSION_DENIED'
+  | 'PERMISSION_BLOCKED'
+  | 'DEVICE_NOT_FOUND'
+  | 'DEVICE_IN_USE'
+  | 'NOT_SUPPORTED'
+  | 'INITIALIZATION_FAILED'
+  | 'RECORDING_FAILED'
+  | 'INVALID_CONFIG'
+  | 'UNKNOWN';
+
+export interface MicrophoneError {
+  code: MicrophoneErrorCode;
+  message: string;
+  originalError?: Error;
+}
+
+// ============================================
+// CALLBACK TYPES
+// ============================================
+
+export type AudioDataCallback = (data: PCMData) => void;
+export type AudioLevelCallback = (level: AudioLevel) => void;
+export type StateChangeCallback = (status: MicrophoneStatus) => void;
+export type ErrorCallback = (error: MicrophoneError) => void;
+
+// ============================================
+// MICROPHONE INTERFACE
+// ============================================
+
+export interface IMicrophone {
+  /** Current status */
+  readonly status: MicrophoneStatus;
+
+  /** Check microphone permission status */
+  checkPermission(): Promise<PermissionResult>;
+
+  /** Request microphone permission */
+  requestPermission(): Promise<PermissionResult>;
+
+  /**
+   * Start recording/streaming audio.
+   * @param config Optional audio configuration (uses defaults if not provided)
+   */
+  start(config?: Partial<AudioConfig>): Promise<void>;
+
+  /** Stop recording/streaming */
+  stop(): Promise<void>;
+
+  /**
+   * Pause recording (native only).
+   * On web, this will stop - use start() to resume.
+   */
+  pause(): Promise<void>;
+
+  /** Resume recording after pause (native only) */
+  resume(): Promise<void>;
+
+  /**
+   * Subscribe to PCM audio data chunks.
+   * @returns Unsubscribe function
+   */
+  onAudioData(callback: AudioDataCallback): () => void;
+
+  /**
+   * Subscribe to audio level updates (for visualization).
+   * @param intervalMs Update interval in milliseconds. Default: 100
+   * @returns Unsubscribe function
+   */
+  onAudioLevel(callback: AudioLevelCallback, intervalMs?: number): () => void;
+
+  /**
+   * Subscribe to state changes.
+   * @returns Unsubscribe function
+   */
+  onStateChange(callback: StateChangeCallback): () => void;
+
+  /**
+   * Subscribe to errors.
+   * @returns Unsubscribe function
+   */
+  onError(callback: ErrorCallback): () => void;
+
+  /** Reset peak level meter */
+  resetPeakLevel(): void;
+
+  /** Clean up resources */
+  dispose(): void;
+}
+
+// ============================================
+// RECORDER INTERFACE (File Recording)
+// ============================================
+
+export type RecordingFormat = 'wav' | 'raw';
+
+export interface RecordingOptions {
+  /** Output format. Default: 'wav' */
+  format: RecordingFormat;
+
+  /** Audio configuration */
+  audioConfig?: Partial<AudioConfig>;
+
+  /** Maximum recording duration in seconds. 0 = unlimited */
+  maxDuration?: number;
+}
+
+export interface RecordingResult {
+  /** File path (native) or Blob URL (web) */
+  uri: string;
+
+  /** Duration in milliseconds */
+  duration: number;
+
+  /** File size in bytes */
+  size: number;
+
+  /** Audio configuration used */
+  config: AudioConfig;
+
+  /** Format of the recording */
+  format: RecordingFormat;
+
+  /** Get the recording as ArrayBuffer (for upload, processing, etc.) */
+  getArrayBuffer(): Promise<ArrayBuffer>;
+
+  /** Get the recording as Blob (web) or base64 string (native) */
+  getData(): Promise<Blob | string>;
+}
+
+export interface IRecorder {
+  /** Whether currently recording to file */
+  readonly isRecording: boolean;
+
+  /** Current recording duration in milliseconds */
+  readonly duration: number;
+
+  /** Start recording to file */
+  startRecording(options?: RecordingOptions): Promise<void>;
+
+  /** Stop recording and get result */
+  stopRecording(): Promise<RecordingResult>;
+
+  /** Cancel recording without saving */
+  cancelRecording(): Promise<void>;
+
+  /** Clean up resources */
+  dispose(): void;
+}
+
+// ============================================
+// HOOK TYPES
+// ============================================
+
+export interface UseMicrophoneOptions {
+  /** Audio configuration */
+  config?: Partial<AudioConfig>;
+
+  /** Auto-request permission on mount. Default: false */
+  autoRequestPermission?: boolean;
+
+  /** Audio level update interval in ms. Default: 100 */
+  levelUpdateInterval?: number;
+}
+
+export interface UseMicrophoneResult {
+  // State
+  status: MicrophoneStatus;
+  isRecording: boolean;
+  isPaused: boolean;
+  level: AudioLevel;
+  error: MicrophoneError | null;
+  permission: PermissionStatus;
+
+  // Actions
+  start: (config?: Partial<AudioConfig>) => Promise<void>;
+  stop: () => Promise<void>;
+  pause: () => Promise<void>;
+  resume: () => Promise<void>;
+  requestPermission: () => Promise<PermissionResult>;
+  resetPeakLevel: () => void;
+
+  // Data subscription (for custom processing)
+  subscribeToAudioData: (callback: AudioDataCallback) => () => void;
+}
+
+export interface UseRecorderOptions {
+  /** Recording options */
+  options?: RecordingOptions;
+}
+
+export interface UseRecorderResult {
+  // State
+  isRecording: boolean;
+  duration: number;
+  error: MicrophoneError | null;
+
+  // Actions
+  startRecording: (options?: RecordingOptions) => Promise<void>;
+  stopRecording: () => Promise<RecordingResult>;
+  cancelRecording: () => Promise<void>;
+}

package/src/utils.ts

@@ -0,0 +1,217 @@
+import type { AudioConfig, AudioLevel, BitDepth } from './types';
+import { BIT_DEPTH_MAX_VALUES } from './constants';
+
+/**
+ * Decode Base64 string to ArrayBuffer.
+ * Works in both web and React Native environments.
+ */
+export function base64ToArrayBuffer(base64: string): ArrayBuffer {
+  // Use atob for web, Buffer for React Native
+  const binaryString =
+    typeof atob !== 'undefined'
+      ? atob(base64)
+      : Buffer.from(base64, 'base64').toString('binary');
+
+  const bytes = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+
+/**
+ * Encode ArrayBuffer to Base64 string.
+ * Works in both web and React Native environments.
+ */
+export function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return typeof btoa !== 'undefined'
+    ? btoa(binary)
+    : Buffer.from(binary, 'binary').toString('base64');
+}
+
+/**
+ * Create appropriate TypedArray for PCM data based on bit depth.
+ */
+export function createPCMTypedArray(
+  buffer: ArrayBuffer,
+  bitDepth: BitDepth
+): Int8Array | Int16Array | Float32Array {
+  switch (bitDepth) {
+    case 8:
+      return new Int8Array(buffer);
+    case 16:
+      return new Int16Array(buffer);
+    case 32:
+      return new Float32Array(buffer);
+    default:
+      return new Int16Array(buffer);
+  }
+}
+
+/**
+ * Calculate audio levels from PCM samples.
+ * @param samples - PCM sample data
+ * @param bitDepth - Bit depth of the samples
+ * @param previousPeak - Previous peak value to maintain peak hold
+ * @returns Audio level metrics
+ */
+export function calculateAudioLevels(
+  samples: Int8Array | Int16Array | Float32Array,
+  bitDepth: BitDepth,
+  previousPeak: number = 0
+): AudioLevel {
+  const maxValue = BIT_DEPTH_MAX_VALUES[bitDepth];
+
+  let sum = 0;
+  let peak = previousPeak;
+  let current = 0;
+
+  for (let i = 0; i < samples.length; i++) {
+    const normalized = Math.abs(samples[i]) / maxValue;
+    sum += normalized * normalized;
+    if (normalized > current) {
+      current = normalized;
+    }
+    if (normalized > peak) {
+      peak = normalized;
+    }
+  }
+
+  const rms = Math.sqrt(sum / samples.length);
+  const db = rms > 0 ? 20 * Math.log10(rms) : -Infinity;
+
+  return { current, peak, rms, db };
+}
+
+/**
+ * Convert Float32 samples (-1.0 to 1.0) to Int16 samples.
+ */
+export function float32ToInt16(float32Array: Float32Array): Int16Array {
+  const int16Array = new Int16Array(float32Array.length);
+  for (let i = 0; i < float32Array.length; i++) {
+    // Clamp and convert
+    const s = Math.max(-1, Math.min(1, float32Array[i]));
+    int16Array[i] = s < 0 ? s * 0x8000 : s * 0x7fff;
+  }
+  return int16Array;
+}
+
+/**
+ * Convert Float32 samples (-1.0 to 1.0) to Int8 samples.
+ */
+export function float32ToInt8(float32Array: Float32Array): Int8Array {
+  const int8Array = new Int8Array(float32Array.length);
+  for (let i = 0; i < float32Array.length; i++) {
+    const s = Math.max(-1, Math.min(1, float32Array[i]));
+    int8Array[i] = s < 0 ? s * 0x80 : s * 0x7f;
+  }
+  return int8Array;
+}
+
+/**
+ * Write a string to a DataView at a specific offset.
+ */
+function writeString(view: DataView, offset: number, string: string): void {
+  for (let i = 0; i < string.length; i++) {
+    view.setUint8(offset + i, string.charCodeAt(i));
+  }
+}
+
+/**
+ * Generate WAV file header.
+ * @param dataLength - Length of audio data in bytes
+ * @param config - Audio configuration
+ * @returns ArrayBuffer containing the 44-byte WAV header
+ */
+export function createWavHeader(
+  dataLength: number,
+  config: AudioConfig
+): ArrayBuffer {
+  const headerLength = 44;
+  const header = new ArrayBuffer(headerLength);
+  const view = new DataView(header);
+
+  const bytesPerSample = config.bitDepth / 8;
+  const blockAlign = config.channels * bytesPerSample;
+  const byteRate = config.sampleRate * blockAlign;
+
+  // RIFF header
+  writeString(view, 0, 'RIFF');
+  view.setUint32(4, 36 + dataLength, true); // File size - 8
+  writeString(view, 8, 'WAVE');
+
+  // fmt subchunk
+  writeString(view, 12, 'fmt ');
+  view.setUint32(16, 16, true); // Subchunk1Size (16 for PCM)
+  view.setUint16(20, config.bitDepth === 32 ? 3 : 1, true); // AudioFormat (1=PCM, 3=IEEE float)
+  view.setUint16(22, config.channels, true);
+  view.setUint32(24, config.sampleRate, true);
+  view.setUint32(28, byteRate, true);
+  view.setUint16(32, blockAlign, true);
+  view.setUint16(34, config.bitDepth, true);
+
+  // data subchunk
+  writeString(view, 36, 'data');
+  view.setUint32(40, dataLength, true);
+
+  return header;
+}
+
+/**
+ * Concatenate multiple ArrayBuffers into one.
+ */
+export function concatArrayBuffers(buffers: ArrayBuffer[]): ArrayBuffer {
+  const totalLength = buffers.reduce((sum, buf) => sum + buf.byteLength, 0);
+  const result = new Uint8Array(totalLength);
+
+  let offset = 0;
+  for (const buffer of buffers) {
+    result.set(new Uint8Array(buffer), offset);
+    offset += buffer.byteLength;
+  }
+
+  return result.buffer;
+}
+
+/**
+ * Create a complete WAV file from PCM data.
+ * @param pcmData - Raw PCM audio data
+ * @param config - Audio configuration
+ * @returns ArrayBuffer containing complete WAV file
+ */
+export function createWavFile(
+  pcmData: ArrayBuffer,
+  config: AudioConfig
+): ArrayBuffer {
+  const header = createWavHeader(pcmData.byteLength, config);
+  return concatArrayBuffers([header, pcmData]);
+}
+
+/**
+ * Create a MicrophoneError object.
+ */
+export function createMicrophoneError(
+  code: import('./types').MicrophoneErrorCode,
+  message: string,
+  originalError?: Error
+): import('./types').MicrophoneError {
+  return { code, message, originalError };
+}
+
+/**
+ * Merge partial config with defaults.
+ */
+export function mergeConfig(
+  partial: Partial<AudioConfig> | undefined,
+  defaults: AudioConfig
+): AudioConfig {
+  return {
+    ...defaults,
+    ...partial,
+  };
+}