本站点除 Legacy 产品与方案外，已迁移至声网新文档中心，当前页面不再维护





全部产品

Console 官网社区技术支持





实现点歌、独唱、合唱

更新时间 2023/09/22 10:21:24

概述

为降低开发者的集成难度，声网为 K 歌房场景提供了场景化 API。场景化 API 封装了声网音视频 SDK 的 API，并提供了 K 歌业务常见的功能，例如，对主唱和伴唱进行 NTP 时间同步。你只需要调用一个场景化 API 即可实现通过多个音视频 SDK 的 API 完成的复杂代码逻辑，从而更轻松实现 K 歌场景。声网在 GitHub 上提供 KTV 场景化 API 的源码文件 KTVApi 和 KTVApiImpl。

在使用场景化 API 方案前，请联系技术支持开通权限。
本文仅适用于 K 歌场景化 API v3.3.0。

本文介绍如何使用 KTV 场景化 API 实现点歌、独唱、合唱等基础业务功能。

前提条件

开始前，请确保你的开发环境满足以下条件：

Xcode 12.0 或以上版本。
已安装 Cocoapods。
iOS 11.0 或以上版本的设备。
有效的声网开发者账号。
有效的声网项目，获取项目的 App ID、RTC Token、RTM Token。
- 在线 K 歌房仅使用 RTM Token 进行鉴权，不会产生云信令服务费用。
- 你可以获取临时 RTM Token 用于测试，但在正式生产环境中，你需要自己部署一个 RTM Token 服务器来生成、更新 Token，详见使用 RTM Token 鉴权。
如果你的网络环境部署了防火墙，请参考应用企业防火墙限制以正常使用声网服务。

参考一下步骤来配置项目：

参考项目配置集成所需 SDK。
在工程文件中引入 KTVApi 和 KTVApiImpl。

点歌

本节介绍如何实现点歌功能。点歌指用户通过浏览榜单或搜索关键词选定想唱的正版音乐，然后下载播放音乐。用户需要在唱歌前进行点歌。

方案介绍

下图展示点歌的 API 调用时序图：

1. 初始化 KTV API 模块

调用 sharedEngineWithAppId 初始化 AgoraRtcEngineKit。请确保 AgoraRtcEngineKit 的生命周期大于 KTV API 模块的生命周期。

// 初始化 AgoraRtcEngineKit
// self.RTCkit 是定义的 AgoraRtcEngineKit 全局变量
self.RTCkit = [AgoraRtcEngineKit sharedEngineWithAppId:<Your_Agora_Appid> delegate:self];
// 在独唱场景下，将音频应用场景设为 AgoraAudioScenarioGameStreaming，在合唱场景下设为 AgoraAudioScenarioChorus
[self.RTCkit setAudioScenario:AgoraAudioScenarioGameStreaming];
[self.RTCkit setAudioProfile:AgoraAudioProfileMusicHighQuality];
[self.RTCkit setChannelProfile:AgoraChannelProfileLiveBroadcasting];

创建 KTV API 实例，并初始化 API 模块。调用 addEventHandler 注册 KTV API 事件。调用 KTV API 模块的 API 前，请确保已初始化 KTV API 实例。

 // 创建 KTVApiConfig 实例
KTVApiConfig *apiConfig = [[KTVApiConfig alloc] initWithAppId:@"<Your Agora Appid>"
                                                    rtmToken:@"<Your Agora Rtm Token>"
                                                      engine:self.RTCkit
                                                channelName:@"<Your Channel Name>"
                                                   localUid:@"<Your Uid>"
                                          chorusChannelName:@"<Your Chorus Channel Name>"
                                        chorusChannelToken:@"<Your Agora Chorus Token>"
                                                     // 设置 K 歌的场景。
                                                      type:KTVTypeNormal
                                               // 设置可缓存的音乐资源数量，最多不能超过 50。
                                               maxCacheSize:10
                                               // 设置音乐资源类型，默认为声网音乐内容中心提供的版权音乐。
                                                musicType:loadMusicTypeMcc
                                                // 设置是否开启调试模式，默认为 false。
                                                isDebugMode: false];


self.ktvApi = [[KTVApiImpl alloc] initWithConfig:apiConfig];

// 更新数据流 ID。一个频道中最多只能创建 5 个数据流。 
[self.ktvApi renewInnerDataStreamId];

// 注册 KTVAPI 事件。
[self.ktvApi addEventHandlerWithKtvApiEventHandler:self];

当用于音乐内容中心的 RTM Token、用于加入频道 2 的 Token 即将过期时，你会收到 onTokenPrivilegeWillExpire 回调。

如需更新 RTM Token，你需要先调用 KTVApiDelegate 下的 getMusicContentCenter 获取音乐内容中心实例，再调用 KTVApiDelegate 下的 renewToken 来更新 Token。
如需更新加入频道 2 的 Token，直接调用 KTVApiDelegate 下的 renewToken 来更新 Token。

当用于加入频道 1 的 Token 即将过期前，你会收到 AgoraRtcEngineDelegate 类下的 tokenPrivilegeWillExpire 回调，你需要调用 AgoraRtcEngineKit 下的 renewToken 来更新 Token。

2. 获取歌曲列表

通过关键词搜索或音乐榜单获取歌曲列表。

// 通过关键词搜索歌曲
[self.ktvApi fetchMusicChartsWithCompletion:^(NSString *requestId , AgoraMusicContentCenterStatusCode code , NSArray<AgoraMusicChartInfo *> *info) {

    }];
- (void)loadSearchDataWithKeyWord:(NSString *)keyWord {
    NSDictionary *dict = @{
        @"pitchType": @(1),
        @"needLyric": @(YES) // 用来过滤没有歌词的歌曲
    };
    NSString *extra = [NSString convertToJsonData:dict];

    [self.ktvApi searchMusicWithKeyword:keyWord ?: @""
                                   page:self.page
                               pageSize:50
                             jsonOption:extra
                             completion:^(NSString * _Nonnull, AgoraMusicContentCenterStatusCode, AgoraMusicCollection * _Nonnull) {
                                 // 结果返回
                             }];
}

// 用音乐榜单获取歌曲
- (void)loadDataWithIndex:(NSInteger)pageType {
    NSArray *chartIds = @[@(3), @(4), @(2), @(6)];
    NSInteger chartId = [[chartIds objectAtIndex:MIN(pageType - 1, chartIds.count - 1)] intValue];
    NSDictionary *dict = @{
        @"pitchType": @(1),
        @"needLyric": @(YES) // 用来过滤没有歌词的歌曲
    };
    NSString *extra = [NSString convertToJsonData:dict];

    [self.ktvApi searchMusicWithMusicChartId:chartId
                                        page:self.page
                                    pageSize:20
                                  jsonOption:extra
                                  completion:^(NSString * _Nonnull, AgoraMusicContentCenterStatusCode, AgoraMusicCollection * _Nonnull) {
                                      // 结果返回
                                  }];
}

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

3. 加载及播放歌曲

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

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

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

// 示例代码为用户点歌后需要开始独唱的场景，你可以选择下列任意一个方案开始独唱。
// 方案 1：autoPlay 设置为 YES, 歌曲加载成功后会自动将用户角色切换为独唱者（SoloSinger）并开始播放歌曲。
// mode 设为 KTVLoadMusicModeLoadLrcMusicAndLrc，同时加载歌曲和歌词。
KTVSongConfiguration *songConfig = [[KTVSongConfiguration alloc] init];
songConfig.autoPlay = YES;
songConfig.mode = KTVLoadMusicModeLoadLrcMusicAndLrc;
songConfig.mainSingerUid = mainSingerUid;

[self.ktvApi loadMusicWithSongCode:songCode
                            config:songConfig
             onMusicLoadStateListener:self];

// 歌曲加载进度回调
- (void)onMusicLoadProgressWithSongCode:(NSInteger)songCode
                                percent:(NSInteger)percent
                                 status:(AgoraMusicContentCenterPreloadStatus)status
                                    msg:(NSString *)msg
                               lyricUrl:(NSString *)lyricUrl {
}


// 方案 2：autoPlay 设置为 NO 时, 歌曲加载成功后不会自动播放。
KTVSongConfiguration* songConfig = [[KTVSongConfiguration alloc] init];
songConfig.autoPlay = NO;
// 同时加载歌曲和歌词。
songConfig.mode = KTVLoadMusicModeLoadMusicAndLrc;
songConfig.mainSingerUid = mainSingerUid;
// 歌曲加载失败的原因。
- (void)onMusicLoadFailWithSongCode:(NSInteger)songCode reason:(enum KTVLoadSongFailReason)reason {

}
// 歌曲加载成功的回调，在此回调内调用 switchSingerRole 切换角色，调用 startSing 开始播放歌曲。
- (void)onMusicLoadSuccessWithSongCode:(NSInteger)songCode lyricUrl:(NSString * _Nonnull)lyricUrl {
    // 切换角色
    [weakSelf.ktvApi switchSingerRoleWithNewRole:KTVSingRoleSoloSinger
                               onSwitchRoleState:^(KTVSwitchRoleState state, KTVSwitchRoleFailReason reason) {
        // 切换角色状态回调。
    }];
    // 开始播放歌曲。
    [weakSelf.ktvApi startSingWithSongCode:songCode startPos:0];
}

[self.ktvApi loadMusicWithSongCode:songCode config:songConfig onMusicLoadStateListener:self];

// 歌曲加载进度回调。
- (void)onMusicLoadProgressWithSongCode:(NSInteger)songCode
                                percent:(NSInteger)percent
                                 status:(AgoraMusicContentCenterPreloadStatus)status
                                    msg:(NSString *)msg
                               lyricUrl:(NSString *)lyricUrl {

}

4. 切换角色

KTV API 初始化时默认用户角色为听众，如果需要开始独唱或加入合唱，需要调用 switchSingerRole 来切换至相应的角色。 KTV API 内部会根据角色的切换来控制演唱过程中音乐播放器的播放、同步，以及订阅和发布音频流的行为。你还可以通过 onSingerRoleChanged 回调来获取角色切换的相关信息。

请参考下图来进行角色切换：

[self.ktvApi switchSingerRoleWithNewRole:role
                   // 通过闭包 onSwitchRoleState 返回切换角色的状态和失败原因。
                   onSwitchRoleState:^(KTVSwitchRoleState state, KTVSwitchRoleFailReason reason) {
    if (state == KTVSwitchRoleStateFail && reason != KTVSwitchRoleFailReasonNoPermission) {

        return;
    }

}];

// 角色已切换回调。
- (void)onSingerRoleChangedWithOldRole:(KTVSingRole)oldRole newRole:(KTVSingRole)newRole {
}

5. 监听并控制歌曲播放

歌曲播放时，音乐播放器会通过 onMusicPlayerStateChanged 回调向业务层通知歌曲播放状态改变。收到 onMusicPlayerStateChanged(AgoraMediaPlayerStateOpenCompleted) 回调后，你可以使用 seekSing、pauseSing、resumeSing 等方法控制播放器。

KTV API 模块内部会自动处理播放器同步，因此你也可以通过 onMusicPlayerStateChanged 回调获取远端播放器的状态。

// 跳转到指定时间播放歌曲
[self.ktvApi seekSing: time];

6. 释放资源

退出 K 歌场景时，你需要调用 cleanCache 释放 KTV API 模块内的资源和取消注册事件回调。请确保 AgoraRtcEngineKit 的生命周期大于 KTV API 模块。释放资源时，请在释放 KTV API 模块之后再释放 AgoraRtcEngineKit。

[self.ktvApi cleanCache];

独唱

本节介绍如何实现独唱功能。用户点歌后，可以开始独唱，K 歌房内的听众都可以听到其演唱。房间内想与独唱者连麦语聊的听众可以上麦。

方案介绍

独唱场景下存在两种角色：

独唱者：加入频道，加载并播放歌曲。KTV API 模块内部控制音乐播放器播放音乐，发布音乐到远端，将音乐播放进度同步到远端，让歌词组件进入歌词滚动状态等逻辑。
听众：加入频道，加载歌词。KTV API 模块内部控制听众订阅独唱者的人声和音乐的音频合流，同步独唱者的音乐播放进度，让歌词组件进入歌词滚动状态等逻辑。如果普通听众需要上麦聊天，可以更新媒体选项。

下图展示独唱的 API 调用时序图：

独唱者实现

1. 加入频道

调用 joinChannelByToken 让独唱者加入频道。为保证高音质，声网推荐你在加入频道前调用 SetAudioProfile 将音频编码属性设为 AgoraAudioProfileMusicHighQuality，调用 setAudioScenario 将音频场景设为 AgoraAudioScenarioGameStreaming。

// 加入频道
[self.rtcKit joinChannelByToken:<YOUR TOKEN>
                    channelId:<YOUR CHANNEL NAME>
                           info:nil
                            uid:<YOUR UID>
                   // 媒体选项，详见第 5 步操作。
                   mediaOptions:mediaOption
                   joinSuccess:nil];

2. 加载及播放歌曲

调用 loadMusic 加载歌曲。在调用该方法时，如果你将 autoPlay 设为 YES，歌曲加载完成后会自动播放，用户角色会自动设为独唱者（SoloSinger）。如果设置为 NO，则需在 onMusicLoadSuccess 回调内调用 switchSingerRole 将用户角色设为 SoloSinger，然后调用 startSing 才可以播放歌曲。

// 方案 1：加载歌曲后自动播放。
KTVSongConfiguration* songConfig = [[KTVSongConfiguration alloc] init];
songConfig.autoPlay = YES;
songConfig.mode = KTVLoadMusicModeLoadMusicAndLrc;
songConfig.mainSingerUid = mainSingerUid;

[self.ktvApi loadMusicWithSongCode:songCode config:songConfig onMusicLoadStateListener:self];

// 歌曲加载失败。
- (void)onMusicLoadFailWithSongCode:(NSInteger)songCode reason:(enum KTVLoadSongFailReason)reason {

}

// 歌曲加载成功。
- (void)onMusicLoadSuccessWithSongCode:(NSInteger)songCode lyricUrl:(NSString * _Nonnull)lyricUrl {

}

// 歌曲加载进度回调。
- (void)onMusicLoadProgressWithSongCode:(NSInteger)songCode
                               percent:(NSInteger)percent
                                status:(AgoraMusicContentCenterPreloadStatus)status
                                   msg:(NSString *)msg
                              lyricUrl:(NSString *)lyricUrl {

}

// 方案 2：autoPlay 设置为 NO 时, 歌曲加载成功后不会自动播放。
KTVSongConfiguration* songConfig = [[KTVSongConfiguration alloc] init];
songConfig.autoPlay = NO;
// 同时加载歌曲和歌词。
songConfig.mode = KTVLoadMusicModeLoadMusicAndLrc;
songConfig.mainSingerUid = mainSingerUid;
// 歌曲加载失败的原因。
- (void)onMusicLoadFailWithSongCode:(NSInteger)songCode reason:(enum KTVLoadSongFailReason)reason {

}
// 歌曲加载成功的回调，在此回调内调用 switchSingerRole 切换角色，调用 startSing 开始播放歌曲。
- (void)onMusicLoadSuccessWithSongCode:(NSInteger)songCode lyricUrl:(NSString * _Nonnull)lyricUrl {
    // 切换角色
    [weakSelf.ktvApi switchSingerRoleWithNewRole:KTVSingRoleSoloSinger
                               onSwitchRoleState:^(KTVSwitchRoleState state, KTVSwitchRoleFailReason reason) {
        // 切换角色状态回调。
    }];
    // 开始播放歌曲。
    [weakSelf.ktvApi startSingWithSongCode:songCode startPos:0];
}

[self.ktvApi loadMusicWithSongCode:songCode config:songConfig onMusicLoadStateListener:self];

// 歌曲加载进度回调。
- (void)onMusicLoadProgressWithSongCode:(NSInteger)songCode
                                percent:(NSInteger)percent
                                 status:(AgoraMusicContentCenterPreloadStatus)status
                                    msg:(NSString *)msg
                               lyricUrl:(NSString *)lyricUrl {

}

3. 歌曲结束

当歌曲播放完成或切歌后，你需要调用 switchSingerRole 将用户的角色切回听众。

[self.ktvApi switchSingerRoleWithNewRole:KTVSingRoleAudience
                      onSwitchRoleState:^(KTVSwitchRoleState state, KTVSwitchRoleFailReason reason) {
                      }];

4. 关闭麦克风

独唱者停止唱歌或希望暂时关闭麦克风时，可以调用 adjustRecordingSignalVolume，将音频采集信号音量设置为 0。

[self.RTCKit adjustRecordingSignalVolume:0];

5. 根据角色更新媒体选项

通过 updateChannelWithMediaOptions 方法在主播加入频道后更新频道媒体选项，例如是否开启本地音频采集，是否发布本地音频流等。

AgoraRtcChannelMediaOptions* options = [AgoraRtcChannelMediaOptions new];
// 发布本地麦克风流。
options.publishMicrophoneTrack = YES;
// 启用音频采集和播放。
options.enableAudioRecordingOrPlayout = YES;
// 设置角色为主播。
options.clientRoleType = AgoraClientRoleBroadcaster;
// 更新媒体选项。
[self.RTCKit updateChannelWithMediaOptions:options];

听众实现

1. 加入频道

调用 joinChannelByToken 让听众加入频道。

// 加入频道
[self.rtcKit joinChannelByToken:<YOUR TOKEN>
                    channelId:<YOUR CHANNEL NAME>
                           info:nil
                            uid:<YOUR UID>
                   // 媒体选项，详见第 3 步操作。
                   mediaOptions:mediaOption
                   joinSuccess:nil];

2. 加载歌词

调用 loadMusic 加载歌词。听众加入频道后，默认订阅独唱者发布的音频合流，即独唱者人声和音乐混合的音频流，因此只需要加载歌词。

KTVSongConfiguration* songConfig = [[KTVSongConfiguration alloc] init];
// 用户角色为听众，autoPlay 必须设为 NO。
songConfig.autoPlay = NO;
// 仅加载歌词。
songConfig.mode = KTVLoadMusicModeLoadLrcOnly;
songConfig.mainSingerUid = mainSingerUid;

[self.ktvApi loadMusicWithSongCode:songCode config:songConfig onMusicLoadStateListener:self];
// 歌曲加载失败回调。
- (void)onMusicLoadFailWithSongCode:(NSInteger)songCode reason:(enum KTVLoadSongFailReason)reason {
}
// 歌曲加载成功回调。
- (void)onMusicLoadSuccessWithSongCode:(NSInteger)songCode lyricUrl:(NSString * _Nonnull)lyricUrl {

}

// 歌曲加载进度回调。
- (void)onMusicLoadProgressWithSongCode:(NSInteger)songCode
                               percent:(NSInteger)percent
                                status:(AgoraMusicContentCenterPreloadStatus)status
                                   msg:(NSString *)msg
                              lyricUrl:(NSString *)lyricUrl {

}

3. 根据角色更新媒体选项

通过 updateChannelWithMediaOptions 方法在听众加入频道后更新频道媒体选项，例如是否开启本地音频采集，是否发布本地音频流等。

听众的用户角色为 AgoraClientRoleAudience，因此无法在频道内发布音频流。如果听众想上麦与独唱者语聊，需要将用户角色修改为 AgoraClientRoleBroadcaster。修改角色后，SDK 默认发布该连麦听众的音频流，独唱者和其他听众都能听到连麦听众的声音。

// 对需要上麦聊天的听众更新媒体选项。
AgoraRtcChannelMediaOptions* options = [AgoraRtcChannelMediaOptions new];
// 发布本地麦克风流。
options.publishMicrophoneTrack = YES;
// 启用音频采集和播放。
options.enableAudioRecordingOrPlayout = YES;
// 设置角色为主播。
options.clientRoleType = AgoraClientRoleBroadcaster;
// 更新媒体选项。
[self.RTCKit updateChannelWithMediaOptions:options];


// 对未上麦的听众更新媒体选项。
AgoraRtcChannelMediaOptions* options = [AgoraRtcChannelMediaOptions new];
// 不发布本地麦克风流。
options.publishMicrophoneTrack = NO;
// 启用音频采集和播放。
options.enableAudioRecordingOrPlayout = YES;
// 设置角色为观众。
options.clientRoleType = AgoraClientRoleAudience;
// 更新媒体选项。
[self.RTCKit updateChannelWithMediaOptions:options];

合唱

本节介绍如何实现合唱功能。独唱者点歌开唱，伴唱加入后独唱者成为领唱，K 歌房内的听众都可以听到合唱。房间内想与领唱或伴唱连麦语聊的听众可以上麦。

方案介绍

合唱场景下存在四种角色：

独唱者：在没有伴唱加入、伴唱中途退出后，演唱的人的用户角色为独唱者。独唱需加入频道，加载并播放歌曲，发布麦克风采集的音频流。KTV API 模块内部控制音乐播放器播放音乐，发布音乐到远端，将音乐播放进度同步到远端，让歌词组件进入歌词滚动状态等逻辑。
合唱中的领唱者：独唱者开始唱歌后，如有人加入合唱，独唱则成为合唱中的领唱者。领唱者需要加入频道 1，加载并播放歌曲，发布麦克风采集的音频流。此外，领唱还需要加入频道 2 将人声同步给伴唱。KTV API 模块内部控制音乐播放器播放音乐，同步领唱的音乐播放进度，让歌词组件进入歌词滚动状态等逻辑。
合唱中的伴唱：独唱者开始唱歌后，如有人加入合唱，则其成为合唱中的伴唱。伴唱需要加入频道 2，加载并播放歌曲，发布麦克风采集的音频流。KTV API 模块内部控制音乐播放器播放音乐，同步领唱的音乐播放进度，让歌词组件进入歌词滚动状态等逻辑。
听众：加入频道 1，加载歌词。KTV API 模块内部控制听众订阅领唱的人声和音乐的音频合流，订阅伴唱的人声，同步领唱的音乐播放进度，让歌词组件进入歌词滚动状态等逻辑。如果普通听众需要上麦聊天，可以更新媒体选项。

下图展示合唱的 API 调用时序图：

领唱实现

1. 加入频道

调用 joinChannelByToken 加入频道。为保证高音质，声网推荐你在加入频道前调用 SetAudioProfile 将音频编码属性设为 AgoraAudioProfileMusicHighQuality，调用 setAudioScenario 将音频场景设为 AgoraAudioScenarioGameStreaming。

// 加入频道
[self.rtcKit joinChannelByToken:<YOUR TOKEN>
                    channelId:<YOUR CHANNEL NAME>
                           info:nil
                            uid:<YOUR UID>
                   // 媒体选项，详见第 4 步操作。
                   mediaOptions:mediaOption
                   joinSuccess:nil];

2. 加载及播放歌曲

// 方案 1：加载歌曲后自动播放。
KTVSongConfiguration* songConfig = [[KTVSongConfiguration alloc] init];
songConfig.autoPlay = YES;
songConfig.mode = KTVLoadMusicModeLoadMusicAndLrc;
songConfig.mainSingerUid = mainSingerUid;

[self.ktvApi loadMusicWithSongCode:songCode config:songConfig onMusicLoadStateListener:self];

// 歌曲加载失败。
- (void)onMusicLoadFailWithSongCode:(NSInteger)songCode reason:(enum KTVLoadSongFailReason)reason {

}

// 歌曲加载成功。
- (void)onMusicLoadSuccessWithSongCode:(NSInteger)songCode lyricUrl:(NSString * _Nonnull)lyricUrl {

}

// 歌曲加载进度回调。
- (void)onMusicLoadProgressWithSongCode:(NSInteger)songCode
                               percent:(NSInteger)percent
                                status:(AgoraMusicContentCenterPreloadStatus)status
                                   msg:(NSString *)msg
                              lyricUrl:(NSString *)lyricUrl {

}

// 方案 2：autoPlay 设置为 NO 时, 歌曲加载成功后不会自动播放。
KTVSongConfiguration* songConfig = [[KTVSongConfiguration alloc] init];
songConfig.autoPlay = NO;
// 同时加载歌曲和歌词。
songConfig.mode = KTVLoadMusicModeLoadMusicAndLrc;
songConfig.mainSingerUid = mainSingerUid;
// 歌曲加载失败的原因。
- (void)onMusicLoadFailWithSongCode:(NSInteger)songCode reason:(enum KTVLoadSongFailReason)reason {

}
// 歌曲加载成功的回调，在此回调内调用 switchSingerRole 切换角色，调用 startSing 开始播放歌曲。
- (void)onMusicLoadSuccessWithSongCode:(NSInteger)songCode lyricUrl:(NSString * _Nonnull)lyricUrl {
    // 切换角色
    [weakSelf.ktvApi switchSingerRoleWithNewRole:KTVSingRoleSoloSinger
                               onSwitchRoleState:^(KTVSwitchRoleState state, KTVSwitchRoleFailReason reason) {
        // 切换角色状态回调。
    }];
    // 开始播放歌曲。
    [weakSelf.ktvApi startSingWithSongCode:songCode startPos:0];
}

[self.ktvApi loadMusicWithSongCode:songCode config:songConfig onMusicLoadStateListener:self];

// 歌曲加载进度回调。
- (void)onMusicLoadProgressWithSongCode:(NSInteger)songCode
                                percent:(NSInteger)percent
                                 status:(AgoraMusicContentCenterPreloadStatus)status
                                    msg:(NSString *)msg
                               lyricUrl:(NSString *)lyricUrl {

}

3. 切换角色

有人加入合唱成为伴唱时，独唱者需将其用户角色切换为领唱；最后一个伴唱者退出合唱时，领唱需将其用户角色切回独唱者；歌曲结束后，需将用户角色切为听众。

// 听众加入合唱成为伴唱，独唱者切换角色为领唱。
[self.ktvApi switchSingerRoleWithNewRole:KTVSingRoleLeadSinger
                               onSwitchRoleState:^(KTVSwitchRoleState state, KTVSwitchRoleFailReason reason) {
        }];
// 最后一个伴唱退出合唱，领唱切换角色为独唱。
[self.ktvApi switchSingerRoleWithNewRole:KTVSingRoleSoloSinger
                               onSwitchRoleState:^(KTVSwitchRoleState state, KTVSwitchRoleFailReason reason) {
        }];
// 歌曲结束后，将角色切换为听众。
[self.ktvApi switchSingerRoleWithNewRole:KTVSingRoleAudience
                               onSwitchRoleState:^(KTVSwitchRoleState state, KTVSwitchRoleFailReason reason) {
        }];

4. 根据角色更新媒体选项

通过 updateChannelWithMediaOptions 方法在主播加入频道后更新频道媒体选项，例如是否开启本地音频采集，是否发布本地音频流等。

AgoraRtcChannelMediaOptions* options = [AgoraRtcChannelMediaOptions new];
// 发布本地麦克风流
options.publishMicrophoneTrack = YES;
// 启用音频采集和播放
options.enableAudioRecordingOrPlayout = YES;
// 设置角色为主播
options.clientRoleType = AgoraClientRoleBroadcaster;
// 更新媒体选项
[self.RTCKit updateChannelWithMediaOptions:options];

伴唱实现

1. 加入频道

调用 joinChannelByToken 让伴唱加入频道。

// 加入频道
[self.rtcKit joinChannelByToken:<YOUR TOKEN>
                    channelId:<YOUR CHANNEL NAME>
                          info:nil
                           uid:<YOUR UID>
                 // 媒体选项，详见第 4 步操作。
                 mediaOptions:mediaOption
                 joinSuccess:nil];

2. 加载歌曲

听众加入合唱成为伴唱前，需调用 loadMusic 加载歌曲。歌曲加载完成后，调用 switchSingerRole 将用户角色设为伴唱（CoSinger）。

KTVSongConfiguration* songConfig = [[KTVSongConfiguration alloc] init];
// 不开启自动播放。
songConfig.autoPlay = NO;
// 仅加载歌曲。
songConfig.mode = KTVLoadMusicModeLoadMusicOnly;
songConfig.mainSingerUid = mainSingerUid;

[self.ktvApi loadMusicWithSongCode:songCode config:songConfig onMusicLoadStateListener:self];
// 歌曲加载失败。
- (void)onMusicLoadFailWithSongCode:(NSInteger)songCode reason:(enum KTVLoadSongFailReason)reason {

}
// 歌曲加载成功。
- (void)onMusicLoadSuccessWithSongCode:(NSInteger)songCode lyricUrl:(NSString * _Nonnull)lyricUrl {

    // 切换角色为伴唱。
    [weakSelf.ktvApi switchSingerRoleWithNewRole:KTVSingRoleCoSinger
                               onSwitchRoleState:^(KTVSwitchRoleState state, KTVSwitchRoleFailReason reason) {
        }];
}

3. 切换角色

当歌曲结束或伴唱想要中途退出合唱时，调用 switchSingerRole 将用户角色切换为听众。

[self.ktvApi switchSingerRoleWithNewRole:KTVSingRoleAudience
                      onSwitchRoleState:^(KTVSwitchRoleState state, KTVSwitchRoleFailReason reason) {
}];

4. 根据角色更新媒体选项

通过 updateChannelWithMediaOptions 方法在伴唱加入频道后更新频道媒体选项，例如是否开启本地音频采集，是否发布本地音频流等。

AgoraRtcChannelMediaOptions* options = [AgoraRtcChannelMediaOptions new];
// 发布本地麦克风流
options.publishMicrophoneTrack = YES;
// 启用音频采集和播放
options.enableAudioRecordingOrPlayout = YES;
// 设置角色为主播
options.clientRoleType = AgoraClientRoleBroadcaster;
// 更新媒体选项
[self.RTCKit updateChannelWithMediaOptions:options];

听众实现

1. 加入频道

调用 joinChannelByToken 让听众加入频道。

// 加入频道
[self.rtcKit joinChannelByToken:<YOUR TOKEN>
                    channelId:<YOUR CHANNEL NAME>
                           info:nil
                            uid:<YOUR UID>
                   // 媒体选项，详见第 xxx。
                   mediaOptions:mediaOption
                   joinSuccess:nil];

2. 加载歌词

调用 loadMusic 加载歌词。听众加入频道后，默认订阅领唱人声和音乐混合的音频流，默认订阅伴唱人声，因此只需要加载歌词。

KTVSongConfiguration* songConfig = [[KTVSongConfiguration alloc] init];
// 用户角色为听众，autoPlay 必须设为 NO。
songConfig.autoPlay = NO;
// 仅加载歌词。
songConfig.mode = KTVLoadMusicModeLoadLrcOnly;
songConfig.mainSingerUid = mainSingerUid;

[self.ktvApi loadMusicWithSongCode:songCode config:songConfig onMusicLoadStateListener:self];
// 加载失败。
- (void)onMusicLoadFailWithSongCode:(NSInteger)songCode reason:(enum KTVLoadSongFailReason)reason {

}
// 加载成功。
- (void)onMusicLoadSuccessWithSongCode:(NSInteger)songCode lyricUrl:(NSString * _Nonnull)lyricUrl {

}
// 报告加载进度。
- (void)onMusicLoadProgressWithSongCode:(NSInteger)songCode
                                percent:(NSInteger)percent
                                 status:(AgoraMusicContentCenterPreloadStatus)status
                                    msg:(NSString *)msg
                               lyricUrl:(NSString *)lyricUrl {

}

3. 根据角色更新媒体选项

通过 updateChannelWithMediaOptions 方法在听众加入频道后更新频道媒体选项，例如是否开启本地音频采集，是否发布本地音频流等。

听众的用户角色为 AgoraClientRoleAudience，因此无法在频道内发布音频流。如果听众想上麦与主唱/伴唱语聊，需要将用户角色修改为 AgoraClientRoleBroadcaster。修改角色后，SDK 默认发布该连麦听众的音频流，主唱、伴唱、其他听众都能听到连麦听众的声音。

// 对需要上麦聊天的听众更新媒体选项。
AgoraRtcChannelMediaOptions* options = [AgoraRtcChannelMediaOptions new];
// 发布本地麦克风流。
options.publishMicrophoneTrack = YES;
// 启用音频采集和播放。
options.enableAudioRecordingOrPlayout = YES;
// 设置角色为主播。
options.clientRoleType = AgoraClientRoleBroadcaster;
// 更新媒体选项。
[self.RTCKit updateChannelWithMediaOptions:options];


// 对未上麦的听众更新媒体选项。
AgoraRtcChannelMediaOptions* options = [AgoraRtcChannelMediaOptions new];
// 不发布本地麦克风流。
options.publishMicrophoneTrack = NO;
// 启用音频采集和播放。
options.enableAudioRecordingOrPlayout = YES;
// 设置角色为观众。
options.clientRoleType = AgoraClientRoleAudience;
// 更新媒体选项。
[self.RTCKit updateChannelWithMediaOptions:options];

抢唱

声网基于独唱推出抢唱功能，本节介绍如何实现副歌片段抢唱功能。

方案介绍

默认由房主播放副歌片段（播放的实现逻辑同独唱），听众可以上麦进行抢唱，抢到麦后房主停止播放，抢到麦的人播放副歌片段并进行独唱，K 歌房内的听众都可以听到其演唱。

抢唱场景下存在两种角色：

独唱者：加入频道，加载并播放歌曲。KTV API 模块内部控制音乐播放器播放音乐，发布音乐到远端，将音乐播放进度同步到远端，让歌词组件进入歌词滚动状态等逻辑。
听众：加入频道，加载歌词。KTV API 模块内部控制听众订阅独唱者的人声和音乐的音频合流，同步独唱者的音乐播放进度，让歌词组件进入歌词滚动状态等逻辑。如果听众需要上麦聊天，可以更新媒体选项。

下图展示抢唱的 API 调用时序图：

抢唱实现

与独唱方案相比，抢唱方案中仅需在 KTVApiConfig 中将 KTVType 设为 SingBattle（抢唱场景），独唱者实现和听众实现也仅在加载及播放这一步骤有差异。因此，你可以参考独唱方案来实现独唱者和听众逻辑。

加载及播放

在播放副歌片段之前，你需要先调用 getInternalSongCode 方法为该片段创建一个编号，作为该片段的唯一标识。当你获取到该片段的编号后，调用 loadMusic 并将获取到的副歌片段编号传入 songCode 参数来加载该副歌片段。

获取副歌片段总分

抢唱场景下的播放和演唱的音乐资源为副歌片段，你可以参考下列步骤来获取副歌片段的总分：

通过 onHighPartTime 回调获取副歌片段开始和结束时间。
调用歌词组件中的 parseLyricData 方法解析歌词文件数据，获取歌词数据模型。

通过歌词的行数来计算副歌片段的总分，示例代码如下：

  - (void)dealWithBattleSong:(LyricModel *)lyricsModel {
 // 确保传入的歌词模型不为空
 if (!lyricsModel) {
     return;
 }

 // 初始化行数计数器
 NSInteger lineCount = 0;

 // 遍历歌词数据模型中的每一行歌词
 for (NSInteger index = 0; index < lyricsModel.lines.count; index++) {
     // 获取当前歌词的行数
     LyricLine *line = lyricsModel.lines[index];

     // 检查当前歌词行的开始时间是否处于副歌片段开始和结束时间的范围内
     if (line.beginTime >= highStartTime && highEndTime >= line.beginTime + line.duration) {
         // 打印匹配的行信息，并增加行数计数
         NSLog(@"%ld -> s: %f, e: %f", (long)index, line.beginTime, line.beginTime + line.duration);
         lineCount++;
     }
 }

 // 总分=行数*100
 localTotalScore = lineCount * 100;
}

API 参考

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

这篇文章对你有帮助吗？

是

否