@tencentcloud/sdk-mcp 1.3.8 → 1.3.9

package/resource/doc/livekit/live/flutter/live-integration.md

@@ -138,62 +138,29 @@ void main() async {
 
 ## 搭建基础直播间
 
-### 步骤1：实现主播视频开播
+### 步骤1：实现主播开播
 
-主播开播流程如下，您只需执行以下几步操作，即可快速搭建主播视频直播。
+主播开播涉及“预览”和“直播”两个阶段。由于底层视频渲染机制不同，我们需要构建一个状态机来管理视图切换，从而避免预览时出现黑屏。
+1. **核心逻辑与状态定义**
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100032457995/44027626dcad11f0a4f35254007c27c5.png)
 
-
-> **提示：**
-> 
-
-> 主播开播推流的业务代码，您也可以参考 TUILiveKit 开源项目中的 [live_room_anchor_widget.dart](https://github.com/Tencent-RTC/TUIKit_Flutter/blob/main/live/livekit/lib/live_stream/features/live_room_anchor_widget.dart) 文件来了解完整的实现逻辑。
-> 
-
-1. **初始化主播推流视图**
-
-
-   在您的主播页面中，创建一个 `LiveCoreWidget` 实例，并通过 `LiveCoreController` 控制直播行为。
+   首先，在您的 State 类中定义核心控制器，并增加一个 _isLiveStarted 标记，用于区分当前是“预览态”还是“直播态”。
 
    ``` java
-   import 'package:flutter/material.dart';
-   import 'package:atomic_x_core/atomicxcore.dart';
-   
-   /// YourAnchorPage 代表您的主播开播页面
-   class YourAnchorPage extends StatefulWidget {
-     final String liveId;
-   
-     const YourAnchorPage({super.key, required this.liveId});
-   
-     @override
-     State<YourAnchorPage> createState() => _YourAnchorPageState();
-   }
-   
    class _YourAnchorPageState extends State<YourAnchorPage> {
-     // 1. 创建 LiveCoreController 实例
+     // 核心控制器
      late final LiveCoreController _controller;
+     // 状态标记：false = 预览中; true = 直播中
+     bool _isLiveStarted = false; 
    
      @override
      void initState() {
        super.initState();
-       // 2. 初始化 controller
-       _controller = LiveCoreController.create();
-       // 3. 设置直播 ID
+       _controller = LiveCoreController.create(CoreViewType.pushView);
        _controller.setLiveID(widget.liveId);
-     }
-   
-     @override
-     Widget build(BuildContext context) {
-       return Scaffold(
-         body: Stack(
-           children: [
-             // 4. 将主播推流页面加载到您的视图上
-             LiveCoreWidget(controller: _controller),
-             // 您的其他 UI 组件
-           ],
-         ),
-       );
+       
+       // 初始化时直接打开设备（详见下一步）
+       _openDevices();
      }
    }
    ```
@@ -201,134 +168,109 @@ void main() async {
 
 
    通过调用 **DeviceStore** 的 `openLocalCamera`、`openLocalMicrophone` 接口打开摄像头和麦克风，**您无需做额外操作，LiveCoreWidget 会自动预览当前摄像头的视频流**，示例代码如下：
+   
+
+   > **注意：**
+   > 
+
+   > 此步骤对于预览至关重要。只有打开设备，后续的 VideoView 才有画面可渲染。
+   > 
 
    ``` java
-   import 'package:flutter/material.dart';
-   import 'package:atomic_x_core/atomicxcore.dart';
-   
-   /// YourAnchorPage 代表您的主播开播页面
-   class YourAnchorPage extends StatefulWidget {
-     final String liveId;
-   
-     const YourAnchorPage({super.key, required this.liveId});
-   
-     @override
-     State<YourAnchorPage> createState() => _YourAnchorPageState();
-   }
-   
-   class _YourAnchorPageState extends State<YourAnchorPage> {
-     late final LiveCoreController _controller;
-   
-     @override
-     void initState() {
-       super.initState();
-       _controller = LiveCoreController.create();
-       _controller.setLiveID(widget.liveId);
-       // 打开设备
-       _openDevices();
-     }
-   
-     void _openDevices() {
-       // 1. 打开前置摄像头
+   void _openDevices() {
+       // 1. 打开前置摄像头 (true 表示前置)
        DeviceStore.shared.openLocalCamera(true);
        // 2. 打开麦克风
        DeviceStore.shared.openLocalMicrophone();
      }
+   ```
+3. **构建预览视图**
+
+
+   这是最关键的一步。我们需要根据 `_isLiveStarted` 的状态选择不同的组件：
+
+- **预览态：**使用 `VideoView` + `setLocalVideoView`（直接渲染本地采集数据）。
+
+- **直播态：**使用 `LiveCoreWidget`（渲染直播间流数据）。
+
+   ``` java
+   // 3.1 封装预览视图组件
+     Widget _buildLocalPreview() {
+       return Container(
+         color: Colors.black,
+         child: VideoView(
+           onViewCreated: (viewId) {
+             // 关键：将本地摄像头画面绑定到预览 View
+             TUIRoomEngine.sharedInstance().setLocalVideoView(viewId);
+           },
+           onViewDisposed: (viewId) {
+             // 销毁时解绑
+             TUIRoomEngine.sharedInstance().setLocalVideoView(0);
+           },
+         ),
+       );
+     }
    
+     // 3.2 组合主视图
      @override
      Widget build(BuildContext context) {
        return Scaffold(
          body: Stack(
            children: [
-             LiveCoreWidget(controller: _controller),
+             // 视图层：根据状态自动切换
+             Positioned.fill(
+               child: _isLiveStarted 
+                   ? LiveCoreWidget(controller: _controller) // 直播中：用核心组件
+                   : _buildLocalPreview(),                   // 预览中：用 VideoView
+             ),
+             
+             // UI 层：开播按钮（仅在预览时显示）
+             if (!_isLiveStarted)
+               Positioned(
+                 bottom: 50, left: 0, right: 0,
+                 child: Center(
+                   child: ElevatedButton(
+                     onPressed: _startLive, // 下一步实现此方法
+                     child: const Text('开始直播'),
+                   ),
+                 ),
+               ),
            ],
          ),
        );
      }
-   }
    ```
-3. **开始直播**
+4. **实现开播与关播逻辑**
 
 
-   通过调用 **LiveListStore** 的 `createLive` 接口开始视频直播，完整示例代码如下：
+   通过调用 **LiveListStore** 的 `createLive` 接口开始视频直播，示例代码如下：
 
    ``` java
-   import 'package:flutter/material.dart';
-   import 'package:atomic_x_core/atomicxcore.dart';
-   
-   /// YourAnchorPage 代表您的主播开播页面
-   class YourAnchorPage extends StatefulWidget {
-     final String liveId;
-   
-     const YourAnchorPage({super.key, required this.liveId});
-   
-     @override
-     State<YourAnchorPage> createState() => _YourAnchorPageState();
-   }
-   
-   class _YourAnchorPageState extends State<YourAnchorPage> {
-     late final LiveCoreController _controller;
-   
-     @override
-     void initState() {
-       super.initState();
-       _controller = LiveCoreController.create();
-       _controller.setLiveID(widget.liveId);
-       _openDevices();
-     }
-   
-     void _openDevices() {
-       DeviceStore.shared.openLocalCamera(true);
-       DeviceStore.shared.openLocalMicrophone();
-     }
-   
-     // 调用开播接口开始直播
-     Future<void> _startLive() async {
-       // 1. 准备 LiveInfo 对象
+   Future<void> _startLive() async {
+       // 1. 配置直播间参数
        final liveInfo = LiveInfo(
-         // 设置直播的房间 id
-         liveID: widget.liveId,
-         // 设置直播的房间名称
-         liveName: "test 直播",
-         // 配置布局模板，默认：600 动态宫格布局
-         seatLayoutTemplateID: 600,
-         // 配置主播始终在麦位上
-         keepOwnerOnSeat: true,
+         liveID: widget.liveId,         // 房间唯一标识
+         liveName: "Atomic Live Demo",  // 房间标题
+         seatLayoutTemplateID: 600,     // 布局模式：600 代表默认动态宫格
+         keepOwnerOnSeat: true,         // 房主是否始终占有一个麦位
        );
    
-       // 2. 调用 LiveListStore.shared.createLive 开始直播
+       // 2. 发起开播请求
        final result = await LiveListStore.shared.createLive(liveInfo);
    
        if (result.isSuccess) {
-         debugPrint("startLive success");
+         debugPrint("开播成功");
+         // 3. 关键步骤：更新状态
+         // 将 _isLiveStarted 置为 true，触发 build 方法重新构建，
+         // 从而将 UI 从 VideoView（预览）切换为 LiveCoreWidget（直播）。
+         setState(() {
+           _isLiveStarted = true;
+         });
        } else {
-         debugPrint("startLive error: ${result.errorMessage}");
+         debugPrint("开播失败: ${result.errorMessage}");
+         // 可以在此处添加 Toast 提示用户
        }
      }
-   
-     @override
-     Widget build(BuildContext context) {
-       return Scaffold(
-         body: Stack(
-           children: [
-             LiveCoreWidget(controller: _controller),
-             // 开播按钮
-             Positioned(
-               bottom: 50,
-               left: 0,
-               right: 0,
-               child: Center(
-                 child: ElevatedButton(
-                   onPressed: _startLive,
-                   child: const Text('开始直播'),
-                 ),
-               ),
-             ),
-           ],
-         ),
-       );
-     }
-   }
    ```
 
    **LiveInfo 参数说明：**
@@ -495,19 +437,40 @@ void main() async {
 </tr>
 </table>
 
-4. **结束直播**
+5. **结束直播**
 
 
    直播结束后，主播可以调用 **LiveListStore** 的 `endLive` 接口结束直播。SDK 会处理停止推流和销毁房间的逻辑。
 
+   ``` java
+   Future<void> _stopLive() async {
+       // 1. 调用接口结束直播
+       // SDK 内部会自动停止推流、销毁房间并清理媒体资源
+       final result = await LiveListStore.shared.endLive();
+   
+       if (result.isSuccess) {
+         debugPrint("关播成功");
+         // 2. 退出当前页面
+         if (mounted) {
+           Navigator.of(context).pop();
+         }
+       } else {
+         debugPrint("关播失败: ${result.errorMessage}");
+       }
+     }
+   ```
+6. **完整代码参考**
+
+
+   为了方便您快速集成，我们将上述步骤整合为完整的 `YourAnchorPage` 文件。您可以直接复制以下代码：
+
    ``` java
    import 'package:flutter/material.dart';
    import 'package:atomic_x_core/atomicxcore.dart';
+   import 'package:rtc_room_engine/rtc_room_engine.dart'; // 引入 RTC 引擎
    
-   /// YourAnchorPage 代表您的主播开播页面
    class YourAnchorPage extends StatefulWidget {
      final String liveId;
-   
      const YourAnchorPage({super.key, required this.liveId});
    
      @override
@@ -515,20 +478,73 @@ void main() async {
    }
    
    class _YourAnchorPageState extends State<YourAnchorPage> {
-     // ... 其他代码 ...
+     late final LiveCoreController _controller;
+     bool _isLiveStarted = false; // 直播状态标记
    
-     // 结束直播
-     Future<void> _stopLive() async {
-       final result = await LiveListStore.shared.endLive();
+     @override
+     void initState() {
+       super.initState();
+       _controller = LiveCoreController.create(CoreViewType.pushView);
+       _controller.setLiveID(widget.liveId);
+       _openDevices(); // 步骤2：打开设备
+     }
+   
+     void _openDevices() {
+       DeviceStore.shared.openLocalCamera(true);
+       DeviceStore.shared.openLocalMicrophone();
+     }
+   
+     // 步骤3：构建预览
+     Widget _buildLocalPreview() {
+       return Container(
+         color: Colors.black,
+         child: VideoView(
+           onViewCreated: (viewId) => TUIRoomEngine.sharedInstance().setLocalVideoView(viewId),
+           onViewDisposed: (viewId) => TUIRoomEngine.sharedInstance().setLocalVideoView(0),
+         ),
+       );
+     }
    
+     // 步骤4：开播逻辑
+     Future<void> _startLive() async {
+       final liveInfo = LiveInfo(
+         liveID: widget.liveId,
+         liveName: "Test Live",
+         seatLayoutTemplateID: 600,
+         keepOwnerOnSeat: true,
+       );
+   
+       final result = await LiveListStore.shared.createLive(liveInfo);
        if (result.isSuccess) {
-         debugPrint("endLive success");
-       } else {
-         debugPrint("endLive error: ${result.errorMessage}");
+         setState(() {
+           _isLiveStarted = true; // 切换 UI 状态
+         });
        }
      }
    
-     // ... 其他代码 ...
+     @override
+     Widget build(BuildContext context) {
+       return Scaffold(
+         body: Stack(
+           children: [
+             // 视图自动切换
+             Positioned.fill(
+               child: _isLiveStarted
+                   ? LiveCoreWidget(controller: _controller)
+                   : _buildLocalPreview(),
+             ),
+             // 开播按钮
+             if (!_isLiveStarted)
+               Positioned(
+                 bottom: 50, left: 0, right: 0,
+                 child: Center(
+                   child: ElevatedButton(onPressed: _startLive, child: const Text('开始直播')),
+                 ),
+               ),
+           ],
+         ),
+       );
+     }
    }
    ```
 
@@ -549,32 +565,46 @@ void main() async {
 
 
    在您的观众页面中，创建 `LiveCoreWidget` 实例，并通过 `LiveCoreController` 控制直播行为。
+   
+
+   > **注意：**
+   > 
+
+   > **必须确保 LiveCoreWidget 在调用 joinLive() 之前已经完成初始化并处于渲染树中。**
+   > 
+
+   > **原理分析：**`LiveCoreWidget` 在 `initState` 中会执行 `controller.init() `以注册对 `currentLive` 信息的监听。如果先调用` joinLive()` 导致房间信息更新，而此时 `Widget` 尚未渲染（监听器未注册），则无法触发内部的自动拉流逻辑，导致画面黑屏。
+   > 
 
    ``` java
    import 'package:flutter/material.dart';
    import 'package:atomic_x_core/atomicxcore.dart';
    
    /// YourAudiencePage 代表您的观众观看页面
-   class YourAudiencePage extends StatefulWidget {
-     final String liveId;
-   
-     const YourAudiencePage({super.key, required this.liveId});
-   
-     @override
-     State<YourAudiencePage> createState() => _YourAudiencePageState();
-   }
-   
    class _YourAudiencePageState extends State<YourAudiencePage> {
-     // 1. 创建 LiveCoreController 实例
      late final LiveCoreController _controller;
+     bool _isJoining = true;
    
      @override
      void initState() {
        super.initState();
-       // 2. 初始化 controller
-       _controller = LiveCoreController.create();
-       // 3. 绑定直播 id
+       _controller = LiveCoreController.create(CoreViewType.playView);
        _controller.setLiveID(widget.liveId);
+       
+       // 修正：在第一帧渲染完成后再进房，确保 LiveCoreWidget 已完成 init() 
+       WidgetsBinding.instance.addPostFrameCallback((_) {
+         _joinLive();
+       });
+     }
+   
+     Future<void> _joinLive() async {
+       final result = await LiveListStore.shared.joinLive(widget.liveId);
+       if (result.isSuccess) {
+         debugPrint("joinLive success");
+         if (mounted) setState(() => _isJoining = false);
+       } else {
+         debugPrint("joinLive error: ${result.errorMessage}");
+       }
      }
    
      @override
@@ -582,8 +612,11 @@ void main() async {
        return Scaffold(
          body: Stack(
            children: [
-             // 4. 将观众拉流页面加载到您的视图上
+             // 必须始终渲染，不可根据 _isJoining 状态移除，否则会导致监听失效
              LiveCoreWidget(controller: _controller),
+             
+             if (_isJoining)
+               const Center(child: CircularProgressIndicator(color: Colors.white)),
            ],
          ),
        );
@@ -1002,6 +1035,14 @@ class _YourAudiencePageState extends State<YourAudiencePage> {
 - **检查网络**：请检查设备网络连接是否正常。
 
 
+### 观众端调用了 joinLive 且返回 Success，但依然没有视频画面？
+- **时序问题：**是否在 LiveCoreWidget 挂载前就执行了 joinLive？请参考上文使用 addPostFrameCallback。
+
+- **Controller 类型：**创建时是否正确传入了 CoreViewType.playView？
+
+- **Widget 持久性：**在进房过程中，LiveCoreWidget 是否因为 setState 被意外销毁或重新创建？请确保其在 Widget 树中的稳定性。
+
+
 ### Flutter 项目如何请求权限？
 
 您可以使用 `permission_handler` 插件来请求摄像头和麦克风权限：