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

package/ios/TracksRecorder/AudioPipeline.swift

@@ -0,0 +1,270 @@
+//
+// Copyright © 2026 Stream.io Inc. All rights reserved.
+//
+
+import AVFoundation
+import CoreMedia
+import Foundation
+import WebRTC
+
+/// Audio pipeline owned by `TracksRecorderManager`. Encapsulates the AAC audio path:
+///  - the `RecorderAudioRenderTap` installed on
+///    `RTCDefaultAudioProcessingModule.renderPreProcessingDelegate`
+///    (post-mix decoded audio, no per-track lookup required),
+///  - the in-place speaker mute (`muteOriginal: true` on the tap; the tap
+///    zero-fills the buffer after copying for recording),
+///  - the AAC `AVAssetWriterInput` (writer-driven encode via
+///    `outputSettings`),
+///  - per-recording counters / PTS range surfaced via `logSummary` at stop.
+///
+/// All state mutation runs on the host's serial queue. The tap's
+/// callback runs on a WebRTC audio thread and re-dispatches onto
+/// `host.queue` after copying the PCM buffer.
+internal final class AudioPipeline {
+
+    private static let aacBitRate: NSNumber = NSNumber(value: 64_000)
+
+    private weak var host: PipelineHost?
+
+    private let apm: RTCDefaultAudioProcessingModule
+
+    private var renderTap: RecorderAudioRenderTap?
+    private var audioInput: AVAssetWriterInput?
+    private var inputAdded = false
+
+    // Diagnostic counters + PTS range, surfaced via [logSummary] at stop.
+    private var buffersReceived = 0
+    private var samplesAppended = 0
+    private var buffersDropped = 0
+    private var firstSamplePtsUs: Int64 = -1
+    private var lastSamplePtsUs: Int64 = -1
+
+    // MARK: - Init
+
+    init(host: PipelineHost, apm: RTCDefaultAudioProcessingModule) {
+        self.host = host
+        self.apm = apm
+    }
+
+    // MARK: - Public API
+
+    /// Install the render-tap as the APM's `renderPreProcessingDelegate`.
+    /// The tap copies PCM into a new buffer for recording AND zero-fills the
+    /// original (post-mix decoded audio) so the speaker plays silence —
+    /// this gives "audio in the file, silence at the speaker" without
+    /// disrupting the recording. The standard `track.setVolume(0)` /
+    /// `track.isEnabled = false` mutes apply *before* this tap and would
+    /// silence the recording too.
+    func start() {
+        let tap = RecorderAudioRenderTap(muteOriginal: true) { [weak self] pcmBuffer in
+            self?.handleAudioBuffer(pcmBuffer: pcmBuffer)
+        }
+        renderTap = tap
+        apm.renderPreProcessingDelegate = tap
+    }
+
+    /// On-queue. Clear the render-tap delegate slot — only if it still
+    /// points to this pipeline's tap. If another consumer has rotated in,
+    /// leave theirs alone.
+    func detachSink() {
+        if let tap = renderTap, apm.renderPreProcessingDelegate === tap {
+            apm.renderPreProcessingDelegate = nil
+        }
+        renderTap = nil
+    }
+
+    /// On-queue. Marks the asset-writer input as finished so the writer can
+    /// finalise.
+    func markInputAsFinished() {
+        audioInput?.markAsFinished()
+    }
+
+    func logSummary() {
+        let tapCalls = renderTap?.callCount ?? -1
+        let durationMs: Int64
+        if firstSamplePtsUs >= 0 && lastSamplePtsUs >= firstSamplePtsUs {
+            durationMs = (lastSamplePtsUs - firstSamplePtsUs) / 1000
+        } else {
+            durationMs = -1
+        }
+        NSLog(
+            "[TracksRecorder.Audio] summary received=%d appended=%d dropped=%d tapCalls=%d firstPtsUs=%lld lastPtsUs=%lld durationMs=%lld",
+            buffersReceived,
+            samplesAppended,
+            buffersDropped,
+            tapCalls,
+            firstSamplePtsUs,
+            lastSamplePtsUs,
+            durationMs
+        )
+    }
+
+    // MARK: - Tap → queue bridge
+
+    private func handleAudioBuffer(pcmBuffer: AVAudioPCMBuffer) {
+        // Unlike `VideoPipeline`'s `CVPixelBuffer` closure capture, an
+        // ARC-retained `AVAudioPCMBuffer` does *not* extend the lifetime
+        // of the underlying PCM samples — those live in WebRTC's
+        // render-buffer pool and are reused the moment this callback
+        // returns. A deep copy before the queue hop is mandatory.
+        guard let copy = AudioPipeline.deepCopyPCMBuffer(pcmBuffer) else { return }
+        guard let host = host else { return }
+
+        // `DispatchTime.now().uptimeNanoseconds` is the monotonic clock
+        // that matches `RTCVideoFrame.timeStampNs` on iOS — both reduce
+        // to `mach_absolute_time()` converted to nanoseconds, so the
+        // shared time origin works coherently across both pipelines.
+        let captureTimeNs = DispatchTime.now().uptimeNanoseconds
+        host.queue.async { [weak self] in
+            self?.handleAudioBufferOnQueue(pcmBuffer: copy, captureTimeNs: captureTimeNs)
+        }
+    }
+
+    private func handleAudioBufferOnQueue(pcmBuffer: AVAudioPCMBuffer, captureTimeNs: UInt64) {
+        guard let host = host, host.isRecording, let writer = host.assetWriter else { return }
+
+        // Lazy-create the writer's audio input on the first buffer. The
+        // input's settings depend on the runtime PCM format reported by
+        // WebRTC.
+        if audioInput == nil {
+            configureAudioInput(format: pcmBuffer.format, writer: writer)
+        }
+
+        let pts = presentationTime(host: host, timestampNs: captureTimeNs)
+
+        guard writer.status == .writing,
+              let audioInput = audioInput,
+              audioInput.isReadyForMoreMediaData else {
+            buffersDropped += 1
+            return
+        }
+
+        guard let sampleBuffer = AudioPipeline.makeSampleBuffer(from: pcmBuffer, pts: pts) else {
+            buffersDropped += 1
+            return
+        }
+
+        if audioInput.append(sampleBuffer) {
+            buffersReceived += 1
+            samplesAppended += 1
+            let ptsUs = Int64(CMTimeGetSeconds(pts) * 1_000_000)
+            if firstSamplePtsUs < 0 || ptsUs < firstSamplePtsUs {
+                firstSamplePtsUs = ptsUs
+            }
+            if ptsUs > lastSamplePtsUs {
+                lastSamplePtsUs = ptsUs
+            }
+        } else {
+            buffersDropped += 1
+        }
+    }
+
+    // MARK: - Asset writer input setup
+
+    private func configureAudioInput(format: AVAudioFormat, writer: AVAssetWriter) {
+        let settings: [String: Any] = [
+            AVFormatIDKey: NSNumber(value: kAudioFormatMPEG4AAC),
+            AVSampleRateKey: NSNumber(value: format.sampleRate),
+            AVNumberOfChannelsKey: NSNumber(value: format.channelCount),
+            AVEncoderBitRateKey: AudioPipeline.aacBitRate,
+        ]
+        let input = AVAssetWriterInput(mediaType: .audio, outputSettings: settings)
+        input.expectsMediaDataInRealTime = true
+
+        guard writer.canAdd(input) else {
+            NSLog("[TracksRecorder.Audio] writer cannot add audio input")
+            host?.onFatalError(makeRecorderError("audio_input_add_failed", code: 4))
+            return
+        }
+         
+        writer.add(input)
+        audioInput = input
+        inputAdded = true
+        host?.onTrackAdded()
+    }
+
+    // MARK: - PCM → CMSampleBuffer helper
+
+    /// Converts an `AVAudioPCMBuffer` into a `CMSampleBuffer` suitable for
+    /// `AVAssetWriterInput.append`. Returns `nil` if any Core Media call
+    /// fails; the caller treats that as a dropped buffer.
+    private static func makeSampleBuffer(
+        from pcmBuffer: AVAudioPCMBuffer,
+        pts: CMTime
+    ) -> CMSampleBuffer? {
+        var formatDescription: CMAudioFormatDescription?
+        let createDescStatus = CMAudioFormatDescriptionCreate(
+            allocator: kCFAllocatorDefault,
+            asbd: pcmBuffer.format.streamDescription,
+            layoutSize: 0,
+            layout: nil,
+            magicCookieSize: 0,
+            magicCookie: nil,
+            extensions: nil,
+            formatDescriptionOut: &formatDescription
+        )
+        guard createDescStatus == noErr, let formatDesc = formatDescription else { return nil }
+
+        var sampleBuffer: CMSampleBuffer?
+        var timing = CMSampleTimingInfo(
+            duration: CMTime(value: 1, timescale: Int32(pcmBuffer.format.sampleRate)),
+            presentationTimeStamp: pts,
+            decodeTimeStamp: .invalid
+        )
+        let createStatus = CMSampleBufferCreate(
+            allocator: kCFAllocatorDefault,
+            dataBuffer: nil,
+            dataReady: false,
+            makeDataReadyCallback: nil,
+            refcon: nil,
+            formatDescription: formatDesc,
+            sampleCount: CMItemCount(pcmBuffer.frameLength),
+            sampleTimingEntryCount: 1,
+            sampleTimingArray: &timing,
+            sampleSizeEntryCount: 0,
+            sampleSizeArray: nil,
+            sampleBufferOut: &sampleBuffer
+        )
+        guard createStatus == noErr, let sb = sampleBuffer else { return nil }
+
+        let setStatus = CMSampleBufferSetDataBufferFromAudioBufferList(
+            sb,
+            blockBufferAllocator: kCFAllocatorDefault,
+            blockBufferMemoryAllocator: kCFAllocatorDefault,
+            flags: 0,
+            bufferList: pcmBuffer.audioBufferList
+        )
+        guard setStatus == noErr else { return nil }
+        return sb
+    }
+
+    /// Returns a deep copy of the supplied `AVAudioPCMBuffer`. WebRTC owns
+    /// the source buffer's backing memory only for the duration of the
+    /// render-tap callback; ARC retains the wrapper across the queue hop
+    /// but not the underlying PCM samples. Copying here lets the recorder
+    /// queue read the data later without racing WebRTC's render-buffer
+    /// reuse.
+    private static func deepCopyPCMBuffer(_ source: AVAudioPCMBuffer) -> AVAudioPCMBuffer? {
+        guard let copy = AVAudioPCMBuffer(
+            pcmFormat: source.format,
+            frameCapacity: source.frameCapacity
+        ) else { return nil }
+        copy.frameLength = source.frameLength
+        let frameLength = Int(source.frameLength)
+        let channelCount = Int(source.format.channelCount)
+        if let src = source.int16ChannelData, let dst = copy.int16ChannelData {
+            for ch in 0..<channelCount {
+                memcpy(dst[ch], src[ch], frameLength * MemoryLayout<Int16>.size)
+            }
+        } else if let src = source.floatChannelData, let dst = copy.floatChannelData {
+            for ch in 0..<channelCount {
+                memcpy(dst[ch], src[ch], frameLength * MemoryLayout<Float>.size)
+            }
+        } else if let src = source.int32ChannelData, let dst = copy.int32ChannelData {
+            for ch in 0..<channelCount {
+                memcpy(dst[ch], src[ch], frameLength * MemoryLayout<Int32>.size)
+            }
+        }
+        return copy
+    }
+}

package/ios/TracksRecorder/PipelineHost.swift

@@ -0,0 +1,56 @@
+//
+// Copyright © 2026 Stream.io Inc. All rights reserved.
+//
+
+import AVFoundation
+import CoreMedia
+import Foundation
+
+/// Internal coordination contract between `TracksRecorderManager` and its
+/// per-kind pipelines (`VideoPipeline`, `AudioPipeline`). The pipelines own
+/// their encoder + sink + drain logic; the host owns lifecycle, the asset
+/// writer, the writer-start gate, the shared time origin, and the terminal-
+/// completion barrier.
+///
+/// Every method on this protocol is called from the host's serial queue —
+/// pipelines must `host.queue.async { ... }` before calling back into the
+/// host. The protocol is class-bound so pipelines can hold a `weak`
+/// reference and avoid retain cycles.
+internal protocol PipelineHost: AnyObject {
+    /// The recorder's serial dispatch queue.
+    var queue: DispatchQueue { get }
+
+    var assetWriter: AVAssetWriter? { get }
+
+    var isRecording: Bool { get }
+
+    /// Returns the recording's shared time origin in nanoseconds. The first
+    /// pipeline to deliver a sample seeds the origin with its timestamp;
+    /// subsequent calls return the established value.
+    func seedOriginNs(_ timestampNs: UInt64) -> UInt64
+
+    /// Pipeline has added an input to the writer. The host decrements its
+    /// pending-pipeline counter and starts the writer once all expected
+    /// pipelines have reported their input.
+    func onTrackAdded()
+
+    func onFatalError(_ error: NSError)
+}
+
+/// Maps an absolute monotonic timestamp (nanoseconds) to presentation time
+/// relative to the recording's shared origin. The first sample from either
+/// pipeline seeds the origin via `host.seedOriginNs`; later samples use
+/// elapsed = timestamp − origin (clamped to 0).
+internal func presentationTime(host: PipelineHost, timestampNs: UInt64) -> CMTime {
+    let origin = host.seedOriginNs(timestampNs)
+    let elapsed: Int64 = timestampNs >= origin ? Int64(timestampNs - origin) : 0
+    return CMTime(value: elapsed, timescale: 1_000_000_000)
+}
+
+internal func makeRecorderError(_ message: String, code: Int) -> NSError {
+    NSError(
+        domain: "io.stream.video.tracks-recorder",
+        code: code,
+        userInfo: [NSLocalizedDescriptionKey: message]
+    )
+}

package/ios/TracksRecorder/RecorderAudioRenderTap.swift

@@ -0,0 +1,154 @@
+//
+// Copyright © 2026 Stream.io Inc. All rights reserved.
+//
+
+import AVFoundation
+import CoreMedia
+import Foundation
+import WebRTC
+
+/// Render-side audio tap used by `TracksRecorderManager`. Implements
+/// `RTCAudioCustomProcessingDelegate` and is installed on
+/// `RTCDefaultAudioProcessingModule.renderPreProcessingDelegate` for the
+/// duration of a recording.
+///
+/// The render path WebRTC is using:
+/// ```
+/// SFU → decoder → audio mixer → renderPreProcessingDelegate →
+///   render-side processing → speaker
+/// ```
+///
+/// What the delegate sees per call: an `RTCAudioBuffer` that holds the
+/// **post-mix** decoded audio about to be played to the speaker. In a
+/// self-sub-only call, that's exactly the SFU echo of the local mic. In a
+/// call with multiple remote participants the buffer contains the
+/// post-mix output (everyone blended together).
+///
+/// **Important:** `RTCAudioBuffer` exposes `rawBuffer(forChannel:)` as
+/// `UnsafeMutablePointer<Float>` in **FloatS16** format — i.e. Float32 values
+/// in the Int16 range -32768…32767. Cast/clamp to `Int16` for the PCM
+/// destination buffer (no normalisation needed).
+///
+/// **Threading:** all three protocol methods run on a WebRTC audio
+/// processing thread. The buffer handler closure is invoked from there; the
+/// caller is responsible for hopping queues if needed.
+///
+/// **Lifetime:** `RTCDefaultAudioProcessingModule.renderPreProcessingDelegate`
+/// is `weak`, so the manager must keep this instance alive for the duration
+/// of recording.
+@objc public final class RecorderAudioRenderTap: NSObject, RTCAudioCustomProcessingDelegate {
+
+    typealias BufferHandler = (AVAudioPCMBuffer) -> Void
+
+    private let bufferHandler: BufferHandler
+
+    /// When `true`, the WebRTC `RTCAudioBuffer` is zero-filled in place
+    /// *after* the samples have been copied into the recording PCM buffer.
+    /// The recording keeps the original audio; everything downstream of
+    /// this delegate (render-side APM → audio device module → speaker)
+    /// sees silence. This yields "audio in the file, silence at the
+    /// speaker" without disrupting the recording — `track.setVolume(0)`
+    /// / `track.isEnabled = false` mutes apply *before* this tap and
+    /// would silence the recording too.
+    ///
+    /// Side effect to be aware of: this mutes the entire post-mix
+    /// playback, not just one track. In a self-sub-only call post-mix ==
+    /// loopback, so it's effectively a per-track mute. With other remote
+    /// participants in the call they would be muted at the speaker too
+    /// while recording is active.
+    private let muteOriginal: Bool
+
+    private var processingSampleRate: Double = 0
+    private var processingChannels: Int = 0
+    private var avFormat: AVAudioFormat?
+
+    /// Atomic-style call counter — exposes whether the APM is invoking
+    /// `audioProcessingProcess(audioBuffer:)` at all.
+    private let counterLock = NSLock()
+    private var _callCount: Int = 0
+    @objc public var callCount: Int {
+        counterLock.lock()
+        defer { counterLock.unlock() }
+        return _callCount
+    }
+
+    init(muteOriginal: Bool, bufferHandler: @escaping BufferHandler) {
+        self.muteOriginal = muteOriginal
+        self.bufferHandler = bufferHandler
+        super.init()
+    }
+
+    // MARK: - RTCAudioCustomProcessingDelegate
+
+    public func audioProcessingInitialize(sampleRate: Int, channels: Int) {
+        processingSampleRate = Double(sampleRate)
+        processingChannels = channels
+        avFormat = AVAudioFormat(
+            commonFormat: .pcmFormatInt16,
+            sampleRate: processingSampleRate,
+            channels: AVAudioChannelCount(channels),
+            interleaved: false
+        )
+        NSLog("[TracksRecorder] RenderTap initialize sampleRate=%d channels=%d",
+              sampleRate, channels)
+    }
+
+    public func audioProcessingProcess(audioBuffer: RTCAudioBuffer) {
+        counterLock.lock()
+        _callCount += 1
+        let count = _callCount
+        counterLock.unlock()
+
+        if count == 1 {
+            NSLog("[TracksRecorder] RenderTap FIRST call frames=%d channels=%d",
+                  audioBuffer.frames, audioBuffer.channels)
+        } else if count % 100 == 0 {
+            NSLog("[TracksRecorder] RenderTap call #%d", count)
+        }
+
+        guard let format = avFormat else { return }
+        let frames = Int(audioBuffer.frames)
+        let channels = Int(audioBuffer.channels)
+        guard frames > 0, channels > 0 else { return }
+
+        guard let pcm = AVAudioPCMBuffer(
+            pcmFormat: format,
+            frameCapacity: AVAudioFrameCount(frames)
+        ) else {
+            return
+        }
+        pcm.frameLength = AVAudioFrameCount(frames)
+        guard let dst = pcm.int16ChannelData else { return }
+
+        // Copy each channel: FloatS16 (Float32 in Int16 range) → Int16.
+        // No normalisation needed — values already span the Int16 range.
+        for ch in 0..<channels {
+            let src = audioBuffer.rawBuffer(forChannel: ch)
+            let dstChannel = dst[ch]
+            for i in 0..<frames {
+                let v = src[i]
+                if v >= 32767 {
+                    dstChannel[i] = Int16.max
+                } else if v <= -32768 {
+                    dstChannel[i] = Int16.min
+                } else {
+                    dstChannel[i] = Int16(v)
+                }
+
+                // If `muteOriginal` is on, zero the source buffer in the same pass
+                // so the data continuing downstream to the speaker is silence.
+                if muteOriginal {
+                    src[i] = 0
+                }
+            }
+        }
+
+        bufferHandler(pcm)
+    }
+
+    public func audioProcessingRelease() {
+        avFormat = nil
+        // Deliberately preserve `_callCount` — useful in end-of-recording
+        // diagnostics even after release.
+    }
+}

package/ios/TracksRecorder/RecorderVideoSink.swift

@@ -0,0 +1,137 @@
+//
+// Copyright © 2026 Stream.io Inc. All rights reserved.
+//
+
+import CoreMedia
+import CoreVideo
+import Foundation
+import WebRTC
+
+/// Per-track video sink used by `TracksRecorderManager`. Implements
+/// `RTCVideoRenderer` so it can be attached directly to an `RTCVideoTrack`.
+///
+/// Each delivered `RTCVideoFrame` is normalised to a CVPixelBuffer in the
+/// hardware H.264 encoder's native format — **NV12**
+/// (`kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange`).
+/// `RTCCVPixelBuffer` sources (camera passthrough) are forwarded with
+/// the underlying pixel buffer unchanged. `RTCI420Buffer` and other YUV
+/// sources are converted into a fresh IOSurface-backed NV12 buffer via
+/// a plane reorder (no color-space conversion required).
+///
+/// **Why NV12 and not BGRA?** AVAssetWriter's hardware encoder accepts
+/// both, but BGRA requires an internal colour-space conversion that
+/// fails with VideoToolbox `-16364` on certain stride/alignment
+/// combinations a few frames in. NV12 is the encoder's native input;
+/// passing it directly bypasses the failure entirely.
+///
+/// Threading: `renderFrame` runs on a WebRTC frame-delivery thread; the
+/// callback must be safe to invoke from there. The manager serialises
+/// further access on its own queue.
+@objc final class RecorderVideoSink: NSObject, RTCVideoRenderer {
+
+    typealias FrameHandler = (_ pixelBuffer: CVPixelBuffer, _ width: Int32, _ height: Int32, _ timestampNs: Int64) -> Void
+
+    private let frameHandler: FrameHandler
+
+    init(frameHandler: @escaping FrameHandler) {
+        self.frameHandler = frameHandler
+        super.init()
+    }
+
+    // MARK: - RTCVideoRenderer
+
+    func setSize(_ size: CGSize) {
+        // No-op: pixel buffer dimensions are derived from each incoming frame.
+    }
+
+    func renderFrame(_ frame: RTCVideoFrame?) {
+        guard let frame = frame, frame.width > 0, frame.height > 0 else { return }
+
+        let pixelBuffer: CVPixelBuffer?
+        if let cvBuffer = frame.buffer as? RTCCVPixelBuffer {
+            // Camera passthrough — already a CVPixelBuffer (typically NV12 on iOS).
+            pixelBuffer = cvBuffer.pixelBuffer
+        } else if let i420 = frame.buffer as? RTCI420Buffer {
+            pixelBuffer = Self.makeNV12PixelBuffer(fromI420: i420)
+        } else {
+            // Other YUV variants — normalise via toI420() first.
+            let i420 = frame.buffer.toI420()
+            if let concrete = i420 as? RTCI420Buffer {
+                pixelBuffer = Self.makeNV12PixelBuffer(fromI420: concrete)
+            } else {
+                pixelBuffer = nil
+            }
+        }
+
+        guard let outputBuffer = pixelBuffer else { return }
+        frameHandler(outputBuffer, frame.width, frame.height, frame.timeStampNs)
+    }
+
+    // MARK: - I420 → NV12
+
+    /// Allocates a fresh IOSurface-backed NV12 `CVPixelBuffer` and copies
+    /// the I420 source's planes into it (Y as-is, U+V interleaved into the
+    /// UV plane). No colour-space conversion — this is purely a plane
+    /// reorder, so the operation is both fast and bit-exact.
+    private static func makeNV12PixelBuffer(fromI420 i420: RTCI420Buffer) -> CVPixelBuffer? {
+        let width = Int(i420.width)
+        let height = Int(i420.height)
+        let chromaWidth = Int(i420.chromaWidth)
+        let chromaHeight = Int(i420.chromaHeight)
+
+        var pixelBuffer: CVPixelBuffer?
+        let attrs: [String: Any] = [
+            kCVPixelBufferIOSurfacePropertiesKey as String: [:] as [String: Any],
+        ]
+        let status = CVPixelBufferCreate(
+            kCFAllocatorDefault,
+            width,
+            height,
+            kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange,
+            attrs as CFDictionary,
+            &pixelBuffer
+        )
+        guard status == kCVReturnSuccess, let buffer = pixelBuffer else { return nil }
+
+        CVPixelBufferLockBaseAddress(buffer, [])
+        defer { CVPixelBufferUnlockBaseAddress(buffer, []) }
+
+        // Plane 0: Y — direct copy.
+        guard let yDest = CVPixelBufferGetBaseAddressOfPlane(buffer, 0) else { return nil }
+        let yDestStride = CVPixelBufferGetBytesPerRowOfPlane(buffer, 0)
+        let ySrcStride = Int(i420.strideY)
+        let ySrc = UnsafeRawPointer(i420.dataY)
+        if ySrcStride == yDestStride {
+            memcpy(yDest, ySrc, ySrcStride * height)
+        } else {
+            let copyBytes = min(ySrcStride, yDestStride)
+            for row in 0..<height {
+                memcpy(
+                    yDest.advanced(by: row * yDestStride),
+                    ySrc.advanced(by: row * ySrcStride),
+                    copyBytes
+                )
+            }
+        }
+
+        // Plane 1: UV — interleave I420's U and V planes.
+        guard let uvDestRaw = CVPixelBufferGetBaseAddressOfPlane(buffer, 1) else { return nil }
+        let uvDestStride = CVPixelBufferGetBytesPerRowOfPlane(buffer, 1)
+        let uvDest = uvDestRaw.assumingMemoryBound(to: UInt8.self)
+        let uSrcStride = Int(i420.strideU)
+        let vSrcStride = Int(i420.strideV)
+        let uSrc = i420.dataU
+        let vSrc = i420.dataV
+        for row in 0..<chromaHeight {
+            let uRow = uSrc.advanced(by: row * uSrcStride)
+            let vRow = vSrc.advanced(by: row * vSrcStride)
+            let uvRow = uvDest.advanced(by: row * uvDestStride)
+            for col in 0..<chromaWidth {
+                uvRow[col * 2] = uRow[col]
+                uvRow[col * 2 + 1] = vRow[col]
+            }
+        }
+
+        return buffer
+    }
+}