@tencent-rtc/mcp 1.3.9 → 1.4.0

package/resource/doc/livekit/preset/live/vue/components/stream-mixer.md

@@ -0,0 +1,215 @@
+This document provides a detailed introduction to **Video Source Editing Canvas (StreamMixer)**. You can refer to the sample code in this document to integrate our pre-developed components into your existing project, or customize the style and layout according to your needs by following the component customization section in the document.
+
+## Core Features
+| **Feature Category** | **Specific Capabilities** |
+| --- | --- |
+| **Real-time preview** | Provide a WYSIWYG editing experience where hosts can intuitively see the mixed stream effect, supporting operations like rotation, move, scale, mirror, and hierarchy adjustment. |
+| **Template layout** | Built-in multiple live streaming room layout templates support automatic adaptation to different microphone-connected scenarios, including nine-grid, 1v6, floating window, helping you quickly switch between different live stream styles. |
+| **User status management** | Intelligent detection of co-broadcasting users joining and exiting, automatic layout adjustment with no manual intervention required, ensuring smooth live streaming and providing seamless experience for hosts. |
+| **Customizable UI** | To meet diverse business scenarios, the video source editing canvas provides component UI customization slots, enabling full control over co-broadcasting users' video stream areas. Rewrite their UI display, flexibly define avatars, nicknames, status, and other information, and easily create a unique visual experience that matches your UI style. |
+
+## Component Integration
+
+### Step 1: Configuring the Environment and Activating the Service
+
+Before quick integration, you need to refer to Preparations, meet related environment configuration and activate corresponding service.
+
+### Step 2: Installing Dependencies
+
+【npm】
+``` bash
+npm install tuikit-atomicx-vue3@latest @tencentcloud/uikit-base-component-vue3 --save
+```
+
+【pnpm】
+``` bash
+pnpm add tuikit-atomicx-vue3@latest @tencentcloud/uikit-base-component-vue3
+```
+
+【yarn】
+``` bash
+yarn add tuikit-atomicx-vue3@latest @tencentcloud/uikit-base-component-vue3
+```
+
+### Step 3: Joining Live Room
+
+Introduce and use the **Video Source Editing Canvas** in your project. You can copy the following example code directly to your project and add the corresponding live streaming room.
+``` typescript
+<template>
+  <UIKitProvider theme="dark" language="zh-CN">
+    <div class="app">
+      <LiveScenePanel class="live-scene-panel" />
+      <StreamMixer class="live-stream-mixer" />
+    </div>
+  </UIKitProvider>
+</template>
+
+<script setup lang="ts">
+import { onMounted } from 'vue';
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
+import { LiveScenePanel, StreamMixer, useLoginState, useLiveState, useCoGuestState } from 'tuikit-atomicx-vue3';
+
+const { login } = useLoginState();
+const { createLive } = useLiveState();
+const { sendCoGuestRequest } = useCoGuestState();
+
+async function initLogin() {
+  try {
+    await login({
+      sdkAppId: 0,        // SDKAppID, see Step 1 to get
+      userId: '',         // UserID, see Step 1 to get
+      userSig: '',        // userSig, see Step 1 to get
+    });
+  } catch (error) {
+    console.error('login error:', error);
+  }
+}
+
+onMounted(async () => {
+  await initLogin();
+  // After the anchor creates a live streaming room
+  // StreamMixer automatically pushes the local composite video stream to the room
+  await createLive({
+    liveId: `live_${loginUserInfo.value.userId}`,
+    liveName: `${loginUserInfo.value?.userName}'s live streaming room`,
+  });
+  // The client can join the live room by calling the method and switch on/off mic as needed.
+  // After the audience succeeds in going on mic, StreamMixer starts TRTC streaming automatically
+  await sendCoGuestRequest();
+});
+</script>
+
+<style>.app {width: 100vw; height: 100vh; display: flex; justify-content: center; align-items: center}</style>
+```
+``` bash
+npm run dev
+```
+
+## Component Customization
+
+**Video Source Editing Canvas** provides a flexible component customization slot that supports you in adjusting the style and layout of elements such as avatar, nickname, and status based on your own needs. It also supports customizing the video stream area for co-streaming UI. Below are slot usage examples.
+
+### Component Slot
+| **Name** | **Parameter** | **Description** |
+| --- | --- | --- |
+| seatViewUI | seatInfo: SeatInfo | Display UI for custom seat |
+
+``` java
+// Example of using the seatViewUI slot
+<StreamMixer>
+  <CustomSeatViewUI #seatViewUI></CustomSeatViewUI>
+</StreamMixer>
+```
+1. `SeatInfo` defines the basic info and status of each seat in a live streaming room:
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `index` | `number` | Required | The seat index number starts incrementing from 0, used to identify the seat position in the room. |
+| `isLocked` | `boolean` | Required | The seat lock status, `true` means the seat is locked and other users are unable to enter; `false` means the seat is open. |
+| `userInfo` | `SeatUserInfo` | optional | The user information of the current occupant in this seat. If the seat is empty, it is `undefined`. |
+| `region` | `RegionInfo` | optional | The display region information of the seat in the video canvas, for multiple streams video layout. |
+
+   ``` typescript
+   interface SeatInfo {
+     index: number;           // Seat index
+     isLocked: boolean;       // Whether the seat is locked
+     userInfo?: SeatUserInfo; // User information on the seat (optional)
+     region?: RegionInfo;     // Region information of the seat in the canvas (optional)
+   }
+   ```
+2. `SeatUserInfo` defines the user details of each seat in a live streaming room:
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `roomId` | `string` | Required | The current unique identifier of the live streaming room, used to distinguish different live streaming rooms |
+| `userId` | `string` | Required | User's Unique Identifier, must be unique in the entire system |
+| `userName` | `string` | Required | The name displayed for users in live streams supports Chinese, English, and other characters. |
+| `avatarUrl` | `string` | Required | The complete URL of the user profile photo supports HTTPS protocol. |
+| `microphoneStatus` | `DeviceStatus` | Required | Microphone status |
+| `microphoneStatusReason` | `DeviceStatusReason` | Required | Reasons for microphone status changes, to distinguish between user proactive operation and administrator operation |
+| `cameraStatus` | `DeviceStatus` | Required | Camera status |
+| `cameraStatusReason` | `DeviceStatusReason` | Required | Reasons for camera status changes, to distinguish between user proactive operation and administrator operation |
+
+   ``` typescript
+   interface SeatUserInfo {
+     roomId: string;                    // Live streaming room ID
+     userId: string;                    // User ID
+     userName: string;                  // User Display Name
+     avatarUrl: string;                 // User Avatar URL
+     microphoneStatus: DeviceStatus;    // mic status
+     allowOpenMicrophone: boolean;      // whether to allow turning on microphone
+     cameraStatus: DeviceStatus;        // camera status
+     allowOpenCamera: boolean;          // whether to allow turning on camera
+   }
+
+   export type SeatUserInfo = {
+     liveId: string;                                // Live streaming room ID
+     userId: string;                                // User ID
+     userName: string;                              // User Display Name
+     avatarUrl: string;                             // User Avatar URL
+     microphoneStatus: DeviceStatus;                // mic status
+     microphoneStatusReason: DeviceStatusReason;    // reason for change
+     cameraStatus: DeviceStatus;                    // camera status
+     cameraStatusReason: DeviceStatusReason;        // reason for change
+   }
+   ```
+3. `RegionInfo` defines the display area and hierarchical information of the seat in the video canvas:
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `x` | `number` | Required | X-coordinate of the region's top-left corner relative to the canvas (pixel value) |
+| `y` | `number` | Required | Y-coordinate of the region's top-left corner relative to the canvas (pixel value) |
+| `w` | `number` | Required | Width of the region (pixel value), must be greater than 0 |
+| `h` | `number` | Required | Height of the region (pixel value), must be greater than 0 |
+| `zOrder` | `number` | Required | Z-order, the larger the value, the more positioned towards the front for processing overlap display priority |
+
+   ``` typescript
+   interface RegionInfo {
+     x: number;      // Top-left X-axis coordinate of the region
+     y: number;      // Top-left Y-axis coordinate of the region
+     w: number;      // Region width
+     h: number;      // Region height
+     zOrder: number; // Z-order
+   }
+   ```
+
+### Custom Slot Example
+
+To help you better experience and understand the customized capability of the seatViewUI slot in the video source editing Canvas component, we provide a **live streaming and mic connection scenario** example for your reference. You can refer to the above **step 3** to incrementally copy the following code into your project to achieve a similar effect.
+``` typescript
+<template>
+  <StreamMixer>
+    <template #seatViewUI="{ userInfo }">
+      <div
+        class="live-stream-view"
+        :class="{ 'is-anchor': isAnchor(userInfo), 'is-guest': !isAnchor(userInfo) }"
+      >
+        User information overlay
+        <div class="user-overlay">
+          <div class="user-badge" :class="{ 'anchor-badge': isAnchor(userInfo) }">
+            {{ isAnchor(userInfo) ? 'Anchor' : 'Audience' }}
+          </div>
+          <div class="user-name">{{ userInfo.userName }}</div>
+          <div class="device-status">
+            <span :class="['mic', userInfo.microphoneStatus]"></span>
+            <span :class="['camera', userInfo.cameraStatus]"></span>
+          </div>
+        </div>
+      </div>
+    </template>
+  </StreamMixer>
+</template>
+
+<script setup lang="ts">
+import { StreamMixer } from 'tuikit-atomicx-vue3';
+import type { SeatUserInfo } from 'tuikit-atomicx-vue3';
+
+// Determine whether it is an anchor (based on business logic)
+const isAnchor = (userInfo: SeatUserInfo) => {
+  // Here access can be judged based on uid and role
+  return userInfo.userId.includes('anchor') || userInfo.userName.includes('Anchor');
+};
+</script>
+
+<style scoped>.live-stream-view{position:relative;width:100%;height:100%;border-radius:8px;overflow:hidden}.live-stream-view.is-anchor{border:3px solid #ff6b35;box-shadow:0 0 20px rgba(255,107,53,.3)}.live-stream-view.is-guest{border:1px solid #ddd}.video-area{width:100%;height:100%;background:#000}.user-overlay{position:absolute;bottom:0;left:0;right:0;background:linear-gradient(transparent,rgba(0,0,0,.8));padding:10px;color:#fff}.user-badge{display:inline-block;padding:2px 8px;border-radius:10px;font-size:12px;margin-bottom:5px;background:#666}.anchor-badge{background:#ff6b35;color:#fff}.user-name{font-weight:700;margin-bottom:5px}.device-status span{margin-right:5px;opacity:.8}.device-status .camera.Off,.device-status .mic.Off{opacity:.3}</style>
+```

package/resource/doc/livekit/preset/live/vue/faq.md

@@ -0,0 +1 @@
+

package/resource/doc/livekit/preset/live/vue/live-list-integration.md

@@ -0,0 +1,241 @@
+## Overview
+
+This guide introduces the **Live Stream List page** in the TUILiveKit Demo. Use this documentation to quickly integrate our ready-made Live Stream List page into your project, or customize its appearance, layout, and features to fit your needs.
+
+## Quick Experience
+
+Start a live stream instantly using the [Online Hosting Site](https://web.sdk.qcloud.com/trtc/livekit/pusher/index.html), and view your Live Stream List from your account on the [Online Viewing Site](https://web.sdk.qcloud.com/trtc/livekit/player/index.html).
+
+## Quick Integration
+
+### Step 1: Environment Setup and Activate the Service
+
+Before you begin, follow the Preparation guide to integrate required components and enable login functionality.
+
+### Step 2: Install Dependencies
+
+Install the necessary dependencies using one of the following package managers:
+
+【npm】
+``` bash
+npm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 --save
+```
+
+【pnpm】
+``` bash
+pnpm add tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3
+```
+
+【yarn】
+``` bash
+yarn add tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3
+```
+
+### Step 3: Integrate Live Stream List Page
+
+Create a **live-list.vue** file in your project and add the following code to embed the **Live Stream List page**.
+
+> **Note：**
+>
+
+> You can copy the code below directly into your project, or check the [Live Stream List](https://github.com/Tencent-RTC/TUILiveKit/blob/main/Web/web-vite-vue3/src/TUILiveKit/LiveListView.vue) for the full source code.
+>
+
+``` typescript
+<template>
+  <UIKitProvider theme="dark">
+    <div class="container">
+      <header class="header">
+        <h1 class="title">Online Live</h1>
+      </header>
+      <main class="main">
+        <LiveList />
+      </main>
+    </div>
+  </UIKitProvider>
+</template>
+
+<script setup lang="ts">
+import { onMounted } from 'vue';
+import { LiveList, useLoginState } from 'tuikit-atomicx-vue3';
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
+
+const { login } = useLoginState();
+
+async function initLogin() {
+  try {
+    await login({
+      sdkAppId: 0,        // SDKAppID, see Step 1 for details
+      userId: '',         // UserID, see Step 1 for details
+      userSig: '',        // userSig, see Step 1 for details
+    });
+  } catch (error) {
+    console.error('Login failed:', error);
+  }
+}
+
+onMounted(async () => {
+  await initLogin();
+});
+</script>
+
+<style scoped>:global(*),:global(::after),:global(::before){box-sizing:border-box;margin:0}.container{display:flex;flex-direction:column;height:100vh;width:100vw;background:var(--bg-color-default)}.header{display:flex;align-items:center;flex-shrink:0}.title{margin:0;font-size:16px;font-weight:600;color:var(--text-color-primary);letter-spacing:-.5px}.main{flex:1;padding:24px;overflow-y:auto;min-height:0}</style>
+```
+
+> **注意：**
+>
+
+> To enable navigation from the Live Stream List to a specific live room, see the Specify Live Room section below.
+>
+
+## Start the Project
+
+### Launch Live Stream List Page
+
+After running the following command, open your browser and visit your local address to access the Live Stream List page.
+
+> **Tip：**
+>
+
+> Once the command completes, enter your local address in the browser (for example, `http://localhost:5173/live-list`; your port number may differ based on your project setup) to view the Live Stream List page.
+>
+
+``` bash
+npm run dev
+```
+
+### Specify Live Room
+
+To enable navigation from the Live Stream List (or homepage) to the viewing page, set up Vue Router. Create a `router` folder inside your project's `src` directory and add an `index.ts` file. Then, import and register the router in your main file (such as **main.ts** or **index.ts**). For reference, see the [GitHub code example](https://github.com/Tencent-RTC/TUILiveKit/blob/main/Web/web-vite-vue3/src/main.ts).
+
+#### Step 1: Configure Page Routing
+
+Set up Vue Router to map `live-list.vue` to the Live Stream List page.
+
+> **Note：**
+>
+> - If your project already has a `src/router/index.ts` file, merge the following code into your existing file.
+> - If you haven't set up routing, create a new `src/router/index.ts` file and add the configuration below.
+
+``` typescript
+import { createRouter, createWebHistory } from 'vue-router';
+
+const routes = [
+  {
+    // Live Stream List page; update the path below to match your project structure
+    path: '/live-list',
+    component: () => import('../live-list.vue'),
+  },
+  // To enable navigation from the Live Stream List cover to the corresponding live room, configure the viewing page route as shown below
+  {
+    // Route to the viewing page; update the path below to match your project structure
+    path: '/live-player',
+    component: () => import('../live-player.vue'),
+  },
+];
+
+const router = createRouter({
+  history: createWebHistory(),
+  routes,
+});
+export default router;
+```
+
+#### Step 2: Configure src/main.ts
+
+Add the router and localization setup to your project's entry file, src/main.ts:
+``` java
+// src/main.ts
+import { createApp } from 'vue';
+import App from './App.vue';
+import router from './router';
+
+const app = createApp(App);
+app.use(router);
+app.mount('#app');
+```
+
+#### Step 3: Configure live-list File
+
+Add the following code to your **live-list.vue** file to enable navigation from the Live Stream List to the viewing page.
+``` typescript
+// live-list.vue (can be incrementally added to your code)
+<template>
+  <UIKitProvider>
+     <!-- Refer to Step 3 in Quick Integration above -->
+     <LiveList @live-room-click="handleLiveRoomClick" />
+  </UIKitProvider>
+</template>
+
+<script setup lang="ts">
+import { useRouter, useRoute } from 'vue-router';
+
+const router = useRouter();
+const route = useRoute();
+
+function handleLiveRoomClick(liveInfo: LiveInfo) {
+  if (liveInfo?.liveId) {
+    router.push({ path: '/live-player', query: { ...route.query, liveId: liveInfo.liveId } });
+  }
+}
+
+</script>
+```
+
+## Customization
+
+You can tailor the Live Stream List page UI to fit your project’s requirements. The table below summarizes key customization options.
+| **Category** | **Feature** | **Description** |
+| --- | --- | --- |
+| **Live Room List** | Customize Live Room List display area | **Supports:** - **Show/hide live room info text, customize UI.** - **Set the number of live rooms per row/column.** |
+| **Personal Info** | Customize personal info display | **Supports:** - **Show/hide personal info.** - **Customize font, color, and UI settings for personal info.** |
+
+### Color Theme and Language
+
+Change the default theme and language by configuring the `UIKitProvider` parameters in `App.vue`.
+| UIKitProvider Parameter | Options | Default |
+| --- | --- | --- |
+| theme | "light" | "dark" |
+| language | "zh-CN" | "en-US" |
+
+``` typescript
+<UIKitProvider theme="light">
+  <router-view />
+</UIKitProvider>
+
+<script setup lang="ts">
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
+```
+
+### Button and Icon Customization
+
+Customize buttons, icons, and other controls as needed. For example, in `live-list.vue`, you can add, remove, or modify `Button` and `Icon` components. Beyond layout, you have full control over colors, fonts, border radius, input fields, and pop-ups to match your UI design.
+| **Category** | **Feature** | **Description** |
+| --- | --- | --- |
+| **Asset Management** | Customize asset management display area | Supports adjusting icon size, color, or replacing icons. |
+| **Live Tools** | Customize live tool info display | Supports adjusting icon size, color, or replacing icons. |
+| **Online Audience** | Customize audience info display | Supports: - Show/hide audience level. - Customize audience info font, color, and UI settings. - Replace with your preferred icon style. |
+| **Message List** | Customize live comments display area | Supports: - Show/hide chat input area. - Customize chat bubble style, audience level, and more. |
+
+### Set Nickname and Avatar
+
+To customize the nickname or avatar, use [setSelfInfo](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#setSelfInfo) as shown in the sample code below:
+``` typescript
+import { useLoginState } from 'tuikit-atomicx-vue3';
+
+const { setSelfInfo } = useLoginState();
+
+// Set user personal info
+await setSelfInfo({
+  userName: 'Zhang San',
+  avatarUrl: 'https://example.com/avatar.png',
+});
+```
+
+## Next Steps
+
+You’ve now integrated the **Live Stream List page**. Next, you can add the **Host Streaming Page**, **Audience Viewing Page**, and further **UI Customization** features. See the table below for links to each integration guide:
+| **Feature** | **Description** | **Integration Guide** |
+| --- | --- | --- |
+| **Audience Viewing** | Allow audience to join the host’s live room and watch the stream, with features like guest co-hosting, live room info, online audience, and live comments. | Audience Viewing |
+| **Host Streaming** | Host starts streaming and configures related settings on the current page. | Host Streaming |