@stream-io/video-react-native-sdk 1.38.2 → 1.39.1-beta.0

package/ios/TracksRecorder/TracksRecorderManager.swift

@@ -0,0 +1,327 @@
+//
+// Copyright © 2026 Stream.io Inc. All rights reserved.
+//
+
+import AVFoundation
+import CoreMedia
+import Foundation
+import WebRTC
+
+/// Orchestrator for the React Native track recorder. Owns the
+/// `AVAssetWriter`, the recording lifecycle, the writer-start gate, and
+/// the terminal-completion barrier. Delegates the encoder + sink + drain
+/// work to `VideoPipeline` and `AudioPipeline` respectively (composed via
+/// `PipelineHost`).
+///
+/// The `startRecording` completion is the *lifecycle* signal — it fires once at the terminal moment of the
+/// recording (auto-stop timer expired, manual stop, or fatal error),
+/// carrying the resulting file URL or an error. The `stopRecording`
+/// completion is just a synchronization point — `void` — so callers can
+/// `await stopTrackRecording(); await getStreamRecordings()` without
+/// racing the disk flush.
+@objc public final class TracksRecorderManager: NSObject, PipelineHost {
+
+    @objc public static let shared = TracksRecorderManager()
+
+    // MARK: - Configuration
+
+    @objc public var recordingsDirectory: URL {
+        let tmp = NSTemporaryDirectory()
+        let url = URL(fileURLWithPath: tmp).appendingPathComponent("StreamRecordings", isDirectory: true)
+        try? FileManager.default.createDirectory(
+            at: url,
+            withIntermediateDirectories: true,
+            attributes: nil
+        )
+        return url
+    }
+
+    // MARK: - PipelineHost
+
+    let queue = DispatchQueue(label: "io.stream.video.tracks-recorder")
+
+    private(set) var assetWriter: AVAssetWriter?
+    private(set) var isRecording = false
+
+    // MARK: - State
+
+    private var videoPipeline: VideoPipeline?
+    private var audioPipeline: AudioPipeline?
+
+    private var outputURL: URL?
+    private var recordingCompletion: ((URL?, NSError?) -> Void)?
+    private var isCompleted = false
+
+    private var pendingPipelines = 0
+    private var recordingStartHostTimeNs: UInt64?
+    private var autoStopTimer: DispatchSourceTimer?
+
+    // MARK: - Public API
+
+    @objc public func startRecording(
+        videoTrackId: String?,
+        maxDurationMs: Int,
+        targetWidth: Int,
+        targetHeight: Int,
+        webRTCModule: WebRTCModule,
+        completion: @escaping (URL?, NSError?) -> Void
+    ) {
+        queue.async { [weak self] in
+            guard let self = self else { return }
+
+            if self.isRecording {
+                completion(nil, makeRecorderError("recording_in_progress", code: 1))
+                return
+            }
+
+            let videoTrack = videoTrackId
+                .flatMap { webRTCModule.track(forId: $0) } as? RTCVideoTrack
+
+            // Resolve the APM for the render-side audio tap before opening
+            // any files — so a missing/incompatible APM fails fast. Audio
+            // is captured through the APM render-pre delegate (post-mix
+            // decoded audio); no per-track lookup is needed.
+            let apmId = WebRTCModuleOptions.sharedInstance().audioProcessingModule
+            guard let apm = apmId as? RTCDefaultAudioProcessingModule else {
+                completion(nil, makeRecorderError("audio_processing_module_unavailable", code: 5))
+                return
+            }
+            if apm.renderPreProcessingDelegate != nil {
+                completion(nil, makeRecorderError("recording_blocked_by_audio_render_tap", code: 6))
+                return
+            }
+
+            let dir = self.recordingsDirectory
+            let timestamp = Int(Date().timeIntervalSince1970 * 1000)
+            let outputURL = dir.appendingPathComponent("recording_\(timestamp).mp4")
+
+            let writer: AVAssetWriter
+            do {
+                writer = try AVAssetWriter(url: outputURL, fileType: .mp4)
+            } catch {
+                completion(nil, error as NSError)
+                return
+            }
+
+            self.assetWriter = writer
+            self.outputURL = outputURL
+            self.recordingCompletion = completion
+            self.isCompleted = false
+            self.recordingStartHostTimeNs = nil
+            self.pendingPipelines = 0
+            self.isRecording = true
+
+            if let videoTrack = videoTrack {
+                let pipeline = VideoPipeline(
+                    host: self,
+                    videoTrack: videoTrack,
+                    targetWidth: Int32(targetWidth),
+                    targetHeight: Int32(targetHeight)
+                )
+                self.videoPipeline = pipeline
+                self.pendingPipelines += 1
+                pipeline.start()
+            }
+
+            let audio = AudioPipeline(host: self, apm: apm)
+            self.audioPipeline = audio
+            self.pendingPipelines += 1
+            audio.start()
+
+            if maxDurationMs > 0 {
+                let timer = DispatchSource.makeTimerSource(queue: self.queue)
+                timer.schedule(deadline: .now() + .milliseconds(maxDurationMs))
+                timer.setEventHandler { [weak self] in
+                    self?.stopRecording { }
+                }
+                timer.resume()
+                self.autoStopTimer = timer
+            }
+
+            NSLog("[TracksRecorder] recording started video=%@ audio=YES → %@",
+                  videoTrack != nil ? "YES" : "NO",
+                  outputURL.absoluteString)
+        }
+    }
+
+    @objc public func stopRecording(completion: @escaping () -> Void) {
+        queue.async { [weak self] in
+            guard let self = self else {
+                DispatchQueue.main.async { completion() }
+                return
+            }
+
+            if !self.isRecording {
+                DispatchQueue.main.async { completion() }
+                return
+            }
+
+            self.autoStopTimer?.cancel()
+            self.autoStopTimer = nil
+
+            // Detach sinks/taps so no more frames arrive on the recorder path.
+            self.videoPipeline?.detachSink()
+            self.audioPipeline?.detachSink()
+
+            let video = self.videoPipeline
+            let audio = self.audioPipeline
+            let writer = self.assetWriter
+            let outputURL = self.outputURL
+
+            self.isRecording = false
+
+            // If the writer never started (no encoded sample ever made it
+            // out), there's nothing to finalise.
+            guard let assetWriter = writer, assetWriter.status == .writing else {
+                NSLog("[TracksRecorder] stopRecording: writer not in .writing (status=%ld) — no file produced",
+                      Int(writer?.status.rawValue ?? -1))
+                video?.logSummary()
+                audio?.logSummary()
+                self.fireTerminalCompletion(url: nil, error: writer?.error as NSError?)
+                self.cleanupAfterStop()
+                DispatchQueue.main.async { completion() }
+                return
+            }
+
+            video?.markInputAsFinished()
+            audio?.markInputAsFinished()
+
+            assetWriter.finishWriting { [weak self] in
+                guard let self = self else {
+                    DispatchQueue.main.async { completion() }
+                    return
+                }
+                self.queue.async {
+                    let resolved: URL? = (assetWriter.status == .completed) ? outputURL : nil
+                    let writerError: NSError? = (assetWriter.status == .failed)
+                        ? (assetWriter.error as NSError?)
+                        : nil
+                    video?.logSummary()
+                    audio?.logSummary()
+                    NSLog("[TracksRecorder] recording finalised → %@",
+                          resolved?.absoluteString ?? "(no file produced)")
+                    self.fireTerminalCompletion(url: resolved, error: writerError)
+                    self.cleanupAfterStop()
+                    DispatchQueue.main.async { completion() }
+                }
+            }
+        }
+    }
+
+    @objc public func clearRecordingsDirectory(completion: @escaping (NSError?) -> Void) {
+        queue.async { [weak self] in
+            guard let self = self else { return }
+            let fm = FileManager.default
+            do {
+                let contents = try fm.contentsOfDirectory(
+                    at: self.recordingsDirectory,
+                    includingPropertiesForKeys: nil,
+                    options: []
+                )
+                for url in contents {
+                    try? fm.removeItem(at: url)
+                }
+                DispatchQueue.main.async { completion(nil) }
+            } catch {
+                DispatchQueue.main.async { completion(error as NSError) }
+            }
+        }
+    }
+
+    @objc public func listRecordings() -> [URL] {
+        let fm = FileManager.default
+        guard let contents = try? fm.contentsOfDirectory(
+            at: recordingsDirectory,
+            includingPropertiesForKeys: [.contentModificationDateKey],
+            options: [.skipsHiddenFiles]
+        ) else {
+            return []
+        }
+        return contents.sorted { lhs, rhs in
+            let lDate = (try? lhs.resourceValues(forKeys: [.contentModificationDateKey]).contentModificationDate) ?? .distantPast
+            let rDate = (try? rhs.resourceValues(forKeys: [.contentModificationDateKey]).contentModificationDate) ?? .distantPast
+            return lDate > rDate
+        }
+    }
+
+    // MARK: - PipelineHost
+
+    func seedOriginNs(_ timestampNs: UInt64) -> UInt64 {
+        if let existing = recordingStartHostTimeNs { return existing }
+        recordingStartHostTimeNs = timestampNs
+        return timestampNs
+    }
+
+    func onTrackAdded() {
+        pendingPipelines = max(0, pendingPipelines - 1)
+        maybeStartSession()
+    }
+
+    func onFatalError(_ error: NSError) {
+        fireTerminalCompletion(url: nil, error: error)
+        cleanupAfterFailure()
+    }
+
+    // MARK: - Internal helpers
+
+    /// Starts the writer once every active pipeline has reported its input
+    /// added. Calling `startWriting()` / `startSession(.zero)` before all
+    /// inputs are present would leave un-added tracks orphaned; the gate
+    /// is load-bearing.
+    private func maybeStartSession() {
+        guard let writer = assetWriter else { return }
+        if pendingPipelines > 0 { return }
+        if writer.status != .unknown { return }
+
+        guard writer.startWriting() else {
+            let err = (writer.error as NSError?) ?? makeRecorderError("start_failed", code: 3)
+            fireTerminalCompletion(url: nil, error: err)
+            cleanupAfterFailure()
+            return
+        }
+        // The session origin is `.zero`; PTS values are computed relative
+        // to `recordingStartHostTimeNs` before being passed to
+        // `VTCompressionSessionEncodeFrame`, so the first encoded sample
+        // already carries pts=0.
+        writer.startSession(atSourceTime: .zero)
+        NSLog("[TracksRecorder] writer.startWriting() + startSession(.zero)")
+    }
+
+    private func fireTerminalCompletion(url: URL?, error: NSError?) {
+        guard !isCompleted else { return }
+        isCompleted = true
+        let cb = recordingCompletion
+        recordingCompletion = nil
+        DispatchQueue.main.async { cb?(url, error) }
+    }
+
+    private func cleanupAfterFailure() {
+        videoPipeline?.detachSink()
+        audioPipeline?.detachSink()
+        autoStopTimer?.cancel()
+        autoStopTimer = nil
+        resetTransientState()
+    }
+
+    private func cleanupAfterStop() {
+        resetTransientState()
+    }
+
+    /// Resets every transient field to its initial value. Single source of
+    /// truth for "the manager is between recordings". Does NOT release
+    /// native resources — the caller must have already torn down the
+    /// pipelines and the writer.
+    private func resetTransientState() {
+        videoPipeline = nil
+        audioPipeline = nil
+        assetWriter = nil
+        outputURL = nil
+        recordingCompletion = nil
+        isCompleted = false
+        isRecording = false
+        pendingPipelines = 0
+        recordingStartHostTimeNs = nil
+        autoStopTimer?.cancel()
+        autoStopTimer = nil
+    }
+}

package/ios/TracksRecorder/VideoPipeline.swift

@@ -0,0 +1,297 @@
+//
+// Copyright © 2026 Stream.io Inc. All rights reserved.
+//
+
+import AVFoundation
+import CoreMedia
+import CoreVideo
+import Foundation
+import WebRTC
+
+/// Video pipeline owned by `TracksRecorderManager`. Encapsulates the H.264
+/// video path:
+///  - the `RecorderVideoSink` attached to the source `RTCVideoTrack`,
+///  - an `AVAssetWriterInput` configured for H.264 encoding (codec, bitrate,
+///    profile, key-frame interval) paired with an
+///    `AVAssetWriterInputPixelBufferAdaptor` — AVFoundation owns the encoder
+///    and picks hardware/software automatically. No manual VT session.
+///  - per-recording counters / PTS range surfaced via `logSummary` at stop.
+///
+/// All state mutation runs on the host's serial queue. Frames arrive on the
+/// WebRTC sink thread and re-dispatch onto `host.queue` before touching
+/// pipeline state.
+internal final class VideoPipeline {
+
+    private static let bitRate: NSNumber = NSNumber(value: 1_000_000)
+
+    private weak var host: PipelineHost?
+    private let videoTrack: RTCVideoTrack
+    private let targetWidth: Int32
+    private let targetHeight: Int32
+
+    private var sink: RecorderVideoSink?
+    private var videoInput: AVAssetWriterInput?
+    private var pixelBufferAdaptor: AVAssetWriterInputPixelBufferAdaptor?
+    private var inputAdded = false
+
+    // Diagnostic counters + PTS range, surfaced via [logSummary] at stop.
+    private var framesReceived = 0
+    private var samplesAppended = 0
+    private var frameAppendFailures = 0
+    private var framesDropped = 0
+    private var firstSamplePtsUs: Int64 = -1
+    private var lastSamplePtsUs: Int64 = -1
+
+    // MARK: - Init
+
+    init(
+        host: PipelineHost,
+        videoTrack: RTCVideoTrack,
+        targetWidth: Int32 = 0,
+        targetHeight: Int32 = 0
+    ) {
+        self.host = host
+        self.videoTrack = videoTrack
+        self.targetWidth = targetWidth
+        self.targetHeight = targetHeight
+    }
+
+    // MARK: - Public API
+
+    /// Attach the sink to the source track. Future frames post to
+    /// `host.queue` and run through the per-frame handler.
+    func start() {
+        let sink = RecorderVideoSink { [weak self] pixelBuffer, width, height, timestampNs in
+            self?.handleVideoFrame(
+                pixelBuffer: pixelBuffer,
+                width: width,
+                height: height,
+                timestampNs: timestampNs
+            )
+        }
+        self.sink = sink
+        videoTrack.add(sink)
+    }
+
+    /// On-queue. Remove the sink from the source track so no more frames
+    /// arrive. Idempotent.
+    func detachSink() {
+        if let sink = sink {
+            videoTrack.remove(sink)
+        }
+        sink = nil
+    }
+
+    /// On-queue. Marks the asset-writer input as finished so the writer
+    /// can finalise. AVFoundation's `finishWriting` flushes any pending
+    /// encoded samples internally; no separate drain step is required.
+    func markInputAsFinished() {
+        videoInput?.markAsFinished()
+    }
+
+    /// On-queue. Logs the pipeline's diagnostic summary — call once at the
+    /// end of a recording.
+    func logSummary() {
+        let durationMs: Int64
+        if firstSamplePtsUs >= 0 && lastSamplePtsUs >= firstSamplePtsUs {
+            durationMs = (lastSamplePtsUs - firstSamplePtsUs) / 1000
+        } else {
+            durationMs = -1
+        }
+        let writerStatus = host?.assetWriter?.status.rawValue ?? -1
+        let writerErr = (host?.assetWriter?.error as NSError?)?.localizedDescription ?? "nil"
+        NSLog(
+            "[TracksRecorder.Video] summary received=%d appended=%d appendFailures=%d dropped=%d firstPtsUs=%lld lastPtsUs=%lld durationMs=%lld writerStatus=%ld writerErr=%@",
+            framesReceived,
+            samplesAppended,
+            frameAppendFailures,
+            framesDropped,
+            firstSamplePtsUs,
+            lastSamplePtsUs,
+            durationMs,
+            writerStatus,
+            writerErr
+        )
+    }
+
+    // MARK: - Sink → queue bridge
+
+    private func handleVideoFrame(
+        pixelBuffer: CVPixelBuffer,
+        width: Int32,
+        height: Int32,
+        timestampNs: Int64
+    ) {
+        guard let host = host else { return }
+
+        // Pixel buffer is borrowed from the sink — it must be retained
+        // across the queue hop. The closure capture pins it for the
+        // duration of the async block (ARC retains it as part of the
+        // closure's captured state).
+        host.queue.async { [weak self, pixelBuffer] in
+            self?.handleVideoFrameOnQueue(
+                pixelBuffer: pixelBuffer,
+                width: width,
+                height: height,
+                timestampNs: timestampNs
+            )
+        }
+    }
+
+    private func handleVideoFrameOnQueue(
+        pixelBuffer: CVPixelBuffer,
+        width: Int32,
+        height: Int32,
+        timestampNs: Int64
+    ) {
+        guard let host = host, host.isRecording, let writer = host.assetWriter else { return }
+
+        framesReceived += 1
+
+        // Lazy-create the writer's video input on the first frame.
+        // Prefer the publisher's max video dimensions so the encoder
+        // is sized for the highest layer the SFU might ever forward;
+        // fall back to the first frame's actual dimensions when no
+        // target is supplied.
+        if videoInput == nil {
+            let actualW = Int32(CVPixelBufferGetWidth(pixelBuffer))
+            let actualH = Int32(CVPixelBufferGetHeight(pixelBuffer))
+            let (encW, encH) = resolveEncoderDimensions(
+                targetW: targetWidth,
+                targetH: targetHeight,
+                frameW: actualW,
+                frameH: actualH
+            )
+            let pixelFormat = CVPixelBufferGetPixelFormatType(pixelBuffer)
+            configureVideoInput(
+                width: encW,
+                height: encH,
+                pixelFormat: pixelFormat,
+                writer: writer
+            )
+        }
+
+        let pts = presentationTime(host: host, timestampNs: UInt64(bitPattern: timestampNs))
+
+        guard
+            writer.status == .writing,
+            let input = videoInput,
+            let adaptor = pixelBufferAdaptor
+        else {
+            if writer.status == .failed {
+                let err = writer.error as NSError?
+                NSLog("[TracksRecorder.Video] writer FAILED in frame handler: domain=%@ code=%ld desc=%@",
+                      err?.domain ?? "nil", err?.code ?? 0,
+                      err?.localizedDescription ?? "nil")
+            }
+            return
+        }
+
+        if !input.isReadyForMoreMediaData {
+            framesDropped += 1
+            if framesDropped % 30 == 1 {
+                NSLog("[TracksRecorder.Video] input not ready, dropped=%d", framesDropped)
+            }
+            return
+        }
+
+        let appended = adaptor.append(pixelBuffer, withPresentationTime: pts)
+        if appended {
+            samplesAppended += 1
+            let ptsUs = Int64(CMTimeGetSeconds(pts) * 1_000_000)
+            if firstSamplePtsUs < 0 || ptsUs < firstSamplePtsUs {
+                firstSamplePtsUs = ptsUs
+            }
+            if ptsUs > lastSamplePtsUs {
+                lastSamplePtsUs = ptsUs
+            }
+            if samplesAppended == 1 {
+                NSLog("[TracksRecorder.Video] first frame appended OK pts=%lldus", ptsUs)
+            }
+        } else {
+            // `adaptor.append` returns false without a direct reason —
+            // inspect `writer.error` and the input's ready flag for
+            // diagnostics.
+            frameAppendFailures += 1
+            let writerErr = writer.error as NSError?
+            NSLog(
+                "[TracksRecorder.Video] adaptor.append FAILED #%d writerStatus=%ld writerErr domain=%@ code=%ld desc=%@ inputReady=%@",
+                frameAppendFailures,
+                writer.status.rawValue,
+                writerErr?.domain ?? "nil",
+                writerErr?.code ?? 0,
+                writerErr?.localizedDescription ?? "nil",
+                input.isReadyForMoreMediaData ? "YES" : "NO"
+            )
+        }
+    }
+
+    // MARK: - Asset writer input setup
+
+    /// Picks the encoder dimensions, preferring the caller-supplied
+    /// target but oriented to match the frame buffer. Publish options
+    /// are expressed in WebRTC's canonical landscape form; the buffer
+    /// may be portrait — swap target axes when they disagree. Falls
+    /// back to the frame's own dimensions if no target was supplied.
+    private func resolveEncoderDimensions(
+        targetW: Int32,
+        targetH: Int32,
+        frameW: Int32,
+        frameH: Int32
+    ) -> (Int32, Int32) {
+        guard targetW > 0 && targetH > 0 else { return (frameW, frameH) }
+        let framePortrait = frameH > frameW
+        let targetPortrait = targetH > targetW
+        if framePortrait == targetPortrait {
+            return (targetW, targetH)
+        }
+        return (targetH, targetW)
+    }
+
+    /// Builds the H.264 `AVAssetWriterInput` and its pixel-buffer
+    /// adaptor. AVFoundation owns the encoder and falls back from
+    /// hardware to software if the H.264 pool is contended.
+    private func configureVideoInput(
+        width: Int32,
+        height: Int32,
+        pixelFormat: OSType,
+        writer: AVAssetWriter
+    ) {
+        // `AVVideoScalingModeResizeAspect` lets AVFoundation scale
+        // incoming pixel buffers to the encoder's output dimensions
+        // while preserving aspect ratio.
+        let settings: [String: Any] = [
+            AVVideoCodecKey: AVVideoCodecType.h264,
+            AVVideoWidthKey: width,
+            AVVideoHeightKey: height,
+            AVVideoScalingModeKey: AVVideoScalingModeResizeAspect,
+            AVVideoCompressionPropertiesKey: [
+                AVVideoAverageBitRateKey: VideoPipeline.bitRate,
+            ],
+        ]
+        let input = AVAssetWriterInput(mediaType: .video, outputSettings: settings)
+        input.expectsMediaDataInRealTime = true
+
+        // Omit width/height in source attributes so the adaptor
+        // accepts buffers at any layer resolution the SFU forwards.
+        let pbAttributes: [String: Any] = [
+            kCVPixelBufferPixelFormatTypeKey as String: pixelFormat,
+        ]
+        let adaptor = AVAssetWriterInputPixelBufferAdaptor(
+            assetWriterInput: input,
+            sourcePixelBufferAttributes: pbAttributes
+        )
+
+        guard writer.canAdd(input) else {
+            NSLog("[TracksRecorder.Video] writer cannot add encoding video input")
+            host?.onFatalError(makeRecorderError("video_input_add_failed", code: 4))
+            return
+        }
+
+        writer.add(input)
+        videoInput = input
+        pixelBufferAdaptor = adaptor
+        inputAdded = true
+        host?.onTrackAdded()
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stream-io/video-react-native-sdk",
-  "version": "1.38.2",
+  "version": "1.39.1-beta.0",
   "description": "Stream Video SDK for React Native",
   "author": "https://getstream.io",
   "homepage": "https://getstream.io/video/docs/react-native/",
@@ -32,6 +32,7 @@
     "cpp",
     "stream-video-react-native.podspec",
     "package.json",
+    "CHANGELOG.md",
     "app.plugin.js",
     "expo-config-plugin/README.md",
     "expo-config-plugin/static/**/*",
@@ -50,8 +51,8 @@
     "!**/.*"
   ],
   "dependencies": {
-    "@stream-io/video-client": "1.53.2",
-    "@stream-io/video-react-bindings": "1.16.5",
+    "@stream-io/video-client": "1.54.1-beta.0",
+    "@stream-io/video-react-bindings": "1.17.0",
     "intl-pluralrules": "2.0.1",
     "react-native-url-polyfill": "^3.0.0",
     "rxjs": "~7.8.2",
@@ -116,10 +117,10 @@
     "@react-native-firebase/messaging": "^24.0.0",
     "@react-native/babel-preset": "0.85.3",
     "@react-native/metro-config": "0.85.3",
-    "@stream-io/noise-cancellation-react-native": "^0.8.0",
-    "@stream-io/react-native-callingx": "^0.5.1",
+    "@stream-io/noise-cancellation-react-native": "0.8.0",
+    "@stream-io/react-native-callingx": "0.5.1",
     "@stream-io/react-native-webrtc": "145.0.0",
-    "@stream-io/video-filters-react-native": "^0.13.0",
+    "@stream-io/video-filters-react-native": "0.13.0",
     "@testing-library/jest-native": "^5.4.3",
     "@testing-library/react-native": "13.3.3",
     "@tsconfig/node18": "^18.2.6",