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

package/resource/knowledge/livekit/core-sdk/api-reference/android/DeviceStore.md

@@ -0,0 +1,466 @@
+## Introduction
+
+`DeviceStore` provides a comprehensive set of APIs to manage audio and video devices, including microphone, camera and screen sharing features.
+
+> **Important: **
+>
+
+> Use **DeviceStore.shared** singleton to get the `DeviceStore` instance. Do not attempt to initialize directly.
+>
+
+> **Note: **
+>
+
+> Device state updates are delivered through the **deviceState** publisher. Subscribe to it to receive real-time updates about microphone, camera, network and other states.
+>
+
+## Features
+- **Microphone Management**: Open/close microphone, set capture volume and output volume.
+
+- **Camera Management**: Open/close camera, switch front/rear camera, set mirror and video quality.
+
+- **Audio Route**: Switch between speaker and earpiece.
+
+- **Screen Sharing**: Start and stop screen sharing feature.
+
+- **Network Status**: Real-time monitoring of network quality information.
+
+## Subscribable Data
+
+**DeviceState** fields are described below:
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|microphoneStatus|StateFlow<DeviceStatus>|Microphone status.|
+|microphoneLastError|StateFlow<DeviceError>|Microphone error, used to extract error information when an error occurs.|
+|captureVolume|StateFlow<Int>|Capture volume, with a value range from 0 to 100.|
+|currentMicVolume|StateFlow<Int>|Current user's actual output volume.|
+|outputVolume|StateFlow<Int>|Maximum output volume, with a value range from 0 to 100.|
+|cameraStatus|StateFlow<DeviceStatus>|Camera status.|
+|cameraLastError|StateFlow<DeviceError>|Camera error, used to extract error information when an error occurs.|
+|isFrontCamera|StateFlow<Boolean>|Whether it's front camera.|
+|localMirrorType|StateFlow<MirrorType>|Mirror state.|
+|localVideoQuality|StateFlow<VideoQuality>|Local video quality.|
+|currentAudioRoute|StateFlow<AudioRoute>|Current audio route location.|
+|screenStatus|StateFlow<DeviceStatus>|Screen sharing status.|
+|networkInfo|StateFlow<NetworkInfo>|Network information.|
+|networkType|StateFlow<NetworkType>|Current network type.|
+
+## API List
+
+|**Function**|**Description**|
+|---------|---------|
+|DeviceStore.shared|Singleton object.|
+|openLocalMicrophone|Open local microphone.|
+|closeLocalMicrophone|Close local microphone.|
+|setCaptureVolume|Set capture volume.|
+|setOutputVolume|Set output volume.|
+|setAudioRoute|Set audio route.|
+|startCameraTest|Start camera test.|
+|stopCameraTest|Stop camera test.|
+|openLocalCamera|Open local camera.|
+|closeLocalCamera|Close local camera.|
+|switchCamera|Switch camera.|
+|switchMirror|Switch mirror state.|
+|updateVideoQuality|Update video quality.|
+|startScreenShare|Start screen sharing.|
+|stopScreenShare|Stop screen sharing.|
+|reset|Reset to default state.|
+
+### Getting Instance
+
+#### DeviceStore.shared
+
+Singleton object.
+
+### Microphone Operations
+
+#### openLocalMicrophone
+
+Open local microphone.
+``` kotlin
+abstract fun openLocalMicrophone(completion: CompletionHandler?)
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|completion|CompletionHandler?|Whether operation succeeded.|
+
+#### closeLocalMicrophone
+
+Close local microphone.
+``` kotlin
+abstract fun closeLocalMicrophone()
+```
+
+**Version**
+
+Supported since version 3.5.
+
+#### setCaptureVolume
+
+Set capture volume.
+``` kotlin
+abstract fun setCaptureVolume(volume: Int)
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|volume|Int|Capture volume, with a value range from 0 to 100.|
+
+#### setOutputVolume
+
+Set maximum output volume.
+``` kotlin
+abstract fun setOutputVolume(volume: Int)
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|volume|Int|Maximum volume, with a value range from 0 to 100.|
+
+### Audio Route
+
+#### setAudioRoute
+
+Set audio route.
+``` kotlin
+abstract fun setAudioRoute(audioRoute: AudioRoute)
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|audioRoute|AudioRoute|Route location.|
+
+### Camera Operations
+
+#### startCameraTest
+
+Start camera test, if camera opens successfully, the view will be rendered to the set CameraView.
+``` kotlin
+abstract fun startCameraTest(cameraView: CameraView, completion: CompletionHandler?)
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|cameraView|CameraView|Rendering view for camera capture.|
+|completion|CompletionHandler?|Whether operation succeeded.|
+
+#### stopCameraTest
+
+Stop camera test.
+``` kotlin
+abstract fun stopCameraTest()
+```
+
+**Version**
+
+Supported since version 3.5.
+
+#### openLocalCamera
+
+Open local camera.
+``` kotlin
+abstract fun openLocalCamera(isFront: Boolean, completion: CompletionHandler?)
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|isFront|Boolean|Whether front camera.|
+|completion|CompletionHandler?|Whether operation succeeded.|
+
+#### closeLocalCamera
+
+Close local camera.
+``` kotlin
+abstract fun closeLocalCamera()
+```
+
+**Version**
+
+Supported since version 3.5.
+
+#### switchCamera
+
+Switch camera.
+``` kotlin
+abstract fun switchCamera(isFront: Boolean)
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|isFront|Boolean|Whether front camera.|
+
+#### switchMirror
+
+Switch mirror state.
+``` kotlin
+abstract fun switchMirror(mirrorType: MirrorType)
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|mirrorType|MirrorType|Mirror state.|
+
+#### updateVideoQuality
+
+Update video quality.
+``` kotlin
+abstract fun updateVideoQuality(quality: VideoQuality)
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|quality|VideoQuality|Video quality.|
+
+### Screen Sharing
+
+#### startScreenShare
+
+Start screen sharing.
+``` kotlin
+abstract fun startScreenShare()
+```
+
+**Version**
+
+Supported since version 3.5.
+
+#### stopScreenShare
+
+Stop screen capture.
+``` kotlin
+abstract fun stopScreenShare()
+```
+
+**Version**
+
+Supported since version 3.5.
+
+### Reset
+
+#### reset
+
+Reset to default state.
+``` kotlin
+abstract fun reset()
+```
+
+**Version**
+
+Supported since version 3.5.
+
+## Data Structures
+
+### DeviceType
+
+Device type.
+
+|**Enum Value**|**Value**|**Description**|
+|---------|---------|---------|
+|MICROPHONE|0|Microphone type.|
+|CAMERA|1|Camera type.|
+|SCREEN_SHARE|2|Screen sharing type.|
+
+### DeviceError
+
+Device related error codes.
+
+|**Enum Value**|**Value**|**Description**|
+|---------|---------|---------|
+|NO_ERROR|0|Operation successful.|
+|NO_DEVICE_DETECTED|1|No device detected.|
+|NO_SYSTEM_PERMISSION|2|No system permission.|
+|NOT_SUPPORT_CAPTURE|3|Capture not supported.|
+|OCCUPIED_ERROR|4|Device occupied.|
+|UNKNOWN_ERROR|5|Unknown error.|
+
+### DeviceStatus
+
+Device on/off status.
+
+|**Enum Value**|**Value**|**Description**|
+|---------|---------|---------|
+|OFF|0|Off.|
+|ON|1|On.|
+
+### AudioRoute
+
+Audio route.
+
+|**Enum Value**|**Value**|**Description**|
+|---------|---------|---------|
+|SPEAKERPHONE|0|Speaker, using speaker to play (i.e., "hands-free"), located at the bottom of the phone, louder sound, suitable for playing music out loud.|
+|EARPIECE|1|Earpiece, using earpiece to play, located at the top of the phone, quieter sound, suitable for private call scenarios.|
+
+### VideoQuality
+
+Video quality level.
+
+|**Enum Value**|**Value**|**Description**|
+|---------|---------|---------|
+|QUALITY_360P|1|360P, resolution 640 x 360.|
+|QUALITY_540P|2|540P, resolution 960 x 540.|
+|QUALITY_720P|3|720P, resolution 1280 x 720.|
+|QUALITY_1080P|4|1080P, resolution 1920 x 1080.|
+
+### NetworkQuality
+
+Network quality.
+
+|**Enum Value**|**Value**|**Description**|
+|---------|---------|---------|
+|UNKNOWN|0|Unknown network.|
+|EXCELLENT|1|Excellent.|
+|GOOD|2|Good.|
+|POOR|3|Poor.|
+|BAD|4|Bad.|
+|VERY_BAD|5|Very bad.|
+|DOWN|6|Disconnected.|
+
+### MirrorType
+
+Camera mirror state.
+
+|**Enum Value**|**Value**|**Description**|
+|---------|---------|---------|
+|AUTO|0|Auto, front camera mirrored, rear camera not mirrored.|
+|ENABLE|1|Both front and rear cameras mirrored.|
+|DISABLE|2|Neither front nor rear camera mirrored.|
+
+### NetworkType
+
+Network type.
+
+|**Enum Value**|**Value**|**Description**|
+|---------|---------|---------|
+|UNKNOWN|0|Unknown or unidentified network type.|
+|WIFI|1|WiFi network connection.|
+|CELLULAR|2|Cellular/mobile data network connection.|
+
+### DeviceFocusOwner
+
+Device focus.
+
+|**Enum Value**|**Description**|
+|---------|---------|
+|call|Voice call scenario.|
+|live|Live streaming scenario.|
+|room|Room scenario.|
+|none|Not set.|
+
+### NetworkInfo
+
+Network information.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|userID|String|User unique ID.|
+|quality|NetworkQuality|Network quality.|
+|upLoss|Int|Uplink packet loss rate, with a value range from 0 to 100.|
+|downLoss|Int|Downlink packet loss rate, with a value range from 0 to 100.|
+|delay|Int|Latency (unit: milliseconds).|
+
+### DeviceState
+
+Device state.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|microphoneStatus|StateFlow<DeviceStatus>|Microphone status.|
+|microphoneLastError|StateFlow<DeviceError>|Microphone error, used to extract error information when an error occurs.|
+|captureVolume|StateFlow<Int>|Capture volume, with a value range from 0 to 100.|
+|currentMicVolume|StateFlow<Int>|Current user's actual output volume.|
+|outputVolume|StateFlow<Int>|Maximum output volume, with a value range from 0 to 100.|
+|cameraStatus|StateFlow<DeviceStatus>|Camera status.|
+|cameraLastError|StateFlow<DeviceError>|Camera error, used to extract error information when an error occurs.|
+|isFrontCamera|StateFlow<Boolean>|Whether it's front camera.|
+|localMirrorType|StateFlow<MirrorType>|Mirror state.|
+|localVideoQuality|StateFlow<VideoQuality>|Local video quality.|
+|currentAudioRoute|StateFlow<AudioRoute>|Current audio route location.|
+|screenStatus|StateFlow<DeviceStatus>|Screen sharing status.|
+|networkInfo|StateFlow<NetworkInfo>|Network information.|
+|networkType|StateFlow<NetworkType>|Current network type.|
+
+## Usage Example
+``` kotlin
+// Get singleton instance
+val store = DeviceStore.shared()
+// Subscribe to state changes
+lifecycleScope.launch {
+    store.deviceState.microphoneStatus.collect { status ->
+        println("Microphone status: $status")
+    }
+}
+lifecycleScope.launch {
+    store.deviceState.cameraStatus.collect { status ->
+        println("Camera status: $status")
+    }
+}
+// Open microphone
+store.openLocalMicrophone { code, message ->
+    if (code == 0) {
+        println("Microphone opened successfully")
+    }
+}
+// Open front camera
+store.openLocalCamera(isFront = true) { code, message ->
+    if (code == 0) {
+        println("Camera opened successfully")
+    }
+}
+```

package/resource/knowledge/livekit/core-sdk/api-reference/android/GiftStore.md

@@ -0,0 +1,173 @@
+## Introduction
+
+`GiftStore` provides a complete set of gift management APIs, including sending gifts, refreshing gift lists, setting language, and listening to gift events. Through this class, gift interaction features can be implemented in live rooms.
+
+> **Important: **
+>
+
+> Use the **GiftStore.create** factory method to create a `GiftStore` instance, passing a valid live room ID.
+>
+
+> **Note: **
+>
+
+> Gift state updates are delivered through the **giftState** publisher. Subscribe to it to receive real-time updates of gift data in the room.
+>
+
+## Features
+- **Gift Sending**: Support sending specified gifts to the current room.
+
+- **Gift List**: Get and refresh the available gift list in the current room.
+
+- **Language Setting**: Set the display language for gift information.
+
+- **Event Listening**: Listen to gift receiving events.
+
+## Subscribable Data
+
+**GiftState** fields are described below:
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|usableGifts|StateFlow<List<GiftCategory>>|All gift categories and gift lists available in the current room.|
+
+## API List
+
+|**Function**|**Description**|
+|---------|---------|
+|GiftStore.create|Create gift management instance.|
+|addGiftListener|Gift event callbacks.|
+|removeGiftListener|Gift event callbacks.|
+|sendGift|Send gift.|
+|refreshUsableGifts|Refresh available gift list.|
+|setLanguage|Set display language.|
+
+### Creating Instance
+
+#### GiftStore.create
+
+Create gift management instance.
+
+### Observing State and Events
+
+#### addGiftListener
+
+Gift event callbacks.
+
+#### removeGiftListener
+
+Gift event callbacks.
+
+### Gift Operations
+
+#### sendGift
+
+Send a specified gift to the current room.
+``` kotlin
+abstract fun sendGift(
+        giftID: String,
+        count: Int,
+        completion: CompletionHandler?
+    )
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|giftID|String|Unique identifier ID of the gift to send.|
+|count|Int|Number of gifts to send at once.|
+|completion|CompletionHandler?|Completion callback (success/failure status).|
+
+#### refreshUsableGifts
+
+Manually refresh the available gift list in the current room.
+``` kotlin
+abstract fun refreshUsableGifts(completion: CompletionHandler?)
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|completion|CompletionHandler?|Completion callback (on success, the latest gift list can be obtained through state; on failure, error information is returned).|
+
+#### setLanguage
+
+Set the display language for gift information.
+``` kotlin
+abstract fun setLanguage(language: String)
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|language|String|Language code ("zh-CN" for Chinese, "en" for English). After setting, gift names, descriptions, etc. will be updated to the corresponding language when the display interface is refreshed.|
+
+## Data Structures
+
+### Gift
+
+Gift data model, containing complete attribute information of a single gift.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|giftID|String|Gift ID.|
+|name|String|Gift name.|
+|desc|String|Gift description.|
+|iconURL|String|Network URL of the gift icon image, used to load gift thumbnails.|
+|resourceURL|String|Network URL of the gift animation resource file, used to load gift display animations.|
+|level|Long|Gift level, used to distinguish gift rarity or value tier.|
+|coins|Long|Gift price (coins).|
+|extensionInfo|Map<String,String>|Gift extension information, customizable fields (such as effect type, sending restrictions, etc.).|
+
+### GiftCategory
+
+Gift category.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|categoryID|String|Category unique identifier ID, used to distinguish different gift categories.|
+|name|String|Category display name, used for UI category display (such as "Popular Gifts", "Premium Gifts").|
+|desc|String|Category description information, used to explain the characteristics of this category.|
+|extensionInfo|Map<String,String>|Category extension information, containing custom fields (such as sorting weight, display style, etc.).|
+|giftList|List<Gift>|All gifts under the current category.|
+
+### GiftState
+
+Gift state, managing the gift data state of the current room, supporting real-time updates and subscription listening.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|usableGifts|StateFlow<List<GiftCategory>>|All gift categories and gift lists available in the current room.|
+
+### GiftListener
+
+Gift event, used to receive gift dynamics in live rooms/voice chat rooms.
+
+**Methods**
+
+**onReceiveGift**: Event callback when receiving a new gift message. This event is triggered when other viewers send gifts in the live room/voice chat room, returning relevant information.
+``` kotlin
+open fun onReceiveGift(liveID: String, gift: Gift, count: Int, sender: LiveUserInfo) {}
+```
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|liveID|String|Live room ID.|
+|gift|Gift|Gift information.|
+|count|Int|Gift count.|
+|sender|LiveUserInfo|Gift sender information.|

package/resource/knowledge/livekit/core-sdk/api-reference/android/LikeStore.md

@@ -0,0 +1,51 @@
+## Introduction
+
+`LikeStore` provides a complete set of like management APIs, including sending likes, listening to like events, and getting like states. Through this class, you can implement like interaction features in live rooms.
+
+> **Important: **
+>
+
+> Use the **LikeStore.create** factory method to create a `LikeStore` instance, which requires a valid live room ID.
+>
+
+> **Note: **
+>
+
+> Like state updates are delivered through the **likeState** publisher. Subscribe to it to receive real-time updates of like data in the room.
+>
+
+## Features
+- **Like Sending**: Support sending likes to the current room.
+
+- **Like State**: Get the accumulated like count of the current room.
+
+- **Event Listening**: Listen to like receiving events.
+
+## Data Structures
+
+### LikeState
+
+Like state, used to display and subscribe to like information in live rooms/voice chat rooms.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|totalLikeCount|StateFlow<Long>|Total accumulated like count of the current live room/voice chat room, supporting real-time updates and subscription listening.|
+
+### LikeListener
+
+Like event, used to receive like dynamics in live rooms/voice chat rooms.
+
+This listener is used to receive like dynamics in live rooms/voice chat rooms.
+
+**Methods**
+
+**onReceiveLikesMessage**: Event callback for receiving new like messages. When other audiences send likes in the live room/voice chat room, this event will be triggered and return relevant information.
+``` kotlin
+open fun onReceiveLikesMessage(liveID: String, totalLikesReceived: Long, sender: LiveUserInfo) {}
+```
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|liveID|String|Live room ID.|
+|totalLikesReceived|Long|Number of new likes received this time.|
+|sender|LiveUserInfo|Like sender information.|