@waveform-playlist/recording 5.0.0-alpha.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Naomi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# @waveform-playlist/recording
+
+Audio recording support for waveform-playlist using AudioWorklet.
+
+## Features
+
+- ✅ **AudioWorklet-based recording** - Low latency, direct PCM access
+- ✅ **Real-time waveform visualization** - See the waveform as you record
+- ✅ **React hooks** - Easy integration with React apps
+- ✅ **Device selection** - Choose from available microphone inputs
+- ✅ **Optional package** - Only include if you need recording
+
+## Installation
+
+```bash
+npm install @waveform-playlist/recording
+```
+
+## Usage
+
+### Basic Recording
+
+```typescript
+import { useRecording, useMicrophoneAccess, RecordButton } from '@waveform-playlist/recording';
+
+function RecordingApp() {
+  const { stream, requestAccess } = useMicrophoneAccess();
+  const { isRecording, startRecording, stopRecording, peaks, duration } = useRecording(stream);
+
+  const handleRecord = async () => {
+    if (!stream) {
+      await requestAccess();
+    }
+
+    if (isRecording) {
+      const audioBuffer = await stopRecording();
+      // Use the recorded audio buffer
+    } else {
+      await startRecording();
+    }
+  };
+
+  return (
+    <div>
+      <RecordButton isRecording={isRecording} onClick={handleRecord} />
+      <p>Duration: {duration.toFixed(1)}s</p>
+      {/* Display waveform using peaks */}
+    </div>
+  );
+}
+```
+
+### With Microphone Selection
+
+```typescript
+import {
+  useMicrophoneAccess,
+  useRecording,
+  MicrophoneSelector,
+  RecordButton,
+  RecordingIndicator,
+} from '@waveform-playlist/recording';
+
+function RecordingApp() {
+  const { stream, devices, requestAccess } = useMicrophoneAccess();
+  const { isRecording, duration, startRecording, stopRecording } = useRecording(stream);
+  const [selectedDevice, setSelectedDevice] = useState<string>();
+
+  const handleDeviceChange = async (deviceId: string) => {
+    setSelectedDevice(deviceId);
+    await requestAccess(deviceId);
+  };
+
+  return (
+    <div>
+      <MicrophoneSelector
+        devices={devices}
+        selectedDeviceId={selectedDevice}
+        onDeviceChange={handleDeviceChange}
+      />
+      <RecordButton
+        isRecording={isRecording}
+        onClick={isRecording ? stopRecording : startRecording}
+      />
+      <RecordingIndicator isRecording={isRecording} duration={duration} />
+    </div>
+  );
+}
+```
+
+### Integration with WaveformPlaylist
+
+```typescript
+import { WaveformPlaylistProvider, Waveform } from '@waveform-playlist/browser';
+import { useRecording, useMicrophoneAccess } from '@waveform-playlist/recording';
+
+function RecordingPlaylist() {
+  const { stream, requestAccess } = useMicrophoneAccess();
+  const { peaks, audioBuffer, startRecording, stopRecording } = useRecording(stream);
+  const [tracks, setTracks] = useState([]);
+
+  const handleStopRecording = async () => {
+    const buffer = await stopRecording();
+    if (buffer) {
+      // Add recorded track to playlist
+      setTracks([
+        ...tracks,
+        {
+          src: buffer,
+          name: 'Recording',
+        },
+      ]);
+    }
+  };
+
+  return (
+    <WaveformPlaylistProvider tracks={tracks}>
+      <button onClick={requestAccess}>Request Microphone</button>
+      <button onClick={startRecording}>Record</button>
+      <button onClick={handleStopRecording}>Stop</button>
+      <Waveform />
+    </WaveformPlaylistProvider>
+  );
+}
+```
+
+## API Reference
+
+### Hooks
+
+#### `useMicrophoneAccess()`
+
+Manages microphone access and device enumeration.
+
+**Returns:**
+- `stream: MediaStream | null` - Active microphone stream
+- `devices: MicrophoneDevice[]` - Available microphone devices
+- `hasPermission: boolean` - Whether microphone permission is granted
+- `isLoading: boolean` - Loading state during access request
+- `requestAccess: (deviceId?: string) => Promise<void>` - Request microphone access
+- `stopStream: () => void` - Stop the microphone stream
+- `error: Error | null` - Error state
+
+#### `useRecording(stream, options?)`
+
+Main recording hook using AudioWorklet.
+
+**Parameters:**
+- `stream: MediaStream | null` - Microphone stream from `useMicrophoneAccess`
+- `options?: RecordingOptions`
+  - `sampleRate?: number` - Sample rate (defaults to AudioContext rate)
+  - `channelCount?: number` - Number of channels (default: 1)
+  - `samplesPerPixel?: number` - Samples per pixel for peaks (default: 1024)
+
+**Returns:**
+- `isRecording: boolean` - Whether recording is active
+- `isPaused: boolean` - Whether recording is paused
+- `duration: number` - Recording duration in seconds
+- `peaks: number[]` - Peak data for waveform visualization
+- `audioBuffer: AudioBuffer | null` - Final recorded audio buffer
+- `startRecording: () => Promise<void>` - Start recording
+- `stopRecording: () => Promise<AudioBuffer | null>` - Stop and finalize recording
+- `pauseRecording: () => void` - Pause recording
+- `resumeRecording: () => void` - Resume recording
+- `error: Error | null` - Error state
+
+### Components
+
+#### `<RecordButton />`
+
+Button for starting/stopping recording.
+
+**Props:**
+- `isRecording: boolean` - Recording state
+- `onClick: () => void` - Click handler
+- `disabled?: boolean` - Disabled state
+- `className?: string` - CSS class name
+
+#### `<MicrophoneSelector />`
+
+Dropdown for selecting microphone device.
+
+**Props:**
+- `devices: MicrophoneDevice[]` - Available devices
+- `selectedDeviceId?: string` - Currently selected device
+- `onDeviceChange: (deviceId: string) => void` - Change handler
+- `disabled?: boolean` - Disabled state
+- `className?: string` - CSS class name
+
+#### `<RecordingIndicator />`
+
+Visual indicator showing recording status and duration.
+
+**Props:**
+- `isRecording: boolean` - Recording state
+- `isPaused?: boolean` - Paused state
+- `duration: number` - Duration in seconds
+- `formatTime?: (seconds: number) => string` - Custom time formatter
+- `className?: string` - CSS class name
+
+## Architecture
+
+The recording implementation uses AudioWorklet for low-latency audio capture:
+
+```
+getUserMedia → MediaStream
+                    ↓
+        MediaStreamSource (Web Audio)
+                    ↓
+          AudioWorklet Processor
+          (captures raw PCM data)
+                    ↓
+        Main Thread (React Hook)
+          - Accumulates audio data
+          - Generates peaks in real-time
+          - Updates waveform visualization
+                    ↓
+         Final AudioBuffer
+```
+
+## Browser Support
+
+- Chrome 66+
+- Firefox 76+
+- Edge 79+
+- Safari 14.1+
+
+Requires HTTPS or localhost for microphone access.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,234 @@
+import React from 'react';
+
+/**
+ * Types for the recording package
+ */
+interface RecordingState {
+    isRecording: boolean;
+    isPaused: boolean;
+    duration: number;
+    sampleRate: number;
+}
+interface RecordingData {
+    buffer: AudioBuffer | null;
+    peaks: Int8Array | Int16Array;
+    duration: number;
+}
+interface MicrophoneDevice {
+    deviceId: string;
+    label: string;
+    groupId: string;
+}
+interface RecordingOptions {
+    /**
+     * Number of channels to record (1 = mono, 2 = stereo)
+     * Default: 1 (mono)
+     * Note: Sample rate is determined by the global AudioContext
+     */
+    channelCount?: number;
+    /**
+     * Samples per pixel for peak generation
+     * Default: 1024
+     */
+    samplesPerPixel?: number;
+    /**
+     * Specific device ID to use for recording
+     */
+    deviceId?: string;
+    /**
+     * MediaTrackConstraints for audio recording
+     * Use this to customize echo cancellation, noise suppression, auto gain control, latency, etc.
+     * Default: Recording-optimized settings (all processing disabled, latency: 0 for low latency)
+     */
+    audioConstraints?: MediaTrackConstraints;
+}
+interface UseRecordingReturn {
+    isRecording: boolean;
+    isPaused: boolean;
+    duration: number;
+    peaks: Int8Array | Int16Array;
+    audioBuffer: AudioBuffer | null;
+    level: number;
+    peakLevel: number;
+    startRecording: () => Promise<void>;
+    stopRecording: () => Promise<AudioBuffer | null>;
+    pauseRecording: () => void;
+    resumeRecording: () => void;
+    error: Error | null;
+}
+interface UseMicrophoneAccessReturn {
+    stream: MediaStream | null;
+    devices: MicrophoneDevice[];
+    hasPermission: boolean;
+    isLoading: boolean;
+    requestAccess: (deviceId?: string, audioConstraints?: MediaTrackConstraints) => Promise<void>;
+    stopStream: () => void;
+    error: Error | null;
+}
+
+/**
+ * Main recording hook using AudioWorklet
+ */
+
+declare function useRecording(stream: MediaStream | null, options?: RecordingOptions): UseRecordingReturn;
+
+/**
+ * Hook for managing microphone access and device enumeration
+ */
+
+declare function useMicrophoneAccess(): UseMicrophoneAccessReturn;
+
+/**
+ * Hook for monitoring microphone input levels
+ *
+ * Uses Tone.js Meter for real-time audio level monitoring.
+ */
+interface UseMicrophoneLevelOptions {
+    /**
+     * How often to update the level (in Hz)
+     * Default: 60 (60fps)
+     */
+    updateRate?: number;
+    /**
+     * FFT size for the analyser
+     * Default: 256
+     */
+    fftSize?: number;
+    /**
+     * Smoothing time constant (0-1)
+     * Higher values = smoother but slower response
+     * Default: 0.8
+     */
+    smoothingTimeConstant?: number;
+}
+interface UseMicrophoneLevelReturn {
+    /**
+     * Current audio level (0-1)
+     * 0 = silence, 1 = maximum level
+     */
+    level: number;
+    /**
+     * Peak level since last reset (0-1)
+     */
+    peakLevel: number;
+    /**
+     * Reset the peak level
+     */
+    resetPeak: () => void;
+}
+/**
+ * Monitor microphone input levels in real-time
+ *
+ * @param stream - MediaStream from getUserMedia
+ * @param options - Configuration options
+ * @returns Object with current level and peak level
+ *
+ * @example
+ * ```typescript
+ * const { stream } = useMicrophoneAccess();
+ * const { level, peakLevel, resetPeak } = useMicrophoneLevel(stream);
+ *
+ * return <VUMeter level={level} peakLevel={peakLevel} />;
+ * ```
+ */
+declare function useMicrophoneLevel(stream: MediaStream | null, options?: UseMicrophoneLevelOptions): UseMicrophoneLevelReturn;
+
+/**
+ * RecordButton - Control button for starting/stopping recording
+ */
+
+interface RecordButtonProps {
+    isRecording: boolean;
+    onClick: () => void;
+    disabled?: boolean;
+    className?: string;
+}
+declare const RecordButton: React.FC<RecordButtonProps>;
+
+/**
+ * MicrophoneSelector - Dropdown for selecting microphone input device
+ */
+
+interface MicrophoneSelectorProps {
+    devices: MicrophoneDevice[];
+    selectedDeviceId?: string;
+    onDeviceChange: (deviceId: string) => void;
+    disabled?: boolean;
+    className?: string;
+}
+declare const MicrophoneSelector: React.FC<MicrophoneSelectorProps>;
+
+/**
+ * RecordingIndicator - Shows recording status, duration, and visual indicator
+ */
+
+interface RecordingIndicatorProps {
+    isRecording: boolean;
+    isPaused?: boolean;
+    duration: number;
+    formatTime?: (seconds: number) => string;
+    className?: string;
+}
+declare const RecordingIndicator: React.FC<RecordingIndicatorProps>;
+
+/**
+ * VU Meter Component
+ *
+ * Displays real-time audio input levels with color-coded zones
+ * and peak indicator.
+ */
+
+interface VUMeterProps {
+    /**
+     * Current audio level (0-1)
+     */
+    level: number;
+    /**
+     * Peak level (0-1)
+     * Optional - if provided, shows peak indicator
+     */
+    peakLevel?: number;
+    /**
+     * Width of the meter in pixels
+     * Default: 200
+     */
+    width?: number;
+    /**
+     * Height of the meter in pixels
+     * Default: 20
+     */
+    height?: number;
+    /**
+     * Additional CSS class name
+     */
+    className?: string;
+}
+declare const VUMeter: React.NamedExoticComponent<VUMeterProps>;
+
+/**
+ * Peak generation for real-time waveform visualization during recording
+ * Matches the format used by webaudio-peaks: min/max pairs with bit depth
+ */
+/**
+ * Generate peaks from audio samples in standard min/max pair format
+ *
+ * @param samples - Audio samples to process
+ * @param samplesPerPixel - Number of samples to represent in each peak
+ * @param bits - Bit depth for peak values (8 or 16)
+ * @returns Int8Array or Int16Array of peak values (min/max pairs)
+ */
+declare function generatePeaks(samples: Float32Array, samplesPerPixel: number, bits?: 8 | 16): Int8Array | Int16Array;
+
+/**
+ * Utility functions for working with AudioBuffers during recording
+ */
+/**
+ * Concatenate multiple Float32Arrays into a single array
+ */
+declare function concatenateAudioData(chunks: Float32Array[]): Float32Array;
+/**
+ * Convert Float32Array to AudioBuffer
+ */
+declare function createAudioBuffer(audioContext: AudioContext, samples: Float32Array, sampleRate: number, channelCount?: number): AudioBuffer;
+
+export { type MicrophoneDevice, MicrophoneSelector, type MicrophoneSelectorProps, RecordButton, type RecordButtonProps, type RecordingData, RecordingIndicator, type RecordingIndicatorProps, type RecordingOptions, type RecordingState, type UseMicrophoneAccessReturn, type UseMicrophoneLevelOptions, type UseMicrophoneLevelReturn, type UseRecordingReturn, VUMeter, type VUMeterProps, concatenateAudioData, createAudioBuffer, generatePeaks, useMicrophoneAccess, useMicrophoneLevel, useRecording };