版权音乐
介绍版权音乐的相关方法和回调。
createMusicPlayer
创建音乐播放器。
public abstract IAgoraMusicPlayer createMusicPlayer();
详情
- 自从
- v4.1.0
返回值
- 方法调用成功:返回 IAgoraMusicPlayer 对象。
- 方法调用失败:返回空指针。
destroy
销毁 IAgoraMusicContentCenter 实例。
public static synchronized void destroy() { if (mInstance == null) return; mInstance.release(); mInstance = null; }
详情
- 自从
- v4.1.0
该方法需要在 RtcEngine 的 destroy 方法前调用。
getCaches
获取已缓存的音乐资源信息。
public abstract MusicCacheInfo[] getCaches();
详情
- 自从
- v4.2.0
调用该方法前,你需要预先分配一定大小的内存空间用来存储缓存音乐资源的信息。
当你不再需要使用已缓存的音乐资源时,你需要及时释放内存以防止内存泄漏。
返回值
- 方法调用成功时,返回包含 MusicCacheInfo 对象的数组。
- 方法调用失败时,返回 NULL。
getInternalSongCode
创建音乐资源的副歌片段编号。
public abstract long getInternalSongCode(long songCode, String jsonOption);
详情
- 自从
- v4.2.2
适用场景
当你需要播放某一音乐资源的副歌片段前,你需要调用此方法,通过 jsonOption 参数和该音乐资源的 songCode 来为该音乐资源的副歌片段创建一个编号,作为该资源的唯一标识。当你获取到该片段的编号后,在你调用相应方法打开、预加载、移除该资源时,将该内部歌曲编号传入 songCode 参数。
参数
- songCode
- 音乐资源编号,用于标识音乐资源。你可以通过调用 getMusicCollectionByMusicChartId [1/2] 或 searchMusic [1/2] 方法来获取音乐资源,并通过由此触发的 onMusicCollectionResult 回调获取音乐资源的编号(songCode)。
- jsonOption
- 扩展 JSON 字段,默认为 NULL。目前支持传入下列值:
Key 值 Value 值 示例 sceneType 场景类型: - 1:直播场景:K 歌及背景音乐播放。
- 2:直播场景:背景音乐播放。
- 3:(默认)语聊场景:K 歌。
- 4:语聊场景:背景音乐播放。
- 5:VR 场景:K 歌及背景音乐播放。
注: 声网会根据你在 sceneType 传入的应用场景进行收费。不同的应用场景对应不同的费率,你可以参考 计费说明 查看详细的计费。如果需要切换到不同场景,需要重新调用此方法并传入 sceneType 的值。{"sceneType":1} highPart 副歌片段的索引。你可以从 onMusicCollectionResult 回调中获取副歌片段的索引然后传值。索引序号从 0 开始。 {"format": {"highpart": 0}}
返回值
- 方法调用成功,返回创建的音乐资源内部编号。
- < 0: 方法调用失败。
getPlaySrc [2/2]
initialize
public abstract int initialize(MusicContentCenterConfiguration configuration);
详情
- 自从
- v4.1.0
在调用 IAgoraMusicContentCenter 类下的其他方法前,你需要先调用该方法初始化 IAgoraMusicContentCenter。
参数
- configuration
- IAgoraMusicContentCenter 的设置,详见 MusicContentCenterConfiguration。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getLyric
获取音乐资源的歌词下载地址。
public abstract String getLyric(long songCode, int lyricType);
详情
- 自从
- v4.1.0
成功调用该方法后,SDK 会触发 onLyricResult 回调报告歌词的下载地址。
参数
- songCode
- 音乐资源的编号,用于标识音乐资源。
- LyricType
- 歌词类型:
- 0:xml 格式。
- 1:lrc 格式。
返回值
一个 requestId,为本次请求的唯一标识。
getMusicCharts
获取全部音乐榜单。
public abstract String getMusicCharts();
详情
- 自从
- v4.1.0
当你调用该方法后,SDK 会触发 onMusicChartsResult 回调报告音乐榜单的详细信息。
返回值
一个 requestId,为本次请求的唯一标识。
getMusicCollectionByMusicChartId [1/2]
通过音乐榜单的 ID 获取指定榜单的音乐资源列表。
public String getMusicCollectionByMusicChartId(int musicChartId, int page, int pageSize) { return getMusicCollectionByMusicChartId(musicChartId, page, pageSize, null); }
详情
- 自从
- v4.1.0
成功调用该方法后,SDK 会触发 onMusicCollectionResult 回调报告榜单中音乐资源列表的详细信息。
参数
- musicChartId
- 音乐榜单的 ID,可以通过 onMusicChartsResult 回调获取。你也可以通过 RESTful API 来获取曲库所有歌曲列表或获取增量歌曲列表。
- page
- 当前页面编号,默认从 1 开始。
- pageSize
- 当前音乐资源列表的总页面数量,最大值为 50。
返回值
一个 requestId,为本次请求的唯一标识。
getMusicCollectionByMusicChartId [2/2]
通过音乐榜单的 ID 获取指定榜单的音乐资源列表。
public abstract String getMusicCollectionByMusicChartId( int musicChartId, int page, int pageSize, String jsonOption);
详情
- 自从
- v4.1.0
成功调用该方法后,SDK 会触发 onMusicCollectionResult 回调报告榜单中音乐资源列表的详细信息。
参数
- musicChartId
- 音乐榜单的 ID,可以通过 onMusicChartsResult 回调获取。你也可以通过 RESTful API 来获取曲库所有歌曲列表或获取增量歌曲列表。
- page
- 当前页面编号,默认从 1 开始。
- pageSize
- 当前音乐资源列表的总页面数量,最大值为 50。
- jsonOption
- 扩展 JSON 字段,默认为 NULL。你可以通过该字段来筛选出你需要的音乐资源,目前支持筛选可打分的音乐资源及音乐资源的副歌片段:
Key 值 Value 值 示例 pitchType 是否支持打分: - 1:支持打分的音乐资源。
- 2:不支持打分的音乐资源。
{"pitchType":1} needHighPart 是否需要副歌片段资源: true
:需要副歌片段资源。false
:不需要副歌片段资源。
{"needHighPart":true}
返回值
一个 requestId,为本次请求的唯一标识。
getSongSimpleInfo
获取某一音乐资源的详细信息。
public abstract String getSongSimpleInfo(long songCode);
详情
- 自从
- v4.2.2
在调用该方法前,你需要先获取到对应的音乐资源的编号。你可以通过调用 getMusicCollectionByMusicChartId [1/2] 或 searchMusic [1/2] 方法来获取音乐资源,并通过由此触发的 onMusicCollectionResult 回调获取音乐资源的编号(songCode)。
当你调用该方法后,SDK 会触发 onSongSimpleInfoResult 回调报告音乐资源的详细信息。
参数
- songCode
- 音乐资源的编号,用于标识音乐资源。
返回值
一个 requestId,为本次请求的唯一标识。
isPreloaded
检测音乐资源是否已被预加载。
public abstract int isPreloaded(long songCode);
详情
- 自从
- v4.1.0
该方法为同步调用。如需预加载新的音乐资源,可调用 preload [1/2]。
参数
- songCode
- 音乐资源的编号,用于标识一个音乐资源。
返回值
- 0: 方法调用成功,该音乐资源已被预加载。
- < 0: 方法调用失败。
open
通过音乐资源编号打开音乐资源。
int open(long songCode, long startPos);
详情
- 自从
- v4.1.0
在调用此方法之前,请确保需要播放的音乐资源已加载完成。你可以调用 isPreloaded 方法来检测音乐资源是否已被预加载,或通过 onPreLoadEvent 回调得知。
如需播放媒体文件,请在收到 onPlayerStateChanged 回调报告播放状态为 PLAYER_STATE_OPEN_COMPLETED 后再调用 play 方法播放媒体文件。
参数
- songCode
- 音乐资源的编号,用于标识音乐资源。
- startPos
- 设置起始播放位置(毫秒),默认值为 0。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
open2
通过 URL 打开音乐资源。
@Override int open(String url, long startPos);
详情
- 自从
- v4.2.0
如需播放媒体文件,请在收到 onPlayerStateChanged 回调报告播放状态为 PLAYER_STATE_OPEN_COMPLETED 后再调用 play 方法播放媒体文件。
参数
- url
- 音乐资源的路径,支持本地和在线文件。
- startPos
- 设置起始播放位置(毫秒),默认值为 0。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
preload [1/2]
预加载音乐资源。
public abstract int preload(long songCode, String jsonOption);
详情
- 弃用:
- 该方法已废弃,请改用 preload [2/2]。
你可以调用该方法预先加载需要播放的音乐资源。成功调用该方法后,SDK 会触发 onPreLoadEvent 回调报告预加载音乐资源的事件。
在调用该方法来预加载音乐资源之前,你需要调用 getMusicCollectionByMusicChartId [1/2] 或 searchMusic [1/2] 方法来获取你需要播放的音乐资源,并通过由此触发的 onMusicCollectionResult 回调获取音乐资源的编号(songCode)。
参数
- songCode
- 音乐资源的编号,用于标识音乐资源。
- jsonOption
-
扩展 JSON 字段。
声网会根据你在场景字段(sceneType)传入的应用场景进行收费。不同的应用场景对应不同的费率,你可以参考 计费说明 查看详细的计费。
- 1:直播场景:K 歌及背景音乐播放。
- 2:直播场景:背景音乐播放。
- 3:(默认)语聊场景:K 歌。
- 4:语聊场景:背景音乐播放。
- 5:VR 场景:K 歌及背景音乐播放。
示例:
{"sceneType":1}
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
preload [2/2]
预加载音乐资源。
public abstract String preload(long songCode);
详情
- 自从
- v4.2.2
你可以调用该方法预先加载需要播放的音乐资源。成功调用该方法后,SDK 会触发 onPreLoadEvent 回调报告预加载音乐资源的事件。
在调用该方法来预加载音乐资源之前,你需要调用 getMusicCollectionByMusicChartId [1/2] 或 searchMusic [1/2] 方法来获取你需要播放的音乐资源,并通过由此触发的 onMusicCollectionResult 回调获取音乐资源的编号(songCode)。
参数
- songCode
- 音乐资源的编号,用于标识音乐资源。
返回值
一个 requestId,为本次请求的唯一标识。
removeCache
删除已缓存的音乐资源。
public abstract int removeCache(long songCode);
详情
- 自从
- v4.2.0
参数
- songCode
- 待删除的音乐资源的编号。
返回值
- 0: 方法调用成功,音乐资源已删除。
- < 0: 方法调用失败。
renewToken
更新 Token。
public abstract int renewToken(String token);
详情
- 自从
- v4.1.0
当你用于鉴权的 Token 快要过期或已过期时,你可以调用该方法来传入新生成的 Token。
参数
- token
- 新的 Token。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
release
registerEventHandler
注册音乐内容中心回调事件。
public abstract int registerEventHandler(IMusicContentCenterEventHandler eventHandler);
详情
- 自从
- v4.1.0
参数
- eventHandler
- 待注册的回调事件,详见 IMusicContentCenterEventHandler。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
searchMusic [1/2]
搜索音乐资源。
public String searchMusic(String keyword, int page, int pageSize) { return searchMusic(keyword, page, pageSize, null); }
详情
- 自从
- v4.1.0
成功调用该方法后,SDK 会触发 onMusicCollectionResult 回调报告检索到的音乐资源列表。
参数
- keyword
- 搜索关键词,支持歌曲名、歌手搜索。
- page
- 想要获取的音乐资源列表的目标页编号。
- pageSize
- 每页所展示的音乐资源的最大数量,最大值为 50。
返回值
一个 requestId,为本次请求的唯一标识。
searchMusic [2/2]
搜索音乐资源。
public abstract String searchMusic(String keyword, int page, int pageSize, String jsonOption);
详情
- 自从
- v4.1.0
成功调用该方法后,SDK 会触发 onMusicCollectionResult 回调报告检索到的音乐资源列表。
参数
- keyword
- 搜索关键词,支持歌曲名、歌手搜索。
- page
- 想要获取的音乐资源列表的目标页编号。
- pageSize
- 每页所展示的音乐资源的最大数量,最大值为 50。
- jsonOption
- 扩展 JSON 字段,默认为 NULL。你可以通过该字段来筛选出你需要的音乐资源,目前支持筛选可打分的音乐资源及音乐资源的副歌片段:
Key 值 Value 值 示例 pitchType 是否支持打分: - 1:支持打分的音乐资源。
- 2:不支持打分的音乐资源。
{"pitchType":1} needHighPart 是否需要副歌片段资源: true
:需要副歌片段资源。false
:不需要副歌片段资源。
{"needHighPart":true}
返回值
一个 requestId,为本次请求的唯一标识。
stop
停止播放音乐资源。
@Override int stop();
详情
- 自从
- v4.2.0
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
unregisterEventHandler
取消注册音乐内容中心事件回调。
public abstract int unregisterEventHandler();
详情
- 自从
- v4.1.0
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
onPreLoadEvent
报告预加载音乐资源的事件。
onPreLoadEvent(String requestId, long songCode, int percent, String lyricUrl, int status, int errorCode);
- 自从
- v4.1.0
当你调用 preload [1/2] 方法预加载音乐资源后,SDK 会触发该回调。
参数
- requestId
- 请求 ID。本次请求的唯一标识。
- songCode
- 音乐资源的编号,用于标识一个音乐资源。
- percent
- 音乐资源当前的加载进度,取值范围为 [0,100]。
- lyricUrl
- 歌词下载地址。
- status
-
当前音乐资源的加载状态:
- 0:音乐资源加载完成。
- 1:音乐资源加载失败。
- 2:音乐资源正在加载中。
- errorCode
-
音乐内容中心的请求状态码:
- MUSIC_CONTENT_CENTER_STATUS_OK (0):请求成功。
- MUSIC_CONTENT_CENTER_STATUS_ERR (1):一般错误,无明确归因。
- MUSIC_CONTENT_CENTER_STATUS_ERR_GATEWAY (2):网关异常。可能的原因有:
- 当前使用的 Token 已过期。请重新生成 Token。
- 传入的 Token 无效。请确保你使用的是 RTM Token。
- 网络错误。请检查你的网络。
- MUSIC_CONTENT_CENTER_STATUS_ERR_PERMISSION_AND_RESOURCE (3):权限错误或音乐资源不存在。请确保你的项目已开通声网音乐内容中心权限,请联系技术支持。
- MUSIC_CONTENT_CENTER_STATUS_ERR_INTERNAL_DATA_PARSE (4):内部数据解析错误。请联系技术支持。
- MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_LOADING (5):音乐资源加载时出错。请联系技术支持。
- MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_DECRYPTION (6):音乐资源解密时出错。请联系技术支持。
onLyricResult
歌词下载地址回调。
void onLyricResult(String requestId, long songCode, String lyricUrl, int errorCode);
- 自从
- v4.1.0
当你调用 getLyric 获取指定歌曲的歌词下载地址后,SDK 会触发该回调。
参数
- requestId
- 请求 ID。本次请求的唯一标识。
- songCode
- 音乐资源的编号,用于标识音乐资源。
- lyricUrl
- 歌词的下载地址。
- errorCode
-
音乐内容中心的请求状态码:
- MUSIC_CONTENT_CENTER_STATUS_OK (0):请求成功。
- MUSIC_CONTENT_CENTER_STATUS_ERR (1):一般错误,无明确归因。
- MUSIC_CONTENT_CENTER_STATUS_ERR_GATEWAY (2):网关异常。可能的原因有:
- 当前使用的 Token 已过期。请重新生成 Token。
- 传入的 Token 无效。请确保你使用的是 RTM Token。
- 网络错误。请检查你的网络。
- MUSIC_CONTENT_CENTER_STATUS_ERR_PERMISSION_AND_RESOURCE (3):权限错误或音乐资源不存在。请确保你的项目已开通声网音乐内容中心权限,请联系技术支持。
- MUSIC_CONTENT_CENTER_STATUS_ERR_INTERNAL_DATA_PARSE (4):内部数据解析错误。请联系技术支持。
- MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_LOADING (5):音乐资源加载时出错。请联系技术支持。
- MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_DECRYPTION (6):音乐资源解密时出错。请联系技术支持。
onMusicChartsResult
获取音乐榜单回调。
void onMusicChartsResult(String requestId, MusicChartInfo[] list, int errorCode);
- 自从
- v4.1.0
当你调用 getMusicCharts 方法获取全部音乐榜单之后,SDK 会触发该回调。
参数
- requestId
- 请求 ID。本次请求的唯一标识。
- errorCode
-
音乐内容中心的请求状态码:
- MUSIC_CONTENT_CENTER_STATUS_OK (0):请求成功。
- MUSIC_CONTENT_CENTER_STATUS_ERR (1):一般错误,无明确归因。
- MUSIC_CONTENT_CENTER_STATUS_ERR_GATEWAY (2):网关异常。可能的原因有:
- 当前使用的 Token 已过期。请重新生成 Token。
- 传入的 Token 无效。请确保你使用的是 RTM Token。
- 网络错误。请检查你的网络。
- MUSIC_CONTENT_CENTER_STATUS_ERR_PERMISSION_AND_RESOURCE (3):权限错误或音乐资源不存在。请确保你的项目已开通声网音乐内容中心权限,请联系技术支持。
- MUSIC_CONTENT_CENTER_STATUS_ERR_INTERNAL_DATA_PARSE (4):内部数据解析错误。请联系技术支持。
- MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_LOADING (5):音乐资源加载时出错。请联系技术支持。
- MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_DECRYPTION (6):音乐资源解密时出错。请联系技术支持。
- list
- 当前可播放的音乐榜单列表。详见 MusicChartInfo。
onMusicCollectionResult
获取音乐资源列表回调。
void onMusicCollectionResult( String requestId, int page, int pageSize, int total, Music[] list, int errorCode);
- 自从
- v4.1.0
当你调 getMusicCollectionByMusicChartId [1/2] 方法来获取指定榜单的音乐资源列表或调用 searchMusic [1/2] 来搜索音乐资源时,SDK 会触发此回调报告榜单中音乐资源列表的详细信息。
参数
- requestId
- 请求 ID。本次请求的唯一标识。
- errorCode
-
音乐内容中心的请求状态码:
- MUSIC_CONTENT_CENTER_STATUS_OK (0):请求成功。
- MUSIC_CONTENT_CENTER_STATUS_ERR (1):一般错误,无明确归因。
- MUSIC_CONTENT_CENTER_STATUS_ERR_GATEWAY (2):网关异常。可能的原因有:
- 当前使用的 Token 已过期。请重新生成 Token。
- 传入的 Token 无效。请确保你使用的是 RTM Token。
- 网络错误。请检查你的网络。
- MUSIC_CONTENT_CENTER_STATUS_ERR_PERMISSION_AND_RESOURCE (3):权限错误或音乐资源不存在。请确保你的项目已开通声网音乐内容中心权限,请联系技术支持。
- MUSIC_CONTENT_CENTER_STATUS_ERR_INTERNAL_DATA_PARSE (4):内部数据解析错误。请联系技术支持。
- MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_LOADING (5):音乐资源加载时出错。请联系技术支持。
- MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_DECRYPTION (6):音乐资源解密时出错。请联系技术支持。
- page
- 当前页面编号,默认从 1 开始。
- pageSize
- 每页所展示的音乐资源的最大数量,最大值为 50。
- total
- 列表内音乐资源的总数量。
- list
- 音乐资源列表的详细信息。详见 Music。
onSongSimpleInfoResult
音乐资源的详细信息回调。
void onSongSimpleInfoResult(String requestId, long songCode, String simpleInfo, int errorCode);
详情
- 自从
- v4.2.2
当你调用 getSongSimpleInfo 获取某一音乐资源的详细信息后,SDK 会触发该回调。
参数
- requestId
- 请求 ID。本次请求的唯一标识。
- songCode
- 音乐资源的编号,用于标识音乐资源。
- simpleInfo
- 音乐资源的相关信息,包含下列内容:
- 副歌片段的开始和结束的时间(ms)
- 副歌片段的歌词下载地址
- 副歌片段时长(ms)
- 歌曲名称
- 歌手名
- errorCode
-
音乐内容中心的请求状态码:
- MUSIC_CONTENT_CENTER_STATUS_OK (0):请求成功。
- MUSIC_CONTENT_CENTER_STATUS_ERR (1):一般错误,无明确归因。
- MUSIC_CONTENT_CENTER_STATUS_ERR_GATEWAY (2):网关异常。可能的原因有:
- 当前使用的 Token 已过期。请重新生成 Token。
- 传入的 Token 无效。请确保你使用的是 RTM Token。
- 网络错误。请检查你的网络。
- MUSIC_CONTENT_CENTER_STATUS_ERR_PERMISSION_AND_RESOURCE (3):权限错误或音乐资源不存在。请确保你的项目已开通声网音乐内容中心权限,请联系技术支持。
- MUSIC_CONTENT_CENTER_STATUS_ERR_INTERNAL_DATA_PARSE (4):内部数据解析错误。请联系技术支持。
- MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_LOADING (5):音乐资源加载时出错。请联系技术支持。
- MUSIC_CONTENT_CENTER_STATUS_ERR_MUSIC_DECRYPTION (6):音乐资源解密时出错。请联系技术支持。