@siteed/expo-audio-stream 1.16.0 → 2.0.0

package/src/AudioAnalysis/extractAudioAnalysis.ts

@@ -1,220 +1,239 @@
 // packages/expo-audio-stream/src/AudioAnalysis/extractAudioAnalysis.ts
-import { ConsoleLike } from '../ExpoAudioStream.types'
+/**
+ * This module provides functions for extracting and analyzing audio data.
+ * - `extractAudioAnalysis`: For detailed analysis with customizable ranges and decoding options.
+ * - `extractWavAudioAnalysis`: For analyzing WAV files without decoding, preserving original PCM values.
+ * - `extractPreview`: For generating quick previews of audio waveforms, optimized for UI rendering.
+ */
+import crc32 from 'crc-32'
+
+import { ConsoleLike, ExtractAudioDataOptions } from '../ExpoAudioStream.types'
 import ExpoAudioStreamModule from '../ExpoAudioStreamModule'
 import { isWeb } from '../constants'
 import {
-    AmplitudeAlgorithm,
     AudioAnalysis,
     AudioFeaturesOptions,
-    AudioPreview,
+    DataPoint,
     DecodingConfig,
     PreviewOptions,
 } from './AudioAnalysis.types'
+import { processAudioBuffer } from '../utils/audioProcessing'
 import { convertPCMToFloat32 } from '../utils/convertPCMToFloat32'
 import { getWavFileInfo, WavFileInfo } from '../utils/getWavFileInfo'
 import { InlineFeaturesExtractor } from '../workers/InlineFeaturesExtractor.web'
 
-export interface ExtractAudioAnalysisProps {
+function calculateCRC32ForDataPoint(data: Float32Array): number {
+    // Convert float array to byte array for CRC32
+    const byteArray = new Uint8Array(data.length * 4)
+    const dataView = new DataView(byteArray.buffer)
+
+    for (let i = 0; i < data.length; i++) {
+        dataView.setFloat32(i * 4, data[i], true)
+    }
+
+    return crc32.buf(byteArray)
+}
+
+export interface ExtractWavAudioAnalysisProps {
     fileUri?: string // should provide either fileUri or arrayBuffer
     wavMetadata?: WavFileInfo
     arrayBuffer?: ArrayBuffer
     bitDepth?: number
-    skipWavHeader?: boolean
     durationMs?: number
     sampleRate?: number
     numberOfChannels?: number
-    algorithm?: AmplitudeAlgorithm
     position?: number // Optional number of bytes to skip. Default is 0
     length?: number // Optional number of bytes to read.
-    pointsPerSecond?: number // Optional number of points per second. Use to reduce the number of points and compute the number of datapoints to return.
+    segmentDurationMs?: number // Optional number of points per second. Use to reduce the number of points and compute the number of datapoints to return.
     features?: AudioFeaturesOptions
     featuresExtratorUrl?: string
     logger?: ConsoleLike
     decodingOptions?: DecodingConfig
 }
 
-export interface ExtractAudioFromAnyFormatProps
-    extends ExtractAudioAnalysisProps {
-    mimeType?: string
+// Define base options interface with common properties
+interface BaseExtractOptions {
+    fileUri?: string
+    arrayBuffer?: ArrayBuffer
+    /**
+     * Duration of each analysis segment in milliseconds. Defaults to 100ms if not specified.
+     */
+    segmentDurationMs?: number
+    features?: AudioFeaturesOptions
     decodingOptions?: DecodingConfig
-    startTime?: number // Add start time in milliseconds
-    endTime?: number // Add end time in milliseconds
+    logger?: ConsoleLike
 }
 
-export async function extractAudioFromAnyFormat({
-    fileUri,
-    arrayBuffer,
-    mimeType,
-    decodingOptions,
-    startTime,
-    endTime,
-    ...restProps
-}: ExtractAudioFromAnyFormatProps): Promise<AudioAnalysis> {
+// Time-based range options
+interface TimeRangeOptions extends BaseExtractOptions {
+    startTimeMs?: number
+    endTimeMs?: number
+    position?: never
+    length?: never
+}
+
+// Byte-based range options
+interface ByteRangeOptions extends BaseExtractOptions {
+    position?: number
+    length?: number
+    startTimeMs?: never
+    endTimeMs?: never
+}
+
+/**
+ * Options for extracting audio analysis.
+ * - For time-based analysis, provide `startTimeMs` and `endTimeMs`.
+ * - For byte-based analysis, provide `position` and `length`.
+ * - Do not mix time and byte ranges.
+ */
+export type ExtractAudioAnalysisProps = TimeRangeOptions | ByteRangeOptions
+
+/**
+ * Extracts detailed audio analysis from the specified audio file or buffer.
+ * Supports either time-based or byte-based ranges for flexibility in analysis.
+ *
+ * @param props - The options for extraction, including file URI, ranges, and decoding settings.
+ * @returns A promise that resolves to the audio analysis data.
+ * @throws {Error} If both time and byte ranges are provided or if required parameters are missing.
+ */
+export async function extractAudioAnalysis(
+    props: ExtractAudioAnalysisProps
+): Promise<AudioAnalysis> {
+    const {
+        fileUri,
+        arrayBuffer,
+        decodingOptions,
+        logger,
+        segmentDurationMs = 100,
+        features,
+    } = props
+
     if (isWeb) {
         try {
-            // Get the audio data
-            let audioBuffer: ArrayBuffer
-            if (arrayBuffer) {
-                audioBuffer = arrayBuffer
-            } else if (fileUri) {
-                const response = await fetch(fileUri)
-                if (!response.ok) {
-                    throw new Error(
-                        `Failed to fetch fileUri: ${response.statusText}`
-                    )
-                }
-                audioBuffer = await response.arrayBuffer()
-            } else {
-                throw new Error(
-                    'Either arrayBuffer or fileUri must be provided'
-                )
-            }
-
-            // Create audio context with target sample rate if specified
+            // Create AudioContext here
             const audioContext = new (window.AudioContext ||
                 (window as any).webkitAudioContext)({
-                sampleRate: decodingOptions?.targetSampleRate,
-            })
-
-            // Decode the audio data
-            const decodedAudioBuffer =
-                await audioContext.decodeAudioData(audioBuffer)
-
-            // Calculate the actual duration in milliseconds
-            const fullDurationMs = decodedAudioBuffer.duration * 1000
-            const effectiveDurationMs = endTime
-                ? endTime - (startTime || 0)
-                : fullDurationMs - (startTime || 0)
-
-            // Create a new buffer for the selected range
-            const rangeLength = decodedAudioBuffer.length
-            const rangeBuffer = new AudioBuffer({
-                length: rangeLength,
-                numberOfChannels: decodedAudioBuffer.numberOfChannels,
-                sampleRate: decodedAudioBuffer.sampleRate,
+                sampleRate: decodingOptions?.targetSampleRate ?? 16000,
             })
 
-            // Copy the selected range
-            for (
-                let channel = 0;
-                channel < decodedAudioBuffer.numberOfChannels;
-                channel++
-            ) {
-                const channelData = decodedAudioBuffer.getChannelData(channel)
-                const rangeData = channelData.slice(0, rangeLength)
-                rangeBuffer.copyToChannel(rangeData, channel)
-            }
-
-            // Use the range buffer instead of the full buffer
-            let processedBuffer = rangeBuffer
-
-            // Get original properties
-            const originalSampleRate = processedBuffer.sampleRate
-            const length = processedBuffer.length
-
-            // Determine target format
-            const targetChannels =
-                decodingOptions?.targetChannels ??
-                processedBuffer.numberOfChannels
-            const targetSampleRate =
-                decodingOptions?.targetSampleRate ?? processedBuffer.sampleRate
-
-            // Create offline context for resampling if needed
-            if (targetSampleRate !== originalSampleRate) {
-                const offlineCtx = new OfflineAudioContext(
-                    targetChannels,
-                    (length * targetSampleRate) / originalSampleRate,
-                    targetSampleRate
-                )
-                const source = offlineCtx.createBufferSource()
-                source.buffer = processedBuffer
-                source.connect(offlineCtx.destination)
-                source.start()
-                processedBuffer = await offlineCtx.startRendering()
-            }
+            try {
+                const processedBuffer = await processAudioBuffer({
+                    arrayBuffer,
+                    fileUri,
+                    targetSampleRate:
+                        decodingOptions?.targetSampleRate ?? 16000,
+                    targetChannels: decodingOptions?.targetChannels ?? 1,
+                    normalizeAudio: decodingOptions?.normalizeAudio ?? false,
+                    startTimeMs:
+                        'startTimeMs' in props ? props.startTimeMs : undefined,
+                    endTimeMs:
+                        'endTimeMs' in props ? props.endTimeMs : undefined,
+                    position: 'position' in props ? props.position : undefined,
+                    length: 'length' in props ? props.length : undefined,
+                    audioContext, // Pass the context we created
+                    logger,
+                })
 
-            // Convert to the desired format
-            const newLength = processedBuffer.length
-            let wavBuffer: Float32Array | Int16Array | Int8Array
-
-            // Create appropriate buffer based on target bit depth
-            switch (decodingOptions?.targetBitDepth) {
-                case 16:
-                    wavBuffer = new Int16Array(newLength * targetChannels)
-                    break
-                case 8:
-                    wavBuffer = new Int8Array(newLength * targetChannels)
-                    break
-                case 32:
-                default:
-                    wavBuffer = new Float32Array(newLength * targetChannels)
-                    break
-            }
+                const channelData = processedBuffer.buffer.getChannelData(0)
 
-            // Interleave channels and handle bit depth conversion
-            const numChannels = Math.min(
-                processedBuffer.numberOfChannels,
-                targetChannels
-            )
-            for (let channel = 0; channel < numChannels; channel++) {
-                const channelData = processedBuffer.getChannelData(channel)
-                for (let i = 0; i < newLength; i++) {
-                    let sample = channelData[i]
-
-                    // Normalize if requested
-                    if (decodingOptions?.normalizeAudio) {
-                        sample = Math.max(-1, Math.min(1, sample))
+                // Create and initialize the worker
+                const blob = new Blob([InlineFeaturesExtractor], {
+                    type: 'application/javascript',
+                })
+                const workerUrl = URL.createObjectURL(blob)
+                const worker = new Worker(workerUrl)
+
+                return new Promise((resolve, reject) => {
+                    worker.onmessage = (event) => {
+                        if (event.data.error) {
+                            reject(new Error(event.data.error))
+                            return
+                        }
+
+                        const result: AudioAnalysis = event.data.result
+                        // Calculate CRC32 after worker completes if requested
+                        if (features?.crc32) {
+                            const samplesPerSegment = Math.floor(
+                                (processedBuffer.sampleRate *
+                                    segmentDurationMs) /
+                                    1000
+                            )
+
+                            result.dataPoints = result.dataPoints.map(
+                                (point: DataPoint, index: number) => {
+                                    const startSample =
+                                        index * samplesPerSegment
+                                    const segmentData = channelData.slice(
+                                        startSample,
+                                        startSample + samplesPerSegment
+                                    )
+
+                                    return {
+                                        ...point,
+                                        features: {
+                                            ...point.features,
+                                            crc32: calculateCRC32ForDataPoint(
+                                                segmentData
+                                            ),
+                                        },
+                                    }
+                                }
+                            )
+                        }
+
+                        URL.revokeObjectURL(workerUrl)
+                        worker.terminate()
+                        resolve(result)
                     }
 
-                    // Convert sample based on target bit depth
-                    if (decodingOptions?.targetBitDepth === 16) {
-                        sample = sample * 32767 // Convert to 16-bit range
-                    } else if (decodingOptions?.targetBitDepth === 8) {
-                        sample = sample * 127 // Convert to 8-bit range
+                    worker.onerror = (error) => {
+                        URL.revokeObjectURL(workerUrl)
+                        worker.terminate()
+                        reject(error)
                     }
 
-                    wavBuffer[i * targetChannels + channel] = sample
-                }
+                    worker.postMessage({
+                        channelData,
+                        sampleRate: processedBuffer.sampleRate,
+                        segmentDurationMs,
+                        bitDepth: decodingOptions?.targetBitDepth ?? 32,
+                        numberOfChannels: processedBuffer.channels,
+                        // enableLogging: !!logger,
+                        features,
+                    })
+                })
+            } finally {
+                await audioContext.close()
             }
-
-            // Pass the duration to extractAudioAnalysis
-            return await extractAudioAnalysis({
-                arrayBuffer: wavBuffer.buffer as ArrayBuffer,
-                bitDepth: decodingOptions?.targetBitDepth ?? 32,
-                skipWavHeader: true,
-                sampleRate: targetSampleRate,
-                numberOfChannels: targetChannels,
-                durationMs: effectiveDurationMs,
-                ...restProps,
-            })
         } catch (error) {
-            console.error('Failed to process audio:', error)
+            logger?.error('Failed to process audio:', error)
             throw error
         }
     } else {
-        // For native platforms, pass through all options
-        return await extractAudioAnalysis({
-            fileUri,
-            decodingOptions,
-            ...restProps,
-        })
+        return await ExpoAudioStreamModule.extractAudioAnalysis(props)
     }
 }
 
-export const extractAudioAnalysis = async ({
+/**
+ * Analyzes WAV files without decoding, preserving original PCM values.
+ * Use this function when you need to ensure the analysis matches other software by avoiding any transformations.
+ *
+ * @param props - The options for WAV analysis, including file URI and range.
+ * @returns A promise that resolves to the audio analysis data.
+ */
+export const extractRawWavAnalysis = async ({
     fileUri,
-    pointsPerSecond = 20,
+    segmentDurationMs = 100, // Default to 100ms
     arrayBuffer,
     bitDepth,
-    skipWavHeader = true,
     durationMs,
     sampleRate,
     numberOfChannels,
-    algorithm = 'rms',
     features,
-    featuresExtratorUrl,
     logger,
-}: ExtractAudioAnalysisProps): Promise<AudioAnalysis> => {
+    position = 0,
+    length,
+}: ExtractWavAudioAnalysisProps): Promise<AudioAnalysis> => {
     if (isWeb) {
         if (!arrayBuffer && !fileUri) {
             throw new Error('Either arrayBuffer or fileUri must be provided')
@@ -237,7 +256,7 @@ export const extractAudioAnalysis = async ({
         // Create a new copy of the ArrayBuffer to avoid detachment issues
         const bufferCopy = arrayBuffer.slice(0)
         logger?.log(
-            `extractAudioAnalysis skipWavHeader=${skipWavHeader} bitDepth=${bitDepth} len=${bufferCopy.byteLength}`,
+            `extractAudioAnalysis bitDepth=${bitDepth} len=${bufferCopy.byteLength}`,
             bufferCopy.slice(0, 100)
         )
 
@@ -258,25 +277,22 @@ export const extractAudioAnalysis = async ({
         } = await convertPCMToFloat32({
             buffer: arrayBuffer,
             bitDepth: actualBitDepth,
-            skipWavHeader,
         })
         logger?.log(
-            `extractAudioAnalysis skipWaveHeader=${skipWavHeader} convertPCMToFloat32 length=${channelData.length} range: [ ${min} :: ${max} ]`
+            `extractAudioAnalysis convertPCMToFloat32 length=${channelData.length} range: [ ${min} :: ${max} ]`
         )
 
+        // Apply position and length constraints to channelData if specified
+        const startIndex = position
+        const endIndex = length ? startIndex + length : channelData.length
+        const constrainedChannelData = channelData.slice(startIndex, endIndex)
+
         return new Promise((resolve, reject) => {
-            let worker: Worker
-            if (featuresExtratorUrl) {
-                worker = new Worker(
-                    new URL(featuresExtratorUrl, window.location.href)
-                )
-            } else {
-                const blob = new Blob([InlineFeaturesExtractor], {
-                    type: 'application/javascript',
-                })
-                const url = URL.createObjectURL(blob)
-                worker = new Worker(url)
-            }
+            const blob = new Blob([InlineFeaturesExtractor], {
+                type: 'application/javascript',
+            })
+            const url = URL.createObjectURL(blob)
+            const worker = new Worker(url)
 
             worker.onmessage = (event) => {
                 resolve(event.data.result)
@@ -288,10 +304,10 @@ export const extractAudioAnalysis = async ({
 
             worker.postMessage({
                 command: 'process',
-                channelData,
+                channelData: constrainedChannelData,
                 sampleRate,
-                pointsPerSecond,
-                algorithm,
+                segmentDurationMs,
+                logger,
                 bitDepth,
                 fullAudioDurationMs: durationMs,
                 numberOfChannels,
@@ -303,64 +319,52 @@ export const extractAudioAnalysis = async ({
         }
         logger?.log(`extractAudioAnalysis`, {
             fileUri,
-            pointsPerSecond,
-            algorithm,
+            segmentDurationMs,
         })
         const res = await ExpoAudioStreamModule.extractAudioAnalysis({
             fileUri,
-            pointsPerSecond,
-            skipWavHeader,
-            algorithm,
+            segmentDurationMs,
             features,
+            position,
+            length,
         })
         logger?.log(`extractAudioAnalysis`, res)
         return res
     }
 }
 
+/**
+ * Generates a simplified preview of the audio waveform for quick visualization.
+ * Ideal for UI rendering with a specified number of points.
+ *
+ * @param options - The options for the preview, including file URI and time range.
+ * @returns A promise that resolves to the audio preview data.
+ */
 export async function extractPreview({
     fileUri,
-    numberOfPoints,
-    algorithm = 'rms',
-    startTime,
-    endTime,
+    numberOfPoints = 100,
+    startTimeMs = 0,
+    endTimeMs = 30000, // First 30 seconds
     decodingOptions,
-}: PreviewOptions): Promise<AudioPreview> {
-    if (isWeb) {
-        // For web, we can reuse the existing extractAudioFromAnyFormat with modified parameters
-        const analysis = await extractAudioFromAnyFormat({
-            fileUri,
-            algorithm,
-            decodingOptions,
-            startTime, // Pass startTime
-            endTime, // Pass endTime
-            pointsPerSecond:
-                (numberOfPoints ?? 100) /
-                ((endTime ? endTime - (startTime || 0) : 1000) / 1000), // Adjust points per second calculation
-        })
-
-        // Convert AudioAnalysis to AudioPreview format and adjust duration
-        return {
-            pointsPerSecond: analysis.pointsPerSecond,
-            durationMs: endTime
-                ? endTime - (startTime || 0)
-                : analysis.durationMs, // Use range duration if specified
-            amplitudeRange: analysis.amplitudeRange,
-            dataPoints: analysis.dataPoints.map((point) => ({
-                id: point.id,
-                amplitude: point.amplitude,
-                startTime: point.startTime,
-                endTime: point.endTime,
-            })),
-        }
-    }
+    logger,
+}: PreviewOptions): Promise<AudioAnalysis> {
+    const durationMs = endTimeMs - startTimeMs
+    const segmentDurationMs = Math.floor(durationMs / numberOfPoints)
 
-    return await ExpoAudioStreamModule.extractPreview({
+    // Call extractAudioAnalysis with calculated parameters
+    const analysis = await extractAudioAnalysis({
         fileUri,
-        numberOfPoints,
-        algorithm,
-        startTime,
-        endTime,
+        startTimeMs,
+        endTimeMs,
+        logger,
+        segmentDurationMs,
         decodingOptions,
     })
+
+    // Transform the result into AudioPreview format
+    return analysis
 }
+
+export const extractAudioData = async (props: ExtractAudioDataOptions) => {
+    return await ExpoAudioStreamModule.extractAudioData(props)
+}

package/src/ExpoAudioStream.types.ts

@@ -1,8 +1,8 @@
 // packages/expo-audio-stream/src/ExpoAudioStream.types.ts
 import {
-    AmplitudeAlgorithm,
     AudioAnalysis,
     AudioFeaturesOptions,
+    DecodingConfig,
 } from './AudioAnalysis/AudioAnalysis.types'
 import { AudioAnalysisEvent } from './events'
 
@@ -20,6 +20,7 @@ export interface AudioStreamStatus {
     durationMs: number
     size: number
     interval: number
+    intervalAnalysis: number
     mimeType: string
     compression?: CompressionInfo
 }
@@ -38,10 +39,12 @@ export interface AudioDataEvent {
 export type EncodingType = 'pcm_32bit' | 'pcm_16bit' | 'pcm_8bit'
 export type SampleRate = 16000 | 44100 | 48000
 export type BitDepth = 8 | 16 | 32
+export type PCMFormat = `pcm_${BitDepth}bit`
 
 export type ConsoleLike = {
     log: (message: string, ...args: unknown[]) => void
     debug: (message: string, ...args: unknown[]) => void
+    info: (message: string, ...args: unknown[]) => void
     warn: (message: string, ...args: unknown[]) => void
     error: (message: string, ...args: unknown[]) => void
 }
@@ -147,7 +150,10 @@ export interface RecordingConfig {
     // Interval in milliseconds at which to emit recording data
     interval?: number
 
-    // Continue recording when app is in background (default is true)
+    // Interval in milliseconds at which to emit analysis data
+    intervalAnalysis?: number
+
+    // Keep the device awake while recording (default is false)
     keepAwake?: boolean
 
     // Show a notification during recording (default is false)
@@ -165,11 +171,8 @@ export interface RecordingConfig {
     // iOS-specific configuration
     ios?: IOSConfig
 
-    // Number of data points to extract per second of audio (default is 1000)
-    pointsPerSecond?: number
-
-    // Algorithm to use for amplitude computation (default is "rms")
-    algorithm?: AmplitudeAlgorithm
+    // Duration of each segment in milliseconds (default: 100)
+    segmentDurationMs?: number
 
     // Feature options to extract (default is empty)
     features?: AudioFeaturesOptions
@@ -264,6 +267,53 @@ export interface WaveformConfig {
     height?: number // Height of the waveform view in dp (default: 64)
 }
 
+export interface ExtractAudioDataOptions {
+    fileUri: string
+    // Time-based range (mutually exclusive with byte-based range)
+    startTimeMs?: number
+    endTimeMs?: number
+    // Byte-based range (mutually exclusive with time-based range)
+    position?: number
+    length?: number
+    /** Include normalized audio data in [-1, 1] range */
+    includeNormalizedData?: boolean
+    /** Include base64 encoded string representation of the audio data */
+    includeBase64Data?: boolean
+    /** Include WAV header in the PCM data (makes it a valid WAV file) */
+    includeWavHeader?: boolean
+    /** Logger for debugging - can pass console directly. */
+    logger?: ConsoleLike
+    /** Compute the checksum of the pcm data */
+    computeChecksum?: boolean
+    /** Target config for the normalized audio (Android and Web) */
+    decodingOptions?: DecodingConfig
+}
+
+export interface ExtractedAudioData {
+    /** Raw PCM audio data */
+    pcmData: Uint8Array
+    /** Normalized audio data in [-1, 1] range (when includeNormalizedData is true) */
+    normalizedData?: Float32Array
+    /** Base64 encoded string representation of the audio data (when includeBase64Data is true) */
+    base64Data?: string
+    /** Sample rate in Hz (e.g., 44100, 48000) */
+    sampleRate: number
+    /** Number of audio channels (1 for mono, 2 for stereo) */
+    channels: number
+    /** Bits per sample (8, 16, or 32) */
+    bitDepth: BitDepth
+    /** Duration of the audio in milliseconds */
+    durationMs: number
+    /** PCM format identifier (e.g., "pcm_16bit") */
+    format: PCMFormat
+    /** Total number of audio samples per channel */
+    samples: number
+    /** Whether the pcmData includes a WAV header */
+    hasWavHeader?: boolean
+    /** CRC32 Checksum of pcm data */
+    checksum?: number
+}
+
 export interface UseAudioRecorderState {
     startRecording: (_: RecordingConfig) => Promise<StartRecordingResult>
     stopRecording: () => Promise<AudioRecording | null>