tirtc-react-native 2.2.0

package/src/types.ts

@@ -0,0 +1,340 @@
+import type {ViewProps} from 'react-native';
+import type {TiRtcConn} from './conn';
+import type {TiRtcVideoInput} from './video_input';
+import type {TiRtcVideoOutput} from './video_output';
+
+export type TiRtcSize = Readonly<{
+  width: number;
+  height: number;
+}>;
+
+export const TiRtcOutputBufferStrategy = {
+  automatic: 'automatic',
+  noBuffer: 'noBuffer',
+} as const;
+export type TiRtcOutputBufferStrategy =
+  (typeof TiRtcOutputBufferStrategy)[keyof typeof TiRtcOutputBufferStrategy];
+
+export const TiRtcConnState = {
+  idle: 'idle',
+  connecting: 'connecting',
+  connected: 'connected',
+  disconnected: 'disconnected',
+} as const;
+export type TiRtcConnState = (typeof TiRtcConnState)[keyof typeof TiRtcConnState];
+
+export const TiRtcInputState = {
+  idle: 'idle',
+  running: 'running',
+  stopped: 'stopped',
+  failed: 'failed',
+} as const;
+export type TiRtcInputState = (typeof TiRtcInputState)[keyof typeof TiRtcInputState];
+
+export const TiRtcAudioCodec = {
+  g711a: 'g711a',
+  aac: 'aac',
+  pcm: 'pcm',
+  opus: 'opus',
+  amr: 'amr',
+} as const;
+export type TiRtcAudioCodec = (typeof TiRtcAudioCodec)[keyof typeof TiRtcAudioCodec];
+
+export const TiRtcAudioSampleRate = {
+  rate8k: 'rate8k',
+  rate16k: 'rate16k',
+} as const;
+export type TiRtcAudioSampleRate =
+  (typeof TiRtcAudioSampleRate)[keyof typeof TiRtcAudioSampleRate];
+
+export const TiRtcAudioChannelCount = {
+  mono: 'mono',
+} as const;
+export type TiRtcAudioChannelCount =
+  (typeof TiRtcAudioChannelCount)[keyof typeof TiRtcAudioChannelCount];
+
+export const TiRtcAudioAecMode = {
+  disabled: 'disabled',
+  enabled: 'enabled',
+} as const;
+export type TiRtcAudioAecMode = (typeof TiRtcAudioAecMode)[keyof typeof TiRtcAudioAecMode];
+
+export const TiRtcAudioAgcLevel = {
+  disabled: 'disabled',
+  low: 'low',
+  medium: 'medium',
+  high: 'high',
+} as const;
+export type TiRtcAudioAgcLevel =
+  (typeof TiRtcAudioAgcLevel)[keyof typeof TiRtcAudioAgcLevel];
+
+export const TiRtcAudioAnsLevel = {
+  disabled: 'disabled',
+  low: 'low',
+  medium: 'medium',
+  high: 'high',
+} as const;
+export type TiRtcAudioAnsLevel =
+  (typeof TiRtcAudioAnsLevel)[keyof typeof TiRtcAudioAnsLevel];
+
+export const TiRtcVideoCodec = {
+  h264: 'h264',
+  h265: 'h265',
+  mjpeg: 'mjpeg',
+} 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',
+  fps30: 'fps30',
+} as const;
+export type TiRtcVideoFrameRate =
+  (typeof TiRtcVideoFrameRate)[keyof typeof TiRtcVideoFrameRate];
+
+export const TiRtcCameraFacing = {
+  front: 'front',
+  back: 'back',
+} as const;
+export type TiRtcCameraFacing = (typeof TiRtcCameraFacing)[keyof typeof TiRtcCameraFacing];
+
+export const TiRtcVideoDecoderPreference = {
+  auto: 'auto',
+  software: 'software',
+  hardware: 'hardware',
+} as const;
+export type TiRtcVideoDecoderPreference =
+  (typeof TiRtcVideoDecoderPreference)[keyof typeof TiRtcVideoDecoderPreference];
+
+export const TiRtcVideoDecoderBackend = {
+  unknown: 'unknown',
+  software: 'software',
+  hardware: 'hardware',
+} as const;
+export type TiRtcVideoDecoderBackend =
+  (typeof TiRtcVideoDecoderBackend)[keyof typeof TiRtcVideoDecoderBackend];
+
+export const TiRtcVideoBitstreamFormat = {
+  unknown: 'unknown',
+  h264AnnexB: 'h264AnnexB',
+  h265AnnexB: 'h265AnnexB',
+  mjpegJfif: 'mjpegJfif',
+} as const;
+export type TiRtcVideoBitstreamFormat =
+  (typeof TiRtcVideoBitstreamFormat)[keyof typeof TiRtcVideoBitstreamFormat];
+
+export const TiRtcAudioOutputState = {
+  idle: 'idle',
+  buffering: 'buffering',
+  playing: 'playing',
+  failed: 'failed',
+} as const;
+export type TiRtcAudioOutputState =
+  (typeof TiRtcAudioOutputState)[keyof typeof TiRtcAudioOutputState];
+
+export const TiRtcVideoOutputState = {
+  idle: 'idle',
+  buffering: 'buffering',
+  rendering: 'rendering',
+  failed: 'failed',
+} as const;
+export type TiRtcVideoOutputState =
+  (typeof TiRtcVideoOutputState)[keyof typeof TiRtcVideoOutputState];
+
+export type TiRtcInitOptions = Readonly<{
+  appId?: string;
+  endpoint?: string;
+  consoleLogEnabled?: boolean;
+}>;
+
+export type TiRtcAudioOutputOptions = Readonly<{
+  agcLevel?: TiRtcAudioAgcLevel;
+  ansLevel?: TiRtcAudioAnsLevel;
+  bufferStrategy?: TiRtcOutputBufferStrategy;
+  maxBufferWatermarkMs?: number;
+}>;
+
+export type TiRtcVideoOutputOptions = Readonly<{
+  decoderPreference?: TiRtcVideoDecoderPreference;
+  bufferStrategy?: TiRtcOutputBufferStrategy;
+  maxBufferWatermarkMs?: number;
+}>;
+
+/**
+ * Props for the public remote video Fabric surface.
+ *
+ * Pass the owning `TiRtcVideoOutput` instance, not a native id. The component
+ * renders an inert React Native `View` until the output has a live native
+ * identity, and returns to that placeholder after the owner is disposed.
+ */
+export type TiRtcVideoOutputViewProps = ViewProps &
+  Readonly<{
+    /** Video output owner whose attached stream should render in this surface. */
+    output: TiRtcVideoOutput;
+    /** Surface scaling mode. Defaults to `contain`. */
+    resizeMode?: 'contain' | 'cover' | 'stretch';
+  }>;
+
+export type TiRtcAudioInputOptions = Readonly<{
+  codec?: TiRtcAudioCodec;
+  sampleRate?: TiRtcAudioSampleRate;
+  channels?: TiRtcAudioChannelCount;
+  aecMode?: TiRtcAudioAecMode;
+  agcLevel?: TiRtcAudioAgcLevel;
+  ansLevel?: TiRtcAudioAnsLevel;
+}>;
+
+export type TiRtcVideoInputOptions = Readonly<{
+  codec?: TiRtcVideoEncoderCodec;
+  width?: number;
+  height?: number;
+  frameRate?: TiRtcVideoFrameRate;
+  bitrateKbps?: number;
+  cameraFacing?: TiRtcCameraFacing;
+}>;
+
+/**
+ * Props for the public local camera preview Fabric surface.
+ *
+ * Pass the owning `TiRtcVideoInput` instance, not a native id. The component
+ * renders an inert React Native `View` until the input has a live native
+ * identity, and returns to that placeholder after the owner is disposed.
+ */
+export type TiRtcVideoInputPreviewProps = ViewProps &
+  Readonly<{
+    /** Video input owner whose local capture preview should render here. */
+    input: TiRtcVideoInput;
+    /** Surface scaling mode. Defaults to `contain`. */
+    resizeMode?: 'contain' | 'cover' | 'stretch';
+  }>;
+
+export type TiRtcOnConnStateChanged = (state: TiRtcConnState, errorCode: number) => void;
+export type TiRtcOnConnCommand = (commandId: number, data: Uint8Array) => void;
+export type TiRtcOnConnStreamMessage = (
+  streamId: number,
+  timestampMs: number,
+  data: Uint8Array,
+) => void;
+export type TiRtcOnAudioOutputStateChanged = (state: TiRtcAudioOutputState) => void;
+export type TiRtcOnAudioOutputError = (code: number) => void;
+export type TiRtcOnVideoOutputStateChanged = (state: TiRtcVideoOutputState) => void;
+export type TiRtcOnVideoOutputRenderSizeChanged = (size: TiRtcSize) => void;
+export type TiRtcOnVideoOutputError = (code: number) => void;
+export type TiRtcOnInputStateChanged = (state: TiRtcInputState) => void;
+export type TiRtcOnInputError = (code: number, message: string | null) => void;
+export type TiRtcOnVideoInputActualConfigChanged = (size: TiRtcSize, fps: number) => void;
+
+export type TiRtcConnMetricsResult = Readonly<{
+  code: number;
+  snapshot: TiRtcConnMetricsSnapshot | null;
+}>;
+
+export type TiRtcConnMetricsSnapshot = Readonly<{
+  hasConnectStart: boolean;
+  hasConnected: boolean;
+  connectStartMonotonicMs: number;
+  connectedMonotonicMs: number;
+  isReady: boolean;
+  connectDurationMs: number | null;
+}>;
+
+export type TiRtcOutputStartupMetrics = Readonly<{
+  hasConnectStart: boolean;
+  hasConnected: boolean;
+  hasFirstPacket: boolean;
+  hasFirstOutput: boolean;
+  connectStartMonotonicMs: number;
+  connectedMonotonicMs: number;
+  firstPacketMonotonicMs: number;
+  firstOutputMonotonicMs: number;
+  firstPacketAfterConnectedMs: number;
+  firstOutputAfterConnectedMs: number;
+  timeToFirstOutputMs: number;
+}>;
+
+export type TiRtcOutputStutterMetrics = Readonly<{
+  stutterThresholdMs: number;
+  outputDurationMs: number;
+  stutterTotalMs: number;
+  stutterCount: number;
+  stutterPeakMs: number;
+  stutterAverageMs: number;
+  stutterRatePercent: number;
+}>;
+
+export type TiRtcAudioOutputMetricsResult = Readonly<{
+  code: number;
+  snapshot: TiRtcAudioOutputMetricsSnapshot | null;
+}>;
+
+export type TiRtcAudioOutputMetricsSnapshot = Readonly<{
+  startup: TiRtcOutputStartupMetrics;
+  stutter: TiRtcOutputStutterMetrics;
+  estimatedOutputLatencyMs: number;
+  audioCodec: TiRtcAudioCodec | null;
+  audioSampleRateHz: number;
+  audioChannels: number;
+  audioInputBitrateKbps: number;
+  audioInputPacketRate: number;
+  audioRenderCallbackRate: number;
+  statsRefreshIntervalMs: number;
+  statsUpdatedAtMonotonicMs: number;
+}>;
+
+export type TiRtcVideoOutputMetricsResult = Readonly<{
+  code: number;
+  snapshot: TiRtcVideoOutputMetricsSnapshot | null;
+}>;
+
+export type TiRtcVideoOutputMetricsSnapshot = Readonly<{
+  startup: TiRtcOutputStartupMetrics;
+  stutter: TiRtcOutputStutterMetrics;
+  estimatedOutputLatencyMs: number;
+  videoCodec: TiRtcVideoCodec | null;
+  videoWidth: number;
+  videoHeight: number;
+  decoderBackend: TiRtcVideoDecoderBackend;
+  videoInputBitrateKbps: number;
+  videoInputFps: number;
+  videoDecodedFps: number;
+  videoRenderFps: number;
+  statsRefreshIntervalMs: number;
+  statsUpdatedAtMonotonicMs: number;
+}>;
+
+export type TiRtcAudioOutputDebugSnapshotResult = Readonly<{
+  code: number;
+  snapshot: TiRtcAudioOutputDebugSnapshot | null;
+}>;
+
+export type TiRtcAudioOutputDebugSnapshot = Readonly<{
+  codec: TiRtcAudioCodec | null;
+  sampleRateHz: number;
+  channels: number;
+}>;
+
+export type TiRtcVideoOutputDebugSnapshotResult = Readonly<{
+  code: number;
+  snapshot: TiRtcVideoOutputDebugSnapshot | null;
+}>;
+
+export type TiRtcVideoOutputDebugSnapshot = Readonly<{
+  codec: TiRtcVideoCodec | null;
+  bitstreamFormat: TiRtcVideoBitstreamFormat;
+  width: number;
+  height: number;
+  decoderPreference: TiRtcVideoDecoderPreference;
+  resolvedDecoderBackend: TiRtcVideoDecoderBackend;
+}>;
+
+export type TiRtcLoggingUploadResult = Readonly<{
+  code: number;
+  logId: string | null;
+}>;

package/src/video_input.ts

@@ -0,0 +1,314 @@
+import * as React from 'react';
+import {View} from 'react-native';
+
+import {
+  isPlainObject,
+  isPositiveInt32Size,
+  isUInt8,
+  normalizeCreateResult,
+  returnReleasedIfDisposed,
+  TIRTC_ERROR_INVALID_ARGUMENT,
+  TIRTC_ERROR_OK,
+  TIRTC_HOST_ERROR_OBJECT_RELEASED,
+} from './errors';
+import {registerNativeEventHandler, unregisterNativeEventHandler} from './events';
+import {
+  clearNativeIdentity,
+  readNativeIdentity,
+  setNativeIdentity,
+  subscribeNativeIdentity,
+  type NativeIdentity,
+} from './native_object_id';
+import {NativeTiRtc, NativeTiRtcVideoInputPreview, type NativeTiRtcEvent} from './native';
+import {TiRtcConn} from './conn';
+import type {
+  TiRtcInputState,
+  TiRtcOnInputError,
+  TiRtcOnInputStateChanged,
+  TiRtcOnVideoInputActualConfigChanged,
+  TiRtcSize,
+  TiRtcVideoInputOptions,
+  TiRtcVideoInputPreviewProps,
+} from './types';
+
+type VideoInputPreviewPropsWithoutOwner = Omit<TiRtcVideoInputPreviewProps, 'input'>;
+
+export class TiRtcVideoInput {
+  private identity: NativeIdentity | null = null;
+  private disposed = false;
+  private createCode: number = TIRTC_ERROR_OK;
+  private queue: Promise<unknown> = Promise.resolve();
+  private currentState: TiRtcInputState = 'idle';
+  private currentOutputSize: TiRtcSize | null = null;
+  private currentOutputFps: number | null = null;
+  private options: Required<TiRtcVideoInputOptions> = {
+    codec: 'h264',
+    width: 640,
+    height: 480,
+    frameRate: 'fps15',
+    bitrateKbps: 0,
+    cameraFacing: 'front',
+  };
+
+  onStateChanged: TiRtcOnInputStateChanged | null = null;
+  onActualConfigChanged: TiRtcOnVideoInputActualConfigChanged | null = null;
+  onError: TiRtcOnInputError | null = null;
+
+  constructor() {
+    const result = normalizeCreateResult(NativeTiRtc.createVideoInput());
+    this.createCode = result.code;
+    if (result.code === TIRTC_ERROR_OK) {
+      this.adoptIdentity({objectId: result.objectId, generation: result.generation});
+    }
+  }
+
+  get state(): TiRtcInputState {
+    if (this.identity !== null && !this.disposed) {
+      const result = NativeTiRtc.videoInputGetState(this.identity.objectId);
+      if (result.state !== null) {
+        this.currentState = result.state as TiRtcInputState;
+      }
+    }
+    return this.currentState;
+  }
+
+  get outputSize(): TiRtcSize | null {
+    this.refreshActualConfig();
+    return this.currentOutputSize;
+  }
+
+  get outputFps(): number | null {
+    this.refreshActualConfig();
+    return this.currentOutputFps;
+  }
+
+  setOptions(options: TiRtcVideoInputOptions): Promise<number> {
+    if (!isPlainObject(options)) {
+      return Promise.resolve(TIRTC_ERROR_INVALID_ARGUMENT);
+    }
+    const normalized = {
+      codec: options.codec ?? 'h264',
+      width: options.width ?? 640,
+      height: options.height ?? 480,
+      frameRate: options.frameRate ?? 'fps15',
+      bitrateKbps: options.bitrateKbps ?? 0,
+      cameraFacing: options.cameraFacing ?? 'front',
+    };
+    if (!isPositiveInt32Size(normalized.width)
+      || !isPositiveInt32Size(normalized.height)
+      || !Number.isSafeInteger(normalized.bitrateKbps)
+      || normalized.bitrateKbps < 0
+      || normalized.bitrateKbps > 4294967295) {
+      return Promise.resolve(TIRTC_ERROR_INVALID_ARGUMENT);
+    }
+    return this.enqueue(async () => {
+      const identity = this.ensureIdentity();
+      if (typeof identity === 'number') {
+        return identity;
+      }
+      const code = await NativeTiRtc.videoInputSetOptions(identity.objectId, normalized);
+      if (code === TIRTC_ERROR_OK) {
+        this.options = normalized;
+      }
+      return code;
+    });
+  }
+
+  start(): Promise<number> {
+    return this.enqueue(async () => {
+      const identity = this.ensureIdentity();
+      if (typeof identity === 'number') {
+        return identity;
+      }
+      return NativeTiRtc.videoInputStart(identity.objectId);
+    });
+  }
+
+  attach(connection: TiRtcConn, streamId: number): Promise<number> {
+    const connIdentity = readNativeIdentity(connection);
+    if (!isUInt8(streamId)) {
+      return Promise.resolve(TIRTC_ERROR_INVALID_ARGUMENT);
+    }
+    if (connIdentity === null) {
+      return Promise.resolve(TIRTC_ERROR_INVALID_ARGUMENT);
+    }
+    return this.enqueue(async () => {
+      const identity = this.ensureIdentity();
+      if (typeof identity === 'number') {
+        return identity;
+      }
+      return NativeTiRtc.videoInputAttach(identity.objectId, connIdentity.objectId, streamId);
+    });
+  }
+
+  detach(connection: TiRtcConn): Promise<number> {
+    const connIdentity = readNativeIdentity(connection);
+    if (connIdentity === null) {
+      return Promise.resolve(TIRTC_ERROR_INVALID_ARGUMENT);
+    }
+    return this.enqueue(async () => {
+      if (this.identity === null) {
+        return TIRTC_ERROR_OK;
+      }
+      return NativeTiRtc.videoInputDetach(this.identity.objectId, connIdentity.objectId);
+    });
+  }
+
+  stop(): Promise<number> {
+    return this.enqueue(async () => {
+      if (this.identity === null) {
+        return TIRTC_ERROR_OK;
+      }
+      return NativeTiRtc.videoInputStop(this.identity.objectId);
+    });
+  }
+
+  /**
+   * Creates a React element bound to this input owner.
+   *
+   * The returned element renders a placeholder until this input has a live
+   * native identity. Configure and start the input before expecting camera
+   * frames, and dispose the input when capture is no longer needed.
+   */
+  preview(props: VideoInputPreviewPropsWithoutOwner = {}): React.ReactElement {
+    return React.createElement(TiRtcVideoInputPreview, {
+      ...props,
+      input: this,
+    });
+  }
+
+  dispose(): Promise<number> {
+    if (this.disposed) {
+      return Promise.resolve(TIRTC_ERROR_OK);
+    }
+    return this.enqueue(async () => {
+      if (this.identity === null) {
+        this.disposed = true;
+        this.clearCallbacks();
+        this.currentState = 'stopped';
+        this.currentOutputSize = null;
+        this.currentOutputFps = null;
+        return TIRTC_ERROR_OK;
+      }
+      const identity = this.identity;
+      const code = await NativeTiRtc.videoInputDispose(identity.objectId);
+      if (code === TIRTC_ERROR_OK) {
+        this.disposed = true;
+        this.identity = null;
+        unregisterNativeEventHandler(identity);
+        clearNativeIdentity(this);
+        this.clearCallbacks();
+        this.currentState = 'stopped';
+        this.currentOutputSize = null;
+        this.currentOutputFps = null;
+      }
+      return code;
+    }, true);
+  }
+
+  private enqueue(operation: () => Promise<number>, allowDisposed = false): Promise<number> {
+    const released = returnReleasedIfDisposed(this.disposed);
+    if (released !== null && !allowDisposed) {
+      return Promise.resolve(released);
+    }
+    const next = this.queue.then(async () => {
+      if (this.disposed && !allowDisposed) {
+        return TIRTC_HOST_ERROR_OBJECT_RELEASED;
+      }
+      return operation();
+    });
+    this.queue = next.catch(() => undefined);
+    return next;
+  }
+
+  private ensureIdentity(): NativeIdentity | number {
+    const released = returnReleasedIfDisposed(this.disposed);
+    if (released !== null) {
+      return released;
+    }
+    if (this.identity !== null) {
+      return this.identity;
+    }
+    return this.createCode;
+  }
+
+  private adoptIdentity(identity: NativeIdentity): void {
+    this.identity = identity;
+    setNativeIdentity(this, identity);
+    registerNativeEventHandler(identity, (event) => this.handleEvent(event));
+    void NativeTiRtc.videoInputSetOptions(identity.objectId, this.options);
+  }
+
+  private refreshActualConfig(): void {
+    if (this.disposed || this.identity === null) {
+      return;
+    }
+    const result = NativeTiRtc.videoInputGetActualConfig(this.identity.objectId);
+    this.currentOutputSize = result.size;
+    this.currentOutputFps = result.fps;
+  }
+
+  private clearCallbacks(): void {
+    this.onStateChanged = null;
+    this.onActualConfigChanged = null;
+    this.onError = null;
+  }
+
+  private handleEvent(event: NativeTiRtcEvent): void {
+    if (this.disposed) {
+      return;
+    }
+    switch (event.type) {
+      case 'videoInputStateChanged':
+        if (event.state !== undefined) {
+          this.currentState = event.state as TiRtcInputState;
+          this.onStateChanged?.(this.currentState);
+        }
+        break;
+      case 'videoInputActualConfigChanged':
+        if (event.size !== undefined && event.fps !== undefined) {
+          this.currentOutputSize = event.size;
+          this.currentOutputFps = event.fps;
+          this.onActualConfigChanged?.(event.size, event.fps);
+        }
+        break;
+      case 'videoInputError':
+        this.onError?.(event.code ?? TIRTC_ERROR_INVALID_ARGUMENT, event.message ?? null);
+        break;
+      default:
+        break;
+    }
+  }
+}
+
+/**
+ * Renders the local preview surface for a `TiRtcVideoInput`.
+ *
+ * The component observes the owner identity and never accepts raw native ids.
+ * If the owner is not created, has been disposed, or is not a `TiRtcVideoInput`,
+ * it renders a regular `View` with the remaining props.
+ */
+export function TiRtcVideoInputPreview(props: TiRtcVideoInputPreviewProps): React.ReactElement {
+  const {input, resizeMode = 'contain', ...viewProps} = props as TiRtcVideoInputPreviewProps;
+  const identity = useOwnerIdentity(input instanceof TiRtcVideoInput ? input : null);
+  if (identity === null) {
+    return React.createElement(View, viewProps);
+  }
+  return React.createElement(NativeTiRtcVideoInputPreview, {
+    ...viewProps,
+    nativeObjectId: identity.objectId,
+    generation: identity.generation,
+    resizeMode,
+  });
+}
+
+function useOwnerIdentity(owner: object | null): NativeIdentity | null {
+  const [, forceUpdate] = React.useReducer((value: number) => value + 1, 0);
+  React.useEffect(() => {
+    if (owner === null) {
+      return undefined;
+    }
+    return subscribeNativeIdentity(owner, forceUpdate);
+  }, [owner]);
+  return owner === null ? null : readNativeIdentity(owner);
+}