# 获取版权音乐 (/zh-CN/solutions/online-ktv/ktv-scenario/build/extend-karaoke/get-music) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). <_PlatformTabsGroup> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="android" /> 声网内容中心提供 K 歌热门曲库,涵盖大量正版歌曲、歌词等。本文分别介绍如何使用 KTV 场景化 API 及 RESTful API 获取声网内容中心提供的版权音乐并进行播放。 ## 前提条件 [#前提条件] - 已实现基本的在线 K 歌逻辑,详情请参考[快速集成 KTV API](/zh-CN/solutions/online-ktv/ktv-scenario/get-started/integrate-ktvapi)。 - 已联系[技术支持](https://ticket.shengwang.cn)开通版权音乐权限。 - 有效的声网项目,详情请参考[开通场景化 API 方案服务](/zh-CN/solutions/online-ktv/ktv-scenario/build/setup-and-access/enable-service)。 - 如果你使用场景化 API 获取版权音乐,需要获取项目的 RTM Token。 :::info[信息] - 加载版权音乐时声网使用 RTM Token 进行鉴权,不会产生云信令服务费用。 - 你可以参考[开通场景化 API 方案服务](/zh-CN/solutions/online-ktv/ktv-scenario/build/setup-and-access/enable-service)获取临时 RTM Token 用于测试,但在正式生产环境中,你需要自己部署一个 RTM Token 服务器来生成、更新 Token,详见[部署 RTM Token](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation)。 ::: - 如果你的网络环境部署了防火墙,请参考[应用企业防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。 ## 实现流程 [#实现流程] 本节介绍如何获取版权歌单、加载并播放版权音乐。 ### 1. 初始化设置 [#1-初始化设置] 调用 `createKTVApi` 创建并初始化 KTV API 实例时,确保 `KTVApiConfig` 中的 `musicType` 设为 `SONG_CODE`(表示使用声网音乐内容中心提供的版权音乐)并填入 RTM Token 进行鉴权。 ```kotlin // 创建并初始化 KTVAPI 模块 val ktvApiProtocol = createKTVApi( KTVApiConfig( // 你的 App ID "", // RTM Token,如果你使用的是本地的曲库而非声网提供的版权音乐,该参数可为空 "", mRtcEngine, // 需加入的频道名称 "", // 用户 ID "", // 合唱子频道的频道名,由外部指定 "", // 根据合唱子频道名和用户 ID 生成的 Token,用于加入该频道时鉴权 "" ), // 设置可缓存的音乐资源数量,最多不能超过 50 10, // 设置 K 歌的场景 KTVType.Normal, // 音乐资源类型,默认为声网音乐内容中心提供的版权音乐 KTVMusicType.SONG_CODE ) ``` :::info[信息] 当用于音乐内容中心鉴权的 RTM Token 即将过期时,你会收到 [onTokenPrivilegeWillExpire](/zh-CN/api-reference/online-ktv) 回调。你需要调用 `KTVApi` 下的 [renewToken](/zh-CN/api-reference/online-ktv) 来更新 Token。 ::: ### 2. 获取版权音乐 [#2-获取版权音乐] 针对场景化 API 方案,声网提供两种方式获取版权音乐:场景化 API 及 RESTful API。 #### 使用场景化 API 获取 [#使用场景化-api-获取] 调用 `searchMusicByKeyword` 通过关键词搜索歌曲,也可以调用 `fetchMusicCharts` 获取音乐榜单,然后再调用 `searchMusicByMusicChartId` 通过歌曲榜单的 ID 获取指定榜单的歌曲资源列表。 ```kotlin tab="用关键词搜索歌曲" // 用关键词搜索歌曲 fun searchSong(condition: String, page: Int) { val jsonOption = "{\"pitchType\":1,\"needLyric\":true}" // 搜索过滤条件。 ktvApiProtocol.searchMusicByKeyword(condition, page, 50, jsonOption) { requestId, status, page, pageSize, total, list -> // 回调内直接处理异步调用结果 } } ``` ```kotlin tab="获取音乐榜单" // 获取音乐榜单 fun fetchMusicCharts() { ktvApiProtocol.fetchMusicCharts() { requestId, status, list -> // 回调内直接处理异步调用结果 } } // 通过榜单号获取歌曲列表 fun searchSongWithRankingChartId(type: Int, page: Int) { val jsonOption = "{\"pitchType\":1,\"needLyric\":true}" // 过滤条件 ktvApiProtocol.searchMusicByMusicChartId(type, page, 50, jsonOption) { requestId, status, page, pageSize, total, list -> // 回调内直接处理异步调用结果 } } ``` :::warning[注意] 你可以通过 `jsonOption` 字段来筛选有副歌片段、支持打分的音乐资源。`jsonOption` 字段的具体说明见 [`searchMusicByKeyword`](/zh-CN/api-reference/online-ktv) 及 [`searchMusicByMusicChartId`](/zh-CN/api-reference/online-ktv) 的 API 文档。 ::: #### 使用 RESTful API 获取 [#使用-restful-api-获取] 参考下列步骤来使用 RESTful API 从声网内容中心获取版权音乐。 1. 实现 HTTP 认证 RESTful API 仅支持 HTTPS 协议。发送请求时,你需要通过 Basic HTTP 认证,并将生成的凭证填入 HTTP 请求头部的 `Authorization` 字段。具体生成 `Authorization` 字段的方法请参考[ HTTP 基本认证](/zh-CN/realtime-media/rtc/build/setup-and-access/http-basic-auth)。 2. 获取歌曲列表 根据你的需求调用不同的 RESTful API 来获取歌曲列表、热门榜单等,调用说明及示例详见 [API 文档](/zh-CN/api-reference/online-ktv)。 ### 3. 加载及播放版权音乐 [#3-加载及播放版权音乐] 成功获取版权音乐后,调用 `loadMusic`[1/2] 加载歌曲。该方法中你需要传入歌曲编号并进行歌曲加载配置。歌曲加载结果会通过 `IMusicLoadStateListener` 接口类下的回调通知你。在调用该方法时,你需要传入下列参数: - `songCode`:歌曲编号。如果你需要播放歌曲的副歌片段,需要先调用 `getInternalSongCode` 方法为该片段创建一个编号,作为该片段的唯一标识。当你获取到该片段的编号后,调用 `loadMusic`[1/2] 并将获取到的副歌片段编号传入 `songCode` 参数来加载该副歌片段。 - `config`:歌曲加载配置,包含下列参数: - `songIdentifier`:歌曲的唯一标识。如果你使用的是自行维护的曲库,你需要传入该参数,并需确保唯一性。如果你使用的是声网提供的版权音乐,向 `songCode` 传参即可,此参数传空。 - `mode`:歌曲加载的模式,默认为加载歌曲及歌词。 - `mainSingerUid`:独唱者的用户 ID。 - `IMusicLoadStateListener`:监听歌曲加载状态的接口类。 :::info[信息] 目前仅支持一次加载一首歌曲,请在一首歌曲加载完成后再加载下一首。 ::: ```kotlin // 下列示例代码以独唱者为例,展示如何加载、播放版权音乐 // 歌曲加载成功后需要在 onMusicLoadSuccess 回调内调用 switchSingerRole 切换用户角色为独唱者,再调用 startSing 开始演唱 ktvApiProtocol.loadMusic( songCode, KTVLoadMusicConfiguration(songId, mainSingerUid, KTVLoadMusicMode.LOAD_MUSIC_AND_LRC), object : IMusicLoadStateListener { override fun onMusicLoadSuccess(songCode: Long, lyricUrl: String) { // 歌曲加载成功后,调用 switchSingerRole 将用户角色设为独唱者 ktvApiProtocol.switchSingerRole(SoloSinger) // 开始唱歌 ktvApiProtocol.startSing(songCode, 0) } // 加载失败 override fun onMusicLoadFail(songCode: Long, reason: KTVLoadSongFailReason) { } // 报告加载进度 override fun onMusicLoadProgress( songCode: Long, percent: Int, status: MusicLoadStatus, msg: String?, lyricUrl: String? ) { } } ``` 如果你需要取消当前正在加载的版权音乐、或者清除已加载的缓存,可以调用 `removeMusic` 方法。 ```kotlin ktvApiProtocol.removeMusic(songCode) ``` ## API 参考 [#api-参考] 本节介绍获取版权音乐使用的 API: - [K 歌房场景化 API](/zh-CN/api-reference/online-ktv) - [RESTful API](/zh-CN/api-reference/online-ktv) ## 相关文档 [#相关文档] 本节介绍 K 歌方案的相关实现文档: - [快速集成 KTV API](/zh-CN/solutions/online-ktv/ktv-scenario/get-started/integrate-ktvapi) - [独唱](/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) - [歌词打分组件](/zh-CN/solutions/online-ktv/ktv-scenario/build/extend-karaoke/lyrics-scoring) <_PlatformProcessedMarker close="true" /> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="android" platform="ios" /> 声网内容中心提供 K 歌热门曲库,涵盖大量正版歌曲、歌词等。本文分别介绍如何使用 KTV 场景化 API 及 RESTful API 获取声网内容中心提供的版权音乐并进行播放。 ## 前提条件 [#前提条件-1] - 已实现基本的在线 K 歌逻辑,详情请参考[快速集成 KTV API](/zh-CN/solutions/online-ktv/ktv-scenario/get-started/integrate-ktvapi)。 - 已联系[技术支持](https://ticket.shengwang.cn)开通版权音乐权限。 - 有效的声网项目,详情请参考[开通场景化 API 方案服务](/zh-CN/solutions/online-ktv/ktv-scenario/build/setup-and-access/enable-service)。 - 如果你使用场景化 API 获取版权音乐,需要获取项目的 RTM Token。 :::info[信息] - 加载版权音乐时声网使用 RTM Token 进行鉴权,不会产生云信令服务费用。 - 你可以参考[开通场景化 API 方案服务](/zh-CN/solutions/online-ktv/ktv-scenario/build/setup-and-access/enable-service)获取临时 RTM Token 用于测试,但在正式生产环境中,你需要自己部署一个 RTM Token 服务器来生成、更新 Token,详见[部署 RTM Token](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation)。 ::: - 如果你的网络环境部署了防火墙,请参考[应用企业防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。 ## 实现流程 [#实现流程-1] 本节介绍如何获取版权歌单、加载并播放版权音乐。 ### 1. 初始化设置 [#1-初始化设置-1] 调用 `init` 初始化 KTV API 实例时,确保 `KTVApiConfig` 中的 `musicType` 设为 `loadMusicTypelocal`(表示使用声网音乐内容中心提供的版权音乐)并填入 RTM Token 进行鉴权。 ```objc KTVApiConfig *apiConfig = [[KTVApiConfig alloc]initWithAppId:[[AppContext shared] appId] // RTM Token,仅在使用声网版权音乐时需要填该参数 rtmToken:VLUserCenter.user.agoraRTMToken engine:self.RTCkit // 需加入的频道名称 channelName:@"" // 合唱子频道的频道名,由外部指定 chorusChannelName:@"" // 根据合唱子频道名和用户 ID 生成的 Token,用于加入该频道时鉴权 chorusChannelToken:@"" // 设置 K 歌的场景 type:KTVTypeNormal // 设置可缓存的音乐资源数量,最多不能超过 50 maxCacheSize:10 // 设置音乐资源类型为版权音乐 musicType:loadMusicTypelocal // mcc域名 mccDomain:nil]; [self.ktvApi loadMusicWithConfig:config url:@"Your music url"]; ``` :::info[信息] 当用于音乐内容中心鉴权的 RTM Token 即将过期时,你会收到 [onTokenPrivilegeWillExpire](/zh-CN/api-reference/online-ktv) 回调。你需要调用 `KTVApi` 下的 [renewToken](/zh-CN/api-reference/online-ktv) 来更新 Token。 ::: ### 2. 获取版权音乐 [#2-获取版权音乐-1] 针对场景化 API 方案,声网提供两种方式获取版权音乐:场景化 API 及 RESTful API。 #### 使用场景化 API 获取 [#使用场景化-api-获取-1] 你可以调用 `searchMusic`[2/2] 来通过关键词搜索歌曲,也可以调用 `fetchMusicCharts` 来获取音乐榜单,然后再调用 `searchMusic`[1/2] 来通过歌曲榜单的 ID 获取指定榜单的歌曲资源列表。 ```objc tab="通过关键词搜索歌曲" // 通过关键词搜索歌曲 - (void)loadSearchDataWithKeyWord:(NSString *)keyWord { NSDictionary *dict = @{ @"pitchType" : @(1), // 用来过滤没有歌词的歌曲 @"needLyric" : @(YES), }; NSString *extra = [NSString convertToJsonData:dict]; [self.ktvApi searchMusicWithKeyword:keyWord ? keyWord : @"" page:self.page pageSize:50 jsonOption:extra completion:^(NSString *_Nonnull, AgoraMusicContentCenterStatusCode, AgoraMusicCollection *_Nonnull){ }]; } ``` ```objc tab="获取榜单之前先要获取榜单 ID" // 获取榜单之前先要获取榜单 ID [self.ktvApi fetchMusicChartsWithCompletion:^(NSString *requestId, AgoraMusicContentCenterStatusCode code, NSArray *info){ }]; - (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]; // 根据榜单 ID 获取歌曲列表 [self.ktvApi searchMusicWithMusicChartId:chartId page:self.page pageSize:20 jsonOption:extra completion:^(NSString *_Nonnull, AgoraMusicContentCenterStatusCode, AgoraMusicCollection *_Nonnull){ //结果返回 }]; } ``` :::warning[注意] 你可以通过 `jsonOption` 字段来筛选有副歌片段、支持打分的音乐资源。`jsonOption` 字段的具体说明见 [`searchMusic`[1/2]](/zh-CN/api-reference/online-ktv) 及 [`searchMusic`[2/2]](/zh-CN/api-reference/online-ktv) 的 API 文档。 ::: #### 使用 RESTful API 获取 [#使用-restful-api-获取-1] 参考下列步骤来使用 RESTful API 从声网内容中心获取版权音乐。 1. 实现 HTTP 认证 RESTful API 仅支持 HTTPS 协议。发送请求时,你需要通过 Basic HTTP 认证,并将生成的凭证填入 HTTP 请求头部的 `Authorization` 字段。具体生成 `Authorization` 字段的方法请参考[ HTTP 基本认证](/zh-CN/realtime-media/rtc/build/setup-and-access/http-basic-auth)。 2. 获取歌曲列表 根据你的需求调用不同的 RESTful API 来获取歌曲列表、热门榜单等,调用说明及示例详见 [API 文档](/zh-CN/api-reference/online-ktv)。 ### 3. 加载及播放版权音乐 [#3-加载及播放版权音乐-1] 成功获取版权音乐后,调用 `loadMusic`[1/2] 加载歌曲。该方法中你需要传入歌曲编号并进行歌曲加载配置。歌曲加载结果会通过 `IMusicLoadStateListener` 接口类下的回调通知你。在调用 `loadMusic`[1/2] 时,你需要传入下列参数: - `songCode`:歌曲编号,可参考[步骤 2](/zh-CN/solutions/online-ktv/ktv-scenario/build/extend-karaoke/get-music)获取。如果你需要播放歌曲的副歌片段,需要先调用 `getInternalSongCode` 方法为该片段创建一个编号,作为该片段的唯一标识。当你获取到该片段的编号后,调用 `loadMusic` 并将获取到的副歌片段编号传入 `songCode` 参数来加载该副歌片段。 - `config`:歌曲加载配置,包含下列参数: - `songIdentifier`:歌曲的唯一标识。如果你使用的是自行维护的曲库,你需要传入该参数,并需确保唯一性。如果你使用的是声网提供的版权音乐,向 `songCode` 传参即可,此参数传空。 - `mode`:歌曲加载的模式,默认为加载歌曲及歌词。 - `mainSingerUid`:独唱者的用户 ID。 - `IMusicLoadStateListener`:监听歌曲加载状态的协议。 :::info[信息] 目前仅支持一次加载一首歌曲,请在一首歌曲加载完成后再加载下一首。 ::: ```objc // 下列示例代码以独唱者为例,展示如何加载、播放版权音乐 // 歌曲加载成功后需要在 onMusicLoadSuccess 回调内调用 switchSingerRole 切换用户角色为独唱者,再调用 startSing 开始演唱 KTVSongConfiguration *songConfig = [[KTVSongConfiguration alloc] init]; // 同时加载歌曲和歌词 songCode.songIdentifier = songIdentifier; 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 { } ``` 如果你需要取消当前正在加载的版权音乐、或者清除已加载的缓存,可以调用 `removeMusic` 方法。 ```objc [self.ktvApi removeMusicWithSongCode:songCode]; ``` ## API 参考 [#api-参考-1] 本节介绍获取及播放版权音乐使用的 API: - [K 歌房场景化 API](/zh-CN/api-reference/online-ktv) - [RESTful API](/zh-CN/api-reference/online-ktv) ## 相关文档 [#相关文档-1] - [快速集成 KTV API](/zh-CN/solutions/online-ktv/ktv-scenario/get-started/integrate-ktvapi) - [独唱](/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) - [歌词打分组件](/zh-CN/solutions/online-ktv/ktv-scenario/build/extend-karaoke/get-music) <_PlatformProcessedMarker close="true" />