# 快速集成 KTV API (/zh-CN/solutions/online-ktv/ktv-scenario/get-started/integrate-ktvapi/ios) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). KTV API 是声网为降低开发者的集成难度,为 K 歌房场景提供的场景化 API。KTV API 对声网实时互动 SDK 的 API 进行了一系列业务封装,提供出了 K 歌业务常见的业务功能接口,例如,获取版权歌单、下载版权音乐、切换演唱身份等。你只需要调用简单几个场景化 API 即可实现需要通过实时互动 API 才能实现的复杂代码逻辑,从而更轻松实现 K 歌场景。声网在 GitHub 上提供 KTV 场景化 API 的源码文件 [KTVApi.swift](https://github.com/AgoraIO-Community/KTVApi/blob/main/KTVAPI/iOS/Classes/KTVApi.swift) 和 [KTVApiImpl.swift](https://github.com/AgoraIO-Community/KTVApi/blob/main/KTVAPI/iOS/Classes/KTVApiImpl.swift) 供你参考。 在线 K 歌房内用户角色说明如下: | 角色 | 描述 | | :------- | :----------------------------------------------------------- | | 房主 | 歌房创建者。可以收、发音频流。 | |独唱|在没有伴唱加入、伴唱中途退出后,演唱的人的用户角色为独唱者。| | 主唱 | 如果有伴唱加入合唱,独唱成为主唱,可以收、发音频流。 | | 伴唱 | 独唱开始唱歌后,如有人加入合唱,则其成为合唱中的伴唱,可以收、发音频流。 | | 听众 | 进入歌房的倾听者,只能接收音频流。 | K 歌场景下主唱及独唱的业务流程图如下: ![独唱](https://web-cdn.agora.io/docs-portal/img/online-ktv/ktv-scenario-solo.png) 伴唱及听众的业务流程图如下: ![伴唱及观众](https://web-cdn.agora.io/docs-portal/img/online-ktv/ktv-scenario-audience.png) 本文介绍如何集成 KTV API 并实现在线 K 歌。 ## 前提条件 [#前提条件-1] 开始前,请确保你的开发环境满足以下条件: - Xcode 13.0 或以上版本。 - 已安装 [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started)。 - iOS 13.0 或以上版本的设备。 - 有效的声网开发者账号、声网项目,并获取项目的 App ID、RTC Token,详情请参考[开通场景化 API 方案服务](/zh-CN/solutions/online-ktv/ktv-scenario/build/setup-and-access/enable-service)。 :::info[信息] - 你可以参考[开通场景化 API 方案服务](/zh-CN/solutions/online-ktv/ktv-scenario/build/setup-and-access/enable-service)获取临时 Token 用于测试,但在正式生产环境中,你需要自己部署一个 Token 服务器来生成、更新 Token,详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。如果你使用了声网的版权音乐,你还需要使用 RTM Token,详见[部署 RTM Token](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation)。 - 如果你的网络环境部署了防火墙,请参考[应用企业防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。 ::: ## 集成 SDK 和 KTV API [#集成-sdk-和-ktv-api-1] 参考以下步骤来集成实时互动 SDK 和 KTV API: 1. 在终端里进入项目根目录,并运行 `pod init` 命令。项目文件夹下会生成一个 `Podfile` 文本文件。 2. 打开 `Podfile` 文件,修改文件为如下内容。注意将 `Your App` 替换为你的 Target 名称。 ```shell platform :ios, '9.0' target 'Your App' do pod 'AgoraRtcEngine_Special_iOS', '4.1.1.23' end ``` 3. 在终端内运行 `pod install` 命令安装声网 SDK。成功安装后,Terminal 中会显示 `Pod installation complete!` 4. 成功安装后,项目文件夹下会生成一个后缀为 `.xcworkspace` 的文件,通过 Xcode 打开该文件进行后续操作。 5. 在工程文件中引入 [KTVApi.swift](https://github.com/AgoraIO-Community/KTVApi/blob/main/KTVAPI/iOS/Classes/KTVApi.swift) 和 [KTVApiImpl.swift](https://github.com/AgoraIO-Community/KTVApi/blob/main/KTVAPI/iOS/Classes/KTVApiImpl.swift) 文件。 ## 实现在线 K 歌 [#实现在线-k-歌-1] 本节介绍使用 KTV API 实现在线 K 歌的基本逻辑。 ### 1. 创建并初始化 KTV API 模块 [#1-创建并初始化-ktv-api-模块-1] 1. 调用 [`sharedEngineWithAppId`](/zh-CN/api-reference/rtc/ios/initialize#api_irtcengine_create) 初始化 `AgoraRtcEngineKit`。请确保 `AgoraRtcEngineKit` 的生命周期大于 KTV API 模块的生命周期。 ```objc // 初始化 AgoraRtcEngineKit // self.RTCkit 是定义的 AgoraRtcEngineKit 全局变量 self.RTCkit = [AgoraRtcEngineKit sharedEngineWithAppId: delegate:self]; // 在独唱场景下,将音频应用场景设为 AgoraAudioScenarioGameStreaming,在合唱场景下设为 AgoraAudioScenarioChorus [self.RTCkit setAudioScenario:AgoraAudioScenarioGameStreaming]; [self.RTCkit setAudioProfile:AgoraAudioProfileMusicHighQuality]; [self.RTCkit setChannelProfile:AgoraChannelProfileLiveBroadcasting]; ``` 2. 调用 `createKTVApi` 创建并初始化 KTV API 实例。在[大合唱场景](/zh-CN/solutions/online-ktv/ktv-scenario/build/implementation/grand-chorus)下,你需要调用 `createKTVGiantChorusApi` 来创建大合唱场景下的 KTV API 实例。 ```objc tab="大合唱场景" tabGroup="create" // 创建 GiantChorusConfiguration 实例 GiantChorusConfiguration *config = [[GiantChorusConfiguration alloc] init]; config.appId = @""; config.rtmToken = @""; config.engine = self.RTCkit; config.channelName = @""; config.localUid = ; config.chorusChannelName = @""; config.chorusChannelToken = @""; config.maxCacheSize = 10; config.musicType = loadMusicTypeMcc; config.audienceChannelToken = @""; config.musicStreamUid = 0; config.musicChannelToken = @""; config.routeSelectionConfig = [[GiantChorusRouteSelectionConfig alloc] initWithType:GiantChorusRouteSelectionTypeByDelay streamNum:6]; config.mccDomain = nil; // 创建实例 self.ktvApi = [self createKTVGiantChorusApiWithConfig:config]; ``` ```objc tab="其他场景" tabGroup="create" // 创建 KTVApiConfig 实例 KTVApiConfig *apiConfig = [[KTVApiConfig alloc] initWithAppId:@"" // RTM Token,如果你使用的是本地的曲库而非声网提供的版权音乐,该参数可为空 rtmToken:@"" engine:self.RTCkit // 需加入的频道的名称 channelName:@"" // 用户 ID localUid:@"" // 合唱子频道的频道名,由外部指定 chorusChannelName:@"" // 根据频合唱子频道名和用户 ID 生成的 Token,用于加入该频道时鉴权 chorusChannelToken:@"" // 设置 K 歌的场景 type:KTVTypeNormal // 设置可缓存的音乐资源数量,最多不能超过 50 maxCacheSize:10 // 设置音乐资源类型,默认为声网音乐内容中心提供的版权音乐 musicType:loadMusicTypeMcc // 音乐内容中心域名,可传空 mccDomain:nil]; self.ktvApi = [[KTVApiImpl alloc] initWithConfig:apiConfig]; ``` :::info[信息] - 当用于加入主频道的 Token 即将过期前,你会收到 `IRtcEngineEventHandler` 类下的 [`onTokenPrivilegeWillExpire`](/zh-CN/api-reference/rtc/ios/channel#callback_irtcengineeventhandler_ontokenprivilegewillexpire) 回调,你需要调用 `IRtcEngine` 下的 [`renewToken`](/zh-CN/api-reference/rtc/ios/channel#renewtoken) 来更新 Token。 - 如需更新加入合唱子频道的 Token,[KTVApi](/zh-CN/api-reference/online-ktv) 下的 `renewToken` 来更新 Token。 - 如果你使用了声网的版权音乐,当用于鉴权的 RTM Token、用于加入合唱子频道的 Token 即将过期时,你会收到 [onTokenPrivilegeWillExpire](/zh-CN/api-reference/online-ktv) 回调。如需更新 RTM Token,你需要调用 `KTVApi` 下的 [renewToken](/zh-CN/api-reference/online-ktv) 来更新 Token。 ::: ### 2. 订阅事件回调 [#2-订阅事件回调-1] 调用 `addEventHandler` 订阅 KTV API 事件,KTV API 模块支持订阅多个事件。如果你需要取消订阅事件,可调用 `removeEventHandler` 方法。 ```objc // 订阅 KTVAPI 事件 [self.ktvapi addEventHandlerWithKtvApiEventHandler:self]; // 取消订阅 KTVAPI 事件 [self.ktvApi removeEventHandlerWithKtvApiEventHandler:self]; ``` ### 3. 同步数据流 [#3-同步数据流-1] 为同步频道内的歌词进度等状态信息,你需要在调用 `joinChannelByToken`[2/4] 成功加入频道后调用 `renewInnerDataStreamId` 来创建数据流通道。一个频道中最多只能创建 **5 个**数据流通道。 ```objc // 更新数据流 ID [self.ktvApi renewInnerDataStreamId]; ``` :::warning[注意] 如果退出频道后再次加入频道,你需要在加入频道成功后重新调用 `renewInnerDataStreamId` 来创建数据流通道。 ::: ### 4. 加载及播放歌曲 [#4-加载及播放歌曲-1] 声网提供正版版权音乐库,如需加载版权歌单,请参考[获取版权音乐](/zh-CN/solutions/online-ktv/ktv-scenario/build/extend-karaoke/get-music)。声网也支持加载你自己本地的歌曲曲库。你可以调用 `loadMusic`[2/2] 来加载并播放你本地的音乐文件。 ```objc KTVSongConfiguration *songConfig = [[KTVSongConfiguration alloc] init]; songConfig.songIdentifier = songIdentifier; songConfig.mode = KTVLoadMusicModeLoadLrcMusicAndLrc; songConfig.mainSingerUid = mainSingerUid; // 通过 url 加载本地音乐 [self.ktvApi loadMusicWithConfig:config url:@"Your music url"]; ``` :::info[信息] 目前仅支持一次加载一首歌曲,请在一首歌曲加载完成后再加载下一首。 ::: ### 5. 切换角色 [#5-切换角色-1] KTV API 初始化时默认用户角色为听众,如果需要开始独唱或加入合唱,需要调用 `switchSingerRole` 来切换至相应的角色。 KTV API 内部会根据角色的切换来控制演唱过程中音乐播放器的播放、同步,以及订阅和发布音频流的行为。你还可以通过 `onSingerRoleChanged` 回调来获取切换的状态。 请参考下图来进行角色切换: ![](https://web-cdn.agora.io/docs-files/1704340396791) ```objc [self.ktvApi switchSingerRoleWithNewRole:role // 通过闭包 onSwitchRoleState 返回切换角色的状态和失败原因。 onSwitchRoleState:^(KTVSwitchRoleState state, KTVSwitchRoleFailReason reason) { if (state == KTVSwitchRoleStateFail && reason != KTVSwitchRoleFailReasonNoPermission) { return; } }]; // 角色已切换回调。 - (void)onSingerRoleChangedWithOldRole:(KTVSingRole)oldRole newRole:(KTVSingRole)newRole { } ``` ### 6. 监听并控制歌曲播放 [#6-监听并控制歌曲播放-1] 歌曲播放时,音乐播放器会通过 `onMusicPlayerStateChanged` 回调向业务层通知歌曲播放状态改变。收到 `onMusicPlayerStateChanged(AgoraMediaPlayerStateOpenCompleted)` 回调后,你可以使用 `seekSing`、`pauseSing`、`resumeSing` 等方法控制播放器。 :::warning[注意] KTV API 模块内部会自动处理播放器同步,因此你也可以通过 `onMusicPlayerStateChanged` 回调获取远端播放器的状态。 ::: ```objc // 跳转到指定时间播放歌曲 [self.ktvApi seekSing: time]; ``` ### 7. 释放资源 [#7-释放资源] 退出 K 歌场景时,你需要调用 `cleanCache` 释放 KTV API 模块内的资源和取消注册事件回调。请确保 `AgoraRtcEngineKit` 的生命周期大于 KTV API 模块。释放资源时,请在释放 KTV API 模块之后再释放 `AgoraRtcEngineKit`。 ```objc // 先释放 KTV API 模块资源 [self.ktvApi cleanCache]; // 再销毁 RtcEngine 实例 [AgoraRtcEngineKit destroy]; ``` 下图展示 KTV API 的调用时序图: 实现上述基本的业务逻辑后,你可以根据你实际的业务场景,选择[独唱](/zh-CN/solutions/online-ktv/ktv-scenario/build/implementation/solo)、[合唱](/zh-CN/solutions/online-ktv/ktv-scenario/build/implementation/chorus)、[大合唱](/zh-CN/solutions/online-ktv/ktv-scenario/build/implementation/grand-chorus)、[抢唱](/zh-CN/solutions/online-ktv/ktv-scenario/build/implementation/gaming)或[接唱](/zh-CN/solutions/online-ktv/ktv-scenario/build/implementation/relay)方案。 ## 相关信息 [#相关信息-1] 本节介绍集成 KTV API 的其他相关信息和文档。 ### 获取歌曲进度和音高信息 [#获取歌曲进度和音高信息-1] 1. 为实时获取歌曲进度、人声音高等信息来渲染歌词及音高线,你的歌词组件类需要继承 `KTVLrcViewDelegate`,并实现该类中的回调。 ```objc class LrcView: KTVLrcViewDelegate { func onUpdatePitch(pitch: Float) { // 人声音高回调,每 20 ms 更新一次 } func onUpdateProgress(progress: Int) { // 歌词播放进度回调,每 20 ms 更新一次 } func onDownloadLrcData(url: String) { // 此处可以下载歌词文件 } func onHighPartTime(highStartTime: Int, highEndTime: Int) { // 当你播放的是歌曲副歌片段时,会触发该回调报告副歌片段的起始和结束时间 } } ``` 2. 调用 `setLrcView` 方法将你的歌词组件对象传递给 KTV API 模块。 ### API 参考 [#api-参考-1] 本文集成步骤中使用如下 API: - [K 歌房场景化 API](/zh-CN/api-reference/online-ktv) - [实时互动 API](/zh-CN/api-reference/online-ktv) ### 相关文档 [#相关文档-1] - [独唱](/zh-CN/solutions/online-ktv/ktv-scenario/build/implementation/solo) - [合唱](/zh-CN/solutions/online-ktv/ktv-scenario/build/implementation/chorus) - [抢唱](/zh-CN/solutions/online-ktv/ktv-scenario/build/implementation/gaming) - [接唱](/zh-CN/solutions/online-ktv/ktv-scenario/build/implementation/relay)