@siteed/audio-studio 3.1.0 → 3.2.0-beta.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/errors/AudioStreamError.test.ts

@@ -0,0 +1,65 @@
+import { AudioStreamError, mapStreamError } from './AudioStreamError'
+
+describe('AudioStreamError', () => {
+    it('passes through an existing AudioStreamError unchanged', () => {
+        const original = new AudioStreamError({
+            code: 'ERR_AUDIO_STREAM_CANCELLED',
+            message: 'aborted',
+            recoverable: true,
+        })
+        expect(mapStreamError(original)).toBe(original)
+    })
+
+    it('maps native FILE_NOT_FOUND code', () => {
+        const mapped = mapStreamError({ code: 'FILE_NOT_FOUND', message: 'gone' })
+        expect(mapped.code).toBe('ERR_AUDIO_STREAM_FILE_NOT_FOUND')
+        expect(mapped.recoverable).toBe(false)
+    })
+
+    it('maps unsupported codec text', () => {
+        const mapped = mapStreamError(new Error('No suitable codec for audio/opus'))
+        expect(mapped.code).toBe('ERR_AUDIO_STREAM_UNSUPPORTED_FORMAT')
+    })
+
+    it('marks cancellation as recoverable', () => {
+        const mapped = mapStreamError({
+            code: 'ERR_AUDIO_STREAM_CANCELLED',
+            message: 'user cancelled',
+        })
+        expect(mapped.code).toBe('ERR_AUDIO_STREAM_CANCELLED')
+        expect(mapped.recoverable).toBe(true)
+    })
+
+    it('falls back to UNKNOWN', () => {
+        const mapped = mapStreamError({})
+        expect(mapped.code).toBe('ERR_AUDIO_STREAM_UNKNOWN')
+    })
+
+    it('preserves nativeCode and nativeMessage', () => {
+        const mapped = mapStreamError({
+            code: 'WEIRD_NATIVE_CODE',
+            message: 'something went wrong on the bridge',
+        })
+        expect(mapped.nativeCode).toBe('WEIRD_NATIVE_CODE')
+        expect(mapped.nativeMessage).toContain('bridge')
+    })
+
+    it('serialises to a stable JSON payload', () => {
+        const err = new AudioStreamError({
+            code: 'ERR_AUDIO_STREAM_DECODE_FAILED',
+            message: 'decoder bust',
+            recoverable: false,
+            fileUri: 'file:///a.m4a',
+            platform: 'ios',
+        })
+        expect(err.toJSON()).toEqual({
+            code: 'ERR_AUDIO_STREAM_DECODE_FAILED',
+            message: 'decoder bust',
+            recoverable: false,
+            fileUri: 'file:///a.m4a',
+            platform: 'ios',
+            nativeCode: undefined,
+            nativeMessage: undefined,
+        })
+    })
+})

package/src/errors/AudioStreamError.ts

@@ -0,0 +1,185 @@
+/**
+ * Stable typed errors for `streamAudioData`. Callers can switch on `code`.
+ */
+export type AudioStreamErrorCode =
+    | 'ERR_AUDIO_STREAM_UNSUPPORTED_FORMAT'
+    | 'ERR_AUDIO_STREAM_INVALID_RANGE'
+    | 'ERR_AUDIO_STREAM_DECODE_FAILED'
+    | 'ERR_AUDIO_STREAM_CANCELLED'
+    | 'ERR_AUDIO_STREAM_PERMISSION_DENIED'
+    | 'ERR_AUDIO_STREAM_FILE_NOT_FOUND'
+    | 'ERR_AUDIO_STREAM_BACKPRESSURE_TIMEOUT'
+    | 'ERR_AUDIO_STREAM_NATIVE_UNAVAILABLE'
+    | 'ERR_AUDIO_STREAM_BUSY'
+    | 'ERR_AUDIO_STREAM_UNKNOWN'
+
+export interface AudioStreamErrorPayload {
+    code: AudioStreamErrorCode
+    message: string
+    recoverable: boolean
+    fileUri?: string
+    platform?: string
+    nativeCode?: string
+    nativeMessage?: string
+}
+
+const RECOVERABLE: AudioStreamErrorCode[] = [
+    'ERR_AUDIO_STREAM_CANCELLED',
+    'ERR_AUDIO_STREAM_BUSY',
+    'ERR_AUDIO_STREAM_BACKPRESSURE_TIMEOUT',
+    'ERR_AUDIO_STREAM_PERMISSION_DENIED',
+]
+
+export class AudioStreamError extends Error {
+    readonly code: AudioStreamErrorCode
+    readonly recoverable: boolean
+    readonly fileUri?: string
+    readonly platform?: string
+    readonly nativeCode?: string
+    readonly nativeMessage?: string
+
+    constructor(payload: AudioStreamErrorPayload) {
+        super(payload.message)
+        this.name = 'AudioStreamError'
+        this.code = payload.code
+        this.recoverable = payload.recoverable
+        this.fileUri = payload.fileUri
+        this.platform = payload.platform
+        this.nativeCode = payload.nativeCode
+        this.nativeMessage = payload.nativeMessage
+    }
+
+    toJSON(): AudioStreamErrorPayload {
+        return {
+            code: this.code,
+            message: this.message,
+            recoverable: this.recoverable,
+            fileUri: this.fileUri,
+            platform: this.platform,
+            nativeCode: this.nativeCode,
+            nativeMessage: this.nativeMessage,
+        }
+    }
+}
+
+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 normalizeCode(raw: string | undefined): AudioStreamErrorCode | null {
+    if (!raw) return null
+    const upper = raw.toUpperCase()
+    if (upper.startsWith('ERR_AUDIO_STREAM_')) {
+        const known: AudioStreamErrorCode[] = [
+            'ERR_AUDIO_STREAM_UNSUPPORTED_FORMAT',
+            'ERR_AUDIO_STREAM_INVALID_RANGE',
+            'ERR_AUDIO_STREAM_DECODE_FAILED',
+            'ERR_AUDIO_STREAM_CANCELLED',
+            'ERR_AUDIO_STREAM_PERMISSION_DENIED',
+            'ERR_AUDIO_STREAM_FILE_NOT_FOUND',
+            'ERR_AUDIO_STREAM_BACKPRESSURE_TIMEOUT',
+            'ERR_AUDIO_STREAM_NATIVE_UNAVAILABLE',
+            'ERR_AUDIO_STREAM_BUSY',
+            'ERR_AUDIO_STREAM_UNKNOWN',
+        ]
+        if ((known as string[]).includes(upper)) {
+            return upper as AudioStreamErrorCode
+        }
+    }
+    if (upper.includes('FILE_NOT_FOUND') || upper === 'ENOENT') {
+        return 'ERR_AUDIO_STREAM_FILE_NOT_FOUND'
+    }
+    if (upper.includes('PERMISSION') || upper === 'EACCES') {
+        return 'ERR_AUDIO_STREAM_PERMISSION_DENIED'
+    }
+    if (
+        upper.includes('UNSUPPORTED') ||
+        upper.includes('NO_SUITABLE_CODEC') ||
+        upper.includes('NO SUITABLE CODEC') ||
+        upper.includes('NOT SUPPORTED')
+    ) {
+        return 'ERR_AUDIO_STREAM_UNSUPPORTED_FORMAT'
+    }
+    if (
+        upper.includes('INVALID_RANGE') ||
+        upper.includes('OUT_OF_RANGE') ||
+        upper.includes('INVALID_TIME')
+    ) {
+        return 'ERR_AUDIO_STREAM_INVALID_RANGE'
+    }
+    if (upper.includes('CANCELLED') || upper.includes('CANCELED')) {
+        return 'ERR_AUDIO_STREAM_CANCELLED'
+    }
+    if (upper.includes('BUSY')) {
+        return 'ERR_AUDIO_STREAM_BUSY'
+    }
+    if (upper.includes('BACKPRESSURE')) {
+        return 'ERR_AUDIO_STREAM_BACKPRESSURE_TIMEOUT'
+    }
+    if (
+        upper.includes('DECODE') ||
+        upper.includes('CODEC') ||
+        upper.includes('MALFORMED')
+    ) {
+        return 'ERR_AUDIO_STREAM_DECODE_FAILED'
+    }
+    return null
+}
+
+export function mapStreamError(
+    err: unknown,
+    fileUri?: string,
+    platform?: string
+): AudioStreamError {
+    if (err instanceof AudioStreamError) return err
+
+    const nativeMessage = getNativeMessage(err)
+    const nativeCode = getNativeCode(err)
+    const lower = nativeMessage.toLowerCase()
+
+    let code =
+        normalizeCode(nativeCode) ??
+        normalizeCode(nativeMessage) ??
+        'ERR_AUDIO_STREAM_UNKNOWN'
+
+    if (code === 'ERR_AUDIO_STREAM_UNKNOWN') {
+        if (lower.includes('not found') || lower.includes('does not exist')) {
+            code = 'ERR_AUDIO_STREAM_FILE_NOT_FOUND'
+        } else if (
+            lower.includes('unsupported') ||
+            lower.includes('no suitable codec')
+        ) {
+            code = 'ERR_AUDIO_STREAM_UNSUPPORTED_FORMAT'
+        } else if (lower.includes('permission') || lower.includes('denied')) {
+            code = 'ERR_AUDIO_STREAM_PERMISSION_DENIED'
+        } else if (lower.includes('decode') || lower.includes('codec')) {
+            code = 'ERR_AUDIO_STREAM_DECODE_FAILED'
+        } else if (lower.includes('cancel')) {
+            code = 'ERR_AUDIO_STREAM_CANCELLED'
+        }
+    }
+
+    return new AudioStreamError({
+        code,
+        message: `Audio stream failed (${code}): ${nativeMessage}`,
+        recoverable: RECOVERABLE.includes(code),
+        fileUri,
+        platform,
+        nativeCode,
+        nativeMessage,
+    })
+}

package/src/index.ts

@@ -19,6 +19,10 @@ import {
     useSharedAudioRecorder,
 } from './AudioRecorder.provider'
 import AudioStudioModule from './AudioStudioModule'
+import {
+    getAudioDecodeCapabilities,
+    streamAudioData,
+} from './streamAudioData'
 import { trimAudio } from './trimAudio'
 import { useAudioRecorder } from './useAudioRecorder'
 
@@ -44,6 +48,7 @@ export { AudioDeviceManager, audioDeviceManager } from './AudioDeviceManager'
 export { useAudioDevices } from './hooks/useAudioDevices'
 
 export { setMelSpectrogramWasmUrl } from './AudioAnalysis/wasmConfig'
+export { extractPreviewBars } from './AudioAnalysis/extractPreviewBars'
 
 export {
     AudioRecorderProvider,
@@ -53,6 +58,8 @@ export {
     extractPreview,
     trimAudio,
     extractAudioData,
+    streamAudioData,
+    getAudioDecodeCapabilities,
     extractMelSpectrogram,
     initMelStreamingWasm,
     computeMelFrameWasm,
@@ -61,6 +68,33 @@ export {
     useSharedAudioRecorder,
 }
 
+export {
+    AudioExtractionError,
+    mapExtractionError,
+} from './errors/AudioExtractionError'
+export type {
+    AudioExtractionErrorCode,
+    AudioExtractionErrorPayload,
+} from './errors/AudioExtractionError'
+
+export {
+    AudioStreamError,
+    mapStreamError,
+} from './errors/AudioStreamError'
+export type {
+    AudioStreamErrorCode,
+    AudioStreamErrorPayload,
+} from './errors/AudioStreamError'
+
+export type {
+    StreamAudioDataOptions,
+    StreamAudioDataChunk,
+    StreamAudioDataProgress,
+    StreamAudioDataResult,
+    StreamAudioDataCallbacks,
+    AudioDecodeCapabilities,
+} from './streamAudioData'
+
 // Export all types
 export type * from './AudioAnalysis/AudioAnalysis.types'
 export type * from './AudioStudio.types'