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

package/build/types/streamAudioData.d.ts

@@ -0,0 +1,114 @@
+/**
+ * High-level API: stream decoded audio from a stored file as bounded Float32
+ * chunks without materializing the full PCM range in memory.
+ *
+ * See `docs/STREAM_AUDIO_DATA.md` for the full contract and rollout notes.
+ */
+export interface StreamAudioDataOptions {
+    /** URI of the audio file to decode. */
+    fileUri: string;
+    /** Start time in milliseconds (default: 0). */
+    startTimeMs?: number;
+    /** End time in milliseconds (default: end-of-file). */
+    endTimeMs?: number;
+    /**
+     * Source sample rate hint. Ignored if `targetSampleRate` is set; native
+     * decoders read the actual rate from the file.
+     */
+    sampleRate?: number;
+    /** Output sample rate. Native resamples when this differs from the file. */
+    targetSampleRate?: number;
+    /** Output channel count (1 = mono downmix, 2 = stereo passthrough). */
+    channels?: number;
+    /** Clamp samples to [-1, 1] and replace non-finite values with 0. */
+    normalizeAudio?: boolean;
+    /** Target chunk duration in ms (default: 1000, min: 10, max: 60000). */
+    chunkDurationMs?: number;
+    /** Soft cap on chunk size in bytes (Float32 = 4 bytes/sample). */
+    maxChunkBytes?: number;
+    /** Max chunks queued in native before JS ack pauses decode (default: 4). */
+    maxBufferedChunks?: number;
+    /** Output PCM format; only `'float32'` supported today. */
+    streamFormat?: 'float32';
+    /** Abort the in-flight request. Resolves promise with `cancelled: true`. */
+    signal?: AbortSignal;
+}
+export interface StreamAudioDataChunk {
+    /** Native request id; constant across all chunks of one call. */
+    requestId: string;
+    /** Zero-based monotonic chunk index. */
+    chunkIndex: number;
+    /** Start time in output-rate ms (rounded to nearest sample). */
+    startTimeMs: number;
+    /** End time in output-rate ms. */
+    endTimeMs: number;
+    /** Duration in ms (`endTimeMs - startTimeMs`). */
+    durationMs: number;
+    /** First sample index in the output timeline. */
+    startSample: number;
+    /** Sample count in `samples` (interleaved if channels > 1). */
+    sampleCount: number;
+    /** Output sample rate. */
+    sampleRate: number;
+    /** Output channel count. */
+    channels: number;
+    /** Interleaved Float32 samples in [-1, 1]. */
+    samples: Float32Array;
+    /** True for the last chunk of a non-cancelled run. */
+    isFinal: boolean;
+}
+export interface StreamAudioDataProgress {
+    requestId: string;
+    processedMs: number;
+    durationMs: number;
+    progress: number;
+    emittedChunks: number;
+    bufferedChunks?: number;
+}
+export interface StreamAudioDataResult {
+    requestId: string;
+    durationMs: number;
+    sampleRate: number;
+    channels: number;
+    chunks: number;
+    samples: number;
+    cancelled: boolean;
+}
+export interface StreamAudioDataCallbacks {
+    /**
+     * Called with each decoded chunk. If this returns a Promise, native decode
+     * pauses until it resolves (backpressure). Throwing aborts the stream with
+     * `ERR_AUDIO_STREAM_DECODE_FAILED`.
+     */
+    onChunk: (chunk: StreamAudioDataChunk) => void | Promise<void>;
+    /** Called whenever native reports progress. */
+    onProgress?: (progress: StreamAudioDataProgress) => void;
+}
+export interface AudioDecodeCapabilities {
+    platform: 'ios' | 'android' | 'web';
+    supportedInputFormats: string[];
+    supportedOutputFormats: Array<'float32'>;
+    supportsCancellation: boolean;
+    supportsBackpressure: boolean;
+    supportsTimeRange: boolean;
+    supportsTargetSampleRate: boolean;
+    supportsChannelMixing: boolean;
+    knownLimitations?: string[];
+}
+/**
+ * Stream decoded audio from a stored file as bounded Float32 PCM chunks.
+ *
+ * Memory bound:
+ *   `chunkDurationMs * sampleRate * channels * 4 * maxBufferedChunks` +
+ *   native decoder buffers.
+ *
+ * Cancellation: pass `options.signal` and call `abort()`. The returned promise
+ * resolves with `cancelled: true` (it does not reject) when cancellation wins.
+ *
+ * Backpressure: if `onChunk` returns a Promise, native decode is paused until
+ * it resolves; if it throws, the stream is aborted with a `decode_failed` error.
+ */
+export declare function streamAudioData(options: StreamAudioDataOptions, callbacks: StreamAudioDataCallbacks): Promise<StreamAudioDataResult>;
+/** Discover what the running platform supports. */
+export declare function getAudioDecodeCapabilities(): Promise<AudioDecodeCapabilities>;
+//# sourceMappingURL=streamAudioData.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"streamAudioData.d.ts","sourceRoot":"","sources":["../../src/streamAudioData.ts"],"names":[],"mappings":"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"}

package/ios/AudioProcessingHelpers.swift

@@ -681,15 +681,20 @@ func extractRawAudioData(
         for channel in 0..<channels {
             let sample = floatData[channel][frame]
             
-            let normalizedSample = decodingConfig.normalizeAudio ? 
-                max(-1.0, min(1.0, sample)) : sample
-            
+            // Sanitize: replace NaN/Inf with 0 then clamp. Skip clamp when
+            // normalizeAudio=false so callers see the raw decoded magnitude,
+            // but always finite-check to avoid Swift's `Int16(_:)` /
+            // `Int32(_:)` trap on non-finite values.
+            let safeSample: Float = sample.isFinite ? sample : 0
+            let normalizedSample = decodingConfig.normalizeAudio ?
+                max(-1.0, min(1.0, safeSample)) : safeSample
+
             switch targetBitDepth {
             case 16:
-                let intValue = Int16(normalizedSample * Float(Int16.max))
+                let intValue = safeFloatToInt16(normalizedSample)
                 pcmData.append(contentsOf: withUnsafeBytes(of: intValue) { Array($0) })
             case 32:
-                let intValue = Int32(normalizedSample * Float(Int32.max))
+                let intValue = safeFloatToInt32(normalizedSample)
                 pcmData.append(contentsOf: withUnsafeBytes(of: intValue) { Array($0) })
             default:
                 throw NSError(domain: "AudioProcessing", code: -1, userInfo: [NSLocalizedDescriptionKey: "Unsupported bit depth \(targetBitDepth)"])

package/ios/AudioStreamDecoder.swift

@@ -0,0 +1,523 @@
+// packages/audio-studio/ios/AudioStreamDecoder.swift
+//
+// Progressive file decoder for `streamAudioData`. Decodes a stored audio
+// file into bounded Float32 chunks via AVAssetReader without materializing
+// the full PCM range. Sanitizes samples (NaN/Inf -> 0, clamp to [-1, 1])
+// and honors per-request cancellation + backpressure ack.
+import AVFoundation
+import Foundation
+
+public protocol AudioStreamDecoderDelegate: AnyObject {
+    func streamDecoder(
+        _ decoder: AudioStreamDecoder,
+        didEmitChunk payload: [String: Any]
+    )
+    func streamDecoder(
+        _ decoder: AudioStreamDecoder,
+        didReportProgress payload: [String: Any]
+    )
+    func streamDecoder(
+        _ decoder: AudioStreamDecoder,
+        didCompleteWith payload: [String: Any]
+    )
+    func streamDecoder(
+        _ decoder: AudioStreamDecoder,
+        didFailWith payload: [String: Any]
+    )
+}
+
+public final class AudioStreamDecoder {
+    public struct Options {
+        public let requestId: String
+        public let fileUri: String
+        public let startTimeMs: Double?
+        public let endTimeMs: Double?
+        public let targetSampleRate: Double?
+        public let channels: Int?
+        public let normalizeAudio: Bool
+        public let chunkDurationMs: Int
+        public let maxChunkBytes: Int?
+        public let maxBufferedChunks: Int
+
+        public init(
+            requestId: String,
+            fileUri: String,
+            startTimeMs: Double?,
+            endTimeMs: Double?,
+            targetSampleRate: Double?,
+            channels: Int?,
+            normalizeAudio: Bool,
+            chunkDurationMs: Int,
+            maxChunkBytes: Int?,
+            maxBufferedChunks: Int
+        ) {
+            self.requestId = requestId
+            self.fileUri = fileUri
+            self.startTimeMs = startTimeMs
+            self.endTimeMs = endTimeMs
+            self.targetSampleRate = targetSampleRate
+            self.channels = channels
+            self.normalizeAudio = normalizeAudio
+            self.chunkDurationMs = max(10, min(60000, chunkDurationMs))
+            self.maxChunkBytes = maxChunkBytes
+            self.maxBufferedChunks = max(1, maxBufferedChunks)
+        }
+    }
+
+    public weak var delegate: AudioStreamDecoderDelegate?
+
+    private let options: Options
+    private let queue: DispatchQueue
+    private let cancelLock = NSLock()
+    private var cancelled = false
+    private let ackLock = NSLock()
+    private let ackCondition = NSCondition()
+    private var lastAckedIndex = -1
+    private var lastEmittedIndex = -1
+
+    public init(options: Options) {
+        self.options = options
+        self.queue = DispatchQueue(
+            label: "net.siteed.audiostudio.streamdecoder.\(options.requestId)",
+            qos: .userInitiated
+        )
+    }
+
+    public func start() {
+        queue.async { [weak self] in
+            self?.run()
+        }
+    }
+
+    public func cancel() {
+        cancelLock.lock()
+        cancelled = true
+        cancelLock.unlock()
+        ackCondition.lock()
+        ackCondition.broadcast()
+        ackCondition.unlock()
+    }
+
+    public func acknowledgeChunk(_ index: Int) {
+        ackCondition.lock()
+        if index > lastAckedIndex {
+            lastAckedIndex = index
+        }
+        ackCondition.broadcast()
+        ackCondition.unlock()
+    }
+
+    private func isCancelled() -> Bool {
+        cancelLock.lock()
+        defer { cancelLock.unlock() }
+        return cancelled
+    }
+
+    private func run() {
+        let url: URL
+        if let parsed = URL(string: options.fileUri),
+           parsed.scheme != nil {
+            url = parsed
+        } else {
+            url = URL(fileURLWithPath: options.fileUri)
+        }
+
+        if !FileManager.default.fileExists(atPath: url.path) {
+            emitError(
+                code: "ERR_AUDIO_STREAM_FILE_NOT_FOUND",
+                message: "File not found: \(url.lastPathComponent)"
+            )
+            return
+        }
+
+        let asset = AVURLAsset(url: url)
+        guard let audioTrack = asset.tracks(withMediaType: .audio).first else {
+            emitError(
+                code: "ERR_AUDIO_STREAM_UNSUPPORTED_FORMAT",
+                message: "No audio track found"
+            )
+            return
+        }
+
+        let trackDuration = CMTimeGetSeconds(asset.duration) * 1000.0
+        let totalDurationMs = trackDuration.isFinite && trackDuration > 0
+            ? trackDuration
+            : 0.0
+
+        // Read source sample rate from track.
+        let sourceSampleRate: Double = {
+            guard let desc = audioTrack.formatDescriptions.first else { return 0 }
+            // swiftlint:disable:next force_cast
+            let formatDescription = desc as! CMAudioFormatDescription
+            guard let asbd = CMAudioFormatDescriptionGetStreamBasicDescription(
+                formatDescription
+            )?.pointee else {
+                return 0
+            }
+            return asbd.mSampleRate
+        }()
+        let sourceChannelCount: Int = {
+            guard let desc = audioTrack.formatDescriptions.first else { return 1 }
+            // swiftlint:disable:next force_cast
+            let formatDescription = desc as! CMAudioFormatDescription
+            guard let asbd = CMAudioFormatDescriptionGetStreamBasicDescription(
+                formatDescription
+            )?.pointee else {
+                return 1
+            }
+            return Int(asbd.mChannelsPerFrame)
+        }()
+
+        let outputSampleRate = options.targetSampleRate
+            ?? (sourceSampleRate > 0 ? sourceSampleRate : 16000)
+        let outputChannels = options.channels ?? min(2, max(1, sourceChannelCount))
+
+        let outputSettings: [String: Any] = [
+            AVFormatIDKey: kAudioFormatLinearPCM,
+            AVLinearPCMBitDepthKey: 32,
+            AVLinearPCMIsFloatKey: true,
+            AVLinearPCMIsBigEndianKey: false,
+            AVLinearPCMIsNonInterleaved: false,
+            AVSampleRateKey: outputSampleRate,
+            AVNumberOfChannelsKey: outputChannels,
+        ]
+
+        let reader: AVAssetReader
+        do {
+            reader = try AVAssetReader(asset: asset)
+        } catch {
+            emitError(
+                code: "ERR_AUDIO_STREAM_DECODE_FAILED",
+                message: "Reader init failed: \(error.localizedDescription)"
+            )
+            return
+        }
+
+        if let startMs = options.startTimeMs, let endMs = options.endTimeMs {
+            if startMs < 0 || endMs <= startMs {
+                emitError(
+                    code: "ERR_AUDIO_STREAM_INVALID_RANGE",
+                    message: "Invalid time range"
+                )
+                return
+            }
+            let start = CMTime(seconds: startMs / 1000.0, preferredTimescale: 600)
+            let duration = CMTime(
+                seconds: (endMs - startMs) / 1000.0,
+                preferredTimescale: 600
+            )
+            reader.timeRange = CMTimeRange(start: start, duration: duration)
+        } else if let startMs = options.startTimeMs {
+            let start = CMTime(seconds: startMs / 1000.0, preferredTimescale: 600)
+            reader.timeRange = CMTimeRange(
+                start: start,
+                duration: CMTime.positiveInfinity
+            )
+        }
+
+        let trackOutput = AVAssetReaderTrackOutput(
+            track: audioTrack,
+            outputSettings: outputSettings
+        )
+        trackOutput.alwaysCopiesSampleData = false
+
+        guard reader.canAdd(trackOutput) else {
+            emitError(
+                code: "ERR_AUDIO_STREAM_DECODE_FAILED",
+                message: "Cannot attach decoder output"
+            )
+            return
+        }
+        reader.add(trackOutput)
+
+        guard reader.startReading() else {
+            let err = reader.error?.localizedDescription ?? "Unknown reader error"
+            emitError(
+                code: "ERR_AUDIO_STREAM_DECODE_FAILED",
+                message: "startReading failed: \(err)"
+            )
+            return
+        }
+
+        let samplesPerChunk = max(
+            1,
+            Int((Double(options.chunkDurationMs) / 1000.0) * outputSampleRate)
+        ) * outputChannels
+        let cappedSamplesPerChunk: Int = {
+            guard let maxBytes = options.maxChunkBytes else { return samplesPerChunk }
+            let maxFloats = max(1, maxBytes / 4)
+            return min(samplesPerChunk, maxFloats)
+        }()
+
+        var pending = [Float]()
+        pending.reserveCapacity(cappedSamplesPerChunk * 2)
+        var chunkIndex = 0
+        var totalSamples = 0
+        var processedMs: Double = 0
+        var cancelledByUser = false
+        let rangeStartMs = options.startTimeMs ?? 0
+
+        while reader.status == .reading {
+            if isCancelled() {
+                cancelledByUser = true
+                break
+            }
+            guard let sampleBuffer = trackOutput.copyNextSampleBuffer() else {
+                break
+            }
+            guard let block = CMSampleBufferGetDataBuffer(sampleBuffer) else {
+                continue
+            }
+            let frameCount = CMSampleBufferGetNumSamples(sampleBuffer)
+            if frameCount <= 0 { continue }
+
+            var lengthAtOffset = 0
+            var totalLength = 0
+            var dataPointer: UnsafeMutablePointer<Int8>?
+            let status = CMBlockBufferGetDataPointer(
+                block,
+                atOffset: 0,
+                lengthAtOffsetOut: &lengthAtOffset,
+                totalLengthOut: &totalLength,
+                dataPointerOut: &dataPointer
+            )
+            guard status == kCMBlockBufferNoErr, let raw = dataPointer else {
+                continue
+            }
+
+            let sampleCount = totalLength / MemoryLayout<Float>.size
+            let floatPtr = UnsafeRawPointer(raw)
+                .assumingMemoryBound(to: Float.self)
+            var idx = pending.count
+            pending.append(contentsOf: repeatElement(0, count: sampleCount))
+            for i in 0..<sampleCount {
+                let v = floatPtr[i]
+                if v.isNaN || v.isInfinite {
+                    pending[idx] = 0
+                } else if options.normalizeAudio {
+                    pending[idx] = max(-1.0, min(1.0, v))
+                } else {
+                    pending[idx] = v
+                }
+                idx += 1
+            }
+
+            while pending.count >= cappedSamplesPerChunk {
+                let payload = Array(pending.prefix(cappedSamplesPerChunk))
+                pending.removeFirst(cappedSamplesPerChunk)
+                let durationOfChunk = Double(cappedSamplesPerChunk)
+                    / (outputSampleRate * Double(outputChannels))
+                let startMs = rangeStartMs
+                    + (Double(totalSamples) / (outputSampleRate * Double(outputChannels))) * 1000.0
+                emitChunk(
+                    index: chunkIndex,
+                    startTimeMs: startMs,
+                    endTimeMs: startMs + durationOfChunk * 1000.0,
+                    startSample: totalSamples / outputChannels,
+                    sampleRate: outputSampleRate,
+                    channels: outputChannels,
+                    samples: payload,
+                    isFinal: false
+                )
+                lastEmittedIndex = chunkIndex
+                chunkIndex += 1
+                totalSamples += cappedSamplesPerChunk
+                processedMs = startMs + durationOfChunk * 1000.0
+                emitProgress(
+                    processedMs: processedMs,
+                    durationMs: totalDurationMs,
+                    emittedChunks: chunkIndex
+                )
+
+                if waitForAckOrCancel(upTo: chunkIndex - 1) {
+                    cancelledByUser = true
+                    break
+                }
+            }
+            if cancelledByUser { break }
+        }
+
+        if cancelledByUser {
+            reader.cancelReading()
+            emitError(
+                code: "ERR_AUDIO_STREAM_CANCELLED",
+                message: "Stream cancelled"
+            )
+            emitComplete(
+                durationMs: processedMs,
+                sampleRate: outputSampleRate,
+                channels: outputChannels,
+                chunks: chunkIndex,
+                samples: totalSamples,
+                cancelled: true
+            )
+            return
+        }
+
+        if reader.status == .failed {
+            let err = reader.error?.localizedDescription ?? "Unknown decode error"
+            emitError(
+                code: "ERR_AUDIO_STREAM_DECODE_FAILED",
+                message: err
+            )
+            return
+        }
+
+        // Flush remaining samples as final chunk.
+        if !pending.isEmpty {
+            let durationOfChunk = Double(pending.count)
+                / (outputSampleRate * Double(outputChannels))
+            let startMs = rangeStartMs
+                + (Double(totalSamples) / (outputSampleRate * Double(outputChannels))) * 1000.0
+            emitChunk(
+                index: chunkIndex,
+                startTimeMs: startMs,
+                endTimeMs: startMs + durationOfChunk * 1000.0,
+                startSample: totalSamples / outputChannels,
+                sampleRate: outputSampleRate,
+                channels: outputChannels,
+                samples: pending,
+                isFinal: true
+            )
+            totalSamples += pending.count
+            chunkIndex += 1
+            processedMs = startMs + durationOfChunk * 1000.0
+            pending.removeAll(keepingCapacity: false)
+        } else if chunkIndex > 0 {
+            // Last emitted chunk wasn't marked final. Emit a zero-sample final
+            // tail so consumers that key off isFinal see termination.
+            let startMs = rangeStartMs
+                + (Double(totalSamples) / (outputSampleRate * Double(outputChannels))) * 1000.0
+            emitChunk(
+                index: chunkIndex,
+                startTimeMs: startMs,
+                endTimeMs: startMs,
+                startSample: totalSamples / outputChannels,
+                sampleRate: outputSampleRate,
+                channels: outputChannels,
+                samples: [Float](),
+                isFinal: true
+            )
+            chunkIndex += 1
+        }
+
+        emitComplete(
+            durationMs: totalDurationMs > 0 ? totalDurationMs : processedMs,
+            sampleRate: outputSampleRate,
+            channels: outputChannels,
+            chunks: chunkIndex,
+            samples: totalSamples,
+            cancelled: false
+        )
+    }
+
+    /// Blocks the decoder thread while too many unacked chunks are in flight.
+    /// Returns true if cancellation arrived while waiting.
+    private func waitForAckOrCancel(upTo index: Int) -> Bool {
+        ackCondition.lock()
+        defer { ackCondition.unlock() }
+        while true {
+            if isCancelled() {
+                return true
+            }
+            let inFlight = index - lastAckedIndex
+            if inFlight < options.maxBufferedChunks {
+                return false
+            }
+            ackCondition.wait(until: Date().addingTimeInterval(0.05))
+        }
+    }
+
+    private func emitChunk(
+        index: Int,
+        startTimeMs: Double,
+        endTimeMs: Double,
+        startSample: Int,
+        sampleRate: Double,
+        channels: Int,
+        samples: [Float],
+        isFinal: Bool
+    ) {
+        let payload: [String: Any] = [
+            "requestId": options.requestId,
+            "chunkIndex": index,
+            "startTimeMs": startTimeMs,
+            "endTimeMs": endTimeMs,
+            "startSample": startSample,
+            "sampleCount": samples.count,
+            "sampleRate": sampleRate,
+            "channels": channels,
+            "samples": samples,
+            "isFinal": isFinal,
+        ]
+        delegate?.streamDecoder(self, didEmitChunk: payload)
+    }
+
+    private func emitProgress(
+        processedMs: Double,
+        durationMs: Double,
+        emittedChunks: Int
+    ) {
+        let progress: Double = durationMs > 0
+            ? min(1.0, max(0.0, processedMs / durationMs))
+            : 0
+        let payload: [String: Any] = [
+            "requestId": options.requestId,
+            "processedMs": processedMs,
+            "durationMs": durationMs,
+            "progress": progress,
+            "emittedChunks": emittedChunks,
+        ]
+        delegate?.streamDecoder(self, didReportProgress: payload)
+    }
+
+    private func emitComplete(
+        durationMs: Double,
+        sampleRate: Double,
+        channels: Int,
+        chunks: Int,
+        samples: Int,
+        cancelled: Bool
+    ) {
+        let payload: [String: Any] = [
+            "requestId": options.requestId,
+            "durationMs": durationMs,
+            "sampleRate": sampleRate,
+            "channels": channels,
+            "chunks": chunks,
+            "samples": samples,
+            "cancelled": cancelled,
+        ]
+        delegate?.streamDecoder(self, didCompleteWith: payload)
+    }
+
+    private func emitError(code: String, message: String) {
+        let payload: [String: Any] = [
+            "requestId": options.requestId,
+            "code": code,
+            "message": message,
+        ]
+        delegate?.streamDecoder(self, didFailWith: payload)
+    }
+}
+
+/// Safe Float -> integer conversion. Replaces NaN/Inf with 0 and clamps the
+/// scaled value into the integer range before constructing the bounded type,
+/// avoiding the Swift trap that previously crashed the host app inside
+/// `extractRawAudioData` on malformed samples.
+@inline(__always)
+public func safeFloatToInt16(_ sample: Float) -> Int16 {
+    let safe = sample.isFinite ? max(-1.0, min(1.0, sample)) : 0
+    let scaled = (safe * Float(Int16.max)).rounded()
+    let clamped = max(Float(Int16.min), min(Float(Int16.max), scaled))
+    return Int16(clamped)
+}
+
+@inline(__always)
+public func safeFloatToInt32(_ sample: Float) -> Int32 {
+    let safe = sample.isFinite ? max(-1.0, min(1.0, sample)) : 0
+    let scaled = Double(safe) * Double(Int32.max)
+    let rounded = scaled.rounded()
+    let clamped = max(Double(Int32.min), min(Double(Int32.max), rounded))
+    return Int32(clamped)
+}