agora-electron-sdk 4.2.6 → 4.3.0-dev.1

package/ts/Private/AgoraMediaBase.ts

@@ -108,9 +108,9 @@ export enum AudioRoute {
    */
   RouteLoudspeaker = 4,
   /**
-   * @ignore
+   * 5: The audio route is a Bluetooth device using the HFP protocol.
    */
-  RouteHeadsetbluetooth = 5,
+  RouteBluetoothDeviceHfp = 5,
   /**
    * 7: The audio route is a USB peripheral device. (For macOS only)
    */
@@ -127,6 +127,10 @@ export enum AudioRoute {
    * 9: The audio route is Apple AirPlay. (For macOS only)
    */
   RouteAirplay = 9,
+  /**
+   * 10: The audio route is a Bluetooth device using the A2DP protocol.
+   */
+  RouteBluetoothDeviceA2dp = 10,
 }
 
 /**
@@ -188,7 +192,7 @@ export enum MediaSourceType {
    */
   PrimaryCameraSource = 2,
   /**
-   * 3: The secondary camera.
+   * 3: A secondary camera.
    */
   SecondaryCameraSource = 3,
   /**
@@ -200,7 +204,7 @@ export enum MediaSourceType {
    */
   SecondaryScreenSource = 5,
   /**
-   * @ignore
+   * 6. Custom video source.
    */
   CustomVideoSource = 6,
   /**
@@ -483,6 +487,26 @@ export enum CameraVideoSourceType {
   VideoSourceUnspecified = 2,
 }
 
+/**
+ * @ignore
+ */
+export enum MetaInfoKey {
+  /**
+   * @ignore
+   */
+  KeyFaceCapture = 0,
+}
+
+/**
+ * @ignore
+ */
+export abstract class IVideoFrameMetaInfo {
+  /**
+   * @ignore
+   */
+  abstract getMetaInfoStr(key: MetaInfoKey): string;
+}
+
 /**
  * @ignore
  */
@@ -671,6 +695,10 @@ export class VideoFrame {
    * @ignore
    */
   pixelBuffer?: Uint8Array;
+  /**
+   * The meta information in the video frame. To use this parameter, please.
+   */
+  metaInfo?: IVideoFrameMetaInfo;
 }
 
 /**
@@ -696,7 +724,7 @@ export enum MediaPlayerSourceType {
  */
 export enum VideoModulePosition {
   /**
-   * 1: The post-capturer position, which corresponds to the video data in the onCaptureVideoFrame callback.
+   * 1: The location of the locally collected video data after preprocessing corresponds to the onCaptureVideoFrame callback. The observed video here has the effect of video pre-processing, which can be verified by enabling image enhancement, virtual background, or watermark.
    */
   PositionPostCapturer = 1 << 0,
   /**
@@ -704,9 +732,15 @@ export enum VideoModulePosition {
    */
   PositionPreRenderer = 1 << 1,
   /**
-   * 4: The pre-encoder position, which corresponds to the video data in the onPreEncodeVideoFrame callback.
+   * 4: The pre-encoder position, which corresponds to the video data in the onPreEncodeVideoFrame callback. The observed video here has the effects of video pre-processing and encoding pre-processing.
+   *  To verify the pre-processing effects of the video, you can enable image enhancement, virtual background, or watermark.
+   *  To verify the pre-encoding processing effect, you can set a lower frame rate (for example, 5 fps).
    */
   PositionPreEncoder = 1 << 2,
+  /**
+   * 8: The position after local video capture and before pre-processing. The observed video here does not have pre-processing effects, which can be verified by enabling image enhancement, virtual background, or watermarks.
+   */
+  PositionPostCapturerOrigin = 1 << 3,
 }
 
 /**
@@ -777,6 +811,10 @@ export class AudioFrame {
    * @ignore
    */
   presentationMs?: number;
+  /**
+   * @ignore
+   */
+  audioTrackNumber?: number;
 }
 
 /**
@@ -1027,13 +1065,13 @@ export interface IVideoFrameObserver {
    * Occurs each time the SDK receives a video frame captured by local devices.
    *
    * After you successfully register the video frame observer, the SDK triggers this callback each time it receives a video frame. In this callback, you can get the video data captured by local devices. You can then pre-process the data according to your scenarios. Once the pre-processing is complete, you can directly modify videoFrame in this callback, and set the return value to true to send the modified video data to the SDK.
-   *  The video data that this callback gets has not been pre-processed, and is not watermarked, cropped, rotated or beautified.
+   *  The video data that this callback gets has not been pre-processed such as watermarking, cropping, and rotating.
    *  If the video data type you get is RGBA, the SDK does not support processing the data of the alpha channel.
    *
    * @param sourceType Video source types, including cameras, screens, or media player. See VideoSourceType.
    * @param videoFrame The video frame. See VideoFrame. The default value of the video frame data format obtained through this callback is as follows:
-   *  macOS: YUV 420
-   *  Windows: YUV 420
+   *  macOS: I420 or CVPixelBufferRef
+   *  Windows: YUV420
    *
    * @returns
    * When the video processing mode is ProcessModeReadOnly : true : Reserved for future use. false : Reserved for future use.
@@ -1052,8 +1090,8 @@ export interface IVideoFrameObserver {
    *
    * @param sourceType The type of the video source. See VideoSourceType.
    * @param videoFrame The video frame. See VideoFrame. The default value of the video frame data format obtained through this callback is as follows:
-   *  macOS: YUV 420
-   *  Windows: YUV 420
+   *  macOS: I420 or CVPixelBufferRef
+   *  Windows: YUV420
    *
    * @returns
    * When the video processing mode is ProcessModeReadOnly : true : Reserved for future use. false : Reserved for future use.
@@ -1078,8 +1116,8 @@ export interface IVideoFrameObserver {
    * @param channelId The channel ID.
    * @param remoteUid The user ID of the remote user who sends the current video frame.
    * @param videoFrame The video frame. See VideoFrame. The default value of the video frame data format obtained through this callback is as follows:
-   *  macOS: YUV 420
-   *  Windows: YUV 420
+   *  macOS: I420 or CVPixelBufferRef
+   *  Windows: YUV420
    *
    * @returns
    * When the video processing mode is ProcessModeReadOnly : true : Reserved for future use. false : Reserved for future use.
@@ -1144,7 +1182,7 @@ export enum MediaRecorderStreamType {
  */
 export enum RecorderState {
   /**
-   * -1: An error occurs during the recording. See RecorderErrorCode for the reason.
+   * -1: An error occurs during the recording. See RecorderReasonCode for the reason.
    */
   RecorderStateError = -1,
   /**
@@ -1160,27 +1198,27 @@ export enum RecorderState {
 /**
  * The reason for the state change.
  */
-export enum RecorderErrorCode {
+export enum RecorderReasonCode {
   /**
    * 0: No error.
    */
-  RecorderErrorNone = 0,
+  RecorderReasonNone = 0,
   /**
-   * 1: The SDK fails to write the recorded data to a file.
+   * @ignore
    */
-  RecorderErrorWriteFailed = 1,
+  RecorderReasonWriteFailed = 1,
   /**
-   * 2: The SDK does not detect any audio and video streams, or audio and video streams are interrupted for more than five seconds during recording.
+   * @ignore
    */
-  RecorderErrorNoStream = 2,
+  RecorderReasonNoStream = 2,
   /**
-   * 3: The recording duration exceeds the upper limit.
+   * @ignore
    */
-  RecorderErrorOverMaxDuration = 3,
+  RecorderReasonOverMaxDuration = 3,
   /**
-   * 4: The recording configuration changes.
+   * @ignore
    */
-  RecorderErrorConfigChanged = 4,
+  RecorderReasonConfigChanged = 4,
 }
 
 /**
@@ -1238,7 +1276,7 @@ export interface IMediaRecorderObserver {
     channelId: string,
     uid: number,
     state: RecorderState,
-    error: RecorderErrorCode
+    reason: RecorderReasonCode
   ): void;
 
   /**

package/ts/Private/AgoraMediaPlayerTypes.ts

@@ -1,4 +1,5 @@
 import './extension/AgoraMediaPlayerTypesExtension';
+
 /**
  * The playback state.
  */
@@ -70,81 +71,81 @@ export enum MediaPlayerState {
 }
 
 /**
- * Error codes of the media player.
+ * Reasons for the changes in the media player status.
  */
-export enum MediaPlayerError {
+export enum MediaPlayerReason {
   /**
    * 0: No error.
    */
-  PlayerErrorNone = 0,
+  PlayerReasonNone = 0,
   /**
    * -1: Invalid arguments.
    */
-  PlayerErrorInvalidArguments = -1,
+  PlayerReasonInvalidArguments = -1,
   /**
    * -2: Internal error.
    */
-  PlayerErrorInternal = -2,
+  PlayerReasonInternal = -2,
   /**
    * -3: No resource.
    */
-  PlayerErrorNoResource = -3,
+  PlayerReasonNoResource = -3,
   /**
    * -4: Invalid media resource.
    */
-  PlayerErrorInvalidMediaSource = -4,
+  PlayerReasonInvalidMediaSource = -4,
   /**
    * -5: The media stream type is unknown.
    */
-  PlayerErrorUnknownStreamType = -5,
+  PlayerReasonUnknownStreamType = -5,
   /**
    * -6: The object is not initialized.
    */
-  PlayerErrorObjNotInitialized = -6,
+  PlayerReasonObjNotInitialized = -6,
   /**
    * -7: The codec is not supported.
    */
-  PlayerErrorCodecNotSupported = -7,
+  PlayerReasonCodecNotSupported = -7,
   /**
    * -8: Invalid renderer.
    */
-  PlayerErrorVideoRenderFailed = -8,
+  PlayerReasonVideoRenderFailed = -8,
   /**
    * -9: An error with the internal state of the player occurs.
    */
-  PlayerErrorInvalidState = -9,
+  PlayerReasonInvalidState = -9,
   /**
    * -10: The URL of the media resource cannot be found.
    */
-  PlayerErrorUrlNotFound = -10,
+  PlayerReasonUrlNotFound = -10,
   /**
    * -11: Invalid connection between the player and the Agora Server.
    */
-  PlayerErrorInvalidConnectionState = -11,
+  PlayerReasonInvalidConnectionState = -11,
   /**
    * -12: The playback buffer is insufficient.
    */
-  PlayerErrorSrcBufferUnderflow = -12,
+  PlayerReasonSrcBufferUnderflow = -12,
   /**
    * -13: The playback is interrupted.
    */
-  PlayerErrorInterrupted = -13,
+  PlayerReasonInterrupted = -13,
   /**
    * -14: The SDK does not support the method being called.
    */
-  PlayerErrorNotSupported = -14,
+  PlayerReasonNotSupported = -14,
   /**
    * @ignore
    */
-  PlayerErrorTokenExpired = -15,
+  PlayerReasonTokenExpired = -15,
   /**
    * @ignore
    */
-  PlayerErrorIpExpired = -16,
+  PlayerReasonIpExpired = -16,
   /**
    * -17: An unknown error.
    */
-  PlayerErrorUnknown = -17,
+  PlayerReasonUnknown = -17,
 }
 
 /**
@@ -365,22 +366,60 @@ export class CacheStatistics {
   downloadSize?: number;
 }
 
+/**
+ * The information of the media file being played.
+ */
+export class PlayerPlaybackStats {
+  /**
+   * The frame rate (fps) of the video.
+   */
+  videoFps?: number;
+  /**
+   * The bitrate (kbps) of the video.
+   */
+  videoBitrateInKbps?: number;
+  /**
+   * The bitrate (kbps) of the audio.
+   */
+  audioBitrateInKbps?: number;
+  /**
+   * The total bitrate (kbps) of the media stream.
+   */
+  totalBitrateInKbps?: number;
+}
+
 /**
  * Information related to the media player.
  */
 export class PlayerUpdatedInfo {
   /**
-   * The ID of a media player.
+   * @ignore
    */
-  playerId?: string;
+  internalPlayerUuid?: string;
   /**
    * The ID of a deivce.
    */
   deviceId?: string;
   /**
-   * The statistics about the media file being cached. If you call the openWithMediaSource method and set enableCache as true, the statistics about the media file being cached is updated every second after the media file is played. See CacheStatistics.
+   * Height (pixel) of the video.
    */
-  cacheStatistics?: CacheStatistics;
+  videoHeight?: number;
+  /**
+   * Width (pixel) of the video.
+   */
+  videoWidth?: number;
+  /**
+   * Audio sample rate (Hz).
+   */
+  audioSampleRate?: number;
+  /**
+   * The number of audio channels.
+   */
+  audioChannels?: number;
+  /**
+   * The number of bits per audio sample point.
+   */
+  audioBitsPerSample?: number;
 }
 
 /**
@@ -410,6 +449,10 @@ export class MediaSource {
    *  If you enable this function, the Media Player caches part of the media file being played on your local device, and you can play the cached media file without internet connection. The statistics about the media file being cached are updated every second after the media file is played. See CacheStatistics.
    */
   enableCache?: boolean;
+  /**
+   * Whether to allow the selection of different audio tracks when playing this media file: true : Allow to select different audio tracks. false : (Default) Do not allow to select different audio tracks. If you need to set different audio tracks for local playback and publishing to the channel, you need to set this parameter to true, and then call the selectMultiAudioTrack method to select the audio track.
+   */
+  enableMultiAudioTrack?: boolean;
   /**
    * Whether the media resource to be opened is a live stream or on-demand video distributed through Media Broadcast service: true : The media resource to be played is a live or on-demand video distributed through Media Broadcast service. false : (Default) The media resource is not a live stream or on-demand video distributed through Media Broadcast service. If you need to open a live stream or on-demand video distributed through Broadcast Streaming service, pass in the URL of the media resource to url, and set isAgoraSource as true; otherwise, you don't need to set the isAgoraSource parameter.
    */

package/ts/Private/IAgoraH265Transcoder.ts

@@ -0,0 +1,73 @@
+import './extension/IAgoraH265TranscoderExtension';
+
+/* enum_H265TranscodeResult */
+export enum H265TranscodeResult {
+  /* enum_H265TranscodeResult_H265TranscodeResultUnknown */
+  H265TranscodeResultUnknown = -1,
+  /* enum_H265TranscodeResult_H265TranscodeResultSuccess */
+  H265TranscodeResultSuccess = 0,
+  /* enum_H265TranscodeResult_H265TranscodeResultRequestInvalid */
+  H265TranscodeResultRequestInvalid = 1,
+  /* enum_H265TranscodeResult_H265TranscodeResultUnauthorized */
+  H265TranscodeResultUnauthorized = 2,
+  /* enum_H265TranscodeResult_H265TranscodeResultTokenExpired */
+  H265TranscodeResultTokenExpired = 3,
+  /* enum_H265TranscodeResult_H265TranscodeResultForbidden */
+  H265TranscodeResultForbidden = 4,
+  /* enum_H265TranscodeResult_H265TranscodeResultNotFound */
+  H265TranscodeResultNotFound = 5,
+  /* enum_H265TranscodeResult_H265TranscodeResultConflicted */
+  H265TranscodeResultConflicted = 6,
+  /* enum_H265TranscodeResult_H265TranscodeResultNotSupported */
+  H265TranscodeResultNotSupported = 7,
+  /* enum_H265TranscodeResult_H265TranscodeResultTooOften */
+  H265TranscodeResultTooOften = 8,
+  /* enum_H265TranscodeResult_H265TranscodeResultServerInternalError */
+  H265TranscodeResultServerInternalError = 9,
+  /* enum_H265TranscodeResult_H265TranscodeResultServiceUnavailable */
+  H265TranscodeResultServiceUnavailable = 10,
+}
+
+/* class_IH265TranscoderObserver */
+export interface IH265TranscoderObserver {
+  /* callback_IH265TranscoderObserver_onEnableTranscode */
+
+  onEnableTranscode?(result: H265TranscodeResult): void;
+  /* callback_IH265TranscoderObserver_onQueryChannel */
+
+  onQueryChannel?(
+    result: H265TranscodeResult,
+    originChannel: string,
+    transcodeChannel: string
+  ): void;
+  /* callback_IH265TranscoderObserver_onTriggerTranscode */
+
+  onTriggerTranscode?(result: H265TranscodeResult): void;
+}
+
+/* class_IH265Transcoder */
+export abstract class IH265Transcoder {
+  /* api_IH265Transcoder_enableTranscode */
+
+  abstract enableTranscode(token: string, channel: string, uid: number): number;
+  /* api_IH265Transcoder_queryChannel */
+
+  abstract queryChannel(token: string, channel: string, uid: number): number;
+  /* api_IH265Transcoder_triggerTranscode */
+
+  abstract triggerTranscode(
+    token: string,
+    channel: string,
+    uid: number
+  ): number;
+  /* api_IH265Transcoder_registerTranscoderObserver */
+
+  abstract registerTranscoderObserver(
+    observer: IH265TranscoderObserver
+  ): number;
+  /* api_IH265Transcoder_unregisterTranscoderObserver */
+
+  abstract unregisterTranscoderObserver(
+    observer: IH265TranscoderObserver
+  ): number;
+}

package/ts/Private/IAgoraLog.ts

@@ -1,4 +1,5 @@
 import './extension/IAgoraLogExtension';
+
 /**
  * The output log level of the SDK.
  */

package/ts/Private/IAgoraMediaEngine.ts

@@ -113,7 +113,7 @@ export abstract class IMediaEngine {
   /**
    * Pulls the remote audio data.
    *
-   * Before calling this method, you need to call setExternalAudioSink to notify the app to enable and set the external rendering. After a successful method call, the app pulls the decoded and mixed audio data for playback.
+   * Before calling this method, you need to call setExternalAudioSink to notify the app to enable and set the external rendering. After a successful call of this method, the app pulls the decoded and mixed audio data for playback.
    *  This method only supports pulling data from custom audio source. If you need to pull the data captured by the SDK, do not call this method.
    *  Call this method after joining a channel.
    *  Once you enable the external audio sink, the app will not retrieve any audio data from the onPlaybackAudioFrame callback.
@@ -174,10 +174,10 @@ export abstract class IMediaEngine {
   /**
    * Creates a custom audio track.
    *
-   * To publish a custom audio source to multiple channels, see the following steps:
+   * Ensure that you call this method before joining a channel. To publish a custom audio source, see the following steps:
    *  Call this method to create a custom audio track and get the audio track ID.
-   *  In ChannelMediaOptions of each channel, set publishCustomAduioTrackId to the audio track ID that you want to publish, and set publishCustomAudioTrack to true.
-   *  If you call pushAudioFrame, and specify trackId as the audio track ID set in step 2, you can publish the corresponding custom audio source in multiple channels.
+   *  Call joinChannel to join the channel. In ChannelMediaOptions, set publishCustomAduioTrackId to the audio track ID that you want to publish, and set publishCustomAudioTrack to true.
+   *  Call pushAudioFrame and specify trackId as the audio track ID set in step 2. You can then publish the corresponding custom audio source in the channel.
    *
    * @param trackType The type of the custom audio track. See AudioTrackType. If AudioTrackDirect is specified for this parameter, you must set publishMicrophoneTrack to false in ChannelMediaOptions when calling joinChannel to join the channel; otherwise, joining the channel fails and returns the error code -2.
    * @param config The configuration of the custom audio track. See AudioTrackConfig.
@@ -232,9 +232,14 @@ export abstract class IMediaEngine {
   ): number;
 
   /**
-   * Pushes the external raw video frame to the SDK.
-   *
-   * If you call createCustomVideoTrack method to get the video track ID, set the customVideoTrackId parameter to the video track ID you want to publish in the ChannelMediaOptions of each channel, and set the publishCustomVideoTrack parameter to true, you can call this method to push the unencoded external video frame to the SDK.
+   * Pushes the external raw video frame to the SDK through video tracks.
+   *
+   * To publish a custom video source, see the following steps:
+   *  Call createCustomVideoTrack to create a video track and get the video track ID.
+   *  Call joinChannel to join the channel. In ChannelMediaOptions, set customVideoTrackId to the video track ID that you want to publish, and set publishCustomVideoTrack to true.
+   *  Call this method and specify videoTrackId as the video track ID set in step 2. You can then publish the corresponding custom video source in the channel. After calling this method, even if you stop pushing external video frames to the SDK, the custom video stream will still be counted as the video duration usage and incur charges. Agora recommends that you take appropriate measures based on the actual situation to avoid such video billing.
+   *  If you no longer need to capture external video data, you can call destroyCustomVideoTrack to destroy the custom video track.
+   *  If you only want to use the external video data for local preview and not publish it in the channel, you can call muteLocalVideoStream to cancel sending video stream or call updateChannelMediaOptions to set publishCustomVideoTrack to false.
    *
    * @param frame The external raw video frame to be pushed. See ExternalVideoFrame.
    * @param videoTrackId The video track ID returned by calling the createCustomVideoTrack method. The default value is 0.