# 虚拟节拍器 (/zh-CN/api-reference/rtc/flutter/play/rhythmplayer)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## configRhythmPlayer [#configrhythmplayer]
配置虚拟节拍器。
```dart
Future configRhythmPlayer(AgoraRhythmPlayerConfig config);
```
:::error[废弃]
自 v6.6.2 版本废弃。
:::
- 调用 [startRhythmPlayer](/zh-CN/api-reference/rtc/flutter/play/rhythmplayer#api_irtcengine_startrhythmplayer) 后,你可以调用该方法重新配置虚拟节拍器。
- 开启虚拟节拍器后,SDK 会从头开始播放指定的音频文件,并根据你在 [AgoraRhythmPlayerConfig](/zh-CN/api-reference/rtc/flutter/class-agorarhythmplayerconfig) 中设置的 `beatsPerMinute` 控制每个文件的播放时长。例如,将 `beatsPerMinute` 设为 `60`,则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长,则 SDK 只播放节拍时长部分的音频。
- 虚拟节拍器的声音默认不会发布至远端,如果你希望远端用户听到虚拟节拍器的声音,你可以在调用该方法后,将 [ChannelMediaOptions](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 中的 `publishRhythmPlayerTrack` 设为 true。
### 调用时机 [#调用时机]
加入频道前后均可调用。
### 相关回调 [#相关回调]
成功调用该方法后,SDK 会在本地触发 [onRhythmPlayerStateChanged](/zh-CN/api-reference/rtc/flutter/play/rhythmplayer#callback_irtcengineeventhandler_onrhythmplayerstatechanged) 回调,报告虚拟节拍器的状态。
### 参数 [#参数]
节拍器配置。详见 [AgoraRhythmPlayerConfig](/zh-CN/api-reference/rtc/flutter/class-agorarhythmplayerconfig)。
### 返回值 [#返回值]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类]
- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)
## startRhythmPlayer [#startrhythmplayer]
开启虚拟节拍器。
```dart
Future startRhythmPlayer(
{required String sound1,
required String sound2,
required AgoraRhythmPlayerConfig config});
```
:::error[废弃]
自 v6.6.2 版本废弃。
:::
- 开启虚拟节拍器后,SDK 会从头开始播放指定的音频文件,并根据你在 [AgoraRhythmPlayerConfig](/zh-CN/api-reference/rtc/flutter/class-agorarhythmplayerconfig) 中设置的 `beatsPerMinute` 控制每个文件的播放时长。例如,将 `beatsPerMinute` 设为 `60`,则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长,则 SDK 只播放节拍时长部分的音频。
- 虚拟节拍器的声音默认不会发布至远端,如果你希望远端用户听到虚拟节拍器的声音,你可以在调用该方法后,将 [ChannelMediaOptions](/zh-CN/api-reference/rtc/flutter/class-channelmediaoptions) 中的 `publishRhythmPlayerTrack` 设为 true。
### 适用场景 [#适用场景]
在音乐教学、体育教学等场景中,老师通常需要使用节拍器,让学生跟着正确的节拍练习。节拍由强拍和弱拍组成,每小节的第一拍称为强拍,其余称为弱拍。
### 调用时机 [#调用时机-1]
加入频道前后均可调用。
### 相关回调 [#相关回调-1]
成功调用该方法后,SDK 会在本地触发 [onRhythmPlayerStateChanged](/zh-CN/api-reference/rtc/flutter/play/rhythmplayer#callback_irtcengineeventhandler_onrhythmplayerstatechanged) 回调,报告虚拟节拍器的状态。
### 参数 [#参数-1]
强拍文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如 `C:\music\audio.mp4`。支持的音频文件格式见 [RTC SDK 支持播放哪些格式的音频文件](/zh-CN/reference/faq/product/audio_format)。
弱拍文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如 `C:\music\audio.mp4`。支持的音频文件格式见 [RTC SDK 支持播放哪些格式的音频文件](/zh-CN/reference/faq/product/audio_format)。
节拍器配置。详见 [AgoraRhythmPlayerConfig](/zh-CN/api-reference/rtc/flutter/class-agorarhythmplayerconfig)。
### 返回值 [#返回值-1]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)
## stopRhythmPlayer [#stoprhythmplayer]
关闭虚拟节拍器。
```dart
Future stopRhythmPlayer();
```
:::error[废弃]
自 v6.6.2 版本废弃。
:::
调用 [startRhythmPlayer](/zh-CN/api-reference/rtc/flutter/play/rhythmplayer#api_irtcengine_startrhythmplayer) 后,你可以调用该方法关闭虚拟节拍器。
:::note
注: 该方法仅适用于 Android 和 iOS。
:::
### 返回值 [#返回值-2]
方法成功调用时,无返回值;方法调用失败时,会抛出 [AgoraRtcException](/zh-CN/api-reference/rtc/flutter/class-agorartcexception) 异常,你需要捕获异常并进行处理。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-2]
- [RtcEngine](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengine)
## onRhythmPlayerStateChanged [#onrhythmplayerstatechanged]
虚拟节拍器状态发生改变回调。
```dart
final void Function(RhythmPlayerStateType state, RhythmPlayerReason reason)?
onRhythmPlayerStateChanged;
```
:::error[废弃]
自 v6.6.2 版本废弃。
:::
虚拟节拍器状态发生改变时,SDK 会触发该回调报告当前的虚拟节拍器状态。在虚拟节拍器出现故障时,该回调可以帮助你了解当前虚拟节拍的状态以及出现故障的原因,方便你排查问题。
:::note
注: 该回调仅适用于 Android 和 iOS。
:::
### 参数 [#参数-2]
当前的虚拟节拍器状态,详见 [RhythmPlayerStateType](/zh-CN/api-reference/rtc/flutter/enum-rhythmplayerstatetype)。
虚拟节拍器发生错误的错误码和错误信息,详见 [RhythmPlayerReason](/zh-CN/api-reference/rtc/flutter/enum-rhythmplayerreason)。
### 所属接口类 [#所属接口类-3]
- [RtcEngineEventHandler](/zh-CN/api-reference/rtc/flutter/rtc-interface-class#class_irtcengineeventhandler)