@tencent-rtc/mcp 1.4.6 → 1.6.0-beta.1

package/resource/knowledge/roomkit/core-sdk/vue/device-state.md

@@ -0,0 +1,461 @@
+This document guides you on how to use Atomicx components and the `useDeviceState` Hook to manage the state of audio/video devices (camera, microphone, speaker) in a meeting, as well as how to obtain local network quality information.
+
+## Feature Overview
+- **Device enumeration and switching:** Supports retrieving the list of available system devices in real time and switching between them seamlessly.
+
+- **Fine-grained state control:** Provides the ability to turn devices on/off, mute capture, adjust volume, and monitor volume in real time.
+
+- **Error diagnostics:** Provides real-time feedback on abnormal states such as hardware conflicts and missing system permissions.
+
+- **Network quality monitoring:** Provides multi-dimensional network information including latency and packet loss rate.
+
+## Prerequisites
+- The user has completed login authentication via [useLoginState](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#module-LoginState). For details, refer to the Integration Overview.
+
+- If integrating within an `iframe`, you need to declare the permissions in the tag.
+
+   ``` typescript
+   <iframe allow="microphone; camera;"></iframe>
+   ```
+
+## Implementing Camera Management
+
+You can use [useDeviceState](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#module-DeviceState) to control turning the local camera on/off, switching devices, and to listen for capture status and errors.
+
+### Step 1: Turn the camera on/off
+
+Control turning the camera on/off by calling the [openLocalCamera](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#openLocalCamera) and [closeLocalCamera](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#closeLocalCamera) methods.
+``` typescript
+import { useDeviceState, DeviceStatus } from 'tuikit-atomicx-vue3/room';
+const { cameraStatus, openLocalCamera, closeLocalCamera } = useDeviceState();
+const toggleCamera = async () => {
+  if (cameraStatus.value === DeviceStatus.On) {
+    await closeLocalCamera();
+  } else {
+    await openLocalCamera();
+  }
+};
+```
+
+### Step 2: Get/switch the camera device
+
+#### Example of getting and switching the camera on desktop
+
+You can use [cameraList](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#cameraList) to get all available camera devices, and use the [setCurrentCamera](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#setCurrentCamera) method to switch the currently used camera.
+``` typescript
+import { useDeviceState } from 'tuikit-atomicx-vue3/room';
+const { cameraList, currentCamera, getCameraList, setCurrentCamera } = useDeviceState();
+
+// Get the camera list
+await getCameraList();
+
+// Iterate and display available cameras
+cameraList.value.forEach((camera) => {
+  console.log(`Camera: ${camera.deviceName} (${camera.deviceId})`);
+});
+
+// Switch to the specified camera
+const switchCamera = async (deviceId: string) => {
+  try {
+    // Switch the device (if the camera is already on, capture will automatically restart with the new device)
+    await setCurrentCamera({ deviceId });
+    console.log('Camera switched successfully');
+  } catch (error) {
+    console.error('Failed to switch camera:', error);
+    // The original device will continue to be used if switching fails
+  }
+};
+
+// Listen for changes to the current camera
+watch(currentCamera, (camera) => {
+  if (camera) {
+    console.log('Currently used camera:', camera.deviceName);
+  }
+});
+```
+
+> **Note:**
+>
+
+> When you call [setCurrentCamera](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#setCurrentCamera) to switch the device, if the camera is already on, Atomicx will automatically stop capturing from the current device and restart capturing with the new device, so the video stream switches seamlessly. If switching fails, the original device will continue to be used.
+>
+
+#### Example of switching the camera on mobile
+
+On mobile, use [switchCamera](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#switchCamera) to switch between the front and rear cameras.
+``` typescript
+import { useDeviceState } from 'tuikit-atomicx-vue3/room';
+const { isFrontCamera, switchCamera } = useDeviceState();
+
+// Determine whether the device is mobile
+const isMobile = /Android|webOS|iPhone|iPad|iPod/i.test(navigator.userAgent);
+
+// Switch between front and rear cameras (mobile only)
+const toggleCamera = async () => {
+  if (!isMobile) {
+    console.warn('Switching between front and rear cameras is only supported on mobile');
+    return;
+  }
+
+  // Switch to the opposite camera
+  await switchCamera({ isFrontCamera: !isFrontCamera.value });
+  console.log(`Switched to the ${isFrontCamera.value ? 'front' : 'rear'} camera`);
+};
+```
+
+### Step 3: Handle camera capture errors
+
+When an error occurs during camera capture, you can obtain the error information via the [cameraLastError](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#cameraLastError) property.
+
+> Note:
+>
+
+> Common camera errors include `NoSystemPermission` (no system permission) and `OccupiedError` (device is occupied). You should display a clear error message to the user based on this property.
+>
+
+``` typescript
+import { useDeviceState, DeviceError } from 'tuikit-atomicx-vue3/room';
+const { cameraLastError } = useDeviceState();
+
+// Listen for camera errors
+watch(cameraLastError, (error) => {
+  switch (error) {
+    case DeviceError.NoSystemPermission:
+      console.error('Camera permission denied. Please enable camera permission in system settings');
+      break;
+    case DeviceError.NoDeviceDetected:
+      console.error('No camera device detected');
+      break;
+    case DeviceError.OccupiedError:
+      console.error('The camera is occupied by another application');
+      break;
+    case DeviceError.NotSupportCapture:
+      console.error('The current browser does not support camera capture');
+      break;
+    default:
+      break;
+  }
+});
+```
+
+## Implementing Microphone Management
+
+You can use [useDeviceState](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#module-DeviceState) to control turning the local microphone on/off, muting, adjusting volume, and displaying real-time volume, and to listen for capture status and errors.
+
+### Step 1: Turn the microphone on/off
+``` typescript
+import { useDeviceState, DeviceStatus } from 'tuikit-atomicx-vue3/room';
+const { microphoneStatus, openLocalMicrophone, closeLocalMicrophone } = useDeviceState();
+const toggleMicrophone = async () => {
+  if (microphoneStatus.value === DeviceStatus.On) {
+    await closeLocalMicrophone();
+  } else {
+    await openLocalMicrophone();
+  }
+};
+```
+
+### Step 2: Get/switch the microphone device
+
+#### Example of getting/switching the microphone in a desktop browser
+
+You can use [microphoneList](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#microphoneList) to get all available microphone devices, and use the [setCurrentMicrophone](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#setCurrentMicrophone) method to switch the currently used microphone.
+``` typescript
+import { useDeviceState } from 'tuikit-atomicx-vue3/room';
+
+const {
+  microphoneList,
+  currentMicrophone,
+  getMicrophoneList,
+  setCurrentMicrophone
+} = useDeviceState();
+
+// Get the microphone list
+await getMicrophoneList();
+
+// Iterate and display available microphones
+microphoneList.value.forEach((mic) => {
+  console.log(`Microphone: ${mic.deviceName} (${mic.deviceId})`);
+});
+
+// Switch to the specified microphone
+const switchMicrophone = async (deviceId: string) => {
+  await setCurrentMicrophone({ deviceId });
+};
+
+// Listen for changes to the current microphone
+watch(currentMicrophone, (mic) => {
+  if (mic) {
+    console.log('Currently used microphone:', mic.deviceName);
+  }
+});
+```
+
+### Step 3: Set the capture volume
+
+You can use the [setCaptureVolume](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#setCaptureVolume) method to adjust the capture volume of the local microphone.
+``` typescript
+import { useDeviceState } from 'tuikit-atomicx-vue3/room';
+const { captureVolume, setCaptureVolume } = useDeviceState();
+
+// Set the capture volume to 50%
+await setCaptureVolume(50);
+
+// Listen for changes to the capture volume
+watch(captureVolume, (volume) => {
+  console.log('Current capture volume:', volume);
+});
+```
+
+### Step 4: Display real-time volume
+
+The [currentMicVolume](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#currentMicVolume) property updates the local microphone's capture volume in real time, and can be used for the dynamic display of a volume bar.
+``` typescript
+<template>
+  <div class="mic-volume">
+    <label>Microphone volume</label>
+    <div class="volume-bar-container">
+      <div
+        class="volume-bar"
+        :style="{ width: `${currentMicVolume}%` }"
+      />
+    </div>
+    <span>{{ currentMicVolume }}</span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { useDeviceState } from 'tuikit-atomicx-vue3/room';
+const { currentMicVolume } = useDeviceState();
+</script>
+
+<style scoped>
+.volume-bar-container {
+  width: 200px;
+  height: 8px;
+  background-color: #e0e0e0;
+  border-radius: 4px;
+  overflow: hidden;
+}
+
+.volume-bar {
+  height: 100%;
+  background-color: #4caf50;
+  transition: width 0.1s ease;
+}
+</style>
+```
+
+### Step 5: Handle microphone capture errors
+
+When an error occurs during microphone capture, you can obtain the error information via the [microphoneLastError](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#microphoneLastError) data.
+``` typescript
+import { useDeviceState, DeviceError } from 'tuikit-atomicx-vue3/room';
+const { microphoneLastError } = useDeviceState();
+
+// Listen for microphone errors
+watch(microphoneLastError, (error) => {
+  switch (error) {
+    case DeviceError.NoSystemPermission:
+      console.error('Microphone permission denied. Please enable microphone permission in system settings');
+      break;
+    case DeviceError.NoDeviceDetected:
+      console.error('No microphone device detected');
+      break;
+    case DeviceError.OccupiedError:
+      console.error('The microphone is occupied by another application');
+      break;
+    case DeviceError.NotSupportCapture:
+      console.error('The current browser does not support microphone capture');
+      break;
+    default:
+      break;
+  }
+});
+```
+
+## Implementing Speaker Management
+
+The speaker (playback device) mainly involves switching devices and setting the playback volume.
+
+### Step 1: Get/switch the speaker device
+
+You can use [speakerList](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#speakerList) to get all available speaker devices, and use the [setCurrentSpeaker](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#setCurrentSpeaker) method to switch the currently used speaker.
+``` typescript
+import { useDeviceState } from 'tuikit-atomicx-vue3/room';
+const {
+  speakerList,
+  currentSpeaker,
+  getSpeakerList,
+  setCurrentSpeaker
+} = useDeviceState();
+
+// Get the speaker list
+await getSpeakerList();
+
+// Iterate and display available speakers
+speakerList.value.forEach((speaker) => {
+  console.log(`Speaker: ${speaker.deviceName} (${speaker.deviceId})`);
+});
+
+// Switch to the specified speaker
+const switchSpeaker = async (deviceId: string) => {
+  await setCurrentSpeaker({ deviceId });
+};
+
+// Listen for changes to the current speaker
+watch(currentSpeaker, (speaker) => {
+  if (speaker) {
+    console.log('Currently used speaker:', speaker.deviceName);
+  }
+});
+```
+
+### Step 2: Set the playback volume
+
+You can use the [setOutputVolume](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#setOutputVolume) method to adjust the playback volume of the speaker.
+``` typescript
+import { useDeviceState } from 'tuikit-atomicx-vue3/room';
+const { outputVolume, setOutputVolume } = useDeviceState();
+
+// Set the playback volume to 60%
+await setOutputVolume(60);
+
+// Listen for changes to the playback volume
+watch(outputVolume, (volume) => {
+  console.log('Current playback volume:', volume);
+});
+```
+
+## Implementing Network Quality Monitoring
+
+Using the [networkInfo](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#networkInfo) data from [useDeviceState](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#module-DeviceState), you can monitor the local user's network quality in real time.
+
+> **Note:**
+>
+
+> Valid data can only be obtained from [networkInfo](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#networkInfo) when the local user has joined a room via [joinRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#joinRoom) and turned on the microphone or camera.
+>
+
+``` typescript
+<template>
+  <div class="network-indicator" @click="showDetails = !showDetails">
+    <TUIIcon v-if="networkIcon" :icon="networkIcon" />
+    <span class="network-text">{{ networkText }}</span>
+    <div v-if="showDetails" class="network-details">
+      <div>Latency: {{ networkInfo?.delay }}ms</div>
+      <div>Upstream loss: {{ networkInfo?.upLoss }}%</div>
+      <div>Downstream loss: {{ networkInfo?.downLoss }}%</div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import {
+  IconNetworkStability,
+  IconNetworkFluctuation,
+  IconNetworkLag,
+  IconNetworkDisconnected,
+  IconArrowStrokeUp,
+} from '@tencentcloud/uikit-base-component-vue3';
+import { useDeviceState, NetworkQuality } from 'tuikit-atomicx-vue3/room';
+
+const { networkInfo } = useDeviceState();
+const showDetails = ref(false);
+
+// Network quality icon
+const networkIcon = computed(() => {
+  if (!networkInfo.value) return '';
+  switch (networkInfo.value.quality) {
+    case NetworkQuality.Excellent:
+    case NetworkQuality.Good:
+      return IconNetworkStability;
+    case NetworkQuality.Poor:
+      return IconNetworkFluctuation;
+    case NetworkQuality.Bad:
+    case NetworkQuality.VeryBad:
+      return IconNetworkLag;
+    case NetworkQuality.Down:
+      return IconNetworkDisconnected;
+    default:
+      return '';
+  }
+});
+
+// Network quality text
+const networkText = computed(() => {
+  if (!networkInfo.value) return 'Unknown';
+  switch (networkInfo.value.quality) {
+    case NetworkQuality.Excellent:
+      return 'Excellent';
+    case NetworkQuality.Good:
+      return 'Good';
+    case NetworkQuality.Poor:
+      return 'Fair';
+    case NetworkQuality.Bad:
+      return 'Poor';
+    case NetworkQuality.VeryBad:
+      return 'Very poor';
+    case NetworkQuality.Down:
+      return 'Disconnected';
+    default:
+      return 'Unknown';
+  }
+});
+</script>
+
+<style scoped>
+
+.network-indicator {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+.network-details {
+  position: absolute;
+  top: 100%;
+  left: 0;
+  margin-top: 4px;
+  padding: 8px;
+  background: white;
+  border-radius: 4px;
+  box-shadow: 0 2px 8px rgba(0,0,0,0.15);
+  font-size: 12px;
+  white-space: nowrap;
+  z-index: 2;
+}
+</style>
+```
+
+## API Documentation
+
+|**State/Component**|**Description**|**API Documentation**|
+|---------|---------|---------|
+|**useDeviceState**|Contains the audio/video device state, the audio/video device lists, and operation interfaces.|[API Documentation](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#module-DeviceState)|
+
+## FAQ
+
+### If a user's computer has no microphone or speaker device, can they still enter an audio/video room?
+
+Yes, they can enter the room. Even without a microphone, speaker, or camera, a user can still successfully call the `joinRoom` interface to enter an audio/video room. However, in this state, the user will encounter the following interaction issues.
+
+**Feature limitations:**
+- **Unable to start media capture:** Because the system's underlying layer cannot drive the relevant hardware, calling the [openLocalMicrophone](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#openLocalMicrophone) or [openLocalCamera](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#openLocalCamera) interface will trigger an asynchronous error. In this case, the [microphoneLastError](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#microphoneLastError) or [cameraLastError](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#cameraLastError) property will return `DeviceError.NoDeviceDetected` (no device detected).
+
+- **Capture side limited:** The local device cannot capture and transmit audio (requires a microphone) or video (requires a camera).
+
+- **Playback side limited:** Because the speaker device is missing, the user will not be able to hear the audio of other participants in the room.
+
+   **Features that can still be used:**
+
+   View-only mode: The user can still watch video streams or screen sharing shared by remote participants.
+
+### How do I implement device hot-plug detection?
+
+Atomicx has a built-in device hot-plug detection feature. When a media device is plugged in or unplugged, the device list and current device data are updated automatically.

package/resource/knowledge/roomkit/core-sdk/vue/free-beauty-panel.md

@@ -0,0 +1,216 @@
+The basic beauty feature allows users to apply smoothing, whitening, and rosy effects to their portrait during video calls or live streaming.
+
+## Use Cases
+- **Video conferencing:** Reduces skin blemishes and brightens the complexion, making participants look more professional and energetic.
+
+- **Live streaming:** Streamers use the beauty feature to improve the visual quality of the image and attract more viewers.
+
+- **Online education:** Teachers and students maintain a clean and natural appearance, creating a pleasant classroom atmosphere.
+
+## Prerequisites
+- **User status:** The user has completed login authentication via useLoginState, is in the **logged-in** state. See the Integration Overview.
+
+- **Environment dependency:** The project has already imported `tuikit-atomicx-vue3`.
+
+- **Device requirements:** An available camera device is required, and the user must have granted camera access permission. If the user denies the permission, the virtual background feature will not work.
+
+## Implementing the Basic Beauty Feature
+
+This feature provides two integration options. You can choose the one that best fits your business needs:
+- **Option 1 (Recommended):** Quick integration using UI components. Directly import the beauty panel component provided by `tuikit-atomicx-vue3` ([FreeBeautyPanel](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/packages/tuikit-atomicx-vue3/src/components/FreeBeautyPanel)) and embed it into your application's dialog. This has the lowest development cost.
+
+- **Option 2 (Advanced):** Custom integration using low-level APIs. Implement the UI and interaction logic yourself based on the atomicx-core SDK API [useFreeBeautyState](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#module-FreeBeautyState) state hook. This offers the highest flexibility.
+
+## Option 1: Quick Integration Using UI Components
+
+`tuikit-atomicx-vue3` provides the core beauty settings panel component:
+- [**FreeBeautyPanel**](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/packages/tuikit-atomicx-vue3/src/components/FreeBeautyPanel)**:** The basic beauty configuration panel, including parameter adjustment for smoothing, whitening, and rosy effects.
+
+### Step 1: Import the Component
+``` typescript
+import { FreeBeautyPanel } from 'tuikit-atomicx-vue3/room';
+```
+
+### Step 2: Use the Component
+
+It is generally recommended to place `FreeBeautyPanel` inside a Dialog or Modal, and trigger its display via a button click.
+
+**The following example shows how to implement a complete interaction where clicking a button opens the beauty settings:**
+
+> **Note:**
+>
+
+> All TUIKit components must be wrapped inside UIKitProvider; otherwise, they will not be able to obtain their context dependencies, resulting in abnormal styling.
+>
+
+``` typescript
+<template>
+  <UIKitProvider theme="light" language="en-US">
+    <div class="toolbar-container">
+      <!-- 1. Trigger button -->
+      <button @click="openBeautySettings">Set Beauty</button>
+
+      <!-- 2. Settings dialog -->
+      <div v-if="showSettings" class="modal-mask">
+        <div class="modal-content">
+          <div class="modal-header">
+            <span>Basic Beauty</span>
+            <button @click="showSettings = false">Close</button>
+          </div>
+
+          <div class="modal-body">
+            <!-- 3. Import the panel component -->
+            <!-- @close event: triggered when the user clicks the close button inside the panel (if any) -->
+            <FreeBeautyPanel @close="showSettings = false" />
+          </div>
+        </div>
+      </div>
+    </div>
+  </UIKitProvider>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
+import { FreeBeautyPanel, useDeviceState } from 'tuikit-atomicx-vue3/room';
+
+const showSettings = ref(false);
+const { cameraList } = useDeviceState();
+
+const openBeautySettings = () => {
+  // 1. Check whether there is an available camera
+  if (cameraList.value.length === 0) {
+    alert('No camera detected; cannot set beauty');
+    return;
+  }
+
+  // 2. Open the settings panel
+  showSettings.value = true;
+};
+</script>
+
+<style scoped>
+.modal-mask {
+  position: fixed; top: 0; left: 0; width: 100%; height: 100%;
+  background: rgba(0,0,0,0.5); display: flex; justify-content: center; align-items: center; z-index: 1000;
+}
+.modal-content { background: white; width: 600px; border-radius: 8px; overflow: hidden; }
+.modal-header { padding: 16px; display: flex; justify-content: space-between; border-bottom: 1px solid #eee; }
+.modal-body { padding: 16px; }
+</style>
+```
+
+The internal logic of this component is as follows:
+- **Show the panel:** After the user clicks the button, a dialog containing `FreeBeautyPanel` pops up.
+
+- **Adjust parameters:** The user drags the sliders in the panel to adjust the smoothing, whitening, and rosy parameters.
+
+- **Real-time preview:** During adjustment, the preview interface is called in real time to preview the beauty effect.
+
+- **Save and apply:** When the panel is closed (triggering the `@close` event), the current settings are automatically saved so that they take effect for remote users.
+
+## Option 2: Custom Integration Using Low-Level APIs
+
+This section mainly describes how to implement basic beauty via the atomicx-core SDK API [useFreeBeautyState](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#module-FreeBeautyState) interface.
+
+### Step 1: Set Up the Preview
+
+When the user adjusts the beauty parameters (for example, by dragging a slider), use [setFreeBeauty](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#setFreeBeauty) for real-time preview. At this point, the effect is only visible locally and will not be transmitted to remote users.
+
+> **Note:**
+>
+
+> The value range of the parameters is 0-100.
+>
+
+``` typescript
+import { useFreeBeautyState } from 'tuikit-atomicx-vue3/room';
+
+const { setFreeBeauty, beautyConfig } = useFreeBeautyState();
+
+// Example: adjust the beauty parameters
+const updatePreview = async (beauty: number, white: number, ruddy: number) => {
+  // The values in beautyConfig update automatically; this demonstrates how to set the preview manually
+  await setFreeBeauty({
+    beautyLevel: beauty,      // Smoothing (0-100)
+    whitenessLevel: white,    // Whitening (0-100)
+    ruddinessLevel: ruddy     // Rosy (0-100)
+  });
+};
+```
+
+### Step 2: Save and Apply
+
+After the user confirms that they are satisfied with the preview, call [saveBeautySetting](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#saveBeautySetting) to apply the current configuration to the video stream. At this point, remote users can see the beauty effect.
+
+> **Note:**
+>
+
+> The beauty feature depends on a camera device. You can use [useDeviceState](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#module-DeviceState) to check the device status.
+>
+> - [cameraList](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#cameraList): The list of currently available camera devices. If the list is empty, it means no camera was detected or camera permission is denied.
+
+``` typescript
+import { useFreeBeautyState } from 'tuikit-atomicx-vue3/room';
+
+const { saveBeautySetting } = useFreeBeautyState();
+
+const applyBeauty = async () => {
+  // Save the currently previewed settings so that they take effect for remote users
+  await saveBeautySetting();
+  console.log('Beauty has taken effect');
+};
+```
+
+### Step 3: Disable the Beauty Effect
+
+To disable beauty, simply set all parameters to 0 and save.
+``` typescript
+const closeBeauty = async () => {
+  // 1. Set all parameters to 0 and preview
+  await setFreeBeauty({
+    beautyLevel: 0,
+    whitenessLevel: 0,
+    ruddinessLevel: 0
+  });
+
+  // 2. Save to apply
+  await saveBeautySetting();
+};
+```
+
+## Development Notes
+- **Parameter range:** The parameters received by `setFreeBeauty` (`beautyLevel`, `whitenessLevel`, `ruddinessLevel`) all have a range of 0-100.
+
+- **Preview and apply:** To provide a better user experience, beauty adjustment is divided into two phases: **"preview"** and **"apply"**. `setFreeBeauty` is only used for local preview; you must call `saveBeautySetting` for `trtcCloud.setBeautyStyle` to be officially invoked and applied to the published stream.
+
+- **Device dependency:** The beauty feature depends on the video stream, so the effect can only be seen when the camera is enabled. If no camera is detected, it is recommended to disable the beauty entry.
+
+- **Performance consumption:** Enabling beauty adds a certain amount of CPU and GPU load. It is recommended to guide users on low-end devices to use it moderately.
+
+## FAQ
+
+### **Why can't remote users see the effect after I adjust the beauty settings?**
+
+Please confirm whether `saveBeautySetting()` was called. `setFreeBeauty()` is only used for local preview; only after saving will it be applied to the published video stream.
+
+### **Can I set beauty without a camera?**
+
+No. The beauty feature processes the video stream, so if no video image is captured, beauty cannot take effect. It is recommended to hide or disable the beauty entry when there is no camera.
+
+### **After leaving the room or turning off the camera, do I need to reset beauty manually?**
+
+No. `useFreeBeautyState` already implements automatic state management internally:
+- Camera switching: Beauty is paused when the camera is turned off, and the last saved settings are automatically restored when it is turned back on.
+
+- Entering/leaving rooms: All beauty parameters are automatically reset when leaving the room, with no manual cleanup required by the developer.
+
+## **Example Project**
+
+Tencent Cloud provides the example project [atomicx-vite-vue3-ts](https://github.com/Tencent-RTC/TUIRoomKit/tree/main/Web/example/atomicx-vite-vue3-ts) on GitHub, which you can refer to in order to implement the complete RoomKit functionality.
+
+## API Documentation
+
+|**State/Component**|**Description**|**API Documentation**|
+|---------|---------|---------|
+|**useFreeBeautyState**|Free beauty feature management|[API Documentation](https://web.sdk.qcloud.com/trtc/live/web/doc/en/index.html#module-FreeBeautyState)|