虚拟节拍器

configRhythmPlayerCopy Anchor Link

配置虚拟节拍器。

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

调用 startRhythmPlayer 后，你可以调用该方法重新配置虚拟节拍器。启用虚拟节拍器后，SDK 会从头开始播放指定的音效文件，并根据你在 AgoraRhythmPlayerConfig 中设置的 beatsPerMinute 控制每个文件的播放时长。例如，如果将 beatsPerMinute 设置为 60，SDK 每秒播放一个节拍。如果文件时长超过节拍时长，SDK 只播放节拍时长内的音频。默认情况下，虚拟节拍器的声音会在频道中发布。如果希望远端用户也能听到该声音，可以在 ChannelMediaOptions 中将 publishRhythmPlayerTrack 设置为 true。

调用时机Copy Anchor Link

该方法可以在加入频道前或后调用。

相关回调Copy Anchor Link

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

参数Copy Anchor Link

返回值Copy Anchor Link

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

所属接口类Copy Anchor Link

• IRtcEngine

startRhythmPlayerCopy Anchor Link

启用虚拟节拍器。

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

启用虚拟节拍器后，SDK 会从头开始播放指定的音效文件，并根据你在 AgoraRhythmPlayerConfig 中设置的 beatsPerMinute 控制每个文件的播放时长。例如，如果你将 beatsPerMinute 设置为 60，SDK 每秒播放一个节拍。如果文件时长超过节拍时长，SDK 只播放节拍时长内的音频内容。 默认情况下，虚拟节拍器的声音会在频道中发布。如果你希望远端用户也能听到该声音，可以在 ChannelMediaOptions 中将 publishRhythmPlayerTrack 设置为 true。

适用场景Copy Anchor Link

在音乐教育、体育教学等场景中，教师通常需要使用节拍器帮助学生按照正确的节奏进行练习。节拍由强拍和弱拍组成，每小节的第一个节拍称为强拍，其余为弱拍。

调用时机Copy Anchor Link

该方法可以在加入频道前或加入频道后调用。

相关回调Copy Anchor Link

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

参数Copy Anchor Link

返回值Copy Anchor Link

• 0：方法调用成功。

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

  • -22：未找到音效文件。请为 sound1 和 sound2 设置正确的路径。

所属接口类Copy Anchor Link

• IRtcEngine

stopRhythmPlayerCopy Anchor Link

禁用虚拟节拍器。

virtual int stopRhythmPlayer() = 0;

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

返回值Copy Anchor Link

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

所属接口类Copy Anchor Link

• IRtcEngine

onRhythmPlayerStateChangedCopy Anchor Link

虚拟节拍器状态发生变化时的回调。

virtual void onRhythmPlayerStateChanged(RHYTHM_PLAYER_STATE_TYPE state, RHYTHM_PLAYER_REASON reason)

该回调用于报告虚拟节拍器的当前状态，指示本地音频流的状态，帮助你在音频异常时排查问题。

触发时机Copy Anchor Link

当虚拟节拍器状态发生变化时触发。

参数Copy Anchor Link

所属接口类Copy Anchor Link

• IRtcEngineEventHandler