# 实现音视频互动 (/zh-CN/realtime-media/rtc/get-started/quick-start/flutter)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
本文介绍如何集成声网实时互动 SDK,通过少量代码从 0 开始实现一个简单的实时互动 App,适用于互动直播和视频通话场景。
首先,你需要了解以下有关音视频实时互动的基础概念:
- 声网实时互动 SDK:由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。
- 频道:用于传输数据的通道,在同一个频道内的用户可以进行实时互动。
- 主播:可以在频道内**发布**音视频,同时也可以**订阅**其他主播发布的音视频。
- 观众:可以在频道内**订阅**音视频,不具备**发布**音视频权限。
更多概念详见[关键概念](/zh-CN/realtime-media/rtc/reference/key-concept)。
下图展示在 App 中实现音视频互动的基本工作流程:
1. 所有用户调用 `joinChannel` 方法加入频道,并根据需要设置用户角色:
- 互动直播:如果用户需要在频道中发流,则设为主播;如果用户只需要收流,则设为观众。
- 视频通话:将所有用户的角色都设为主播。
2. 加入频道后,不同角色的用户具备不同的行为:
- 所有用户默认都可以接收频道中的音视频流。
- 主播可以在频道内发布音视频流。
- 观众如果需要发流,可在频道内调用 `setClientRole` 方法修改用户角色,使其具备发流权限。
## 前提条件 [#前提条件-9]
- Flutter 2.10.5 或更高版本。
- Dart 2.14.0 或更高版本。
- 根据你的目标平台,准备对应的开发和运行环境:
| 目标平台 | 环境要求 |
| --- | --- |
| iOS | [quick-start-5923-2-1 details](#table-slot-quick-start-5923-2-1) |
| Android | [quick-start-5923-3-1 details](#table-slot-quick-start-5923-3-1) |
| macOS | [quick-start-5923-4-1 details](#table-slot-quick-start-5923-4-1) |
| Windows | [quick-start-5923-5-1 details](#table-slot-quick-start-5923-5-1) |
**quick-start-5923-2-1 details**
- macOS 10.15 或更高版本
- 最新版本的 Xcode
- 两台 iOS 设备
**quick-start-5923-3-1 details**
- macOS 10.15 或更高版本
- Windows 10 或更高版本
- 最新版本的 Android Studio
- 两台 Android 设备
**quick-start-5923-4-1 details**
- macOS 10.15 或更高版本
- 最新版本的 Xcode
- 两台 macOS 设备
**quick-start-5923-5-1 details**
- Windows 10 或更高版本
- 最新版本的 Visual Studio
- 两台 Windows 设备
:::info[信息]
- 更多环境要求细节,详见 [Install Flutter](https://docs.flutter.dev/get-started/install)。
- 你可以运行 `flutter doctor` 命令检查开发和运行环境是否达到要求。
:::
- 可以访问互联网的计算机。如果你的网络环境部署了防火墙,参考[应对防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。
- 一个有效的声网账号以及声网项目。请参考[开通 RTC 服务](/zh-CN/realtime-media/rtc/build/setup-and-access/enable-service)从声网控制台获得以下信息:
- App ID:声网随机生成的字符串,用于识别你的项目。
- 临时 Token:Token 也称为动态密钥,在客户端加入频道时对用户鉴权。临时 Token 的有效期为 24 小时。
## 创建项目 [#创建项目-8]
根据你选用的 IDE 不同,创建 Flutter 项目有多种方式,详见 [Create the app](https://docs.flutter.dev/get-started/test-drive?tab=vscode#create-app)。在本文中,以在终端中运行 `flutter create` 命令创建 Flutter 项目为例。
```shell
# 将 替换为项目名
flutter create
```
## 集成 SDK [#集成-sdk-8]
1. 打开 `pubspec.yaml` 文件,添加以下依赖:
- 添加 `agora_rtc_engine` 依赖项,集成声网 Flutter SDK。关于 `agora_rtc_engine` 的最新版本可以查询 [https://pub.dev/packages/agora_rtc_engine](https://pub.dev/packages/agora_rtc_engine)
- 添加 `permission_handler` 依赖项,安装权限处理插件。
```yaml
environment:
sdk: ">=2.12.0 <3.0.0"
# 依赖项
dependencies:
flutter:
sdk: flutter
# The following adds the Cupertino Icons font to your application.
# Use with the CupertinoIcons class for iOS style icons.
cupertino_icons: ^0.1.3
# 声网 Flutter SDK 依赖项,请使用最新版本的 agora_rtc_engine
agora_rtc_engine: ^6.0.0
# 权限处理插件依赖项
permission_handler: ^8.3.0
```
2. 添加依赖并保存文件后,打开终端,在项目路径下执行以下命令获取并安装依赖:
```shell
flutter pub get
```
## 创建用户界面 [#创建用户界面-7]
根据实时音视频互动的场景需要,为你的项目创建两个视图框,分别用于展示本地视频和远端视频。复制以下代码即可快速创建场景所需的用户界面。
```dart
// 构建 UI,显示本地视图和远端视图
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
appBar: AppBar(
title: const Text('Agora Video Call'),
),
body: Stack(
children: [
Center(
child: _remoteVideo(),
),
Align(
alignment: Alignment.topLeft,
child: SizedBox(
width: 100,
height: 150,
child: Center(
child: _localUserJoined
? AgoraVideoView(
controller: VideoViewController(
rtcEngine: _engine,
canvas: const VideoCanvas(uid: 0),
),
)
: const CircularProgressIndicator(),
),
),
),
],
),
),
);
}
```
## 实现步骤 [#实现步骤-9]
本小节介绍如何实现一个实时音视频互动 App。你可以先复制完整的示例代码到你的项目中,快速体验实时音视频互动的基础功能,再按照实现步骤了解其中的核心 API 调用。
下图展示了使用声网 RTC SDK 实现音视频互动的基本流程:
下面列出了一段实现实时音视频互动基本流程的完整代码以供参考。复制以下代码替换 `/lib/main.dart` 文件的全部内容,即可快速体验实时音视频互动基础功能。
:::info[信息]
将 `<-- Insert App Id -->`、`<-- Insert Token -->` 和 `<-- Insert Channel Name -->` 分别替换为你在控制台获取到的 App ID、临时 Token,以及生成临时 Token 时填入的频道名。
:::
```dart
import 'dart:async';
import 'package:agora_rtc_engine/agora_rtc_engine.dart';
import 'package:flutter/material.dart';
import 'package:permission_handler/permission_handler.dart';
void main() => runApp(MyApp());
// 填写声网控制台中获取的 App ID
const appId = "<-- Insert App Id -->";
// 填写声网控制台中生成的临时 Token
const token = "<-- Insert Token -->";
// 填写频道名
const channel = "<-- Insert Channel Name -->";
// 应用类
class MyApp extends StatefulWidget {
const MyApp({Key? key}) : super(key: key);
@override
_MyAppState createState() => _MyAppState();
}
// 应用状态类
class _MyAppState extends State {
int? _remoteUid; // 用于存储远端用户的 uid
bool _localUserJoined = false; // 表示本地用户是否加入频道,初始值为 false
late RtcEngine _engine; // 用于存储 RtcEngine 实例
@override
void initState() {
super.initState();
initAgora();
}
Future initAgora() async {
// 获取麦克风和摄像头权限
await [Permission.microphone, Permission.camera].request();
// 创建 RtcEngine 对象
_engine = await createAgoraRtcEngine();
// 初始化 RtcEngine,设置频道场景为 channelProfileLiveBroadcasting(直播场景)
await _engine.initialize(const RtcEngineContext(
appId: appId,
channelProfile: ChannelProfileType.channelProfileLiveBroadcasting,
));
// 添加回调事件
_engine.registerEventHandler(
RtcEngineEventHandler(
// 成功加入频道回调
onJoinChannelSuccess: (RtcConnection connection, int elapsed) {
debugPrint("local user ${connection.localUid} joined");
setState(() {
_localUserJoined = true;
});
},
// 远端用户或主播加入当前频道回调
onUserJoined: (RtcConnection connection, int remoteUid, int elapsed) {
debugPrint("remote user $remoteUid joined");
setState(() {
_remoteUid = remoteUid;
});
},
// 远端用户或主播离开当前频道回调
onUserOffline: (RtcConnection connection, int remoteUid,
UserOfflineReasonType reason) {
debugPrint("remote user $remoteUid left channel");
setState(() {
_remoteUid = null;
});
},
),
);
// 启用视频模块
await _engine.enableVideo();
// 开启本地预览
await _engine.startPreview();
// 加入频道
await _engine.joinChannel(
token: token,
channelId: channel,
options: const ChannelMediaOptions(
// 自动订阅所有视频流
autoSubscribeVideo: true,
// 自动订阅所有音频流
autoSubscribeAudio: true,
// 发布摄像头采集的视频
publishCameraTrack: true,
// 发布麦克风采集的音频
publishMicrophoneTrack: true,
// 设置用户角色为 clientRoleBroadcaster(主播)或 clientRoleAudience(观众)
clientRoleType: ClientRoleType.clientRoleBroadcaster),
uid: 0,
);
}
@override
void dispose() {
super.dispose();
_dispose();
}
Future _dispose() async {
await _engine.leaveChannel(); // 离开频道
await _engine.release(); // 释放资源
}
// 构建 UI,显示本地视图和远端视图
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
appBar: AppBar(
title: const Text('Agora Video Call'),
),
body: Stack(
children: [
Center(
child: _remoteVideo(),
),
Align(
alignment: Alignment.topLeft,
child: SizedBox(
width: 100,
height: 150,
child: Center(
child: _localUserJoined
? AgoraVideoView(
controller: VideoViewController(
rtcEngine: _engine,
canvas: const VideoCanvas(uid: 0),
),
)
: const CircularProgressIndicator(),
),
),
),
],
),
),
);
}
// 生成远端视频
Widget _remoteVideo() {
if (_remoteUid != null) {
return AgoraVideoView(
controller: VideoViewController.remote(
rtcEngine: _engine,
canvas: VideoCanvas(uid: _remoteUid),
connection: const RtcConnection(channelId: channel),
),
);
} else {
return const Text(
'Please wait for remote user to join',
textAlign: TextAlign.center,
);
}
}
}
```
### 导入 package [#导入-package]
导入构建 App 所需的 package。
```dart
import 'dart:async';
import 'package:agora_rtc_engine/agora_rtc_engine.dart';
import 'package:flutter/material.dart';
import 'package:permission_handler/permission_handler.dart';
```
### 定义 App ID 和 Token [#定义-app-id-和-token-2]
传入从声网控制台获取的 App ID、临时 Token,以及生成临时 Token 时填入的频道名,用于后续初始化引擎和加入频道。
```dart
// 填写声网控制台中获取的 App ID
const appId = "<-- Insert App Id -->";
// 填写声网控制台中生成的临时 Token
const token = "<-- Insert Token -->";
// 填写频道名
const channel = "<-- Insert Channel Name -->";
```
### 处理权限请求 [#处理权限请求-3]
获取体验实时音视频所需的麦克风和摄像头权限。
```dart
await [Permission.microphone, Permission.camera].request();
```
:::info[信息]
如果你的目标平台是 iOS 或 macOS,需要在 [`Info.plist`](https://help.apple.com/xcode/mac/current/#/dev3f399a2a6) 中添加实时互动所需的权限声明如下:
- 麦克风:`key` 为 `Privacy - Microphone Usage Description`,`value` 填写使用目的,如:for a video call。
- 摄像头:`key` 为 `Privacy - Camera Usage Description`,`value` 填写使用目的,如:for a video call。
:::
### 初始化引擎 [#初始化引擎-8]
调用 `createAgoraRtcEngine` 方法创建一个 `RtcEngine` 对象,然后调用 `initialize` 初始化引擎并设置频道场景为 `channelProfileLiveBroadcasting`(直播场景)。
:::warning[注意]
在初始化 SDK 前,需确保终端用户已经充分了解并同意相关的隐私政策。
:::
```dart
// 创建 RtcEngine 对象
_engine = await createAgoraRtcEngine();
// 初始化 RtcEngine,设置频道场景为 channelProfileLiveBroadcasting(直播场景)
await _engine.initialize(const RtcEngineContext(
appId: appId,
channelProfile: ChannelProfileType.channelProfileLiveBroadcasting,
));
```
### 启用视频模块 [#启用视频模块-8]
按照以下步骤启用视频模块:
1. 调用 `enableVideo` 方法,启用视频模块。
2. 调用 `startPreview` 方法,开启本地视频预览。
```dart
// 启用视频模块
await _engine.enableVideo();
// 开启本地预览
await _engine.startPreview();
```
### 加入频道并发布音视频流 [#加入频道并发布音视频流-8]
调用 `joinChannel` 加入频道。在 `ChannelMediaOptions` 中进行如下配置:
- 设置用户角色为 `clientRoleBroadcaster`(主播)或 `clientRoleAudience`(观众)。
- 将 `publishMicrophoneTrack` 和 `publishCameraTrack` 设置为 `true`,发布麦克风采集的音频和摄像头采集的视频。
- 将 `autoSubscribeAudio` 和 `autoSubscribeVideo` 设置为 `true`,自动订阅所有音视频流。
```dart
await _engine.joinChannel(
// 使用临时 Token 和频道名加入频道
token: token,
channelId: channel,
options: const ChannelMediaOptions(
// 自动订阅所有视频流
autoSubscribeVideo: true,
// 自动订阅所有音频流
autoSubscribeAudio: true,
// 发布摄像头采集的视频
publishCameraTrack: true,
// 发布麦克风采集的音频
publishMicrophoneTrack: true,
// 设置用户角色为 clientRoleBroadcaster(主播)或 clientRoleAudience(观众)
clientRoleType: ClientRoleType.clientRoleBroadcaster),
// uid 为 0 表示由引擎内部随机生成用户 ID
uid: 0,
);
```
### 实现常用回调 [#实现常用回调-8]
根据使用场景,定义必要的回调。以下示例代码展示如何调用 `registerEventHandler` 添加并实现 `onJoinChannelSuccess`、 `onUserJoined` 和 `onUserOffline` 回调。
```dart
// 添加回调事件
_engine.registerEventHandler(
RtcEngineEventHandler(
// 成功加入频道回调
onJoinChannelSuccess: (RtcConnection connection, int elapsed) {
debugPrint("local user ${connection.localUid} joined");
setState(() {
_localUserJoined = true;
});
},
// 远端用户或主播加入当前频道回调
onUserJoined: (RtcConnection connection, int remoteUid, int elapsed) {
debugPrint("remote user $remoteUid joined");
setState(() {
_remoteUid = remoteUid;
});
},
// 远端用户或主播离开当前频道回调
onUserOffline: (RtcConnection connection, int remoteUid,
UserOfflineReasonType reason) {
debugPrint("remote user $remoteUid left channel");
setState(() {
_remoteUid = null;
});
},
),
);
```
### 设置远端视图 [#设置远端视图-4]
当远端用户加入频道时,触发 `onUserJoined` 回调。通过该回调获取远端用户的 `uid` 后,创建一个 `AgoraVideoView` 控件,用于显示对应远端用户的视频流。
```dart
// 生成远端视频
Widget _remoteVideo() {
if (_remoteUid != null) {
return AgoraVideoView(
controller: VideoViewController.remote(
rtcEngine: _engine,
canvas: VideoCanvas(uid: _remoteUid),
connection: const RtcConnection(channelId: channel),
),
);
} else {
return const Text(
'Please wait for remote user to join',
textAlign: TextAlign.center,
);
}
}
```
### 开始音视频互动 [#开始音视频互动-6]
在 `initState()` 方法中初始化声网音视频功能并开始实时音视频互动。
```dart
@override
void initState() {
super.initState();
initAgora();
}
```
### 结束音视频互动 [#结束音视频互动-6]
按照以下步骤结束音视频互动:
1. 调用 `leaveChannel` 离开当前频道,释放所有会话相关的资源。
2. 调用 `release` 销毁引擎,并释放声网 SDK 中使用的所有资源。
:::warning[注意]
- 调用 `release` 后,你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音视频互动功能,你必须重新创建一个新的引擎。详见[初始化引擎](#初始化引擎-8)。
- 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作,因此建议在子线程中调用该方法,避免主线程阻塞。
:::
```dart
Future _dispose() async {
await _engine.leaveChannel(); // 离开频道
await _engine.release(); // 释放资源
}
```
## 调试 App [#调试-app-4]
按照以下步骤测试直播 App:
1. 将目标设备连接到电脑。
2. 打开终端,在项目路径下执行以下命令在目标设备上运行示例项目:
```shell
flutter run
```
3. 启动 App,授予麦克风和摄像头权限,如果你将用户角色设置为主播,便会在本地视图中看到自己。
4. 使用第二台设备,重复以上步骤,在该设备上安装 App、打开 App 加入频道,观察测试结果:
- 如果两台设备均作为主播加入频道,则可以看到对方并且听到对方的声音。
- 如果两台设备分别作为主播和观众加入,则主播可以在本地视频窗口看到自己;观众可以在远端视频窗口看到主播、并听到主播的声音。
以 Android 设备为例,编译成功后的 App 如下图所示:
## 后续步骤 [#后续步骤-7]
- 本文的示例使用了临时 Token 加入频道。在测试或生产环境中,为确保通信安全,声网推荐使用 Token 服务器来生成 Token,详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。
- 如果你想要实现极速直播场景,可以在互动直播的基础上,通过修改观众端的延时级别为低延时 (`audienceLatencyLevelLowLatency`)实现。详见[实现极速直播](/zh-CN/realtime-media/rtc/build/advanced-channel/ls-quick-start)。
## 参考信息 [#参考信息-9]
### 示例项目 [#示例项目-9]
声网提供了开源的实时音视频互动示例项目供你参考,你可以前往下载或查看其中的源代码。
join_channel_video} href="https://gitee.com/agoraio-community/Agora-Flutter-SDK/tree/main/example/lib/examples/basic/join_channel_video" />
join_channel_video} href="https://github.com/AgoraIO-Extensions/Agora-Flutter-SDK/tree/main/example/lib/examples/basic/join_channel_video" />
### 常见问题 [#常见问题-8]
- [如何解决 Flutter 上 iOS release 包初始化时报 symbol not found 的问题?](/zh-CN/reference/faq/integration/flutter_ios_build)
- [直播场景下,如何监听远端观众角色用户加入/离开频道的事件?](/zh-CN/reference/faq/integration/audience_event)
- [如何处理视频黑屏问题?](/zh-CN/reference/faq/quality/video_blank)
- [为什么我无法打开摄像头?](/zh-CN/reference/faq/quality/video_camera)
- [如何处理频道相关常见问题?](/zh-CN/reference/faq/integration/channel)
- [如何设置日志文件?](/zh-CN/reference/faq/integration/set_log_file)
- [为什么部分 Android 版本应用锁屏或切后台后采集音视频无效?](/zh-CN/reference/faq/quality/android_background)
- [编译 Xcode 项目时遇到无法打开 framework 的弹窗警告怎么办?](/zh-CN/reference/faq/integration/framework_cannot_be_opened)
- [为什么 SDK 中使用的是动态库而不是静态库?](/zh-CN/reference/faq/integration/dynamic_or_static_library)
### 相关文档 [#相关文档-8]
- [SDK 错误码](/zh-CN/realtime-media/rtc/reference/error-code)
- [频道连接状态管理](/zh-CN/realtime-media/rtc/build/initialize-and-channel/channel-connection)