获取版权音乐

声网内容中心提供 K 歌热门曲库，涵盖 20 多万首正版歌曲、歌词等。本文分别介绍如何使用 KTV 场景化 API 及 RESTful API 获取声网内容中心提供的版权音乐并进行播放。

前提条件

• 已实现基本的在线 K 歌逻辑，详情请参考快速实现。

• 已联系技术支持开通版权音乐权限。

• 有效的声网项目，详情请参考开通服务。

• 如果你使用场景化 API 获取版权音乐，需要获取项目的 RTM Token。

  信息

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

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

实现流程

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

1. 初始化设置

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

Kotlin

// 创建并初始化 KTVAPI 模块
val ktvApiProtocol =
    createKTVApi(
        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. 获取版权音乐

针对场景化 API 方案，声网提供两种方式获取版权音乐：场景化 API 及 RESTful API。

使用场景化 API 获取

调用 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 文档。

使用 RESTful API 获取

参考下列步骤来使用 RESTful API 从声网内容中心获取版权音乐。

1. 实现 HTTP 认证

   RESTful API 仅支持 HTTPS 协议。发送请求时，你需要通过 Basic HTTP 认证，并将生成的凭证填入 HTTP 请求头部的 Authorization 字段。具体生成 Authorization 字段的方法请参考 HTTP 基本认证。

2. 获取歌曲列表

   根据你的需求调用不同的 RESTful API 来获取歌曲列表、热门榜单等，调用说明及示例详见 API 文档。

3. 加载及播放版权音乐

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

• songCode：歌曲编号。如果你需要播放歌曲的副歌片段，需要先调用 getInternalSongCode 方法为该片段创建一个编号，作为该片段的唯一标识。当你获取到该片段的编号后，调用 loadMusic[1/2] 并将获取到的副歌片段编号传入 songCode 参数来加载该副歌片段。
• config：歌曲加载配置，包含下列参数：
  • songIdentifier：歌曲的唯一标识。如果你使用的是自行维护的曲库，你需要传入该参数，并需确保唯一性。如果你使用的是声网提供的版权音乐，向 songCode 传参即可，此参数传空。
  • mode：歌曲加载的模式，默认为加载歌曲及歌词。
  • mainSingerUid：独唱者的用户 ID。
• IMusicLoadStateListener：监听歌曲加载状态的接口类。

信息

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

Kotlin

// 下列示例代码以独唱者为例，展示如何加载、播放版权音乐
// 歌曲加载成功后需要在 onMusicLoadSuccess 回调内调用 switchSingerRole 切换用户角色为独唱者，再调用 startSing 开始演唱
ktvApiProtocol.loadMusic(
    songCode,
    KTVLoadMusicConfiguration(songId, 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
• RESTful API

相关文档

本节介绍 K 歌方案的相关实现文档：

• 快速实现
• 独唱
• 合唱
• 大合唱
• 抢唱
• 接唱
• 歌词打分组件