点歌

1 功能简介

ZEGO 版权内容中心，提供了在线 K 歌场景所需歌曲内容。内容由音乐合作的版权方提供，如需进一步了解版权内容中心，请联系 ZEGO 商务人员咨询。

本文将介绍如何快速实现在线 KTV 场景下搜索、下载和播放正版曲库歌曲的流程。

相关概念

• ZEGO Express SDK：由 ZEGO 提供的实时音视频 SDK，能够为开发者提供便捷接入、高清流畅、多平台互通、低延迟、高并发的音视频服务。
• 点歌：通过 requestResource 等接口获取一首歌曲或伴奏的播放权限。
• 歌曲相关接口扩展说明：用户在使用 ZEGO Express SDK 的版权音乐功能时，所需遵循的调用接口与返回值的相关扩展说明。相关扩展说明为 发送扩展请求接口说明 以及 获取歌曲与歌词资源接口说明。
• 分享资源：用户在点歌/点伴奏成功后，其他用户可以调用 getSharedResource 获取被分享的音乐资源。

2 示例源码

下载 示例源码，体验 ZEGO 在线 KTV 版权音乐点歌功能。

3 前提条件

在实现基本的版权音乐功能之前，请确保：

• 已在项目中集成 ZEGO Express SDK（含版权音乐功能），详情请参考 SDK 集成。
• 已在 ZEGO 控制台 创建项目，并申请有效的 AppID 和 AppSign，详情请参考 控制台 - 项目管理 中的“项目信息”。
• 已联系 ZEGO 商务人员为 AppID 开通版权音乐服务。

4 实现流程

用户实现点歌并播放的基本流程如下图：

1. 调用 createEngine 初始化 ZEGO Express SDK，调用 loginRoom 登录房间。
2. 调用 createCopyrightedMusic 创建版权音乐对象，调用 initCopyrightedMusic 接口，初始化版权音乐对象。
3. 调用 sendExtendedRequest 接口，传入相应参数获取 songID（songID 是一首歌曲的唯一标识）。例如传入 "/top/song" 可获取到当前热门的歌曲列表。
4. 调用 requestResource 点歌，获取歌曲的资源信息。歌曲的资源信息包括歌曲名、歌曲时长、resourceID 等。
5. 调用 download 接口传入 resourceID，将歌曲下载到设备中（歌曲必须先下载完成才能播放）。
6. 调用 createMediaPlayer 初始化播放器，调用播放器等。loadCopyrightedMusicResource 加载歌曲资源，加载成功后调用 start 开始播放。
7. 向远端用户推送唱歌音频流。

4.1 初始化 SDK

步骤 1：调用 createEngine 初始化 SDK。

步骤 2（可选）：调用 loginRoom 登录房间。

步骤 3：调用 createCopyrightedMusic 创建版权音乐对象。

步骤 4：调用 initCopyrightedMusic 初始化版权音乐音乐对象。

/** 定义 CopyrightedMusic 对象 */
ZegoCopyrightedMusic copyrightedMusic;

/** 1. 定义 SDK 引擎对象 */
ZegoExpressEngine engine;
ZegoEngineProfile profile = new ZegoEngineProfile();
/** 请通过官网注册获取，格式为 123456789L */
profile.appID = appID;
/** 64个字符，请通过官网注册获取，格式为 "0123456789012345678901234567890123456789012345678901234567890123" /
/** 如果使用 token 鉴权，不需要配置此参数*/
profile.appSign = appSign;
/** KTV场景接入 */
profile.scenario = ZegoScenario.KARAOKE;
/** 设置 app 的 application 对象 */
profile.application = getApplication();
/** 创建引擎 */
engine = ZegoExpressEngine.createEngine(profile, null);

/** 2. 登录房间*/
// 此步骤对于使用 **appSign** 鉴权的开发者而言，此步骤为 **可选** 步骤；对于使用 **token** 鉴权的开发者，此步骤为 **必需** 步骤。
// ZegoUser 的构造方法 public ZegoUser(String userID) 会将 “userName” 设为与传的参数 “userID” 一样。“userID” 与 “userName” 不能为 “null” 否则会导致登录房间失败。
ZegoUser user = new ZegoUser("userID");

ZegoRoomConfig roomConfig = new ZegoRoomConfig();
//token 由用户自己的服务端生成，为了更快跑通流程，可以通过 ZEGO 控制台 https://console.zego.im/ 获取临时的音视频 token
roomConfig.token = ""; // 如果使用appSign 鉴权，登录房间不需要此参数
// 只有传入 “isUserStatusNotify” 参数取值为 “true” 的 ZegoRoomConfig，才能收到 onRoomUserUpdate 回调。
roomConfig.isUserStatusNotify = true;

// roomID 由您本地生成,需保证 “roomID” 全局唯一。不同用户要登录同一个房间才能进行通话
String roomID = "room1";

// 登录房间
engine.loginRoom(roomID, user, roomConfig, (int error, JSONObject extendedData)->{
// 登录房间结果，如果仅关注登录结果，关注此回调即可
    if (error == 0) {
            // 登录成功
            Toast.makeText(this, "登录成功", Toast.LENGTH_LONG).show();
    } else {
            // 登录失败，请参考 errorCode 说明 https://doc-zh.zego.im/article/4378
            Toast.makeText(this, "登录失败，请参考 errorCode 说明 https://doc-zh.zego.im/article/4378", Toast.LENGTH_LONG).show();
    }
});

/** 3. 创建 CopyrightedMusic 对象 */
copyrightedMusic = engine.createCopyrightedMusic();

/** 4. 初始化 CopyrightedMusic 对象 */
ZegoCopyrightedMusicConfig config = new ZegoCopyrightedMusicConfig();
/** 填写 userID、userName */
/** 如果已经在初始化版权音乐功能前登录房间，请确保 [initCopyrightedMusic] 接口所需传入的 userID、userName 与 [loginRoom] 所传相关内容保持一致且唯一。*/
String userID = "";
String userName = "";
ZegoUser user = new ZegoUser(userID, userName);
config.user = user;

copyrightedMusic.initCopyrightedMusic(config, new IZegoCopyrightedMusicInitCallback() {
    @Override
    public void onInitCallback(int i) {

    }
});

4.2 获取歌曲列表

4.2.1 获取方式

用户可用以下三种方式获取歌曲列表：

4.2.2 调用流程

如下介绍如何使用第 1 种方式获取歌曲列表：

1. 调用 sendExtendedRequest 接口，command 传入 "/tag/list"，params 传入 "{vendor_id：xx}"，即版权方 ID（具体信息请联系 ZEGO 技术支持），在回调中获取到标签列表。

   sendExtendedRequest 接口完整参数与返回结果的说明请参考 发送扩展请求接口说明。

2. 选择某个标签，调用 sendExtendedRequest 接口，command 传入 "/tag/song"，params 传入下列 JSON 格式的字符串，即可在回调中获取到歌曲列表。

   • JSON 格式如下：

     {
         "tag_id": "587", // 从步骤 1 的标签列表回调中选择
         "page": 1,
         "filter": [1],
         "vendor_id": 0
     }

   • 示例代码：

     // 下面以通过标签获取歌曲列表为例
     String command = "/tag/song"; // command 参数代表您请求的业务指令，该示例为标签获取歌曲
     String params = "{ \"vendor_id\": 0, \"tag_id\": \"587\",  \"page\": 1,  \"filter\": [1]}"; // params 参数，是 JSON 格式的字符串，需要您传入的额外参数
     
     copyrightedMusic.sendExtendedRequest(command, params, new IZegoCopyrightedMusicSendExtendedRequestCallback() {
         @Override
         public void onSendExtendedRequestCallback(int i, String s, String s1) {
             // s: command 参数代表您请求的业务指令
             // s1: result 回调结果，JSON 格式字符串
         }
     });

4.2.3 版权信息

在获得的歌曲列表中，每首歌曲都有对应的 copyright 字段，表示这个歌曲的版权信息。

copyright 的结构如下：

//该字段位于 result.data.songs[i].copyright 
{
    "song_lyric": 0,
    "recording": 1,
    "channel": 0
}

具体字段说明如下：

4.3 获取歌曲资源

4.3.1 获取包含人声的歌曲资源

如果包含人声的歌曲资源有版权，就可以调用 requestResource 接口获取到歌曲的资源信息，包括歌曲名、歌曲时长、resourceID 等，接口具体回调的信息参考 获取歌曲与歌词资源接口说明。

// recording 为 1 代表该首歌有包含人声的歌曲的版权
if (recording == 1) {
    /** 点歌配置 */
    ZegoCopyrightedMusicRequestConfig config = new ZegoCopyrightedMusicRequestConfig();
    /** 音乐 songID */
    config.songID = "";
    /** 计费模式，请联系 ZEGO 商务咨询 */
    config.mode = ZegoCopyrightedMusicBillingMode.COUNT;
    /** 版权方，其对应的枚举值信息，请联系 ZEGO 商务咨询*/
    config.vendorID = ZegoCopyrightedMusicVendorID.ZEGO_COPYRIGHTED_MUSIC_DEFAULT;
    /** 场景 ID：1 语聊房、2 直播间在线 K 歌、3 直播间播放背景音乐、4 抢唱*/
    /** 请联系 ZEGO 商务开通使用场景，使用过程请传入正确的场景 ID。*/
    config.sceneID = 0;
    /** 
      * 资源类型包含：
      * ZegoCopyrightedMusicResourceSong：包含人声的原曲
      * ZegoCopyrightedMusicResourceAccompaniment：伴奏
      * ZegoCopyrightedMusicResourceAccompanimentClip：伴奏高潮片段
      */
    ZegoCopyrightedMusicResourceType resourceType = ZegoCopyrightedMusicResourceType.ZEGO_COPYRIGHTED_MUSIC_RESOURCE_SONG;

    /** 点歌 */
    copyrightedMusic.requestResource(config, resourceType, new IZegoCopyrightedMusicRequestResourceCallback() {
        @Override
        public void onRequestRsourceCallback(int i, String s) {
            // s: result
        }
    });
} else {
    // 该首歌没有包含人声的歌曲的版权
}

4.3.2 获取歌曲伴奏/伴奏高潮片段资源

通过调用 requestResource 接口，还可以获取歌曲对应的 “伴奏资源”、“长分片高潮片段资源”、“短分片高潮片段资源”，其实现流程与 获取包含人声的歌曲资源 一致。

获取歌曲对应伴奏、长/短分片高潮片段、抢唱片段的资源时，回调会多出了一些字段，比如 krc_token 等，详情请参考 获取歌曲与歌词资源接口说明。

4.4 下载歌曲

通过 4.3 获取歌曲资源 中点歌获取 resourceID 后，调用 download 接口下载歌曲，下载成功的结果通过 download 接口本身的回调获取。

如果需要获取下载进度，可通过 onDownloadProgressUpdate 回调获取。

resourceID 是开发者在调用 requestResource、getSharedResource 2 个接口时生成的，只在 SDK 的生命周期里有效，SDK 反初始化时就会销毁，因此不能储存到磁盘或者分发给其他用户使用。

/** resourceID */
String resourceID = "";

copyrightedMusic.download(resourceID, new IZegoCopyrightedMusicDownloadCallback() {
    @Override
    public void onDownloadCallback(int i) {

    }
    if (errorCode == 0) {
        // 歌曲下载成功，可以进行播放等操作

    } else {
        // 歌曲下载失败
    }
};

4.5 播放歌曲

4.5.1 开始播放

歌曲下载完成后（收到 download 接口的成功回调），使用 ZegoMediaPlayer 并调用 start 接口开始播放歌曲。

/** 音乐资源 ID，点歌（requestResource）时可获取到 */
String resourceID = "";

// play 开始播放时的进度
long startPosition = 0;

// 1. 通过 ZegoExpressEngine 的 createMediaPlayer 方法 创建 ZegoMediaPlayer
ZegoMediaPlayer mediaPlayer = engine.createMediaPlayer();

// 2. 加载歌曲对应的 resourceID，从 startPosition 处开始加载。注意，只有该歌曲资源下载完成了，这里才能加载成功
mediaPlayer.loadCopyrightedMusicResourceWithPosition(resourceID, startPosition, new IZegoMediaPlayerLoadResourceCallback() {
    @Override
    public void onLoadResourceCallback(int errorcode) {

    }
});

// start 开始播放
mediaPlayer.start();

4.5.2 暂停/恢复/跳转/停止

调用 download 接口下载完资源后，可以调用 pause、resume、seekTo、stop 等接口控制播放状态。

// pause 暂停播放
mediaPlayer.pause();

// resume 恢复播放
mediaPlayer.resume();

// stop 停止播放
mediaPlayer.stop();

// seekTo 调整播放进度到 position 位置，position 为毫秒数
long position = 0L;
mediaPlayer.seekTo(position, new IZegoMediaPlayerSeekToCallback() {
    @Override
    public void onSeekToCallback(int i) {

    }
});

4.6 推送唱歌音频流

点播歌曲完成后，需要推送歌声音频流，以供远端用户听到演唱用户的歌声。请根据实际需求，参考 独唱方案、实时合唱方案、串行合唱方案 或 抢唱方案 实现推流。

5 API 调用时序