进阶功能

---

本文介绍如何使用 KTV 场景的进阶功能。

前提条件

在使用以下“进阶功能”之前，请先实现 点歌 功能。

实现歌词与歌曲进度的同步

ZEGO 提供两种形式的歌词，逐行歌词和逐字歌词。

• 逐行歌词是指歌词按照句子来分割，一句一句展示。用户可以调用 getLrcLyric 接口，传入歌曲的 song_id 获取逐行歌词。
• 逐字歌词是指歌词逐行展示后，一个字一个字的高亮呈现，可以用来做精确的歌词进度展示。用户可以调用 getKrcLyricByToken 接口，传入获取伴奏资源信息 requestResource 时得到的 krcToken 来获取逐字歌词。

1 获取歌词

点歌后或播放歌曲前，用户可以调用获取歌词的方法获取整首歌的歌词。具体回调的信息参考 获取歌曲与歌词资源接口说明。

/** 歌曲的 songID */
NSString *songID = @"";
/** 版权方，其对应的枚举值信息，请联系 ZEGO 商务咨询*/
ZegoCopyrightedMusicVendorID vendorID = ; 
/** 一次性获取逐行歌词 */
[self.copyrightedMusic getLrcLyric:songID vendorID:vendorID callback:^(int errorCode, NSString * _Nonnull lyrics) {
    NSLog(@"逐行歌词是：%@", lyrics);
}];

/** 点歌时获取的 krcToken */
NSString *krcToken = @"";
/** 一次性获取逐字歌词 */
[self.copyrightedMusic getKrcLyricByToken:krcToken callback:^(int errorCode, NSString * _Nonnull lyrics) {
    NSLog(@"逐字歌词是：%@", lyrics);
}];

分享歌曲

点歌用户点完歌曲后，其他用户可以调用 getSharedResource 获取对应的歌曲资源，接口回调的信息参考 获取歌曲与歌词资源接口说明。

获取成功后，可参考 点歌 - 4.4 下载歌曲 获取歌曲资源。

/** 点歌用户分享的歌曲资源对应的 songID */
ZegoCopyrightedMusicGetSharedConfig* config = [ZegoCopyrightedMusicGetSharedConfig new];
config.songID = @"";
config.vendorID = ;

/** 资源类型 */
ZegoCopyrightedMusicResourceType resourceType = ZegoCopyrightedMusicResourceSong;

[self.copyrightedMusic getSharedResource:config type:resourceType  callback:^(int errorCode, NSString * _Nonnull resource) {
    if (errorCode == 0) {
        // 歌曲资源获取成功，可进行下载歌曲等操作
    } else {
        // 失败
    }
}];

伴奏/原唱切换

在用户需要切换伴奏/原唱的场景下，要求伴奏资源有原唱和伴奏双音轨。

在点伴奏的结果回调 ZegoCopyrightedMusicRequestResourceCallback、ZegoCopyrightedMusicGetSharedResourceCallback 中，“has_original” 字段会告知用户该资源是否有原唱，详细信息参考 获取歌曲与歌词资源接口说明。

若该资源有原唱，用户可以调用 setAudioTrackIndex 进行伴奏/原唱切换：

• 0 表示伴奏；
• 1 表示原唱。

/** 播放器 */
ZegoMediaPlayer *mediaPlayer = [[ZegoExpressEngine sharedEngine] createMediaPlayer];
/** 伴奏/原唱音轨 */
int index = 0;  // 0 代表伴奏音轨，1 代表原唱音轨。
int res = [mediaPlayer setAudioTrackIndex:index];

演唱分数与音高线

用户在根据伴奏演唱时，可以获取每一句演唱的分数，也可以在整个演唱结束后，获取到总分。

仅伴奏资源支持演唱分数的获取。

1 获取演唱分数

实现流程

1. 通过 实现歌词与歌曲进度的同步 中获取逐字歌词。
2. 在开始播放伴奏音乐后，使用版权音乐的评分接口 startScore 开始评分。
3. 通过获取逐字歌词回调 ZegoCopyrightedMusicGetKrcLyricByTokenCallback 中的参数行开始时间 begin_time 和行持续时间 duration 相加判断一句歌词完成，在用户唱完一句后，可调用 getPreviousScore 接口获取本句得分。

2 获取演唱总分

用户可以在演唱结束后，调用 getTotalScore 计算出整个演唱的总得分。

3 获取音高线数据

开发者可以用演唱声音的音高和歌曲伴奏本身的音高来展示歌曲的音高线。

实现流程

1. 通过 实现歌词与歌曲进度的同步 中获取逐字歌词。

2. 调用 startScore 接口开始评分。

3. 调用 getStandardPitch 接口获取标准音高数组，数组里每一个音高线包含开始时间 begin_time，持续时间 duration，音高值 value（范围 10-90）。

4. 调用 getCurrentPitch 接口获取当前演唱声音的音高数组。

/** 音高线数据 */
{
    "pitch": [
      {
        "begin_time": 13350,
        "duration": 199,
        "value": 18
      },
      {
        "begin_time": 13549,
        "duration": 600,
        "value": 26
      }
    ]
}

/** 音乐资源 ID */
NSString *resourceID = @"";

// 开始播放的位置
unsigned long long startPosition = ;

// 创建 ZegoMediaPlayer
ZegoMediaPlayer *mediaPlayer = [[ZegoExpressEngine sharedEngine] createMediaPlayer];

[mediaPlayer loadCopyrightedMusicResourceWithPosition:resourceID startPosition: startPosition callback:^(int errorCode) {

}];

[mediaPlayer start];

// 播放器状态变化回调
- (void)mediaPlayer:(ZegoMediaPlayer *)mediaPlayer stateUpdate:(ZegoMediaPlayerState)state errorCode:(int)errorCode {
    if (state == ZegoMediaPlayerStatePlaying) {
        // 重置分数
        [self.copyrightedMusic resetScore:self.resourceID];
        // 开启评分，设置回调间隔为 60 ms
        // 请注意，需要在 stateUpdate 回调中监听到歌曲资源已经开始播放，才能调用 startScore 接口
        [self.copyrightedMusic startScore:self.resourceID pitchValueInterval:60];
    } 
}

// 唱完一句后，获取前一句分数
int previousScore = [copyrightedMusic getPreviousScore:resourceID];

// 获取平均分
int averageScore = [copyrightedMusic getAverageScore:resourceID];

// 获取总分
int toTalScore = [copyrightedMusic getTotalScore:resourceID];

// 获取满分
int fullScore = [copyrightedMusic getFullScore:resourceID];

// 暂停评分
[copyrightedMusic pauseScore:resourceID];

// 恢复评分
[copyrightedMusic resumeScore:resourceID];

// 停止评分
[copyrightedMusic stopScore:resourceID];

4 更多演唱分数的相关接口

开发者可以使用 getAverageScore、getTotalScore 等接口获取分数，也可以使用 pauseScore、resumeScore、stopScore、resetScore 等接口控制评分状态。

销毁版权音乐对象

当需要调用 destroyCopyrightedMusic 销毁版权音乐对象时，需在反初始化 SDK 接口 destroyEngine 之前。

// 先销毁 copyrightedMusic
[[ZegoExpressEngine sharedEngine] destroyCopyrightedMusic:self.copyrightedMusic];

// 再销毁 ZegoExpressEngine
[ZegoExpressEngine destroyEngine:^{

}];