歌词同步实现流程

---

1 功能实现流程图

目前运用最广的歌词文件LRC文件内容如下。

 [00:02.37] 即构KTV
 [00:03.12]
 [00:03.80] 作词：即构
 [00:04.55] 作曲：即构
 [00:05.18] 演唱：即构
 [00:06.43] 出品：深圳即构科技

这种格式文件小，容易解析，歌词的精度控制到一行。

当观众、合唱、主唱都存在此歌词文件时，此时只需要知道当前音乐进度时间戳，就能达到歌词同步。

即构 SDK 支持将非媒体信息注入媒体流中。歌词信息和音视频信息是在同一个媒体通道传输的，这样可以保障歌词和音视频同步。歌词进度由主唱端发送，观众跟合唱端接收到时间戳后，再根据时间戳把关键歌词行高亮。达到歌词同步展示的效果。

具体实现流程图请参考：

内部约定主唱端与观众、合唱的歌词同步信息通信格式即可。

2 接收歌词时间戳数据

即构 SDK 拉流解码提取出媒体次要信息，会将其通过 setMediaSideCallback 设置的回调给应用开发者。合唱者、观众需要关注这个回调接口。

2.1 设置回调，接收媒体次要信息

ZEGO SDK 提供了相关接口，用于设置回调，接收媒体次要信息。

ZegoLiveRoomApi-Player.h

/**
设置回调, 接收媒体次要信息

@param onMediaSideCallback 回调函数指针, pszStreamID：流ID，标记当前回调的信息属于哪条流， buf：接收到的信息数据（具体内容参考官网对应文档中的格式说明）, dataLen：buf 总长度
@discussion 开始拉流前调用。观众端在此 API 设置的回调中获取主播端发送的次要信息（要求主播端开启发送媒体次要信息开关，并调用 [ZegoLiveRoomApi (Publisher) -sendMediaSideInfo:dataLen:packet:] 发送次要信息）。当不需要接收信息时，需将 onMediaSideCallback 置空，避免内存泄漏
*/
- (void)setMediaSideCallback:(void(*)(const char *pszStreamID, const unsigned char* buf, int dataLen))onMediaSideCallback;

其中，当用户端收到媒体次要信息时，SDK 会调用之。

2.2 实现回调函数，处理媒体次要信息

媒体次要信息会作为 onReceivedMediaSideInfo 的入参传递进去，开发者需要在该函数内，根据业务要求，处理媒体次要信息。

主唱向观众、合唱端发送的数据格式为时间戳。KTV App 中处理媒体次要信息的示例代码如下：

ZegoLiveRoomApi-Player.h

static void onReceivedMediaSideInfo(const char *pszStreamID, const unsigned char* buf, int dataLen) {
        if (dataLen == 0) {
            NSLog(@"onReceivedMediaSideInfo data is empty");
            return;
        }
        uint8_t *data = (uint8_t *)buf;
        int32_t offset = 4;
         // 偏移offset字节转换成int
        int32_t timeStamp = (data[offset] & 0xff) | ((data[offset+1] & 0xff) << 8) | ((data[offset+2] & 0xff) << 16) | ((data[offset+3] & 0xff) << 24);
        // 此处拿到时间戳数据 timeStamp
        // 拿到timeStamp后根据时间戳的值展示歌词信息
}

[api setMediaSideCallback:onReceivedMediaSideInfo];

当拿到timeStamp后，解析歌词展示timeStamp时间段的歌词数据就OK了。

3 主唱端发送歌词信息

3.1 发送媒体次要信息

即构 SDK 提供了相关接口，用于发送媒体次要信息。在 KTV 场景中，歌词信息就作为媒体次要信息注入媒体流中，连同音视频数据一同发送到拉流端。观众、合唱者等拉流端接受到媒体次要信息后，得到应用进度时间戳。

如果要发送媒体次要信息，首先需要开启媒体次要信息开关。接口如下所示:

ZegoLiveRoomApi-Publisher.h

/**
 发送媒体次要信息开关

 @param start 开启媒体次要信息传输，true 开启媒体次要信息传输, false 关闭媒体次要信息传输。start 为 true 时，onlyAudioPublish 开关才有效
 @param onlyAudioPublish 是否纯音频直播，true 纯音频直播，不传输视频数据，false 音视频直播，传输视频数据。默认为 false。如果本次只有音频直播，必须将 onlyAudioPublish 置为 true，此时将会由音频来驱动次要信息的传输，同时忽略视频流传输
 @discussion 初始化 SDK 后，开始推流前调用。
 */
- (void)setMediaSideFlags:(bool)start onlyAudioPublish:(bool)onlyAudioPublish;

开启媒体次要信息开关后，才能使用以下接口进行发送媒体次要信息。

ZegoLiveRoomApi-Publisher.h

/**
 发送媒体次要信息

 @param inData 需要传输的音视频次要信息数据，外部输入
 @param dataLen 传入的 inData 总长度，不能大于 1000 Bytes
 @param packet 是否外部已经打包好包头，true 已打包, false 未打包。如果没有特殊情况，建议用户使用内部打包
 @discussion 主播端开启媒体次要信息开关，开始推流后调用。调用此 API 发送媒体次要信息后，观众端在 [ZegoLiveRoomApi (Player) -setMediaSideCallback:] 设置的回调中获取媒体次要信息。不需要发送媒体次要信息时，可调用 [ZegoLiveRoomApi (Publisher) setMediaSideFlags:false onlyAudioPublish:false] 关闭通道
 */
- (void)sendMediaSideInfo:(const unsigned char *)inData dataLen:(int)dataLen packet:(bool)packet;

3.2 使用发送媒体次要信息接口，如何进行媒体次要信息发送

媒体次要信息会作为 inData 的参传入到SDK，开发者调用该函数，根据业务要求，传入媒体次要信息。

演示 Demo 中发送媒体次要信息的示例代码如下：

int timeStamp = 50; // 获取播放进度时间戳
Byte mediaSideInfo[4] = {};
mediaSideInfo[0] = (Byte) (timeStamp & 0xFF);
mediaSideInfo[1] = (Byte) ((timeStamp >> 8) & 0xFF);
mediaSideInfo[2] = (Byte) ((timeStamp >> 16) & 0xFF);
mediaSideInfo[3] = (Byte) ((timeStamp >> 24) & 0xFF);

[[ZegoManager api] sendMediaSideInfo:mediaSideInfo dataLen:4 packet:false];

timeStamp，是当前播放的进度时间戳，需要通过播放器SDK MediaPlayer播放器的函数，去获取该伴奏播放的进度时间戳。

关于媒体次要信息功能的详细说明，可参考文档：视频进阶-媒体次要信息

3.3 使用MediaPlayer播放器拿到当前播放的时间戳数据

知道怎么发送媒体次要信息了，接下来使用ZEGO SDK MediaPlayer提供的函数拿到时间戳

示例代码如下：

ZegoMediaPlayer* player = [[ZegoMediaPlayer alloc] initWithPlayerType:MediaPlayerTypeAux];
// 通过该函数获取到播放伴奏进度时间戳
long timeStamp = [player getCurrentDuration];

拿到timeStamp 后，主唱端需要做一个定时器循环去取这个时间戳使用SDK媒体次要信息接口发送出去。

每秒循环取一次，直到该首歌播放完毕, 让观众、合唱歌词展示达到同步状态。