需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

音乐文件播放

  • Android

更新时间不可用

adjustAudioMixingPlayoutVolume

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

Java
public abstract int adjustAudioMixingPlayoutVolume(int volume);

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

调用时机

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

参数

参数名描述
volume

本地播放的混音音量，取值范围为 0 到 100。（默认值为 100）

  • 0：静音。
  • 100：原始音量。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

adjustAudioMixingPublishVolume

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

Java
public abstract int adjustAudioMixingPublishVolume(int volume);

该方法用于调节发送给其他用户的混音音量。

调用时机

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

参数

参数名描述
volume

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

adjustAudioMixingVolume

调节混音时的音量。

Java
public abstract int adjustAudioMixingVolume(int volume);

该方法用于在本地客户端和远端客户端上调节混音音量。

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

调用时机

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

参数

参数名描述
volume

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

getAudioMixingCurrentPosition

获取当前混音的播放位置（毫秒）。

Java
public abstract int getAudioMixingCurrentPosition();

注：

返回值

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

所属接口类

getAudioMixingDuration

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

Java
public abstract int getAudioMixingDuration();

调用时机

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

返回值

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

所属接口类

getAudioMixingPlayoutVolume

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

Java
public abstract int getAudioMixingPlayoutVolume();

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

调用时机

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

返回值

  • 方法调用成功，返回混音音量，取值范围为 [0, 100]。
  • 方法调用失败，返回小于 0 的错误码。

所属接口类

getAudioMixingPublishVolume

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

Java
public abstract int getAudioMixingPublishVolume();

该方法有助于排查音频音量相关的问题。

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

返回值

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

所属接口类

getAudioTrackCount

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

Java
public abstract int getAudioTrackCount();

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

返回值

  • 方法调用成功，返回音轨的索引。
  • < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

pauseAudioMixing

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

Java
public abstract int pauseAudioMixing();

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

调用时机

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

返回值

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

所属接口类

resumeAudioMixing

恢复播放和混音的音乐文件。

Java
public abstract int resumeAudioMixing();

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

调用时机

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

返回值

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

所属接口类

selectAudioTrack

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

Java
public abstract int selectAudioTrack(int audioIndex);

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

注：

参数

参数名描述
audioIndex

你想要指定的音轨索引。该值应大于 0 且小于 getAudioTrackCount 返回的值。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

selectMultiAudioTrack

选择要在本地设备播放和发布到频道的音轨。

Java
int selectMultiAudioTrack(int playoutTrackIndex, int publishTrackIndex);

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

适用场景

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

参数

参数名描述
playoutTrackIndex

用于本地播放的音轨索引。你可以通过 getStreamInfo 获取该索引。

publishTrackIndex

要发布到频道中的音轨索引。你可以通过 getStreamInfo 获取该索引。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setAudioMixingDualMonoMode

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

Java
public abstract int setAudioMixingDualMonoMode(Constants.AudioMixingDualMonoMode mode);

你可以根据需要将音频文件的声道模式设置为原始模式、左声道模式、右声道模式或混合声道模式。例如，在 KTV 场景中，音乐文件的左声道存储伴奏，右声道存储原唱人声。你可以根据实际需求进行设置：

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

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

适用场景

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

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

调用时机

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

参数

参数名描述
mode

声道模式。详见 AudioMixingDualMonoMode。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setAudioMixingPitch

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

Java
public abstract int setAudioMixingPitch(int pitch);

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

调用时机

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

参数

参数名描述
pitch

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setAudioMixingPlaybackSpeed

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

Java
public abstract int setAudioMixingPlaybackSpeed(int speed);

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

参数

参数名描述
speed

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

  • 50：原始速度的一半。
  • 100：原始速度。
  • 400：原始速度的 4 倍。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

setAudioMixingPosition

设置混音的播放位置。

Java
public abstract int setAudioMixingPosition(int pos);

调用时机

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

参数

参数名描述
pos

播放位置，单位为毫秒。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

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

所属接口类

startAudioMixing [1/2]

开始播放音乐文件。

Java
public abstract int startAudioMixing(String filePath, boolean loopback, int cycle);

废弃

该方法已废弃。请改用 startAudioMixing [2/2]。

该方法支持播放以 content:// 开头的 URI 文件。支持的音频文件格式详见声网 RTC SDK 支持的音频文件格式。如果本地音乐文件不存在、SDK 不支持该文件格式，或无法访问音乐文件的 URL，SDK 会上报 AUDIO_MIXING_REASON_CAN_NOT_OPEN。

注：

  • 如果调用该方法播放短音效文件，可能会播放失败。建议使用 playEffect 播放此类文件。

  • 如果需要多次调用该方法，确保每次调用的时间间隔大于 500 毫秒。

  • 在 Android 平台上，有以下注意事项：

    • 使用该方法时，需确保 Android 设备版本为 v4.2 或更高，API 版本为 v16 或更高。
    • 如果需要播放在线音乐文件，不建议使用重定向的 URL 地址。部分 Android 设备可能无法打开重定向的 URL。
    • 如果在模拟器上调用该方法，需确保音乐文件位于 /sdcard/ 目录下，且格式为 MP3。

调用时机

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

相关回调

成功调用该方法会触发 onAudioMixingStateChanged（AUDIO_MIXING_STATE_PLAYING）回调。当音频混音文件播放结束时，SDK 会在本地客户端触发 onAudioMixingStateChanged（AUDIO_MIXING_STATE_STOPPED）回调。

参数

参数名描述
filePath

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

文件路径。支持以下类型：

  • 以 content:// 开头的 URI 地址。
  • 以 /assets/ 开头的路径。
  • URL。
  • 本地文件的绝对路径，需精确到文件名及扩展名。

支持的音频格式包括 MP3、AAC、M4A、MP4、WAV 和 3GP。

loopback

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

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

音乐文件的播放次数：

  • > 0：播放指定次数，例如 1 表示播放 1 次。
  • -1：无限循环播放。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。

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

    • -1：发生通用错误（无明确原因）。

    • -2：参数无效。

    • -3：SDK 未就绪：

      • 音频模块未启用。
      • 程序未完成。
      • RtcEngine 初始化失败。请重新初始化 RtcEngine。

所属接口类

startAudioMixing [2/2]

开始播放音乐文件。

Java
public abstract int startAudioMixing(String filePath, boolean loopback, int cycle, int startPos);

该方法支持播放以 content:// 开头的 URI 文件。如果本地音乐文件不存在、SDK 不支持该文件格式，或无法访问音乐文件的 URL，SDK 会返回 AUDIO_MIXING_REASON_CAN_NOT_OPEN。

注：

  • 如果你调用该方法播放短音效文件，可能会播放失败。声网建议使用 playEffect 方法播放此类文件。

  • 如果你需要多次调用该方法，请确保每次调用之间的时间间隔大于 500 毫秒。

  • 在 Android 平台上，请注意以下事项：

    • 设备需为 Android v4.2 或更高版本，且 API 版本为 v16 或更高。
    • 如果播放在线音乐文件，声网不建议使用重定向的 URL 地址，部分 Android 设备可能无法打开此类地址。
    • 如果在模拟器上调用该方法，请确保音乐文件位于 /sdcard/ 目录下，且格式为 MP3。

调用时机

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

相关回调

成功调用该方法会触发 onAudioMixingStateChanged（AUDIO_MIXING_STATE_PLAYING）回调。当音频混音文件播放结束时，SDK 会在本地触发 onAudioMixingStateChanged（AUDIO_MIXING_STATE_STOPPED）回调。

参数

参数名描述
filePath

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

loopback

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

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

音乐文件的播放次数：

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

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 0：方法调用成功。

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

    • -1：发生通用错误（无明确原因）。

    • -2：参数无效。

    • -3：SDK 未就绪：

      • 音频模块未启用。
      • 程序未完成。
      • RtcEngine 初始化失败，请重新初始化 RtcEngine。

所属接口类

stopAudioMixing

停止播放音乐文件。

Java
public abstract int stopAudioMixing();

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

调用时机

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

返回值

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

所属接口类

onAudioMixingFinished

本地音乐文件播放结束回调。

Java
public void onAudioMixingFinished()

废弃

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

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

触发时机

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

所属接口类

onAudioMixingPositionChanged

音乐文件播放进度回调。

Java
public void onAudioMixingPositionChanged(long position)

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

触发时机

该回调在调用 startAudioMixing 播放音乐文件后，每两秒触发一次。

参数

参数名描述
position

播放进度，单位为毫秒。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onAudioMixingStateChanged

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

Java
public void onAudioMixingStateChanged(int state, int reason)

该回调报告当前音乐文件的播放状态和错误码。

触发时机

该回调在音乐文件播放状态发生变化时被触发。

参数

参数名描述
state

音乐文件的播放状态：

  • AUDIO_MIXING_STATE_PLAYING (710)：音乐文件正在播放。
  • AUDIO_MIXING_STATE_PAUSED (711)：音乐文件暂停播放。
  • AUDIO_MIXING_STATE_STOPPED (713)：音乐文件停止播放。
  • AUDIO_MIXING_STATE_FAILED (714)：播放音乐文件时出现异常，SDK 会通过 reason 参数返回具体原因。
reason

错误码：

  • AUDIO_MIXING_REASON_OK (0)：没有错误。
  • AUDIO_MIXING_REASON_CAN_NOT_OPEN (701)：SDK 无法打开音乐文件。
  • AUDIO_MIXING_REASON_TOO_FREQUENT_CALL (702)：SDK 打开音乐文件过于频繁。
  • AUDIO_MIXING_REASON_INTERRUPTED_EOF (703)：音乐文件播放被中断。
  • AUDIO_MIXING_REASON_ONE_LOOP_COMPLETED (721)：音乐文件完成一次循环播放。
  • AUDIO_MIXING_REASON_ALL_LOOPS_COMPLETED (723)：音乐文件完成所有循环播放。
  • AUDIO_MIXING_REASON_STOPPED_BY_USER (724)：通过调用 stopAudioMixing 停止音乐文件播放。
表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利