SY RTC Flutter SDK #

SY RTC Flutter SDK 是一个用于实时语音通信的 Flutter 插件，提供类似声网 Agora 的 API 接口。可以直接从 pub.dev 安装使用，无需任何额外配置！

✨ 特性 #

• ✅ 零配置：直接从 pub.dev 安装即可使用，无需修改任何原生代码
• ✅ 跨平台：支持 Android 和 iOS
• ✅ 简单易用：API 设计简洁，类似 Agora SDK
• ✅ 完整功能：支持房间管理、音频控制、事件监听等核心功能

📦 安装 #

方式一：从 pub.dev 安装（推荐） #

在 pubspec.yaml 中添加：

dependencies:
  sy_rtc_flutter_sdk: ^0.0.1

然后运行：

flutter pub get

方式二：从 Git 安装 #

dependencies:
  sy_rtc_flutter_sdk:
    git:
      url: https://github.com/yourusername/sy_rtc_flutter_sdk.git
      ref: main

🚀 快速开始 #

1. 导入包 #

import 'package:sy_rtc_flutter_sdk/sy_rtc_flutter_sdk.dart';

2. 创建引擎实例 #

final engine = SyRtcEngine();

3. 初始化引擎 #

// 方式一：仅初始化（默认只有语聊功能）
await engine.init('your_app_id');

// 方式二：初始化并查询功能权限（推荐）
await engine.init(
  'your_app_id',
  apiBaseUrl: 'https://api.example.com', // 您的API基础URL
);

功能权限说明：

• 如果提供了 apiBaseUrl，SDK 会自动查询 AppId 的功能权限
• 只有开通了 live 功能的 AppId 才能使用视频相关功能
• 所有 AppId 默认都有 voice（语聊）功能

4. 设置事件监听 #

// 监听用户加入
engine.onUserJoined.listen((event) {
  print('用户加入: ${event.uid}, 耗时: ${event.elapsed}ms');
});

// 监听用户离开
engine.onUserOffline.listen((event) {
  print('用户离开: ${event.uid}, 原因: ${event.reason}');
});

// 监听音量指示
engine.onVolumeIndication.listen((event) {
  event.speakers.forEach((info) {
    print('用户 ${info.uid} 音量: ${info.volume}');
  });
});

5. 加入房间 #

// 先从服务器获取 Token（不能在前端直接生成）
String token = await getTokenFromServer(appId, channelId, uid);

// 加入房间
await engine.join(
  channelId: 'channel_001',
  uid: 'user_001',
  token: token,
);

6. 检查功能权限 #

// 检查是否开通了语聊功能
if (await engine.hasVoiceFeature()) {
  // 可以使用音频功能
  await engine.enableLocalAudio(true);
}

// 检查是否开通了直播功能
if (await engine.hasLiveFeature()) {
  // 可以使用视频功能
  await engine.enableVideo();
  await engine.startPreview();
} else {
  print('当前AppId未开通直播功能，只能使用音频功能');
}

7. 控制音频 #

// 启用本地音频
await engine.enableLocalAudio(true);

// 静音
await engine.muteLocalAudio(true);

// 取消静音
await engine.muteLocalAudio(false);

7. 设置客户端角色 #

// 设置为主播（可以说话）
await engine.setClientRole('host');

// 设置为观众（只能听）
await engine.setClientRole('audience');

8. 离开房间 #

await engine.leave();

9. 释放资源 #

engine.dispose();

📖 完整示例 #

import 'package:sy_rtc_flutter_sdk/sy_rtc_flutter_sdk.dart';

class RtcPage extends StatefulWidget {
  @override
  _RtcPageState createState() => _RtcPageState();
}

class _RtcPageState extends State<RtcPage> {
  late SyRtcEngine _engine;
  bool _isJoined = false;
  bool _isMuted = false;

  @override
  void initState() {
    super.initState();
    _initEngine();
  }

  Future<void> _initEngine() async {
    _engine = SyRtcEngine();
    
    // 初始化
    await _engine.init('your_app_id');
    
    // 设置事件监听
    _engine.onUserJoined.listen((event) {
      print('用户加入: ${event.uid}');
    });
    
    _engine.onUserOffline.listen((event) {
      print('用户离开: ${event.uid}');
    });
  }

  Future<void> _joinChannel() async {
    try {
      // 从服务器获取 Token
      String token = await _getTokenFromServer();
      
      await _engine.join(
        channelId: 'channel_001',
        uid: 'user_001',
        token: token,
      );
      
      setState(() {
        _isJoined = true;
      });
      
      // 启用本地音频
      await _engine.enableLocalAudio(true);
    } catch (e) {
      print('加入房间失败: $e');
    }
  }

  Future<void> _leaveChannel() async {
    await _engine.leave();
    setState(() {
      _isJoined = false;
    });
  }

  Future<void> _toggleMute() async {
    await _engine.muteLocalAudio(!_isMuted);
    setState(() {
      _isMuted = !_isMuted;
    });
  }

  @override
  void dispose() {
    _engine.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('RTC 房间')),
      body: Column(
        children: [
          if (!_isJoined)
            ElevatedButton(
              onPressed: _joinChannel,
              child: Text('加入房间'),
            )
          else ...[
            ElevatedButton(
              onPressed: _leaveChannel,
              child: Text('离开房间'),
            ),
            ElevatedButton(
              onPressed: _toggleMute,
              child: Text(_isMuted ? '取消静音' : '静音'),
            ),
          ],
        ],
      ),
    );
  }
}

🔧 权限配置 #

Android #

无需手动配置！ Flutter 插件会自动处理权限。

如果遇到权限问题，检查 android/app/src/main/AndroidManifest.xml 是否包含：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

iOS #

无需手动配置！ Flutter 插件会自动处理权限。

如果遇到权限问题，检查 ios/Runner/Info.plist 是否包含：

<key>NSMicrophoneUsageDescription</key>
<string>需要麦克风权限进行语音通话</string>

📚 API 文档 #

SyRtcEngine #

初始化

Future<void> init(String appId)

初始化 RTC 引擎。

参数：

• appId: 应用ID，从用户后台获取

示例：

await engine.init('your_app_id');

加入房间

Future<void> join({
  required String channelId,
  required String uid,
  required String token,
})

加入语音房间。

参数：

• channelId: 房间ID
• uid: 用户ID（字符串类型）
• token: 鉴权Token（从服务器获取，不能在前端生成）

示例：

await engine.join(
  channelId: 'channel_001',
  uid: 'user_001',
  token: 'token_from_server',
);

离开房间

Future<void> leave()

离开当前房间。

示例：

await engine.leave();

启用/禁用本地音频

Future<void> enableLocalAudio(bool enabled)

启用或禁用本地音频采集和播放。

参数：

• enabled: true 为启用，false 为禁用

示例：

await engine.enableLocalAudio(true);

静音/取消静音

Future<void> muteLocalAudio(bool muted)

静音或取消静音本地音频。

参数：

• muted: true 为静音，false 为取消静音

示例：

await engine.muteLocalAudio(true);  // 静音
await engine.muteLocalAudio(false); // 取消静音

设置客户端角色

Future<void> setClientRole(String role)

设置客户端角色。

参数：

• role: 'host' 或 'audience'
  • 'host': 主播，可以说话
  • 'audience': 观众，只能听

示例：

await engine.setClientRole('host');

释放资源

void dispose()

释放引擎资源。在不再使用引擎时调用。

示例：

engine.dispose();

事件监听 #

用户加入事件

Stream<SyUserJoinedEvent> get onUserJoined

当有用户加入房间时触发。

事件数据：

class SyUserJoinedEvent {
  final String uid;      // 用户ID
  final int elapsed;      // 加入耗时（毫秒）
}

示例：

engine.onUserJoined.listen((event) {
  print('用户 ${event.uid} 加入，耗时 ${event.elapsed}ms');
});

用户离开事件

Stream<SyUserOfflineEvent> get onUserOffline

当有用户离开房间时触发。

事件数据：

class SyUserOfflineEvent {
  final String uid;      // 用户ID
  final String reason;    // 离开原因
}

示例：

engine.onUserOffline.listen((event) {
  print('用户 ${event.uid} 离开，原因: ${event.reason}');
});

音量指示事件

Stream<SyVolumeIndicationEvent> get onVolumeIndication

当检测到用户音量变化时触发。

事件数据：

class SyVolumeIndicationEvent {
  final List<VolumeInfo> speakers;  // 说话者列表
}

class VolumeInfo {
  final String uid;      // 用户ID
  final int volume;      // 音量（0-255）
}

示例：

engine.onVolumeIndication.listen((event) {
  event.speakers.forEach((info) {
    print('用户 ${info.uid} 音量: ${info.volume}');
  });
});

🔑 如何获取 Token？ #

重要：Token 必须从服务器获取，不能在前端直接生成！

推荐流程 #

1. 客户端请求加入房间

   // 客户端代码
   final response = await http.post(
     Uri.parse('https://your-api.com/rtc/token'),
     body: {
       'appId': appId,
       'channelId': channelId,
       'uid': uid,
     },
   );
   final token = jsonDecode(response.body)['data']['token'];
   

2. 服务器生成 Token

   // 服务器代码（Java Spring Boot）
   @PostMapping("/rtc/token")
   public Result<String> generateToken(@RequestBody TokenRequest request) {
       String token = rtcService.generateToken(
           request.getAppId(),
           request.getChannelId(),
           request.getUid()
       );
       return Result.success(token);
   }
   

3. 客户端使用 Token 加入房间

   await engine.join(
     channelId: channelId,
     uid: uid,
     token: token,
   );
   

❓ 常见问题 #

1. SDK 初始化失败？ #

可能原因：

• AppId 不正确
• 网络连接问题
• 权限未授予

解决方法：

• 检查 AppId 是否正确（从用户后台获取）
• 检查网络连接
• 确保已授予麦克风权限（Android/iOS 会自动请求）

2. 无法加入房间？ #

可能原因：

• Token 无效或已过期
• 房间不存在
• 账户余额不足

解决方法：

• 重新从服务器获取 Token
• 确认房间ID正确
• 检查账户余额

3. 没有声音？ #

可能原因：

• 本地音频未启用
• 已静音
• 角色设置为观众

解决方法：

// 启用本地音频
await engine.enableLocalAudio(true);

// 取消静音
await engine.muteLocalAudio(false);

// 设置为主播
await engine.setClientRole('host');

4. 如何发布到 pub.dev？ #

1. 检查 pubspec.yaml

   name: sy_rtc_flutter_sdk
   description: "SY RTC Flutter SDK - A Flutter plugin for RTC audio communication"
   version: 0.0.1
   homepage: https://github.com/yourusername/sy_rtc_flutter_sdk
   

2. 运行检查

   flutter pub publish --dry-run
   

3. 发布

   flutter pub publish
   

📱 平台要求 #

• Flutter: >=3.3.0
• Dart: >=3.6.2
• Android: minSdk 21+ (Android 5.0)
• iOS: iOS 12.0+

📄 许可证 #

MIT License

🤝 贡献 #

欢迎提交 Issue 和 Pull Request！

📧 联系方式 #

如有问题，请提交 Issue 或联系开发团队。

最后更新: 2026-01-14