feat: support 4.21.0

.github/workflows/mirror.yml

@@ -14,7 +14,7 @@ jobs:
     if: github.actor != 'dependabot[bot]'
     steps:
       - name: Mirror repo
-        uses: Yikun/hub-mirror-action@v1.3
+        uses: Yikun/hub-mirror-action@v1.4
         with:
           src: github/AgoraIO-Extensions
           dst: gitee/agoraio-community

.vscode/settings.json

@@ -3,8 +3,8 @@
   "editor.formatOnSave": true,
   "editor.defaultFormatter": "esbenp.prettier-vscode",
   "editor.codeActionsOnSave": {
-    "source.fixAll": true,
-    "source.addMissingImports": true
+    "source.fixAll": "explicit",
+    "source.addMissingImports": "explicit"
   },
   "prettier.enable": true,
   "cSpell.enabled": true,

examples/basic/src/components/Room.tsx

@@ -20,6 +20,7 @@ interface RoomProps {
   renderRemoteUsers?: () => ReactNode;
   micOn: boolean;
   cameraOn: boolean;
+  showUserInfo?: boolean;
 }
 
 export function Room({
@@ -28,6 +29,7 @@ export function Room({
   renderAction,
   renderLocalUser,
   renderRemoteUsers,
+  showUserInfo = true,
 }: RoomProps) {
   const isConnected = useIsConnected();
 
@@ -46,10 +48,12 @@ export function Room({
   return (
     <>
       {renderAction ? renderAction() : undefined}
-      <UsersInfo
-        published={publishedUsers.length + (selfPublished ? 1 : 0)}
-        total={remoteUsers.length + 1}
-      />
+      {showUserInfo && (
+        <UsersInfo
+          published={publishedUsers.length + (selfPublished ? 1 : 0)}
+          total={remoteUsers.length + 1}
+        />
+      )}
       <AutoLayout>
         {isConnected &&
           (renderLocalUser ? (

examples/basic/src/pages/component/LocalVideoTrack/index.tsx

@@ -28,6 +28,7 @@ export const LocalVideoTrackComponent = () => {
           play={cameraOn}
           style={{ width: "300px", height: "300px" }}
           track={localCameraTrack}
+          videoPlayerConfig={{ mirror: true, fit: "contain" }}
         />
       </div>
       <MediaControl

examples/basic/src/pages/hook/index.ts

@@ -1,5 +1,6 @@
 import UseAutoPlayAudioTrack from "./useAutoPlayAudioTrack";
 import UseAutoPlayVideoTrack from "./useAutoPlayVideoTrack";
+import UseClientEvent from "./useClientEvent";
 import UseConnectionState from "./useConnectionState";
 import UseCurrentUID from "./useCurrentUID";
 import UseIsConnected from "./useIsConnected";
@@ -49,6 +50,10 @@ const Hooks = [
     label: "useLocalScreenTrack",
     component: UseLocalScreenTrack,
   },
+  {
+    label: "UseClientEvent",
+    component: UseClientEvent,
+  },
 ];
 
 export { Hooks };

examples/basic/src/pages/hook/useClientEvent/index.tsx

@@ -0,0 +1,86 @@
+import type { ConnectionDisconnectedReason, ConnectionState } from "agora-rtc-react";
+import { useClientEvent, useJoin, useRTCClient } from "agora-rtc-react";
+import { List, Typography } from "antd";
+import { useState } from "react";
+
+import { Container, MediaControl, Room } from "../../../components";
+import { appConfig } from "../../../utils";
+
+const { Title } = Typography;
+
+export const UseClientEvent = () => {
+  const [calling, setCalling] = useState(false);
+  const [logSink, setLogSink] = useState<
+    Array<{
+      eventName: string;
+      value: string;
+    }>
+  >([]);
+  const client = useRTCClient();
+  useClientEvent(
+    client,
+    "connection-state-change",
+    (
+      curState: ConnectionState,
+      revState: ConnectionState,
+      reason?: ConnectionDisconnectedReason,
+    ) => {
+      console.log(
+        `connection-state-change,curState: ${curState},revState: ${revState},reason: ${reason}`,
+      );
+      setLogSink(logs =>
+        logs.concat({
+          eventName: "connection-state-change",
+          value: `curState: ${curState},revState: ${revState},reason: ${reason}`,
+        }),
+      );
+    },
+  );
+
+  //local
+  useJoin(
+    {
+      appid: appConfig.appId,
+      channel: appConfig.channel,
+      token: appConfig.token,
+    },
+    calling,
+  );
+  const renderLocalUser = () => {
+    return <></>;
+  };
+
+  return (
+    <Container>
+      <div className="h-screen p-3">
+        <Title>UseClientEvent</Title>
+        <List
+          bordered
+          dataSource={logSink}
+          renderItem={item => (
+            <List.Item>
+              <Typography.Text mark>[{item.eventName}]</Typography.Text> {item.value}
+            </List.Item>
+          )}
+          style={{ height: "300px", overflow: "auto" }}
+        />
+      </div>
+      {calling && (
+        <Room
+          cameraOn={false}
+          micOn={false}
+          renderLocalUser={renderLocalUser}
+          showUserInfo={false}
+        />
+      )}
+      <MediaControl
+        calling={calling}
+        setCalling={() => {
+          setCalling(a => !a);
+        }}
+      />
+    </Container>
+  );
+};
+
+export default UseClientEvent;

package.json

@@ -71,12 +71,12 @@
     "@types/react": "^18.2.14",
     "@types/react-dom": "^18.2.7",
     "@types/testing-library__jest-dom": "^5.14.8",
-    "agora-rtc-sdk-ng": "4.20.0",
+    "agora-rtc-sdk-ng": "4.21.0",
     "agora-rtc-sdk-ng-fake": "github:AgoraIO-Extensions/agora-rtc-sdk-ng-fake#semver:^1.0.4",
     "react-test-renderer": "^18.2.0",
     "storybook": "^7.0.26",
     "tsup": "^7.1.0",
-    "typedoc": "^0.24.8",
+    "typedoc": "^0.25.13",
     "typescript": "^5.1.6"
   },
   "lint-staged": {

packages/agora-rtc-react-ui/src/components/CameraVideoTrack.tsx

@@ -1,4 +1,4 @@
-import type { LocalVideoTrackProps } from "agora-rtc-react";
+import type { LocalVideoTrackProps, VideoPlayerConfig } from "agora-rtc-react";
 import type { ICameraVideoTrack } from "agora-rtc-react";
 import { LocalVideoTrack } from "agora-rtc-react";
 import { useAwaited } from "agora-rtc-react/src/hooks/tools";
@@ -14,6 +14,11 @@ export interface CameraVideoTrackProps extends LocalVideoTrackProps {
    * Device ID, which can be retrieved by calling `getDevices()`.
    */
   readonly deviceId?: string;
+
+  /**
+   * Playback configurations for a video track. Set the playback configurations for a video track when calling [ILocalVideoTrack.play]{@link ILocalVideoTrack.play}.
+   */
+  readonly videoPlayerConfig?: VideoPlayerConfig;
 }
 
 /**
@@ -24,7 +29,12 @@ export interface CameraVideoTrackProps extends LocalVideoTrackProps {
  * return <CameraVideoTrack track={track} play />
  * ```
  */
-export function CameraVideoTrack({ track: maybeTrack, deviceId, ...props }: CameraVideoTrackProps) {
+export function CameraVideoTrack({
+  track: maybeTrack,
+  deviceId,
+  videoPlayerConfig,
+  ...props
+}: CameraVideoTrackProps) {
   const track = useAwaited(maybeTrack);
 
   useEffect(() => {
@@ -33,5 +43,5 @@ export function CameraVideoTrack({ track: maybeTrack, deviceId, ...props }: Came
     }
   }, [deviceId, track]);
 
-  return <LocalVideoTrack track={maybeTrack} {...props} />;
+  return <LocalVideoTrack track={maybeTrack} videoPlayerConfig={videoPlayerConfig} {...props} />;
 }

packages/agora-rtc-react-ui/src/components/LocalMicrophoneAndCameraUser.tsx

@@ -1,4 +1,4 @@
-import type { ICameraVideoTrack, IMicrophoneAudioTrack } from "agora-rtc-react";
+import type { ICameraVideoTrack, IMicrophoneAudioTrack, VideoPlayerConfig } from "agora-rtc-react";
 import {
   FloatBoxStyle,
   VideoTrackWrapperStyle,
@@ -56,6 +56,10 @@ export interface LocalMicrophoneAndCameraUserProps extends HTMLProps<HTMLDivElem
    * Children is rendered on top of the video canvas.
    */
   readonly children?: ReactNode;
+  /**
+   * Playback configurations for a video track. Set the playback configurations for a video track when calling [ILocalVideoTrack.play]{@link ILocalVideoTrack.play}.
+   */
+  readonly videoPlayerConfig?: VideoPlayerConfig;
 }
 
 /**
@@ -73,6 +77,7 @@ export function LocalMicrophoneAndCameraUser({
   volume,
   cover,
   children,
+  videoPlayerConfig,
   style,
   ...props
 }: LocalMicrophoneAndCameraUserProps) {
@@ -86,6 +91,7 @@ export function LocalMicrophoneAndCameraUser({
         disabled={!cameraOn}
         play={playVideo}
         track={videoTrack}
+        videoPlayerConfig={videoPlayerConfig}
       />
       <MicrophoneAudioTrack
         deviceId={micDeviceId}

packages/agora-rtc-react-ui/src/components/RemoteVideoPlayer.tsx

@@ -1,4 +1,4 @@
-import type { IAgoraRTCClient, IRemoteVideoTrack } from "agora-rtc-react";
+import type { IAgoraRTCClient, IRemoteVideoTrack, VideoPlayerConfig } from "agora-rtc-react";
 import { RemoteVideoTrack, useRTCClient } from "agora-rtc-react";
 import {
   FloatBoxStyle,
@@ -29,6 +29,10 @@ export interface RemoteVideoPlayerProps extends HTMLProps<HTMLDivElement> {
    * client instance
    */
   readonly client?: IAgoraRTCClient | null;
+  /**
+   * Playback configurations for a video track. Set the playback configurations for a video track when calling [ILocalVideoTrack.play]{@link ILocalVideoTrack.play}.
+   */
+  readonly videoPlayerConfig?: VideoPlayerConfig;
 }
 
 /**
@@ -42,6 +46,7 @@ export function RemoteVideoPlayer({
   client,
   style,
   children,
+  videoPlayerConfig,
   ...props
 }: RemoteVideoPlayerProps) {
   const mergedStyle = useMergedStyle(VideoTrackWrapperStyle, style);
@@ -52,7 +57,7 @@ export function RemoteVideoPlayer({
   playVideo = playVideo ?? hasVideo;
   return (
     <div {...props} style={mergedStyle}>
-      <RemoteVideoTrack play={playVideo} track={track} />
+      <RemoteVideoTrack play={playVideo} track={track} videoPlayerConfig={videoPlayerConfig} />
       {cover && !playVideo && <UserCover cover={cover} />}
       <div style={FloatBoxStyle}>{children}</div>
     </div>

packages/agora-rtc-react-ui/test/CameraVideoTrack.test.tsx

@@ -1,6 +1,7 @@
 import { composeStories } from "@storybook/react";
 import { render } from "@testing-library/react";
-import type { ICameraVideoTrack } from "agora-rtc-react";
+import type { ICameraVideoTrack, VideoPlayerConfig } from "agora-rtc-react";
+import * as fun from "agora-rtc-react/src/components/TrackBoundary";
 import { useAwaited } from "agora-rtc-react/src/hooks/tools";
 import type { Mock } from "vitest";
 import { describe, expect, test, vi } from "vitest";
@@ -32,6 +33,19 @@ describe("CameraVideoTrack component", () => {
     expect(mockTrack.setDevice).toHaveBeenCalledWith("123");
     vi.clearAllMocks();
   });
+
+  test("config videoPlayerConfig on CameraVideoTrack", () => {
+    vi.spyOn(fun, "useAutoPlayVideoTrack");
+    const videoPlayerConfig: VideoPlayerConfig = { mirror: false, fit: "cover" };
+    render(<CameraVideoTrack play track={mockTrack} videoPlayerConfig={videoPlayerConfig} />);
+    expect(fun.useAutoPlayVideoTrack).toBeCalledWith(
+      undefined,
+      true,
+      videoPlayerConfig,
+      expect.anything(),
+    );
+    vi.clearAllMocks();
+  });
 });
 
 describe("CameraVideoTrack component stories", () => {

packages/agora-rtc-react-ui/test/LocalMicrophoneAndCameraUser.test.tsx

@@ -1,6 +1,8 @@
 import { composeStories } from "@storybook/react";
 import { render } from "@testing-library/react";
+import * as fun from "agora-rtc-react/src/components/TrackBoundary";
 import * as clientHook from "agora-rtc-react/src/hooks/tools";
+import type { VideoPlayerConfig } from "agora-rtc-sdk-ng";
 import { FakeMicrophoneAudioTrack } from "agora-rtc-sdk-ng-fake";
 import { describe, expect, test, vi } from "vitest";
 
@@ -35,6 +37,19 @@ describe("LocalMicrophoneAndCameraUser component", () => {
     const { container } = render(<LocalMicrophoneAndCameraUser cameraOn cover={cover} />);
     expect(container.querySelector("img")?.getAttribute("src")).toBeUndefined();
   });
+
+  test("config videoPlayerConfig on LocalMicrophoneAndCameraUser", () => {
+    vi.spyOn(fun, "useAutoPlayVideoTrack");
+    const videoPlayerConfig: VideoPlayerConfig = { mirror: false, fit: "cover" };
+    render(<LocalMicrophoneAndCameraUser videoPlayerConfig={videoPlayerConfig} />);
+    expect(fun.useAutoPlayVideoTrack).toBeCalledWith(
+      expect.anything(),
+      false,
+      videoPlayerConfig,
+      expect.anything(),
+    );
+    vi.clearAllMocks();
+  });
 });
 
 describe("LocalMicrophoneAndCameraUser component stories", () => {

packages/agora-rtc-react-ui/test/RemoteVideoPlayer.test.tsx

@@ -1,6 +1,8 @@
 import { composeStories } from "@storybook/react";
 import { render } from "@testing-library/react";
-import { FakeRTCClient } from "agora-rtc-sdk-ng-fake";
+import * as fun from "agora-rtc-react/src/components/TrackBoundary";
+import type { VideoPlayerConfig } from "agora-rtc-sdk-ng";
+import { FakeRTCClient, FakeRemoteVideoTrack } from "agora-rtc-sdk-ng-fake";
 import { describe, expect, test, vi } from "vitest";
 
 import { RemoteVideoPlayer } from "../src/components";
@@ -19,6 +21,28 @@ describe("RemoteVideoPlayer component", () => {
     vi.clearAllMocks();
     vi.resetAllMocks();
   });
+
+  test("config videoPlayerConfig on RemoteVideoPlayer", () => {
+    const client = FakeRTCClient.create();
+    const track = FakeRemoteVideoTrack.create();
+    vi.spyOn(fun, "useAutoPlayVideoTrack");
+    const videoPlayerConfig: VideoPlayerConfig = { mirror: false, fit: "cover" };
+    render(
+      <RemoteVideoPlayer
+        client={client}
+        playVideo
+        track={track}
+        videoPlayerConfig={videoPlayerConfig}
+      />,
+    );
+    expect(fun.useAutoPlayVideoTrack).toBeCalledWith(
+      track,
+      true,
+      videoPlayerConfig,
+      expect.anything(),
+    );
+    vi.clearAllMocks();
+  });
 });
 
 describe("RemoteVideoPlayer component stories", () => {

packages/agora-rtc-react-ui/test/setup.tsx

@@ -1,11 +1,8 @@
 import "@testing-library/jest-dom";
-import matchers from "@testing-library/jest-dom/matchers";
 import type { ReactNode } from "react";
-import { expect, vi } from "vitest";
+import { vi } from "vitest";
 import "vitest-canvas-mock";
 
-expect.extend(matchers);
-
 /**
  * started [email protected], need mock RTCPeerConnection.
  * RTCPeerConnection does not implement global