音乐文件播放

adjustAudioMixingPlayoutVolume

调节本地播放的混音音量。

C++
virtual int adjustAudioMixingPlayoutVolume(int volume) = 0;

调用时机

你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged（AUDIO_MIXING_STATE_PLAYING）回调后调用该方法。

参数

volume: 本地播放的混音音量，取值范围为 0 到 100。（默认）为 100，表示原始音量。

返回值

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

所属接口类

IRtcEngine

adjustAudioMixingPublishVolume

调节用于发布的混音音量。

C++
virtual int adjustAudioMixingPublishVolume(int volume) = 0;

调用时机

请在调用 startAudioMixing 并收到 onAudioMixingStateChanged（AUDIO_MIXING_STATE_PLAYING）回调后调用该方法。

参数

volume: 用于发布的混音音量。取值范围为 0 到 100，默认值为 100，表示原始音量。

返回值

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

所属接口类

IRtcEngine

adjustAudioMixingVolume

调节本地和远端的混音音量。

C++
virtual int adjustAudioMixingVolume(int volume) = 0;

信息

adjustAudioMixingVolume 方法不会影响通过 playEffect 方法设置的音频文件的音量。

调用时机

请在调用 startAudioMixing 方法之后调用该方法。

参数

volume: 混音音量。取值范围为 0 到 100。（默认）100 表示原始音量。

返回值

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

所属接口类

IRtcEngine

getAudioMixingCurrentPosition

获取当前混音的播放进度（毫秒）。

C++
virtual int getAudioMixingCurrentPosition() = 0;

信息

你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged（AUDIO_MIXING_STATE_PLAYING）回调后调用此方法。
如果需要多次调用 getAudioMixingCurrentPosition，请确保两次调用之间的时间间隔大于 500 毫秒。

返回值

≥ 0：方法调用成功，返回当前混音的播放进度（毫秒）。返回 0 表示当前音乐文件尚未开始播放。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

getAudioMixingDuration

获取混音文件的总时长（毫秒）。

C++
virtual int getAudioMixingDuration() = 0;

调用时机

请在调用 startAudioMixing 并收到 onAudioMixingStateChanged（AUDIO_MIXING_STATE_PLAYING）回调后调用该方法。

返回值

方法调用成功，返回混音文件的总时长（毫秒）。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

getAudioMixingPlayoutVolume

获取本地播放的混音音量。

C++
virtual int getAudioMixingPlayoutVolume() = 0;

你可以调用该方法获取混音音频文件的本地播放音量，有助于排查与音量相关的问题。

调用时机

请在调用 startAudioMixing 并收到 onAudioMixingStateChanged（AUDIO_MIXING_STATE_PLAYING）回调后调用此方法。

返回值

方法调用成功，返回混音音量，取值范围为 [0, 100]。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

getAudioMixingPublishVolume

获取用于发布的混音音量。

C++
virtual int getAudioMixingPublishVolume() = 0;

信息

你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged（AUDIO_MIXING_STATE_PLAYING）回调后调用该方法。

返回值

0：方法调用成功，返回混音音量，取值范围为 [0,100]。
< 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

IRtcEngine

getAudioTrackCount

获取当前音乐文件的音轨索引。

C++
virtual int getAudioTrackCount() = 0;

信息

你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged（AUDIO_MIXING_STATE_PLAYING）回调后调用此方法。

返回值

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

所属接口类

IRtcEngine

pauseAudioMixing

暂停播放和混音的音乐文件。

C++
virtual int pauseAudioMixing() = 0;

调用 startAudioMixing 播放音乐文件后，可以调用该方法暂停播放。若需停止播放，请调用 stopAudioMixing。

调用时机

请在加入频道后调用该方法。

返回值

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

所属接口类

IRtcEngine

resumeAudioMixing

恢复播放并混音音乐文件。

C++
virtual int resumeAudioMixing() = 0;

调用 pauseAudioMixing 暂停播放后，可以调用 resumeAudioMixing 恢复播放。

调用时机

请在加入频道后调用该方法。

返回值

0: 方法调用成功。
< 0: 方法调用失败。

所属接口类

IRtcEngine

selectAudioTrack [1/2]

选择播放过程中使用的音轨。

C++
virtual int selectAudioTrack(int index) = 0;

获取音频文件的音轨索引后，可以调用该方法指定任意音轨进行播放。例如，如果一个多音轨文件的不同音轨存储了不同语言的歌曲，可以调用该方法设置播放语言。

信息

支持的音频文件格式请参见音频文件扩展格式。
你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged（AUDIO_MIXING_STATE_PLAYING）回调后调用该方法。

参数

index: 指定的音轨索引。该值应大于 0 且小于 getAudioTrackCount 返回的值。

返回值

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

所属接口类

IRtcEngine

selectMultiAudioTrack

选择用于本地播放和发布到频道的音轨。

C++
virtual int selectMultiAudioTrack(int playoutTrackIndex, int publishTrackIndex) = 0;

调用该方法前，需要使用 openWithMediaSource 打开媒体文件，并在 MediaSource 中将 enableMultiAudioTrack 设置为 true。

适用场景

该方法适用于例如 KTV 场景：主持人可以选择在本地播放原唱音轨，同时将伴奏音轨发布到频道。

参数

playoutTrackIndex: 用于本地播放的音轨索引。可通过 getStreamInfo 获取。
publishTrackIndex: 要发布到频道的音轨索引。可通过 getStreamInfo 获取。

返回值

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

所属接口类

IMediaPlayer

setAudioMixingDualMonoMode

设置当前音频文件的声道模式。

C++
virtual int setAudioMixingDualMonoMode(media::AUDIO_MIXING_DUAL_MONO_MODE mode) = 0;

在立体声音乐文件中，左右声道可以存储不同的音频数据。你可以根据需要将声道模式设置为原始模式、左声道模式、右声道模式或混合声道模式。

信息

该方法仅适用于立体声音频文件。

适用场景

在 KTV 场景中，音乐文件的左声道存储伴奏，右声道存储原唱人声。你可以根据实际需求进行设置：

如果你只想听到伴奏，调用该方法将声道模式设置为左声道模式。
如果你需要同时听到伴奏和原唱人声，调用该方法将声道模式设置为混合模式。

调用时机

在调用 startAudioMixing 并收到 onAudioMixingStateChanged（AUDIO_MIXING_STATE_PLAYING）回调后调用该方法。

参数

mode: 声道模式。详见 AUDIO_MIXING_DUAL_MONO_MODE。

返回值

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

所属接口类

IRtcEngine

setAudioMixingPitch

设置本地音乐文件的音调。

C++
virtual int setAudioMixingPitch(int pitch) = 0;

调用该方法可在本地音乐文件与本地人声混音时，单独调整本地音乐文件的音调。

调用时机

你需要在调用 startAudioMixing 并收到 onAudioMixingStateChanged（AUDIO_MIXING_STATE_PLAYING）回调后调用该方法。

参数

pitch: 按半音音阶设置本地音乐文件的音调。默认值为 0，表示保持原始音调。取值范围为 -12 到 12，相邻两个值之间的音调差为一个半音。该参数的绝对值越大，音调变化越明显。

返回值

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

所属接口类

IRtcEngine

setAudioMixingPlaybackSpeed

设置当前音频文件的播放速度。

C++
virtual int setAudioMixingPlaybackSpeed(int speed) = 0;

请确保在调用 startAudioMixing 并收到 onAudioMixingStateChanged 回调报告状态为 AUDIO_MIXING_STATE_PLAYING 后再调用此方法。

参数

speed

播放速度。建议设置为 50 到 400 之间的值，定义如下：

50：原始速度的一半。
100：原始速度。
400：原始速度的 4 倍。

返回值

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

所属接口类

IRtcEngine

setAudioMixingPosition

设置混音文件的播放起始位置。

C++
virtual int setAudioMixingPosition(int pos /*in ms*/) = 0;

调用该方法可将音乐文件的播放位置设置为指定的起始位置，默认从头开始播放。

调用时机

请在调用 startAudioMixing 并收到 onAudioMixingStateChanged（AUDIO_MIXING_STATE_PLAYING）回调后调用此方法。

参数

pos: 播放位置，单位为毫秒。

返回值

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

所属接口类

IRtcEngine

startAudioMixing [1/2]

开始播放音乐文件。

C++
virtual int startAudioMixing(const char* filePath, bool loopback, int cycle) = 0;

废弃

该方法已废弃，请改用 startAudioMixing(const char* filePath, bool loopback, int cycle, int startPos)。

如果本地音乐文件不存在、SDK 不支持该文件格式，或无法访问音乐文件的 URL，SDK 会返回 AUDIO_MIXING_REASON_CAN_NOT_OPEN。

信息

如果你调用该方法播放短音效文件，可能会遇到播放失败的情况。建议使用 playEffect 播放此类文件。
如果你需要多次调用该方法，确保每次调用之间的时间间隔大于 500 毫秒。
在 Android 上，有以下注意事项：
- 使用该方法前，请确保 Android 设备版本为 v4.2 或更高，API 版本为 v16 或更高。
- 如果你需要播放在线音乐文件，不建议使用重定向的 URL 地址。部分 Android 设备可能无法打开重定向的 URL 地址。
- 如果你在模拟器上调用该方法，请确保音乐文件位于 /sdcard/ 目录下，且格式为 MP3。

调用时机

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

参数

filePath

文件路径。支持 URL 和本地文件的绝对路径，路径需精确到文件名及扩展名。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV 和 3GP。

信息

如果你已通过调用 preloadEffect 将音效文件预加载到内存中，请确保该参数的值与 preloadEffect 中的 filePath 参数一致。

loopback

是否仅在本地客户端播放音乐文件：

true：仅在本地播放，只有本地用户能听到音乐。
false：将音乐发布到远端，远端和本地用户都能听到音乐。

cycle

音乐文件的播放次数：

>0：播放指定次数，例如 1 表示播放 1 次。
-1：无限循环播放。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。
- -1：发生通用错误（无明确原因）。
- -2：参数无效。
- -3：SDK 未就绪：
  - 音频模块未启用。
  - 程序未完成。
  - IRtcEngine 初始化失败。请重新初始化 IRtcEngine。

所属接口类

IRtcEngine

startAudioMixing [2/2]

开始播放音乐文件。

C++
virtual int startAudioMixing(const char* filePath, bool loopback, int cycle, int startPos) = 0;

如果本地音乐文件不存在、SDK 不支持该文件格式，或无法访问音乐文件的 URL，SDK 会返回 AUDIO_MIXING_REASON_CAN_NOT_OPEN。

信息

如果调用该方法播放短音效文件，可能会播放失败。声网建议使用 playEffect 播放此类文件。
如果需要多次调用该方法，确保两次调用之间的时间间隔大于 500 毫秒。
在 Android 平台上，有以下注意事项：
- 使用该方法时，需确保 Android 设备版本为 v4.2 或更高，API 版本为 v16 或更高。
- 如果需要播放在线音乐文件，声网不建议使用重定向的 URL 地址。部分 Android 设备可能无法打开重定向的 URL。
- 如果在模拟器上调用该方法，需确保音乐文件位于 /sdcard/ 目录下，且格式为 MP3。

调用时机

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

参数

filePath

文件路径：

Android：路径需精确到文件名和后缀名。支持 URL 地址、绝对路径或以 /assets/ 开头的路径。使用绝对路径访问本地文件可能会遇到权限问题，建议使用 URI 地址，例如：content://com.android.providers.media.documents/document/audio%3A14441。
Windows：音效文件的绝对路径或 URL 地址（包括文件名后缀），例如：C:\music\audio.mp4。

loopback

是否仅在本地客户端播放音乐文件：

true：仅本地播放，只有本地用户能听到音乐。
false：将音乐发布到远端，远端用户也能听到音乐。

cycle

音乐文件的播放次数：

>0：播放指定次数，例如 1 表示播放 1 次。
-1：无限循环播放。

startPos

音乐文件的播放起始位置（单位：毫秒）。

返回值

0：方法调用成功。
< 0：方法调用失败。详见错误码了解详情和解决建议。
- -1：发生通用错误（无明确原因）。
- -2：参数无效。
- -3：SDK 未就绪：
  - 音频模块被禁用。
  - 程序未完成。
  - IRtcEngine 初始化失败。请重新初始化 IRtcEngine。

所属接口类

IRtcEngine

stopAudioMixing

停止播放音乐文件。

C++
virtual int stopAudioMixing() = 0;

调用 startAudioMixing 播放音乐文件后，可以调用该方法停止播放。如果只需要暂停播放，请调用 pauseAudioMixing。

调用时机

请在加入频道后调用该方法。

返回值

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

所属接口类

IRtcEngine

onAudioMixingFinished

本地音乐文件播放结束时触发的回调。

C++
virtual void onAudioMixingFinished() __deprecated {}

废弃

该方法已废弃，请改用 onAudioMixingStateChanged。

调用 startAudioMixing 播放本地音乐文件后，当播放结束时会触发该回调。如果调用 startAudioMixing 失败，会返回错误码 WARN_AUDIO_MIXING_OPEN_ERROR。

触发时机

调用 startAudioMixing 播放本地音乐文件后，当播放结束时触发。

所属接口类

IRtcEngineEventHandler

onAudioMixingPositionChanged

报告音乐文件播放进度的回调。

C++
virtual void onAudioMixingPositionChanged(int64_t position) {}

调用 startAudioMixing 播放音乐文件后，SDK 每两秒触发一次该回调，报告音乐文件的播放进度。

参数

position: 播放进度，单位为毫秒。

返回值

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

所属接口类

IRtcEngineEventHandler

onAudioMixingStateChanged

音乐文件播放状态变化回调。

C++
virtual void onAudioMixingStateChanged(AUDIO_MIXING_STATE_TYPE state, AUDIO_MIXING_REASON_TYPE reason)

该回调在音乐文件的播放状态发生变化时触发，并报告当前的播放状态和错误码。

参数

state: 音乐文件的播放状态。详见 AUDIO_MIXING_STATE_TYPE。
reason: 播放状态变化的原因或错误码。详见 AUDIO_MIXING_REASON_TYPE。

所属接口类

IRtcEngineEventHandler

adjustAudioMixingPlayoutVolume

调用时机

参数​

返回值​

adjustAudioMixingPublishVolume

调用时机

参数​

返回值​

adjustAudioMixingVolume

调用时机

参数​

返回值​

getAudioMixingCurrentPosition

返回值​

getAudioMixingDuration

调用时机

返回值​

getAudioMixingPlayoutVolume

调用时机

返回值​

getAudioMixingPublishVolume

返回值​

getAudioTrackCount

返回值​

pauseAudioMixing

调用时机

返回值​

resumeAudioMixing

调用时机

返回值​

selectAudioTrack [1/2]

参数​

返回值​

selectMultiAudioTrack

适用场景

参数​

返回值​

setAudioMixingDualMonoMode

适用场景

调用时机

参数​

返回值​

setAudioMixingPitch

调用时机

参数​

返回值​

setAudioMixingPlaybackSpeed

参数​

返回值​

setAudioMixingPosition

调用时机

参数​

返回值​

startAudioMixing [1/2]

调用时机

相关回调

参数​

返回值​

startAudioMixing [2/2]

调用时机

相关回调

参数​

返回值​

stopAudioMixing

调用时机

返回值​

onAudioMixingFinished

触发时机

onAudioMixingPositionChanged

参数​

返回值​

onAudioMixingStateChanged

参数​

参数

返回值

参数

返回值

参数

返回值

返回值

返回值

返回值

返回值

返回值

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

返回值

参数

返回值

参数