@siteed/audio-studio 3.1.0 → 3.1.1

package/build/types/errors/AudioExtractionError.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 declare class AudioExtractionError extends Error {
+    readonly code: AudioExtractionErrorCode;
+    readonly nativeMessage?: string;
+    readonly fileUri?: string;
+    constructor(payload: AudioExtractionErrorPayload);
+    toJSON(): AudioExtractionErrorPayload;
+}
+/**
+ * Map a thrown native/JS value into an AudioExtractionError with a stable code.
+ * Heuristics inspect message text and known native error codes.
+ */
+export declare function mapExtractionError(err: unknown, fileUri?: string): AudioExtractionError;
+//# sourceMappingURL=AudioExtractionError.d.ts.map

package/build/types/errors/AudioExtractionError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AudioExtractionError.d.ts","sourceRoot":"","sources":["../../../src/errors/AudioExtractionError.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAC9B,mBAAmB,GACnB,gBAAgB,GAChB,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,SAAS,CAAA;AAEf,MAAM,WAAW,2BAA2B;IACxC,IAAI,EAAE,wBAAwB,CAAA;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAA;IACvC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;gBAEb,OAAO,EAAE,2BAA2B;IAQhD,MAAM,IAAI,2BAA2B;CAQxC;AAkED;;;GAGG;AACH,wBAAgB,kBAAkB,CAC9B,GAAG,EAAE,OAAO,EACZ,OAAO,CAAC,EAAE,MAAM,GACjB,oBAAoB,CAqDtB"}

package/build/types/index.d.ts

@@ -14,7 +14,10 @@ export { getPlatformCapabilities, isEncodingSupported, isBitDepthSupported, getF
 export { AudioDeviceManager, audioDeviceManager } from './AudioDeviceManager';
 export { useAudioDevices } from './hooks/useAudioDevices';
 export { setMelSpectrogramWasmUrl } from './AudioAnalysis/wasmConfig';
+export { extractPreviewBars } from './AudioAnalysis/extractPreviewBars';
 export { AudioRecorderProvider, AudioStudioModule, extractRawWavAnalysis, extractAudioAnalysis, extractPreview, trimAudio, extractAudioData, extractMelSpectrogram, initMelStreamingWasm, computeMelFrameWasm, MAX_DURATION_MS, useAudioRecorder, useSharedAudioRecorder, };
+export { AudioExtractionError, mapExtractionError, } from './errors/AudioExtractionError';
+export type { AudioExtractionErrorCode, AudioExtractionErrorPayload, } from './errors/AudioExtractionError';
 export type * from './AudioAnalysis/AudioAnalysis.types';
 export type * from './AudioStudio.types';
 /** @deprecated Use AudioStudioModule instead */

package/build/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACH,qBAAqB,EACrB,oBAAoB,EACvB,MAAM,sCAAsC,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAA;AACnE,OAAO,EACH,qBAAqB,EACrB,eAAe,EAClB,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AAC/D,OAAO,EACH,oBAAoB,EACpB,mBAAmB,EACtB,MAAM,oCAAoC,CAAA;AAC3C,OAAO,EACH,qBAAqB,EACrB,sBAAsB,EACzB,MAAM,0BAA0B,CAAA;AACjC,OAAO,iBAAiB,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAErD,cAAc,6BAA6B,CAAA;AAC3C,cAAc,wBAAwB,CAAA;AACtC,cAAc,wBAAwB,CAAA;AAGtC,OAAO,EACH,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,oBAAoB,GAC5B,MAAM,iCAAiC,CAAA;AAGxC,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAG7E,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAEzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AAErE,OAAO,EACH,qBAAqB,EACrB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,sBAAsB,GACzB,CAAA;AAGD,mBAAmB,qCAAqC,CAAA;AACxD,mBAAmB,qBAAqB,CAAA;AAExC,gDAAgD;AAChD,eAAO,MAAM,qBAAqB,KAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACH,qBAAqB,EACrB,oBAAoB,EACvB,MAAM,sCAAsC,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAA;AACnE,OAAO,EACH,qBAAqB,EACrB,eAAe,EAClB,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AAC/D,OAAO,EACH,oBAAoB,EACpB,mBAAmB,EACtB,MAAM,oCAAoC,CAAA;AAC3C,OAAO,EACH,qBAAqB,EACrB,sBAAsB,EACzB,MAAM,0BAA0B,CAAA;AACjC,OAAO,iBAAiB,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAErD,cAAc,6BAA6B,CAAA;AAC3C,cAAc,wBAAwB,CAAA;AACtC,cAAc,wBAAwB,CAAA;AAGtC,OAAO,EACH,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,oBAAoB,GAC5B,MAAM,iCAAiC,CAAA;AAGxC,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAG7E,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAEzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAA;AAEvE,OAAO,EACH,qBAAqB,EACrB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,sBAAsB,GACzB,CAAA;AAED,OAAO,EACH,oBAAoB,EACpB,kBAAkB,GACrB,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACR,wBAAwB,EACxB,2BAA2B,GAC9B,MAAM,+BAA+B,CAAA;AAGtC,mBAAmB,qCAAqC,CAAA;AACxD,mBAAmB,qBAAqB,CAAA;AAExC,gDAAgD;AAChD,eAAO,MAAM,qBAAqB,KAAoB,CAAA"}

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/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/package.json

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

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
 }