虚拟节拍器

configRhythmPlayer:

配置虚拟节拍器。

Objective-C

- (int)configRhythmPlayer:(AgoraRhythmPlayerConfig * _Nullable)config NS_SWIFT_NAME(configRhythmPlayer(_:));

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

调用时机

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

参数

config

节拍器配置。详见 AgoraRhythmPlayerConfig。

返回值

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

所属接口类

• AgoraRtcEngineKit

startRhythmPlayer:sound2:config:

启用虚拟节拍器。

Objective-C

- (int)startRhythmPlayer:(NSString * _Nonnull)sound1 sound2:(NSString * _Nonnull)sound2 config:(AgoraRhythmPlayerConfig *  _Nullable)config NS_SWIFT_NAME(startRhythmPlayer(_:sound2:config:));

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

适用场景

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

调用时机

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

相关回调

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

参数

sound1

强拍音效文件的绝对路径或 URL 地址（包括文件扩展名）。例如，/var/mobile/Containers/Data/audio.mp4。该方法支持的音频文件格式，详见声网 RTC SDK 支持哪些格式的音频文件。

sound2

弱拍音效文件的绝对路径或 URL 地址（包括文件扩展名）。例如，/var/mobile/Containers/Data/audio.mp4。该方法支持的音频文件格式，详见声网 RTC SDK 支持哪些格式的音频文件。

config

节拍器配置。详见 AgoraRhythmPlayerConfig。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -22：未找到音效文件。请设置正确的 sound1 和 sound2 路径。

所属接口类

• AgoraRtcEngineKit

stopRhythmPlayer

禁用虚拟节拍器。

Objective-C

- (int)stopRhythmPlayer NS_SWIFT_NAME(stopRhythmPlayer());

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

返回值

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

所属接口类

• AgoraRtcEngineKit

rtcEngine:didRhythmPlayerStateChanged:reason:

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

Objective-C

- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didRhythmPlayerStateChanged:(AgoraRhythmPlayerState)state
        reason:(AgoraRhythmPlayerReason)reason NS_SWIFT_NAME(rtcEngine(_:didRhythmPlayerStateChanged:reason:));

当虚拟节拍器状态发生变化时，SDK 会触发该回调以报告当前虚拟节拍器的状态。该回调指示本地音频流的状态，并帮助你在音频异常发生时排查问题。

触发时机

该回调在虚拟节拍器状态发生变化时被触发。

参数

engine

当前使用的 AgoraRtcEngineKit 实例。

state

当前虚拟节拍器的状态，详见 AgoraRhythmPlayerState。

reason

与虚拟节拍器错误相关的错误码和错误信息，详见 AgoraRhythmPlayerReason。

所属接口类

• AgoraRtcEngineDelegate