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

package/resource/knowledge/livekit/core-sdk/api-reference/flutter/AudioEffectStore.md

@@ -0,0 +1,282 @@
+## Introduction
+
+`AudioEffectStore` provides a complete set of audio effect management APIs, including voice changer effects, reverb effects, and ear monitor functionality. Through this class, anchors can adjust their voice effects in real-time during live streaming to enhance the experience.
+
+> **Important: **
+>
+
+> Use the **shared** singleton to get the `AudioEffectStore` instance. The set effects will automatically become invalid after leaving the room, and need to be set again for the next room entry.
+>
+
+> **Note: **
+>
+
+> Audio effect state updates are delivered through the **audioEffectState** publisher. Subscribe to it to receive real-time updates about voice changer, reverb, and ear monitor states.
+>
+
+> **Warning: **
+>
+
+> Due to the very high hardware latency of Bluetooth earphones, the ear monitor feature cannot be enabled when the anchor is wearing Bluetooth earphones. Please prompt the anchor to wear wired earphones in the user interface.
+>
+
+## Features
+- **Voice Changer Effects**: Supports multiple voice changer effects such as child, little girl, uncle, etc.
+
+- **Reverb Effects**: Supports multiple reverb effects such as KTV, small room, auditorium, etc.
+
+- **Ear Monitor**: Anchors can hear their own voice in earphones, suitable for singing scenarios.
+
+- **Volume Control**: Supports fine-grained ear monitor volume adjustment.
+
+## Subscribable Data
+
+**AudioEffectState** fields are described below:
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|audioChangerType|ValueListenable<AudioChangerType>|Voice changer state.|
+|audioReverbType|ValueListenable<AudioReverbType>|Reverb state.|
+|isEarMonitorOpened|ValueListenable<bool>|Ear monitor enabled.|
+|earMonitorVolume|ValueListenable<int>|Ear monitor volume, with a value range from 0 to 100.<br>If the volume is still too low after setting it to 100, you can set the volume to a maximum of 150, but a volume exceeding 100 may cause distortion, please operate with caution.|
+
+## API List
+
+|**Function**|**Description**|
+|---------|---------|
+|shared|Get singleton instance.|
+|setAudioChangerType|Set voice changer effect.|
+|setAudioReverbType|Set reverb effect.|
+|setVoiceEarMonitorEnable|Enable/disable ear monitor.|
+|setVoiceEarMonitorVolume|Set ear monitor volume.|
+|reset|Reset to default state.|
+
+### Getting Instance
+
+#### shared
+
+Get singleton instance.
+
+### Voice Changer Settings
+
+#### setAudioChangerType
+
+Set voice changer effect.
+``` dart
+void setAudioChangerType(AudioChangerType type);
+```
+
+Through this interface, you can set the voice changer effect for human voice.
+
+Voice changer effects can be applied to human voice, and the voice is processed secondarily through acoustic algorithms to obtain a timbre different from the original sound.
+
+**Version**
+
+Supported since version 3.5.
+
+**When to Call**
+
+Call after entering the room and when voice changer effect is needed.
+
+**Notes**
+
+> **Note: **
+>
+
+> The set effect will automatically become invalid after leaving the room. If you need the corresponding effect for the next room entry, you need to call this interface again to set it.
+>
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|type|AudioChangerType|Voice changer effect type.|
+
+### Reverb Settings
+
+#### setAudioReverbType
+
+Set reverb effect.
+``` dart
+void setAudioReverbType(AudioReverbType type);
+```
+
+Through this interface, you can set the reverb effect for human voice.
+
+Reverb effects can be applied to human voice, and the sound is processed through acoustic algorithms to simulate the presence in various different environments.
+
+**Version**
+
+Supported since version 3.5.
+
+**When to Call**
+
+Call after entering the room and when reverb effect is needed.
+
+**Notes**
+
+> **Note: **
+>
+
+> The set effect will automatically become invalid after leaving the room. If you need the corresponding effect for the next room entry, you need to call this interface again to set it.
+>
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|type|AudioReverbType|Reverb effect type.|
+
+### Ear Monitor Settings
+
+#### setVoiceEarMonitorEnable
+
+Enable/disable ear monitor.
+``` dart
+void setVoiceEarMonitorEnable(bool enable);
+```
+
+After the anchor enables ear monitor, they can hear their own voice captured by the microphone in the earphones. This effect is suitable for anchor singing application scenarios.
+
+**Version**
+
+Supported since version 3.5.
+
+**Use Cases**
+
+Suitable for anchor singing scenarios, allowing anchors to hear their own voice in real time to adjust their singing performance.
+
+**When to Call**
+
+Call after entering the room and when the anchor is wearing wired earphones.
+
+**Notes**
+
+> **Warning: **
+>
+
+> Due to the very high hardware latency of Bluetooth earphones, this effect cannot be enabled when the anchor is wearing Bluetooth earphones. Please try to prompt the anchor to wear wired earphones in the user interface.
+>
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|enable|bool|Whether to enable ear monitor.|
+
+#### setVoiceEarMonitorVolume
+
+Set ear monitor volume.
+``` dart
+void setVoiceEarMonitorVolume(int volume);
+```
+
+Through this interface, you can set the volume of the sound in the ear monitor effect.
+
+**Version**
+
+Supported since version 3.5.
+
+**When to Call**
+
+Call after enabling the ear monitor feature.
+
+**Notes**
+
+> **Note: **
+>
+
+> If the volume is still too low after setting it to 100, you can set the volume to a maximum of 150, but a volume exceeding 100 may cause distortion, please operate with caution.
+>
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|volume|int|Ear monitor volume, with a value range from 0 to 100. (Range: Value range from 0 to 100, exceeding 100 may cause distortion) (Default: 100).|
+
+### Reset
+
+#### reset
+
+Reset to default state.
+``` dart
+void reset();
+```
+
+Reset all audio effect settings to default values, including disabling voice changer effect, disabling reverb effect, disabling ear monitor, and resetting ear monitor volume.
+
+**Version**
+
+Supported since version 3.5.
+
+**When to Call**
+
+Call when you need to restore the default audio effect settings, for example before leaving the live room.
+
+## Data Structures
+
+### AudioChangerType
+
+Voice changer effect type.
+
+|**Enum Value**|**Value**|**Description**|
+|---------|---------|---------|
+|none|0|Disable effect.|
+|child|1|Child.|
+|littleGirl|2|Little girl.|
+|man|3|Uncle.|
+|heavyMetal|4|Heavy metal.|
+|cold|5|Cold.|
+|foreigner|6|Foreign accent.|
+|trappedBeast|7|Trapped beast.|
+|fatso|8|Otaku.|
+|strongCurrent|9|Strong current.|
+|heavyMachinery|10|Heavy machinery.|
+|ethereal|11|Ethereal.|
+
+### AudioReverbType
+
+Reverb effect type.
+
+|**Enum Value**|**Value**|**Description**|
+|---------|---------|---------|
+|none|0|Disable effect.|
+|ktv|1|KTV.|
+|smallRoom|2|Small room.|
+|auditorium|3|Auditorium.|
+|deep|4|Deep.|
+|loud|5|Loud.|
+|metallic|6|Metallic.|
+|magnetic|7|Magnetic.|
+
+### AudioEffectState
+
+Audio effect related state data provided by AudioEffectStore.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|audioChangerType|ValueListenable<AudioChangerType>|Voice changer state.|
+|audioReverbType|ValueListenable<AudioReverbType>|Reverb state.|
+|isEarMonitorOpened|ValueListenable<bool>|Ear monitor enabled.|
+|earMonitorVolume|ValueListenable<int>|Ear monitor volume, with a value range from 0 to 100.<br>If the volume is still too low after setting it to 100, you can set the volume to a maximum of 150, but a volume exceeding 100 may cause distortion, please operate with caution.|
+
+## Usage Example
+``` dart
+// Get singleton instance
+final store = AudioEffectStore.shared;
+// Subscribe to state changes
+store.audioEffectState.audioChangerType.addListener(() {
+    print("Current voice changer: ${store.audioEffectState.audioChangerType.value}");
+});
+store.audioEffectState.audioReverbType.addListener(() {
+    print("Current reverb: ${store.audioEffectState.audioReverbType.value}");
+});
+// Set voice changer effect
+store.setAudioChangerType(AudioChangerType.littleGirl);
+// Set reverb effect
+store.setAudioReverbType(AudioReverbType.ktv);
+// Enable ear monitor
+store.setVoiceEarMonitorEnable(true);
+store.setVoiceEarMonitorVolume(80);
+```

package/resource/knowledge/livekit/core-sdk/api-reference/flutter/BarrageStore.md

@@ -0,0 +1,212 @@
+## Introduction
+
+`BarrageStore` provides a complete set of barrage management APIs, including sending text barrages, sending custom barrages, and adding local tip messages. Through this class, you can implement barrage interaction functionality in live rooms.
+
+> **Important: **
+>
+
+> Use the **create** factory method to create a `BarrageStore` instance, which requires a valid live room ID.
+>
+
+> **Note: **
+>
+
+> Barrage state updates are delivered through the **barrageState** publisher. Subscribe to it to receive real-time updates of barrage data in the room.
+>
+
+## Features
+- **Text Barrage**: Supports sending plain text barrage messages.
+
+- **Custom Barrage**: Supports sending custom format barrages (such as barrages with special effects).
+
+- **Local Tips**: Supports adding tip messages visible only locally.
+
+## Subscribable Data
+
+**BarrageState** fields are described below:
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|messageList|ValueListenable<List<Barrage>>|Barrage message list of the current room, supports real-time updates and can be subscribed to.|
+
+## API List
+
+|**Function**|**Description**|
+|---------|---------|
+|create|Create barrage management instance.|
+|addBarrageListener|Add barrage event listener to receive custom messages.|
+|removeBarrageListener|Remove barrage event listener.|
+|sendTextMessage|Send text barrage.|
+|sendCustomMessage|Send custom barrage.|
+|appendLocalTip|Add local tip message.|
+
+### Creating Instance
+
+#### create
+
+Barrage management core class for handling barrage related business logic in live rooms/voice chat rooms.
+``` dart
+static BarrageStore create(String liveID) {
+  return StoreFactory.shared.getStore<BarrageStore>(roomID: liveID);
+}
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|liveID|String|Live room ID.|
+
+### Events Handling
+
+#### addBarrageListener
+
+Add barrage event listener.
+``` dart
+void addBarrageListener(BarrageListener listener);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|listener|BarrageListener|Barrage event listener instance.|
+
+#### removeBarrageListener
+
+Remove barrage event listener.
+``` dart
+void removeBarrageListener(BarrageListener listener);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|listener|BarrageListener|Barrage event listener instance to be removed.|
+
+### Sending Barrage
+
+#### sendTextMessage
+
+Send a text type barrage. After sending successfully, the receiver can obtain barrage messages by subscribing to messageList in BarrageState in advance.
+``` dart
+Future<CompletionHandler> sendTextMessage({
+  required String text,
+  Map<String, String>? extensionInfo,
+});
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|text|String|Text barrage content.|
+|extensionInfo|Map<String,String>?|Extension information, can contain custom fields (such as specifying barrage color, font size, etc.).|
+
+#### sendCustomMessage
+
+Send a custom type barrage message. After sending successfully, the receiver can receive custom messages by subscribing to the addBarrageListener provided by BarrageStore.
+``` dart
+Future<CompletionHandler> sendCustomMessage({
+  required String businessID,
+  required String data,
+});
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|businessID|String|Business identifier ID, used to distinguish custom barrages from different business scenarios.|
+|data|String|Custom data content, usually JSON format string, used to pass business custom data.|
+
+### Local Messages
+
+#### appendLocalTip
+
+Add local tip message (add tip or operation feedback message locally, visible only to the current client).
+``` dart
+void appendLocalTip(Barrage message);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Notes**
+
+> **Note: **
+>
+
+> This message is only displayed locally and will not be sent to other users through the network.
+>
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|message|Barrage|Local barrage message (such as system tips, operation feedback, etc., visible only to the current user).|
+
+## Data Structures
+
+### BarrageType
+
+Barrage type enumeration, used to distinguish different barrage message types.
+
+|**Enum Value**|**Value**|**Description**|
+|---------|---------|---------|
+|text|0|Text type barrage, contains plain text content.|
+|custom|1|Custom type barrage, supports business custom data format (such as barrages with special effects, interactive messages, etc.).|
+
+### Barrage
+
+Barrage data model, containing complete attribute information of a single barrage.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|liveID|String|Unique identifier ID of the live room/voice chat room the barrage belongs to.|
+|sender|LiveUserInfo|User information of the barrage sender (such as user ID, nickname, avatar, etc.).|
+|sequence|int|Unique sequence ID of the barrage message, used for message sorting and deduplication.|
+|timestampInSecond|int|Barrage sending timestamp (unit: seconds), used to display sending time order.|
+|messageType|BarrageType|Barrage message type (text or custom).|
+|textContent|String|Message content of text type barrage, i.e., the text content of the barrage.|
+|extensionInfo|Map<String,String>|Barrage extension information, customizable fields (such as display style, priority, etc.). Valid when messageType is TEXT.|
+|businessID|String|Business identifier ID of custom type barrage, used to distinguish custom barrages from different business scenarios.|
+|data|String|Specific data content of custom type barrage (usually JSON format string), valid when messageType is CUSTOM.|
+
+### BarrageState
+
+Barrage state, managing the barrage data state of the current room.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|messageList|ValueListenable<List<Barrage>>|Barrage message list of the current room, supports real-time updates and can be subscribed to.|
+
+### BarrageListener
+
+Barrage event listener.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|onCustomMessageReceived|voidFunction(Barrage)?|Callback triggered when a custom barrage message is received.|

package/resource/knowledge/livekit/core-sdk/api-reference/flutter/BaseBeautyStore.md

@@ -0,0 +1,153 @@
+## Introduction
+
+Basic beauty functionality achieves real-time beauty effect adjustment through easy-to-use APIs. `BaseBeautyStore` provides a complete set of interfaces to manage beauty effect settings and state subscriptions.
+
+> **Note: **
+>
+
+> Beauty state updates are delivered through the **baseBeautyState** publisher. Subscribe to it to receive real-time updates about beauty effect levels.
+>
+
+## Features
+- **Smooth Effect**: Supports 0-9 level smooth effect adjustment.
+
+- **Whiteness Effect**: Supports 0-9 level whiteness effect adjustment.
+
+- **Ruddy Effect**: Supports 0-9 level ruddy effect adjustment.
+
+- **State Subscription**: Real-time subscription to beauty state changes, synchronizing UI display with actual effects.
+
+## Subscribable Data
+
+**BaseBeautyState** fields are described below:
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|smoothLevel|ValueListenable<double>|Smooth level, with a value range from 0 to 9; 0 means off, 9 means most obvious effect.|
+|whitenessLevel|ValueListenable<double>|Whiteness level, with a value range from 0 to 9; 0 means off, 9 means most obvious effect.|
+|ruddyLevel|ValueListenable<double>|Ruddy level, with a value range from 0 to 9; 0 means off, 9 means most obvious effect.|
+
+## API List
+
+|**Function**|**Description**|
+|---------|---------|
+|shared|Get singleton instance.|
+|setSmoothLevel|Set smooth level.|
+|setWhitenessLevel|Set whiteness level.|
+|setRuddyLevel|Set ruddy level.|
+|reset|Reset to default state.|
+
+### Getting Instance
+
+#### shared
+
+Get singleton instance.
+
+### Beauty Adjustment
+
+#### setSmoothLevel
+
+Set smooth level.
+``` dart
+void setSmoothLevel(double smoothLevel);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|smoothLevel|double|Smooth level, with a value range from 0 to 9; 0 means off, 9 means most obvious effect.|
+
+#### setWhitenessLevel
+
+Set whiteness level.
+``` dart
+void setWhitenessLevel(double whitenessLevel);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|whitenessLevel|double|Whiteness level, with a value range from 0 to 9; 0 means off, 9 means most obvious effect.|
+
+#### setRuddyLevel
+
+Set ruddy level.
+``` dart
+void setRuddyLevel(double ruddyLevel);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|ruddyLevel|double|Ruddy level, with a value range from 0 to 9; 0 means off, 9 means most obvious effect.|
+
+#### reset
+
+Reset all beauty parameters (smooth, whiteness, ruddy) to default off state (value 0).
+``` dart
+void reset();
+```
+
+**Version**
+
+Supported since version 3.5.
+
+## Data Structures
+
+### BaseBeautyState
+
+Basic beauty state, managing the level data of smooth, whiteness, ruddy and other beauty effects. Supports subscription to synchronize UI display with actual effects.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|smoothLevel|ValueListenable<double>|Smooth level, with a value range from 0 to 9; 0 means off, 9 means most obvious effect.|
+|whitenessLevel|ValueListenable<double>|Whiteness level, with a value range from 0 to 9; 0 means off, 9 means most obvious effect.|
+|ruddyLevel|ValueListenable<double>|Ruddy level, with a value range from 0 to 9; 0 means off, 9 means most obvious effect.|
+
+## Usage Example
+``` dart
+// Get singleton instance
+final store = BaseBeautyStore.shared;
+// Define listeners
+late final VoidCallback smoothLevelListener = _onSmoothLevelChanged;
+late final VoidCallback whitenessLevelListener = _onWhitenessLevelChanged;
+late final VoidCallback ruddyLevelListener = _onRuddyLevelChanged;
+void _onSmoothLevelChanged() {
+    print('Smooth level: ${store.baseBeautyState.smoothLevel.value}');
+}
+void _onWhitenessLevelChanged() {
+    print('Whiteness level: ${store.baseBeautyState.whitenessLevel.value}');
+}
+void _onRuddyLevelChanged() {
+    print('Ruddy level: ${store.baseBeautyState.ruddyLevel.value}');
+}
+// Subscribe to state changes
+store.baseBeautyState.smoothLevel.addListener(smoothLevelListener);
+store.baseBeautyState.whitenessLevel.addListener(whitenessLevelListener);
+store.baseBeautyState.ruddyLevel.addListener(ruddyLevelListener);
+// Set beauty effects
+store.setSmoothLevel(5.0);
+store.setWhitenessLevel(3.0);
+store.setRuddyLevel(2.0);
+// Reset all beauty effects
+store.reset();
+// Unsubscribe when done
+store.baseBeautyState.smoothLevel.removeListener(smoothLevelListener);
+store.baseBeautyState.whitenessLevel.removeListener(whitenessLevelListener);
+store.baseBeautyState.ruddyLevel.removeListener(ruddyLevelListener);
+```