@siteed/audio-studio 3.0.5 → 3.1.1

package/ios/AudioProcessor.swift

@@ -1022,6 +1022,105 @@ public class AudioProcessor {
     ///   - endTimeMs: Optional end time in milliseconds
     ///   - featureOptions: The features to extract
     /// - Returns: An `AudioAnalysisData` object containing the extracted features
+    public func extractPreviewBars(
+        numberOfBars: Int,
+        startTimeMs: Double? = nil,
+        endTimeMs: Double? = nil,
+        silenceRmsThreshold: Float = 0.01
+    ) -> [String: Any]? {
+        guard let audioFile = audioFile else {
+            reject("FILE_NOT_INITIALIZED", "Audio file is not initialized.")
+            return nil
+        }
+
+        let requestedBars = max(1, numberOfBars)
+        let sampleRate = audioFile.fileFormat.sampleRate
+        let totalDurationMs = Double(audioFile.length) / sampleRate * 1000
+        let effectiveStartMs = max(0, startTimeMs ?? 0)
+        let effectiveEndMs = min(endTimeMs ?? totalDurationMs, totalDurationMs)
+        let durationMs = max(1, effectiveEndMs - effectiveStartMs)
+        let startFrame = AVAudioFramePosition(effectiveStartMs * sampleRate / 1000.0)
+        let endFrame = AVAudioFramePosition(effectiveEndMs * sampleRate / 1000.0)
+        let samplesInRange = Int(endFrame - startFrame)
+
+        guard samplesInRange > 0 else {
+            reject("INVALID_RANGE", "Invalid sample range: contains no samples")
+            return nil
+        }
+
+        let framesPerBar = max(1, samplesInRange / requestedBars)
+        let startTime = CACurrentMediaTime()
+        var bars: [[String: Any]] = []
+        bars.reserveCapacity(requestedBars)
+        var minAmplitude: Float = .greatestFiniteMagnitude
+        var maxAmplitude: Float = -.greatestFiniteMagnitude
+        var minRms: Float = .greatestFiniteMagnitude
+        var maxRms: Float = -.greatestFiniteMagnitude
+
+        for index in 0..<requestedBars {
+            let barStartFrame = startFrame + AVAudioFramePosition(index * framesPerBar)
+            let barEndFrame = min(startFrame + AVAudioFramePosition((index + 1) * framesPerBar), endFrame)
+            let framesToRead = AVAudioFrameCount(barEndFrame - barStartFrame)
+            if framesToRead == 0 { break }
+
+            do {
+                audioFile.framePosition = barStartFrame
+                guard let buffer = AVAudioPCMBuffer(pcmFormat: audioFile.processingFormat, frameCapacity: framesToRead) else { continue }
+                try audioFile.read(into: buffer, frameCount: framesToRead)
+                guard let floatData = buffer.floatChannelData else { continue }
+
+                var sumSquares: Float = 0
+                var amplitude: Float = 0
+                for frame in 0..<Int(buffer.frameLength) {
+                    let value = floatData[0][frame]
+                    sumSquares += value * value
+                    amplitude = max(amplitude, abs(value))
+                }
+                let frameLength = max(1, Int(buffer.frameLength))
+                let rms = sqrt(sumSquares / Float(frameLength))
+                minAmplitude = min(minAmplitude, amplitude)
+                maxAmplitude = max(maxAmplitude, amplitude)
+                minRms = min(minRms, rms)
+                maxRms = max(maxRms, rms)
+
+                let startBarTimeMs = Double(barStartFrame - startFrame) / Double(samplesInRange) * durationMs
+                let endBarTimeMs = Double(barEndFrame - startFrame) / Double(samplesInRange) * durationMs
+                bars.append([
+                    "id": index,
+                    "amplitude": min(max(amplitude, 0), 1),
+                    "rms": min(max(rms, 0), 1),
+                    "silent": rms < silenceRmsThreshold,
+                    "startTimeMs": startBarTimeMs,
+                    "endTimeMs": max(startBarTimeMs, endBarTimeMs)
+                ])
+            } catch {
+                reject("AUDIO_READ_ERROR", "Error reading audio data: \(error.localizedDescription)")
+                return nil
+            }
+        }
+
+        guard !bars.isEmpty else {
+            reject("PROCESSING_ERROR", "No preview bars were generated")
+            return nil
+        }
+
+        let bitDepth = audioFile.fileFormat.settings[AVLinearPCMBitDepthKey] as? Int ?? 16
+        let extractionTimeMs = Float((CACurrentMediaTime() - startTime) * 1000)
+        return [
+            "bars": bars,
+            "durationMs": durationMs,
+            "sampleRate": Int(sampleRate),
+            "numberOfChannels": Int(audioFile.processingFormat.channelCount),
+            "bitDepth": bitDepth,
+            "samples": samplesInRange,
+            "requestedNumberOfBars": requestedBars,
+            "barDurationMs": durationMs / Double(bars.count),
+            "amplitudeRange": ["min": minAmplitude, "max": maxAmplitude],
+            "rmsRange": ["min": minRms, "max": maxRms],
+            "extractionTimeMs": extractionTimeMs
+        ]
+    }
+
     public func extractPreview(
         numberOfPoints: Int,
         startTimeMs: Double? = nil,

package/ios/AudioStreamManager.swift

@@ -14,6 +14,7 @@ import UserNotifications
 
 // Constants
 internal let WAV_HEADER_SIZE: Int64 = 44  // Standard WAV header is 44 bytes
+internal let MIN_AAC_COMPRESSED_SAMPLE_RATE: Double = 44100.0
 
 // Helper to convert to little-endian byte array
 extension UInt32 {
@@ -152,6 +153,7 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
     
     // Add property to track auto-resume preference
     private var autoResumeAfterInterruption: Bool = false
+    private var pausedBySystemInterruption: Bool = false
     
     // Add these properties
     private var emissionInterval: TimeInterval = 1.0  // Default 1 second
@@ -167,6 +169,28 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
     private var cachedWavFileSize: Int64 = 0
     private var cachedCompressedFileSize: Int64 = 0
 
+    /// Returns an AVAudioRecorder-compatible sample rate for AAC sidecar files.
+    ///
+    /// The primary WAV path can resample emitted PCM to `settings.sampleRate`,
+    /// but the compressed sidecar is produced by AVAudioRecorder directly from
+    /// the active audio session. AVAudioRecorder fails to prepare AAC/M4A files
+    /// below 44.1 kHz, so keep valid requested rates and otherwise use the
+    /// active session rate when available, falling back to 44.1 kHz.
+    internal static func compatibleAACCompressedSampleRate(
+        requestedSampleRate: Double,
+        sessionSampleRate: Double
+    ) -> Double {
+        if requestedSampleRate >= MIN_AAC_COMPRESSED_SAMPLE_RATE {
+            return requestedSampleRate
+        }
+
+        if sessionSampleRate.isFinite && sessionSampleRate >= MIN_AAC_COMPRESSED_SAMPLE_RATE {
+            return sessionSampleRate
+        }
+
+        return MIN_AAC_COMPRESSED_SAMPLE_RATE
+    }
+
     /// Initializes the AudioStreamManager
     override init() {
         super.init()
@@ -231,7 +255,7 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
             // Store the pause start time if not already paused
             if !wasSuspended {
                 currentPauseStart = Date()
-                pauseRecording()
+                pauseRecording(isSystemInterruption: true)
             }
             
             // Always notify delegate of interruption
@@ -248,17 +272,17 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
             if let optionsValue = userInfo[AVAudioSessionInterruptionOptionKey] as? UInt {
                 let options = AVAudioSession.InterruptionOptions(rawValue: optionsValue)
                 Logger.debug("AudioStreamManager", "Interruption options - shouldResume: \(options.contains(.shouldResume))")
-                
-                // Calculate pause duration if we have a pause start time
-                if let pauseStart = currentPauseStart {
-                    let pauseDuration = Date().timeIntervalSince(pauseStart)
-                    totalPausedDuration += pauseDuration
-                    currentPauseStart = nil
-                    Logger.debug("AudioStreamManager", "Added interruption pause duration: \(pauseDuration), total paused: \(totalPausedDuration)")
-                }
-                
-                // For phone calls, we should auto-resume if enabled, regardless of previous pause state
-                if autoResumeAfterInterruption && isRecording {
+
+                // Auto-resume only if this interruption paused the recording.
+                // If the user had already paused, preserve that intent.
+                // Keep currentPauseStart active until the actual resume so duration accounting
+                // excludes the full paused interval, including any post-interruption delay.
+                if AutoResumePolicy.shouldAutoResume(
+                    autoResumeAfterInterruption: autoResumeAfterInterruption,
+                    isRecording: isRecording,
+                    isPaused: isPaused,
+                    pausedBySystemInterruption: pausedBySystemInterruption
+                ) {
                     // Add a longer delay for phone calls and ensure proper session setup
                     DispatchQueue.main.asyncAfter(deadline: .now() + 2.0) { [weak self] in
                         guard let self = self else { return }
@@ -484,6 +508,7 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
                 // If we can't restart, officially pause the recording
                 if !isPaused {
                     isPaused = true
+                    pausedBySystemInterruption = false
                     // Notify delegate
                     delegate?.audioStreamManager(self, didPauseRecording: Date())
                 }
@@ -906,6 +931,7 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
         lastEmittedCompressedSize = 0
         lastEmittedCompressedSizeAnalysis = 0
         isPaused = false
+        pausedBySystemInterruption = false
 
         // Create recording file first (unless primary output is disabled)
         if settings.output.primary.enabled {
@@ -995,10 +1021,27 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
 
             // Setup compressed recording if enabled
             if settings.output.compressed.enabled {
+                let isAACCompressedOutput = settings.output.compressed.format == "aac"
+                let compressedSampleRate: Double
+                if isAACCompressedOutput {
+                    compressedSampleRate = Self.compatibleAACCompressedSampleRate(
+                        requestedSampleRate: settings.sampleRate,
+                        sessionSampleRate: session.sampleRate
+                    )
+                } else {
+                    compressedSampleRate = settings.sampleRate
+                }
+                if isAACCompressedOutput && compressedSampleRate != settings.sampleRate {
+                    Logger.debug(
+                        "AudioStreamManager",
+                        "Adjusted compressed AAC sample rate from \(settings.sampleRate)Hz to \(compressedSampleRate)Hz for AVAudioRecorder compatibility"
+                    )
+                }
+
                 // Create compressed settings
                 let compressedSettings: [String: Any] = [
-                    AVFormatIDKey: settings.output.compressed.format == "aac" ? kAudioFormatMPEG4AAC : kAudioFormatOpus,
-                    AVSampleRateKey: Float64(settings.sampleRate),
+                    AVFormatIDKey: isAACCompressedOutput ? kAudioFormatMPEG4AAC : kAudioFormatOpus,
+                    AVSampleRateKey: compressedSampleRate,
                     AVNumberOfChannelsKey: settings.numberOfChannels,
                     AVEncoderBitRateKey: settings.output.compressed.bitrate,
                     AVEncoderAudioQualityKey: AVAudioQuality.high.rawValue,
@@ -1135,6 +1178,7 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
             lastEmissionTimeAnalysis = Date()
             isRecording = true
             isPaused = false
+            pausedBySystemInterruption = false
             
             // Start the audio engine
             try audioEngine.start()
@@ -1221,6 +1265,7 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
         compressedFileURL = nil // Restore
         audioProcessor = nil // Restore
         recordingSettings = nil
+        pausedBySystemInterruption = false
         isPrepared = false // Restore
         // --- End restored lines and removed log ---
         
@@ -1228,7 +1273,7 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
     }
 
     /// Pauses the current audio recording.
-    func pauseRecording() {
+    func pauseRecording(isSystemInterruption: Bool = false) {
         guard isRecording, !isPaused else { return }
         
         Logger.debug("Pausing recording...")
@@ -1254,6 +1299,7 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
         
         // Update state
         isPaused = true
+        pausedBySystemInterruption = isSystemInterruption
         
         // Stop the engine but don't remove the tap
         audioEngine.pause()
@@ -1302,6 +1348,7 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
             
             // Update state
             isPaused = false
+            pausedBySystemInterruption = false
             
             // Update notification state if enabled
             if recordingSettings?.showNotification == true {
@@ -1850,6 +1897,7 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
         let wasRecording = isRecording
         isRecording = false
         isPaused = false
+        pausedBySystemInterruption = false
         isPrepared = false // Reset preparation state
         
         // If we were only prepared but never started recording, clean up and return nil
@@ -2352,6 +2400,22 @@ class AudioStreamManager: NSObject, AudioDeviceManagerDelegate {
     }
 }
 
+internal struct AutoResumePolicy {
+    /// Auto-resume only when a system interruption caused the pause.
+    /// User-initiated pauses must remain paused after the interruption ends.
+    static func shouldAutoResume(
+        autoResumeAfterInterruption: Bool,
+        isRecording: Bool,
+        isPaused: Bool,
+        pausedBySystemInterruption: Bool
+    ) -> Bool {
+        return autoResumeAfterInterruption &&
+            isRecording &&
+            isPaused &&
+            pausedBySystemInterruption
+    }
+}
+
 extension AudioStreamManager: UNUserNotificationCenterDelegate {
     func userNotificationCenter(
         _ center: UNUserNotificationCenter,

package/ios/AudioStudioModule.swift

@@ -163,6 +163,10 @@ public class AudioStudioModule: Module, AudioStreamManagerDelegate, AudioDeviceM
                 }
             })
         }
+        AsyncFunction("extractPreviewBars") { (options: [String: Any], promise: Promise) in
+            extractPreviewBars(options: options, promise: promise)
+        }
+
         
         
         /// Asynchronously starts audio recording with the given settings.
@@ -1052,6 +1056,65 @@ public class AudioStudioModule: Module, AudioStreamManagerDelegate, AudioDeviceM
     }
     
     /// Clears all audio files stored in the document directory.
+    private func extractPreviewBars(options: [String: Any], promise: Promise) {
+        Logger.debug("AudioStudioModule", "extractPreviewBars called with options: \(options)")
+        guard let fileUri = options["fileUri"] as? String else {
+            promise.reject("INVALID_ARGUMENTS", "Invalid file URI provided")
+            return
+        }
+
+        let url = URL(string: fileUri) ?? URL(fileURLWithPath: fileUri.replacingOccurrences(of: "file://", with: ""))
+        let numberOfBars = (options["numberOfBars"] as? NSNumber)?.intValue ?? 100
+        let startTimeMs = (options["startTimeMs"] as? NSNumber)?.doubleValue
+        let endTimeMs = (options["endTimeMs"] as? NSNumber)?.doubleValue
+        let decodingOptions = options["decodingOptions"] as? [String: Any]
+        let silenceRmsThreshold = (decodingOptions?["silenceRmsThreshold"] as? NSNumber)?.floatValue ?? 0.01
+
+        DispatchQueue.global().async {
+            self.resolvePreviewBars(
+                url: url,
+                numberOfBars: numberOfBars,
+                startTimeMs: startTimeMs,
+                endTimeMs: endTimeMs,
+                silenceRmsThreshold: silenceRmsThreshold,
+                promise: promise
+            )
+        }
+    }
+
+    private func resolvePreviewBars(
+        url: URL,
+        numberOfBars: Int,
+        startTimeMs: Double?,
+        endTimeMs: Double?,
+        silenceRmsThreshold: Float,
+        promise: Promise
+    ) {
+        do {
+            let audioProcessor = try previewBarsProcessor(for: url)
+            guard let result = audioProcessor.extractPreviewBars(
+                numberOfBars: numberOfBars,
+                startTimeMs: startTimeMs,
+                endTimeMs: endTimeMs,
+                silenceRmsThreshold: silenceRmsThreshold
+            ) else {
+                promise.reject("PROCESSING_ERROR", "Failed to extract preview bars")
+                return
+            }
+            promise.resolve(result)
+        } catch {
+            promise.reject("PROCESSING_ERROR", "Failed to initialize audio processor: \(error.localizedDescription)")
+        }
+    }
+
+    private func previewBarsProcessor(for url: URL) throws -> AudioProcessor {
+        return try AudioProcessor(url: url, resolve: { _ in
+            Logger.warn("AudioStudioModule", "extractPreviewBars: AudioProcessor resolve called unexpectedly.")
+        }, reject: { code, message in
+            Logger.warn("AudioStudioModule", "extractPreviewBars: AudioProcessor reject called unexpectedly: \(code) - \(message)")
+        })
+    }
+
     private func clearAudioFiles() {
         let fileURLs = listAudioFiles()  // This now returns full URLs as strings
         fileURLs.forEach { fileURLString in

package/ios/AudioStudioTests/CompressedOnlyOutputTests.swift

@@ -22,6 +22,46 @@ class CompressedOnlyOutputTests: XCTestCase {
     }
     
     // MARK: - Test Compressed-Only Output (Issue #244)
+
+    func testAACCompressedSampleRateFallsBackForLowRequestedRate() {
+        XCTAssertEqual(
+            AudioStreamManager.compatibleAACCompressedSampleRate(
+                requestedSampleRate: 16000,
+                sessionSampleRate: 48000
+            ),
+            48000,
+            "Low requested sample rates should use the active session rate when it is AAC-compatible"
+        )
+
+        XCTAssertEqual(
+            AudioStreamManager.compatibleAACCompressedSampleRate(
+                requestedSampleRate: 16000,
+                sessionSampleRate: 0
+            ),
+            44100,
+            "Low requested sample rates should never be passed directly to AVAudioRecorder for AAC"
+        )
+    }
+
+    func testAACCompressedSampleRateKeepsCompatibleRequestedRate() {
+        XCTAssertEqual(
+            AudioStreamManager.compatibleAACCompressedSampleRate(
+                requestedSampleRate: 44100,
+                sessionSampleRate: 48000
+            ),
+            44100,
+            "Already-compatible requested sample rates should preserve existing behavior"
+        )
+
+        XCTAssertEqual(
+            AudioStreamManager.compatibleAACCompressedSampleRate(
+                requestedSampleRate: 48000,
+                sessionSampleRate: 44100
+            ),
+            48000,
+            "High requested sample rates should not be reduced to the session rate"
+        )
+    }
     
     func testCompressedOnlyOutputWithAAC() {
         // Given: Recording settings with primary disabled and compressed enabled (AAC)
@@ -291,4 +331,4 @@ class TestAudioStreamDelegate: AudioStreamManagerDelegate {
     func audioStreamManager(_ manager: AudioStreamManager, didFailWithError error: String) {
         onError?(error)
     }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@siteed/audio-studio",
-    "version": "3.0.5",
+    "version": "3.1.1",
     "description": "Comprehensive audio processing library for React Native and Expo with recording, analysis, visualization, and streaming capabilities across iOS, Android, and web",
     "license": "MIT",
     "type": "commonjs",
@@ -84,11 +84,11 @@
         "lint:fix": "expo-module lint --fix",
         "test": "expo-module test",
         "test:android": "yarn test:android:unit && yarn test:android:instrumented",
-        "test:android:unit": "cd ../../apps/playground/android && ./gradlew :siteed-expo-audio-studio:test",
-        "test:android:instrumented": "cd ../../apps/playground/android && ./gradlew :siteed-expo-audio-studio:connectedAndroidTest",
-        "test:android:unit:watch": "cd ../../apps/playground/android && ./gradlew :siteed-expo-audio-studio:test --continuous",
+        "test:android:unit": "cd ../../apps/playground/android && ./gradlew :siteed-audio-studio:test",
+        "test:android:instrumented": "cd ../../apps/playground/android && ./gradlew :siteed-audio-studio:connectedAndroidTest",
+        "test:android:unit:watch": "cd ../../apps/playground/android && ./gradlew :siteed-audio-studio:test --continuous",
         "test:ios": "cd ../../apps/playground/ios && xcodebuild -workspace AudioDevPlayground.xcworkspace -scheme AudioDevPlayground -destination 'platform=iOS Simulator,name=iPhone 15' build",
-        "test:coverage": "cd ../../apps/playground/android && ./gradlew :siteed-expo-audio-studio:jacocoTestReport",
+        "test:coverage": "cd ../../apps/playground/android && ./gradlew :siteed-audio-studio:jacocoTestReport",
         "typecheck": "tsc --noEmit",
         "docgen": "typedoc src/index.ts --plugin typedoc-plugin-markdown --readme none --out ../../documentation_site/docs/api-reference/API && node ../../scripts/escape-mdx-generics.js ../../documentation_site/docs/api-reference",
         "prepare": "yarn build && node -e \"require('fs').renameSync('./plugin/build/index.d.ts', './plugin/build/index.d.cts')\"",
@@ -125,8 +125,8 @@
         "expo-modules-core": "~3.0.0",
         "jest": "^29.7.0",
         "prettier": "^3.2.5",
-        "react": "19.1.0",
-        "react-native": "0.81.5",
+        "react": "19.2.0",
+        "react-native": "0.83.6",
         "rimraf": "^6.0.1",
         "size-limit": "^11.1.4",
         "ts-node": "^10.9.2",

package/src/AudioAnalysis/AudioAnalysis.types.ts

@@ -14,6 +14,12 @@ export interface DecodingConfig {
     targetBitDepth?: BitDepth
     /** Whether to normalize audio levels (Android and Web) */
     normalizeAudio?: boolean
+    /**
+     * RMS threshold below which a segment is flagged silent.
+     * Range 0..1. Default 0.01.
+     * Currently applied as a JS post-process so the same behavior holds across iOS/Android/Web.
+     */
+    silenceRmsThreshold?: number
 }
 
 /**
@@ -163,6 +169,69 @@ export interface AudioRangeOptions {
  * Options for generating a quick preview of audio waveform.
  * This is optimized for UI rendering with a specified number of points.
  */
+export interface PreviewBar {
+    /** Stable zero-based bar identifier. */
+    id: number
+    /** Peak amplitude for this bar, normalized to 0..1. */
+    amplitude: number
+    /** Root mean square amplitude for this bar, normalized to 0..1. */
+    rms: number
+    /** Whether this bar is below the configured silence RMS threshold. */
+    silent: boolean
+    /** Bar start time in milliseconds from the extracted range start. */
+    startTimeMs: number
+    /** Bar end time in milliseconds from the extracted range start. */
+    endTimeMs: number
+}
+
+/**
+ * Compact preview-bars result for UI waveform rendering.
+ * Unlike `AudioAnalysis`, this intentionally omits full `DataPoint` feature data.
+ */
+export interface PreviewBarsResult {
+    bars: PreviewBar[]
+    durationMs: number
+    sampleRate: number
+    numberOfChannels: number
+    bitDepth: number
+    samples: number
+    /** Requested bar count before native/platform clamping. */
+    requestedNumberOfBars: number
+    /** Approximate duration represented by each bar. */
+    barDurationMs: number
+    amplitudeRange: {
+        min: number
+        max: number
+    }
+    rmsRange: {
+        min: number
+        max: number
+    }
+    extractionTimeMs: number
+}
+
+/**
+ * Options for extracting compact waveform preview bars for UI rendering.
+ */
+export interface PreviewBarsOptions extends AudioRangeOptions {
+    /** URI of the audio file to analyze */
+    fileUri: string
+    /**
+     * Total number of bars to generate for the preview.
+     * @default 100
+     */
+    numberOfBars?: number
+    /** Optional logger for debugging. */
+    logger?: ConsoleLike
+    /** Optional configuration for decoding the audio file. */
+    decodingOptions?: DecodingConfig
+    /**
+     * Optional callback fired once per compact bar after extraction resolves.
+     * Native progressive streaming is not implied by this callback.
+     */
+    onBarReady?: (bar: PreviewBar, index: number, total: number) => void
+}
+
 export interface PreviewOptions extends AudioRangeOptions {
     /** URI of the audio file to analyze */
     fileUri: string
@@ -184,6 +253,19 @@ export interface PreviewOptions extends AudioRangeOptions {
      * - normalizeAudio: false
      */
     decodingOptions?: DecodingConfig
+    /**
+     * Optional callback fired once per data point as the preview becomes available.
+     * Today the native module returns the full analysis in one shot; the points are then
+     * micro-batched on the JS side so consumers can render bars incrementally.
+     * Native progressive streaming is a future enhancement.
+     */
+    onPointReady?: (point: DataPoint, index: number, total: number) => void
+    /**
+     * Optional cancellation signal for JS-side progressive point emission.
+     * Aborting does not cancel native extraction after it has started, but it
+     * stops any queued `onPointReady` callbacks from an older request.
+     */
+    signal?: AbortSignal
 }
 
 /**