# 实现纯语音互动 (/zh-CN/realtime-media/rtc/build/audio/audio-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. 加入频道后,所有用户都可以在频道内发布音频流,并订阅对方的音频流。 ## 前提条件 [#前提条件-8] 在实现功能以前,请按照以下要求准备开发环境: - 可以访问互联网的计算机。如果你的网络环境部署了防火墙,参考[应对防火墙限制](/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。 :::warning[注意] 临时 Token 的有效期是 24 小时。Token 过期会导致加入频道失败。 ::: ## 创建项目 [#创建项目-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 ``` ## 创建用户界面 [#创建用户界面-6] 复制以下代码即可快速创建实时音频互动场景所需的用户界面。 ```dart // 构建 UI @override Widget build(BuildContext context) { return MaterialApp( title: 'Agora Voice Call', home: Scaffold( appBar: AppBar( title: Text('Agora Voice Call'), ), body: Center( child: Text('Have a voice call!'), ), ), ); } ``` ## 实现步骤 [#实现步骤-8] 本小节介绍如何实现一个实时音频互动 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; bool _localUserJoined = false; late RtcEngine _engine; @override void initState() { super.initState(); initAgora(); } // 初始化应用 Future initAgora() async { // 获取权限 await [Permission.microphone].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.joinChannel( token: token, channelId: channel, options: const ChannelMediaOptions( // 自动订阅所有音频流 autoSubscribeAudio: 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( title: 'Agora Voice Call', home: Scaffold( appBar: AppBar( title: Text('Agora Voice Call'), ), body: Center( child: Text('Have a voice call!'), ), ), ); } } ``` ### 导入 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].request(); ``` :::info[信息] 如果你的目标平台是 iOS 或 macOS,需要在 [`Info.plist`](https://help.apple.com/xcode/mac/current/#/dev3f399a2a6) 中添加实时互动所需的麦克风权限声明,`key` 为 `Privacy - Microphone Usage Description`,`value` 填写使用目的,如:for a voice call。 ::: ### 初始化引擎 [#初始化引擎-7] 调用 `createAgoraRtcEngine` 方法创建一个 `RtcEngine` 对象,然后调用 `initialize` 初始化引擎并设置频道场景为 `channelProfileLiveBroadcasting`(直播场景)。 :::warning[注意] 在初始化 SDK 前,需确保终端用户已经充分了解并同意相关的隐私政策。 ::: ```dart // 创建 RtcEngine _engine = await createAgoraRtcEngine(); // 初始化 RtcEngine,设置频道场景为 channelProfileLiveBroadcasting(直播场景) await _engine.initialize(const RtcEngineContext( appId: appId, channelProfile: ChannelProfileType.channelProfileLiveBroadcasting, )); ``` ### 加入频道并发布音频流 [#加入频道并发布音频流-8] 调用 `joinChannel` 加入频道。在 `ChannelMediaOptions` 中进行如下配置: - 设置用户角色为 `clientRoleBroadcaster`(主播)或 `clientRoleAudience`(观众)。 - 将 `publishMicrophoneTrack` 设置为 `true`,发布麦克风采集的音频。 - 将 `autoSubscribeAudio` 设置为 `true`,自动订阅所有音频流。 ```dart await _engine.joinChannel( // 使用临时 Token 和频道名加入频道 token: token, channelId: channel, options: const ChannelMediaOptions( // 自动订阅所有音频流 autoSubscribeAudio: true, // 发布麦克风采集的音频 publishMicrophoneTrack: true, // 设置用户角色为 clientRoleBroadcaster(主播)或 clientRoleAudience(观众) clientRoleType: ClientRoleType.clientRoleBroadcaster), // uid 为 0 表示引擎内部随机生成用户名 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] 在 `initState()` 方法中初始化声网音频功能并开始实时音频互动。 ```dart @override void initState() { super.initState(); initAgora(); } ``` ### 结束音频互动 [#结束音频互动-4] 按照以下步骤结束音频互动: 1. 调用 `leaveChannel` 离开当前频道,释放所有会话相关的资源。 2. 调用 `release` 销毁引擎,并释放声网 SDK 中使用的所有资源。 :::warning[注意] - 调用 `release` 后,你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音频互动功能,你必须重新创建一个新的引擎。详见[初始化引擎](#初始化引擎-7)。 - 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作,因此建议在子线程中调用该方法,避免主线程阻塞。 ::: ```dart Future _dispose() async { await _engine.leaveChannel(); // 离开频道 await _engine.release(); // 释放资源 } ``` ## 调试 App [#调试-app-4] 按照以下步骤测试语音 App: 1. 将目标设备连接到电脑。 2. 打开终端,在项目路径下执行以下命令在目标设备上运行示例项目: ```shell flutter run ``` 3. 启动 App,授予麦克风权限。 4. 使用第二台设备,重复以上步骤,在该设备上安装 App、打开 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)。 ## 参考信息 [#参考信息-7] ### 示例项目 [#示例项目-8] 声网提供了开源的纯语音互动示例项目供你参考,你可以前往下载或查看其中的源代码。 join_channel_audio.dart} href="https://gitee.com/agoraio-community/Agora-Flutter-SDK/tree/main/example/lib/examples/basic/join_channel_audio" /> join_channel_audio.dart} href="https://github.com/AgoraIO-Extensions/Agora-Flutter-SDK/tree/main/example/lib/examples/basic/join_channel_audio" /> ### 常见问题 [#常见问题-7] - [如何解决 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/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) ### 相关文档 [#相关文档-7] - [SDK 错误码](/zh-CN/realtime-media/rtc/reference/error-code) - [频道连接状态管理](/zh-CN/realtime-media/rtc/build/initialize-and-channel/channel-connection)