@siteed/audio-studio 3.1.0 → 3.1.1

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/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'