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

package/android/src/main/java/com/streamvideo/reactnative/StreamVideoReactNativeModule.kt

@@ -25,8 +25,10 @@ import com.facebook.react.bridge.ReactContextBaseJavaModule
 import com.facebook.react.bridge.ReactMethod
 import com.facebook.react.bridge.WritableMap
 import com.facebook.react.modules.core.DeviceEventManagerModule.RCTDeviceEventEmitter
+import com.facebook.react.bridge.ReadableMap
 import com.oney.WebRTCModule.WebRTCModule
 import com.oney.WebRTCModule.WebRTCModuleOptions
+import com.streamvideo.reactnative.recorder.TracksRecorderManager
 import com.streamvideo.reactnative.screenshare.ScreenAudioCapture
 import com.streamvideo.reactnative.keepalive.StreamCallKeepAliveHeadlessService
 import com.streamvideo.reactnative.util.CallAlivePermissionsHelper
@@ -41,6 +43,7 @@ import kotlinx.coroutines.launch
 import org.webrtc.VideoSink
 import org.webrtc.VideoTrack
 import java.io.ByteArrayOutputStream
+import java.io.File
 import kotlin.math.sin
 
 
@@ -606,8 +609,86 @@ class StreamVideoReactNativeModule(reactContext: ReactApplicationContext) :
         }
     }
 
+    // ── Track recorder bridge ────────────────────────────────────────────
+
+    @ReactMethod
+    fun startTrackRecording(options: ReadableMap, promise: Promise) {
+        val videoTrackId = if (options.hasKey("videoTrackId") && !options.isNull("videoTrackId")) {
+            options.getString("videoTrackId")
+        } else {
+            null
+        }
+        val maxDurationMs = if (options.hasKey("maxDurationMs") && !options.isNull("maxDurationMs")) {
+            options.getInt("maxDurationMs").toLong()
+        } else {
+            DEFAULT_RECORDING_DURATION_MS
+        }
+        val targetWidth = if (options.hasKey("targetWidth") && !options.isNull("targetWidth")) {
+            options.getInt("targetWidth")
+        } else {
+            0
+        }
+        val targetHeight = if (options.hasKey("targetHeight") && !options.isNull("targetHeight")) {
+            options.getInt("targetHeight")
+        } else {
+            0
+        }
+
+        val webRTCModule = reactApplicationContext.getNativeModule(WebRTCModule::class.java)
+        if (webRTCModule == null) {
+            promise.reject(RECORDING_ERROR_CODE, "WebRTCModule not available")
+            return
+        }
+
+        TracksRecorderManager.shared.startRecording(
+            context = reactApplicationContext,
+            webRTCModule = webRTCModule,
+            videoTrackId = videoTrackId,
+            maxDurationMs = maxDurationMs,
+            targetWidth = targetWidth,
+            targetHeight = targetHeight,
+        ) { file, error ->
+            if (error != null) {
+                promise.reject(RECORDING_ERROR_CODE, error.message ?: "recording failed", error)
+            } else {
+                promise.resolve(file?.let { "file://${it.absolutePath}" })
+            }
+        }
+    }
+
+    @ReactMethod
+    fun stopTrackRecording(promise: Promise) {
+        TracksRecorderManager.shared.stopRecording {
+            promise.resolve(null)
+        }
+    }
+
+    @ReactMethod
+    fun clearStreamRecordings(promise: Promise) {
+        TracksRecorderManager.shared.clearRecordingsDirectory(reactApplicationContext) { error ->
+            if (error != null) {
+                promise.reject(RECORDING_CLEAR_ERROR_CODE, error.message ?: "clear failed", error)
+            } else {
+                promise.resolve(null)
+            }
+        }
+    }
+
+    @ReactMethod
+    fun getStreamRecordings(promise: Promise) {
+        val files: List<File> = TracksRecorderManager.shared.listRecordings(reactApplicationContext)
+        val arr = Arguments.createArray()
+        for (f in files) {
+            arr.pushString("file://${f.absolutePath}")
+        }
+        promise.resolve(arr)
+    }
+
     companion object {
         private const val NAME = "StreamVideoReactNative"
         private const val SAMPLE_RATE = 22050
+        private const val DEFAULT_RECORDING_DURATION_MS = 5000L
+        private const val RECORDING_ERROR_CODE = "recording_error"
+        private const val RECORDING_CLEAR_ERROR_CODE = "clear_error"
     }
 }

package/android/src/main/java/com/streamvideo/reactnative/recorder/AudioPipeline.kt

@@ -0,0 +1,436 @@
+package com.streamvideo.reactnative.recorder
+
+import android.media.MediaCodec
+import android.media.MediaCodecInfo
+import android.media.MediaFormat
+import android.media.MediaMuxer
+import android.util.Log
+import com.oney.WebRTCModule.WebRTCModule
+import com.oney.WebRTCModule.WebRTCModuleOptions
+import java.nio.ByteBuffer
+
+/**
+ * Audio pipeline owned by [TracksRecorderManager]. Encapsulates the AAC
+ * audio path:
+ *  - the [RecorderPlaybackSamplesSink] registered with
+ *    `WebRTCModuleOptions.addPlaybackSamplesObserver` (the fork's
+ *    multi-tenant fan-out over `JavaAudioDeviceModule.PlaybackSamplesReadyCallback`),
+ *  - the [MediaCodec] AAC encoder + its configuration,
+ *  - reflection-based speaker mute via `WebRtcAudioTrack.audioTrack.setVolume(0)`
+ *    so the SFU loopback echo doesn't feed back into the mic,
+ *  - encoder output drain (format-locked addTrack, sample append, EOS),
+ *  - per-recording counters surfaced for the end-of-recording log line.
+ *
+ * All state mutation runs on the host's handler thread.
+ */
+internal class AudioPipeline(
+    private val host: PipelineHost,
+    private val webRTCModule: WebRTCModule,
+) {
+    private companion object {
+        const val TAG = "TracksRecorder.Audio"
+        const val MIME = "audio/mp4a-latm"
+        const val BIT_RATE = 64_000
+    }
+
+    private val handler = host.handler
+
+    private var encoder: MediaCodec? = null
+    private var sink: RecorderPlaybackSamplesSink? = null
+
+    private var trackIndex: Int = -1
+    private var formatLocked = false
+
+    private var sampleRate: Int = 0
+    private var channelCount: Int = 0
+    private var bitsPerSample: Int = 0
+
+    /**
+     * Reference to the system [android.media.AudioTrack] held while
+     * playback is muted for recording, so cleanup can restore the
+     * original volume. `@Volatile` because [restoreLoopbackPlaybackMute]
+     * is invoked from both the recorder handler (manual stop) and the
+     * main looper (auto-stop runnable).
+     */
+    @Volatile
+    private var mutedSystemAudioTrack: android.media.AudioTrack? = null
+
+    @Volatile
+    private var muteUnavailable: Boolean = false
+
+    //diagnostic counters
+    private var buffersReceived = 0
+    private var samplesAppended = 0
+    private var buffersDropped = 0
+    private var firstSamplePtsUs: Long = -1
+    private var lastSamplePtsUs: Long = -1
+
+    /**
+     * Register the playback-samples observer with the fork's fan-out and
+     * mute the system playback track. Future audio buffers post to the
+     * handler.
+     */
+    fun start() {
+        val s = RecorderPlaybackSamplesSink { data, sr, ch, frames ->
+            onAudioBufferDelivered(data, sr, ch, frames)
+        }
+        sink = s
+        WebRTCModuleOptions.getInstance().addPlaybackSamplesObserver(s)
+
+        // Always mute the speaker so the loopback echo doesn't feed
+        // back into the mic. First attempt may fail due to a race condition
+        // where the system AudioTrack hasn't been created yet.
+        ensureLoopbackPlaybackMuted()
+    }
+
+    /**
+     * Detach the sink and restore speaker volume synchronously from any
+     * thread. Both operations are off-handler so they take effect
+     * immediately — routing them through the handler would queue them
+     * behind the encoder backlog and keep accepting samples / leave the
+     * speaker muted past the user-facing stop point.
+     */
+    fun detachSink() {
+        try {
+            sink?.let {
+                WebRTCModuleOptions.getInstance().removePlaybackSamplesObserver(it)
+            }
+        } catch (t: Throwable) {
+            Log.w(TAG, "removePlaybackSamplesObserver threw", t)
+        }
+        sink = null
+        restoreLoopbackPlaybackMute()
+    }
+
+    /** On-handler. Submit EOS to the encoder. Returns `true` if queued. */
+    fun signalEndOfStream(muxerInstance: MediaMuxer): Boolean {
+        val enc = encoder ?: return false
+        return signalEoS(enc, muxerInstance)
+    }
+
+    /** On-handler. Drain until BUFFER_FLAG_END_OF_STREAM or budget expires. */
+    fun drainAfterEoS(muxerInstance: MediaMuxer) {
+        val enc = encoder ?: return
+        drain(enc, muxerInstance, endOfStream = true)
+    }
+
+    /** On-handler. Stop + release the encoder. */
+    fun stopAndRelease() {
+        try {
+            encoder?.stop()
+        } catch (t: Throwable) {
+            Log.w(TAG, "encoder.stop() threw", t)
+        }
+        try {
+            encoder?.release()
+        } catch (t: Throwable) {
+            Log.w(TAG, "encoder.release() threw", t)
+        }
+        encoder = null
+    }
+
+    fun logSummary() {
+        val durationMs = if (firstSamplePtsUs >= 0 && lastSamplePtsUs >= firstSamplePtsUs) {
+            (lastSamplePtsUs - firstSamplePtsUs) / 1000
+        } else {
+            -1
+        }
+        Log.i(
+            TAG,
+            "summary received=$buffersReceived appended=$samplesAppended dropped=$buffersDropped firstPtsUs=$firstSamplePtsUs lastPtsUs=$lastSamplePtsUs durationMs=$durationMs",
+        )
+    }
+
+    /**
+     * Idempotent: try to mute the system playback track by setting its
+     * volume to 0. Returns `true` if mute is now in place (either it
+     * was just applied, or it was already applied).
+     *
+     * `WebRtcAudioTrack.audioTrack` is `null` until WebRTC calls
+     * `startPlayout()`, which happens **asynchronously after** the
+     * loopback `MediaStreamTrack` is enabled. The retry path
+     * lives in [handleAudioBufferOnHandler], which only runs after
+     * `startPlayout()` has created the system AudioTrack (that's the
+     * precondition for the JADM playback callback firing at all).
+     *
+     * Reflection is required because `WebRtcAudioTrack` is package-
+     * private and its `audioTrack` field private. Best-effort — if
+     * reflection fails because the class layout changed, recording
+     * still works; the user just hears the echo.
+     */
+    private fun ensureLoopbackPlaybackMuted(): Boolean {
+        if (mutedSystemAudioTrack != null) return true
+        if (muteUnavailable) return false
+
+        try {
+            val adm = webRTCModule.audioDeviceModule ?: return false
+            val audioOutputField = adm.javaClass.getField("audioOutput")
+            val audioOutput = audioOutputField.get(adm) ?: return false
+            val audioTrackField = audioOutput.javaClass.getDeclaredField("audioTrack")
+            audioTrackField.isAccessible = true
+            val systemAudioTrack = audioTrackField.get(audioOutput) as? android.media.AudioTrack
+            if (systemAudioTrack == null) {
+                // Expected on initial call from start(); WebRTC's startPlayout hasn't created the AudioTrack yet. 
+                return false
+            }
+            systemAudioTrack.setVolume(0f)
+            mutedSystemAudioTrack = systemAudioTrack
+            return true
+        } catch (t: Throwable) {
+            muteUnavailable = true
+            Log.w(TAG, "speaker mute failed — recording will still work but speaker will play loopback", t)
+            return false
+        }
+    }
+
+    private fun restoreLoopbackPlaybackMute() {
+        muteUnavailable = false
+        val track = mutedSystemAudioTrack ?: return
+        try {
+            track.setVolume(1f)
+        } catch (t: Throwable) {
+            Log.w(TAG, "restoreLoopbackPlaybackMute failed", t)
+        }
+        mutedSystemAudioTrack = null
+    }
+
+    private fun onAudioBufferDelivered(
+        data: ByteBuffer,
+        sampleRate: Int,
+        channels: Int,
+        frames: Int,
+    ) {
+        // System.nanoTime() shares the monotonic source WebRTC uses
+        // for video frame timestamps, so audio and video PTS line up
+        // against the same origin.
+        val arrivalNs = System.nanoTime()
+        handler.post {
+            try {
+                handleAudioBufferOnHandler(data, sampleRate, channels, frames, arrivalNs)
+            } catch (t: Throwable) {
+                Log.e(TAG, "handleAudioBufferOnHandler threw", t)
+            }
+        }
+    }
+
+    private fun handleAudioBufferOnHandler(
+        data: ByteBuffer,
+        sr: Int,
+        ch: Int,
+        frames: Int,
+        arrivalNs: Long,
+    ) {
+        // Retry the speaker mute on every sample arrival until it
+        // sticks.The very first delivery is the earliest moment we can be sure
+        // WebRTC's `startPlayout()` has created the system AudioTrack
+        // — the JADM playback callback wouldn't fire otherwise — so
+        // this is the tightest mute window we can achieve from native.
+        ensureLoopbackPlaybackMuted()
+
+        val muxerInstance = host.muxer ?: return
+
+        // JADM playback always uses 16-bit signed PCM
+        // (`WebRtcAudioTrack.BITS_PER_SAMPLE`).
+        val bps = 16
+        val enc = encoder ?: createEncoder(sr, ch, bps) ?: return
+
+        // MediaCodec can't re-negotiate format mid-stream; drop
+        // mismatched buffers. Rare in practice — WebRTC keeps PCM
+        // format constant per render session.
+        if (sr != sampleRate || ch != channelCount) {
+            buffersDropped++
+            if (buffersDropped <= 5 || buffersDropped % 30 == 0) {
+                Log.w(
+                    TAG,
+                    "dropping audio buffer sr=$sr ch=$ch (configured sr=$sampleRate ch=$channelCount dropped=$buffersDropped)",
+                )
+            }
+            return
+        }
+
+        // First buffer of any kind establishes the shared origin so
+        // video and audio PTS share zero.
+        val originNs = host.seedOriginNs(arrivalNs)
+
+        // Wall-clock PTS bounds the file's reported duration to the
+        // actual recording window. A sample-counter approach would
+        // over-count if JADM delivered a burst (e.g. playback-startup
+        // buffer flush), making the MP4 longer than the recording
+        // window. Jitter in delivery cadence shows up as a few-ms
+        // variance in sample spacing — below audible threshold.
+        val ptsUs = ((arrivalNs - originNs) / 1000L).coerceAtLeast(0L)
+
+        val byteCount = frames * ch * (bps / 8)
+        val inputIndex = try {
+            enc.dequeueInputBuffer(EncoderConstants.DEQUEUE_TIMEOUT_US)
+        } catch (t: Throwable) {
+            Log.e(TAG, "audio dequeueInputBuffer threw", t)
+            buffersDropped++
+            return
+        }
+        if (inputIndex < 0) {
+            buffersDropped++
+            return
+        }
+        val input = enc.getInputBuffer(inputIndex)
+        if (input == null) {
+            buffersDropped++
+            enc.queueInputBuffer(inputIndex, 0, 0, ptsUs, 0)
+            return
+        }
+        input.clear()
+        if (input.capacity() < byteCount) {
+            Log.w(
+                TAG,
+                "audio input buffer too small (${input.capacity()} < $byteCount) — dropping",
+            )
+            enc.queueInputBuffer(inputIndex, 0, 0, ptsUs, 0)
+            buffersDropped++
+            return
+        }
+        input.put(data)
+        enc.queueInputBuffer(inputIndex, 0, byteCount, ptsUs, 0)
+        buffersReceived++
+
+        drain(enc, muxerInstance, endOfStream = false)
+    }
+
+    private fun createEncoder(sr: Int, ch: Int, bps: Int): MediaCodec? {
+        val format = MediaFormat.createAudioFormat(MIME, sr, ch).apply {
+            setInteger(
+                MediaFormat.KEY_AAC_PROFILE,
+                MediaCodecInfo.CodecProfileLevel.AACObjectLC,
+            )
+            setInteger(MediaFormat.KEY_BIT_RATE, BIT_RATE)
+            // 4× the typical 10 ms PCM buffer — generous so the input
+            // slot is never tight.
+            val pcmBytesPerBuffer = sr * ch * (bps / 8) / 100
+            setInteger(MediaFormat.KEY_MAX_INPUT_SIZE, pcmBytesPerBuffer * 4)
+        }
+        return try {
+            val enc = MediaCodec.createEncoderByType(MIME)
+            enc.configure(format, null, null, MediaCodec.CONFIGURE_FLAG_ENCODE)
+            enc.start()
+            encoder = enc
+            sampleRate = sr
+            channelCount = ch
+            bitsPerSample = bps
+            // INVARIANT: see the symmetric comment in [VideoPipeline.createEncoder].
+            // The host's pending-pipeline counter must remain positive for this
+            // pipeline until `muxer.addTrack(audio)` has been called or the
+            // muxer would start without the audio track.
+            enc
+        } catch (t: Throwable) {
+            Log.e(TAG, "failed to create AAC encoder", t)
+            host.onFatalError(t)
+            null
+        }
+    }
+
+    /**
+     * Queues a zero-length input buffer with `BUFFER_FLAG_END_OF_STREAM`.
+     * Drains output between input attempts so the encoder's input
+     * slots can free up — a polling-only loop deadlocks when output
+     * queues are full. Returns `true` only if the marker was
+     * successfully queued; the caller skips the EOS drain otherwise so
+     * the handler doesn't hang waiting for a marker that won't arrive.
+     */
+    private fun signalEoS(enc: MediaCodec, muxerInstance: MediaMuxer): Boolean {
+        repeat(EncoderConstants.EOS_INPUT_RETRIES) {
+            val idx = try {
+                enc.dequeueInputBuffer(EncoderConstants.DEQUEUE_TIMEOUT_US)
+            } catch (t: Throwable) {
+                Log.w(TAG, "dequeueInputBuffer during EOS threw", t)
+                return false
+            }
+            if (idx >= 0) {
+                enc.queueInputBuffer(
+                    idx, 0, 0, 0L,
+                    MediaCodec.BUFFER_FLAG_END_OF_STREAM,
+                )
+                return true
+            }
+            // Keep output flowing so input slots can be released.
+            try {
+                drain(enc, muxerInstance, endOfStream = false)
+            } catch (t: Throwable) {
+                Log.w(TAG, "drainEncoder during EOS retry threw", t)
+            }
+        }
+        Log.w(TAG, "could not queue EOS — skipping EOS drain to avoid hang")
+        return false
+    }
+
+    private fun drain(
+        enc: MediaCodec,
+        muxerInstance: MediaMuxer,
+        endOfStream: Boolean,
+    ) {
+        val info = MediaCodec.BufferInfo()
+        val timeoutUs =
+            if (endOfStream) EncoderConstants.DEQUEUE_TIMEOUT_US_EOS else 0L
+        val deadlineMs = System.currentTimeMillis() +
+            if (endOfStream) EncoderConstants.EOS_DRAIN_BUDGET_MS else Long.MAX_VALUE
+
+        while (true) {
+            val outIndex = try {
+                enc.dequeueOutputBuffer(info, timeoutUs)
+            } catch (t: Throwable) {
+                Log.e(TAG, "dequeueOutputBuffer threw", t)
+                return
+            }
+
+            when {
+                outIndex == MediaCodec.INFO_TRY_AGAIN_LATER -> {
+                    if (!endOfStream) return
+                    if (System.currentTimeMillis() >= deadlineMs) {
+                        Log.w(
+                            TAG,
+                            "EOS drain timed out without seeing BUFFER_FLAG_END_OF_STREAM — bailing out",
+                        )
+                        return
+                    }
+                    // During EOS keep polling until the marker arrives.
+                }
+
+                outIndex == MediaCodec.INFO_OUTPUT_FORMAT_CHANGED -> {
+                    if (formatLocked) {
+                        Log.w(TAG, "output format changed twice — ignoring")
+                        continue
+                    }
+                    val newIndex = muxerInstance.addTrack(enc.outputFormat)
+                    trackIndex = newIndex
+                    formatLocked = true
+                    host.onTrackAdded()
+                }
+
+                outIndex >= 0 -> {
+                    val out = enc.getOutputBuffer(outIndex)
+                    if (out != null && info.size > 0 && host.muxerStarted &&
+                        trackIndex >= 0 &&
+                        info.flags and MediaCodec.BUFFER_FLAG_CODEC_CONFIG == 0
+                    ) {
+                        out.position(info.offset)
+                        out.limit(info.offset + info.size)
+                        try {
+                            muxerInstance.writeSampleData(trackIndex, out, info)
+                            samplesAppended++
+                            if (firstSamplePtsUs < 0 || info.presentationTimeUs < firstSamplePtsUs) {
+                                firstSamplePtsUs = info.presentationTimeUs
+                            }
+                            if (info.presentationTimeUs > lastSamplePtsUs) {
+                                lastSamplePtsUs = info.presentationTimeUs
+                            }
+                        } catch (t: Throwable) {
+                            Log.e(TAG, "writeSampleData failed", t)
+                        }
+                    }
+                    enc.releaseOutputBuffer(outIndex, false)
+                    if (info.flags and MediaCodec.BUFFER_FLAG_END_OF_STREAM != 0) return
+                }
+            }
+
+            if (!endOfStream && outIndex < 0) return
+        }
+    }
+}

package/android/src/main/java/com/streamvideo/reactnative/recorder/EncoderConstants.kt

@@ -0,0 +1,17 @@
+package com.streamvideo.reactnative.recorder
+
+internal object EncoderConstants {
+    /** Non-blocking dequeue timeout used during normal frame/buffer feed. */
+    const val DEQUEUE_TIMEOUT_US: Long = 10_000L
+
+    /** Slower poll used while waiting for the EOS marker to surface. */
+    const val DEQUEUE_TIMEOUT_US_EOS: Long = 100_000L
+
+    /** Max attempts to queue an EOS input buffer before giving up. */
+    const val EOS_INPUT_RETRIES: Int = 50
+
+    /** Wall-clock cap on the EOS-mode drain so a missed EOS can't hang the handler. */
+    const val EOS_DRAIN_BUDGET_MS: Long = 2_000L
+}
+
+class RecordingError(message: String) : RuntimeException(message)

package/android/src/main/java/com/streamvideo/reactnative/recorder/PipelineHost.kt

@@ -0,0 +1,36 @@
+package com.streamvideo.reactnative.recorder
+
+import android.media.MediaMuxer
+import android.os.Handler
+
+/**
+ * Internal coordination contract between [TracksRecorderManager] and audio/video pipelines.
+ * The pipelines own their encoder + sink + drain logic; the host owns lifecycle, the muxer,
+ * the muxer-start gate, the shared time origin, and the terminal-completion barrier.
+ *
+ * Every method on this interface is called from the host's handler thread
+ * — pipelines must post to [handler] before calling back into the host.
+ */
+internal interface PipelineHost {
+    /** The recorder's serial handler thread. */
+    val handler: Handler
+
+    val muxer: MediaMuxer?
+
+    val muxerStarted: Boolean
+
+    /**
+     * 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.
+     */
+    fun seedOriginNs(timestampNs: Long): Long
+
+    /**
+     * Pipeline has added a track to the muxer. The host 
+     * muxer once all expected pipelines have reported their track.
+     */
+    fun onTrackAdded()
+
+    fun onFatalError(error: Throwable)
+}

package/android/src/main/java/com/streamvideo/reactnative/recorder/RecorderPlaybackSamplesSink.kt

@@ -0,0 +1,60 @@
+package com.streamvideo.reactnative.recorder
+
+import android.util.Log
+import org.webrtc.audio.JavaAudioDeviceModule
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+
+/**
+ * Render-side playback sink for [TracksRecorderManager]. Registered
+ * via `WebRTCModuleOptions.addPlaybackSamplesObserver` for the
+ * duration of a recording. Fires on the JADM audio thread, downstream
+ * of any audio processing factory — works regardless of whether a
+ * custom APM, noise cancellation, or the default is configured.
+ *
+ * `AudioSamples` carries 16-bit signed little-endian PCM in `data`.
+ * Wrapped in a fresh direct ByteBuffer so the manager can write it
+ * straight into a MediaCodec input slot without a second copy.
+ */
+internal class RecorderPlaybackSamplesSink(
+    private val handler: (
+        data: ByteBuffer,
+        sampleRate: Int,
+        channels: Int,
+        frames: Int,
+    ) -> Unit,
+) : JavaAudioDeviceModule.PlaybackSamplesReadyCallback {
+
+    companion object {
+        private const val TAG = "TracksRecorder.PbSink"
+    }
+
+    @Volatile
+    private var _callCount: Int = 0
+    val callCount: Int get() = _callCount
+
+    override fun onWebRtcAudioTrackSamplesReady(samples: JavaAudioDeviceModule.AudioSamples) {
+        _callCount++
+
+        val data = samples.data
+        val sampleRate = samples.sampleRate
+        val channels = samples.channelCount
+        val byteCount = data.size
+        if (byteCount <= 0 || sampleRate <= 0 || channels <= 0) return
+
+        // 16-bit PCM (`WebRtcAudioTrack.BITS_PER_SAMPLE`); `AudioSamples`
+        // doesn't expose a direct frames field.
+        val frames = byteCount / (channels * 2)
+
+        val copy = ByteBuffer.allocateDirect(byteCount).order(ByteOrder.LITTLE_ENDIAN)
+        copy.put(data)
+        copy.position(0)
+        copy.limit(byteCount)
+
+        try {
+            handler(copy, sampleRate, channels, frames)
+        } catch (t: Throwable) {
+            Log.e(TAG, "playback samples handler threw", t)
+        }
+    }
+}

package/android/src/main/java/com/streamvideo/reactnative/recorder/RecorderVideoSink.kt

@@ -0,0 +1,31 @@
+package com.streamvideo.reactnative.recorder
+
+import org.webrtc.VideoFrame
+import org.webrtc.VideoSink
+
+/**
+ * Per-track [VideoSink] for [TracksRecorderManager]. Stays dumb —
+ * retains each incoming frame and forwards it; the manager handles
+ * queue hops, I420 → NV12 conversion, and the encoder feed.
+ *
+ * `onFrame` is invoked from a WebRTC delivery thread. **Never** call
+ * `removeSink` from inside `onFrame` — Android WebRTC has a known
+ * deadlock there. The manager removes from its handler thread.
+ */
+internal class RecorderVideoSink(
+    private val handler: (VideoFrame) -> Unit,
+) : VideoSink {
+
+    override fun onFrame(frame: VideoFrame) {
+        // Retain so the buffer outlives this delivery-thread call.
+        // The manager releases after the encoder consumes it.
+        frame.retain()
+        try {
+            handler.invoke(frame)
+        } catch (t: Throwable) {
+            // Balance the retain when the manager rejects the frame.
+            frame.release()
+            throw t
+        }
+    }
+}