播放音效或音乐文件

  • macOS

更新时间

了解实时互动 RTC 在不同平台上的播放音效或音乐文件方式,包括接入流程、关键配置和平台差异。

在游戏或 K 歌等实时音视频场景中,为烘托气氛、增添趣味性,用户通常需要播放音效或音乐文件。

本文介绍如何在你的项目中实现播放音效或音乐文件功能。

技术原理

声网提供了以下 API, 帮助你实现播放音效或音乐文件:

  • 音效 API:播放持续时间短的氛围音,例如掌声、欢呼声、打斗声、枪击声等,通常可以同时播放多个音效文件。
  • 音乐 API:播放比较长的音乐文件,例如,在唱歌时播放伴奏,在聊天时播放背景音乐。同一时间,只能播放一个音乐文件。

注意

如果使用 startAudioMixing 等音乐 API 播放时长较短的音效文件、或使用 playEffect 等音效 API 播放时长较长的音乐文件可能会播放失败。

这些方法主要包括如下功能:

功能音效 API音乐 API
播放或停止播放特定的音频文件
  • preloadEffect
  • unloadEffect
  • playEffect
  • stopEffect
  • stopAllEffects
  • startAudioMixing
  • stopAudioMixing
暂停或恢复播放音频文件
  • pauseEffect
  • pauseAllEffects
  • resumeEffect
  • resumeAllEffects
  • pauseAudioMixing
  • resumeAudioMixing
获取和调整音频文件的播放位置和音量
  • setEffectPosition
  • getEffectCurrentPosition
  • getEffectsVolume
  • setEffectsVolume
  • setVolumeOfEffect
  • getAudioMixingCurrentPosition
  • setAudioMixingPosition
  • getAudioMixingPublishVolume
  • adjustAudioMixingPublishVolume
  • getAudioMixingPlayoutVolume
  • adjustAudioMixingPlayoutVolume
报告音频文件的播放状态rtcEngineDidAudioEffectFinishaudioMixingStateChanged
表格内容超出当前宽度,可横向滚动查看更多列。

前提条件

在进行操作之前,请确保你已满足以下条件:

实现播放音频文件

本节介绍如何调用音效 API 和音乐混音 API,在你的项目中播放音效和音乐混音文件。

播放音效

加入频道前,调用 preloadEffect 方法预加载音效文件。加入频道后,调用 playEffect 方法播放指定音效文件。多次调用 playEffect,设置多个音效 ID,同时播放多个音效文件。音效播放结束后,SDK 触发 rtcEngineDidAudioEffectFinish 回调。

在你的声网项目中,打开管理音效播放的文件并添加如下代码:

// 设置音效 ID,作为识别音效文件的唯一标识
int EFFECT_ID = 1;
// 指定音效文件的路径
NSString *filePath = "your filepath";
// 如果要反复播放音效,你需要将音效文件预加载至内存。如果音效文件体积较大,请勿预加载
// 你只能预加载本地音效文件
[agoraKit preloadEffect: EFFECT_ID filePath: filePath];

// 设置音效循环播放的次数。-1 表示无限循环
int loopCount = -1;
// 设置音效的音调。1 表示原始音调
double pitch = 1;
// 设置音效的空间位置。0.0 表示音效出现在正前方
double pan = 1;
// 设置音效音量。100 表示原始音量
double gain = 100.0;
// 设置是否将音效发布至远端
BOOL publish = true;
// 调用 playEffect 播放指定的音效文件
// 多次调用 playEffect,设置多个音效 ID,同时播放多个音效文件
[agoraKit playEffect: EFFECT_ID filePath: filePath loopCount: loopCount pitch: pitch pan: pan gain: gain publish: publish];

// 暂停或恢复播放音效文件
[agoraKit pauseEffect: EFFECT_ID];
[agoraKit resumeEffect: EFFECT_ID];

// 设置指定的本地音效文件的播放位置
[agoraKit setEffectPosition: EFFECT_ID pos: 500];

// 设置所有音效文件的播放音量
[agoraKit setEffectsVolume: volume: 50.0];
// 设置指定音效文件的播放音量
[agoraKit setVolumeOfEffect: EFFECT_ID volume: 50.0];

// 卸载预加载的音效文件
[agoraKit unloadEffect: EFFECT_ID];
// 暂停播放所有音效文件
[agoraKit stopAllEffects];

// 当音效文件播放结束后触发该回调
- (void)rtcEngineDidAudioEffectFinish:(AgoraRtcEngineKit* _Nonnull)engine soundId:(NSInteger)soundId;

播放音乐

入频道之前或之后,调用 startAudioMixing 方法播放音乐文件。成功调用该方法后,音乐混音状态发生变化时,SDK 触发 audioMixingStateChanged 回调。该回调也报告音乐混音状态变化的原因。

你还可以通过下列方法实现播放控制:

  • pauseAudioMixing:暂停播放。
  • resumeAudioMixing:恢复播放。
  • stopAudioMixing:停止播放。
  • setAudioMixingPosition:设置当前音乐文件的播放位置。
  • adjustAudioMixingPlayoutVolume:调节当前音乐文件在本地的播放音量。
  • adjustAudioMixingPublishVolume:调节当前音乐文件在远端的播放音量。

在你的声网项目中,打开管理音效播放的文件夹添加以下代码:

// 指定本地或在线音乐文件的路径
NSString *filePath = @"your file path";
// 设置是否只在本地播放音乐文件。No 表示本地用户和远端用户都能听到音乐
BOOL loopback = NO;
// 音乐文件循环播放的次数 1 表示仅播放一次
NSInteger cycle = 1;
// 设置音乐文件的起始播放位置
NSInteger startPos = 0;
// 调用 startAudioMixing 方法播放音乐文件
[agoraKit startAudioMixing: filePath loopback: loopback cycle: cycle startPos: startPos];

// 当音乐文件播放状态发生改变时触发该回调
// 在收到 localAudioMixingStateDidChanged 回调后,声网建议调用其他音乐混音 API,如 pauseAudioMixing 或 getAudioMixingDuration
- (void)rtcEngine:(AgoraRtcEngineKit* _Nonnull)engine audioMixingStateChanged:(AgoraAudioMixingStateType)state reasonCode:(AgoraAudioMixingReasonCode)reasonCode;

// 暂停或恢复播放音乐文件
[agoraKit pauseAudioMixing];
[agoraKit resumeAudioMixing];

// 获取当前音乐文件的总时长
[agoraKit getAudioMixingDuration];
// 设置当前音乐文件的播放位置。500 表示从音乐文件的第 500 ms 开始播放
[agoraKit setAudioMixingPosition: pos: 500];

// 调节当前音乐文件在远端的播放音量
[agoraKit adjustAudioMixingPublishVolume: volume: 50];
// 调节当前音乐文件在本地的播放音量
[agoraKit adjustAudioMixingPlayoutVolume: volume: 50];

参考信息

示例项目

声网提供如下开源的示例项目。你可以前往下载或查看其中的源代码。

API 参考

相关文档

为什么通过系统音量无法调节背景音乐?