@siteed/audio-studio 3.1.1 → 3.2.0

package/src/errors/AudioStreamError.test.ts

@@ -0,0 +1,92 @@
+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('maps backpressure timeout as recoverable', () => {
+        const mapped = mapStreamError({
+            code: 'ERR_AUDIO_STREAM_BACKPRESSURE_TIMEOUT',
+            message: 'ack timed out',
+        })
+        expect(mapped.code).toBe('ERR_AUDIO_STREAM_BACKPRESSURE_TIMEOUT')
+        expect(mapped.recoverable).toBe(true)
+    })
+
+    it('falls back to UNKNOWN', () => {
+        const mapped = mapStreamError({})
+        expect(mapped.code).toBe('ERR_AUDIO_STREAM_UNKNOWN')
+    })
+
+    it('warns when native returns an unknown audio stream code', () => {
+        const warn = jest.spyOn(console, 'warn').mockImplementation(() => {})
+        const mapped = mapStreamError({
+            code: 'ERR_AUDIO_STREAM_FOOBAR',
+            message: 'new native code',
+        })
+        expect(mapped.code).toBe('ERR_AUDIO_STREAM_UNKNOWN')
+        expect(warn).toHaveBeenCalledWith(
+            '[AudioStreamError] Unknown native audio stream error code: ERR_AUDIO_STREAM_FOOBAR'
+        )
+        warn.mockRestore()
+    })
+
+    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,199 @@
+/**
+ * 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 isUnknownAudioStreamCode(raw: string | undefined): boolean {
+    if (!raw) return false
+    return (
+        raw.toUpperCase().startsWith('ERR_AUDIO_STREAM_') &&
+        normalizeCode(raw) === null
+    )
+}
+
+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()
+
+    if (isUnknownAudioStreamCode(nativeCode)) {
+        console.warn(
+            `[AudioStreamError] Unknown native audio stream error code: ${nativeCode}`
+        )
+    }
+
+    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'
 
@@ -54,6 +58,8 @@ export {
     extractPreview,
     trimAudio,
     extractAudioData,
+    streamAudioData,
+    getAudioDecodeCapabilities,
     extractMelSpectrogram,
     initMelStreamingWasm,
     computeMelFrameWasm,
@@ -71,6 +77,24 @@ export type {
     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'