虚拟节拍器

configRhythmPlayer

配置虚拟节拍器。

C++

virtual int configRhythmPlayer(const AgoraRhythmPlayerConfig& config) = 0;

调用 startRhythmPlayer 后，你可以调用该方法重新配置虚拟节拍器。

成功调用该方法后，SDK 会在本地触发 onRhythmPlayerStateChanged 回调，报告虚拟节拍器的状态。

注意：

• 该方法仅适用于 Android 和 iOS。

• 开启虚拟节拍器后，SDK 会从头开始播放指定的音频文件，并根据你在 AgoraRhythmPlayerConfig 中设置的 beatsPerMinute 控制每个文件的播放时长。例如，将 beatsPerMinute 设为 60，则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长，则 SDK 只播放节拍时长部分的音频。

• 虚拟节拍器的声音默认会发布至远端，如果你不希望远端用户听到虚拟节拍器的声音，你可以将 ChannelMediaOptions 中的 publishRhythmPlayerTrack 设为 false。

参数

参数名	描述
config	节拍器配置。详见 AgoraRhythmPlayerConfig。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

startRhythmPlayer

开启虚拟节拍器。

C++

virtual int startRhythmPlayer(const char* sound1, const char* sound2, const AgoraRhythmPlayerConfig& config) = 0;

在音乐教学、体育教学等场景中，老师通常需要使用节拍器，让学生跟着正确的节拍练习。节拍由强拍和弱拍组成，每小节的第一拍称为强拍，其余称为弱拍。

你需要在该方法中设置强拍和弱拍的文件路径、每小节的拍数、节拍速度以及是否将节拍器的声音发送至远端。

成功调用该方法后，SDK 会在本地触发 onRhythmPlayerStateChanged 回调，报告虚拟节拍器的状态。

注意：

• 该方法仅适用于 Android 和 iOS。

• 开启虚拟节拍器后，SDK 会从头开始播放指定的音频文件，并根据你在 AgoraRhythmPlayerConfig 中设置的 beatsPerMinute 控制每个文件的播放时长。例如，将 beatsPerMinute 设为 60，则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长，则 SDK 只播放节拍时长部分的音频。

• 虚拟节拍器的声音默认会发布至远端，如果你不希望远端用户听到虚拟节拍器的声音，你可以将 ChannelMediaOptions 中的 publishRhythmPlayerTrack 设为 false。

参数

参数名	描述
sound1	强拍文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如 C:\music\audio.mp4。支持的音频文件格式见 RTC SDK 支持播放哪些格式的音频文件。
sound2	弱拍文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如 C:\music\audio.mp4。支持的音频文件格式见 RTC SDK 支持播放哪些格式的音频文件。
config	节拍器配置。详见 AgoraRhythmPlayerConfig。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败

  • -22: 无法找到音频文件。请填写正确的 sound1 和 sound2。

所属接口类

• IRtcEngine

stopRhythmPlayer

关闭虚拟节拍器。

C++

virtual int stopRhythmPlayer() = 0;

调用 startRhythmPlayer 后，你可以调用该方法关闭虚拟节拍器。

注意： 该方法仅适用于 Android 和 iOS。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

onRhythmPlayerStateChanged

虚拟节拍器状态发生改变回调。

C++

virtual void onRhythmPlayerStateChanged(RHYTHM_PLAYER_STATE_TYPE state, RHYTHM_PLAYER_ERROR_TYPE errorCode) {
  (void)state;
  (void)errorCode;
}

虚拟节拍器状态发生改变时，SDK 会触发该回调报告当前的虚拟节拍器状态。在虚拟节拍器出现故障时，该回调可以帮助你了解当前虚拟节拍的状态以及出现故障的原因，方便你排查问题。

注意： 该回调仅适用于 Android 和 iOS。

参数

参数名	描述
state	当前的虚拟节拍器状态，详见 RHYTHM_PLAYER_STATE_TYPE。
errorCode	虚拟节拍器发生错误的错误码和错误信息，详见 RHYTHM_PLAYER_ERROR_TYPE。

所属接口类

• IRtcEngineEventHandler