@tencent-rtc/mcp 1.3.1 → 1.3.2

package/resource/doc/roomkit/vue/features/call-user-to-room.md

@@ -0,0 +1,256 @@
+The in-room call feature allows users within a meeting (inviter) to send real-time invitations to users outside the room (invitees). This feature is implemented based on `Atomicx State Hooks` and helps developers quickly build interactive scenarios with proactive invitation capabilities.
+
+## Use Cases
+- **Collaborative Office:** During remote meetings, if cross-departmental decisions are involved, you can invite external experts to join the meeting with one click, shortening communication paths.
+
+- **Live Teaching:** During the teaching process, if teachers find that some students are absent, they can directly invite them to join the class.
+
+- **Internet Medical Consultation:** During case analysis, the primary physician can invite senior doctors to enter the virtual consultation room for multi-party consultation through the call feature, or doctors can call patients in the waiting room for consultations.
+
+
+## Prerequisites
+
+Before integrating this feature, please ensure the following conditions are met:
+- **Inviter (User A):** The user has completed login authentication through `useLoginState`, refer to [Integration Overview](https://write.woa.com/document/197379797539790848), and is already in a room as the room owner or member, refer to [Room Lifecycle](https://write.woa.com/document/197379861957083136).
+
+- **Invitee (User B):** The user has completed login authentication through `useLoginState`, refer to [Integration Overview](https://write.woa.com/document/197379797539790848), to receive signaling events.
+
+- **Environment Dependencies:** The project has correctly installed and imported `tuikit-atomicx-vue3`.
+
+
+## Implementing In-Room Call Feature
+
+The core process for implementing in-room calls is as follows:
+
+![In-room call sequence diagram](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027160512/82ba8603dee611f0a4f35254007c27c5.png)
+
+In-room call sequence diagram
+
+
+### Step 1: Initiate Call (Inviter)
+
+The inviter calls the [callUserToRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#callUserToRoom) interface to initiate an invitation. Please ensure the inviter is currently in the room (i.e., [currentRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#currentRoom) is not empty), otherwise the call cannot be initiated.
+``` typescript
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+
+const { currentRoom, callUserToRoom } = useRoomState();
+
+const inviteUser = async () => {
+  // In-room calls must be associated with an existing roomId, so check the current user's room status first
+  if (!currentRoom.value) {
+    console.warn('Please enter a room first before initiating an invitation');
+    return;
+  }
+
+  try {
+    const resultMap = await callUserToRoom({
+      roomId: currentRoom.value.roomId, // Room ID the invitee will join
+      userIdList: ['user1', 'user2'],    // Target user ID array, supports single or multiple users
+      timeout: 60,                        // Invitation validity period (seconds), both parties will trigger onCallTimeout after timeout
+      // extensionInfo can be used to pass business custom data, such as invitation type, additional messages, etc.
+      extensionInfo: JSON.stringify({ type: 'emergency', priority: 'high' }) 
+    });
+    
+    // resultMap returns the status corresponding to each userId, such as Success, AlreadyInRoom (already in room) or AlreadyInCalling (in call)
+    console.log('Invitation sent successfully, detailed status map:', resultMap);
+  } catch (error) {
+    console.error('Failed to send call request, please check network or login status:', error);
+  }
+};
+```
+
+### Step 2: Listen for Call Events (Invitee)
+
+The invitee needs to listen for the `onCallReceived` event. It is recommended to implement this in long-lived components such as `App.vue` to ensure the user can respond regardless of which page they are on.
+``` typescript
+import { ref, onMounted, onUnmounted } from 'vue';
+import { useRoomState, RoomEvent } from 'tuikit-atomicx-vue3/room';
+
+const { 
+  subscribeEvent, 
+  unsubscribeEvent, 
+  acceptCall, 
+  rejectCall, 
+  joinRoom, 
+  currentRoom 
+} = useRoomState();
+
+const showInviteDialog = ref(false); // Control UI dialog visibility
+const currentCallInfo = ref(null);   // Cache the received invitation context
+
+const handleCallReceived = async ({ roomInfo, call, extensionInfo }) => {
+  // Conflict handling: If the user is currently in a meeting, according to business policy, usually should directly reject new invitations to prevent interference
+  if (currentRoom.value?.roomId) {
+    await rejectCall({ roomId: roomInfo.roomId });
+    return;
+  }
+
+  // Record invitation details for displaying inviter name or business transparent data in UI
+  currentCallInfo.value = { roomInfo, call };
+  showInviteDialog.value = true;
+};
+
+// Accept invitation logic
+const onUserAccept = async () => {
+  if (!currentCallInfo.value) return;
+  const { roomId } = currentCallInfo.value.roomInfo;
+
+  try {
+    // Key process A: Respond to signaling. Inform the inviter that it has been accepted so they can update UI (e.g., display "Other party answered")
+    await acceptCall({ roomId });
+    
+    // Key process B: Execute room entry. Only by calling joinRoom will the audio and video push-pull stream link be truly opened
+    await joinRoom({ roomId }); 
+  } catch (error) {
+    console.error('Room entry operation failed after accepting call:', error);
+  } finally {
+    closeDialog();
+  }
+};
+
+// Reject invitation logic
+const onUserReject = async () => {
+  if (currentCallInfo.value) {
+    // Inform the inviter that it has been rejected, the inviter will receive onCallRejected event
+    await rejectCall({ roomId: currentCallInfo.value.roomInfo.roomId });
+  }
+  closeDialog();
+};
+
+const closeDialog = () => {
+  showInviteDialog.value = false;
+  currentCallInfo.value = null;
+};
+
+// Event full lifecycle management: Ensure listening on component mount and removal on destroy to prevent event overflow
+onMounted(() => {
+  subscribeEvent(RoomEvent.onCallReceived, handleCallReceived);
+  
+  // Listen for various exceptions/sync events that cause invitation to end, ensuring UI dialog can close in time
+  subscribeEvent(RoomEvent.onCallCancelled, closeDialog); // Inviter cancelled the call
+  subscribeEvent(RoomEvent.onCallTimeout, closeDialog);   // Call timed out without response
+  subscribeEvent(RoomEvent.onCallHandledByOtherDevice, closeDialog); // User already handled the call on another device
+});
+
+onUnmounted(() => {
+  // Remove all listeners to avoid continuing to execute handleCallReceived after component destruction, causing memory leaks or errors
+  unsubscribeEvent(RoomEvent.onCallReceived, handleCallReceived);
+  unsubscribeEvent(RoomEvent.onCallCancelled, closeDialog);
+  unsubscribeEvent(RoomEvent.onCallTimeout, closeDialog);
+  unsubscribeEvent(RoomEvent.onCallHandledByOtherDevice, closeDialog);
+});
+```
+
+## Practical Tutorial: Improving Call Connection Rate
+
+To achieve higher call connection rates in business scenarios, in addition to implementing basic functions, it is recommended to refer to the following strategies to optimize user experience:
+
+### 1. Enhanced Call Awareness (Avoid Users Missing Calls)
+
+Due to Web characteristics, browser mute or page running in background state may cause users to miss calls.
+- **Visual Reminder**: Use [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API) to detect page visibility status. If the page is in the background, you can implement title bar flashing prompts by cyclically modifying `document.title` (e.g.: "【New Invitation】UserA invites you to the meeting...") to attract user attention.
+
+- **Audio Reminder**: Play high-priority alert ringtone when the `onCallReceived` event is triggered. Note: Must comply with browser's [Autoplay Policy](https://developer.mozilla.org/zh-CN/docs/Web/Media/Guides/Autoplay), most browsers will restrict audio autoplay in the absence of user interaction (such as clicks, touches, or key presses).
+
+
+### 2. Enrich Invitation Context (Improve Answering Willingness)
+
+Invitations lacking clear intent are easily rejected by users. It is recommended to fully utilize the `extensionInfo` field to pass key business information to improve users' willingness to answer.
+- **Pass Business Context**: Use `extensionInfo` to transparently pass business fields such as `reason` (e.g.: "Project emergency review"), `level` (e.g.: "P0 troubleshooting"), etc., to inform users of the urgency and importance of the call.
+
+
+### 3. Multi-Channel Reach Backup (Ensure Message Delivery)
+
+Limited by Web mechanisms, when the browser process ends, real-time signaling cannot be received. It is recommended to adopt the following alternative solutions to ensure reach:
+- **Browser System Notifications**: Guide users to authorize [Web Notification API](https://developer.mozilla.org/en-US/docs/Web/API/Notification). As long as the browser process is not closed (including minimized or in background tabs), OS-level pop-up notifications can be triggered to effectively remind users.
+
+- **Multi-Channel Reach**: It is recommended to combine backend business logic to send meeting links through **SMS**, **Email**, or **Enterprise WeChat** and other external channels when detecting that users are offline or timeout without response, achieving all-around reach.
+
+
+### 4. Intelligent Retry Mechanism (Solve "Room Entry Failed After Accepting Invitation")
+
+In weak network or other unstable environments, calling `joinRoom` after users click accept invitation may experience occasional failures.
+- **Automatic Retry**: It is recommended to introduce 2-3 automatic retry mechanisms (recommended combined with exponential backoff strategy) in the exception handling logic (`catch`) of `onUserAccept` to maximize ensuring users can successfully join the meeting after clicking "accept".
+
+
+## Development Notes
+1. **Accepting Invitation Does Not Equal Entering Room**
+
+
+   `acceptCall` is only a signaling layer reply (informing the other party that the call has been answered). Users must manually call `await joinRoom({ roomId })` immediately after calling `acceptCall` to truly enter the audio and video room.
+
+2. **Lifecycle Management**
+
+
+   Please be sure to call `unsubscribeEvent` in the component destruction cycle (`onUnmounted`). If listeners are not cleaned up, when users switch pages, listeners from old pages will remain in memory, causing one invitation to pop up multiple windows or logic to execute repeatedly.
+
+3. **Timeout Settings**
+
+
+   If the `timeout` parameter is not set, in some network exceptions or program crash situations, invitations may remain in a suspended state for a long time, making it impossible to initiate another call to that user. It is recommended to set it to 30-60 seconds.
+
+
+## Common Questions
+1. **How to pass custom parameters when calling (e.g., "Emergency meeting from XX")?**
+
+
+   Use the `extensionInfo` parameter of `callUserToRoom` to pass a JSON string. The invitee can parse the string to obtain business information in the `extensionInfo` field of the `onCallReceived` event.
+
+2. **If the invitee is not online, can they receive the invitation after coming online?**
+
+
+   No. The invitation event is an instantaneous signaling action, and the SDK currently does not resend call notifications received while offline.
+
+3. **Can issued invitations be cancelled?**
+
+
+   Yes. Call `cancelCall({ roomId, userIdList })` to cancel. At this time, the invitee will receive the `onCallCancelled` event, and you need to listen to this event to close the UI dialog on the invitee side.
+
+4. **What to do if room entry fails after accepting?**
+
+
+   Check if you have logged in to `TUIRoomEngine`, retry `joinRoom({ roomId })` and capture error prompts to the user; if necessary, provide a "retry" button on the UI.
+
+5. **How to prompt when the other party is busy or already in another room?**
+
+
+   If `AlreadyInRoom` / `AlreadyInCalling` appears in the return value `resultMap` of `callUserToRoom`, you should prompt on the inviter UI "The other party is busy/already in a meeting" and decide whether to retry later.
+
+6. **Dialog not closing after timeout/cancellation?**
+
+
+   Make sure to listen to `onCallTimeout`, `onCallCancelled`, `onCallHandledByOtherDevice`, and uniformly close the dialog and clear current invitation data in the callback.
+
+7. **How to handle simultaneous ringing on multiple devices?**
+
+
+   After accepting/rejecting on any device, other devices will receive `onCallHandledByOtherDevice`, and you need to close dialogs on other ends to avoid repeated processing.
+
+8. **How should extensionInfo be agreed upon?**
+
+
+   It is recommended to use a JSON string and agree on fields (e.g., `type`, `priority`, `from`), parse and display friendly text (e.g., "Emergency meeting from XX") in `handleCallReceived`.
+
+
+## **Sample Project**
+
+Tencent Cloud provides a sample 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 for implementing complete RoomKit functionality.
+
+## API Documentation
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**State/Component**</td>
+
+<td rowspan="1" colSpan="1" >**Feature Description**</td>
+
+<td rowspan="1" colSpan="1" >**API Documentation**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >**useRoomState**</td>
+
+<td rowspan="1" colSpan="1" >Room state management (create, join, schedule, etc.)</td>
+
+<td rowspan="1" colSpan="1" >[API Documentation](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-RoomState)</td>
+</tr>
+</table>

package/resource/doc/roomkit/vue/features/device-detection.md

@@ -0,0 +1,388 @@
+This document will guide you on how to provide device preview and testing functionality before users join a room. Through the pre-room testing interfaces provided by Atomicx, you can guide users to check and adjust their audio/video device status, ensuring they enter the multi-party audio/video room in the best condition.
+
+## Feature Introduction
+
+Device preview is an important part of ensuring the smooth operation of audio/video rooms. Atomicx provides a dedicated set of testing interfaces specifically for pre-room scenarios, with core capabilities including:
+- **Video Preview**: Start the camera without streaming to verify picture clarity and lighting.
+
+- **Microphone Detection**: Confirm microphone capture is working properly through real-time volume feedback.
+
+- **Speaker Calibration**: Confirm output device and volume settings by playing test audio.
+
+
+## Prerequisites
+- User has completed login authentication through [useLoginState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-LoginState), please refer to [Integration Overview](https://write.woa.com/document/197379797539790848).
+
+
+## Implementing Device Detection Features
+
+### Step 1: Camera Test
+
+Use the [startCameraTest](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#startCameraTest) method to start camera testing. This method is only used for local preview and does not generate network traffic.
+
+**Code Example:**
+``` typescript
+<template>
+  <div class="preview-container">
+    <!-- Camera preview area -->
+    <div id="camera-preview" class="camera-preview">
+      <!-- Loading status -->
+      <div v-if="isCameraTestLoading" class="loading-overlay">
+        <div class="loading-spinner" />
+        <span>Starting camera...</span>
+      </div>
+    </div>
+
+    <!-- Camera selection -->
+    <div class="camera-selector">
+      <label>Select Camera</label>
+      <select 
+        :value="currentCamera?.deviceId" 
+        @change="handleCameraChange"
+        :disabled="isCameraTestLoading"
+      >
+        <option 
+          v-for="camera in cameraList" 
+          :key="camera.deviceId"
+          :value="camera.deviceId"
+        >
+          {{ camera.deviceName }}
+        </option>
+      </select>
+    </div>
+
+    <!-- Control buttons -->
+    <div class="control-buttons">
+      <button @click="getCameraList">Get Camera List</button>
+      <button 
+        @click="toggleCameraTest"
+        :disabled="isCameraTestLoading"
+      >
+        {{ isCameraTesting ? 'Stop Preview' : 'Start Preview' }}
+      </button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, watch, onMounted, onUnmounted } from 'vue';
+import { IconWarning } from '@tencentcloud/uikit-base-component-vue3';
+import { 
+  useLoginState,
+  useDeviceState, 
+  DeviceStatus,
+  DeviceError,
+} from 'tuikit-atomicx-vue3/room';
+
+const { 
+  isCameraTesting,
+  isCameraTestLoading,
+  cameraList,
+  currentCamera,
+  startCameraTest,
+  stopCameraTest,
+  getCameraList,
+  setCurrentCamera
+} = useDeviceState();
+
+onUnmounted(() => {
+  if (isCameraTesting.value) {
+    stopCameraTest();
+  }
+});
+
+const toggleCameraTest = async () => {
+  if (isCameraTesting.value) {
+    await stopCameraTest();
+  } else {
+    const previewElement = document.getElementById('camera-preview');
+    if (previewElement) {
+      await startCameraTest({ view: previewElement });
+    }
+  }
+};
+
+const handleCameraChange = async (event: Event) => {
+  const deviceId = (event.target as HTMLSelectElement).value;
+  try {
+    await setCurrentCamera({ deviceId });
+  } catch (error) {
+    console.error('Failed to switch camera:', error);
+  }
+};
+</script>
+
+<style scoped>
+.preview-container {  position: relative;  width: 100%;  max-width: 640px;  margin: 0 auto;}.camera-preview {  width: 100%;  position: relative;  aspect-ratio: 16 / 9;  background-color: #000;  border-radius: 8px;  overflow: hidden;}.loading-overlay {  position: absolute;  inset: 0;  display: flex;  flex-direction: column;  align-items: center;  justify-content: center;  gap: 12px;  background-color: rgba(0, 0, 0, 0.7);  color: white;  border-radius: 8px;}.loading-spinner {  width: 40px;  height: 40px;  border: 4px solid rgba(255, 255, 255, 0.3);  border-top-color: white;  border-radius: 50%;  animation: spin 0.8s linear infinite;}@keyframes spin {  to { transform: rotate(360deg); }}.error-message {  display: flex;  align-items: center;  gap: 8px;  padding: 12px;  margin-top: 12px;  background-color: #ffebee;  color: #c62828;  border-radius: 4px;  font-size: 14px;}.camera-selector {  margin-top: 16px;  display: flex;  align-items: center;  gap: 12px;}.camera-selector label {  font-weight: 500;  min-width: 80px;}.camera-selector select {  flex: 1;  padding: 8px 12px;  border: 1px solid #e0e0e0;  border-radius: 4px;  font-size: 14px;}.control-buttons {  margin-top: 16px;  display: flex;  gap: 12px;}.control-buttons button {  flex: 1;  padding: 12px 24px;  background-color: #1976d2;  color: white;  border: none;  border-radius: 4px;  font-size: 14px;  font-weight: 500;  cursor: pointer;  transition: background-color 0.3s;}.control-buttons button:hover:not(:disabled) {  background-color: #1565c0;}.control-buttons button:disabled {  background-color: #bdbdbd;  cursor: not-allowed;}
+</style>
+```
+
+### Step 2: Microphone Test
+
+Start microphone testing through [startMicrophoneTest](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#startMicrophoneTest), and use [testingMicVolume](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#testingMicVolume) to implement real-time volume bar fluctuation in the UI.
+
+**Code Example:**
+``` typescript
+<template>
+  <div class="microphone-test">
+    <!-- Volume display -->
+    <div class="volume-display">
+      <div class="volume-label">Microphone Volume</div>
+      <div class="volume-bar-container">
+        <div 
+          class="volume-bar" 
+          :style="{ width: `${testingMicVolume}%` }"
+          :class="volumeClass"
+        />
+      </div>
+      <div class="volume-value">{{ testingMicVolume }}</div>
+    </div>
+
+    <!-- Microphone selection -->
+    <div class="microphone-selector">
+      <label>Select Microphone</label>
+      <select 
+        :value="currentMicrophone?.deviceId" 
+        @change="handleMicrophoneChange"
+        :disabled="isMicrophoneTesting"
+      >
+        <option 
+          v-for="mic in microphoneList" 
+          :key="mic.deviceId"
+          :value="mic.deviceId"
+        >
+          {{ mic.deviceName }}
+        </option>
+      </select>
+    </div>
+
+    <!-- Control buttons -->
+    <div class="control-buttons">
+      <button 
+        @click="getMicrophoneList"
+      >
+        Get Devices
+      </button>
+      <button 
+        @click="toggleMicrophoneTest"
+      >
+        {{ isMicrophoneTesting ? 'Stop Test' : 'Start Test' }}
+      </button>
+    </div>
+
+    <!-- Test tip -->
+    <div v-if="isMicrophoneTesting" class="test-tip">
+      <span>Please speak into the microphone to see volume changes</span>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, watch, onMounted, onUnmounted } from 'vue';
+import { 
+  useDeviceState, 
+  DeviceError,
+} from 'tuikit-atomicx-vue3/room';
+
+const { 
+  isMicrophoneTesting,
+  testingMicVolume,
+  microphoneList,
+  currentMicrophone,
+  startMicrophoneTest,
+  stopMicrophoneTest,
+  getMicrophoneList,
+  setCurrentMicrophone
+} = useDeviceState();
+
+// Volume bar style class
+const volumeClass = computed(() => {
+  const volume = testingMicVolume.value;
+  if (volume === 0) return 'volume-zero';
+  if (volume < 30) return 'volume-low';
+  if (volume < 70) return 'volume-medium';
+  return 'volume-high';
+});
+
+// Cleanup: stop testing
+onUnmounted(() => {
+  if (isMicrophoneTesting.value) {
+    stopMicrophoneTest();
+  }
+});
+
+// Toggle microphone test
+const toggleMicrophoneTest = async () => {
+  if (isMicrophoneTesting.value) {
+    await stopMicrophoneTest();
+  } else {
+    try {
+      await startMicrophoneTest({ interval: 200 });
+    } catch (error) {
+      console.error('Failed to start microphone test:', error);
+    }
+  }
+};
+
+// Switch microphone device
+const handleMicrophoneChange = async (event: Event) => {
+  const deviceId = (event.target as HTMLSelectElement).value;
+  try {
+    await setCurrentMicrophone({ deviceId });
+  } catch (error) {
+    console.error('Failed to switch microphone:', error);
+  }
+};
+</script>
+
+<style scoped>
+.microphone-test {  width: 100%;  max-width: 640px;  margin: 0 auto;}.volume-display {  padding: 24px;  background-color: #f5f5f5;  border-radius: 8px;  margin-bottom: 16px;}.volume-label {  font-size: 14px;  font-weight: 500;  color: #666;  margin-bottom: 12px;}.volume-bar-container {  width: 100%;  height: 24px;  background-color: #e0e0e0;  border-radius: 12px;  overflow: hidden;  margin-bottom: 8px;}.volume-bar {  height: 100%;  transition: width 0.1s ease;  border-radius: 12px;}.volume-bar.volume-zero {  background-color: #9e9e9e;}.volume-bar.volume-low {  background-color: #ff9800;}.volume-bar.volume-medium {  background-color: #4caf50;}.volume-bar.volume-high {  background-color: #2196f3;}.volume-value {  text-align: center;  font-size: 18px;  font-weight: 600;  color: #333;}.microphone-selector {  display: flex;  align-items: center;  gap: 12px;  margin-bottom: 16px;}.microphone-selector label {  font-weight: 500;  min-width: 80px;}.microphone-selector select {  flex: 1;  padding: 8px 12px;  border: 1px solid #e0e0e0;  border-radius: 4px;  font-size: 14px;}.error-message {  display: flex;  align-items: center;  gap: 8px;  padding: 12px;  margin-bottom: 16px;  background-color: #ffebee;  color: #c62828;  border-radius: 4px;  font-size: 14px;}.control-buttons {  margin-bottom: 12px; display: flex; gap: 8px; }.control-buttons button {  flex: 1; width: 100%;  padding: 12px 24px;  background-color: #1976d2;  color: white;  border: none;  border-radius: 4px;  font-size: 14px;  font-weight: 500;  cursor: pointer;  transition: background-color 0.3s;}.control-buttons button:hover:not(:disabled) {  background-color: #1565c0;}.control-buttons button:disabled {  background-color: #bdbdbd;  cursor: not-allowed;}.test-tip {  display: flex;  align-items: center;  gap: 8px;  padding: 12px;  background-color: #e3f2fd;  color: #1565c0;  border-radius: 4px;  font-size: 13px;}
+</style>
+```
+
+### Step 3: Speaker Test
+
+Use the [startSpeakerTest](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#startSpeakerTest) method to play a specified audio file to confirm whether the speaker is working properly.
+
+**Code Example:**
+``` typescript
+<template>
+  <div class="speaker-test">
+    <!-- Speaker selection -->
+    <div class="speaker-selector">
+      <label>Select Speaker</label>
+      <select 
+        :value="currentSpeaker?.deviceId" 
+        @change="handleSpeakerChange"
+        :disabled="isSpeakerTesting"
+      >
+        <option 
+          v-for="speaker in speakerList" 
+          :key="speaker.deviceId"
+          :value="speaker.deviceId"
+        >
+          {{ speaker.deviceName }}
+        </option>
+      </select>
+    </div>
+
+    <!-- Control buttons -->
+    <div class="control-buttons">
+      <button @click="getSpeakerList">Get Speaker List</button>
+      <button 
+        @click="toggleSpeakerTest"
+        :disabled="isSpeakerTesting"
+      >
+        {{ isSpeakerTesting ? 'Playing...' : 'Play Test Audio' }}
+      </button>
+      <button 
+        v-if="isSpeakerTesting"
+        @click="stopSpeakerTest"
+      >
+        Stop Playback
+      </button>
+    </div>
+
+    <!-- Test tip -->
+    <div v-if="isSpeakerTesting" class="test-tip">
+      <span>Playing test audio, please confirm if you can hear the sound</span>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from 'vue';
+import { useDeviceState } from 'tuikit-atomicx-vue3/room';
+
+const { 
+  isSpeakerTesting,
+  speakerList,
+  currentSpeaker,
+  startSpeakerTest,
+  stopSpeakerTest,
+  getSpeakerList,
+  setCurrentSpeaker,
+} = useDeviceState();
+
+// Test audio file path
+// Note: This URL is for development testing only. For production environments, please use your own audio file. It is recommended to use a 3-5 second MP3 format audio file
+const testAudioPath = 'https://web.sdk.qcloud.com/trtc/electron/download/resources/media/TestSpeaker.mp3';
+
+// Cleanup: stop testing
+onUnmounted(() => {
+  if (isSpeakerTesting.value) {
+    stopSpeakerTest();
+  }
+});
+
+// Toggle speaker test
+const toggleSpeakerTest = async () => {
+  if (isSpeakerTesting.value) {
+    await stopSpeakerTest();
+  } else {
+    try {
+      await startSpeakerTest({ filePath: testAudioPath });
+    } catch (error) {
+      console.error('Failed to start speaker test:', error);
+    }
+  }
+};
+
+// Switch speaker device
+const handleSpeakerChange = async (event: Event) => {
+  const deviceId = (event.target as HTMLSelectElement).value;
+  try {
+    await setCurrentSpeaker({ deviceId });
+  } catch (error) {
+    console.error('Failed to switch speaker:', error);
+  }
+};
+</script>
+
+<style scoped>
+.speaker-test {  width: 100%;  max-width: 640px;  margin: 0 auto;}.speaker-selector {  display: flex;  align-items: center;  gap: 12px;  margin-bottom: 24px;}.speaker-selector label {  font-weight: 500;  min-width: 80px;}.speaker-selector select {  flex: 1;  padding: 8px 12px;  border: 1px solid #e0e0e0;  border-radius: 4px;  font-size: 14px;}.volume-slider-container {  display: flex;  align-items: center;  gap: 12px;}.volume-slider {  flex: 1;  height: 6px;  border-radius: 3px;  background: #e0e0e0;  outline: none;  -webkit-appearance: none;}.volume-slider::-webkit-slider-thumb {  -webkit-appearance: none;  width: 18px;  height: 18px;  border-radius: 50%;  background: #1976d2;  cursor: pointer;}.volume-slider::-moz-range-thumb {  width: 18px;  height: 18px;  border-radius: 50%;  background: #1976d2;  cursor: pointer;  border: none;}.volume-value {  min-width: 50px;  text-align: right;  font-weight: 500;  color: #333;}.control-buttons {  display: flex;  gap: 12px;  margin-bottom: 12px;}button {  flex: 1;  padding: 12px 24px;  background-color: #1976d2;  color: white;  border: none;  border-radius: 4px;  font-size: 14px;  font-weight: 500;  cursor: pointer;  transition: background-color 0.3s;}.control-buttons button:hover:not(:disabled) {  background-color: #1565c0;}.control-buttons button:disabled {  background-color: #bdbdbd;  cursor: not-allowed;}.test-tip {  display: flex;  align-items: center;  gap: 8px;  padding: 12px;  background-color: #e3f2fd;  color: #1565c0;  border-radius: 4px;  font-size: 13px;}
+</style>
+```
+
+## API Documentation
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**State/Component**</td>
+
+<td rowspan="1" colSpan="1" >**Feature Description**</td>
+
+<td rowspan="1" colSpan="1" >**API Documentation**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >**useDeviceState**</td>
+
+<td rowspan="1" colSpan="1" >Contains audio/video device status, audio/video device list and operation interfaces.</td>
+
+<td rowspan="1" colSpan="1" >[API Documentation](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-DeviceState)</td>
+</tr>
+</table>
+
+
+## FAQ
+
+### Why is there no image in the camera preview?
+
+Possible reasons include:
+- **Permission denied:** Check if the browser allows camera permissions.
+
+- **Device occupied:** Close other applications using the camera.
+
+- **Device not connected:** Check if the camera is properly connected.
+
+- **Browser not supported:** Use modern browsers such as Chrome, Edge, etc.
+
+
+### Microphone test volume is always 0?
+
+Possible reasons include:
+- **Microphone permission not granted:** Check browser permission settings.
+
+- **Microphone is muted:** Check system microphone settings.
+
+- **Wrong device selected:** Switch to the correct microphone device.