tirtc-react-native 2.5.0-alpha.1 → 2.5.0

package/README.md

@@ -6,11 +6,11 @@
 npm install tirtc-react-native
 ```
 
-The package ships ESM JavaScript, TypeScript declarations, Codegen specs, Android native wrapper code and iOS native wrapper code. RTC and CloudStorage use the same native Runtime delivery but keep separate initialization and resource lifecycles. The package requires React Native `>=0.80.0`, Android `com.tange.ai:tirtc:2.5.0-alpha.1`, and iOS `TiRTC` `2.5.0-alpha.1` with iOS minimum `15.1`.
+The package ships ESM JavaScript, TypeScript declarations, Codegen specs, Android native wrapper code and iOS native wrapper code. RTC and CloudStorage use the same native Runtime delivery but keep separate initialization and resource lifecycles. The package requires React Native `>=0.80.0`, Android `com.tange.ai:tirtc:2.5.0`, and iOS `TiRTC` `2.5.0` with iOS minimum `15.1`.
 
 The iOS package supports arm64 devices and Apple Silicon iOS Simulator. Simulator validation covers build, launch, connection, downlink audio, and downlink video; capture and iOS behavioral qualification remain real-device gates.
 
-Version `2.5.0-alpha.1` is the React Native prerelease aligned with the TiRTC 2.5.0-alpha.1 Android and Darwin SDKs.
+Version `2.5.0` is the stable React Native release aligned with the TiRTC 2.5.0 Android and Darwin SDKs.
 
 ## Imports
 
@@ -37,7 +37,7 @@ The root export is the public API. Deep imports are not supported.
 
 String values are exported as stable `as const` objects and matching TypeScript union types:
 
-`TiRtcOutputBufferStrategy`, `TiRtcConnState`, `TiRtcInputState`, `TiRtcAudioCodec`, `TiRtcAudioSampleRate`, `TiRtcAudioChannelCount`, `TiRtcAudioAecMode`, `TiRtcAudioAgcLevel`, `TiRtcAudioAnsLevel`, `TiRtcVideoCodec`, `TiRtcVideoEncoderCodec`, `TiRtcVideoFrameRate`, `TiRtcCameraFacing`, `TiRtcVideoDecoderPreference`, `TiRtcVideoDecoderBackend`, `TiRtcVideoBitstreamFormat`, `TiRtcAudioOutputState`, `TiRtcVideoOutputState`.
+`TiRtcOutputBufferStrategy`, `TiRtcConnState`, `TiRtcInputState`, `TiRtcAudioCodec`, `TiRtcAudioSampleRate`, `TiRtcAudioChannelCount`, `TiRtcAudioAecMode`, `TiRtcAudioAgcLevel`, `TiRtcAudioAnsLevel`, `TiRtcVideoCodec`, `TiRtcVideoFrameRate`, `TiRtcCameraFacing`, `TiRtcVideoDecoderPreference`, `TiRtcVideoDecoderBackend`, `TiRtcVideoBitstreamFormat`, `TiRtcAudioOutputState`, `TiRtcVideoOutputState`.
 
 Use the exported values instead of hard-coded strings in app code.
 
@@ -95,7 +95,7 @@ import {TiRtcAudioCodec, TiRtcAudioInput} from 'tirtc-react-native';
 const audioInput = new TiRtcAudioInput();
 
 await audioInput.setOptions({
-  codec: TiRtcAudioCodec.g711a,
+  media: 2,
 });
 await audioInput.attach(conn, talkbackStreamId);
 await audioInput.start();
@@ -139,7 +139,7 @@ Constructors create native owner identities, so outputs and inputs can attach to
 
 ## Release
 
-Version `2.5.0-alpha.1` is the current React Native prerelease for TiRTC and Ti Cloud Storage. It supports React Native New Architecture apps on Android and iOS and pins Android `com.tange.ai:tirtc:2.5.0-alpha.1` and iOS `TiRTC` `2.5.0-alpha.1`.
+Version `2.5.0` is the current stable React Native release for TiRTC and Ti Cloud Storage. It supports React Native New Architecture apps on Android and iOS and pins Android `com.tange.ai:tirtc:2.5.0` and iOS `TiRTC` `2.5.0`.
 
 ## License
 
@@ -155,12 +155,45 @@ npm run build
 npm run codegen:check
 ```
 
+On macOS, `python3 test/cloud_storage_callbacks_test.py` compiles and executes the iOS Foundation callback queue to check acknowledgement, bounded delivery, and invalidation. Android exercises its native callback queue in the Cloud Storage integration instrumentation. These checks supplement the owner product lanes defined in `react-native-test`.
+
 The external application sample is published under `react-native/` in
 `tirtc-api-samples`. The owner-local projection and recovery entry is:
 
 ```sh
-./scripts/publish_api_samples.sh --version 2.5.0-alpha.1
+./scripts/publish_api_samples.sh --version 2.5.0
 ```
 
 Use `--no-push` for a complete local projection/build rehearsal without writing
 the public repository.
+
+## Microphone media configuration
+
+`TiRtcAudioInputOptions.media` accepts the integer audio media number returned by
+Nano device capabilities:
+
+| media | Audio format |
+| --- | --- |
+| 1 | PCM |
+| 2 | G711A (A-law) |
+| 3 | AAC |
+| 4 | Opus |
+| 5 | AMR (8 kHz mono) |
+
+```ts
+const code = await input.setOptions({media: 2});
+```
+
+Omitting `media` or setting it to `-1` uses the deprecated `codec` field, whose
+default remains G711A. Existing AAC calls keep selecting AAC. An explicit supported
+`media` takes precedence over `codec`; any other value returns the existing
+parameter error and leaves the accepted configuration intact. Stop capture before
+applying new options, and follow the input's existing detach requirements.
+
+The deprecated audio codec values keep their original meanings. Codec fields on
+received frames and metrics retain their output numbering; they are not Nano
+input media numbers.
+
+## Targeted input validation
+
+Prepare the current native dependency, then run `python3 react-native/tirtc/example/tool/integration.py --platform android --case rn_input_media_all` from the repository root. For iOS, select `--platform ios-arm64-simulator --prepared-state <ios-consumer-state>`. Simulator evidence distinguishes decoded constant audio and an unavailable camera from real capture signal verification. Individual cases are `rn_input_media_g711a_h264`, `rn_input_media_aac_mjpeg` and `rn_input_media_legacy_aac_h264`. The test-owned React fixture consumes the public facade; its peer records and decodes the encoded microphone/camera payload. Full integration requirements remain separate.

package/TiRtcReactNative.podspec

@@ -13,7 +13,7 @@ Pod::Spec.new do |s|
   s.source = { :git => 'https://gitlab.tange-ai.com/tirtc-nexus/tirtc.git', :tag => s.version.to_s }
   s.source_files = 'ios/**/*.{h,m,mm,swift}'
   s.dependency 'React-Core'
-  s.dependency 'TiRTC', '2.5.0-alpha.1'
+  s.dependency 'TiRTC', '2.5.0'
 
   if respond_to?(:install_modules_dependencies, true)
     install_modules_dependencies(s)

package/android/build.gradle

@@ -29,7 +29,7 @@ repositories {
 
 dependencies {
   implementation "com.facebook.react:react-android"
-  implementation "com.tange.ai:tirtc:${safeExtGet("tirtcAndroidVersion", "2.5.0-alpha.1")}"
+  implementation "com.tange.ai:tirtc:${safeExtGet("tirtcAndroidVersion", "2.5.0")}"
 }
 
 def safeExtGet(prop, fallback) {

package/android/src/main/java/com/tange/ai/tirtc/reactnative/TiRtcModule.kt

@@ -25,9 +25,15 @@ import com.tange.ai.tirtc.TiRtcRecordingFile
 import com.tange.ai.tirtc.TiRtcSnapshotFile
 import com.tange.ai.tirtc.TiRtcVideoInput
 import com.tange.ai.tirtc.TiRtcVideoOutput
+import com.tange.ai.tirtc.TiRtcRawDumpOptions
+import com.tange.ai.tirtc.TiCloudStorageRawDumpOptions
 import com.tange.ai.tirtc.TiCloudStorage
+import com.tange.ai.tirtc.TiCloudStorageCallbackThread
+import com.tange.ai.tirtc.TiCloudStorageErrorCode
+import com.facebook.react.bridge.Arguments
 import com.tange.ai.tirtc.TiCloudStorageAudioOutput
 import com.tange.ai.tirtc.TiCloudStorageExportRequest
+import com.tange.ai.tirtc.TiCloudStorageExportResult
 import com.tange.ai.tirtc.TiCloudStorageRecordingFile
 import com.tange.ai.tirtc.TiCloudStorageRecordingResult
 import com.tange.ai.tirtc.TiCloudStorageReplaySpeed
@@ -48,14 +54,28 @@ class TiRtcModule(
 ) : NativeTiRtcSpec(reactContext) {
     private val registry = TiRtcReactNativeRegistry
     private val invalidated = AtomicBoolean(false)
-    private val events =
-        TiRtcReactNativeEventSink(registry) { event ->
-            if (!invalidated.get()) {
-                reactContext.runOnJSQueueThread {
-                    if (!invalidated.get()) emitOnTiRtcEvent(event)
-                }
-            }
+    private val cloudStorageCallbacks = TiRtcReactNativeCloudStorageCallbacks {
+        emitEvent(Arguments.createMap().apply {
+            putString("type", "tiCloudStorageCallbackReady")
+            putInt("objectId", 0)
+            putInt("generation", 0)
+        })
+    }
+    private val events = TiRtcReactNativeEventSink(registry) { event ->
+        val type = event.getString("type") ?: ""
+        if (type.startsWith("tiCloudStorageReplay") || type.startsWith("tiCloudStorageExport")) {
+            cloudStorageCallbacks.deliver(event)
+        } else {
+            emitEvent(event)
         }
+    }
+
+    private fun emitEvent(event: WritableMap) {
+        if (!invalidated.get()) reactContext.runOnJSQueueThread {
+            if (!invalidated.get()) emitOnTiRtcEvent(event)
+        }
+    }
+
     private val eventBinder = TiRtcReactNativeEventBinder(events)
     private val nextMediaFileId = AtomicInteger(1)
     private val mediaFiles = ConcurrentHashMap<Int, Any>()
@@ -69,6 +89,7 @@ class TiRtcModule(
 
     override fun invalidate() {
         if (!invalidated.compareAndSet(false, true)) return
+        cloudStorageCallbacks.close()
         val objects = registry.drain(events)
         val files = mediaFiles.values.toList()
         mediaFiles.clear()
@@ -182,7 +203,7 @@ class TiRtcModule(
             ?: return createResult(TiRtcReactNativeErrors.OBJECT_RELEASED, 0, 0)
         return registerReactNativeObject(
             registry,
-            factory = { cloudStorage.createReplay() },
+            factory = { cloudStorage.createReplay(TiCloudStorageCallbackThread.BACKGROUND) },
             onRegistered = { entry, value -> eventBinder.wireCloudStorageReplay(entry.id, value as com.tange.ai.tirtc.TiCloudStorageReplay) },
         )
     }
@@ -196,7 +217,10 @@ class TiRtcModule(
     ): WritableMap {
         val cloudStorage = registry.cloudStorage(id.toInt())
             ?: return recordingStartResult(TiRtcReactNativeErrors.OBJECT_RELEASED, null)
-        val bridge = CloudStorageExportBridge(::resolveCloudStorageRecording)
+        val bridge = CloudStorageExportBridge(::resolveCloudStorageExport, events)
+        val entry = registry.add(bridge)
+        bridge.objectId = entry.id
+        bridge.onDrained = { registry.release(entry.id) }
         val started = cloudStorage.exportRecording(
             TiCloudStorageExportRequest(
                 startTimeMs.toLong(),
@@ -205,17 +229,34 @@ class TiRtcModule(
                 audioChannelId?.toInt(),
             ),
             null,
+            { progress -> bridge.progress(progress) },
+            { gap -> bridge.recordingGap(gap) },
+            TiCloudStorageCallbackThread.BACKGROUND,
         ) { result -> bridge.complete(result) }
-        val task = started.task ?: return recordingStartResult(started.code, null)
-        bridge.task = task
-        val entry = registry.add(bridge)
-        bridge.onDrained = { registry.release(entry.id) }
-        return recordingStartResult(started.code, entry.id)
+        val task = started.task
+        if (task == null) {
+            bridge.rejectStart()
+            registry.release(entry.id)
+            return recordingStartResult(started.code, null)
+        }
+        bridge.bindTask(task)
+        return recordingStartResult(started.code, entry.id, entry.generation)
     }
 
+    override fun tiCloudStorageTakeCallback(): WritableMap? = cloudStorageCallbacks.take()
+
+    override fun tiCloudStorageAcknowledgeCallback(deliveryId: Double): Double =
+        cloudStorageCallbacks.acknowledge(deliveryId)
+
     override fun tiCloudStorageExportProgress(id: Double): Double =
         registry.tiCloudStorageExportTask(id.toInt())?.task?.progress ?: 0.0
 
+    override fun tiCloudStorageExportProgressDetail(id: Double): WritableMap =
+        tiCloudStorageExportProgress(
+            registry.tiCloudStorageExportTask(id.toInt())?.task?.progressDetail
+                ?: com.tange.ai.tirtc.TiCloudStorageExportProgress(0.0, 0),
+        )
+
     @ReactMethod
     override fun tiCloudStorageExportResult(id: Double, promise: Promise) {
         registry.tiCloudStorageExportTask(id.toInt())?.await(promise)
@@ -225,6 +266,9 @@ class TiRtcModule(
     override fun tiCloudStorageExportStop(id: Double): Double =
         registry.tiCloudStorageExportTask(id.toInt())?.task?.stop().normalized()
 
+    override fun tiCloudStorageExportCancel(id: Double): Double =
+        registry.tiCloudStorageExportTask(id.toInt())?.task?.cancel().normalized()
+
     override fun tiCloudStorageDispose(id: Double): Double {
         val objectId = id.toInt()
         val code = registry.cloudStorage(objectId)?.dispose().normalized()
@@ -290,6 +334,30 @@ class TiRtcModule(
         return recordingStartResult(result.code, entry?.id)
     }
 
+    @ReactMethod
+    override fun tiCloudStorageReplayStartRawDump(
+        id: Double,
+        audioChannelIds: ReadableArray,
+        videoChannelIds: ReadableArray,
+        promise: Promise,
+    ) {
+        val replay = registry.tiCloudStorageReplay(id.toInt())
+        if (replay == null) {
+            promise.resolve(rawDumpStartResult(TiRtcReactNativeErrors.OBJECT_RELEASED, null))
+            return
+        }
+        val options = TiCloudStorageRawDumpOptions(
+            IntArray(audioChannelIds.size()) { audioChannelIds.getInt(it) },
+            IntArray(videoChannelIds.size()) { videoChannelIds.getInt(it) },
+        )
+        replay.startRawDump(options) { result ->
+            val entry = result.dump?.let(registry::add)
+            reactContext.runOnJSQueueThread {
+                promise.resolve(rawDumpStartResult(result.code, entry?.id))
+            }
+        }
+    }
+
     @ReactMethod
     override fun tiCloudStorageRecordingTaskStop(id: Double, promise: Promise) {
         val objectId = id.toInt()
@@ -426,6 +494,18 @@ class TiRtcModule(
         }
     }
 
+    private fun resolveCloudStorageExport(
+        promise: Promise, result: TiCloudStorageExportResult,
+        progress: com.tange.ai.tirtc.TiCloudStorageExportProgress?,
+    ) {
+        val fileId = result.file?.let { file ->
+            nextMediaFileId.getAndIncrement().also { mediaFiles[it] = file }
+        }
+        reactContext.runOnJSQueueThread {
+            promise.resolve(tiCloudStorageExportResult(result, fileId, progress))
+        }
+    }
+
     @ReactMethod
     override fun uploadLogs(promise: Promise) {
         uploadLogsToPromise(promise)
@@ -495,6 +575,49 @@ class TiRtcModule(
         return recordingStartResult(result.code, entry?.id)
     }
 
+    @ReactMethod
+    override fun connStartRawDump(
+        id: Double,
+        audioStreamIds: ReadableArray,
+        videoStreamIds: ReadableArray,
+        uplinkAudioStreamIds: ReadableArray,
+        promise: Promise,
+    ) {
+        val conn = registry.conn(id.toInt())
+        if (conn == null) {
+            promise.resolve(rawDumpStartResult(TiRtcReactNativeErrors.OBJECT_RELEASED, null))
+            return
+        }
+        val options = TiRtcRawDumpOptions(
+            IntArray(audioStreamIds.size()) { audioStreamIds.getInt(it) },
+            IntArray(videoStreamIds.size()) { videoStreamIds.getInt(it) },
+            IntArray(uplinkAudioStreamIds.size()) { uplinkAudioStreamIds.getInt(it) },
+        )
+        conn.startRawDump(options) { result ->
+            val entry = result.dump?.let(registry::add)
+            reactContext.runOnJSQueueThread {
+                promise.resolve(rawDumpStartResult(result.code, entry?.id))
+            }
+        }
+    }
+
+    @ReactMethod
+    override fun rawDumpStop(id: Double, promise: Promise) {
+        val objectId = id.toInt()
+        val dump = registry.rawDump(objectId)
+        if (dump == null) {
+            promise.resolve(rawDumpStopResult(TiRtcReactNativeErrors.OBJECT_RELEASED, null))
+            return
+        }
+        dump.stop { result ->
+            val terminal = result.code != TiCloudStorageErrorCode.IN_USE
+            if (terminal) registry.release(objectId)
+            reactContext.runOnJSQueueThread {
+                promise.resolve(rawDumpStopResult(result.code, result.archive, terminal))
+            }
+        }
+    }
+
     @ReactMethod
     override fun recordingTaskStop(id: Double, promise: Promise) {
         val objectId = id.toInt()

package/android/src/main/java/com/tange/ai/tirtc/reactnative/TiRtcReactNativeCleanup.kt

@@ -12,7 +12,9 @@ import com.tange.ai.tirtc.TiRtcRecordingTask
 import com.tange.ai.tirtc.TiRtcSnapshotFile
 import com.tange.ai.tirtc.TiRtcVideoInput
 import com.tange.ai.tirtc.TiRtcVideoOutput
+import com.tange.ai.tirtc.TiRawDump
 import com.tange.ai.tirtc.TiCloudStorage
+import com.tange.ai.tirtc.TiCloudStorageErrorCode
 import com.tange.ai.tirtc.TiCloudStorageAudioOutput
 import com.tange.ai.tirtc.TiCloudStorageRecordingFile
 import com.tange.ai.tirtc.TiCloudStorageRecordingTask
@@ -31,7 +33,7 @@ internal object TiRtcReactNativeCleanup {
         }
         fun finish() {
             if (pending.decrementAndGet() == 0) {
-                Handler(Looper.getMainLooper()).post { releaseOwners(objects) }
+                Handler(Looper.getMainLooper()).post { releaseOwners(objects.toMutableList()) }
             }
         }
         fun delete(file: Any?) {
@@ -53,6 +55,10 @@ internal object TiRtcReactNativeCleanup {
         files.forEach(::delete)
         objects.forEach { value ->
             when (value) {
+                is TiRawDump -> {
+                    retain()
+                    value.stop { finish() }
+                }
                 is TiRtcRecordingTask -> {
                     retain()
                     value.stop { result ->
@@ -79,31 +85,60 @@ internal object TiRtcReactNativeCleanup {
         finish()
     }
 
-    private fun releaseOwners(objects: List<Any>) {
+    private fun releaseOwners(objects: MutableList<Any>, delayMs: Long = 10) {
+        fun released(operation: String, code: Int): Boolean {
+            if (code == 0 || code == TiRtcReactNativeErrors.OBJECT_RELEASED) return true
+            if (delayMs == 10L || code != TiCloudStorageErrorCode.IN_USE) logFailure(operation, code)
+            // Closing the JS handoff wakes its waiter; the Native callback may still be
+            // unwinding. Retain the owners and yield the main queue until disposal succeeds.
+            Handler(Looper.getMainLooper()).postDelayed({ releaseOwners(objects, minOf(1000, delayMs * 2)) }, delayMs)
+            return false
+        }
+        objects.filterIsInstance<TiCloudStorageReplay>().forEach { replay ->
+            if (!released("ti-cloud-storage-replay-stop", replay.stop())) return
+        }
         objects.filterIsInstance<TiCloudStorageAudioOutput>().forEach { output ->
-            logFailure("ti-cloud-storage-audio-detach", output.detach())
-            logFailure("ti-cloud-storage-audio-dispose", output.dispose())
+            if (!released("ti-cloud-storage-audio-detach", output.detach())) return
+            if (!released("ti-cloud-storage-audio-dispose", output.dispose())) return
+            objects.remove(output)
         }
         objects.filterIsInstance<TiCloudStorageVideoOutput>().forEach { output ->
-            logFailure("ti-cloud-storage-video-detach", output.detach())
-            logFailure("ti-cloud-storage-video-view-detach", output.detachView())
-            logFailure("ti-cloud-storage-video-dispose", output.dispose())
-        }
-        objects.filterIsInstance<TiRtcAudioOutput>().forEach { logFailure("audio_output_dispose", it.dispose()) }
-        objects.filterIsInstance<TiRtcVideoOutput>().forEach { logFailure("video_output_dispose", it.dispose()) }
-        objects.filterIsInstance<TiRtcAudioInput>().forEach { logFailure("audio_input_dispose", it.dispose()) }
-        objects.filterIsInstance<TiRtcVideoInput>().forEach { logFailure("video_input_dispose", it.dispose()) }
+            if (!released("ti-cloud-storage-video-detach", output.detach())) return
+            if (!released("ti-cloud-storage-video-view-detach", output.detachView())) return
+            if (!released("ti-cloud-storage-video-dispose", output.dispose())) return
+            objects.remove(output)
+        }
+        objects.filterIsInstance<TiRtcAudioOutput>().forEach {
+            if (!released("audio_output_dispose", it.dispose())) return
+            objects.remove(it)
+        }
+        objects.filterIsInstance<TiRtcVideoOutput>().forEach {
+            if (!released("video_output_dispose", it.dispose())) return
+            objects.remove(it)
+        }
+        objects.filterIsInstance<TiRtcAudioInput>().forEach {
+            if (!released("audio_input_dispose", it.dispose())) return
+            objects.remove(it)
+        }
+        objects.filterIsInstance<TiRtcVideoInput>().forEach {
+            if (!released("video_input_dispose", it.dispose())) return
+            objects.remove(it)
+        }
         objects.filterIsInstance<TiCloudStorageReplay>().forEach { replay ->
-            logFailure("ti-cloud-storage-replay-stop", replay.stop())
-            logFailure("ti-cloud-storage-replay-dispose", replay.dispose())
+            if (!released("ti-cloud-storage-replay-dispose", replay.dispose())) return
+            objects.remove(replay)
         }
         objects.filterIsInstance<TiRtcConn>().forEach { conn ->
-            logFailure("conn_disconnect", conn.disconnect())
-            logFailure("conn_dispose", conn.dispose())
+            if (!released("conn_disconnect", conn.disconnect())) return
+            if (!released("conn_dispose", conn.dispose())) return
+            objects.remove(conn)
+        }
+        objects.filterIsInstance<TiCloudStorage>().forEach {
+            if (!released("ti-cloud-storage-dispose", it.dispose())) return
+            objects.remove(it)
         }
-        objects.filterIsInstance<TiCloudStorage>().forEach { logFailure("ti-cloud-storage-dispose", it.dispose()) }
-        logFailure("ti-cloud-storage-shutdown", TiCloudStorage.shutdown())
-        logFailure("runtime_shutdown", TiRtc.shutdown())
+        if (!released("ti-cloud-storage-shutdown", TiCloudStorage.shutdown())) return
+        if (!released("runtime_shutdown", TiRtc.shutdown())) return
         TiRtcLogging.i(TAG, "[module_invalidate] native owners released")
     }
 

package/android/src/main/java/com/tange/ai/tirtc/reactnative/TiRtcReactNativeCloudStorageCallbacks.kt

@@ -0,0 +1,60 @@
+package com.tange.ai.tirtc.reactnative
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+
+/** The SDK's single serial background queue permits one borrowed event per module. */
+internal class TiRtcReactNativeCloudStorageCallbacks(private val wake: () -> Unit) {
+    private val monitor = Object()
+    private var closed = false
+    private var pending: WritableMap? = null
+    private var claimed = false
+    private var sequence = 0L
+
+    fun deliver(event: WritableMap) {
+        val deliveryId = synchronized(monitor) {
+            if (closed) return
+            check(pending == null) { "Cloud Storage callbacks require serial SDK delivery" }
+            sequence += 1
+            pending = event
+            claimed = false
+            sequence
+        }
+        var interrupted = false
+        try {
+            wake()
+            synchronized(monitor) {
+                while (!closed && pending != null && sequence == deliveryId) {
+                    try { monitor.wait() } catch (_: InterruptedException) { interrupted = true }
+                }
+            }
+        } finally {
+            if (interrupted) Thread.currentThread().interrupt()
+        }
+    }
+
+    fun take(): WritableMap? = synchronized(monitor) {
+        val event = pending ?: return@synchronized null
+        if (closed || claimed) return@synchronized null
+        claimed = true
+        Arguments.createMap().apply {
+            putDouble("deliveryId", sequence.toDouble())
+            putMap("event", event)
+        }
+    }
+
+    fun acknowledge(deliveryId: Double): Double = synchronized(monitor) {
+        if (!closed && claimed && deliveryId == sequence.toDouble()) {
+            pending = null
+            claimed = false
+            monitor.notifyAll()
+        }
+        0.0
+    }
+
+    fun close() = synchronized(monitor) {
+        closed = true
+        pending = null
+        monitor.notifyAll()
+    }
+}

package/android/src/main/java/com/tange/ai/tirtc/reactnative/TiRtcReactNativeEventBinder.kt

@@ -23,6 +23,7 @@ import com.tange.ai.tirtc.TiCloudStorageOutputErrorListener
 import com.tange.ai.tirtc.TiCloudStorageReplay
 import com.tange.ai.tirtc.TiCloudStorageReplayCompletedListener
 import com.tange.ai.tirtc.TiCloudStorageReplayErrorListener
+import com.tange.ai.tirtc.TiCloudStorageRecordingGapListener
 import com.tange.ai.tirtc.TiCloudStorageTimeChangedListener
 import com.tange.ai.tirtc.TiCloudStorageVideoOutput
 import com.tange.ai.tirtc.TiCloudStorageVideoOutputStateListener
@@ -36,6 +37,7 @@ internal class TiRtcReactNativeEventBinder(
         replay.onTimeChanged = TiCloudStorageTimeChangedListener { events.tiCloudStorageReplayTimeChanged(id, it) }
         replay.onCompleted = TiCloudStorageReplayCompletedListener { events.tiCloudStorageReplayCompleted(id) }
         replay.onError = TiCloudStorageReplayErrorListener { events.tiCloudStorageReplayError(id, it) }
+        replay.onRecordingGap = TiCloudStorageRecordingGapListener { events.tiCloudStorageReplayRecordingGap(id, it) }
     }
 
     fun wireCloudStorageAudioOutput(id: Int, output: TiCloudStorageAudioOutput) {

package/android/src/main/java/com/tange/ai/tirtc/reactnative/TiRtcReactNativeEventSink.kt

@@ -4,6 +4,8 @@ import android.util.Size
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.WritableArray
 import com.facebook.react.bridge.WritableMap
+import com.tange.ai.tirtc.TiCloudStorageExportProgress
+import com.tange.ai.tirtc.TiCloudStorageRecordingGap
 
 internal class TiRtcReactNativeEventSink(
     private val registry: TiRtcReactNativeRegistry,
@@ -60,6 +62,24 @@ internal class TiRtcReactNativeEventSink(
         })
     }
 
+    fun tiCloudStorageReplayRecordingGap(objectId: Int, gap: TiCloudStorageRecordingGap) {
+        emit(base("tiCloudStorageReplayRecordingGap", objectId).apply {
+            putMap("recordingGap", tiCloudStorageRecordingGap(gap))
+        })
+    }
+
+    fun tiCloudStorageExportProgress(objectId: Int, progress: TiCloudStorageExportProgress) {
+        emit(base("tiCloudStorageExportProgress", objectId).apply {
+            putMap("exportProgress", tiCloudStorageExportProgress(progress))
+        })
+    }
+
+    fun tiCloudStorageExportRecordingGap(objectId: Int, gap: TiCloudStorageRecordingGap) {
+        emit(base("tiCloudStorageExportRecordingGap", objectId).apply {
+            putMap("recordingGap", tiCloudStorageRecordingGap(gap))
+        })
+    }
+
     fun audioOutputStateChanged(
         objectId: Int,
         state: String,