文档中心
全部产品
Console Agora.io 社区 提交工单
简体中文
search-icon

空间音效

更新时间 2022/08/12 06:37:07

Agora 为电子竞技、在线会议等场景提供空间音效功能，让用户拥有沉浸式的音频体验。

  • 通过更新用户的空间位置，用户可以实时感受到其他用户距离、方位、朝向的变化。
  • 通过更新媒体播放器的空间位置，用户可以为背景音、伴奏等媒体资源增添空间感。
  • 通过设置参数，体验声音模糊、空气衰减等效果。
空间音效功能当前处于实验阶段，请联系 sales@agora.io 开通空间音效功能，如果需要技术支持，请联系技术支持。

技术原理

用户的空间音效

Agora 为用户提供如下方案设置空间音效：

  • 本地直角坐标系计算方案: 该方案使用 AgoraLocalSpatialAudioKit 类实现空间音效，通过 SDK 计算本地用户与远端用户的相对位置。你需要分别调用 updateSelfPosition 和 updateRemotePosition 更新本地和远端用户的空间坐标，本地用户才能听到远端用户的空间音效。
  • 本地球坐标系计算方案: 该方案使用 AgoraRtcEngineKit 类的 enableSpatialAudio 和 setRemoteUserSpatialAudioParams 实现空间音效。你需要向 SDK 传入本地用户与远端用户的相对水平角、俯仰角、距离与朝向，本地用户才能听到远端用户的空间音效。如果你的 app 基于空间坐标来确定用户位置，在使用空间音效时，你还需要通过用户的空间坐标自行计算出用户间的相对水平角、俯仰角、距离与朝向。

媒体播放器的空间音效

Agora 为媒体播放器提供如下两种方案设置空间音效：

  • 本地直角坐标系计算方案: 该方案通过 SDK 计算本地用户和媒体播放器的相对位置。你需要在 AgoraLocalSpatialAudioKit 类中分别调用 updateSelfPosition 和 updatePlayerPositionInfo 更新本地用户和媒体播放器的空间坐标，本地用户才能听到媒体播放器的空间音效。
  • 本地球坐标系计算方案: 该方案使用 AgoraRtcMediaPlayerProtocol 类的 setSpatialAudioParams 实现空间音效。你需要向 SDK 传入本地用户与媒体播放器的相对水平角、俯仰角、距离与朝向，本地用户才能听到媒体播放器的空间音效。如果你的 app 基于空间坐标来确定本地用户和媒体播放器的位置，在使用空间音效时，你还需要通过本地用户与媒体播放器的空间坐标自行计算出两者间的相对水平角、俯仰角、距离与朝向。

前提条件

在实现空间音效前，请确保已在你的项目中实现基本的实时音视频功能。详见快速开始：

实现方法

用户的空间音效

本地直角坐标系计算方案

该方案通过 AgoraLocalSpatialAudioKit 类实现空间音效，API 调用时序与操作步骤如下：

  1. 在调用其他 Agora API 前，调用 sharedEngineWithAppId 并填入你的 App ID，初始化 AgoraRtcEngineKit 对象。

  2. 在调用 AgoraLocalSpatialAudioKit 类的其他 API 前，调用 sharedLocalSpatialAudioWithConfig 初始化 AgoraLocalSpatialAudioKit 对象。

  3. 调用 setAudioProfile 设置 profile（音频编码属性）为 AgoraAudioProfileDefault、scenario（音频应用场景）为 AgoraAudioScenarioGameStreaming。

  4. 调用带 mediaOptions 参数的 joinChannelByToken 加入频道（使用 RTC Token）。你需要在 AgoraRtcChannelMediaOptions 中设置 channelProfile（频道场景）为 AgoraChannelProfileLiveBroadcasting（直播场景）、clientRoleType（用户角色）为 AgoraClientRoleBroadcaster（主播）。

  5. Agora 默认订阅所有远端用户的音频流，你需要调用 AgoraRtcEngineKit 的 muteAllRemoteAudioStreams(true) 取消订阅所有远端用户，否则你在步骤 6 中设置的音频接收范围会无效。

  6. 调用下列方法，设置音频接收范围：

    1. 调用 setMaxAudioRecvCount 设置音频接收范围内最多可接收的音频流数。
    2. 调用 setAudioRecvRange 设置音频接收范围（米）。
    3. 调用 setDistanceUnit 设置游戏引擎单位距离的长度（米）。

  7. 先后调用 updateSelfPosition 和 updateRemotePosition 更新本地和远端用户的空间位置，体验空间音效。

  8. 如果无需体验空间音效，则调用 clearRemotePositions 删除所有远端用户的空间位置信息。删除后，本地用户会听不到所有远端用户。

  9. 调用 AgoraLocalSpatialAudioKit 的 destroy 销毁 AgoraLocalSpatialAudioKit 对象。

    必须在调用 AgoraRtcEngineKit 的 destroy 前销毁 AgoraLocalSpatialAudioKit 对象。

  10. 调用 AgoraRtcEngineKit 的 leaveChannel 和 destroy 离开频道并销毁 AgoraRtcEngineKit 对象。

本地球坐标系计算方案

该方案通过 AgoraRtcEngineKit 类实现空间音效，API 调用时序与操作步骤如下：

  1. 在调用其他 Agora API 前，调用 sharedEngineWithAppId 并填入你的 App ID，初始化 AgoraRtcEngineKit 对象。
  2. 调用 setAudioProfile 设置 profile（音频编码属性）为 AgoraAudioProfileDefault、scenario（音频应用场景）为 AgoraAudioScenarioGameStreaming。
  3. 调用带 mediaOptions 参数的 joinChannelByToken 加入频道（使用 RTC Token）。你需要在 AgoraRtcChannelMediaOptions 中设置 channelProfile（频道场景）为 AgoraChannelProfileLiveBroadcasting（直播场景）、clientRoleType（用户角色）为 AgoraClientRoleBroadcaster（主播）。
  4. 调用 enableSpatialAudio(true) 开启空间音效。
  5. 调用 setRemoteUserSpatialAudioParams 设置本地用户与远端用户的相对水平角、俯仰角、距离、朝向，以及是否开启声音模糊和空气衰减效果，体验空间音效。
  6. 如果无需体验空间音效，则调用 enableSpatialAudio(false) 关闭空间音效。
  7. 调用 AgoraRtcEngineKit 的 leaveChannel 和 destroy 离开频道并销毁 AgoraRtcEngineKit 对象。

媒体播放器的空间音效

本地直角坐标系计算方案

该方案通过 AgoraLocalSpatialAudioKit 类中的 updateSelfPosition 和 updatePlayerPositionInfo 实现空间音效。以 AgoraLocalSpatialAudioKit 类为例，操作步骤如下：

  1. 在调用其他 Agora API 前，调用 sharedEngineWithAppId 并填入你的 App ID，初始化 AgoraRtcEngineKit 对象。

  2. 在调用 AgoraLocalSpatialAudioKit 类的其他 API 前，调用 sharedLocalSpatialAudioWithConfig 初始化 AgoraLocalSpatialAudioKit 对象。

  3. 调用 setAudioProfile 设置 profile（音频编码属性）为 AgoraAudioProfileDefault、scenario（音频应用场景）为 AgoraAudioScenarioGameStreaming。

  4. 调用带 mediaOptions 参数的 joinChannelByToken 加入频道（使用 RTC Token）。你需要在 AgoraRtcChannelMediaOptions 中设置 channelProfile（频道场景）为 AgoraChannelProfileLiveBroadcasting（直播场景）、clientRoleType（用户角色）为 AgoraClientRoleBroadcaster（主播）。

  5. Agora 默认订阅所有远端用户的音频流，你需要调用 AgoraRtcEngineKit 的 muteAllRemoteAudioStreams(true) 取消订阅所有远端用户，否则你在步骤 6 中设置的音频接收范围会无效。

  6. 调用下列方法，设置音频接收范围：

    1. 调用 setMaxAudioRecvCount 设置音频接收范围内最多可接收的音频流数。
    2. 调用 setAudioRecvRange 设置音频接收范围（米）。
    3. 调用 setDistanceUnit 设置游戏引擎单位距离的长度（米）。

  7. 先后调用 updateSelfPosition 和 updatePlayerPositionInfo 更新本地用户和媒体播放器的空间位置，体验空间音效。

  8. 调用 AgoraLocalSpatialAudioKit 的 destroy 销毁 AgoraLocalSpatialAudioKit 对象。

    必须在调用 AgoraRtcEngineKit 的 destroy 前销毁 AgoraLocalSpatialAudioKit 对象。

  9. 调用 AgoraRtcEngineKit 的 destroy 销毁 AgoraRtcEngineKit 对象。

本地球坐标系计算方案

该方案通过 AgoraRtcMediaPlayerProtocol 类中的 setSpatialAudioParams 实现空间音效，操作步骤如下：

  1. 在调用其他 Agora API 前，调用 sharedEngineWithAppId 并填入你的 App ID，初始化 AgoraRtcEngineKit 对象。
  2. 调用 setAudioProfile 设置 profile（音频编码属性）为 AgoraAudioProfileDefault、scenario（音频应用场景）为 AgoraAudioScenarioGameStreaming。
  3. 调用带 mediaOptions 参数的 joinChannelByToken 加入频道（使用 RTC Token）。你需要在 AgoraRtcChannelMediaOptions 中设置 channelProfile（频道场景）为 AgoraChannelProfileLiveBroadcasting（直播场景）、clientRoleType（用户角色）为 AgoraClientRoleBroadcaster（主播）。
  4. 调用 createMediaPlayerWithDelegate 创建 AgoraRtcMediaPlayerProtocol 对象。
  5. 调用 open 打开媒体资源。
  6. 调用 setSpatialAudioParams 设置本地用户与媒体播放器的相对水平角、俯仰角、距离与朝向，以及是否开启声音模糊和空气衰减效果，体验空间音效。
  7. 如果无需体验空间音效，则调用 setSpatialAudioParams(nil) 关闭空间音效。
  8. 调用 destroyMediaPlayer 销毁 AgoraRtcMediaPlayerProtocol 对象。
  9. 调用 AgoraRtcEngineKit 的 destroy 销毁 AgoraRtcEngineKit 对象。

示例代码

本节展示使用本地直角坐标系计算方案实现媒体播放器空间音效的示例代码：

// Swift
class SpatialAudioMain: BaseViewController {
    var agoraKit: AgoraRtcEngineKit!
    var mediaPlayer: AgoraRtcMediaPlayerProtocol!
    var localSpatial: AgoraLocalSpatialAudioKit!

    override func viewDidLoad() {
        // 初始化 AgoraRtcEngineKit
        agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId: KeyCenter.AppId, delegate: self)
        // 设置频道场景为直播场景
        agoraKit.setChannelProfile(.liveBroadcasting)
        // 设置用户角色为主播
        agoraKit.setClientRole(.broadcaster)
        // 设置音频编码属性和应用场景
        agoraKit.setAudioProfile(.default, scenario: .gameStreaming)
        guard let filePath = Bundle.main.path(forResource: "audiomixing", ofType: "mp3") else {return}
        // 创建媒体播放器
        mediaPlayer = agoraKit.createMediaPlayer(with: self)
        // 打开媒体资源
        mediaPlayer.open(filePath, startPos: 0)

        // 初始化 AgoraLocalSpatialAudioKit
        let localSpatialConfig = AgoraLocalSpatialAudioConfig()
        localSpatialConfig.rtcEngine = agoraKit
        localSpatial = AgoraLocalSpatialAudioKit.sharedLocalSpatialAudio(with: localSpatialConfig)
        // 设置音频接收范围
        localSpatial.setAudioRecvRange(50)
        // 设置游戏引擎单位距离的长度
        localSpatial.setDistanceUnit(1)
        // 更新本地用户的空间位置
        let pos = [NSNumber(0.0), NSNumber(0), NSNumber(0.0)]
        let forward = [NSNumber(1.0), NSNumber(0.0), NSNumber(0.0)]
        let right = [NSNumber(0.0), NSNumber(1.0), NSNumber(0.0)]
        let up = [NSNumber(0.0), NSNumber(0.0), NSNumber(1.0)]
        self.localSpatial.updateSelfPosition(pos, axisForward: forward, axisRight: right, axisUp: up)
    }

    override func willMove(toParent parent: UIViewController?) {
        if parent == nil {
            // 销毁 AgoraLocalSpatialAudioKit
            AgoraLocalSpatialAudioKit.destroy()
            // 销毁 AgoraRtcEngineKit
            AgoraRtcEngineKit.destroy()
        }
    }

    // 更新媒体播放器的空间位置
    func updateRemoteUserSpatialAudioPositon() {
        let maxR = UIScreen.main.bounds.height / 2.0
        let maxSpatailDistance = 30.0
        let spatialDistance = currentDistance * maxSpatailDistance / maxR

        let posForward = spatialDistance * cos(currentAngle);
        let posRight = spatialDistance * sin(currentAngle);
        let position = [NSNumber(value: posForward), NSNumber(value: posRight), NSNumber(0.0)]
        let forward = [NSNumber(1.0), NSNumber(0.0), NSNumber(0.0)]

        let positionInfo = AgoraRemoteVoicePositionInfo()
        positionInfo.position = position
        positionInfo.forward = forward
        localSpatial.updatePlayerPositionInfo(Int(mediaPlayer.getMediaPlayerId()), positionInfo: positionInfo)
    }
}

相关文档

示例项目

Agora 在 GitHub 上提供开源的示例项目。你可以前往下载，或查看其中的源代码：

API 参考