tirtc-react-native 2.4.2 → 2.5.0

package/src/specs/NativeTiRtc.ts

@@ -36,6 +36,7 @@ export type NativeVideoOutputOptions = Readonly<{
 }>;
 
 export type NativeAudioInputOptions = Readonly<{
+  media: number;
   codec: 'g711a' | 'aac' | 'pcm' | 'opus' | 'amr';
   sampleRate: 'rate8k' | 'rate16k';
   channels: 'mono';
@@ -45,7 +46,7 @@ export type NativeAudioInputOptions = Readonly<{
 }>;
 
 export type NativeVideoInputOptions = Readonly<{
-  codec: 'h264' | 'mjpeg';
+  media: number;
   width: number;
   height: number;
   frameRate: 'fps10' | 'fps15' | 'fps30';
@@ -102,11 +103,63 @@ export type NativeLoggingUploadResult = Readonly<{
   logId: string | null;
 }>;
 
+export type NativeRawDumpStartResult = Readonly<{code: number; dumpId: NativeObjectId | null}>;
+export type NativeRawDumpArchive = Readonly<{
+  captureId: string; path: string; size: number; sha256: string; capturedDurationMs: number;
+  captureComplete: boolean; stopReason: number;
+  unsavedPacketCount: number; unsavedByteCount: number; empty: boolean;
+}>;
+export type NativeRawDumpStopResult = Readonly<{
+  code: number; archive: NativeRawDumpArchive | null; terminal: boolean;
+}>;
+
 export type NativeTiCloudStorageRecordingRange = Readonly<{
   startTimeMs: number;
   endTimeMs: number;
 }>;
 
+export type NativeTiCloudStorageRecordingTrack = Readonly<{
+  kind: number;
+  channelId: number;
+}>;
+
+export type NativeTiCloudStorageRecordingGap = Readonly<{
+  range: NativeTiCloudStorageRecordingRange;
+  tracks: ReadonlyArray<NativeTiCloudStorageRecordingTrack>;
+  reasons: ReadonlyArray<number>;
+}>;
+
+export type NativeTiCloudStorageExportProgress = Readonly<{
+  fraction: number;
+  coveredDurationMs: number;
+}>;
+
+export type NativeTiCloudStorageExportSegment = Readonly<{
+  sourceRange: NativeTiCloudStorageRecordingRange;
+  outputStartMs: number;
+  outputEndMs: number;
+}>;
+
+export type NativeTiCloudStorageExportReport = Readonly<{
+  requestedRange: NativeTiCloudStorageRecordingRange;
+  coveredDurationMs: number;
+  segments: ReadonlyArray<NativeTiCloudStorageExportSegment>;
+  gaps: ReadonlyArray<NativeTiCloudStorageRecordingGap>;
+  unprocessedRanges: ReadonlyArray<NativeTiCloudStorageRecordingRange>;
+  complete: boolean;
+  termination: number;
+  cause: number;
+}>;
+
+export type NativeTiCloudStorageExportResult = Readonly<{
+  code: number;
+  fileId: NativeObjectId | null;
+  filePath: string | null;
+  durationMs: number | null;
+  report: NativeTiCloudStorageExportReport | null;
+  progressDetail: NativeTiCloudStorageExportProgress | null;
+}>;
+
 export type NativeTiCloudStorageRecordingRangesResult = Readonly<{
   code: number;
   recordings: ReadonlyArray<NativeTiCloudStorageRecordingRange>;
@@ -131,6 +184,7 @@ export type NativeTiCloudStorageReplayInfo = Readonly<{
 export type NativeTiCloudStorageTaskStartResult = Readonly<{
   code: number;
   taskId: NativeObjectId | null;
+  generation: number;
 }>;
 
 export type NativeTiRtcEvent = Readonly<{
@@ -147,6 +201,8 @@ export type NativeTiRtcEvent = Readonly<{
   data?: NativeBytes;
   size?: NativeSize;
   fps?: number;
+  exportProgress?: NativeTiCloudStorageExportProgress;
+  recordingGap?: NativeTiCloudStorageRecordingGap;
 }>;
 
 type NativeConnMetricsResult = Readonly<{
@@ -242,15 +298,22 @@ type NativeVideoOutputDebugSnapshotResult = Readonly<{
   }> | null;
 }>;
 
+type NativeTiCloudStorageCallback = Readonly<{
+  deliveryId: number;
+  event: NativeTiRtcEvent;
+}>;
+
 interface Spec extends TurboModule {
   readonly onTiRtcEvent: CodegenTypes.EventEmitter<NativeTiRtcEvent>;
 
   initialize(options: NativeInitOptions): Promise<number>;
   shutdown(): number;
   errorToString(code: number): string;
-  writeLog(level: number, tag: string, message: string): void;
+  writeLog(level: number, tag: string, message: string): number;
   uploadLogs(): Promise<NativeLoggingUploadResult>;
 
+  tiCloudStorageTakeCallback(): NativeTiCloudStorageCallback | null;
+  tiCloudStorageAcknowledgeCallback(deliveryId: number): number;
   tiCloudStorageInitialize(options: NativeInitOptions): Promise<number>;
   tiCloudStorageShutdown(): number;
   tiCloudStorageCreate(token: string): NativeCreateResult;
@@ -275,7 +338,9 @@ interface Spec extends TurboModule {
     audioChannelId: number | null,
   ): NativeTiCloudStorageTaskStartResult;
   tiCloudStorageExportProgress(id: NativeObjectId): number;
-  tiCloudStorageExportResult(id: NativeObjectId): Promise<NativeMp4Result>;
+  tiCloudStorageExportProgressDetail(id: NativeObjectId): NativeTiCloudStorageExportProgress;
+  tiCloudStorageExportResult(id: NativeObjectId): Promise<NativeTiCloudStorageExportResult>;
+  tiCloudStorageExportCancel(id: NativeObjectId): number;
   tiCloudStorageExportStop(id: NativeObjectId): number;
   tiCloudStorageDispose(id: NativeObjectId): number;
 
@@ -290,6 +355,11 @@ interface Spec extends TurboModule {
     videoChannelId: number,
     audioChannelId: number | null,
   ): NativeTiCloudStorageTaskStartResult;
+  tiCloudStorageReplayStartRawDump(
+    id: NativeObjectId,
+    audioChannelIds: ReadonlyArray<number>,
+    videoChannelIds: ReadonlyArray<number>,
+  ): Promise<NativeRawDumpStartResult>;
   tiCloudStorageRecordingTaskStop(id: NativeObjectId): Promise<NativeMp4Result>;
   tiCloudStorageReplayStop(id: NativeObjectId): number;
   tiCloudStorageReplayDispose(id: NativeObjectId): number;
@@ -326,6 +396,13 @@ interface Spec extends TurboModule {
     id: NativeObjectId,
     options: NativeRecordingOptions,
   ): NativeRecordingStartResult;
+  connStartRawDump(
+    id: NativeObjectId,
+    audioStreamIds: ReadonlyArray<number>,
+    videoStreamIds: ReadonlyArray<number>,
+    uplinkAudioStreamIds: ReadonlyArray<number>,
+  ): Promise<NativeRawDumpStartResult>;
+  rawDumpStop(id: NativeObjectId): Promise<NativeRawDumpStopResult>;
   recordingTaskStop(id: NativeObjectId): Promise<NativeMp4Result>;
   mediaFileMoveToGallery(id: NativeObjectId, fileName: string | null): Promise<NativeGalleryResult>;
   mediaFileDelete(id: NativeObjectId): Promise<number>;

package/src/storage.ts

@@ -11,7 +11,15 @@ import {
 } from './errors';
 import {registerNativeEventHandler, unregisterNativeEventHandler} from './events';
 import {TiRtcLogging} from './logging';
-import {NativeTiRtc, NativeTiRtcVideoOutputView, type NativeTiRtcEvent} from './native';
+import {logBuildIdentity} from './logging_internal';
+import {
+  NativeTiRtc,
+  NativeTiRtcVideoOutputView,
+  type NativeTiRtcEvent,
+  type NativeTiCloudStorageExportProgress,
+  type NativeTiCloudStorageExportReport,
+  type NativeTiCloudStorageRecordingGap,
+} from './native';
 import {
   clearNativeIdentity,
   readNativeIdentity,
@@ -20,6 +28,12 @@ import {
   type NativeIdentity,
 } from './native_object_id';
 import {NativeMediaFileBase, recordingFailure, type Resp, type TiRtcGalleryAsset} from './recording';
+import {
+  createRawDumpFromNative,
+  normalizeRawDumpIds,
+  TiRawDump,
+  type TiCloudStorageRawDumpOptions,
+} from './raw_dump';
 
 export const TI_CLOUD_STORAGE_ERROR_OK = 0 as const;
 export const TI_CLOUD_STORAGE_ERROR_INVALID_ARGUMENT = 6000 as const;
@@ -45,6 +59,8 @@ export const TI_CLOUD_STORAGE_ERROR_UNAVAILABLE = 6123 as const;
 export const TI_CLOUD_STORAGE_ERROR_STOPPED = 6124 as const;
 export const TI_CLOUD_STORAGE_ERROR_RECORDING_NOT_FOUND = 6134 as const;
 export const TI_CLOUD_STORAGE_ERROR_RECORDING_DOWNLOAD_FAILED = 6135 as const;
+export const TI_CLOUD_STORAGE_ERROR_NETWORK_UNAVAILABLE = 6136 as const;
+export const TI_CLOUD_STORAGE_ERROR_ENDPOINT_DNS_RESOLUTION_FAILED = 6137 as const;
 
 export type TiCloudStorageRecordingRange = Readonly<{
   startTimeMs: number;
@@ -63,6 +79,70 @@ export type TiCloudStorageRecordingDaysResult = Readonly<{
   days: ReadonlyArray<TiCloudStorageRecordingDay>;
 }>;
 
+export const TiCloudStorageRecordingTrackKind = {video: 'video', audio: 'audio'} as const;
+export type TiCloudStorageRecordingTrackKind =
+  (typeof TiCloudStorageRecordingTrackKind)[keyof typeof TiCloudStorageRecordingTrackKind];
+export type TiCloudStorageRecordingTrack = Readonly<{
+  kind: TiCloudStorageRecordingTrackKind;
+  channelId: number;
+}>;
+export const TiCloudStorageRecordingGapReason = {
+  unknown: 'unknown',
+  notFound: 'notFound',
+  downloadFailed: 'downloadFailed',
+  integrityFailed: 'integrityFailed',
+  mediaUnreadable: 'mediaUnreadable',
+  noKeyFrame: 'noKeyFrame',
+  noRecording: 'noRecording',
+  decryptionFailed: 'decryptionFailed',
+  unsupportedMedia: 'unsupportedMedia',
+  trackUnavailable: 'trackUnavailable',
+} as const;
+export type TiCloudStorageRecordingGapReason =
+  (typeof TiCloudStorageRecordingGapReason)[keyof typeof TiCloudStorageRecordingGapReason];
+export type TiCloudStorageRecordingGap = Readonly<{
+  range: TiCloudStorageRecordingRange;
+  tracks: ReadonlyArray<TiCloudStorageRecordingTrack>;
+  reasons: ReadonlyArray<TiCloudStorageRecordingGapReason>;
+}>;
+export type TiCloudStorageExportProgress = Readonly<{
+  fraction: number;
+  coveredDurationMs: number;
+}>;
+export type TiCloudStorageExportSegment = Readonly<{
+  sourceRange: TiCloudStorageRecordingRange;
+  outputStartMs: number;
+  outputEndMs: number;
+}>;
+export const TiCloudStorageExportTermination = {
+  exhausted: 'exhausted',
+  interrupted: 'interrupted',
+  cancelled: 'cancelled',
+  failed: 'failed',
+} as const;
+export type TiCloudStorageExportTermination =
+  (typeof TiCloudStorageExportTermination)[keyof typeof TiCloudStorageExportTermination];
+export type TiCloudStorageExportReport = Readonly<{
+  requestedRange: TiCloudStorageRecordingRange;
+  coveredDurationMs: number;
+  segments: ReadonlyArray<TiCloudStorageExportSegment>;
+  gaps: ReadonlyArray<TiCloudStorageRecordingGap>;
+  unprocessedRanges: ReadonlyArray<TiCloudStorageRecordingRange>;
+  complete: boolean;
+  termination: TiCloudStorageExportTermination;
+  cause: number;
+}>;
+export type TiCloudStorageExportOutcome = Readonly<{
+  code: number;
+  file: TiCloudStorageRecordingFile | null;
+  report: TiCloudStorageExportReport | null;
+}>;
+export type TiCloudStorageExportObserver = Readonly<{
+  onProgress?: (progress: number) => void;
+  onProgressDetail?: (progress: TiCloudStorageExportProgress) => void;
+  onRecordingGap?: (gap: TiCloudStorageRecordingGap) => void;
+}>;
+
 export const TiCloudStorageReplaySpeed = {
   x0_125: 'x0_125',
   x0_25: 'x0_25',
@@ -144,6 +224,37 @@ function success<T>(data: T): Resp<T> {
 function validTime(value: number): boolean {
   return isFiniteSafeInteger(value) && value >= 0;
 }
+
+function recordingGapFromNative(value: NativeTiCloudStorageRecordingGap): TiCloudStorageRecordingGap {
+  const kinds = [TiCloudStorageRecordingTrackKind.video, TiCloudStorageRecordingTrackKind.audio] as const;
+  const reasons = Object.values(TiCloudStorageRecordingGapReason);
+  return {
+    range: value.range,
+    tracks: value.tracks.flatMap((track) => {
+      const kind = kinds[track.kind - 1];
+      return kind === undefined ? [] : [{kind, channelId: track.channelId}];
+    }),
+    reasons: value.reasons.map((reason) => reasons[reason] ?? TiCloudStorageRecordingGapReason.unknown),
+  };
+}
+
+function exportProgressFromNative(value: NativeTiCloudStorageExportProgress): TiCloudStorageExportProgress {
+  return {fraction: value.fraction, coveredDurationMs: value.coveredDurationMs};
+}
+
+function exportReportFromNative(value: NativeTiCloudStorageExportReport): TiCloudStorageExportReport {
+  const terminations = Object.values(TiCloudStorageExportTermination);
+  return {
+    requestedRange: value.requestedRange,
+    coveredDurationMs: value.coveredDurationMs,
+    segments: value.segments,
+    gaps: value.gaps.map(recordingGapFromNative),
+    unprocessedRanges: value.unprocessedRanges,
+    complete: value.complete,
+    termination: terminations[value.termination] ?? TiCloudStorageExportTermination.failed,
+    cause: value.cause,
+  };
+}
 function speedToNative(speed: TiCloudStorageReplaySpeed): number | null {
   switch (speed) {
     case TiCloudStorageReplaySpeed.x0_125:
@@ -214,6 +325,7 @@ function videoStateFromNative(state: unknown): TiCloudStorageVideoOutputState {
 export class TiCloudStorage {
   private identity: NativeIdentity | null = null;
   private disposed = false;
+  private pendingAsyncOperations = 0;
   constructor(private token: string) {}
 
   static init(
@@ -232,6 +344,7 @@ export class TiCloudStorage {
       endpoint: options.endpoint ?? '',
       consoleLogEnabled: options.consoleLogEnabled ?? false,
     }).then((code) => {
+      if (code === 0) logBuildIdentity('cloud_storage');
       tiCloudStorageLogOutcome('cloud_storage_initialize', code);
       return code;
     });
@@ -268,10 +381,12 @@ export class TiCloudStorage {
       return Promise.resolve({code: identity, recordings: []});
     }
     TiRtcLogging.i(tiCloudStorageLogTag, `[recording_list] outcome=started range_duration_ms=${endTimeMs - startTimeMs}`);
-    return NativeTiRtc.tiCloudStorageListRecordings(identity.objectId, startTimeMs, endTimeMs).then((result) => {
-      tiCloudStorageLogOutcome('recording_list', result.code, ` recording_count=${result.recordings.length}`);
-      return result;
-    });
+    return this.trackAsyncOperation(() =>
+      NativeTiRtc.tiCloudStorageListRecordings(identity.objectId, startTimeMs, endTimeMs).then((result) => {
+        tiCloudStorageLogOutcome('recording_list', result.code, ` recording_count=${result.recordings.length}`);
+        return result;
+      }),
+    );
   }
   listRecordingDays(
     startDate: string,
@@ -292,20 +407,25 @@ export class TiCloudStorage {
       return Promise.resolve({code: identity, days: []});
     }
     TiRtcLogging.i(tiCloudStorageLogTag, '[recording_days_list] outcome=started');
-    return NativeTiRtc.tiCloudStorageListRecordingDays(
-      identity.objectId,
-      startDate,
-      endDate,
-      timeZoneId,
-    ).then((result) => {
-      tiCloudStorageLogOutcome('recording_days_list', result.code, ` day_count=${result.days.length}`);
-      return result;
-    });
+    return this.trackAsyncOperation(() =>
+      NativeTiRtc.tiCloudStorageListRecordingDays(
+        identity.objectId,
+        startDate,
+        endDate,
+        timeZoneId,
+      ).then((result) => {
+        tiCloudStorageLogOutcome('recording_days_list', result.code, ` day_count=${result.days.length}`);
+        return result;
+      }),
+    );
   }
   createReplay(): TiCloudStorageReplay {
     return new TiCloudStorageReplay(this);
   }
-  exportRecording(options: TiCloudStorageExportOptions, onProgress?: (progress: number) => void): Resp<TiCloudStorageExportTask> {
+  exportRecording(
+    options: TiCloudStorageExportOptions,
+    observer?: ((progress: number) => void) | TiCloudStorageExportObserver,
+  ): Resp<TiCloudStorageExportTask> {
     if (
       !validTime(options.startTimeMs) ||
       !validTime(options.endTimeMs) ||
@@ -326,11 +446,12 @@ export class TiCloudStorage {
     );
     tiCloudStorageLogOutcome('export_start', result.code, ` range_duration_ms=${options.endTimeMs - options.startTimeMs}`);
     return result.code === 0 && result.taskId !== null
-      ? success(new TiCloudStorageExportTask(result.taskId, this, onProgress))
+      ? success(new TiCloudStorageExportTask(result.taskId, result.generation, this, observer))
       : recordingFailure(result.code);
   }
   dispose(): number {
     if (this.disposed) return 0;
+    if (this.pendingAsyncOperations > 0) return TI_CLOUD_STORAGE_ERROR_IN_USE;
     if (this.identity === null) {
       this.disposed = true;
       this.token = '';
@@ -347,6 +468,17 @@ export class TiCloudStorage {
     }
     return code;
   }
+  private trackAsyncOperation<T>(operation: () => Promise<T>): Promise<T> {
+    this.pendingAsyncOperations += 1;
+    try {
+      return operation().finally(() => {
+        this.pendingAsyncOperations -= 1;
+      });
+    } catch (error) {
+      this.pendingAsyncOperations -= 1;
+      return Promise.reject(error);
+    }
+  }
   private ensureIdentity(): NativeIdentity | number {
     if (this.disposed) return TI_CLOUD_STORAGE_ERROR_NOT_INITIALIZED;
     if (this.identity !== null) return this.identity;
@@ -369,11 +501,13 @@ function tiCloudStorageNativeIdentity(cloudStorage: TiCloudStorage): NativeIdent
 export class TiCloudStorageReplay {
   private identity: NativeIdentity | null = null;
   private disposed = false;
+  private inCallback = false;
   private currentSpeed: TiCloudStorageReplaySpeed = 'x1';
   private currentTime: number | null = null;
   onTimeChanged: ((timeMs: number) => void) | null = null;
   onError: ((code: number) => void) | null = null;
   onCompleted: (() => void) | null = null;
+  onRecordingGap: ((gap: TiCloudStorageRecordingGap) => void) | null = null;
   constructor(private readonly cloudStorage: TiCloudStorage) {}
   get speed(): TiCloudStorageReplaySpeed {
     if (this.identity !== null) {
@@ -390,6 +524,7 @@ export class TiCloudStorageReplay {
     return this.currentTime;
   }
   play(startTimeMs: number, endTimeMs: number, initialTimeMs?: number): number {
+    if (this.inCallback) return TI_CLOUD_STORAGE_ERROR_IN_USE;
     if (
       !validTime(startTimeMs) ||
       !validTime(endTimeMs) ||
@@ -417,6 +552,7 @@ export class TiCloudStorageReplay {
     return code;
   }
   seek(timeMs: number): number {
+    if (this.inCallback) return TI_CLOUD_STORAGE_ERROR_IN_USE;
     if (!validTime(timeMs)) return TI_CLOUD_STORAGE_ERROR_INVALID_ARGUMENT;
     const identity = this.ensureIdentity();
     const code = typeof identity === 'number' ? identity : NativeTiRtc.tiCloudStorageReplaySeek(identity.objectId, timeMs);
@@ -452,19 +588,38 @@ export class TiCloudStorageReplay {
       ? success(new TiCloudStorageRecordingTask(result.taskId, this))
       : recordingFailure(result.code);
   }
+  async startRawDump(options: TiCloudStorageRawDumpOptions): Promise<Resp<TiRawDump>> {
+    if (options === null || typeof options !== 'object')
+      return recordingFailure(TI_CLOUD_STORAGE_ERROR_INVALID_ARGUMENT);
+    const audio = normalizeRawDumpIds(options.audioChannelIds ?? [], 255);
+    const video = normalizeRawDumpIds(options.videoChannelIds ?? [], 255);
+    if (audio === null || video === null || (audio.length === 0 && video.length === 0))
+      return recordingFailure(TI_CLOUD_STORAGE_ERROR_INVALID_ARGUMENT);
+    const identity = this.ensureIdentity();
+    if (typeof identity === 'number') return recordingFailure(identity);
+    const result = await NativeTiRtc.tiCloudStorageReplayStartRawDump(
+      identity.objectId, audio, video,
+    );
+    return result.code === 0 && result.dumpId !== null
+      ? {success: true, code: null, message: null, data: createRawDumpFromNative(result.dumpId)}
+      : recordingFailure(result.code);
+  }
   stop(): number {
+    if (this.inCallback) return TI_CLOUD_STORAGE_ERROR_IN_USE;
     const code = this.command(NativeTiRtc.tiCloudStorageReplayStop);
     if (code === 0) this.currentTime = null;
     tiCloudStorageLogOutcome('replay_stop', code);
     return code;
   }
   dispose(): number {
+    if (this.inCallback) return TI_CLOUD_STORAGE_ERROR_IN_USE;
     if (this.disposed) return 0;
     if (this.identity === null) {
       this.disposed = true;
       this.onTimeChanged = null;
       this.onError = null;
       this.onCompleted = null;
+      this.onRecordingGap = null;
       return 0;
     }
     const identity = this.identity;
@@ -477,6 +632,7 @@ export class TiCloudStorageReplay {
       this.onTimeChanged = null;
       this.onError = null;
       this.onCompleted = null;
+      this.onRecordingGap = null;
     }
     tiCloudStorageLogOutcome('replay_dispose', code);
     return code;
@@ -501,11 +657,18 @@ export class TiCloudStorageReplay {
     return this.identity;
   }
   private handleEvent(event: NativeTiRtcEvent): void {
-    if (event.type === 'tiCloudStorageReplayTimeChanged' && event.timestampMs !== undefined) {
-      this.currentTime = event.timestampMs;
-      this.onTimeChanged?.(event.timestampMs);
-    } else if (event.type === 'tiCloudStorageReplayCompleted') this.onCompleted?.();
-    else if (event.type === 'tiCloudStorageReplayError') this.onError?.(event.code ?? TI_CLOUD_STORAGE_ERROR_UNAVAILABLE);
+    this.inCallback = true;
+    try {
+      if (event.type === 'tiCloudStorageReplayTimeChanged' && event.timestampMs !== undefined) {
+        this.currentTime = event.timestampMs;
+        this.onTimeChanged?.(event.timestampMs);
+      } else if (event.type === 'tiCloudStorageReplayCompleted') this.onCompleted?.();
+      else if (event.type === 'tiCloudStorageReplayError') this.onError?.(event.code ?? TI_CLOUD_STORAGE_ERROR_UNAVAILABLE);
+      else if (event.type === 'tiCloudStorageReplayRecordingGap' && event.recordingGap !== undefined)
+        this.onRecordingGap?.(recordingGapFromNative(event.recordingGap));
+    } finally {
+      this.inCallback = false;
+    }
   }
 }
 
@@ -732,40 +895,98 @@ export class TiCloudStorageRecordingTask {
 
 export class TiCloudStorageExportTask {
   private resultPromise: Promise<Resp<TiCloudStorageRecordingFile>>;
+  private completionPromise: Promise<TiCloudStorageExportOutcome>;
+  private readonly identity: NativeIdentity;
+  private currentProgressDetail: TiCloudStorageExportProgress = {fraction: 0, coveredDurationMs: 0};
+  private currentReport: TiCloudStorageExportReport | null = null;
+  private readonly observer: TiCloudStorageExportObserver;
+  private terminal = false;
+
   constructor(
     private readonly taskId: number,
+    generation: number,
     private readonly owner: TiCloudStorage,
-    private readonly onProgress?: (progress: number) => void,
+    observer?: ((progress: number) => void) | TiCloudStorageExportObserver,
   ) {
-    this.resultPromise = NativeTiRtc.tiCloudStorageExportResult(taskId).then((result) => {
+    this.identity = {objectId: taskId, generation};
+    this.observer = typeof observer === 'function' ? {onProgress: observer} : (observer ?? {});
+    registerNativeEventHandler(this.identity, (event) => this.handleEvent(event));
+    this.completionPromise = NativeTiRtc.tiCloudStorageExportResult(taskId).then((result) => {
+      if (result.progressDetail != null) {
+        const progress = exportProgressFromNative(result.progressDetail);
+        this.currentProgressDetail = {
+          fraction: Math.max(this.currentProgressDetail.fraction, progress.fraction),
+          coveredDurationMs: Math.max(this.currentProgressDetail.coveredDurationMs, progress.coveredDurationMs),
+        };
+      }
+      this.terminal = true;
+      unregisterNativeEventHandler(this.identity);
       tiCloudStorageLogOutcome('export_terminal', result.code, ` duration_ms=${result.durationMs ?? 0}`);
-      return result.code === 0 && result.fileId !== null && result.filePath !== null && result.durationMs !== null
-        ? success(new RecordingFile(result.filePath, result.durationMs, result.fileId))
-        : recordingFailure(result.code);
+      const file =
+        result.fileId !== null && result.filePath !== null && result.durationMs !== null
+          ? new RecordingFile(result.filePath, result.durationMs, result.fileId)
+          : null;
+      this.currentReport = result.report === null ? null : exportReportFromNative(result.report);
+      if (this.currentReport !== null) {
+        this.currentProgressDetail = {
+          fraction: this.currentProgressDetail.fraction,
+          coveredDurationMs: this.currentReport.coveredDurationMs,
+        };
+      }
+      return {code: result.code, file, report: this.currentReport};
     });
-    if (onProgress !== undefined) {
-      let lastProgress = -1;
-      const timer = setInterval(() => {
-        const progress = NativeTiRtc.tiCloudStorageExportProgress(taskId);
-        if (progress !== lastProgress) {
-          lastProgress = progress;
-          onProgress(progress);
-        }
-      }, 100);
-      const clear = () => clearInterval(timer);
-      void this.resultPromise.then(clear, clear);
-    }
+    this.resultPromise = this.completionPromise.then((outcome) =>
+      outcome.code === TI_CLOUD_STORAGE_ERROR_OK && outcome.file !== null
+        ? success(outcome.file)
+        : recordingFailure(outcome.code),
+    );
   }
   get progress(): number {
     void this.owner;
-    return NativeTiRtc.tiCloudStorageExportProgress(this.taskId);
+    return this.progressDetail.fraction;
+  }
+  get progressDetail(): TiCloudStorageExportProgress {
+    if (this.terminal) return this.currentProgressDetail;
+    const value = exportProgressFromNative(NativeTiRtc.tiCloudStorageExportProgressDetail(this.taskId));
+    this.currentProgressDetail = {
+      fraction: Math.max(this.currentProgressDetail.fraction, value.fraction),
+      coveredDurationMs: Math.max(this.currentProgressDetail.coveredDurationMs, value.coveredDurationMs),
+    };
+    return this.currentProgressDetail;
+  }
+  get report(): TiCloudStorageExportReport | null {
+    return this.currentReport;
+  }
+  get completion(): Promise<TiCloudStorageExportOutcome> {
+    return this.completionPromise;
   }
   get result(): Promise<Resp<TiCloudStorageRecordingFile>> {
     return this.resultPromise;
   }
+  cancel(): number {
+    if (this.terminal) return TI_CLOUD_STORAGE_ERROR_OK;
+    const code = NativeTiRtc.tiCloudStorageExportCancel(this.taskId);
+    tiCloudStorageLogOutcome('export_cancel', code);
+    return code;
+  }
   stop(): Promise<Resp<TiCloudStorageRecordingFile>> {
+    if (this.terminal) return this.resultPromise;
     const code = NativeTiRtc.tiCloudStorageExportStop(this.taskId);
     tiCloudStorageLogOutcome('export_stop', code);
     return this.resultPromise;
   }
+  private handleEvent(event: NativeTiRtcEvent): void {
+    if (this.terminal) return;
+    if (event.type === 'tiCloudStorageExportProgress' && event.exportProgress !== undefined) {
+      const progress = exportProgressFromNative(event.exportProgress);
+      this.currentProgressDetail = {
+        fraction: Math.max(this.currentProgressDetail.fraction, progress.fraction),
+        coveredDurationMs: Math.max(this.currentProgressDetail.coveredDurationMs, progress.coveredDurationMs),
+      };
+      this.observer.onProgress?.(this.currentProgressDetail.fraction);
+      this.observer.onProgressDetail?.(this.currentProgressDetail);
+    } else if (event.type === 'tiCloudStorageExportRecordingGap' && event.recordingGap !== undefined) {
+      this.observer.onRecordingGap?.(recordingGapFromNative(event.recordingGap));
+    }
+  }
 }

package/src/types.ts

@@ -84,13 +84,6 @@ export const TiRtcVideoCodec = {
 } as const;
 export type TiRtcVideoCodec = (typeof TiRtcVideoCodec)[keyof typeof TiRtcVideoCodec];
 
-export const TiRtcVideoEncoderCodec = {
-  h264: 'h264',
-  mjpeg: 'mjpeg',
-} as const;
-export type TiRtcVideoEncoderCodec =
-  (typeof TiRtcVideoEncoderCodec)[keyof typeof TiRtcVideoEncoderCodec];
-
 export const TiRtcVideoFrameRate = {
   fps10: 'fps10',
   fps15: 'fps15',
@@ -183,6 +176,9 @@ export type TiRtcVideoOutputViewProps = ViewProps &
   }>;
 
 export type TiRtcAudioInputOptions = Readonly<{
+  /** Nano audio media: 1 PCM, 2 G711A, 3 AAC, 4 Opus, 5 AMR. Omitted or -1 uses codec. */
+  media?: number;
+  /** @deprecated Use media. The legacy default is g711a. */
   codec?: TiRtcAudioCodec;
   sampleRate?: TiRtcAudioSampleRate;
   channels?: TiRtcAudioChannelCount;
@@ -192,7 +188,8 @@ export type TiRtcAudioInputOptions = Readonly<{
 }>;
 
 export type TiRtcVideoInputOptions = Readonly<{
-  codec?: TiRtcVideoEncoderCodec;
+  /** Nano video media: 66 H.264 (default) or 65 MJPEG. */
+  media?: number;
   width?: number;
   height?: number;
   frameRate?: TiRtcVideoFrameRate;