@tencent-rtc/mcp 1.7.2 → 1.7.3

package/resource/knowledge/roomkit/core-sdk/vue/whiteboard-annotation.md

@@ -0,0 +1,196 @@
+This document introduces how to use the Atomicx API to integrate whiteboard or screen sharing annotation into your own meeting UI.
+
+First, choose the feature you want to implement:
+
+|Goal|Do you need to start screen sharing first|Integration order|
+|---------|---------|---------|
+|Whiteboard: Write on a blank canvas|No|Once the display area is ready, call `startWhiteboard`|
+|Screen sharing annotation: Annotate on the screen sharing view|Yes|Call `startScreenShare` first, then call `startWhiteboard`|
+
+> **Note:**
+> **To integrate screen sharing annotation, you do not need to integrate the standalone whiteboard first.** Both features use `startWhiteboard` to create the drawing layer, but their integration flows are independent of each other. Choose one according to your business goal.
+>
+
+## Preparation
+
+Before you start, please confirm:
+- User state: The user has completed login authentication through `useLoginState` (see Integration overview) and is already in a room as the owner or a member of that room (see Room management).
+
+- Environment dependency: The project has correctly installed and imported `tuikit-atomicx-vue3` (Vue 3), version `6.1.0` or later.
+
+- Use the latest stable versions of Chrome and Edge on Windows or macOS desktops.
+
+   The "display area" in the code in this document is a `<div>` on the page used to display the whiteboard or shared view. After setting its `id`, pass that `id` to the API. It determines both where the content is displayed and the display size, and you do not need to understand the internal implementation of the whiteboard.
+
+## Integrating the whiteboard
+
+The whiteboard does not depend on screen sharing. Prepare a display area, and when the user clicks "Open whiteboard", pass its `id` to `startWhiteboard`:
+``` typescript
+<template>
+  <button @click="openWhiteboard">Open whiteboard</button>
+  <div id="whiteboard-view" class="content-view" />
+</template>
+
+<script setup lang="ts">
+import { useWhiteboardState } from 'tuikit-atomicx-vue3/room';
+
+const { startWhiteboard } = useWhiteboardState();
+
+async function openWhiteboard() {
+  await startWhiteboard({
+    view: 'whiteboard-view',
+    canvasColor: '#FFFFFF',
+  });
+}
+</script>
+
+<style scoped>
+.content-view {
+  position: relative;
+  width: 100%;
+  height: 600px;
+  background: #fff;
+}
+</style>
+```
+
+After the call succeeds, the current user can draw in that area, and other members in the room will see the whiteboard view in real time.
+
+## Integrating screen sharing annotation
+
+Screen sharing annotation adds a transparent drawing layer on top of the shared view. The whole flow has only two steps:
+1. Display the screen sharing view in a `<div>` on the page.
+
+2. Pass the `id` of the same `<div>` to `startWhiteboard` so that the strokes overlay the shared view.
+
+   The following example provides two buttons, "Start sharing" and "Start annotation":
+
+   ``` typescript
+   <template>
+     <button @click="shareScreen">Start sharing</button>
+     <button @click="openAnnotation">Start annotation</button>
+     <div id="screen-share-view" class="content-view" />
+   </template>
+
+   <script setup lang="ts">
+   import {
+     DeviceStatus,
+     useDeviceState,
+     useWhiteboardState,
+   } from 'tuikit-atomicx-vue3/room';
+
+   const { screenStatus, startScreenShare } = useDeviceState();
+   const { startWhiteboard } = useWhiteboardState();
+
+   async function shareScreen() {
+     await startScreenShare({
+       screenAudio: true,
+       view: 'screen-share-view',
+     });
+   }
+
+   async function openAnnotation() {
+     if (screenStatus.value !== DeviceStatus.On) {
+       throw new Error('Please start screen sharing first');
+     }
+
+     await startWhiteboard({
+       view: 'screen-share-view',
+     });
+   }
+   </script>
+
+   <style scoped>
+   .content-view {
+     position: relative;
+     width: 100%;
+     height: 600px;
+   }
+   </style>
+   ```
+
+## Adding drawing tools
+
+The whiteboard and screen sharing annotation use the same set of tool APIs. Just connect the methods below to your toolbar buttons:
+``` typescript
+import {
+  useWhiteboardState,
+  WhiteboardTool,
+} from 'tuikit-atomicx-vue3/room';
+
+const {
+  setToolConfig,
+  undo,
+  redo,
+  clear,
+  snapshot,
+} = useWhiteboardState();
+
+// Pen
+setToolConfig({
+  tool: WhiteboardTool.Pen,
+  color: '#006EFF',
+  lineWidth: 4,
+});
+
+// Rectangle
+setToolConfig({
+  tool: WhiteboardTool.Shape,
+  shapeType: 'rect',
+  color: '#006EFF',
+  lineWidth: 4,
+});
+
+await undo();           // Undo
+await redo();           // Redo
+await clear();          // Clear
+const image = await snapshot();
+```
+
+The available tools include:
+
+|Tool|Enum value|Purpose|
+|---------|---------|---------|
+|Select|`WhiteboardTool.None`|Stop drawing.|
+|Pen|`WhiteboardTool.Pen`|Free-form writing.|
+|Laser pointer|`WhiteboardTool.Laser`|Disappears automatically after a short stay.|
+|Shape|`WhiteboardTool.Shape`|Draw a rectangle or ellipse through `shapeType`.|
+|Arrow|`WhiteboardTool.Arrow`|Mark a direction or key point.|
+|Eraser|`WhiteboardTool.EraserObject`|Erase graphic objects.|
+
+When drawing a shape, set `shapeType` in the same configuration object: `rect` for a rectangle and `ellipse` for an ellipse.
+
+## Hiding the whiteboard and annotation entries
+
+When closing the whiteboard or annotation, call `stopWhiteboard`:
+``` typescript
+const { stopWhiteboard } = useWhiteboardState();
+
+stopWhiteboard();
+```
+
+## Updating the whiteboard display area
+
+When you need to switch the whiteboard to another display area, you can call `updateWhiteboard` and pass in the new element id.
+``` typescript
+const { updateWhiteboard } = useWhiteboardState();
+
+updateWhiteboard({ view: 'whiteboard-new-view' });
+```
+
+## Scope of use
+- Does not yet support mobile browsers and webinar (Webinar) rooms.
+
+- Currently, the initiator draws while other members watch in real time; simultaneous drawing by multiple people is not yet supported.
+
+- The whiteboard and regular screen sharing use the same sharing channel and cannot be enabled at the same time.
+
+## FAQs
+
+### Why is no content displayed on the page after calling `startWhiteboard`?
+
+Please confirm that when calling it you passed the `id` of the display area through `view`, and that the corresponding `<div>` exists on the page. If the element is mounted later, call `updateWhiteboard({ view })` after the whiteboard is started.
+
+### Can the whiteboard and regular screen sharing be enabled at the same time?
+
+No. The whiteboard and regular screen sharing use the same sharing channel; screen sharing annotation, on the other hand, overlays a drawing layer on top of the screen sharing view, which is a supported combination.

package/resource/knowledge/roomkit/faq/error-code.md

@@ -0,0 +1,103 @@
+## Client error codes
+
+### Common error codes
+| Error code | Description |
+| --- | --- |
+| 0 | Operation succeeded |
+| -1 | Uncategorized common error |
+| -2 | The request was rate-limited, please retry later |
+| -1000 | SDKAppID not found, please confirm the application information in the <a href="https://console.cloud.tencent.com/vcube/project/manage">Tencent Cloud VCube SDK console</a> |
+| -1001 | An invalid parameter was passed when calling the API, check whether the input parameters are valid |
+| -1002 | Not logged in, please call the Login interface |
+| -1003 | Failed to obtain permission, the audio/video permission is currently not authorized, check whether the device permission is enabled |
+| -1004 | This feature requires an additional package, please enable the corresponding package as needed in the <a href="https://console.cloud.tencent.com/vcube/project/manage">Tencent Cloud VCube SDK console</a> |
+
+### Error definitions for local user rendering, video management, and audio management API callbacks
+| Error code | Description |
+| --- | --- |
+| -1100 | System problem, failed to open the camera. Check whether the camera device is working properly |
+| -1101 | The camera is not authorized by the system, check the system authorization |
+| -1102 | The camera is occupied, check whether another process is using the camera |
+| -1103 | There is currently no camera device, please plug in a camera device to resolve this problem |
+| -1104 | System problem, failed to open the microphone. Check whether the microphone device is working properly |
+| -1105 | The microphone is not authorized by the system, check the system authorization |
+| -1106 | The microphone is occupied |
+| -1107 | There is currently no microphone device |
+| -1108 | Failed to obtain the screen sharing object, check the screen recording permission |
+| -1109 | Failed to start screen sharing, check whether someone in the room is already sharing their screen |
+
+### Error definitions for room management related API callbacks
+| Error code | Description |
+| --- | --- |
+| -2100 | The room does not exist when entering, or it may have been dismissed |
+| -2101 | You must enter the room before using this feature |
+| -2102 | The room owner does not support the exit-room operation. Conference room type: you can transfer ownership first, then exit. LivingRoom (live) room type: the room owner can only dismiss the room |
+| -2103 | This operation is not supported for the current room type |
+| -2104 | This operation is not supported in the current speaking mode |
+| -2105 | Illegal room ID for creating a room, a custom ID must be printable ASCII characters (0x20-0x7e), up to 48 bytes |
+| -2106 | The room ID is already in use, please choose another room ID |
+| -2107 | Illegal room name, the name is up to 30 bytes, the character encoding must be UTF-8, if it contains Chinese |
+| -2108 | The current user is already in another room. A single roomEngine instance only supports the user entering one room. To enter a different room, exit first or use a new roomEngine instance |
+
+### Error definitions for in-room user information API callbacks
+| Error code | Description |
+| --- | --- |
+| -2200 | The user was not found |
+| -2201 | The user was not found in the room |
+
+### Error definitions for in-room user speaking management API callbacks & in-room seat management API callbacks
+| Error code | Description |
+| --- | --- |
+| -2300 | Room owner permission is required to operate |
+| -2301 | Room owner or administrator permission is required to operate |
+| -2310 | No permission for the signaling request, e.g. canceling an invitation not initiated by yourself. |
+| -2311 | The signaling request ID is invalid or has already been processed. |
+| -2340 | The maximum number of seats exceeds the package limit |
+| -2341 | The current user is already on a seat |
+| -2342 | The current seat is already occupied |
+| -2343 | The current seat is locked |
+| -2344 | The seat number does not exist |
+| -2345 | The current user is not on a seat |
+| -2346 | The number of people on seats is full |
+| -2360 | The audio of the current seat is locked |
+| -2361 | You need to apply to the room owner or administrator to turn on the microphone |
+| -2370 | The video of the current seat is locked, the camera can be turned on only after the room owner unlocks the seat |
+| -2371 | You need to apply to the room owner or administrator to turn on the camera |
+| -2380 | The current room has enabled mute all |
+| -2381 | You have been muted in the current room |
+
+## Server error codes
+| Error code | Description |
+| --- | --- |
+| 83007 | The request was rate-limited |
+| 84002 | The room does not exist |
+| 84003 | The number of people in the room has exceeded the maximum package limit |
+| 84004 | The user does not exist in the room |
+| 84005 | The room already exists |
+| 84006 | The room owner cannot exit the room |
+| 85001 | The seats are full |
+| 85002 | The seat is locked |
+| 85003 | The user is already on a seat |
+| 85004 | The seat is in use |
+| 85005 | The seat number does not exist |
+| 85006 | The seat audio is locked |
+| 85007 | The seat video is locked |
+| 85008 | Seats cannot be used in non-live scenarios |
+| 87001 | Modifying member identity or room information is not allowed |
+| 87002 | Insufficient permission, room owner or administrator identity is required |
+| 87003 | IM group attribute update error |
+| 87005 | IM group attribute retrieval exception |
+| 87006 | Insufficient permission, only the room owner can operate |
+| 87007 | Insufficient permission, only an administrator can operate |
+| 87008 | Destroying the IM room is not allowed |
+| 41001 | Error creating the IM group |
+| 41002 | Error destroying the IM group |
+| 41003 | Error adding an IM member |
+| 41004 | Error deleting an IM member |
+| 41005 | IM role change error |
+| 42001 | Error scheduling the meeting |
+| 42002 | Invalid scheduled meeting |
+| 42003 | A scheduled meeting must be a conference scenario |
+| 42004 | The scheduled meeting has not started |
+| 42005 | The scheduled meeting has already started |
+| 42006 | Too many invited members for the scheduled meeting, exceeding the count limit |