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

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)
+}