@siteed/audio-studio 3.0.5 → 3.1.1

package/src/AudioAnalysis/extractPreview.ts

@@ -1,34 +1,135 @@
-import { PreviewOptions, AudioAnalysis } from './AudioAnalysis.types'
+import { mapExtractionError } from '../errors/AudioExtractionError'
+import { PreviewOptions, AudioAnalysis, DataPoint } from './AudioAnalysis.types'
 import { extractAudioAnalysis } from './extractAudioAnalysis'
 
+const DEFAULT_SILENCE_THRESHOLD = 0.01
+
+/**
+ * Apply a silence threshold to the data points by recomputing the `silent` flag from rms.
+ * Returns a new array (does not mutate the source).
+ */
+function applySilenceThreshold(
+    dataPoints: DataPoint[],
+    threshold: number
+): DataPoint[] {
+    return dataPoints.map((p) => ({
+        ...p,
+        silent: p.rms < threshold,
+    }))
+}
+
+const SMALL_TOTAL_INSTANT_THRESHOLD = 50
+const PROGRESSIVE_BATCH_DELAY_MS = 30
+const PROGRESSIVE_BATCH_COUNT = 8
+
+/**
+ * Schedule progressive emission of points after the native one-shot resolve.
+ * Native progressive streaming is a future enhancement; today the points are
+ * micro-batched on the JS side so consumers (and the agentic recipe runner)
+ * can observe an in-flight `pointsReceived < totalPoints` window.
+ */
+function emitPointsProgressively(
+    dataPoints: DataPoint[],
+    onPointReady: NonNullable<PreviewOptions['onPointReady']>,
+    signal?: PreviewOptions['signal'],
+    logger?: PreviewOptions['logger']
+): void {
+    const total = dataPoints.length
+    if (total === 0) return
+
+    const safeEmit = (point: DataPoint, index: number) => {
+        if (signal?.aborted) return
+        try {
+            onPointReady(point, index, total)
+        } catch (err) {
+            // Swallow callback errors so a buggy consumer cannot break extraction.
+            logger?.warn?.('extractPreview onPointReady callback failed', err)
+        }
+    }
+
+    if (signal?.aborted) return
+    if (total <= SMALL_TOTAL_INSTANT_THRESHOLD) {
+        for (let i = 0; i < total; i++) safeEmit(dataPoints[i], i)
+        return
+    }
+
+    // First quarter flushes immediately so the UI shows something within a frame.
+    const firstFlushCount = Math.max(1, Math.floor(total / 4))
+    for (let i = 0; i < firstFlushCount; i++) safeEmit(dataPoints[i], i)
+
+    if (firstFlushCount >= total) return
+
+    const remaining = total - firstFlushCount
+    const batchSize = Math.max(
+        1,
+        Math.ceil(remaining / PROGRESSIVE_BATCH_COUNT)
+    )
+    let cursor = firstFlushCount
+    const pump = () => {
+        if (signal?.aborted) return
+        const end = Math.min(total, cursor + batchSize)
+        for (let i = cursor; i < end; i++) safeEmit(dataPoints[i], i)
+        cursor = end
+        if (cursor < total) {
+            setTimeout(pump, PROGRESSIVE_BATCH_DELAY_MS)
+        }
+    }
+    setTimeout(pump, PROGRESSIVE_BATCH_DELAY_MS)
+}
+
 /**
  * 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.
+ * @throws {AudioExtractionError} when the underlying extraction fails.
  */
 export async function extractPreview({
     fileUri,
     numberOfPoints = 100,
     startTimeMs = 0,
-    endTimeMs = 30000, // First 30 seconds
+    endTimeMs = 30000,
     decodingOptions,
     logger,
+    onPointReady,
+    signal,
 }: PreviewOptions): Promise<AudioAnalysis> {
-    const durationMs = endTimeMs - startTimeMs
-    const segmentDurationMs = Math.floor(durationMs / numberOfPoints)
-
-    // Call extractAudioAnalysis with calculated parameters
-    const analysis = await extractAudioAnalysis({
-        fileUri,
-        startTimeMs,
-        endTimeMs,
-        logger,
-        segmentDurationMs,
-        decodingOptions,
-    })
-
-    // Transform the result into AudioPreview format
-    return analysis
+    const durationMs = Math.max(1, endTimeMs - startTimeMs)
+    const segmentDurationMs = Math.max(
+        1,
+        Math.floor(durationMs / numberOfPoints)
+    )
+
+    let analysis: AudioAnalysis
+    try {
+        analysis = await extractAudioAnalysis({
+            fileUri,
+            startTimeMs,
+            endTimeMs,
+            logger,
+            segmentDurationMs,
+            decodingOptions,
+        })
+    } catch (err) {
+        throw mapExtractionError(err, fileUri)
+    }
+
+    const threshold =
+        decodingOptions?.silenceRmsThreshold ?? DEFAULT_SILENCE_THRESHOLD
+    const adjusted: AudioAnalysis = {
+        ...analysis,
+        dataPoints: applySilenceThreshold(analysis.dataPoints, threshold),
+    }
+
+    if (onPointReady) {
+        emitPointsProgressively(
+            adjusted.dataPoints,
+            onPointReady,
+            signal,
+            logger
+        )
+    }
+
+    return adjusted
 }

package/src/AudioAnalysis/extractPreviewBars.ts

@@ -0,0 +1,193 @@
+import {
+    AudioAnalysis,
+    DataPoint,
+    PreviewBar,
+    PreviewBarsOptions,
+    PreviewBarsResult,
+} from './AudioAnalysis.types'
+import { extractPreview } from './extractPreview'
+import AudioStudioModule from '../AudioStudioModule'
+import { mapExtractionError } from '../errors/AudioExtractionError'
+import { cleanNativeOptions } from '../utils/cleanNativeOptions'
+
+const DEFAULT_PREVIEW_BARS = 100
+const DEFAULT_PREVIEW_END_TIME_MS = 30000
+const DEFAULT_SILENCE_THRESHOLD = 0.01
+
+interface NativePreviewBarsModule {
+    extractPreviewBars: (
+        options: Record<string, unknown>
+    ) => Promise<PreviewBarsResult>
+}
+
+function hasNativePreviewBars(
+    module: unknown
+): module is NativePreviewBarsModule {
+    return (
+        module !== null &&
+        (typeof module === 'object' || typeof module === 'function') &&
+        typeof (module as NativePreviewBarsModule).extractPreviewBars ===
+            'function'
+    )
+}
+
+function clamp01(value: number): number {
+    if (!Number.isFinite(value)) return 0
+    return Math.max(0, Math.min(1, value))
+}
+
+function getPointTimeMs(value: number | undefined, fallbackMs: number): number {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? Math.round(value)
+        : fallbackMs
+}
+
+function pointToPreviewBar(
+    point: DataPoint,
+    index: number,
+    fallbackBarDurationMs: number,
+    silenceRmsThreshold: number
+): PreviewBar {
+    const fallbackStartTimeMs = Math.round(index * fallbackBarDurationMs)
+    const fallbackEndTimeMs = Math.round((index + 1) * fallbackBarDurationMs)
+    const startTimeMs = getPointTimeMs(point.startTime, fallbackStartTimeMs)
+    const endTimeMs = getPointTimeMs(point.endTime, fallbackEndTimeMs)
+    const rms = clamp01(point.rms)
+
+    return {
+        id: point.id ?? index,
+        amplitude: clamp01(point.amplitude),
+        rms,
+        silent: point.silent ?? rms < silenceRmsThreshold,
+        startTimeMs,
+        endTimeMs: Math.max(startTimeMs, endTimeMs),
+    }
+}
+
+function calculateRange(values: number[]): { min: number; max: number } {
+    if (values.length === 0) {
+        return { min: 0, max: 0 }
+    }
+
+    let min = Number.POSITIVE_INFINITY
+    let max = Number.NEGATIVE_INFINITY
+
+    for (const value of values) {
+        const safeValue = clamp01(value)
+        min = Math.min(min, safeValue)
+        max = Math.max(max, safeValue)
+    }
+
+    return { min, max }
+}
+
+function fromAudioAnalysis(
+    analysis: AudioAnalysis,
+    requestedNumberOfBars: number,
+    silenceRmsThreshold: number
+): PreviewBarsResult {
+    const barDurationMs =
+        analysis.segmentDurationMs ||
+        Math.max(
+            1,
+            analysis.durationMs / Math.max(1, analysis.dataPoints.length)
+        )
+    const bars = analysis.dataPoints.map((point, index) =>
+        pointToPreviewBar(point, index, barDurationMs, silenceRmsThreshold)
+    )
+
+    return {
+        bars,
+        durationMs: analysis.durationMs,
+        sampleRate: analysis.sampleRate,
+        numberOfChannels: analysis.numberOfChannels,
+        bitDepth: analysis.bitDepth,
+        samples: analysis.samples,
+        requestedNumberOfBars,
+        barDurationMs,
+        amplitudeRange: calculateRange(bars.map((bar) => bar.amplitude)),
+        rmsRange: calculateRange(bars.map((bar) => bar.rms)),
+        extractionTimeMs: analysis.extractionTimeMs,
+    }
+}
+
+function emitBarsProgressively(
+    bars: PreviewBar[],
+    onBarReady: NonNullable<PreviewBarsOptions['onBarReady']>
+): void {
+    const total = bars.length
+    for (let index = 0; index < total; index++) {
+        onBarReady(bars[index], index, total)
+    }
+}
+
+/**
+ * Extracts compact waveform preview bars for UI rendering.
+ *
+ * Native platforms may provide a compact `extractPreviewBars` bridge. Until that
+ * bridge is available, this safely falls back to the existing `extractPreview`
+ * compatibility path and adapts `DataPoint` objects into compact bars.
+ *
+ * @throws {AudioExtractionError} when the underlying extraction fails.
+ */
+export async function extractPreviewBars({
+    fileUri,
+    numberOfBars = DEFAULT_PREVIEW_BARS,
+    startTimeMs = 0,
+    endTimeMs = DEFAULT_PREVIEW_END_TIME_MS,
+    decodingOptions,
+    logger,
+    onBarReady,
+}: PreviewBarsOptions): Promise<PreviewBarsResult> {
+    const requestedNumberOfBars = Math.max(1, Math.floor(numberOfBars))
+    const nativeOptions = {
+        fileUri,
+        numberOfBars: requestedNumberOfBars,
+        startTimeMs,
+        endTimeMs,
+        decodingOptions,
+    }
+
+    const nativeModule = AudioStudioModule as unknown
+    if (hasNativePreviewBars(nativeModule)) {
+        let result: PreviewBarsResult
+        try {
+            result = await nativeModule.extractPreviewBars(
+                cleanNativeOptions(nativeOptions)
+            )
+        } catch (err) {
+            throw mapExtractionError(err, fileUri)
+        }
+
+        if (onBarReady) {
+            emitBarsProgressively(result.bars, onBarReady)
+        }
+        return result
+    }
+
+    let analysis: AudioAnalysis
+    try {
+        analysis = await extractPreview({
+            fileUri,
+            numberOfPoints: requestedNumberOfBars,
+            startTimeMs,
+            endTimeMs,
+            decodingOptions,
+            logger,
+        })
+    } catch (err) {
+        throw mapExtractionError(err, fileUri)
+    }
+
+    const result = fromAudioAnalysis(
+        analysis,
+        requestedNumberOfBars,
+        decodingOptions?.silenceRmsThreshold ?? DEFAULT_SILENCE_THRESHOLD
+    )
+
+    if (onBarReady) {
+        emitBarsProgressively(result.bars, onBarReady)
+    }
+
+    return result
+}

package/src/AudioStudio.types.ts

@@ -160,7 +160,10 @@ export interface AudioRecording {
     createdAt?: number
     /** Array of transcription data if available */
     transcripts?: TranscriberData[]
-    /** Analysis data for the recording if processing was enabled */
+    /**
+     * Full analysis data for the recording if processing was enabled and
+     * `keepFullAnalysis` was not set to `false`.
+     */
     analysisData?: AudioAnalysis
     /** Information about compression if enabled, including the URI to the compressed file */
     compression?: CompressionInfo & {
@@ -432,6 +435,17 @@ export interface RecordingConfig {
     /** Enable audio processing (default is false) */
     enableProcessing?: boolean
 
+    /**
+     * Whether `useAudioRecorder` should retain every audio-analysis data point
+     * and attach the full history to `stopRecording().analysisData`.
+     *
+     * Defaults to `true` for backwards compatibility. Set to `false` for
+     * long-running recordings when you only need live `analysisData` state or
+     * per-callback `onAudioAnalysis` chunks; this avoids unbounded JS memory
+     * growth in the hook without disabling native analysis processing.
+     */
+    keepFullAnalysis?: boolean
+
     /** iOS-specific configuration */
     ios?: IOSConfig
 

package/src/errors/AudioExtractionError.ts

@@ -0,0 +1,167 @@
+/**
+ * Typed error class for audio extraction failures.
+ * Wraps native module errors with stable codes consumers can switch on.
+ */
+export type AudioExtractionErrorCode =
+    | 'unsupported_codec'
+    | 'malformed_file'
+    | 'decode_failed'
+    | 'permission_denied'
+    | 'file_not_found'
+    | 'unknown'
+
+export interface AudioExtractionErrorPayload {
+    code: AudioExtractionErrorCode
+    message: string
+    nativeMessage?: string
+    fileUri?: string
+}
+
+export class AudioExtractionError extends Error {
+    readonly code: AudioExtractionErrorCode
+    readonly nativeMessage?: string
+    readonly fileUri?: string
+
+    constructor(payload: AudioExtractionErrorPayload) {
+        super(payload.message)
+        this.name = 'AudioExtractionError'
+        this.code = payload.code
+        this.nativeMessage = payload.nativeMessage
+        this.fileUri = payload.fileUri
+    }
+
+    toJSON(): AudioExtractionErrorPayload {
+        return {
+            code: this.code,
+            message: this.message,
+            nativeMessage: this.nativeMessage,
+            fileUri: this.fileUri,
+        }
+    }
+}
+
+function getNativeMessage(err: unknown): string {
+    if (err instanceof Error) return err.message
+    if (typeof err === 'string') return err
+
+    try {
+        return JSON.stringify(err) ?? String(err)
+    } catch {
+        return String(err)
+    }
+}
+
+function getNativeCode(err: unknown): string | undefined {
+    if (err && typeof err === 'object' && 'code' in err) {
+        const code = (err as { code?: unknown }).code
+        if (typeof code === 'string') return code
+    }
+    return undefined
+}
+
+function mapNativeCode(
+    code: string | undefined
+): AudioExtractionErrorCode | null {
+    if (!code) return null
+
+    const normalized = code.toUpperCase()
+    if (
+        normalized.includes('FILE_NOT_FOUND') ||
+        normalized === 'ENOENT' ||
+        normalized.includes('NO_SUCH_FILE')
+    ) {
+        return 'file_not_found'
+    }
+    if (
+        normalized.includes('PERMISSION') ||
+        normalized === 'EACCES' ||
+        normalized.includes('NOT_AUTHORIZED')
+    ) {
+        return 'permission_denied'
+    }
+    if (
+        normalized.includes('UNSUPPORTED') ||
+        normalized.includes('NO_SUITABLE_CODEC')
+    ) {
+        return 'unsupported_codec'
+    }
+    if (
+        normalized.includes('INVALID_RANGE') ||
+        normalized.includes('INVALID_HEADER') ||
+        normalized.includes('MALFORMED') ||
+        normalized.includes('CORRUPT')
+    ) {
+        return 'malformed_file'
+    }
+    if (
+        normalized.includes('PROCESSING_ERROR') ||
+        normalized.includes('AUDIO_READ_ERROR') ||
+        normalized.includes('DECODE')
+    ) {
+        return 'decode_failed'
+    }
+
+    return null
+}
+
+/**
+ * Map a thrown native/JS value into an AudioExtractionError with a stable code.
+ * Heuristics inspect message text and known native error codes.
+ */
+export function mapExtractionError(
+    err: unknown,
+    fileUri?: string
+): AudioExtractionError {
+    if (err instanceof AudioExtractionError) return err
+
+    const nativeMessage = getNativeMessage(err)
+    const lower = nativeMessage.toLowerCase()
+
+    let code = mapNativeCode(getNativeCode(err)) ?? 'unknown'
+    if (
+        code === 'unknown' &&
+        (lower.includes('unsupported') ||
+            lower.includes('not supported') ||
+            lower.includes('no suitable codec') ||
+            lower.includes('no track'))
+    ) {
+        code = 'unsupported_codec'
+    } else if (
+        code === 'unknown' &&
+        (lower.includes('not found') ||
+            lower.includes('no such file') ||
+            lower.includes('does not exist'))
+    ) {
+        code = 'file_not_found'
+    } else if (
+        code === 'unknown' &&
+        (lower.includes('permission') ||
+            lower.includes('denied') ||
+            lower.includes('not authorized'))
+    ) {
+        code = 'permission_denied'
+    } else if (
+        code === 'unknown' &&
+        (lower.includes('malformed') ||
+            lower.includes('corrupt') ||
+            lower.includes('invalid header') ||
+            lower.includes('invalid wav'))
+    ) {
+        code = 'malformed_file'
+    } else if (
+        code === 'unknown' &&
+        (lower.includes('decode') ||
+            lower.includes('codec') ||
+            lower.includes('mediaextractor') ||
+            lower.includes('avaudio'))
+    ) {
+        code = 'decode_failed'
+    }
+
+    return new AudioExtractionError({
+        code,
+        message: `Audio extraction failed (${code}): ${nativeMessage}`,
+        nativeMessage,
+        fileUri,
+    })
+}

package/src/index.ts

@@ -44,6 +44,7 @@ export { AudioDeviceManager, audioDeviceManager } from './AudioDeviceManager'
 export { useAudioDevices } from './hooks/useAudioDevices'
 
 export { setMelSpectrogramWasmUrl } from './AudioAnalysis/wasmConfig'
+export { extractPreviewBars } from './AudioAnalysis/extractPreviewBars'
 
 export {
     AudioRecorderProvider,
@@ -61,6 +62,15 @@ export {
     useSharedAudioRecorder,
 }
 
+export {
+    AudioExtractionError,
+    mapExtractionError,
+} from './errors/AudioExtractionError'
+export type {
+    AudioExtractionErrorCode,
+    AudioExtractionErrorPayload,
+} from './errors/AudioExtractionError'
+
 // Export all types
 export type * from './AudioAnalysis/AudioAnalysis.types'
 export type * from './AudioStudio.types'

package/src/useAudioRecorder.tsx

@@ -156,6 +156,10 @@ interface HandleAudioAnalysisProps {
     visualizationDuration: number
 }
 
+function shouldKeepFullAnalysis(config?: RecordingConfig | null): boolean {
+    return config?.keepFullAnalysis !== false
+}
+
 export function useAudioRecorder({
     logger,
     audioWorkletUrl,
@@ -232,10 +236,15 @@ export function useAudioRecorder({
                 ...analysis.dataPoints,
             ]
 
-            const fullCombinedDataPoints = [
-                ...(fullAnalysisRef.current?.dataPoints ?? []),
-                ...analysis.dataPoints,
-            ]
+            const keepFullAnalysis = shouldKeepFullAnalysis(
+                recordingConfigRef.current
+            )
+            const fullCombinedDataPoints = keepFullAnalysis
+                ? [
+                      ...(fullAnalysisRef.current?.dataPoints ?? []),
+                      ...analysis.dataPoints,
+                  ]
+                : undefined
 
             // Calculate the new duration
             // The number of segments is based on how many segments of segmentDurationMs can fit in visualizationDuration
@@ -257,13 +266,15 @@ export function useAudioRecorder({
                 )
             }
 
-            // Keep the full data points
-            fullAnalysisRef.current = {
-                ...fullAnalysisRef.current,
-                dataPoints: fullCombinedDataPoints,
+            // Keep the full data points when requested for stopRecording().analysisData.
+            if (keepFullAnalysis && fullCombinedDataPoints) {
+                fullAnalysisRef.current = {
+                    ...fullAnalysisRef.current,
+                    dataPoints: fullCombinedDataPoints,
+                }
+                fullAnalysisRef.current.durationMs =
+                    fullCombinedDataPoints.length * analysis.segmentDurationMs
             }
-            fullAnalysisRef.current.durationMs =
-                fullCombinedDataPoints.length * analysis.segmentDurationMs
             savedAnalysisData.dataPoints = combinedDataPoints
             savedAnalysisData.bitDepth =
                 analysis.bitDepth || savedAnalysisData.bitDepth
@@ -284,9 +295,11 @@ export function useAudioRecorder({
                 min: newMin,
                 max: newMax,
             }
-            fullAnalysisRef.current.amplitudeRange = {
-                min: newMin,
-                max: newMax,
+            if (keepFullAnalysis) {
+                fullAnalysisRef.current.amplitudeRange = {
+                    min: newMin,
+                    max: newMax,
+                }
             }
 
             logger?.debug(
@@ -523,6 +536,7 @@ export function useAudioRecorder({
                 onAudioStream,
                 onRecordingInterrupted,
                 onAudioAnalysis,
+                keepFullAnalysis: _keepFullAnalysis,
                 ...options
             } = validatedOptions
             const { enableProcessing } = options
@@ -579,6 +593,7 @@ export function useAudioRecorder({
                 onAudioStream,
                 onRecordingInterrupted,
                 onAudioAnalysis,
+                keepFullAnalysis: _keepFullAnalysis,
                 ...options
             } = recordingOptions
 
@@ -603,7 +618,14 @@ export function useAudioRecorder({
         logger?.debug(`stoping recording`)
 
         const stopResult: AudioRecording = await audioStudio.stopRecording()
-        stopResult.analysisData = fullAnalysisRef.current
+        if (shouldKeepFullAnalysis(recordingConfigRef.current)) {
+            stopResult.analysisData = fullAnalysisRef.current
+        } else {
+            // `keepFullAnalysis` is a hook-level retention policy. If a platform
+            // starts returning native analysisData in the future, keep opt-out
+            // semantics explicit and avoid leaking a full history here.
+            delete stopResult.analysisData
+        }
 
         if (analysisListenerRef.current) {
             analysisListenerRef.current.remove()