# 虚拟节拍器 (/zh-CN/api-reference/rtc/macos/play/rhythmplayer) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## configRhythmPlayer: [#configrhythmplayer] 配置虚拟节拍器。 ```objc - (int)configRhythmPlayer:(AgoraRhythmPlayerConfig * _Nullable)config NS_SWIFT_NAME(configRhythmPlayer(_:)); ``` :::error[废弃] 自 v4.6.0 版本废弃。 ::: 调用 `startRhythmPlayer` 方法后,你可以调用该方法重新配置虚拟节拍器。启用虚拟节拍器后,SDK 会从头开始播放指定的音效文件,并根据你在 [AgoraRhythmPlayerConfig](/zh-CN/api-reference/rtc/macos/class-agorarhythmplayerconfig) 中设置的 `beatsPerMinute` 控制每个文件的播放时长。例如,如果将 `beatsPerMinute` 设置为 60,SDK 每秒播放一个节拍。如果文件时长超过节拍时长,SDK 只播放节拍时长内的音频。默认情况下,虚拟节拍器的声音会在频道中发布。如果你希望远端用户也能听到该声音,可以在 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中将 `publishRhythmPlayerTrack` 设置为 YES。 ### 调用时机 [#调用时机] 该方法可以在加入频道前或后调用。 ### 参数 [#参数] 节拍器配置。详见 [AgoraRhythmPlayerConfig](/zh-CN/api-reference/rtc/macos/class-agorarhythmplayerconfig)。 ### 返回值 [#返回值] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## startRhythmPlayer\:sound2\:config: [#startrhythmplayersound2config] 启用虚拟节拍器。 ```objc - (int)startRhythmPlayer:(NSString * _Nonnull)sound1 sound2:(NSString * _Nonnull)sound2 config:(AgoraRhythmPlayerConfig * _Nullable)config NS_SWIFT_NAME(startRhythmPlayer(_:sound2:config:)); ``` :::error[废弃] 自 v4.6.0 版本废弃。 ::: 启用虚拟节拍器后,SDK 会从头开始播放你指定的音效文件,并根据 [AgoraRhythmPlayerConfig](/zh-CN/api-reference/rtc/macos/class-agorarhythmplayerconfig) 中设置的 `beatsPerMinute` 控制每个文件的播放时长。例如,如果你将 `beatsPerMinute` 设置为 60,SDK 每秒播放一个节拍。如果文件时长超过节拍时长,SDK 只播放节拍时长内的音频内容。默认情况下,虚拟节拍器的声音会在频道中发布。如果你希望远端用户也能听到该声音,可以在 [AgoraRtcChannelMediaOptions](/zh-CN/api-reference/rtc/macos/class-channelmediaoptions) 中将 `publishRhythmPlayerTrack` 设置为 YES。 ### 适用场景 [#适用场景] 在音乐教育、体育教学等场景中,教师通常需要使用节拍器帮助学生按照正确的节奏进行练习。节拍由强拍和弱拍组成,每小节的第一个节拍称为强拍,其余为弱拍。 ### 调用时机 [#调用时机-1] 该方法可以在加入频道前或加入频道后调用。 ### 相关回调 [#相关回调] 调用该方法成功后,SDK 会在本地触发 [rtcEngine\:didRhythmPlayerStateChanged\:reason:](/zh-CN/api-reference/rtc/macos/play/rhythmplayer#callback_irtcengineeventhandler_onrhythmplayerstatechanged) 回调,报告虚拟节拍器的状态。 ### 参数 [#参数-1] 强拍音效文件的绝对路径或 URL 地址(包括文件扩展名)。例如,/var/mobile/Containers/Data/audio.mp4。该方法支持的音频文件格式,详见[声网 RTC SDK 支持哪些格式的音频文件](/zh-CN/reference/faq/product/audio_format)。 弱拍音效文件的绝对路径或 URL 地址(包括文件扩展名)。例如,/var/mobile/Containers/Data/audio.mp4。该方法支持的音频文件格式,详见[声网 RTC SDK 支持哪些格式的音频文件](/zh-CN/reference/faq/product/audio_format)。 节拍器配置。详见 [AgoraRhythmPlayerConfig](/zh-CN/api-reference/rtc/macos/class-agorarhythmplayerconfig)。 ### 返回值 [#返回值-1] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 - -22:未找到音效文件。请设置正确的 `sound1` 和 `sound2` 路径。 ### 所属接口类 [#所属接口类-1] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## stopRhythmPlayer [#stoprhythmplayer] 禁用虚拟节拍器。 ```objc - (int)stopRhythmPlayer NS_SWIFT_NAME(stopRhythmPlayer()); ``` :::error[废弃] 自 v4.6.0 版本废弃。 ::: 调用 `startRhythmPlayer` 方法后,你可以调用该方法来禁用虚拟节拍器。 ### 返回值 [#返回值-2] - 0:方法调用成功。 - < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。 ### 所属接口类 [#所属接口类-2] - [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) ## rtcEngine\:didRhythmPlayerStateChanged\:reason: [#rtcenginedidrhythmplayerstatechangedreason] 当虚拟节拍器状态发生变化时触发的回调。 ```objc - (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine didRhythmPlayerStateChanged:(AgoraRhythmPlayerState)state reason:(AgoraRhythmPlayerReason)reason NS_SWIFT_NAME(rtcEngine(_:didRhythmPlayerStateChanged:reason:)); ``` :::error[废弃] 自 v4.6.0 版本废弃。 ::: 当虚拟节拍器状态发生变化时,SDK 会触发该回调以报告当前虚拟节拍器的状态。该回调指示本地音频流的状态,并帮助你在音频异常发生时排查问题。 ### 触发时机 [#触发时机] 该回调在虚拟节拍器状态发生变化时被触发。 ### 参数 [#参数-2] 当前使用的 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 实例。 当前虚拟节拍器的状态,详见 [AgoraRhythmPlayerState](/zh-CN/api-reference/rtc/macos/enum-rhythmplayerstatetype)。 与虚拟节拍器错误相关的错误码和错误信息,详见 [AgoraRhythmPlayerReason](/zh-CN/api-reference/rtc/macos/enum-rhythmplayerreason)。 ### 所属接口类 [#所属接口类-3] - [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)