实现纯语音互动

  • iOS

更新时间

了解如何快速接入实时互动 RTC,完成环境准备、参数配置、示例运行和核心流程验证。

本文介绍如何集成声网实时互动 SDK,通过少量代码从 0 开始实现一个简单的纯语音互动 App,适用于语音通话场景。 首先,你需要了解以下有关音视频实时互动的基础概念:

  • 声网实时互动 SDK:由声网开发的、帮助开发者在 App 中实现实时音视频互动的 SDK。
  • 频道:用于传输数据的通道,在同一个频道内的用户可以进行实时互动。
  • 主播:可以在频道内发布音视频,同时也可以订阅其他主播发布的音视频。
  • 观众:可以在频道内订阅音视频,不具备发布音视频权限。

更多概念详见关键概念。

下图展示在 App 中实现纯语音互动的基本工作流程:

  1. 所有用户调用 joinChannel 方法加入频道,并将所有用户角色都设置为主播。
  2. 加入频道后,所有用户都可以在频道内发布音频流,并订阅对方的音频流。

前提条件

在实现功能以前,请按照以下要求准备开发环境:

  • Xcode 12.0 或以上版本。
  • Apple 开发者账号。
  • 如需使用 Cocoapods 集成 SDK,则确保已安装 Cocoapods,否则请参考 Getting Started with CocoaPods 进行安装。
  • 两台 iOS 9.0 或以上版本的设备。
  • 可以访问互联网的计算机。如果你的网络环境部署了防火墙,参考应对防火墙限制以正常使用声网服务。
  • 一个有效的声网账号以及声网项目。请参考开通 RTC 服务从声网控制台获得 App ID 和临时 Token。

注意

临时 Token 的有效期是 24 小时。Token 过期会导致加入频道失败。

创建项目

按照以下步骤,在 Xcode 中创建一个项目:

  1. 参考 Create a project 创建一个新的项目。Application 选择 App,Interface 选择 Storyboard,Language 选择 Swift。

信息

如果你没有添加过开发团队信息,会看到 Add account… 按钮。点击该按钮并按照屏幕提示登入 Apple ID,点击 Next,完成后即可选择你的 Apple 账户作为开发团队。

  1. 为你的项目设置自动签名。

  2. 设置部署你的 App 的目标设备。

  3. 添加项目的设备权限。

    在项目导航栏中打开 info.plist 文件,编辑属性列表,添加实时互动所需的录音权限。

    信息

    • 下表中列出的权限为必需权限;如果不添加所列权限,你将无法使用麦克风进行实时纯语音互动。
    • 如果你的项目中需要添加第三方插件或库,且该插件或库的签名与项目的签名不一致,你还需勾选 Hardened Runtime > Runtime Exceptions 中的 Disable Library Validation。
    • 更多注意事项,可以参考 Preparing Your App for Distribution。
    KeyTypeValue
    Privacy - Microphone Usage DescriptionString使用麦克风的目的,例如:for a call or live interactive streaming。
    表格内容超出当前宽度,可横向滚动查看更多列。

集成 SDK

为了减小集成 SDK 后的 App 体积,声网推荐你集成音频 SDK 来实现纯语音互动。

根据实际情况,在以下集成方式中任选一种,在你的项目中集成 SDK。

  1. 在终端里进入项目根目录,并运行 pod init 命令。项目文件夹下会生成一个 Podfile 文本文件。

  2. 打开 Podfile 文件,在文件顶部添加声网 CocoaPods CDN 源。请保留项目中已有的源配置;如果项目还依赖公共仓库中的其他 Pod,请同时保留公共源,例如 source 'https://cdn.cocoapods.org/'。已有项目保留原来的 SDK 包名、版本号和组件配置,仅补充源配置。

    以下示例将 CocoaPods 官方公共源放在声网源前面。将 Your App 替换为你的 Target 名称,将 x.y.z 替换为具体的 SDK 版本号,可通过发版说明获取版本信息。示例默认集成 v4.6.0 及之后版本;如需之前的版本,请注释默认的 pod 行,并取消 AgoraAudio_iOS 所在行的注释。

    Podfile 中的平台版本应与工程的 iOS Deployment Target 保持一致,且不低于 SDK 支持的最低版本。

    Ruby
    source 'https://cdn.cocoapods.org/'
    source 'https://download.shengwang.cn/cocoapods/'
    
    platform :ios, '9.0'
    target 'Your App' do
        # 对于 4.6.0 及之后的版本
        pod 'ShengwangAudio_iOS', 'x.y.z'
    
        # 对于 4.6.0 之前的版本
        # pod 'AgoraAudio_iOS', 'x.y.z'
    end
  3. 在 Podfile 所在目录执行 pod install --repo-update,安装所需版本的 SDK。如遇安装问题,请参考 CocoaPods 常见问题。

  4. 成功安装后,项目文件夹下会生成一个后缀为 .xcworkspace 的文件,通过 Xcode 打开该文件进行后续操作。

  1. 前往下载页面,获取最新版的 SDK,然后解压。

  2. 将 SDK 包内 libs 路径下的文件,拷贝到你的项目路径下。

  3. 打开 Xcode,添加对应动态库,确保添加的动态库 Embed 属性设置为 Embed & Sign。

    信息

    SDK 以 XCFramework 形式提供,支持 arm64 架构的 iOS 真机,以及 arm64、x86_64 架构的模拟器。

  1. 在 Xcode 中,进入 File > Add Package Dependencies...,根据 SDK 版本输入对应的 HTTPS 仓库地址:

    Text
    // 对于 4.6.0 及之后的版本
    https://github.com/Shengwang-Lab/ShengwangAudio_iOS.git
    
    // 对于 4.6.0 之前的版本
    https://github.com/AgoraIO/AgoraAudio_iOS.git
  2. 在 Dependency Rule 中选择 Exact Version,输入需要集成的 SDK 版本(例如 4.7.0),然后点击 Add Package。

  3. 在产品列表中,为应用的 Target 选择 RtcBasic 基础组件,其他组件按功能需要选择,然后完成添加。

    添加完成后,可在工程的 Package Dependencies 中确认 SDK 版本。更多设置请参考 Apple 官方文档。

注意

自 4.5.0 起,RTC SDK 和 RTM SDK (2.2.0 及以上版本) 都包含 aosl.xcframework 库。如果你通过 CDN 手动集成 RTC SDK 且同时集成了 RTM SDK,为避免冲突,请手动删除版本较低的 aosl.xcframework 库。4.6.0 RTC SDK aosl.xcframework 库版本为 1.3.0。你可以通过查看 aosl.xcframework 文件的属性来得知库的版本信息。

创建用户界面

根据使用场景,为你的项目创建一个用户界面。用以下代码替换 ViewController.swift 文件中的内容:

实现步骤

下图展示了使用声网 RTC SDK 实现纯语音互动的基本流程。

下面列出了一段实现纯语音互动基本流程的完整代码以供参考。复制以下代码到 ViewController.swift 文件中替换原有内容即可。

信息

在 appId、token 和 channelName 字段中传入你在控制台获取到的 App ID、临时 Token,以及生成临时 Token 时填入的频道名。

导入声网组件

在 ViewController.swift 文件中引入 AgoraRtcKit。

Swift
import AgoraRtcKit

初始化引擎

调用 sharedEngineWithConfig 方法,创建并初始化 AgoraRtcEngineKit。

注意

在初始化 SDK 前,需确保终端用户已经充分了解并同意相关的隐私政策。

Swift
// 在这里输入你在声网控制台中获取的 App ID
agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId:<#Your App ID#>, delegate: self)

加入频道并发布音频流

调用 joinChannelByToken[2/4] 方法、填入你在控制台获取的临时 Token,以及获取 Token 时填入的频道名加入频道,并设置用户角色。

Swift
let options = AgoraRtcChannelMediaOptions()
    // 设置用户角色为主播
    options.clientRoleType = .broadcaster
    // 发布麦克风采集的音频
    options.publishMicrophoneTrack = true
    // 自动订阅所有音频流
    options.autoSubscribeAudio = true
    // 使用临时 Token 加入频道,在这里传入你的项目的 Token 和频道名
    // uid 为 0 表示由引擎内部随机生成; 成功后会触发 didJoinChannel 回调
    agoraKit.joinChannel(byToken: <#Your Token#>, channelId: <#Your Channel Name#>, uid: 0, mediaOptions: options)

实现常用回调

根据使用场景,定义必要的回调。以下示例代码展示了如何实现 didJoinChannel 和 didOfflineOfUid 回调。

Swift
// 成功加入频道回调
func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinChannel channel: String, withUid uid: UInt, elapsed: Int) {
    print("didJoinChannel: \(channel), uid: \(uid)")
}
// 远端用户或主播离开当前频道回调
func rtcEngine(_ engine: AgoraRtcEngineKit, didOfflineOfUid uid: UInt, reason: AgoraUserOfflineReason) {
}

开始音频互动

当视图加载完成后,在 viewDidLoad 中调用一系列方法加入频道,开始音频互动。

Swift
override func viewDidLoad() {
    super.viewDidLoad()
    // 当加载视图后,你可以进行其他其他设置
    // 当调用声网 API 时,以下函数会被调用
    initializeAgoraEngine()
    joinChannel()
}

结束音频互动

  1. 调用 leaveChannel 方法离开频道,与会话相关的资源也会被释放。

    Swift
    agoraKit.leaveChannel(nil)
  2. 调用 destroy 销毁引擎,并释放声网 SDK 中使用的所有资源。

    Swift
    AgoraRtcEngineKit.destroy()

    警告

    • 调用该方法后,你将无法再使用 SDK 的所有方法和回调。如需再次使用实时音频互动功能,你必须重新创建一个新的引擎。详见初始化引擎。
      • 该方法为同步调用。需要等待引擎资源释放后才能执行其他操作,因此建议在子线程中调用该方法,避免主线程阻塞。

调试 App

参考以下步骤来测试你的 App:

  1. 将 iOS 设备连接至计算机。
  2. 点击 Build 来运行你的项目,需等待几秒至 App 安装完成。
  3. 允许 App 访问设备的麦克风权限。
  4. (可选)如果设备上弹出不受信任的开发者提示,则首先点击取消关闭该提示,然后在 iOS 设备上打开设置 > 通用 > VPN 与设备管理,在开发者 APP 中选择信任该开发者。
  5. 使用第二台 iOS 设备,重复以上步骤,在该设备上安装 App,并打开 App 加入频道,观察测试结果:双方可以听到对方的声音。

后续步骤

本文的示例使用了临时 Token 加入频道。在测试或生产环境中,为确保通信安全,声网推荐使用 Token 服务器来生成 Token,详见使用 Token 鉴权。

参考信息

示例项目

声网提供了开源的纯语音互动示例项目供你参考,你可以前往下载或查看其中的源代码。

常见问题

相关文档