tirtc-react-native 2.3.1 → 2.4.0-alpha.4

package/src/audio_output.ts

@@ -3,13 +3,14 @@ import {
   isPositiveInt32,
   isUInt8,
   normalizeCreateResult,
-  returnReleasedIfDisposed,
+  returnNotInitializedIfDisposed,
   TIRTC_ERROR_INVALID_ARGUMENT,
   TIRTC_ERROR_OK,
 } from './errors';
 import {registerNativeEventHandler, unregisterNativeEventHandler} from './events';
 import {readNativeIdentity, clearNativeIdentity, setNativeIdentity, type NativeIdentity} from './native_object_id';
 import {NativeTiRtc, type NativeTiRtcEvent} from './native';
+import {logRtcOutcome, logRtcState} from './logging_internal';
 import {TiRtcConn} from './conn';
 import type {
   TiRtcAudioOutputDebugSnapshotResult,
@@ -27,11 +28,11 @@ export class TiRtcAudioOutput {
   private currentState: TiRtcAudioOutputState = 'idle';
   private options: Required<Omit<TiRtcAudioOutputOptions, 'maxBufferWatermarkMs'>> &
     Pick<TiRtcAudioOutputOptions, 'maxBufferWatermarkMs'> = {
-      agcLevel: 'disabled',
-      ansLevel: 'disabled',
-      bufferStrategy: 'automatic',
-      maxBufferWatermarkMs: undefined,
-    };
+    agcLevel: 'disabled',
+    ansLevel: 'disabled',
+    bufferStrategy: 'automatic',
+    maxBufferWatermarkMs: undefined,
+  };
 
   onStateChanged: TiRtcOnAudioOutputStateChanged | null = null;
   onError: TiRtcOnAudioOutputError | null = null;
@@ -40,8 +41,12 @@ export class TiRtcAudioOutput {
     const result = normalizeCreateResult(NativeTiRtc.createAudioOutput());
     this.createCode = result.code;
     if (result.code === TIRTC_ERROR_OK) {
-      this.adoptIdentity({objectId: result.objectId, generation: result.generation});
+      this.adoptIdentity({
+        objectId: result.objectId,
+        generation: result.generation,
+      });
     }
+    logRtcOutcome('audio_output_create', result.code);
   }
 
   get state(): TiRtcAudioOutputState {
@@ -61,10 +66,7 @@ export class TiRtcAudioOutput {
       bufferStrategy: options.bufferStrategy ?? 'automatic',
       maxBufferWatermarkMs: options.maxBufferWatermarkMs,
     };
-    if (
-      normalized.maxBufferWatermarkMs !== undefined
-      && !isPositiveInt32(normalized.maxBufferWatermarkMs)
-    ) {
+    if (normalized.maxBufferWatermarkMs !== undefined && !isPositiveInt32(normalized.maxBufferWatermarkMs)) {
       return TIRTC_ERROR_INVALID_ARGUMENT;
     }
     const identity = this.ensureIdentity();
@@ -93,15 +95,20 @@ export class TiRtcAudioOutput {
     if (typeof identity === 'number') {
       return identity;
     }
-    return NativeTiRtc.audioOutputAttach(identity.objectId, connIdentity.objectId, streamId);
+    const code = NativeTiRtc.audioOutputAttach(identity.objectId, connIdentity.objectId, streamId);
+    logRtcOutcome('audio_output_attach', code);
+    return code;
   }
 
   detach(): number {
-    const released = returnReleasedIfDisposed(this.disposed);
+    const released = returnNotInitializedIfDisposed(this.disposed);
     if (released !== null) {
       return released;
     }
-    return this.identity === null ? TIRTC_ERROR_OK : NativeTiRtc.audioOutputDetach(this.identity.objectId);
+    const code = this.identity === null ? TIRTC_ERROR_OK : NativeTiRtc.audioOutputDetach(this.identity.objectId);
+    if (code === TIRTC_ERROR_OK) this.currentState = 'idle';
+    logRtcOutcome('audio_output_detach', code);
+    return code;
   }
 
   setVolume(volumePercent: number): number {
@@ -159,11 +166,12 @@ export class TiRtcAudioOutput {
       this.clearCallbacks();
       this.currentState = 'idle';
     }
+    logRtcOutcome('audio_output_dispose', code);
     return code;
   }
 
   private ensureIdentity(): NativeIdentity | number {
-    const released = returnReleasedIfDisposed(this.disposed);
+    const released = returnNotInitializedIfDisposed(this.disposed);
     if (released !== null) {
       return released;
     }
@@ -193,10 +201,15 @@ export class TiRtcAudioOutput {
       return;
     }
     if (event.type === 'audioOutputStateChanged' && event.state !== undefined) {
-      this.currentState = event.state as TiRtcAudioOutputState;
+      const nextState = event.state as TiRtcAudioOutputState;
+      const changed = this.currentState !== nextState;
+      this.currentState = nextState;
+      if (changed) logRtcState('audio_output_state', nextState);
       this.onStateChanged?.(this.currentState);
     } else if (event.type === 'audioOutputError') {
-      this.onError?.(event.code ?? TIRTC_ERROR_INVALID_ARGUMENT);
+      const code = event.code ?? TIRTC_ERROR_INVALID_ARGUMENT;
+      logRtcOutcome('audio_output', code);
+      this.onError?.(code);
     }
   }
 }

package/src/conn.ts

@@ -3,14 +3,23 @@ import {
   isUInt8,
   isUInt32,
   normalizeCreateResult,
-  returnReleasedIfDisposed,
+  returnNotInitializedIfDisposed,
   TIRTC_ERROR_INVALID_ARGUMENT,
   TIRTC_ERROR_OK,
 } from './errors';
 import {registerNativeEventHandler, unregisterNativeEventHandler} from './events';
 import {clearNativeIdentity, setNativeIdentity, type NativeIdentity} from './native_object_id';
 import {NativeTiRtc, type NativeTiRtcEvent} from './native';
+import {logRtcOutcome, logRtcState} from './logging_internal';
 import {toNativeBytes} from './errors';
+import {
+  recordingFailure,
+  startRecording,
+  validateStartRecordingOptions,
+  type Resp,
+  type TiRtcRecordingTask,
+  type TiRtcStartRecordingOptions,
+} from './recording';
 import type {
   TiRtcConnMetricsResult,
   TiRtcConnState,
@@ -29,14 +38,27 @@ export class TiRtcConn {
     const result = normalizeCreateResult(NativeTiRtc.createConn());
     this.createCode = result.code;
     if (result.code === TIRTC_ERROR_OK) {
-      this.adoptIdentity({objectId: result.objectId, generation: result.generation});
+      this.adoptIdentity({
+        objectId: result.objectId,
+        generation: result.generation,
+      });
     }
+    logRtcOutcome('connection_create', result.code);
   }
 
   onStateChanged: TiRtcOnConnStateChanged | null = null;
   onCommand: TiRtcOnConnCommand | null = null;
   onStreamMessage: TiRtcOnConnStreamMessage | null = null;
 
+  startRecording(options: TiRtcStartRecordingOptions): Resp<TiRtcRecordingTask> {
+    const validationCode = validateStartRecordingOptions(options);
+    if (validationCode !== TIRTC_ERROR_OK) {
+      return recordingFailure(validationCode);
+    }
+    const identity = this.ensureIdentity();
+    return typeof identity === 'number' ? recordingFailure(identity) : startRecording(identity.objectId, options);
+  }
+
   get state(): TiRtcConnState {
     if (this.identity !== null && !this.disposed) {
       const result = NativeTiRtc.connGetState(this.identity.objectId);
@@ -55,15 +77,19 @@ export class TiRtcConn {
     if (typeof identity === 'number') {
       return identity;
     }
-    return NativeTiRtc.connConnect(identity.objectId, remoteId, token);
+    const code = NativeTiRtc.connConnect(identity.objectId, remoteId, token);
+    logRtcOutcome('connection_connect', code);
+    return code;
   }
 
   disconnect(): number {
-    const released = returnReleasedIfDisposed(this.disposed);
+    const released = returnNotInitializedIfDisposed(this.disposed);
     if (released !== null) {
       return released;
     }
-    return this.identity === null ? TIRTC_ERROR_OK : NativeTiRtc.connDisconnect(this.identity.objectId);
+    const code = this.identity === null ? TIRTC_ERROR_OK : NativeTiRtc.connDisconnect(this.identity.objectId);
+    logRtcOutcome('connection_disconnect', code);
+    return code;
   }
 
   sendCommand(commandId: number, data: Uint8Array): number {
@@ -93,37 +119,27 @@ export class TiRtcConn {
     if (typeof identity === 'number') {
       return identity;
     }
-    return NativeTiRtc.connSendStreamMessage(
-      identity.objectId,
-      streamId,
-      timestampMs,
-      nativeBytes,
-    );
+    return NativeTiRtc.connSendStreamMessage(identity.objectId, streamId, timestampMs, nativeBytes);
   }
 
   subscribeVideo(streamId: number): number {
-    return this.callWithStream(streamId, (identity) =>
-      NativeTiRtc.connSubscribeVideo(identity.objectId, streamId));
+    return this.callWithStream(streamId, (identity) => NativeTiRtc.connSubscribeVideo(identity.objectId, streamId));
   }
 
   unsubscribeVideo(streamId: number): number {
-    return this.callWithStream(streamId, (identity) =>
-      NativeTiRtc.connUnsubscribeVideo(identity.objectId, streamId));
+    return this.callWithStream(streamId, (identity) => NativeTiRtc.connUnsubscribeVideo(identity.objectId, streamId));
   }
 
   subscribeAudio(streamId: number): number {
-    return this.callWithStream(streamId, (identity) =>
-      NativeTiRtc.connSubscribeAudio(identity.objectId, streamId));
+    return this.callWithStream(streamId, (identity) => NativeTiRtc.connSubscribeAudio(identity.objectId, streamId));
   }
 
   unsubscribeAudio(streamId: number): number {
-    return this.callWithStream(streamId, (identity) =>
-      NativeTiRtc.connUnsubscribeAudio(identity.objectId, streamId));
+    return this.callWithStream(streamId, (identity) => NativeTiRtc.connUnsubscribeAudio(identity.objectId, streamId));
   }
 
   requestKeyFrame(streamId: number): number {
-    return this.callWithStream(streamId, (identity) =>
-      NativeTiRtc.connRequestKeyFrame(identity.objectId, streamId));
+    return this.callWithStream(streamId, (identity) => NativeTiRtc.connRequestKeyFrame(identity.objectId, streamId));
   }
 
   getMetricsSnapshot(): TiRtcConnMetricsResult {
@@ -153,6 +169,7 @@ export class TiRtcConn {
       this.clearCallbacks();
       this.currentState = 'disconnected';
     }
+    logRtcOutcome('connection_dispose', code);
     return code;
   }
 
@@ -168,7 +185,7 @@ export class TiRtcConn {
   }
 
   private ensureIdentity(): NativeIdentity | number {
-    const released = returnReleasedIfDisposed(this.disposed);
+    const released = returnNotInitializedIfDisposed(this.disposed);
     if (released !== null) {
       return released;
     }
@@ -197,7 +214,12 @@ export class TiRtcConn {
     switch (event.type) {
       case 'connStateChanged':
         if (event.state !== undefined && event.errorCode !== undefined) {
-          this.currentState = event.state as TiRtcConnState;
+          const nextState = event.state as TiRtcConnState;
+          const changed = this.currentState !== nextState;
+          this.currentState = nextState;
+          if (changed || event.errorCode !== 0) {
+            logRtcState('connection_state', nextState, event.errorCode);
+          }
           this.onStateChanged?.(this.currentState, event.errorCode);
         }
         break;
@@ -208,11 +230,7 @@ export class TiRtcConn {
         break;
       case 'connStreamMessage':
         if (event.streamId !== undefined && event.timestampMs !== undefined) {
-          this.onStreamMessage?.(
-            event.streamId,
-            event.timestampMs,
-            fromNativeBytes(event.data),
-          );
+          this.onStreamMessage?.(event.streamId, event.timestampMs, fromNativeBytes(event.data));
         }
         break;
       default:

package/src/errors.ts

@@ -1,6 +1,7 @@
 export const TIRTC_ERROR_OK = 0;
 export const TIRTC_ERROR_INVALID_ARGUMENT = 6000;
-export const TIRTC_HOST_ERROR_OBJECT_RELEASED = 1008;
+export const TIRTC_ERROR_NOT_INITIALIZED = 6001;
+export const TIRTC_ERROR_IN_USE = 6026;
 
 export type NativeCreateResultLike = Readonly<{
   code: number;
@@ -9,8 +10,8 @@ export type NativeCreateResultLike = Readonly<{
   message: string | null;
 }>;
 
-export function returnReleasedIfDisposed(disposed: boolean): number | null {
-  return disposed ? TIRTC_HOST_ERROR_OBJECT_RELEASED : null;
+export function returnNotInitializedIfDisposed(disposed: boolean): number | null {
+  return disposed ? TIRTC_ERROR_NOT_INITIALIZED : null;
 }
 
 export function normalizeCreateResult(result: NativeCreateResultLike): NativeCreateResultLike {

package/src/index.ts

@@ -59,3 +59,57 @@ export {TiRtcVideoOutput, TiRtcVideoOutputView} from './video_output';
 export {TiRtcAudioInput} from './audio_input';
 export {TiRtcVideoInput, TiRtcVideoInputPreview} from './video_input';
 export {TiRtcLogging} from './logging';
+export {TiRtcRecordingTask} from './recording';
+export type {
+  Resp,
+  TiRtcGalleryAsset,
+  TiRtcRecordingFile,
+  TiRtcSnapshotFile,
+  TiRtcStartRecordingOptions,
+} from './recording';
+export {
+  TI_CLOUD_STORAGE_ERROR_OK,
+  TI_CLOUD_STORAGE_ERROR_INVALID_ARGUMENT,
+  TI_CLOUD_STORAGE_ERROR_NOT_INITIALIZED,
+  TI_CLOUD_STORAGE_ERROR_TOKEN_EXPIRED,
+  TI_CLOUD_STORAGE_ERROR_ALREADY_INITIALIZED,
+  TI_CLOUD_STORAGE_ERROR_PERMISSION_DENIED,
+  TI_CLOUD_STORAGE_ERROR_IN_USE,
+  TI_CLOUD_STORAGE_ERROR_NOT_STARTED,
+  TI_CLOUD_STORAGE_ERROR_NOT_BOUND,
+  TI_CLOUD_STORAGE_ERROR_NOT_CONFIGURED,
+  TI_CLOUD_STORAGE_ERROR_RESOURCE_EXHAUSTED,
+  TI_CLOUD_STORAGE_ERROR_FILE_WRITE_FAILED,
+  TI_CLOUD_STORAGE_ERROR_UNSUPPORTED_FORMAT,
+  TI_CLOUD_STORAGE_ERROR_IO_FAILED,
+  TI_CLOUD_STORAGE_ERROR_CANCELLED,
+  TI_CLOUD_STORAGE_ERROR_RANGE_TOO_LARGE,
+  TI_CLOUD_STORAGE_ERROR_NO_FRAME,
+  TI_CLOUD_STORAGE_ERROR_NO_RECORDABLE_MEDIA,
+  TI_CLOUD_STORAGE_ERROR_RECORDING_OVERRUN,
+  TI_CLOUD_STORAGE_ERROR_RECORDING_UNREADABLE,
+  TI_CLOUD_STORAGE_ERROR_UNAVAILABLE,
+  TI_CLOUD_STORAGE_ERROR_STOPPED,
+  TiCloudStorageReplaySpeed,
+  TiCloudStorageAudioOutputState,
+  TiCloudStorageVideoOutputState,
+  TiCloudStorage,
+  TiCloudStorageReplay,
+  TiCloudStorageAudioOutput,
+  TiCloudStorageVideoOutput,
+  TiCloudStorageVideoOutputView,
+  TiCloudStorageRecordingTask,
+  TiCloudStorageExportTask,
+} from './storage';
+export type {
+  TiCloudStorageRecordingRange,
+  TiCloudStorageRecordingRangesResult,
+  TiCloudStorageRecordingDay,
+  TiCloudStorageRecordingDaysResult,
+  TiCloudStorageStartRecordingOptions,
+  TiCloudStorageExportOptions,
+  TiCloudStorageGalleryAsset,
+  TiCloudStorageRecordingFile,
+  TiCloudStorageSnapshotFile,
+  TiCloudStorageVideoOutputViewProps,
+} from './storage';

package/src/logging.ts

@@ -28,6 +28,12 @@ export class TiRtcLogging {
   }
 
   static upload(): Promise<TiRtcLoggingUploadResult> {
-    return NativeTiRtc.uploadLogs();
+    TiRtcLogging.i('TIRTC_REACT_NATIVE', '[log_upload] started');
+    return NativeTiRtc.uploadLogs().then((result) => {
+      const message = `[log_upload] completed code=${result.code}`;
+      if (result.code === 0) TiRtcLogging.i('TIRTC_REACT_NATIVE', message);
+      else TiRtcLogging.w('TIRTC_REACT_NATIVE', message);
+      return result;
+    });
   }
 }

package/src/logging_internal.ts

@@ -0,0 +1,23 @@
+import {TiRtcLogging} from './logging';
+
+const rtcLogTag = 'TIRTC_REACT_NATIVE';
+
+export function logRtcOutcome(operation: string, code: number, details = ''): void {
+  const message = `[${operation}] completed code=${code}${details}`;
+  try {
+    if (code === 0) TiRtcLogging.i(rtcLogTag, message);
+    else TiRtcLogging.w(rtcLogTag, message);
+  } catch {
+    // Diagnostics must never change the SDK operation result.
+  }
+}
+
+export function logRtcState(operation: string, state: string, code = 0): void {
+  const message = `[${operation}] state=${state} code=${code}`;
+  try {
+    if (code === 0) TiRtcLogging.i(rtcLogTag, message);
+    else TiRtcLogging.w(rtcLogTag, message);
+  } catch {
+    // Diagnostics must never change callback delivery.
+  }
+}

package/src/recording.ts

@@ -0,0 +1,271 @@
+import {isUInt8, TIRTC_ERROR_INVALID_ARGUMENT} from './errors';
+import {TiRtcLogging} from './logging';
+import {logRtcOutcome} from './logging_internal';
+import {NativeTiRtc} from './native';
+
+export type Resp<T> = Readonly<{
+  success: boolean;
+  code: number | null;
+  message: string | null;
+  data: T | null;
+}>;
+
+export type TiRtcStartRecordingOptions = Readonly<{
+  videoStreamId: number;
+  audioStreamId?: number;
+}>;
+
+export type TiRtcGalleryAsset = Readonly<{
+  uri: string;
+}>;
+
+function success<T>(data: T): Resp<T> {
+  return {success: true, code: null, message: null, data};
+}
+
+export function recordingFailure<T>(code: number, message: string | null = null): Resp<T> {
+  return {success: false, code, message, data: null};
+}
+
+const mediaFileFinalizer =
+  typeof FinalizationRegistry === 'undefined'
+    ? null
+    : new FinalizationRegistry<number>((nativeFileId) => NativeTiRtc.mediaFileRelease(nativeFileId));
+
+function logMediaOutcome(operation: string, code: number): void {
+  const message = `[${operation}] outcome=${code === 0 ? 'ok' : 'failed'} error_code=${code}`;
+  if (code === 0) TiRtcLogging.i('TIRTC_REACT_NATIVE_MEDIA', message);
+  else TiRtcLogging.e('TIRTC_REACT_NATIVE_MEDIA', message);
+}
+
+export interface TiRtcMediaFile {
+  readonly path: string;
+  moveToGallery(fileName?: string): Promise<Resp<TiRtcGalleryAsset>>;
+  delete(): Promise<number>;
+}
+
+export interface TiRtcRecordingFile extends TiRtcMediaFile {
+  readonly durationMs: number;
+}
+
+export interface TiRtcSnapshotFile extends TiRtcMediaFile {}
+
+export abstract class NativeMediaFileBase implements TiRtcMediaFile {
+  private movePromise: Promise<Resp<TiRtcGalleryAsset>> | null = null;
+  private moveFileName: string | null = null;
+  private deletePromise: Promise<number> | null = null;
+  private deleted = false;
+  private galleryAsset: TiRtcGalleryAsset | null = null;
+
+  protected constructor(
+    readonly path: string,
+    private readonly nativeFileId: number,
+    private readonly mediaKind: 'video' | 'image',
+  ) {
+    mediaFileFinalizer?.register(this, nativeFileId, this);
+  }
+
+  moveToGallery(fileName?: string): Promise<Resp<TiRtcGalleryAsset>> {
+    const normalized = normalizeGalleryFileName(fileName, this.mediaKind);
+    if (normalized.code !== 0) {
+      return Promise.resolve(recordingFailure<TiRtcGalleryAsset>(normalized.code));
+    }
+    if (this.galleryAsset !== null) {
+      return Promise.resolve(success(this.galleryAsset));
+    }
+    if (this.deleted) {
+      return Promise.resolve(recordingFailure<TiRtcGalleryAsset>(6045));
+    }
+    if (this.movePromise !== null) {
+      return normalized.fileName === this.moveFileName
+        ? this.movePromise
+        : Promise.resolve(recordingFailure<TiRtcGalleryAsset>(6026));
+    }
+    if (this.deletePromise !== null) {
+      return Promise.resolve(recordingFailure<TiRtcGalleryAsset>(6026));
+    }
+    this.moveFileName = normalized.fileName;
+    this.movePromise = NativeTiRtc.mediaFileMoveToGallery(this.nativeFileId, normalized.fileName)
+      .then((result) => {
+        if (
+          result.code === 0
+          && (result.uri === null || !/^[A-Za-z][A-Za-z0-9+.-]*:/.test(result.uri))
+        ) {
+          logMediaOutcome('gallery_move', 1001);
+          this.deleted = true;
+          NativeTiRtc.mediaFileRelease(this.nativeFileId);
+          mediaFileFinalizer?.unregister(this);
+          return recordingFailure<TiRtcGalleryAsset>(1001);
+        }
+        logMediaOutcome('gallery_move', result.code);
+        if (result.code !== 0 || result.uri === null) {
+          return recordingFailure<TiRtcGalleryAsset>(result.code);
+        }
+        this.galleryAsset = {uri: result.uri};
+        this.deleted = true;
+        NativeTiRtc.mediaFileRelease(this.nativeFileId);
+        mediaFileFinalizer?.unregister(this);
+        return success(this.galleryAsset);
+      })
+      .finally(() => {
+        this.movePromise = null;
+        this.moveFileName = null;
+      });
+    return this.movePromise;
+  }
+
+  delete(): Promise<number> {
+    if (this.deleted || this.galleryAsset !== null) {
+      return Promise.resolve(0);
+    }
+    if (this.deletePromise !== null) {
+      return this.deletePromise;
+    }
+    if (this.movePromise !== null) {
+      return Promise.resolve(6026);
+    }
+    this.deletePromise = this.deleteOnce().finally(() => {
+      this.deletePromise = null;
+    });
+    return this.deletePromise;
+  }
+
+  private async deleteOnce(): Promise<number> {
+    const code = await NativeTiRtc.mediaFileDelete(this.nativeFileId);
+    logMediaOutcome('media_delete', code);
+    if (code === 0) {
+      this.deleted = true;
+      NativeTiRtc.mediaFileRelease(this.nativeFileId);
+      mediaFileFinalizer?.unregister(this);
+    }
+    return code;
+  }
+}
+
+type NormalizedGalleryFileName = Readonly<{
+  code: number;
+  fileName: string | null;
+}>;
+
+export function normalizeGalleryFileName(
+  fileName: string | undefined,
+  mediaType: 'video' | 'image',
+): NormalizedGalleryFileName {
+  if (fileName === undefined) {
+    return {code: 0, fileName: null};
+  }
+  if (
+    typeof fileName !== 'string'
+    || fileName.length === 0
+    || fileName.trim().length === 0
+    || fileName === '.'
+    || fileName === '..'
+    || fileName.includes('/')
+    || fileName.includes('\\')
+    || fileName.includes('\0')
+  ) {
+    return {code: TIRTC_ERROR_INVALID_ARGUMENT, fileName: null};
+  }
+  const extension = mediaType === 'video' ? '.mp4' : '.jpg';
+  const lowerName = fileName.toLowerCase();
+  let stem: string;
+  let normalizedName: string;
+  if (lowerName.endsWith(extension)) {
+    stem = fileName.slice(0, -extension.length);
+    normalizedName = fileName;
+  } else if (fileName.includes('.')) {
+    return {code: TIRTC_ERROR_INVALID_ARGUMENT, fileName: null};
+  } else {
+    stem = fileName;
+    normalizedName = `${fileName}${extension}`;
+  }
+  const stemBytes = utf8ByteLength(stem);
+  return stemBytes >= 1 && stemBytes <= 200
+    ? {code: 0, fileName: normalizedName}
+    : {code: TIRTC_ERROR_INVALID_ARGUMENT, fileName: null};
+}
+
+function utf8ByteLength(value: string): number {
+  let bytes = 0;
+  for (const character of value) {
+    const codePoint = character.codePointAt(0) ?? 0;
+    bytes += codePoint <= 0x7f ? 1 : codePoint <= 0x7ff ? 2 : codePoint <= 0xffff ? 3 : 4;
+  }
+  return bytes;
+}
+
+class TiRtcRecordingFileImpl extends NativeMediaFileBase implements TiRtcRecordingFile {
+  constructor(
+    path: string,
+    readonly durationMs: number,
+    nativeFileId: number,
+  ) {
+    super(path, nativeFileId, 'video');
+  }
+}
+
+class TiRtcSnapshotFileImpl extends NativeMediaFileBase implements TiRtcSnapshotFile {
+  constructor(path: string, nativeFileId: number) {
+    super(path, nativeFileId, 'image');
+  }
+}
+
+export function validateStartRecordingOptions(options: TiRtcStartRecordingOptions): number {
+  return options != null &&
+    isUInt8(options.videoStreamId) &&
+    options.videoStreamId <= 15 &&
+    (options.audioStreamId === undefined || (isUInt8(options.audioStreamId) && options.audioStreamId <= 15)) &&
+    options.audioStreamId !== options.videoStreamId
+    ? 0
+    : TIRTC_ERROR_INVALID_ARGUMENT;
+}
+
+export class TiRtcRecordingTask {
+  private stopPromise: Promise<Resp<TiRtcRecordingFile>> | null = null;
+
+  protected constructor(private readonly nativeTaskId: number) {}
+
+  stop(): Promise<Resp<TiRtcRecordingFile>> {
+    if (this.stopPromise === null) {
+      this.stopPromise = NativeTiRtc.recordingTaskStop(this.nativeTaskId).then((result) => {
+        logRtcOutcome('recording_stop', result.code, ` duration_ms=${result.durationMs ?? 0}`);
+        if (result.code !== 0 || result.fileId === null || result.filePath === null || result.durationMs === null) {
+          return recordingFailure<TiRtcRecordingFile>(result.code);
+        }
+        return success(new TiRtcRecordingFileImpl(result.filePath, result.durationMs, result.fileId));
+      });
+    }
+    return this.stopPromise;
+  }
+}
+
+class NativeTiRtcRecordingTask extends TiRtcRecordingTask {
+  constructor(nativeTaskId: number) {
+    super(nativeTaskId);
+  }
+}
+
+export function startRecording(
+  nativeConnectionId: number,
+  options: TiRtcStartRecordingOptions,
+): Resp<TiRtcRecordingTask> {
+  const validationCode = validateStartRecordingOptions(options);
+  if (validationCode !== 0) {
+    return recordingFailure(validationCode);
+  }
+  const result = NativeTiRtc.connStartRecording(nativeConnectionId, {
+    videoStreamId: options.videoStreamId,
+    audioStreamId: options.audioStreamId ?? null,
+  });
+  logRtcOutcome('recording_start', result.code);
+  return result.code === 0 && result.taskId !== null
+    ? success(new NativeTiRtcRecordingTask(result.taskId))
+    : recordingFailure(result.code);
+}
+
+export async function takeSnapshot(nativeOutputId: number): Promise<Resp<TiRtcSnapshotFile>> {
+  const result = await NativeTiRtc.videoOutputTakeSnapshot(nativeOutputId);
+  return result.code === 0 && result.fileId !== null && result.filePath !== null
+    ? success(new TiRtcSnapshotFileImpl(result.filePath, result.fileId))
+    : recordingFailure(result.code);
+}