@siteed/audio-studio 3.2.1-beta.0 → 3.2.1-beta.2

package/src/useAudioRecorder.tsx

@@ -10,7 +10,9 @@ import {
     AudioStreamStatus,
     CompressionInfo,
     ConsoleLike,
+    MaxDurationReachedEvent,
     RecordingConfig,
+    RecordingStopReason,
     StartRecordingResult,
 } from './AudioStudio.types'
 import AudioStudioModule from './AudioStudioModule'
@@ -19,9 +21,10 @@ import {
     addAudioAnalysisListener,
     addAudioEventListener,
     AudioEventPayload,
+    addMaxDurationReachedListener,
     addRecordingInterruptionListener,
 } from './events'
-import { cleanNativeOptions } from './utils/cleanNativeOptions'
+import { createNativeRecordingOptions } from './utils/nativeRecordingOptions'
 
 export interface UseAudioRecorderProps {
     logger?: ConsoleLike
@@ -41,6 +44,9 @@ export interface UseAudioRecorderState {
     size: number
     compression?: CompressionInfo
     analysisData?: AudioAnalysis
+    maxDurationMs?: number
+    maxDurationReached?: boolean
+    lastRecordingReason?: RecordingStopReason
 }
 
 interface RecorderReducerState {
@@ -50,10 +56,19 @@ interface RecorderReducerState {
     size: number
     compression?: CompressionInfo
     analysisData?: AudioAnalysis
+    maxDurationMs?: number
+    maxDurationReached?: boolean
+    lastRecordingReason?: RecordingStopReason
 }
 
 type RecorderAction =
-    | { type: 'START' | 'STOP' | 'PAUSE' | 'RESUME' }
+    | { type: 'START' | 'PAUSE' | 'RESUME' }
+    | {
+          type: 'STOP'
+          payload: {
+              reason: RecordingStopReason
+          }
+      }
     | {
           type: 'UPDATE_RECORDING_STATE'
           payload: {
@@ -67,8 +82,14 @@ type RecorderAction =
               durationMs: number
               size: number
               compression?: CompressionInfo
+              maxDurationMs?: number
+              maxDurationReached?: boolean
           }
       }
+    | {
+          type: 'MAX_DURATION_REACHED'
+          payload: MaxDurationReachedEvent
+      }
     | { type: 'UPDATE_ANALYSIS'; payload: AudioAnalysis }
 
 const defaultAnalysis: AudioAnalysis = {
@@ -90,6 +111,42 @@ const defaultAnalysis: AudioAnalysis = {
     extractionTimeMs: 0,
 }
 
+function finiteOrZero(value: number): number {
+    return Number.isFinite(value) ? value : 0
+}
+
+function sanitizeSerializableValue<T>(value: T): T {
+    if (typeof value === 'number') {
+        return finiteOrZero(value) as T
+    }
+
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeSerializableValue(item)) as T
+    }
+
+    if (value && typeof value === 'object') {
+        const sanitized: Record<string, unknown> = {}
+
+        for (const [key, nestedValue] of Object.entries(
+            value as Record<string, unknown>
+        )) {
+            sanitized[key] = sanitizeSerializableValue(nestedValue)
+        }
+
+        return sanitized as T
+    }
+
+    return value
+}
+
+function createSerializableAnalysis(analysis: AudioAnalysis): AudioAnalysis {
+    return sanitizeSerializableValue(analysis)
+}
+
+function createRecordingSnapshot(recording: AudioRecording): AudioRecording {
+    return sanitizeSerializableValue(recording)
+}
+
 function audioRecorderReducer(
     state: RecorderReducerState,
     action: RecorderAction
@@ -104,6 +161,9 @@ function audioRecorderReducer(
                 size: 0,
                 compression: undefined,
                 analysisData: defaultAnalysis,
+                maxDurationMs: undefined,
+                maxDurationReached: false,
+                lastRecordingReason: undefined,
             }
         case 'STOP':
             return {
@@ -114,6 +174,9 @@ function audioRecorderReducer(
                 size: 0,
                 compression: undefined,
                 analysisData: undefined,
+                lastRecordingReason: action.payload.reason,
+                // Preserve max-duration state after stop so UI and agentic
+                // validation can explain why recording ended. START resets it.
             }
         case 'PAUSE':
             return { ...state, isPaused: true, isRecording: false }
@@ -138,9 +201,17 @@ function audioRecorderReducer(
                           format: action.payload.compression.format,
                       }
                     : undefined,
+                maxDurationMs: action.payload.maxDurationMs,
+                maxDurationReached: action.payload.maxDurationReached,
             }
             return newState
         }
+        case 'MAX_DURATION_REACHED':
+            return {
+                ...state,
+                maxDurationMs: action.payload.maxDurationMs,
+                maxDurationReached: true,
+            }
         case 'UPDATE_ANALYSIS':
             return {
                 ...state,
@@ -176,6 +247,9 @@ export function useAudioRecorder({
         size: 0,
         compression: undefined,
         analysisData: undefined,
+        maxDurationMs: undefined,
+        maxDurationReached: false,
+        lastRecordingReason: undefined,
     })
 
     const startResultRef = useRef<StartRecordingResult | null>(null)
@@ -208,9 +282,13 @@ export function useAudioRecorder({
         durationMs: 0,
         size: 0,
         compression: undefined as CompressionInfo | undefined,
+        maxDurationMs: undefined as number | undefined,
+        maxDurationReached: false,
     })
 
     const recordingConfigRef = useRef<RecordingConfig | null>(null)
+    const maxDurationHandledRef = useRef(false)
+    const stopFinalizationRef = useRef<Promise<AudioRecording> | null>(null)
 
     // Generate unique instance ID for debugging
     const instanceId = useId().replace(/:/g, '').slice(0, 5)
@@ -442,6 +520,121 @@ export function useAudioRecorder({
         []
     )
 
+    const finalizeRecordingStop = useCallback(
+        async (reason: RecordingStopReason) => {
+            if (stopFinalizationRef.current) {
+                return stopFinalizationRef.current
+            }
+
+            const finalizePromise = (async () => {
+                const nativeStopResult: AudioRecording | null =
+                    await audioStudio.stopRecording()
+
+                if (!nativeStopResult) {
+                    throw new Error('Failed to stop recording')
+                }
+
+                const stopResult = createRecordingSnapshot(nativeStopResult)
+
+                if (shouldKeepFullAnalysis(recordingConfigRef.current)) {
+                    stopResult.analysisData = createSerializableAnalysis(
+                        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()
+                    analysisListenerRef.current = null
+                }
+                onAudioStreamRef.current = null
+
+                stateRef.current.isRecording = false
+                stateRef.current.isPaused = false
+
+                // Note: We deliberately DON'T clear recordingConfigRef here to preserve callbacks.
+                logger?.debug(`recording stopped`, stopResult)
+                maxDurationHandledRef.current = false
+                dispatch({
+                    type: 'STOP',
+                    payload: { reason },
+                })
+
+                const stoppedCallback =
+                    recordingConfigRef.current?.onRecordingStopped
+                if (stoppedCallback) {
+                    try {
+                        void Promise.resolve(
+                            stoppedCallback(stopResult, reason)
+                        ).catch((error) => {
+                            logger?.error(
+                                `Error in recording stopped callback:`,
+                                error
+                            )
+                        })
+                    } catch (error) {
+                        logger?.error(
+                            `Error in recording stopped callback:`,
+                            error
+                        )
+                    }
+                }
+
+                return stopResult
+            })()
+
+            stopFinalizationRef.current = finalizePromise
+            try {
+                return await finalizePromise
+            } finally {
+                stopFinalizationRef.current = null
+            }
+        },
+        [audioStudio, dispatch, logger]
+    )
+
+    const handleMaxDurationReached = useCallback(
+        async (event: MaxDurationReachedEvent) => {
+            if (maxDurationHandledRef.current) {
+                return
+            }
+
+            maxDurationHandledRef.current = true
+            const config = recordingConfigRef.current
+            const callbackEvent: MaxDurationReachedEvent = {
+                ...event,
+                autoStopped:
+                    event.autoStopped || !!config?.autoStopOnMaxDuration,
+            }
+
+            stateRef.current.maxDurationMs = callbackEvent.maxDurationMs
+            stateRef.current.maxDurationReached = true
+            dispatch({
+                type: 'MAX_DURATION_REACHED',
+                payload: callbackEvent,
+            })
+
+            try {
+                config?.onMaxDurationReached?.(callbackEvent)
+            } catch (error) {
+                logger?.error(`Error in max duration callback:`, error)
+            }
+
+            if (config?.autoStopOnMaxDuration && stateRef.current.isRecording) {
+                try {
+                    await finalizeRecordingStop('maxDuration')
+                } catch (error) {
+                    logger?.error(`Error auto-stopping on max duration:`, error)
+                }
+            }
+        },
+        [dispatch, finalizeRecordingStop, logger]
+    )
+
     const checkStatus = useCallback(async () => {
         try {
             const status: AudioStreamStatus = audioStudio.status()
@@ -450,6 +643,22 @@ export function useAudioRecorder({
                 status.compression
             )
 
+            if (
+                status.maxDurationReached === true &&
+                status.maxDurationMs != null &&
+                !stateRef.current.maxDurationReached
+            ) {
+                await handleMaxDurationReached({
+                    durationMs: status.durationMs,
+                    maxDurationMs: status.maxDurationMs,
+                    overrunMs: Math.max(
+                        0,
+                        status.durationMs - status.maxDurationMs
+                    ),
+                    autoStopped: false,
+                })
+            }
+
             // Only dispatch if values actually changed
             if (
                 status.isRecording !== stateRef.current.isRecording ||
@@ -466,26 +675,45 @@ export function useAudioRecorder({
                 })
             }
 
+            const statusMaxDurationReached = status.maxDurationReached ?? false
+            const preserveStoppedMaxDuration =
+                !status.isRecording &&
+                !status.isPaused &&
+                stateRef.current.maxDurationReached &&
+                !statusMaxDurationReached
+            const nextMaxDurationMs = preserveStoppedMaxDuration
+                ? stateRef.current.maxDurationMs
+                : status.maxDurationMs
+            const nextMaxDurationReached = preserveStoppedMaxDuration
+                ? true
+                : statusMaxDurationReached
+
             if (
                 status.durationMs !== stateRef.current.durationMs ||
-                status.size !== stateRef.current.size
+                status.size !== stateRef.current.size ||
+                nextMaxDurationMs !== stateRef.current.maxDurationMs ||
+                nextMaxDurationReached !== stateRef.current.maxDurationReached
             ) {
                 stateRef.current.durationMs = status.durationMs
                 stateRef.current.size = status.size
                 stateRef.current.compression = status.compression
+                stateRef.current.maxDurationMs = nextMaxDurationMs
+                stateRef.current.maxDurationReached = nextMaxDurationReached
                 dispatch({
                     type: 'UPDATE_STATUS',
                     payload: {
                         durationMs: status.durationMs,
                         size: status.size,
                         compression: status.compression,
+                        maxDurationMs: nextMaxDurationMs,
+                        maxDurationReached: nextMaxDurationReached,
                     },
                 })
             }
         } catch (error) {
             logger?.error(`Error getting status:`, error)
         }
-    }, [audioStudio, logger]) // Only depend on audioStudio and logger
+    }, [audioStudio, handleMaxDurationReached, logger])
 
     // Update ref when state changes
     useEffect(() => {
@@ -495,6 +723,8 @@ export function useAudioRecorder({
             durationMs: state.durationMs,
             size: state.size,
             compression: state.compression,
+            maxDurationMs: state.maxDurationMs,
+            maxDurationReached: state.maxDurationReached ?? false,
         }
     }, [
         state.isRecording,
@@ -502,6 +732,8 @@ export function useAudioRecorder({
         state.durationMs,
         state.size,
         state.compression,
+        state.maxDurationMs,
+        state.maxDurationReached,
     ])
 
     const startRecording = useCallback(
@@ -525,6 +757,7 @@ export function useAudioRecorder({
             }
 
             recordingConfigRef.current = validatedOptions
+            maxDurationHandledRef.current = false
             logger?.debug(
                 `start recording with validated config`,
                 validatedOptions
@@ -532,14 +765,7 @@ export function useAudioRecorder({
 
             analysisRef.current = { ...defaultAnalysis } // Reset analysis data
             fullAnalysisRef.current = { ...defaultAnalysis }
-            const {
-                onAudioStream,
-                onRecordingInterrupted,
-                onAudioAnalysis,
-                keepFullAnalysis: _keepFullAnalysis,
-                ...options
-            } = validatedOptions
-            const { enableProcessing } = options
+            const { onAudioStream, enableProcessing } = validatedOptions
 
             const maxRecentDataDuration = 10000 // TODO compute maxRecentDataDuration based on screen dimensions
             if (typeof onAudioStream === 'function') {
@@ -548,8 +774,10 @@ export function useAudioRecorder({
                 logger?.warn(`onAudioStream is not a function`, onAudioStream)
                 onAudioStreamRef.current = null
             }
-            // Strip undefined values and functions that can't cross the native bridge
-            const cleanOptions = cleanNativeOptions(options)
+            // Strip hook-only values and undefineds that can't cross the native bridge.
+            // autoStopOnMaxDuration stays hook-owned so finalization can expose
+            // the same AudioRecording result as a manual stop.
+            const cleanOptions = createNativeRecordingOptions(validatedOptions)
             const startResult: StartRecordingResult =
                 await audioStudio.startRecording(cleanOptions)
             dispatch({ type: 'START' })
@@ -589,13 +817,7 @@ export function useAudioRecorder({
 
             analysisRef.current = { ...defaultAnalysis } // Reset analysis data
             fullAnalysisRef.current = { ...defaultAnalysis }
-            const {
-                onAudioStream,
-                onRecordingInterrupted,
-                onAudioAnalysis,
-                keepFullAnalysis: _keepFullAnalysis,
-                ...options
-            } = recordingOptions
+            const { onAudioStream } = recordingOptions
 
             // Store onAudioStream for later use when recording starts
             if (typeof onAudioStream === 'function') {
@@ -605,8 +827,8 @@ export function useAudioRecorder({
                 onAudioStreamRef.current = null
             }
 
-            // Strip undefined values and functions that can't cross the native bridge
-            const cleanOptions = cleanNativeOptions(options)
+            // Strip hook-only values and undefineds that can't cross the native bridge.
+            const cleanOptions = createNativeRecordingOptions(recordingOptions)
             // Call the native prepareRecording method
             await audioStudio.prepareRecording(cleanOptions)
             logger?.debug(`recording prepared successfully`)
@@ -616,28 +838,8 @@ export function useAudioRecorder({
 
     const stopRecording = useCallback(async () => {
         logger?.debug(`stoping recording`)
-
-        const stopResult: AudioRecording = await audioStudio.stopRecording()
-        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()
-            analysisListenerRef.current = null
-        }
-        onAudioStreamRef.current = null
-
-        // Note: We deliberately DON'T clear recordingConfigRef here to preserve interruption callback
-        logger?.debug(`recording stopped`, stopResult)
-        dispatch({ type: 'STOP' })
-        return stopResult
-    }, [dispatch])
+        return finalizeRecordingStop('manual')
+    }, [finalizeRecordingStop, logger])
 
     const pauseRecording = useCallback(async () => {
         logger?.debug(`pause recording`)
@@ -653,6 +855,16 @@ export function useAudioRecorder({
         return resumeResult
     }, [dispatch])
 
+    useEffect(() => {
+        const subscription = addMaxDurationReachedListener(async (event) => {
+            await handleMaxDurationReached(event)
+        })
+
+        return () => {
+            subscription.remove()
+        }
+    }, [handleMaxDurationReached])
+
     useEffect(() => {
         let intervalId: ReturnType<typeof setInterval> | undefined
 
@@ -802,5 +1014,8 @@ export function useAudioRecorder({
         size: state.size,
         compression: state.compression,
         analysisData: state.analysisData,
+        maxDurationMs: state.maxDurationMs,
+        maxDurationReached: state.maxDurationReached,
+        lastRecordingReason: state.lastRecordingReason,
     }
 }

package/src/utils/nativeRecordingOptions.test.ts

@@ -0,0 +1,29 @@
+import { createNativeRecordingOptions } from './nativeRecordingOptions'
+
+describe('createNativeRecordingOptions', () => {
+    it('keeps maxDurationMs native but leaves auto-stop finalization hook-owned', () => {
+        const nativeOptions = createNativeRecordingOptions({
+            maxDurationMs: 1500,
+            autoStopOnMaxDuration: true,
+            onMaxDurationReached: jest.fn(),
+            onRecordingStopped: jest.fn(),
+            onRecordingInterrupted: jest.fn(),
+            onAudioAnalysis: jest.fn(),
+            onAudioStream: jest.fn(),
+            keepFullAnalysis: true,
+            sampleRate: 16000,
+        })
+
+        expect(nativeOptions).toMatchObject({
+            maxDurationMs: 1500,
+            sampleRate: 16000,
+        })
+        expect(nativeOptions).not.toHaveProperty('autoStopOnMaxDuration')
+        expect(nativeOptions).not.toHaveProperty('onMaxDurationReached')
+        expect(nativeOptions).not.toHaveProperty('onRecordingStopped')
+        expect(nativeOptions).not.toHaveProperty('onRecordingInterrupted')
+        expect(nativeOptions).not.toHaveProperty('onAudioAnalysis')
+        expect(nativeOptions).not.toHaveProperty('onAudioStream')
+        expect(nativeOptions).not.toHaveProperty('keepFullAnalysis')
+    })
+})

package/src/utils/nativeRecordingOptions.ts

@@ -0,0 +1,20 @@
+import { RecordingConfig } from '../AudioStudio.types'
+import { cleanNativeOptions } from './cleanNativeOptions'
+
+export function createNativeRecordingOptions(recordingOptions: RecordingConfig) {
+    const {
+        onAudioStream,
+        onRecordingInterrupted,
+        onMaxDurationReached,
+        onRecordingStopped,
+        onAudioAnalysis,
+        keepFullAnalysis: _keepFullAnalysis,
+        // Keep hook-owned auto-stop out of the native bridge so the hook can
+        // reuse the same finalization path as manual stop and expose the
+        // resulting AudioRecording consistently.
+        autoStopOnMaxDuration: _autoStopOnMaxDuration,
+        ...options
+    } = recordingOptions
+
+    return cleanNativeOptions(options)
+}