@siteed/audio-studio 3.1.0 → 3.2.0-beta.1

package/ios/AudioStudioModule.swift

@@ -9,6 +9,10 @@ private let recordingInterruptedEvent: String = "onRecordingInterrupted"
 private let deviceChangedEvent: String = "deviceChangedEvent"
 private let trimProgressEvent: String = "TrimProgress"
 private let errorEvent: String = "error"
+private let audioStreamChunkEvent: String = "AudioDataStreamChunk"
+private let audioStreamProgressEvent: String = "AudioDataStreamProgress"
+private let audioStreamCompleteEvent: String = "AudioDataStreamComplete"
+private let audioStreamErrorEvent: String = "AudioDataStreamError"
 private let DEFAULT_SEGMENT_DURATION_MS = 100
 private let audioDeviceTypeBuiltinMic = "builtin_mic"
 private let audioDeviceTypeBluetooth = "bluetooth"
@@ -18,13 +22,16 @@ private let audioDeviceTypeWiredHeadphones = "wired_headphones"
 private let audioDeviceTypeSpeaker = "speaker"
 private let audioDeviceTypeUnknown = "unknown"
 
-public class AudioStudioModule: Module, AudioStreamManagerDelegate, AudioDeviceManagerDelegate {
+public class AudioStudioModule: Module, AudioStreamManagerDelegate, AudioDeviceManagerDelegate, AudioStreamDecoderDelegate {
     private var streamManager = AudioStreamManager()
     private let notificationCenter = UNUserNotificationCenter.current()
     private let notificationIdentifier = "audio_recording_notification"
     private var deviceManager = AudioDeviceManager()
     private var deviceChangeObserver: Any?
 
+    private let streamDecodersLock = NSLock()
+    private var streamDecoders: [String: AudioStreamDecoder] = [:]
+
     // Serial queue for AVAudioEngine lifecycle ops (prepare/start/stop).
     // Prevents concurrent mutation of shared engine state and keeps callers
     // off the main thread to avoid UI freezes during heavy native init.
@@ -43,7 +50,11 @@ public class AudioStudioModule: Module, AudioStreamManagerDelegate, AudioDeviceM
             recordingInterruptedEvent,
             deviceChangedEvent,
             trimProgressEvent,
-            errorEvent
+            errorEvent,
+            audioStreamChunkEvent,
+            audioStreamProgressEvent,
+            audioStreamCompleteEvent,
+            audioStreamErrorEvent
         ])
         
         OnCreate {
@@ -163,6 +174,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.
@@ -897,8 +912,141 @@ public class AudioStudioModule: Module, AudioStreamManagerDelegate, AudioDeviceM
                 }
             }
         }
+
+        AsyncFunction("streamAudioData") { (options: [String: Any], promise: Promise) in
+            guard let requestId = options["requestId"] as? String,
+                  let fileUri = options["fileUri"] as? String else {
+                promise.reject(
+                    "ERR_AUDIO_STREAM_INVALID_RANGE",
+                    "fileUri and requestId are required"
+                )
+                return
+            }
+
+            let streamFormat = options["streamFormat"] as? String ?? "float32"
+            guard streamFormat == "float32" else {
+                promise.reject(
+                    "ERR_AUDIO_STREAM_UNSUPPORTED_FORMAT",
+                    "Only streamFormat='float32' is supported"
+                )
+                return
+            }
+
+            let opts = AudioStreamDecoder.Options(
+                requestId: requestId,
+                fileUri: fileUri,
+                startTimeMs: options["startTimeMs"] as? Double,
+                endTimeMs: options["endTimeMs"] as? Double,
+                targetSampleRate: options["targetSampleRate"] as? Double
+                    ?? (options["sampleRate"] as? Double),
+                channels: options["channels"] as? Int,
+                normalizeAudio: options["normalizeAudio"] as? Bool ?? true,
+                chunkDurationMs: options["chunkDurationMs"] as? Int ?? 1000,
+                maxChunkBytes: options["maxChunkBytes"] as? Int,
+                maxBufferedChunks: options["maxBufferedChunks"] as? Int ?? 4
+            )
+
+            let decoder = AudioStreamDecoder(options: opts)
+            decoder.delegate = self
+            self.streamDecodersLock.lock()
+            if self.streamDecoders[requestId] != nil {
+                self.streamDecodersLock.unlock()
+                promise.reject(
+                    "ERR_AUDIO_STREAM_BUSY",
+                    "requestId already in use"
+                )
+                return
+            }
+            self.streamDecoders[requestId] = decoder
+            self.streamDecodersLock.unlock()
+            decoder.start()
+            promise.resolve(["requestId": requestId])
+        }
+
+        AsyncFunction("cancelStreamAudioData") { (requestId: String, promise: Promise) in
+            self.streamDecodersLock.lock()
+            let decoder = self.streamDecoders[requestId]
+            self.streamDecodersLock.unlock()
+            decoder?.cancel()
+            promise.resolve(["requestId": requestId, "cancelled": decoder != nil])
+        }
+
+        Function("acknowledgeStreamAudioChunk") { (requestId: String, chunkIndex: Int) in
+            self.streamDecodersLock.lock()
+            let decoder = self.streamDecoders[requestId]
+            self.streamDecodersLock.unlock()
+            decoder?.acknowledgeChunk(chunkIndex)
+        }
+
+        AsyncFunction("getAudioDecodeCapabilities") { (promise: Promise) in
+            promise.resolve([
+                "platform": "ios",
+                "supportedInputFormats": [
+                    "audio/wav",
+                    "audio/aac",
+                    "audio/mp4",
+                    "audio/mpeg",
+                    "audio/x-m4a",
+                    "audio/caf",
+                    "audio/aiff",
+                ],
+                "supportedOutputFormats": ["float32"],
+                "supportsCancellation": true,
+                "supportsBackpressure": true,
+                "supportsTimeRange": true,
+                "supportsTargetSampleRate": true,
+                "supportsChannelMixing": true,
+                "knownLimitations": [
+                    "Opus/WebM input depends on AVFoundation codec availability for the iOS version."
+                ],
+            ])
+        }
     }
-    
+
+    private func releaseStreamDecoder(_ requestId: String) {
+        streamDecodersLock.lock()
+        streamDecoders.removeValue(forKey: requestId)
+        streamDecodersLock.unlock()
+    }
+
+    // MARK: - AudioStreamDecoderDelegate
+
+    public func streamDecoder(
+        _ decoder: AudioStreamDecoder,
+        didEmitChunk payload: [String: Any]
+    ) {
+        sendEvent(audioStreamChunkEvent, payload)
+    }
+
+    public func streamDecoder(
+        _ decoder: AudioStreamDecoder,
+        didReportProgress payload: [String: Any]
+    ) {
+        sendEvent(audioStreamProgressEvent, payload)
+    }
+
+    public func streamDecoder(
+        _ decoder: AudioStreamDecoder,
+        didCompleteWith payload: [String: Any]
+    ) {
+        if let requestId = payload["requestId"] as? String {
+            releaseStreamDecoder(requestId)
+        }
+        sendEvent(audioStreamCompleteEvent, payload)
+    }
+
+    public func streamDecoder(
+        _ decoder: AudioStreamDecoder,
+        didFailWith payload: [String: Any]
+    ) {
+        if let requestId = payload["requestId"] as? String,
+           let code = payload["code"] as? String,
+           code != "ERR_AUDIO_STREAM_CANCELLED" {
+            releaseStreamDecoder(requestId)
+        }
+        sendEvent(audioStreamErrorEvent, payload)
+    }
+
     func audioStreamManager(_ manager: AudioStreamManager, didReceiveInterruption info: [String: Any]) {
         Logger.debug("AudioStudioModule", "Delegate: didReceiveInterruption: \(info)")
         // Convert iOS interruption events to match the TypeScript types
@@ -1052,6 +1200,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/AudioStreamDecoderTests.swift

@@ -0,0 +1,128 @@
+import XCTest
+@testable import AudioStudio
+
+final class AudioStreamDecoderTests: XCTestCase {
+
+    // MARK: - Sample sanitization
+
+    func testSafeFloatToInt16ReplacesNonFinite() {
+        XCTAssertEqual(safeFloatToInt16(Float.nan), 0)
+        XCTAssertEqual(safeFloatToInt16(Float.infinity), Int16.max)
+        XCTAssertEqual(safeFloatToInt16(-Float.infinity), Int16.min)
+    }
+
+    func testSafeFloatToInt16ClampsOutOfRange() {
+        XCTAssertEqual(safeFloatToInt16(2.0), Int16.max)
+        XCTAssertEqual(safeFloatToInt16(-2.0), Int16.min)
+        XCTAssertEqual(safeFloatToInt16(0.0), 0)
+    }
+
+    func testSafeFloatToInt16IdentityAtUnityIsBounded() {
+        // The previous Swift `Int16(1.0 * Float(Int16.max))` trap requires
+        // the result of the multiplication to fit Int16. The new helper
+        // must produce Int16.max for sample == 1.0 without trapping.
+        XCTAssertEqual(safeFloatToInt16(1.0), Int16.max)
+        XCTAssertEqual(safeFloatToInt16(-1.0), -Int16.max)
+    }
+
+    func testSafeFloatToInt32ReplacesNonFinite() {
+        XCTAssertEqual(safeFloatToInt32(Float.nan), 0)
+        XCTAssertEqual(safeFloatToInt32(Float.infinity), Int32.max)
+        XCTAssertEqual(safeFloatToInt32(-Float.infinity), Int32.min)
+    }
+
+    func testSafeFloatToInt32ClampsOutOfRange() {
+        XCTAssertEqual(safeFloatToInt32(5.0), Int32.max)
+        XCTAssertEqual(safeFloatToInt32(-5.0), Int32.min)
+    }
+
+    // MARK: - Decoder option bounds
+
+    func testDecoderOptionsClampsChunkDuration() {
+        let opts = AudioStreamDecoder.Options(
+            requestId: "test",
+            fileUri: "/dev/null",
+            startTimeMs: nil,
+            endTimeMs: nil,
+            targetSampleRate: nil,
+            channels: nil,
+            normalizeAudio: true,
+            chunkDurationMs: 5,
+            maxChunkBytes: nil,
+            maxBufferedChunks: 0
+        )
+        XCTAssertEqual(opts.chunkDurationMs, 10, "chunkDurationMs floor is 10ms")
+        XCTAssertEqual(opts.maxBufferedChunks, 1, "maxBufferedChunks floor is 1")
+
+        let bigOpts = AudioStreamDecoder.Options(
+            requestId: "big",
+            fileUri: "/dev/null",
+            startTimeMs: nil,
+            endTimeMs: nil,
+            targetSampleRate: nil,
+            channels: nil,
+            normalizeAudio: true,
+            chunkDurationMs: 999_999,
+            maxChunkBytes: nil,
+            maxBufferedChunks: 99
+        )
+        XCTAssertEqual(bigOpts.chunkDurationMs, 60_000, "chunkDurationMs ceiling is 60s")
+    }
+
+    // MARK: - Decoder event contract
+
+    final class CaptureDelegate: AudioStreamDecoderDelegate {
+        var chunks: [[String: Any]] = []
+        var progressEvents: [[String: Any]] = []
+        var completePayload: [String: Any]?
+        var errorPayload: [String: Any]?
+        let done = XCTestExpectation(description: "decoder terminal event")
+
+        func streamDecoder(_ decoder: AudioStreamDecoder, didEmitChunk payload: [String: Any]) {
+            chunks.append(payload)
+            if let idx = payload["chunkIndex"] as? Int {
+                decoder.acknowledgeChunk(idx)
+            }
+        }
+        func streamDecoder(_ decoder: AudioStreamDecoder, didReportProgress payload: [String: Any]) {
+            progressEvents.append(payload)
+        }
+        func streamDecoder(_ decoder: AudioStreamDecoder, didCompleteWith payload: [String: Any]) {
+            completePayload = payload
+            done.fulfill()
+        }
+        func streamDecoder(_ decoder: AudioStreamDecoder, didFailWith payload: [String: Any]) {
+            errorPayload = payload
+            // Some flows emit an error then a complete; let complete fulfill.
+        }
+    }
+
+    func testDecoderEmitsFileNotFoundForMissingPath() {
+        let delegate = CaptureDelegate()
+        let opts = AudioStreamDecoder.Options(
+            requestId: "missing",
+            fileUri: "/tmp/this-file-does-not-exist-\(UUID().uuidString).wav",
+            startTimeMs: nil,
+            endTimeMs: nil,
+            targetSampleRate: nil,
+            channels: nil,
+            normalizeAudio: true,
+            chunkDurationMs: 100,
+            maxChunkBytes: nil,
+            maxBufferedChunks: 2
+        )
+        let decoder = AudioStreamDecoder(options: opts)
+        decoder.delegate = delegate
+        decoder.start()
+        // Error path never calls complete, so wait directly on the error.
+        let exp = XCTestExpectation(description: "error received")
+        DispatchQueue.global().asyncAfter(deadline: .now() + 0.5) {
+            if delegate.errorPayload != nil {
+                exp.fulfill()
+            }
+        }
+        wait(for: [exp], timeout: 2.0)
+        XCTAssertEqual(delegate.errorPayload?["code"] as? String, "ERR_AUDIO_STREAM_FILE_NOT_FOUND")
+        XCTAssertEqual(delegate.errorPayload?["requestId"] as? String, "missing")
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@siteed/audio-studio",
-    "version": "3.1.0",
+    "version": "3.2.0-beta.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
 }
 
 /**

package/src/AudioAnalysis/extractPreview.ts

@@ -1,34 +1,135 @@
-import { PreviewOptions, AudioAnalysis } from './AudioAnalysis.types'
+import { mapExtractionError } from '../errors/AudioExtractionError'
+import { PreviewOptions, AudioAnalysis, DataPoint } from './AudioAnalysis.types'
 import { extractAudioAnalysis } from './extractAudioAnalysis'
 
+const DEFAULT_SILENCE_THRESHOLD = 0.01
+
+/**
+ * Apply a silence threshold to the data points by recomputing the `silent` flag from rms.
+ * Returns a new array (does not mutate the source).
+ */
+function applySilenceThreshold(
+    dataPoints: DataPoint[],
+    threshold: number
+): DataPoint[] {
+    return dataPoints.map((p) => ({
+        ...p,
+        silent: p.rms < threshold,
+    }))
+}
+
+const SMALL_TOTAL_INSTANT_THRESHOLD = 50
+const PROGRESSIVE_BATCH_DELAY_MS = 30
+const PROGRESSIVE_BATCH_COUNT = 8
+
+/**
+ * Schedule progressive emission of points after the native one-shot resolve.
+ * Native progressive streaming is a future enhancement; today the points are
+ * micro-batched on the JS side so consumers (and the agentic recipe runner)
+ * can observe an in-flight `pointsReceived < totalPoints` window.
+ */
+function emitPointsProgressively(
+    dataPoints: DataPoint[],
+    onPointReady: NonNullable<PreviewOptions['onPointReady']>,
+    signal?: PreviewOptions['signal'],
+    logger?: PreviewOptions['logger']
+): void {
+    const total = dataPoints.length
+    if (total === 0) return
+
+    const safeEmit = (point: DataPoint, index: number) => {
+        if (signal?.aborted) return
+        try {
+            onPointReady(point, index, total)
+        } catch (err) {
+            // Swallow callback errors so a buggy consumer cannot break extraction.
+            logger?.warn?.('extractPreview onPointReady callback failed', err)
+        }
+    }
+
+    if (signal?.aborted) return
+    if (total <= SMALL_TOTAL_INSTANT_THRESHOLD) {
+        for (let i = 0; i < total; i++) safeEmit(dataPoints[i], i)
+        return
+    }
+
+    // First quarter flushes immediately so the UI shows something within a frame.
+    const firstFlushCount = Math.max(1, Math.floor(total / 4))
+    for (let i = 0; i < firstFlushCount; i++) safeEmit(dataPoints[i], i)
+
+    if (firstFlushCount >= total) return
+
+    const remaining = total - firstFlushCount
+    const batchSize = Math.max(
+        1,
+        Math.ceil(remaining / PROGRESSIVE_BATCH_COUNT)
+    )
+    let cursor = firstFlushCount
+    const pump = () => {
+        if (signal?.aborted) return
+        const end = Math.min(total, cursor + batchSize)
+        for (let i = cursor; i < end; i++) safeEmit(dataPoints[i], i)
+        cursor = end
+        if (cursor < total) {
+            setTimeout(pump, PROGRESSIVE_BATCH_DELAY_MS)
+        }
+    }
+    setTimeout(pump, PROGRESSIVE_BATCH_DELAY_MS)
+}
+
 /**
  * Generates a simplified preview of the audio waveform for quick visualization.
  * Ideal for UI rendering with a specified number of points.
  *
  * @param options - The options for the preview, including file URI and time range.
  * @returns A promise that resolves to the audio preview data.
+ * @throws {AudioExtractionError} when the underlying extraction fails.
  */
 export async function extractPreview({
     fileUri,
     numberOfPoints = 100,
     startTimeMs = 0,
-    endTimeMs = 30000, // First 30 seconds
+    endTimeMs = 30000,
     decodingOptions,
     logger,
+    onPointReady,
+    signal,
 }: PreviewOptions): Promise<AudioAnalysis> {
-    const durationMs = endTimeMs - startTimeMs
-    const segmentDurationMs = Math.floor(durationMs / numberOfPoints)
-
-    // Call extractAudioAnalysis with calculated parameters
-    const analysis = await extractAudioAnalysis({
-        fileUri,
-        startTimeMs,
-        endTimeMs,
-        logger,
-        segmentDurationMs,
-        decodingOptions,
-    })
-
-    // Transform the result into AudioPreview format
-    return analysis
+    const durationMs = Math.max(1, endTimeMs - startTimeMs)
+    const segmentDurationMs = Math.max(
+        1,
+        Math.floor(durationMs / numberOfPoints)
+    )
+
+    let analysis: AudioAnalysis
+    try {
+        analysis = await extractAudioAnalysis({
+            fileUri,
+            startTimeMs,
+            endTimeMs,
+            logger,
+            segmentDurationMs,
+            decodingOptions,
+        })
+    } catch (err) {
+        throw mapExtractionError(err, fileUri)
+    }
+
+    const threshold =
+        decodingOptions?.silenceRmsThreshold ?? DEFAULT_SILENCE_THRESHOLD
+    const adjusted: AudioAnalysis = {
+        ...analysis,
+        dataPoints: applySilenceThreshold(analysis.dataPoints, threshold),
+    }
+
+    if (onPointReady) {
+        emitPointsProgressively(
+            adjusted.dataPoints,
+            onPointReady,
+            signal,
+            logger
+        )
+    }
+
+    return adjusted
 }