获取版权音乐

声网提供 K 歌热门曲库，涵盖 20 多万首正版歌曲。本文介绍如何使用 KTV 场景化 API 加载版权音乐并进行播放。

注意

• 在使用获取版权音乐前，请联系技术支持开通权限。
• 本文仅适用于 K 歌场景化 API v4.0.0。

前提条件

• 已参考集成 KTV API 并实现基本的在线 K 歌逻辑，详情请参考集成 KTV API。
• 有效的声网项目、获取项目的 RTM Token，详情请参考开通服务。

信息

• 加载版权音乐时声网使用 RTM Token 进行鉴权，不会产生云信令服务费用。
• 你可以参考开通服务获取临时 RTM Token 用于测试，但在正式生产环境中，你需要自己部署一个 RTM Token 服务器来生成、更新 Token，详见部署 RTM Token。

• 如果你的网络环境部署了防火墙，请参考应用企业防火墙限制以正常使用声网服务。

实现流程

本节介绍如何获取版权歌单、加载并播放版权音乐。

1. 初始化设置

调用 initialize 初始化 KTV API 实例时，确保 KTVApiConfig中的 musicType 设为 SONG_CODE（表示使用声网音乐内容中心提供的版权音乐）并填入 RTM Token 进行鉴权。

Kotlin

// 初始化 KTVAPI 模块
   ktvApiProtocol.initialize(KTVApiConfig(
        // 你的 App ID
        "<Your Agora Appid>",
        // RTM Token，仅在使用声网版权音乐时需要填该参数
        "<Your Agora Rtm Token>",
        mRtcEngine,
        // 需加入的频道名称
        "<Your Channel Name>",
        // 用户 ID
        "<Your Uid>",
        // 合唱子频道的频道名，由外部指定
        "<Your Chorus Channel Name>",
        // 根据频合唱子频道名和用户 ID 生成的 Token，用于加入该频道时鉴权
        "<Your Agora Chorus Token>")
        // 设置可缓存的音乐资源数量，最多不能超过 50
   		10,
        // 设置 K 歌的场景
        KTVType.Normal,
        // 设置音乐资源类型为版权音乐
        KTVMusicType.SONG_CODE
   )

信息

当用于音乐内容中心鉴权的的 RTM Token 即将过期时，你会收到 onTokenPrivilegeWillExpire 回调。你需要调用 KTVApi 下的 renewToken 来更新 Token。

2. 获取歌曲列表

你可以调用 searchSong 来通过关键词搜索歌曲，也可以调用 fetchMusicCharts 来获取音乐榜单，然后再调用 searchMusicByMusicChartId 来通过歌曲榜单的 ID 获取指定榜单的歌曲资源列表。

Kotlin

// 用关键词搜索歌曲。
fun searchSong(condition: String, page: Int) {
    val jsonOption = "{\"pitchType\":1,\"needLyric\":true}" // 搜索过滤条件。
    ktvApiProtocol.searchMusicByKeyword(condition, page, 50, jsonOption) { requestId, status, page, pageSize, total, list ->
		// 回调内直接处理异步调用结果。
	}
}

Kotlin

// 获取音乐榜单。
fun fetchMusicCharts() {
    ktvApiProtocol.fetchMusicCharts() { requestId, status, list ->
		// 回调内直接处理异步调用结果。
	}
}


// 通过榜单号获取歌曲列表。
fun searchSongWithRankingChartId(type: Int, page: Int) {
    val jsonOption = "{\"pitchType\":1,\"needLyric\":true}" // 过滤条件
    ktvApiProtocol.searchMusicByMusicChartId(type, page, 50, jsonOption) { requestId, status, page, pageSize, total, list ->
		// 回调内直接处理异步调用结果
	}
}

注意

你可以通过 jsonOption 字段来筛选有副歌片段、支持打分的音乐资源。jsonOption 字段的具体说明见 searchMusicByKeyword 及 searchMusicByMusicChartId 的 API 文档。

3. 加载及播放版权音乐

调用 loadMusic[1/2] 加载声网的版权音乐。该方法中你需要传入歌曲编号并进行歌曲加载配置。歌曲加载结果会通过 IMusicLoadStateListener 接口类下的回调通知你。在调用该方法时，你需要传入下列参数：

• songCode：歌曲编号。如果你需要播放歌曲的副歌片段，需要先调用 getInternalSongCode 方法为该片段创建一个编号，作为该片段的唯一标识。当你获取到该片段的编号后，调用 loadMusic[1/2] 并将获取到的副歌片段编号传入 songCode 参数来加载该副歌片段。
• config：歌曲加载配置，包含下列参数：
  • autoPlay：歌曲加载完成后是否自动播放
    • true：自动播放歌曲，此时用户角色会自动切换为独唱者。
    • false：不自动播放歌曲。歌曲加载成功后如果听众需要开始独唱或加入合唱，则需要在 onMusicLoadSuccess 回调内调用 switchSingerRole 切换为对应的角色然后调用 startSing 播放歌曲。
  • mode：歌曲加载的模式，默认为加载歌曲及歌词。
  • mainSingerUid：独唱者的用户 ID。
• IMusicLoadStateListener：监听歌曲加载状态的接口类。

信息

目前仅支持一次加载一首歌曲，请在一首歌曲加载完成后再加载下一首。

Kotlin

// 下列示例代码以独唱者为例，提供两种方案展示如何加载、播放版权音乐
// 方案 1：autoPlay 设置为 true, 歌曲加载成功后会自动将用户角色切换为独唱者并开始播放歌曲
ktvApiProtocol.loadMusic(
    songCode,
    KTVLoadMusicConfiguration(true, mainSingerUid, KTVLoadMusicMode.LOAD_MUSIC_AND_LRC),
    object : IMusicLoadStateListener {
        override fun onMusicLoadSuccess(songCode: Long, lyricUrl: String) {
            // 加载成功
        }

        override fun onMusicLoadFail(songCode: Long, reason: KTVLoadSongFailReason) {
            // 加载失败
        }

        override fun onMusicLoadProgress(songCode: Long, percent: Int, status: MusicLoadStatus, msg: String?, lyricUrl: String?) {
            // 报告加载进度
        }
    }
)

// 方案 2：autoPlay 设置为 false 时, 歌曲加载成功后不会自动播放，需要在 onMusicLoadSuccess 回调内调用 switchSingerRole 切换用户角色为独唱者，再调用 startSing 开始演唱
ktvApiProtocol.loadMusic(
    songCode,
    KTVLoadMusicConfiguration(false, mainSingerUid, KTVLoadMusicMode.LOAD_MUSIC_AND_LRC),
    object : IMusicLoadStateListener {
        override fun onMusicLoadSuccess(songCode: Long, lyricUrl: String) {
            // 歌曲加载成功后，调用 switchSingerRole 将用户角色设为独唱者
            ktvApiProtocol.switchSingerRole(SoloSinger)
            // 开始唱歌
            ktvApiProtocol.startSing(songCode, 0)
        }

        override fun onMusicLoadFail(songCode: Long, reason: KTVLoadSongFailReason) {
            // 加载失败
        }

        override fun onMusicLoadProgress(songCode: Long, percent: Int, status: MusicLoadStatus, msg: String?, lyricUrl: String?) {
            // 报告加载进度
        }
    }
)

如果你需要取消当前正在加载的版权音乐、或者清除已加载的缓存，可以调用 removeMusic 方法。

Kotlin

ktvApiProtocol.removeMusic(songCode)

API 参考

本文集成步骤中使用如下 API：

• K 歌房场景化 API
• 实时互动 API

相关文档

• 集成 KTV API
• 独唱方案
• 合唱方案
• 抢唱方案
• 接唱方案