From 5f9b5f04ebaf510dcabaddfa04453641b5465017 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Fri, 28 Jul 2023 11:09:57 +0800 Subject: [PATCH 01/28] add description about scoring and default log directory for ios --- ...350\257\215\347\273\204\344\273\266API.md" | 2 ++ ...73\266\345\256\236\347\216\260-Android.md" | 20 +++++++++++++------ ...44\273\266\345\256\236\347\216\260-iOS.md" | 10 +++++++++- 3 files changed, 25 insertions(+), 7 deletions(-) diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\347\273\204\344\273\266/API/iOS-\346\255\214\350\257\215\347\273\204\344\273\266API.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\347\273\204\344\273\266/API/iOS-\346\255\214\350\257\215\347\273\204\344\273\266API.md" index 84078a781ee..b3a7f81ebb4 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\347\273\204\344\273\266/API/iOS-\346\255\214\350\257\215\347\273\204\344\273\266API.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\347\273\204\344\273\266/API/iOS-\346\255\214\350\257\215\347\273\204\344\273\266API.md" @@ -234,6 +234,8 @@ func getLineScore(with toneScores: [ToneScoreModel]) -> Int 该协议提供日志相关的 API。 +
默认情况下，储存歌词打分组件日志的沙盒路径为 AppData/Documents/Logs。
+ ### onLog `KaraokeView` 的日志回调。 diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\347\273\204\344\273\266/\345\256\236\347\216\260/\347\273\204\344\273\266\345\256\236\347\216\260-Android.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\347\273\204\344\273\266/\345\256\236\347\216\260/\347\273\204\344\273\266\345\256\236\347\216\260-Android.md" index c9976e30f57..766c74a20d2 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\347\273\204\344\273\266/\345\256\236\347\216\260/\347\273\204\344\273\266\345\256\236\347\216\260-Android.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\347\273\204\344\273\266/\345\256\236\347\216\260/\347\273\204\344\273\266\345\256\236\347\216\260-Android.md" @@ -1,6 +1,6 @@ -声网歌词打分组件（KaraokeView）包含歌词组件（LyricsView）和打分组件（ScoringView）。在 K 歌房场景中，你可以通过歌词组件实现歌曲播放时歌词同步展示以及自定义歌词界面，通过打分组件实现根据当前播放进度展示对应的原唱音准线、展示演唱者和原唱音准线的匹配效果、演唱者的分数、自定义打分逻辑以及评分组件界面。 + 声网歌词打分组件（KaraokeView）包含歌词组件（LyricsView）和打分组件（ScoringView）。在 K 歌房场景中，你可以通过歌词组件实现歌曲播放时歌词同步展示以及自定义歌词界面，通过打分组件实现根据当前播放进度展示对应的原唱音准线、展示演唱者和原唱音准线的匹配效果、演唱者的分数、自定义打分逻辑以及评分组件界面。 -本文介绍如何在项目中集成并使用声网歌词组件。 +本文介绍如何在项目中集成并使用声网歌词打分组件。
本文仅适用于歌词打分组件 v1.1.1。
@@ -18,6 +18,10 @@ +下图展示歌词打分组件的 API 调用时序： + +![](https://web-cdn.agora.io/docs-files/1687164357039) + ## 前提条件 在使用歌词组件前，请确保你已在项目中集成声网视频 SDK v4.x，并实现在线 K 歌功能，详见[客户端实现](https://docs.agora.io/cn/online-ktv/chorus_client_android?platform=Android)。 @@ -49,10 +53,6 @@ 本节介绍如何实现歌词组件。 -参考如下歌词打分组件的 API 调用时序图： - -![](https://web-cdn.agora.io/docs-files/1687164357039) - ### 声明和初始化 在项目的 Activity 中，声明和初始化歌词、打分组件对象。示例代码如下： @@ -166,6 +166,14 @@ mKaraokeView.setKaraokeEvent(new KaraokeEvent() { ## 实现打分组件 +每一行歌词演唱完毕后，你可以通过打分组件获取该行歌词的演唱得分以及目前的累计得分，每一行歌词的总分为 100 分。整首歌曲演唱完毕后，打分组件会将每一行歌词的演唱得分累加，计算整首歌曲的演唱得分。你可以根据你的业务场景来将歌曲最终的演唱评分进行换算。 + +歌曲总分 = 每一行歌词的总分 (100) * 歌词总行数 + +整首歌曲演唱得分比率 = 每一行歌词累计演唱得分 / 歌曲总分 + +本节介绍如何实现打分组件。 + ### 同步人声音调 当演唱者开始唱歌，你可以通过 `RtcEngine` 下的 [onAudioVolumeIndication](https://docportal.shengwang.cn/cn/online-ktv/API%20Reference/java_ng/API/toc_audio_process.html?platform=Android#callback_irtcengineeventhandler_onaudiovolumeindication) 来获取本地用户的人声音调，然后通过 `setPitch` 来将用户实时的人声音调同步给打分组件。 diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\347\273\204\344\273\266/\345\256\236\347\216\260/\347\273\204\344\273\266\345\256\236\347\216\260-iOS.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\347\273\204\344\273\266/\345\256\236\347\216\260/\347\273\204\344\273\266\345\256\236\347\216\260-iOS.md" index fb1dd138092..69ed2b57642 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\347\273\204\344\273\266/\345\256\236\347\216\260/\347\273\204\344\273\266\345\256\236\347\216\260-iOS.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\347\273\204\344\273\266/\345\256\236\347\216\260/\347\273\204\344\273\266\345\256\236\347\216\260-iOS.md" @@ -1,6 +1,6 @@ 声网歌词打分组件（KaraokeView）包含歌词组件（LyricsView）和打分组件（ScoringView）。在 K 歌房场景中，你可以通过歌词组件实现歌曲播放时歌词同步展示以及自定义歌词界面，通过打分组件实现根据当前播放进度展示对应的原唱音准线、展示演唱者和原唱音准线的匹配效果、演唱者的分数、自定义打分逻辑以及打分组件界面。 -本文介绍如何在项目中集成并使用声网歌词和打分组件。 +本文介绍如何在项目中集成并使用声网歌词打分组件。
本文仅适用于歌词打分组件 v1.1.1。
@@ -146,6 +146,14 @@ public class LyricsView: UIView { ## 实现打分组件 +每一行歌词演唱完毕后，你可以通过打分组件获取该行歌词的演唱得分以及目前的累计得分，每一行歌词的总分为 100 分。整首歌曲演唱完毕后，打分组件会将每一行歌词的演唱得分累加，计算整首歌曲的演唱得分。你可以根据你的业务场景来将歌曲最终的演唱评分进行换算。 + +歌曲总分 = 每一行歌词的总分 (100) * 歌词总行数 + +整首歌曲演唱得分比率 = 每一行歌词累计演唱得分 / 歌曲总分 + +本节介绍如何实现打分组件。 + ### 同步人声音调 当演唱者开始唱歌，你可以通过 `AgoraRtcEngineDelegate` 下的 [reportAudioVolumeIndicationOfSpeakers](https://docportal.shengwang.cn/cn/online-ktv/API%20Reference/ios_ng/API/toc_audio_process.html?platform=iOS#callback_irtcengineeventhandler_onaudiovolumeindication) 来获取本地用户的人声音调，然后通过 `setPitch` 来将用户实时的人声音调同步给打分组件。 From 02b6cfff00c7b17e85210fb88f42322ab4268be8 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Thu, 3 Aug 2023 15:14:30 +0800 Subject: [PATCH 02/28] =?UTF-8?q?=E6=8A=A2=E5=94=B1=E8=8E=B7=E5=8F=96?= =?UTF-8?q?=E5=88=86=E6=95=B0=EF=BC=8850%=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../\351\233\206\346\210\220.md" | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" index 966cb322881..533c7a4874c 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" @@ -100,7 +100,7 @@ ); ``` -
+
### 2. 获取歌曲列表 @@ -288,6 +288,8 @@ ktvApiProtocol.loadMusic(songCode, KTVLoadMusicConfiguration(false, "歌曲开始演唱后，你还可以通过声网的歌词打分组件来根据当前歌曲播放进度展示对应的歌词，获取演唱者的分数，详见歌词打分组件。 + #### 3. 歌曲结束 当歌曲播放完成或切歌后，你需要调用 `switchSingerRole` 将用户的角色切回听众。 @@ -450,6 +452,8 @@ ktvApiProtocol.loadMusic(songCode, KTVLoadMusicConfiguration(false, "歌曲开始演唱后，你还可以通过声网的歌词打分组件来根据当前歌曲播放进度展示对应的歌词，获取演唱者的分数，详见歌词打分组件。 + #### 3. 切换角色 有人加入合唱成为伴唱时，独唱者需将其用户角色切换为领唱；最后一个伴唱者退出合唱时，领唱需将其用户角色切回独唱者；歌曲结束后，需将用户角色切为听众。 @@ -515,6 +519,8 @@ ktvApiProtocol.loadMusic(songCode, KTVLoadMusicConfiguration(false, "歌曲开始演唱后，你还可以通过声网的歌词打分组件来根据当前歌曲播放进度展示对应的歌词，获取演唱者的分数，详见歌词打分组件。 + #### 3. 切换角色 当歌曲结束或伴唱想要中途退出合唱时，调用 `switchSingerRole` 将用户角色切换为听众。 @@ -623,12 +629,16 @@ mRtcEngine.updateChannelMediaOptions(channelMediaOption) ### 抢唱实现 -与独唱方案相比，抢唱方案中，仅需在 `KTVApiConfig` 中将 `KTVType` 设为 `SingBattle`（抢唱场景），独唱者实现和听众实现也仅在加载及播放这一步骤有差异。因此，你可以参考[独唱方案](#solo)来实现独唱者和听众逻辑。 +与独唱方案相比，抢唱方案中，仅需在 `KTVApiConfig` 中将 `KTVType` 设为 `SingBattle`（抢唱场景），独唱者实现和听众实现也仅在加载及播放、获取歌曲总分这两步有差异。因此，你可以参考[独唱方案](#solo)来实现独唱者和听众逻辑。 #### 加载及播放 在播放副歌片段之前，你需要先调用 `getInternalSongCode` 方法为该片段创建一个编号，作为该片段的唯一标识。当你获取到该片段的编号后，调用 `loadMusic` 并将获取到的副歌片段编号传入 `songCode` 参数来加载该副歌片段。 +#### 获取副歌片段总分 + + + ## API 参考 本文集成步骤中使用如下 API： From fb86990f08334ce2edbed5d7bcd482592dae0d35 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Thu, 3 Aug 2023 16:49:33 +0800 Subject: [PATCH 03/28] draft to be reviewed --- .../\351\233\206\346\210\220.md" | 24 +++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" index 533c7a4874c..411792ca58b 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" @@ -7,8 +7,6 @@
  • 在使用场景化 API 方案前，请联系技术支持开通权限。
  • 本文仅适用于 K 歌场景化 API v3.0.0。
- - ## 前提条件 开始前，请确保你的开发环境满足以下条件： @@ -637,7 +635,29 @@ mRtcEngine.updateChannelMediaOptions(channelMediaOption) #### 获取副歌片段总分 +抢唱场景下的播放和演唱的音乐资源为副歌片段，你可以参考下列步骤来获取副歌片段的总分： + +1. 通过 `onHighPartTime` 回调获取副歌片段开始和结束时间。 + +2. 调用 [parseLyricsData](https://docportal.shengwang.cn/cn/online-ktv/lyrics_scores_android?platform=Android#parselyricsdata) 解析歌词文件数据，获取歌词数据模型。 +3. 通过歌词的行数来计算副歌片段的总分，示例代码如下： + + ```kotlin + // 变量，用于保存副歌片段的总分 + int totalScore = 0; + // 计数器，用于统计处于副歌片段开始和结束时间之间的歌词行数 + AtomicInteger lineCount = new AtomicInteger(); + // 遍历歌词数据模型中的每一行歌词，检查每行歌词是否处于副歌片段开始和结束时间的范围内 + lyricsModel.lines.forEach(line -> { + if (line.getStartTime() >= highStartTime && line.getEndTime() <= highEndTime) { + // 计算出处于开始和结束时间之间的歌词行数 + lineCount.getAndIncrement(); + } + }); + // 总分=行数*100 + totalScore = lineCount.get() * 100; + ``` ## API 参考 From 7082c13c68698a1f9c78794c3258459b607cdde6 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Wed, 9 Aug 2023 15:36:35 +0800 Subject: [PATCH 04/28] =?UTF-8?q?=E9=AB=98=E6=BD=AE=E7=89=87=E6=AE=B5?= =?UTF-8?q?=E6=80=BB=E5=88=86+jsonoption?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...257\345\214\226 Kotlin API for Android.md" | 37 +++-- .../\351\233\206\346\210\220.md" | 26 ++-- ...57\345\214\226 Objective-C API for iOS.md" | 72 +++++++--- .../\351\233\206\346\210\220.md" | 134 ++++++++++++++---- 4 files changed, 195 insertions(+), 74 deletions(-) diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Kotlin API for Android.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Kotlin API for Android.md" index 7e926d0f46b..d6342fc6a2e 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Kotlin API for Android.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Kotlin API for Android.md" @@ -1,4 +1,4 @@ -本文提供在线 K 歌房场景定制化 Kotlin API。你可以在 GitHub 上查看源码文件 [KTVApi.kt](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v2.3.1-Android/Android/scenes/ktv/src/main/java/io/agora/scene/ktv/live/KTVApi.kt) 和 [KTVApiImpl.kt](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v2.3.1-Android/Android/scenes/ktv/src/main/java/io/agora/scene/ktv/live/KTVApiImpl.kt)。 +本文提供在线 K 歌房场景定制化 Kotlin API。你可以在 GitHub 上查看源码文件 [KTVApi.kt](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v3.0.0-all-Android/Android/scenes/ktv/src/main/java/io/agora/scene/ktv/live/KTVApi.kt) 和 [KTVApiImpl.kt](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v3.0.0-all-Android/Android/scenes/ktv/src/main/java/io/agora/scene/ktv/live/KTVApiImpl.kt)。
本文适用于 K 歌场景化 API v3.0.0。
@@ -139,7 +139,15 @@ fun searchMusicByMusicChartId( - `musicChartId`：歌曲榜单 ID，可通过 `fetchMusicCharts` 获取。 - `page`：当前页面编号，默认从 1 开始。 - `pageSize`：每页所展示的音乐资源的最大数量，最大值为 50。 -- `jsonOption`：扩展 JSON 字段，可依据特殊需要进行定制，默认为 `NULL`。 +- `jsonOption`：扩展 JSON 字段，默认为 `NULL`。你可以通过该字段来筛选出你需要的音乐资源，目前支持筛选可打分的音乐资源及音乐资源的副歌片段： + + | **Key 值** | **Value 值** | **示例** | + | ------------ | ------------------------------------------------------------ | --------------------- | + | pitchType | 是否支持打分：
  • 1：支持打分的音乐资源。
  • 2：不支持打分的音乐资源。
| {"pitchType":1} | + | needHighPart | 是否需要副歌片段资源：
  • `true`：需要副歌片段资源。
  • `false`：不需要副歌片段资源。
| {"needHighPart":true} | + + + - `onMusicCollectionResultListener`：获取歌曲资源列表回调，包含以下参数： - `requestId`：请求 ID。本次请求的唯一标识。 - `status`：请求状态。 @@ -184,9 +192,19 @@ fun searchMusicByKeyword( #### 参数 - `keyword`：搜索关键词，支持歌曲名、歌手搜索。 + - `page`：想要获取的音乐资源列表的目标页编号。 + - `pageSize`：每页所展示的音乐资源的最大数量，最大值为 50。 -- `jsonOption`：扩展 JSON 字段，可依据特殊需要进行定制，默认为 `NULL`。 + +- `jsonOption`：扩展 JSON 字段，默认为 `NULL`。你可以通过该字段来筛选出你需要的音乐资源，目前支持筛选可打分的音乐资源及音乐资源的副歌片段： + + | **Key 值** | **Value 值** | **示例** | + | ------------ | ------------------------------------------------------------ | --------------------- | + | pitchType | 是否支持打分：
  • 1：支持打分的音乐资源。
  • 2：不支持打分的音乐资源。
| {"pitchType":1} | + | needHighPart | 是否需要副歌片段资源：
  • `true`：需要副歌片段资源。
  • `false`：不需要副歌片段资源。
| {"needHighPart":true} | + + - `onMusicCollectionResultListener`：获取歌曲资源列表回调，包含以下参数： - `requestId`：请求 ID。本次请求的唯一标识。 - `status`：请求状态。 @@ -198,12 +216,6 @@ fun searchMusicByKeyword( - 网络错误。请检查你的网络。 - 3：权限错误或歌曲不存在。请确保你的项目已开通声网音乐内容中心权限。 - 4：内部数据解析错误。 - - 5：歌曲加载时出错。 - - 6：歌曲解密时出错。 - - `page`：当前页面编号，默认从 1 开始。 - - `pageSize`：当前歌曲资源列表的总页面数量，最大值为 50。 - - `total`：列表内歌曲资源的总数量。 - - `list`：[`Music`](https://docportal.shengwang.cn/cn/online-ktv/API%20Reference/java_ng/API/class_music.html) 对象数组，包含歌曲的详细信息。 ### loadMusic [1/2] @@ -414,6 +426,7 @@ fun renewInnerDataStreamId()
由于每个频道中最多只能创建 5 个数据流，因此请勿再一个频道内多次调用该方法。
+ ## ILrcView 该类提供歌词组件的相关回调。在调用 `setLrcView` 设置歌词控制视图时，你需要继承此接口类并实现其下的方法。 @@ -426,7 +439,7 @@ fun onUpdatePitch(pitch: Float?) 人声音调更新回调。 -你需要实现该回调来获取实时的人声音调传递给 KTV API 内部，便于打分组件使用。 +当人声音调更新时，会触发该回调将音调值同步给歌词评分组件。 #### 参数 @@ -438,7 +451,7 @@ fun onUpdatePitch(pitch: Float?) fun onUpdateProgress(progress: Long?) ``` -当歌曲播放进度更新时，会触发该回调报告歌曲的实时播放进度。该回调每 50 ms 触发一次。 +当歌曲播放进度更新时，会触发该回调将歌曲的实时进度同步给歌词评分组件。该回调每 50 ms 触发一次。 #### 参数 @@ -460,6 +473,7 @@ fun onDownloadLrcData(url: String?) - `url`：歌词的下载地址。 + ## IMusicLoadStateListener @@ -662,6 +676,7 @@ enum class KTVLoadSongFailReason(val value: Int) { - `CANCELED`：(2) 歌曲加载因出现错误而终止。 ### KTVSwitchRoleFailReason + ```kotlin diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" index 411792ca58b..ecd99538717 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" @@ -1,6 +1,6 @@ ## 概述 -为降低开发者的集成难度，声网为 K 歌房场景提供了场景化 API。场景化 API 封装了声网音视频 SDK 的 API，并提供了 K 歌业务常见的功能，例如，对领唱和伴唱进行 NTP 时间同步。你只需要调用一个场景化 API 即可实现通过多个音视频 SDK 的 API 完成的复杂代码逻辑，从而更轻松实现 K 歌场景。声网在 GitHub 上提供 KTV 场景化 API 的源码文件 [KTVApi.kt](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v2.3.1-Android/Android/scenes/ktv/src/main/java/io/agora/scene/ktv/live/KTVApi.kt) 和 [KTVApiImpl.kt](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v2.3.1-Android/Android/scenes/ktv/src/main/java/io/agora/scene/ktv/live/KTVApiImpl.kt)。 +为降低开发者的集成难度，声网为 K 歌房场景提供了场景化 API。场景化 API 封装了声网音视频 SDK 的 API，并提供了 K 歌业务常见的功能，例如，对领唱和伴唱进行 NTP 时间同步。你只需要调用一个场景化 API 即可实现通过多个音视频 SDK 的 API 完成的复杂代码逻辑，从而更轻松实现 K 歌场景。声网在 GitHub 上提供 KTV 场景化 API 的源码文件 [KTVApi.kt](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v3.0.0-all-Android/Android/scenes/ktv/src/main/java/io/agora/scene/ktv/live/KTVApi.kt) 和 [KTVApiImpl.kt](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v3.0.0-all-Android/Android/scenes/ktv/src/main/java/io/agora/scene/ktv/live/KTVApiImpl.kt)。 本文介绍如何使用 KTV 场景化 API 实现点歌、独唱、合唱等基础业务功能。 @@ -29,7 +29,7 @@ 参考以下步骤来配置项目： 1. 参考项目配置集成所需 SDK。 -2. 在工程文件中引入 [KTVApi.kt](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v2.3.1-Android/Android/scenes/ktv/src/main/java/io/agora/scene/ktv/live/KTVApi.kt) 和 [KTVApiImpl.kt](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v2.3.1-Android/Android/scenes/ktv/src/main/java/io/agora/scene/ktv/live/KTVApiImpl.kt) 文件。 +2. 在工程文件中引入 [KTVApi.kt](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v3.0.0-all-Android/Android/scenes/ktv/src/main/java/io/agora/scene/ktv/live/KTVApi.kt) 和 [KTVApiImpl.kt](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v3.0.0-all-Android/Android/scenes/ktv/src/main/java/io/agora/scene/ktv/live/KTVApiImpl.kt) 文件。 ## 点歌 @@ -98,7 +98,11 @@ ); ``` -
+
+
    +
  • 当用于音乐内容中心的 RTM Token、用于加入频道 2 的 Token 即将过期时，你会收到 onTokenPrivilegeWillExpire 回调。
    • 如需更新 RTM Token，你需要先调用 KTVApi 下的 getMusicContentCenter 获取音乐内容中心实例，再调用 KTVApi 下的 renewToken 来更新 Token。
      • +
    • 如需更新加入频道 2 的 Token，直接调用 KTVApi 下的 renewToken 来更新 Token。
    +
  • 当用于加入频道 1 的 Token 即将过期前，你会收到 IRtcEngineEventHandler 类下的 onTokenPrivilegeWillExpire 回调，你需要调用 IRtcEngine 下的 renewToken 来更新 Token。
### 2. 获取歌曲列表 @@ -134,11 +138,13 @@ fun searchSongWithRankingChartId(type: Int, page: Int) { } ``` +
你可以通过 jsonOption 字段来筛选有副歌片段、支持打分的音乐资源。jsonOption 字段的具体说明见 searchMusicByKeyword 及 searchMusicByMusicChartId 的 API 文档。
+ ### 3. 加载及播放歌曲 调用 `loadMusic` 加载歌曲。该方法中你需要传入歌曲编号并进行歌曲加载配置。歌曲加载结果会通过 `IMusicLoadStateListener` 接口类下的回调通知你。在调用 `loadMusic` 时，你需要传入下列参数： -- `songCode`：歌曲编号，可参考[步骤 2](#步骤2)获取。 +- `songCode`：歌曲编号，可参考[步骤 2](#步骤2)获取。如果你需要播放歌曲的副歌片段，需要先调用 `getInternalSongCode` 方法为该片段创建一个编号，作为该片段的唯一标识。当你获取到该片段的编号后，调用 `loadMusic` 并将获取到的副歌片段编号传入 `songCode` 参数来加载该副歌片段。 - `config`：歌曲加载配置，包含下列参数： - `autoPlay`：歌曲加载完成后是否自动播放 - `true`：自动播放歌曲，此时用户角色会自动切换为独唱者。 @@ -286,8 +292,6 @@ ktvApiProtocol.loadMusic(songCode, KTVLoadMusicConfiguration(false, "歌曲开始演唱后，你还可以通过声网的歌词打分组件来根据当前歌曲播放进度展示对应的歌词，获取演唱者的分数，详见歌词打分组件。 - #### 3. 歌曲结束 当歌曲播放完成或切歌后，你需要调用 `switchSingerRole` 将用户的角色切回听众。 @@ -450,8 +454,6 @@ ktvApiProtocol.loadMusic(songCode, KTVLoadMusicConfiguration(false, "歌曲开始演唱后，你还可以通过声网的歌词打分组件来根据当前歌曲播放进度展示对应的歌词，获取演唱者的分数，详见歌词打分组件。 - #### 3. 切换角色 有人加入合唱成为伴唱时，独唱者需将其用户角色切换为领唱；最后一个伴唱者退出合唱时，领唱需将其用户角色切回独唱者；歌曲结束后，需将用户角色切为听众。 @@ -517,8 +519,6 @@ ktvApiProtocol.loadMusic(songCode, KTVLoadMusicConfiguration(false, "歌曲开始演唱后，你还可以通过声网的歌词打分组件来根据当前歌曲播放进度展示对应的歌词，获取演唱者的分数，详见歌词打分组件。 - #### 3. 切换角色 当歌曲结束或伴唱想要中途退出合唱时，调用 `switchSingerRole` 将用户角色切换为听众。 @@ -627,8 +627,9 @@ mRtcEngine.updateChannelMediaOptions(channelMediaOption) ### 抢唱实现 -与独唱方案相比，抢唱方案中，仅需在 `KTVApiConfig` 中将 `KTVType` 设为 `SingBattle`（抢唱场景），独唱者实现和听众实现也仅在加载及播放、获取歌曲总分这两步有差异。因此，你可以参考[独唱方案](#solo)来实现独唱者和听众逻辑。 +与独唱方案相比，抢唱方案中仅需在 `KTVApiConfig` 中将 `KTVType` 设为 `SingBattle`（抢唱场景），独唱者实现和听众实现也仅在[加载及播放](#play)这一步骤有差异。因此，你可以参考[独唱方案](#solo)来实现独唱者和听众逻辑。 + #### 加载及播放 在播放副歌片段之前，你需要先调用 `getInternalSongCode` 方法为该片段创建一个编号，作为该片段的唯一标识。当你获取到该片段的编号后，调用 `loadMusic` 并将获取到的副歌片段编号传入 `songCode` 参数来加载该副歌片段。 @@ -639,7 +640,7 @@ mRtcEngine.updateChannelMediaOptions(channelMediaOption) 1. 通过 `onHighPartTime` 回调获取副歌片段开始和结束时间。 -2. 调用 [parseLyricsData](https://docportal.shengwang.cn/cn/online-ktv/lyrics_scores_android?platform=Android#parselyricsdata) 解析歌词文件数据，获取歌词数据模型。 +2. 调用歌词组件中的 [parseLyricsData](https://docportal.shengwang.cn/cn/online-ktv/lyrics_scores_android?platform=Android#parselyricsdata) 方法解析歌词文件数据，获取歌词数据模型。 3. 通过歌词的行数来计算副歌片段的总分，示例代码如下： @@ -659,6 +660,7 @@ mRtcEngine.updateChannelMediaOptions(channelMediaOption) totalScore = lineCount.get() * 100; ``` + ## API 参考 本文集成步骤中使用如下 API： diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Objective-C API for iOS.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Objective-C API for iOS.md" index 5d21eb8582a..7075c5f7ea1 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Objective-C API for iOS.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Objective-C API for iOS.md" @@ -1,4 +1,4 @@ -本文提供在线 K 歌房场景定制化 Objective-C API。你可以在 GitHub 上查看源码文件 [KTVApiDelegate](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/feat/scene/ktv_2.3.1_ios/iOS/AgoraEntScenarios/Scenes/KTV/KTVAPI/KTVApiDelegate.swift) 和 [KTVApiImpl](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/feat/scene/ktv_2.3.1_ios/iOS/AgoraEntScenarios/Scenes/KTV/KTVAPI/KTVApiImpl.swift)。 +本文提供在线 K 歌房场景定制化 Objective-C API。你可以在 GitHub 上查看源码文件 [KTVApi](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v3.0.0-all-iOS/iOS/AgoraEntScenarios/Scenes/KTV/KTVAPI/KTVApi.swift) 和 [KTVApiImpl](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v3.0.0-all-iOS/iOS/AgoraEntScenarios/Scenes/KTV/KTVAPI/KTVApiImpl.swift)。 ## KTVApiDelegate @@ -121,7 +121,15 @@ func searchMusic(musicChartId: Int, - `musicChartId`：歌曲榜单 ID，可通过 `fetchMusicCharts` 获取。 - `page`：当前页面编号，默认从 1 开始。 - `pageSize`：当前音乐资源列表的总页面数量，最大值为 50。 -- `jsonOption`：扩展 JSON 字段，可依据特殊需要进行定制，默认为 `Nil`。 +- `jsonOption`：扩展 JSON 字段，默认为 `Nil`。你可以通过该字段来筛选出你需要的音乐资源，目前支持筛选可打分的音乐资源及音乐资源的副歌片段： + + | **Key 值** | **Value 值** | **示例** | + | ------------ | ------------------------------------------------------------ | --------------------- | + | pitchType | 是否支持打分：
  • 1：支持打分的音乐资源。
  • 2：不支持打分的音乐资源。
| {"pitchType":1} | + | needHighPart | 是否需要副歌片段资源：
  • `true`：需要副歌片段资源。
  • `false`：不需要副歌片段资源。
| {"needHighPart":true} | + + + - `completion`：获取指定榜单的歌曲列表回调。该闭包在函数执行完成后仍然可以被调用。回调闭包接受一个 `MusicResultCallBacks` 对象作为参数，用于获取歌曲列表。 ### searchMusic [2/2] @@ -140,7 +148,15 @@ func searchMusic(keyword: String, - `keyword`：搜索关键词，支持歌曲名、歌手搜索。 - `page`：想要获取的音乐资源列表的目标页编号。 - `pageSize`：每页所展示的音乐资源的最大数量，最大值为 50。 -- `jsonOption`：扩展 JSON 字段，可依据特殊需要进行定制，默认为 `Nil`。 +- `jsonOption`：扩展 JSON 字段，默认为 `Nil`。你可以通过该字段来筛选出你需要的音乐资源，目前支持筛选可打分的音乐资源及音乐资源的副歌片段： + + | **Key 值** | **Value 值** | **示例** | + | ------------ | ------------------------------------------------------------ | --------------------- | + | pitchType | 是否支持打分：
  • 1：支持打分的音乐资源。
  • 2：不支持打分的音乐资源。
| {"pitchType":1} | + | needHighPart | 是否需要副歌片段资源：
  • `true`：需要副歌片段资源。
  • `false`：不需要副歌片段资源。
| {"needHighPart":true} | + + + - `completion`：获取指定歌曲的回调。该闭包在函数执行完成后仍然可以被调用。回调闭包接受一个 `MusicResultCallBacks` 对象作为参数，用于获取歌曲资源。 ### loadMusic [1/2] @@ -275,7 +291,7 @@ func setMicStatus(isOnMicOpen: Bool) - `isOnMicOpen`：当前麦克风的开关状态： - `true`：麦克风开启。 - - `false`：麦克风关闭。 + - `false`：（默认）麦克风关闭。 ### setLrcView @@ -353,7 +369,7 @@ func onUpdatePitch(pitch: Float) func onUpdateProgress(progress: Int) ``` -当歌曲播放进度更新时，会触发该回调报告歌曲的实时播放进度。该回调每 50 ms 触发一次。 +当歌曲播放进度更新时，会触发该回调将歌曲的实时进度同步给歌词评分组件。该回调每 50 ms 触发一次。 #### 参数 @@ -377,7 +393,7 @@ func onDownloadLrcData(url: String) ## IMusicLoadStateListener - + 该接口类提供歌曲加载状态的相关回调。 @@ -431,7 +447,7 @@ func onMusicLoadProgress(songCode: Int, percent: Int, status: AgoraMusicContentC ## KTVApiEventHandlerDelegate - + 该协议提供 K 歌场景的核心回调。 @@ -474,13 +490,6 @@ func onSingerRoleChanged(oldRole: KTVSingRole, newRole: KTVSingRole) - `oldRole`：切换前的用户角色，详见 [KTVSingRole](#KTVSingRole)。 - `newRole`：切换后的用户角色，详见 [KTVSingRole](#KTVSingRole)。 -### onSingingScoreResult - -```objective-c -func onSingingScoreResult(score: Float) -``` - -//TODO ### onTokenPrivilegeWillExpire @@ -517,7 +526,7 @@ func onChorusChannelAudioVolumeIndication( ### KTVSingRole - + ```objc public enum KTVSingRole: Int { @@ -527,6 +536,7 @@ public enum KTVSingRole: Int { case audience } ``` + K 歌用户角色类型： - `SoloSinger`：独唱者。 @@ -536,7 +546,7 @@ K 歌用户角色类型： ### KTVLoadSongFailReason - + ```objective-c public enum KTVLoadSongFailReason: Int { @@ -570,7 +580,7 @@ public enum KTVSwitchRoleFailReason: Int { ### KTVLoadMusicMode - + ```objective-c public enum KTVLoadMusicMode: Int { @@ -599,14 +609,32 @@ public enum KTVLoadSongState: Int { ``` 歌曲加载的状态： + - `idle`: 空闲状态，未加载歌曲。 - `ok`: 加载成功。 - `failed`: 加载失败。 - `inProgress`: 正在加载中。 +### KTVType + + + +```objective-c +@objc public enum KTVType: Int { + case normal + case singbattle +} +``` + +K 歌的场景： + +- `Normal`：独唱、合唱场景。 +- `SingBattle`：抢唱场景。 + + ## Class - + ### KTVApiConfig @@ -619,6 +647,7 @@ public enum KTVLoadSongState: Int { var localUid: Int = 0 var chorusChannelName: String var chorusChannelToken: String + var type: KTVType = .normal var maxCacheSize: Int = 10 @objc public init(appId: String, @@ -628,6 +657,7 @@ public enum KTVLoadSongState: Int { localUid: Int, chorusChannelName: String, chorusChannelToken: String, + type: KTVType, maxCacheSize: Int ) { self.appId = appId @@ -637,10 +667,10 @@ public enum KTVLoadSongState: Int { self.localUid = localUid self.chorusChannelName = chorusChannelName self.chorusChannelToken = chorusChannelToken + self.type = type self.maxCacheSize = maxCacheSize } } - ``` K 歌配置： @@ -661,11 +691,13 @@ K 歌配置： - `chorusChannelToken`：合唱场景下，根据频道 2 的名称和用户 ID 生成的 Token，用于加入频道 2 时进行鉴权。在独唱场景下，该参数可以为空。 +- `type`：K 歌场景，详见 [KTVType](#KTVType)。 + - `maxCacheSize`：可缓存的音乐资源数量，最多不能超过 50。 ### KTVSongConfiguration - + ```objective-c open class KTVSongConfiguration: NSObject { diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" index b9a683982bd..ffede8fecef 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" @@ -1,10 +1,10 @@ ## 概述 -为降低开发者的集成难度，声网为 K 歌房场景提供了场景化 API。场景化 API 封装了声网音视频 SDK 的 API，并提供了 K 歌业务常见的功能，例如，对主唱和伴唱进行 NTP 时间同步。你只需要调用一个场景化 API 即可实现通过多个音视频 SDK 的 API 完成的复杂代码逻辑，从而更轻松实现 K 歌场景。声网在 GitHub 上提供 KTV 场景化 API 的源码文件 [KTVApiDelegate](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/feat/scene/ktv_2.3.1_ios/iOS/AgoraEntScenarios/Scenes/KTV/KTVAPI/KTVApiDelegate.swift) 和 [KTVApiImpl](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/feat/scene/ktv_2.3.1_ios/iOS/AgoraEntScenarios/Scenes/KTV/KTVAPI/KTVApiImpl.swift)。 +为降低开发者的集成难度，声网为 K 歌房场景提供了场景化 API。场景化 API 封装了声网音视频 SDK 的 API，并提供了 K 歌业务常见的功能，例如，对主唱和伴唱进行 NTP 时间同步。你只需要调用一个场景化 API 即可实现通过多个音视频 SDK 的 API 完成的复杂代码逻辑，从而更轻松实现 K 歌场景。声网在 GitHub 上提供 KTV 场景化 API 的源码文件 [KTVApi](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v3.0.0-all-iOS/iOS/AgoraEntScenarios/Scenes/KTV/KTVAPI/KTVApi.swift) 和 [KTVApiImpl](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v3.0.0-all-iOS/iOS/AgoraEntScenarios/Scenes/KTV/KTVAPI/KTVApiImpl.swift)。
  • 在使用场景化 API 方案前，请联系技术支持开通权限。
    • -
  • 本文仅适用于 K 歌场景化 API v2.3.1。
+
  • 本文仅适用于 K 歌场景化 API v3.0.0。
    • 本文介绍如何使用 KTV 场景化 API 实现点歌、独唱、合唱等基础业务功能。 @@ -25,7 +25,7 @@ 参考一下步骤来配置项目： 1. 参考项目配置集成所需 SDK。 -2. 在工程文件中引入 [KTVApiDelegate](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/feat/scene/ktv_2.3.1_ios/iOS/AgoraEntScenarios/Scenes/KTV/KTVAPI/KTVApiDelegate.swift) 和 [KTVApiImpl](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/feat/scene/ktv_2.3.1_ios/iOS/AgoraEntScenarios/Scenes/KTV/KTVAPI/KTVApiImpl.swift)。 +2. 在工程文件中引入 [KTVApi](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v3.0.0-all-iOS/iOS/AgoraEntScenarios/Scenes/KTV/KTVAPI/KTVApi.swift) 和 [KTVApiImpl](https://github.com/AgoraIO-Usecase/agora-ent-scenarios/blob/v3.0.0-all-iOS/iOS/AgoraEntScenarios/Scenes/KTV/KTVAPI/KTVApiImpl.swift)。 ## 点歌 @@ -53,30 +53,37 @@ 2. 创建 KTV API 实例，并初始化 API 模块。调用 `addEventHandler` 注册 KTV API 事件。调用 KTV API 模块的 API 前，请确保已初始化 KTV API 实例。 - ```objective-c - // 你的 App ID - KTVApiConfig *apiConfig = [[KTVApiConfig alloc] initWithAppId:@"" - // RTM Token - rtmToken:@"" - engine:self.RTCkit - // - channelName:@"" - // 加入频道 1 所使用的用户 ID - localUid:@"" - // 频道 2 的名称，详见合唱方案介绍。 - chorusChannelName:@"" - // 根据频道 2 的名称和用户 ID 生成的 Token，用于加入频道 2 时进行鉴权。 - chorusChannelToken:@""]; - - self.ktvApi = [[KTVApiImpl alloc] initWithConfig:apiConfig]; - - // 注册 KTVAPI 事件 - [self.ktvApi addEventHandlerWithKtvApiEventHandler:self]; - ``` -
    +```objective-c + // 创建 KTVApiConfig 实例 +KTVApiConfig *apiConfig = [[KTVApiConfig alloc] initWithAppId:@"" + rtmToken:@"" + engine:self.RTCkit + channelName:@"" + localUid:@"" + chorusChannelName:@"" + chorusChannelToken:@"" + // 设置 K 歌的场景。 + type:KTVTypeNormal + // 设置可缓存的音乐资源数量，最多不能超过 50。 + maxCacheSize:10]; + +self.ktvApi = [[KTVApiImpl alloc] initWithConfig:apiConfig]; + +// 更新数据流 ID。一个频道中最多只能创建 5 个数据流。 +[self.ktvApi renewInnerDataStreamId]; + +// 注册 KTVAPI 事件。 +[self.ktvApi addEventHandlerWithKtvApiEventHandler:self]; +``` -### 2. 获取歌曲列表 +
    +
      +
    • 当用于音乐内容中心的 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. 获取歌曲列表 通过关键词搜索或音乐榜单获取歌曲列表。 @@ -124,11 +131,13 @@ } ``` +
    你可以通过 jsonOption 字段来筛选有副歌片段、支持打分的音乐资源。jsonOption 字段的具体说明见 searchMusic[1/2] 及 searchMusic[2/2] 的 API 文档。
    + ### 3. 加载及播放歌曲 调用 `loadMusic` 加载歌曲。该方法中你需要传入歌曲编号并进行歌曲加载配置。歌曲加载结果会通过 `IMusicLoadStateListener` 接口类下的回调通知你。在调用 `loadMusic` 时，你需要传入下列参数： -- `songCode`：歌曲编号，可参考[步骤 2](#步骤2)获取。 +- `songCode`：歌曲编号，可参考[步骤 2](#步骤2)获取。如果你需要播放歌曲的副歌片段，需要先调用 `getInternalSongCode` 方法为该片段创建一个编号，作为该片段的唯一标识。当你获取到该片段的编号后，调用 `loadMusic` 并将获取到的副歌片段编号传入 `songCode` 参数来加载该副歌片段。 - `config`：歌曲加载配置，包含下列参数： @@ -264,11 +273,12 @@ KTV API 初始化时默认用户角色为听众，如果需要开始独唱或加 下图展示独唱的 API 调用时序图： ![](https://web-cdn.agora.io/docs-files/1684489750503) + ### 独唱者实现 #### 1. 加入频道 -调用 [`joinChannelByToken`](https://docs.agora.io/cn/online-ktv/API%20Reference/ios_ng/API/toc_core_method.html#api_irtcengine_joinchannel2) 让主唱加入频道。为保证高音质，声网推荐你在加入频道前调用 [`SetAudioProfile`](https://docportal.shengwang.cn/cn/online-ktv/API%20Reference/ios_ng/API/toc_audio_process.html?platform=iOS#api_irtcengine_setaudioprofile2) 将音频编码属性设为 `AgoraAudioProfileMusicHighQuality`，调用 [`setAudioScenario`](https://docportal.shengwang.cn/cn/online-ktv/API%20Reference/ios_ng/API/toc_audio_process.html#api_irtcengine_setaudioscenario) 将音频场景设为 `AgoraAudioScenarioGameStreaming`。 +调用 [`joinChannelByToken`](https://docs.agora.io/cn/online-ktv/API%20Reference/ios_ng/API/toc_core_method.html#api_irtcengine_joinchannel2) 让独唱者加入频道。为保证高音质，声网推荐你在加入频道前调用 [`SetAudioProfile`](https://docportal.shengwang.cn/cn/online-ktv/API%20Reference/ios_ng/API/toc_audio_process.html?platform=iOS#api_irtcengine_setaudioprofile2) 将音频编码属性设为 `AgoraAudioProfileMusicHighQuality`，调用 [`setAudioScenario`](https://docportal.shengwang.cn/cn/online-ktv/API%20Reference/ios_ng/API/toc_audio_process.html#api_irtcengine_setaudioscenario) 将音频场景设为 `AgoraAudioScenarioGameStreaming`。 ```objective-c // 加入频道 @@ -359,7 +369,7 @@ songConfig.mainSingerUid = mainSingerUid; #### 4. 关闭麦克风 -主唱停止唱歌或希望暂时关闭麦克风时，可以调用 [`adjustRecordingSignalVolume`](https://docs.agora.io/cn/online-ktv/API%20Reference/ios_ng/API/toc_audio_process.html#api_irtcengine_adjustrecordingsignalvolume)，将音频采集信号音量设置为 0。 +独唱者停止唱歌或希望暂时关闭麦克风时，可以调用 [`adjustRecordingSignalVolume`](https://docs.agora.io/cn/online-ktv/API%20Reference/ios_ng/API/toc_audio_process.html#api_irtcengine_adjustrecordingsignalvolume)，将音频采集信号音量设置为 0。 ```objective-c [self.RTCKit adjustRecordingSignalVolume:0]; @@ -717,7 +727,7 @@ songConfig.mainSingerUid = mainSingerUid; #### 3. 根据角色更新媒体选项 -通过 [`updateChannelWithMediaOptions`](https://docs.agora.io/cn/online-ktv/API%20Reference/ios_ng/API/toc_core_method.html#api_irtcengine_updatechannelmediaoptions) 方法在听众加入频道后更新频道媒体选项，例如是否开启本地音频采集，是否发布本地音频流等。 +通过 [`updateChannelWithMediaOptions`](/cn/online-ktv/API%20Reference/ios_ng/API/toc_core_method.html#api_irtcengine_updatechannelmediaoptions) 方法在听众加入频道后更新频道媒体选项，例如是否开启本地音频采集，是否发布本地音频流等。 听众的用户角色为 `AgoraClientRoleAudience`，因此无法在频道内发布音频流。如果听众想上麦与主唱/伴唱语聊，需要将用户角色修改为 `AgoraClientRoleBroadcaster`。修改角色后，SDK 默认发布该连麦听众的音频流，主唱、伴唱、其他听众都能听到连麦听众的声音。 @@ -746,9 +756,71 @@ options.clientRoleType = AgoraClientRoleAudience; [self.RTCKit updateChannelWithMediaOptions:options]; ``` +## 抢唱 + +声网基于独唱推出抢唱功能，本节介绍如何实现副歌片段抢唱功能。 + +### 方案介绍 + +默认由房主播放副歌片段（播放的实现逻辑同独唱），听众可以上麦进行抢唱，抢到麦后房主停止播放，抢到麦的人播放副歌片段并进行独唱，K 歌房内的听众都可以听到其演唱。 + +抢唱场景下存在两种角色： + +独唱者：加入频道，加载并播放歌曲。KTV API 模块内部控制音乐播放器播放音乐，发布音乐到远端，将音乐播放进度同步到远端，让歌词组件进入歌词滚动状态等逻辑。 +听众：加入频道，加载歌词。KTV API 模块内部控制听众订阅独唱者的人声和音乐的音频合流，同步独唱者的音乐播放进度，让歌词组件进入歌词滚动状态等逻辑。如果听众需要上麦聊天，可以更新媒体选项。 + +下图展示抢唱的 API 调用时序图： +![](https://web-cdn.agora.io/docs-files/1688614425839) + +### 抢唱实现 + +与独唱方案相比，抢唱方案中仅需在 `KTVApiConfig` 中将 `KTVType` 设为 `SingBattle`（抢唱场景），独唱者实现和听众实现也仅在[加载及播放](#play)这一步骤有差异。因此，你可以参考[独唱方案](#solo)来实现独唱者和听众逻辑。 + + +#### 加载及播放 + +在播放副歌片段之前，你需要先调用 `getInternalSongCode` 方法为该片段创建一个编号，作为该片段的唯一标识。当你获取到该片段的编号后，调用 `loadMusic` 并将获取到的副歌片段编号传入 `songCode` 参数来加载该副歌片段。 + +#### 获取副歌片段总分 + +抢唱场景下的播放和演唱的音乐资源为副歌片段，你可以参考下列步骤来获取副歌片段的总分： + +1. 通过 `onHighPartTime` 回调获取副歌片段开始和结束时间。 +2. 调用歌词组件中的 [parseLyricData](https://docs-preprod.agora.io/cn/online-ktv/lyrics_scores_ios?platform=iOS#parselyricdata) 方法解析歌词文件数据，获取歌词数据模型。 +3. 通过歌词的行数来计算副歌片段的总分，示例代码如下： + + ```objective-c + - (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： -- [RTC API](/cn/online-ktv/API%20Reference/ios_ng/API/rtc_api_overview_ng.html) -- [场景化 API](https://docs-preprod.agora.io/cn/online-ktv/ktv_api_oc?platform=iOS) \ No newline at end of file +- [RTC API](https://docportal.shengwang.cn/cn/online-ktv/API%20Reference/ios_ng/API/rtc_api_overview_ng.html) +- [场景化 API](https://docportal.shengwang.cn/cn/online-ktv/ktv_api_oc?platform=iOS) \ No newline at end of file From d8f33b4c3e059609a297439e4bb92ed4dbfee555 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Fri, 25 Aug 2023 15:52:31 +0800 Subject: [PATCH 05/28] android 3.3.0 --- ...257\345\214\226 Kotlin API for Android.md" | 35 +++++++++++++++++-- .../\351\233\206\346\210\220.md" | 11 +++--- 2 files changed, 39 insertions(+), 7 deletions(-) diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Kotlin API for Android.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Kotlin API for Android.md" index d6342fc6a2e..75e93a3db75 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Kotlin API for Android.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Kotlin API for Android.md" @@ -7,6 +7,16 @@ 该类提供实现 K 歌场景的核心方法。 +### create + +```kotlin +fun createKTVApi(): KTVApi = KTVApiImpl() +``` + +创建 KTV API 实例。 + +请确保在调用本方法成功创建 KTV API 实例后，再调用 `initialize` 进行初始化。 + ### initialize ```kotlin @@ -637,6 +647,22 @@ open fun onChorusChannelAudioVolumeIndication( ## Enum class +### KTVMusicType + + + +```kotlin +enum class KTVMusicType(val value: Int) { + SONG_CODE(0), + SONG_URL(1) +} +``` + +音乐资源类型： + +- `SONG_CODE`：（默认）声网内容中心提供的版权音乐。 +- `SONG_URL`：本地歌曲。 + ### KTVSingRole @@ -751,7 +777,7 @@ K 歌的场景： ### KTVApiConfig ```kotlin -data class KTVApiConfig( +data class KTVApiConfig constructor( val appId: String, val rtmToken: String, val engine: RtcEngine, @@ -759,8 +785,9 @@ data class KTVApiConfig( val localUid: Int, val chorusChannelName: String, val chorusChannelToken: String, - val maxCacheSize: Int = 10, - val type: KTVType = KTVType.Normal + val maxCacheSize: Int = 10, + val type: KTVType = KTVType.Normal, + val musicType: KTVSongType = KTVSongType.SONG_CODE ) ``` @@ -786,6 +813,8 @@ K 歌配置： - `type`：K 歌场景，详见 [KTVType](#KTVType)。 +- `musicType`：音乐资源类型，详见 [KTVSongType](#KTVSongType)。 + ### KTVLoadMusicConfiguration diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" index ecd99538717..4591585615b 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" @@ -60,12 +60,13 @@ val mRtcEngine = RtcEngine.create(config) as RtcEngineEx ``` -2. 调用 `initialize` 初始化 KTV API 实例，调用 `addEventHandler` 注册 KTV API 事件。调用 KTV API 模块的 API 前，请确保已调用 `initialize` 初始化 KTV API 实例。 +2. 调用 `createKTVApi` 创建 KTV API 实例，调用 `initialize` 初始化 KTV API 实例，然后调用 `addEventHandler` 注册 KTV API 事件。 ```Kotlin - val ktvApiProtocol = KTVApiImpl() + // 创建 KTV API 实例 + val ktvApiProtocol = createKTVApi() - // 初始化 KTVAPI 模块 + // 初始化 KTV API 模块 ktvApiProtocol.initialize(KTVApiConfig( // 你的 App ID。 "", @@ -83,7 +84,9 @@ // 设置可缓存的音乐资源数量，最多不能超过 50。 10, // 设置 K 歌的场景。 - KTVType.Normal + KTVType.Normal, + // 音乐资源类型，默认为声网音乐内容中心提供的版权音乐。 + KTVSongType.SONG_CODE ) // 更新数据流 ID。一个频道中最多只能创建 5 个数据流。 From 9e25cdd4fe7650f1e13fac93aa443e378cfe8b99 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Fri, 25 Aug 2023 18:02:08 +0800 Subject: [PATCH 06/28] karaoke kit --- ...e API \345\217\202\350\200\203-android.md" | 190 ++++++++++++++++++ .../demo/AUIKaraoke-demo-Android.md | 49 +++++ .../AUIKaraoke/demo/AUIKaraoke-demo-iOS.md | 100 +++++++++ .../\346\234\252\345\221\275\345\220\215.md" | 3 + 4 files changed, 342 insertions(+) create mode 100644 "markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" create mode 100644 markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-Android.md create mode 100644 markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-iOS.md create mode 100644 "markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/\346\234\252\345\221\275\345\220\215.md" diff --git "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" new file mode 100644 index 00000000000..0a6d1ec8d36 --- /dev/null +++ "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" @@ -0,0 +1,190 @@ +# AUIKitKaraoke API 参考 + +本文介绍 AUIKitKaraoke 组件的 API。 + +## KaraokeUIKit + +提供 `AUIKitKaraoke` 的核心类，可用于实现组件初始化、创建、销毁房间等基础功能。 + +### setup + +```kotlin +fun setup( + config: AUICommonConfig, + ktvApi: KTVApi? = null, + rtcEngineEx: RtcEngineEx? = null, + rtmClient: RtmClient? = null +) +``` + +初始化 `scenekit`。 + +在调用 `KaraokeUIKit` 类下的其他 API 前，你需要先调用该方法进行初始化。 + +**参数** + +- `config`：`AUICommonConfig` 这个里面包含了哪些东西？input里面写的是用户信息和appid等。没找到这个commonconfig的类型定义 +- `ktvApi`：[场景化 API](https://docportal.shengwang.cn/cn/online-ktv/ktv_api_kotlin?platform=Android) 实例。如果你的项目中还未集成场景化 API，请传入 `null`，`scenekit` 内部会自行创建场景化 API 实例。 +- `rtcEngineEx`：[RtcEngineEx](https://docportal.shengwang.cn/cn/online-ktv/API%20Reference/java_ng/API/rtc_interface_class.html#class_irtcengineex) 实例。如果的你的项目中还未集成声网 RTC SDK，请传入 `null`，`scenekit` 内部会自行创建 `RtcEngineEx` 实例。 +- `rtmClient`：[RtmClient](https://doc.shengwang.cn/doc/rtm2/java/landing-page) 实例。如果的你的项目中还未集成声网 RTM SDK，请传入 `null`，`scenekit` 内部会自行创建 `RtmClient` 实例。 + +### createRoom + +```kotlin +fun createRoom( + createRoomInfo: AUICreateRoomInfo, + success: (AUIRoomInfo) -> Unit, + failure: (AUIException) -> Unit +) +``` + +创建 K 歌房间。 + +在 K 歌场景下，创建房间的人自动成为房主。成功创建房间后，会返回创建的房间信息。//TODO + +**参数** + +- `createRoomInfo`：需要创建的房间信息，详见 `AUICreateRoomInfo`。//TODO +- `success`：回调函数，当房间创建成功时调用。接受一个 `AUIRoomInfo` 参数，表示成功创建的房间信息，无返回值。//TODO +- `failure`：回调函数，当房间创建失败时调用。接受一个 `AUIException` 参数表示房间创建失败的异常， 无返回值。 + +### getRoomList + +```kotlin +fun getRoomList( + startTime: Long?, + pageSize: Int, + success: (List) -> Unit, + failure: (AUIException) -> Unit +) +``` + +获取 K 歌房间列表。 + +你可以调用该方法获取当前的已创建的 K 歌房间列表。 + +**参数** + +- `startTime`：开始时间 //TODO 是指获取某一特定时间之后创建的房间列表吗？ +- `pageSize`：房间列表页数，默认从 0 还是从 1开始？//TODO +- `success`：回调函数，当成功获取到 K 歌房间列表时调用，会返回一个房间信息列表，详见 [AUIRoomInfo](#AUIRoomInfo)。 +- `failure`：回调函数，当房间创建失败时调用。接受一个 `AUIException` 参数表示房间创建失败的异常， 无返回值。 + +### launchRoom + +```kotlin +fun launchRoom( + roomInfo: AUIRoomInfo, + config: AUIRoomConfig, + karaokeView: KaraokeRoomView, +) +``` + +拉起 K 歌房间。 + +当你成功调用 `createRoom` 创建房间后，你可以调用该方法拉起房间。 + +**参数** + +- `roomInfo`：需要拉起的房间信息，详见 [AUIRoomInfo](#AUIRoomInfo)。 +- `config`：房间配置，详见 [AUIRoomConfig](#AUIRoomConfig)。 +- `karaokeView`： `KaraokeRoomView` 实例，用于显示 K 歌房间的界面。 + +### destroyRoom + +```kotlin +fun destroyRoom(roomId: String?) +``` + +销毁 K 歌房间。 + +**参数** + +- `roomId`：要销毁的房间的 ID。 + +### release + +```kotlin +fun release() +``` + +释放 `scenekit` 资源。 + +//TODO 和destroyRoom 方法之间是否有调用先后时许要求。 + +## 数据模型 + +### AUICommonConfig + +```kotlin + +``` + +房间相关设置。//TODO 这个shortdesc有点怪 + +**参数** + +- `context`：安卓活动上下文。 +- `appId`：你的项目在控制台注册的 App ID，详见[获取 App ID](https://docportal.shengwang.cn/cn/Agora%20Platform/get_appid_token?platform=All%20Platforms#获取-app-id)。 +- `userId`：用户 ID。 +- `userName`：用户名。 +- `userAvatar`：用户头像。 + +### AUIRoomInfo + +```kotlin + +``` + +K 歌房间的相关信息。 + +**参数** + +- `roomId`：房间 ID。 +- `roomOwner`：房主信息，详见 [AUIUserThumbnailInfo](#AUIUserThumbnailInfo)。 +- `onlineUsers`：房间内的人数。 +- `createTime`：房间创建的时间（单位？//TODO） + +### AUIUserThumbnailInfo + +```kotlin + +``` + +K 歌房主相关信息。 + +**参数** + +- `userId`：房主的 ID。 +- `userName`：房主的用户名。 +- `userAvatar`：房主的头像。 + +### AUIException + +```kotlin + +``` + +错误码及信息。 + +**参数** + +- `code`：错误码// TODO 有哪些？ +- `message`：错误信息。 + +### AUIRoomConfig + +K 歌房间设置。 + +```kotlin + +``` + +**参数** + +- `channelName`：主频道名（是指主唱所在的频道吗？），一般为 `roomId`。 +- + + + + \ No newline at end of file diff --git a/markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-Android.md b/markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-Android.md new file mode 100644 index 00000000000..df3450011e2 --- /dev/null +++ b/markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-Android.md @@ -0,0 +1,49 @@ +声网在 GitHub 上提供一个开源的 [AUIKaraoke 示例项目](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main)。本文介绍如何快速跑通该示例项目，体验在线 K 歌场景。//TODO 和生动互娱的demo的描述之间的差异 + +## 前提条件 + +- [Git](https://git-scm.com/downloads) +- Android API Level 24 及以上 +- Android Studio 3.5 及以上 +- Android 设备，版本 Android 7.0 及以上 +- [Java Development Kit](https://www.oracle.com/java/technologies/javase-downloads.html) 17 及以上 + + + +声网推荐使用真机运行项目。部分模拟机可能存在功能缺失或者性能问题。 + + + +## 操作步骤 + +### 获取示例项目 + +运行以下命令克隆仓库到本地： + +```shell +git clone git@github.com:AgoraIO-Community/AUIKitKaraoke.git +``` + +### 配置示例项目 + +配置业务服务器域名。用 Android studio 打开 `AUIKitKaraoke/Android` 文件夹，在 `local.peoperties` 文件里配置业务服务器域名。你也可以直接使用声网用于测试的域名进行体验：https://service.agora.io/uikit-karaoke。 + +![image-20230822142250570](/Users/admin/Library/Application Support/typora-user-images/image-20230822142250570.png) + +### 编译并运行示例项目 + +1. 开启 Android 设备的开发者选项，打开 USB 调试，通过 USB 连接线将 Android 设备接入电脑，并在 Android 设备选项中勾选你的 Android 设备。 + +2. 在 Android Studio 中，点击 **Sync Project with Gradle Files** 按钮，以让项目与 Gradle 文件同步。 + +3. 待同步成功后，点击 ![img](https://web-cdn.agora.io/docs-files/1687670569781) 开始编译。 + +4. 编译成功后，你的 Android 设备上会出现 **AUIKitKaraoke** app。 + +5. 打开 app，点击**创建房间**即可开始体验在线 K 歌。 + + image-20230822164726767 + +## 参考信息 + +- 如需部署 K 歌业务后端服务，可参考[后台服务部署](https://github.com/AgoraIO-Community/AUIKitKaraoke/blob/main/backend/README_zh.md)。 \ No newline at end of file diff --git a/markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-iOS.md b/markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-iOS.md new file mode 100644 index 00000000000..bf948969a45 --- /dev/null +++ b/markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-iOS.md @@ -0,0 +1,100 @@ +声网在 GitHub 上提供一个开源的 [AUIKaraoke 示例项目](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main)。本文介绍如何快速跑通该示例项目，体验在线 K 歌场景。//TODO 和生动互娱的demo的描述之间的差异 + +## 前提条件 + +- [Git](https://git-scm.com/downloads) +- [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) 1.12.1 及以上 + + + +如果你的 CocoaPods 版本低于 1.12.1，在运行 pod install 命令时可能会报错，详见常见问题。 + + + +- [Xcode](https://apps.apple.com/cn/app/xcode/id497799835?mt=12) 13.0 及以上 +- iOS 设备，版本 13.0 及以上 +- 有效的苹果开发者账号 +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora Platform/sign_in_and_sign_up) + + + +声网推荐使用真机运行项目。部分模拟机可能存在功能缺失或者性能问题。 + + + +## 操作步骤 + +### 获取示例项目 + +运行以下命令克隆仓库到本地： + +```shell +git clone git@github.com:AgoraIO-Community/AUIKitKaraoke.git +``` + +### 配置示例项目 + +1. 配置业务服务器域名。 + + 在 `AUIKitKaraoke/KeyCenter.swift` 文件中添加你的业务服务器域名，你也可以直接使用声网测试域名来进行体验：https://service.agora.io/uikit-karaoke。 + + ```swift + static var HostUrl: String = "填入你的业务服务器域名" + ``` + +2. 打开 `AUIKitKaraoke.xcodeproj` 文件，确保 **Minimum Deployments** 设为 **13.0**，**Project Document** 下的 **Project Format** 设为 **Xcode 13.0-compatible**。 + + ![image-20230822110050483](/Users/admin/Library/Application Support/typora-user-images/image-20230822110050483.png) + +3. 打开终端，在 `AUIKitKaraoke/iOS/Example` 目录下运行 `pod install` 命令来安装 SDK 和相关依赖。安装完成后，终端会显示 `Pod installation complete!`。使用 Xcode 打开项目文件夹下新生成的 `AUIKitKaraoke.xcworkspace` 文件。 + +### 编译并运行示例项目 + +1. 将 iOS 设备连接至电脑，在设备上打开 **设备 > 隐私与安全性 > 安全性**，打开**开发者模式**。 + +2. 在 Xcode 界面顶部的 **iOS Device** 选项中勾选你的 iOS 设备。 + +3. 在项目 **TARGETS** 下的 **Signing & Capabilities** 界面勾选 **Automatically manage signing**，然后在每一个 Target 下配置你的苹果开发者账号和 **Bundle Identifier**。 + + ![image-20230821164918829](/Users/admin/Library/Application Support/typora-user-images/image-20230821164918829.png) + +4. 点击 **Start the active scheme** 开始编译。 + +5. 编译成功后，你的 iOS 设备上会安装好 AUIKitKaraoke app。 + +6. 打开 app，点击创建房间即可开始体验在线 K 歌。 + + image-20230821174535425 + + image-20230821174751911 + + + +## 常见问题 + +本节提供跑通示例项目时可能遇到的常见问题及解决方案。 + +### CocoaPods 版本过低 + +如果你的 CocoaPods 版本低于 1.12.1，在跑通本示例项目时可能遇到如下报错： + +```sh +can't modify frozen string: "[Xcodeproject] unknown object version (56). +``` + +### 解决方案 + +1. 升级 CocoaPods 版本。你可以通过运行下列命令来安装特定版本的 CocoaPods： + + ```shell + # 指定你需要升级的 CocoaPods 版本，下列命令以 1.12.1 为例。 + gem install cocoapods -v 1.12.1 + ``` + +2. 重置 CocoaPods 缓存。有时候 CocoaPods 缓存可能导致问题，你可以通过运行以下命令来清除缓存。 + + ```shell + pod cache clean --all + ``` + +3. 在 `AUIKitKaraoke/iOS/Example` 目录下运行 `pod install` 命令来安装 SDK 和相关依赖。安装完成后，终端会显示 `Pod installation complete!`。 \ No newline at end of file diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/\346\234\252\345\221\275\345\220\215.md" "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/\346\234\252\345\221\275\345\220\215.md" new file mode 100644 index 00000000000..851582e319d --- /dev/null +++ "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/\346\234\252\345\221\275\345\220\215.md" @@ -0,0 +1,3 @@ +# 实现在线 K 歌房 + +AUIKitKaraoke 组件 \ No newline at end of file From 7dff1f52641800ff0a7a66d842abd98a36fe31ad Mon Sep 17 00:00:00 2001 From: Suri539 Date: Fri, 25 Aug 2023 18:33:15 +0800 Subject: [PATCH 07/28] =?UTF-8?q?3.3.0=20API=20=E2=9C=8C=EF=B8=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...257\345\214\226 Kotlin API for Android.md" | 4 +- .../\351\233\206\346\210\220.md" | 2 +- ...57\345\214\226 Objective-C API for iOS.md" | 46 ++++++++++--------- .../\351\233\206\346\210\220.md" | 6 ++- 4 files changed, 33 insertions(+), 25 deletions(-) diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Kotlin API for Android.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Kotlin API for Android.md" index 75e93a3db75..c34cf1f1f59 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Kotlin API for Android.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Kotlin API for Android.md" @@ -787,7 +787,7 @@ data class KTVApiConfig constructor( val chorusChannelToken: String, val maxCacheSize: Int = 10, val type: KTVType = KTVType.Normal, - val musicType: KTVSongType = KTVSongType.SONG_CODE + val musicType: KTVMusicType = KTVMusicType.SONG_CODE ) ``` @@ -813,7 +813,7 @@ K 歌配置： - `type`：K 歌场景，详见 [KTVType](#KTVType)。 -- `musicType`：音乐资源类型，详见 [KTVSongType](#KTVSongType)。 +- `musicType`：音乐资源类型，详见 [KTVMusicType](#KTVMusicType)。 ### KTVLoadMusicConfiguration diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" index 4591585615b..3de287e4ad0 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/Android/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" @@ -86,7 +86,7 @@ // 设置 K 歌的场景。 KTVType.Normal, // 音乐资源类型，默认为声网音乐内容中心提供的版权音乐。 - KTVSongType.SONG_CODE + KTVMusicType.SONG_CODE ) // 更新数据流 ID。一个频道中最多只能创建 5 个数据流。 diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Objective-C API for iOS.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Objective-C API for iOS.md" index 7075c5f7ea1..60010afe98b 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Objective-C API for iOS.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Objective-C API for iOS.md" @@ -631,6 +631,22 @@ K 歌的场景： - `Normal`：独唱、合唱场景。 - `SingBattle`：抢唱场景。 + + +#### loadMusicType + +```objective-c +@objc public enum loadMusicType: Int { + case mcc + case local +} +``` + +音乐资源类型： + +- `mcc`：（默认）声网内容中心提供的版权音乐。 +- `local`：本地音乐。 + ## Class @@ -649,27 +665,8 @@ K 歌的场景： var chorusChannelToken: String var type: KTVType = .normal var maxCacheSize: Int = 10 - @objc public - init(appId: String, - rtmToken: String, - engine: AgoraRtcEngineKit, - channelName: String, - localUid: Int, - chorusChannelName: String, - chorusChannelToken: String, - type: KTVType, - maxCacheSize: Int - ) { - self.appId = appId - self.rtmToken = rtmToken - self.engine = engine - self.channelName = channelName - self.localUid = localUid - self.chorusChannelName = chorusChannelName - self.chorusChannelToken = chorusChannelToken - self.type = type - self.maxCacheSize = maxCacheSize - } + var musicType: loadMusicType = .mcc + var isDebugMode: Bool = false } ``` @@ -695,6 +692,13 @@ K 歌配置： - `maxCacheSize`：可缓存的音乐资源数量，最多不能超过 50。 +- `musicType`：音乐资源类型，详见 [loadMusicType](#loadMusicType)。 + +- `isDebugMode`：是否开启调试模式： + + - `true`：开启调试模式。 + - `false`：（默认）关闭调试模式。 + ### KTVSongConfiguration diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" index ffede8fecef..c84c7902d36 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/\345\256\236\347\216\260\346\226\207\346\241\243/\351\233\206\346\210\220.md" @@ -65,7 +65,11 @@ KTVApiConfig *apiConfig = [[KTVApiConfig alloc] initWithAppId:@" Date: Mon, 28 Aug 2023 17:52:22 +0800 Subject: [PATCH 08/28] api ref draft --- ...e API \345\217\202\350\200\203-android.md" | 94 ++++++-- .../AUIKitKaraoke Objective-C API.md | 225 ++++++++++++++++++ .../\346\234\252\345\221\275\345\220\215.md" | 3 - 3 files changed, 302 insertions(+), 20 deletions(-) create mode 100644 markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md delete mode 100644 "markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/\346\234\252\345\221\275\345\220\215.md" diff --git "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" index 0a6d1ec8d36..d69544653b9 100644 --- "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" +++ "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" @@ -1,7 +1,9 @@ -# AUIKitKaraoke API 参考 +# AUIKitKaraoke Kotlin API (Android) 本文介绍 AUIKitKaraoke 组件的 API。 +源码文件？ + ## KaraokeUIKit 提供 `AUIKitKaraoke` 的核心类，可用于实现组件初始化、创建、销毁房间等基础功能。 @@ -23,7 +25,7 @@ fun setup( **参数** -- `config`：`AUICommonConfig` 这个里面包含了哪些东西？input里面写的是用户信息和appid等。没找到这个commonconfig的类型定义 +- `config`：初始化设置，详见 [AUICommonConfig](#AUICommonConfig)。 - `ktvApi`：[场景化 API](https://docportal.shengwang.cn/cn/online-ktv/ktv_api_kotlin?platform=Android) 实例。如果你的项目中还未集成场景化 API，请传入 `null`，`scenekit` 内部会自行创建场景化 API 实例。 - `rtcEngineEx`：[RtcEngineEx](https://docportal.shengwang.cn/cn/online-ktv/API%20Reference/java_ng/API/rtc_interface_class.html#class_irtcengineex) 实例。如果的你的项目中还未集成声网 RTC SDK，请传入 `null`，`scenekit` 内部会自行创建 `RtcEngineEx` 实例。 - `rtmClient`：[RtmClient](https://doc.shengwang.cn/doc/rtm2/java/landing-page) 实例。如果的你的项目中还未集成声网 RTM SDK，请传入 `null`，`scenekit` 内部会自行创建 `RtmClient` 实例。 @@ -44,7 +46,7 @@ fun createRoom( **参数** -- `createRoomInfo`：需要创建的房间信息，详见 `AUICreateRoomInfo`。//TODO +- `createRoomInfo`：房间信息，详见 [AUICreateRoomInfo](#AUICreateRoomInfo)。 - `success`：回调函数，当房间创建成功时调用。接受一个 `AUIRoomInfo` 参数，表示成功创建的房间信息，无返回值。//TODO - `failure`：回调函数，当房间创建失败时调用。接受一个 `AUIException` 参数表示房间创建失败的异常， 无返回值。 @@ -110,17 +112,23 @@ fun release() 释放 `scenekit` 资源。 -//TODO 和destroyRoom 方法之间是否有调用先后时许要求。 +//TODO 和destroyRoom 方法之间是否有调用先后时序要求。 ## 数据模型 -### AUICommonConfig +###

    AUICommonConfig

    ```kotlin - +public class AUICommonConfig { + public @NonNull Context context; + public @NonNull String appId = ""; + public @NonNull String userId = ""; + public @NonNull String userName = ""; + public @NonNull String userAvatar = ""; +} ``` -房间相关设置。//TODO 这个shortdesc有点怪 +通用设置。 **参数** @@ -130,10 +138,15 @@ fun release() - `userName`：用户名。 - `userAvatar`：用户头像。 -### AUIRoomInfo +###

    AUIRoomInfo

    ```kotlin - +public class AUIRoomInfo extends AUICreateRoomInfo implements Serializable { + public @NonNull String roomId = ""; + public @Nullable AUIUserThumbnailInfo roomOwner; + public int onlineUsers = 0; + public long createTime = 0; +} ``` K 歌房间的相关信息。 @@ -145,13 +158,19 @@ K 歌房间的相关信息。 - `onlineUsers`：房间内的人数。 - `createTime`：房间创建的时间（单位？//TODO） -### AUIUserThumbnailInfo +###

    AUIUserThumbnailInfo

    ```kotlin +public class AUIUserThumbnailInfo implements Serializable { + public @NonNull String userId = ""; + public @NonNull String userName = ""; + public @NonNull String userAvatar = ""; + +} ``` -K 歌房主相关信息。 +K 歌中房主的相关信息。 **参数** @@ -159,10 +178,10 @@ K 歌房主相关信息。 - `userName`：房主的用户名。 - `userAvatar`：房主的头像。 -### AUIException +###

    AUIException

    ```kotlin - +public AUIException(int code, String message) ``` 错误码及信息。 @@ -172,18 +191,59 @@ K 歌房主相关信息。 - `code`：错误码// TODO 有哪些？ - `message`：错误信息。 -### AUIRoomConfig +###

    AUIRoomConfig

    K 歌房间设置。 ```kotlin - +public class AUIRoomConfig { + + @NonNull public String channelName = ""; //正常rtm使用的频道 + @NonNull public String rtmToken = ""; //rtm login用，只能007 + @NonNull public String rtcToken = ""; //rtm join用 + @NonNull public String rtcChannelName = ""; //rtc使用的频道 + @NonNull public String rtcRtcToken = ""; //rtc join使用 + @NonNull public String rtcRtmToken = ""; //rtc mcc使用，只能006 + @NonNull public String rtcChorusChannelName = ""; //rtc 合唱使用的频道 + @NonNull public String rtcChorusRtcToken = ""; //rtc 合唱join使用 + + public AUIRoomConfig(@NonNull String roomId) { + channelName = roomId; + rtcChannelName = roomId + "_rtc"; + rtcChorusChannelName = roomId + "_rtc_ex"; + } +} ``` **参数** -- `channelName`：主频道名（是指主唱所在的频道吗？），一般为 `roomId`。 -- +- `channelName`：主频道名，一般为 `roomId`。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。 + +- `rtmToken`：加入主频道时的 RTM Token。//TODO 这个 token 是用于什么鉴权？ + + + + 请确保你使用的 RTM Token 是 AccessToken2。 + + + +- `rtcToken`：加入主频道时用于鉴权的 RTC Token。 + +- `rtcChannelName`：音视频频道名，一般为{roomId}_rtc。//TODO 音视频频道和主频道之间有什么区别？ + +- `rtcRtcToken`： + +- `rtcRtmToken`：用于音乐内容中心鉴权的 RTM Token。 + + + + 请确保你使用的 RTM Token 是 AccessToken。//rtc mcc 使用是啥意思？ + + + +- `rtcChorusChannelName`：合唱频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。//TODO 独唱场景下，这个参数为空？ + +- `rtcChorusRtcToken`：根据合唱频道名和用户 ID 生成的 RTC Token，用于加入合唱频道时进行鉴权。//TODO 在独唱场景下，该参数可以为空？ diff --git a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md new file mode 100644 index 00000000000..19e6d11ef04 --- /dev/null +++ b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md @@ -0,0 +1,225 @@ +# AUIKitKaraoke swift API（iOS） + +本文介绍 AUIKitKaraoke 组件的 API。 + +源码文件？ + +## KaraokeUIKit + +提供 `AUIKitKaraoke` 的核心类，可用于实现组件初始化、创建、销毁房间等基础功能。 + +### setup + +```swift +func setup(roomConfig: AUICommonConfig, + ktvApi: KTVApiDelegate? = nil, + rtcEngine: AgoraRtcEngineKit? = nil, + rtmClient: AgoraRtmClientKit? = nil) +``` + +初始化 `scenekit`。 + +在调用 `KaraokeUIKit` 类下的其他 API 前，你需要先调用该方法进行初始化。 + +**参数** + +- `roomConfig`：初始化设置，详见 [AUICommonConfig](#AUICommonConfig)。 +- `ktvApi`：[KTVApiDelegate](https://docportal.shengwang.cn/cn/online-ktv/ktv_api_oc?platform=iOS#ktvapidelegate) 对象。如果你的项目中还未集成场景化 API，请传入 `nil`，`scenekit` 内部会自行创建 `KTVApiDelegate` 对象。 +- `rtcEngine`：[AgoraRtcEngineKit](https://docportal.shengwang.cn/cn/online-ktv/API%20Reference/ios_ng/API/rtc_interface_class.html#class_irtcengine) 对象。如果的你的项目中还未集成声网 RTC SDK，请传入 `nil`，`scenekit` 内部会自行创建 `AgoraRtcEngineKit` 对象。 +- `rtmClient`：[AgoraRtmClientKit](https://doc.shengwang.cn/doc/rtm2/oc/landing-page) 对象。如果的你的项目中还未集成声网 RTM SDK，请传入 `nil`，`scenekit` 内部会自行创建 `AgoraRtmClientKit` 对象。 + +### createRoom + +```swift +func createRoom(roomInfo: AUICreateRoomInfo, + success: ((AUIRoomInfo?)->())?, + failure: ((Error)->())?) +``` + +创建 K 歌房间。 + +在 K 歌场景下，创建房间的人自动成为房主。成功创建房间后，会返回创建的房间信息。//TODO + +**参数** + +- `roomInfo`：一个 `AUICreateRoomInfo` 对象，包含要创建的房间信息 。 +- `success`：（可选）成功回调闭包，当房间创建成功时将被调用。闭包参数为一个 `AUIRoomInfo` 对象，表示创建的房间信息。 +- `failure`：（可选）失败回调闭包，当房间创建失败时将被调用。闭包参数为一个 `Error` 对象，表示创建失败的错误信息。 + +### getRoomList + +```swift +func getRoomInfoList(lastCreateTime: Int64?, + pageSize: Int, + callback: @escaping AUIRoomListCallback) +``` + +获取 K 歌房间列表。 + +你可以调用该方法获取当前的已创建的 K 歌房间列表。 + +**参数** + +- `lastCreateTime`：（可选）开始时间 //TODO 是指获取某一特定时间之后创建的房间列表吗？ +- `pageSize`：房间列表页数，默认从 0 还是从 1开始？//TODO +- `callback`：用于处理获取房间列表结果的回调闭包，该闭包在函数执行完成后仍然可以被调用。回调闭包接受一个 `AUIRoomListCallback` 对象作为参数。//TODO + +### launchRoom + +```swift +func launchRoom(roomInfo: AUIRoomInfo, + appId: String? = nil, + config: AUIRoomConfig, + karaokeView: AUIKaraokeRoomView) +``` + +拉起 K 歌房间。 + +当你成功调用 `createRoom` 创建房间后，你可以调用该方法拉起房间。 + +**参数** + +- `roomInfo`：需要拉起的房间信息，详见 [AUIRoomInfo](#AUIRoomInfo)。 +- `appId`：（可选）你的项目在控制台注册的 App ID。如果在调用 `setup` 进行初始化时设置了 `appId`，则此处为必填，否则可传入 `nil`。 +- `config`：房间配置，详见 [AUIRoomConfig](#AUIRoomConfig)。 +- `karaokeView`： `AUIKaraokeRoomView` 对象，用于显示 K 歌房间的界面。 + +### destroyRoom + +```kotlin +func destoryRoom(roomId: String) +``` + +销毁 K 歌房间。 + +**参数** + +- `roomId`：要销毁的房间的 ID。 + +## 数据模型 + +###

    AUICommonConfig

    + +```swift +open class AUICommonConfig: NSObject { + public var appId: String = "" + public var host: String = "" + public var userId: String = "" + public var userName: String = "" + public var userAvatar: String = "" +} +``` + +通用设置。 + +**参数** + +- `appId`：你的项目在控制台注册的 App ID，详见[获取 App ID](https://docportal.shengwang.cn/cn/Agora%20Platform/get_appid_token?platform=All%20Platforms#获取-app-id)。 +- `host`：业务后端服务域名。 +- `userId`：用户 ID。 +- `userName`：用户名。 +- `userAvatar`：用户头像。 + +###

    AUIRoomInfo

    + +```kotlin +open class AUIRoomInfo: AUICreateRoomInfo { + public var roomId: String = "" + public var owner: AUIUserThumbnailInfo? + public var memberCount: UInt = 0 + public var createTime: Int64 = 0 +} +``` + +K 歌房间的相关信息。 + +**参数** + +- `roomId`：房间 ID。 +- `roomOwner`：房主信息，详见 [AUIUserThumbnailInfo](#AUIUserThumbnailInfo)。 +- `onlineUsers`：房间内的人数。 +- `createTime`：房间创建的时间（单位？//TODO） + +###

    AUIUserThumbnailInfo

    + +```swift +open class AUIUserThumbnailInfo: NSObject,AUIUserCellUserDataProtocol { + + public var userId: String = "" //用户Id + public var userName: String = "" //用户名 + public var userAvatar: String = "" //用户头像 + public var seatIndex: Int = -1 //用户是否在麦上 + public var isOwner: Bool = false //是否是owner + + public func isEmpty() -> Bool { + guard userId.count > 0, userName.count > 0 else {return true} + + return false + } +} +``` + +K 歌中房主的相关信息。//TODO 原型和input给的参数不一致 + +**参数** + +- `userId`：房主的 ID。 +- `userName`：房主的用户名。 +- `userAvatar`：房主的头像。 + +###

    AUIException

    + +//TODO iOS没有这个 + +###

    AUIRoomConfig

    + +K 歌房间设置。 + +```kotlin +open class AUIRoomConfig: NSObject { + public var channelName: String = "" //正常rtm使用的频道 + public var rtmToken007: String = "" //rtm login用，只能007 + public var rtcToken007: String = "" //rtm join用 + public var rtcChannelName: String = "" //rtc使用的频道 + public var rtcRtcToken: String = "" //rtc join使用 + public var rtcRtmToken: String = "" //rtc mcc使用 + public var rtcChorusChannelName: String = "" //rtc 合唱使用的频道 + public var rtcChorusRtcToken: String = "" //rtc 合唱join使用 +} +``` + +**参数** + +- `channelName`：主频道名，一般为 `roomId`。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。 + +- `rtmToken007`：加入主频道时的 RTM Token。//TODO 这个 token 是用于什么鉴权？ + + + + 请确保你使用的 RTM Token 是 AccessToken2。 + + + +- `rtcToken007`：加入主频道时用于鉴权的 RTC Token。 + +- `rtcChannelName`：音视频频道名，一般为{roomId}_rtc。//TODO 音视频频道和主频道之间有什么区别？ + +- `rtcRtcToken`： + +- `rtcRtmToken`：用于音乐内容中心鉴权的 RTM Token。 + + + + 请确保你使用的 RTM Token 是 AccessToken。//rtc mcc 使用是啥意思？ + + + +- `rtcChorusChannelName`：合唱频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。//TODO 独唱场景下，这个参数为空？ + +- `rtcChorusRtcToken`：根据合唱频道名和用户 ID 生成的 RTC Token，用于加入合唱频道时进行鉴权。//TODO 在独唱场景下，该参数可以为空？ + + + + + + \ No newline at end of file diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/\346\234\252\345\221\275\345\220\215.md" "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/\346\234\252\345\221\275\345\220\215.md" deleted file mode 100644 index 851582e319d..00000000000 --- "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/\346\234\252\345\221\275\345\220\215.md" +++ /dev/null @@ -1,3 +0,0 @@ -# 实现在线 K 歌房 - -AUIKitKaraoke 组件 \ No newline at end of file From aec764279cc56bfcff06c9dcf27ce7022273a7f5 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Wed, 30 Aug 2023 15:55:50 +0800 Subject: [PATCH 09/28] 50% --- .../android-\351\233\206\346\210\220.md" | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 "markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" new file mode 100644 index 00000000000..fa960579be2 --- /dev/null +++ "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" @@ -0,0 +1,88 @@ +# 实现在线 K 歌房 + +本文介绍如何通过 [AUIKitKaraoke 组件](#)快速搭建一个含 UI 界面的在线 K 歌房。 + +下图展示搭建 K 歌房间的流程： + +image-20230830103826589 + +## 准备开发环境 + +### 前提条件 + +- [Git](https://git-scm.com/downloads) +- Android API Level 24 及以上 +- Android Studio 3.5 及以上 +- Android 设备，版本 Android 7.0 及以上 +- [Java Development Kit](https://www.oracle.com/java/technologies/javase-downloads.html) 17 及以上 + + + +声网推荐使用真机运行项目。部分模拟机可能存在功能缺失或者性能问题。 + + + +### 创建项目 + +按照以下步骤来准备开发环境： + +1. 如需创建新项目，在 **Android Studio** 里，依次选择 **Phone and Tablet > Empty Activity**，创建 [Android 项目](https://developer.android.com/studio/projects/create-project)。 + + 创建项目后，**Android Studio** 会自动开始同步 gradle, 稍等片刻至同步成功后再进行下一步操作。 + + + +2. 集成 asceneskit。 + + 1. 将 [asceneskit 文件夹](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main/Android/asceneskit)复制到你的项目中。 + + 2. 在 `settings.gradle` 文件中添加 asceneskit 库： + + ```java + include ':asceneskit' + ``` + + 3. 在 `build.grade` 文件中添加以下依赖： + + ```java + dependencies { + implementation project(':asceneskit') + } + ``` + + 4. 添加权限并设置主题。在你的 `AndroidManifest.xml` 文件中添加下列内容： + + ```java + + + + + + + + + + + + + + ... + + + + + ``` + + 5. 配置你的业务服务器域名。在你的项目的 `local.properties` 文件中添加你的业务服务器域名。你可以参考[后台服务](https://github.com/AgoraIO-Community/AUIKitKaraoke/blob/main/backend/README_zh.md)来搭建你的业务服务器，也可以使用声网用于测试的域名来体验：https://service.agora.io/uikit-karaoke + + ![image-20230830113539829](/Users/admin/Library/Application Support/typora-user-images/image-20230830113539829.png) + + ```java + SERVER_HOST=你的业务服务器域名 + ``` + +## 实现在线 K 歌房 + From 44aa4de7646da9f4a6d04372e508f35881859f38 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Fri, 1 Sep 2023 16:18:49 +0800 Subject: [PATCH 10/28] add android --- ...e API \345\217\202\350\200\203-android.md" | 24 +++- .../android-\351\233\206\346\210\220.md" | 126 +++++++++++++++++- 2 files changed, 148 insertions(+), 2 deletions(-) diff --git "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" index d69544653b9..7092aff518a 100644 --- "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" +++ "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" @@ -138,6 +138,28 @@ public class AUICommonConfig { - `userName`：用户名。 - `userAvatar`：用户头像。 +###

    AUICreateRoomInfo

    + +```kotlin +public class AUICreateRoomInfo implements Serializable { + public @NonNull String roomName = ""; //房间名称 + public @NonNull String thumbnail = ""; //房间列表上的缩略图 + public int micSeatCount = 8; //麦位个数 + public @Nullable String password; //房间密码 + public String micSeatStyle = ""; //麦位样式 +} +``` + +需要创建的 K 歌房间的相关信息。 + +**参数** + +- `roomName`：房间名。 +- `thumbnail`：房间列表上的缩略图？是指用户头像图片的url吗？ +- `micSeatCount`：房间中的麦位数量。//TODO 是否有取值范围？ +- `password`：房间密码。 +- `micSeatStyle`：麦位样式//TODO 什么样式？ + ###

    AUIRoomInfo

    ```kotlin @@ -149,7 +171,7 @@ public class AUIRoomInfo extends AUICreateRoomInfo implements Serializable { } ``` -K 歌房间的相关信息。 +已创建的 K 歌房间的相关信息。 **参数** diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" index fa960579be2..a55809e370f 100644 --- "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" @@ -2,7 +2,7 @@ 本文介绍如何通过 [AUIKitKaraoke 组件](#)快速搭建一个含 UI 界面的在线 K 歌房。 -下图展示搭建 K 歌房间的流程： +下图展示搭建 K 歌房间的完整流程： image-20230830103826589 @@ -22,6 +22,11 @@ +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora Platform/sign_in_and_sign_up)和声网项目，请参考[开始使用声网平台](https://docs.agora.io/cn/Agora Platform/get_appid_token?platform=All Platforms)，从声网控制台获取以下信息： + - App ID：声网随机生成的字符串，用于识别你的 app。 + - 临时 Token：你的 app 客户端加入频道时会使用 Token 对用户进行鉴权。临时 Token 的有效期为 24 小时。 + - rtm token xxxx + ### 创建项目 按照以下步骤来准备开发环境： @@ -86,3 +91,122 @@ ## 实现在线 K 歌房 +下图展示了创建一个在线 K 歌房的 API 调用时序： + +image-20230830161719228 + +### 1. 初始化 KaraokeUiKit + +创建 `AUiCommonConfig` 对象，调用 `setup` 初始化 KaraokeUiKit。 + +```java +// 创建 AUiCommonConfig 对象 +val config = AUiCommonConfig() +config.context = application +// 获取你在声网控制台获取的 app ID +config.appId = "Agora APP ID" +// 用户 ID +config.userId = "User ID" +// 用户名 +config.userName = "User Name" +// 用户头像 +config.userAvatar = "User Avatar" +// 初始化 +KaraokeUiKit.setup( + // AUiCommonConfig 对象 + config = config, + // RtmClient 实例。如果的你的项目中还未集成声网 RTM SDK，请传入 null，KaraokeUiKit 内部会自行创建 + rtmClient = null, + // RtcEngineEx 实例。如果的你的项目中还未集成声网 RTC SDK，请传入 null，KaraokeUiKit 内部会自行创建 + rtcEngineEx = null, + // KtvApi 实例。如果你的项目中还未集成 KtvApi，请传入 null，KaraokeUiKit 内部会自行创建 + ktvApi = null +) +``` + +### 2. 创建房间 + +调用 `createRoom` 创建房间。在创建房间之前，请确保你已经调用 `setup` 成功初始化。 + +```kotlin +val createRoomInfo = AUiCreateRoomInfo() +createRoomInfo.roomName = roomName +// 创建房间 +KaraokeUiKit.createRoom( + createRoomInfo, + success = { roomInfo -> + // 创建房间成功时调用 + }, + failure = { error -> + // 创建房间失败时调用 + } +) +``` + +### 3. 获取房间列表 + +调用 `getRoomList` 获取已创建房间的列表。 + +```kotlin +// 获取房间列表 TODO 这里的参数名是lastCreateTime，但是api参考以及代码仓库里面都是startTime +KaraokeUiKit.getRoomList(lastCreateTime, 10, + // 房间创建成功时调用 + success = { roomList -> + runOnUiThread { + + } + }, + // 房间创建失败时调用 + failure = { error -> + runOnUiThread { + // update ui + } + } +) +``` + +### 4. 拉起房间 + +调用 `launchRooom` 拉起房间。至此，你已经成功搭建一个自带 UI 界面的在线 K 歌房间。 + +在调用该方法前，你需要先调用 getRoomList 获取房间列表及相关房间信息。 + +```kotlin +// 房间信息，通过 getRoomList 获取 +val roomInfo : AUIRoomInfo +val karaokeRoomView: KaraokeRoomView +val config = AUiRoomConfig(roomInfo.roomId) +// 生成config.channelName及AUIRoomContext.shared().currentUserInfo.userId的token +config.rtmToken = "" +config.rtcToken = "" +// 生成config.rtcChannelName及AUIRoomContext.shared().currentUserInfo.userId的token +config.rtcRtmToken = "" +// +config.rtcRtcToken = "" +// 生成config.rtcChorusChannelName及AUIRoomContext.shared().currentUserInfo.userId的token +config.rtcChorusRtcToken = "" +// 拉起房间 +KaraokeUiKit.launchRoom( + roomInfo, + config, + karaokeRoomView +) + +// 订阅房间事件 +KaraokeUiKit.bindRespDelegate(object: AUIRoomManagerRespDelegate{ + override fun onRoomDestroy(roomId: String){ + // 房间被销毁 + } +}) +``` + +### 5. 销毁房间 + +K 歌结束后，调用 `destroyRoom` 销毁房间。 + +```kotlin +KaraokeUiKit.destroyRoom(roomId) +// 取消订阅房间事件 +KaraokeUiKit.unbindRespDelegate(this@RoomActivity) +``` + From 1e9ead93693deb920186fc24f81d1bd70288b44c Mon Sep 17 00:00:00 2001 From: Suri539 Date: Thu, 7 Sep 2023 10:11:10 +0800 Subject: [PATCH 11/28] draft --- .../android-\351\233\206\346\210\220.md" | 2 +- .../ios-\351\233\206\346\210\220.md" | 39 +++++++++++++++++++ 2 files changed, 40 insertions(+), 1 deletion(-) create mode 100644 "markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" index a55809e370f..924dce62a25 100644 --- "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" @@ -1,6 +1,6 @@ # 实现在线 K 歌房 -本文介绍如何通过 [AUIKitKaraoke 组件](#)快速搭建一个含 UI 界面的在线 K 歌房。 +本文介绍如何通过 [AUIKitKaraoke 组件](#link-to-description)快速搭建一个含 UI 界面的在线 K 歌房。 下图展示搭建 K 歌房间的完整流程： diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" new file mode 100644 index 00000000000..419c07821de --- /dev/null +++ "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" @@ -0,0 +1,39 @@ +本文介绍如何通过 [AUIKitKaraoke 组件](#link-to-description)快速搭建一个含 UI 界面的在线 K 歌房。 + +下图展示搭建 K 歌房间的完整流程： + +image-20230830103826589 + +## 准备开发环境 + +### 前提条件 + +- [Git](https://git-scm.com/downloads) +- [CocoaPods](https://guides.cocoapods.org/using/getting-started.html#getting-started) 1.12.1 及以上 + +- [Xcode](https://apps.apple.com/cn/app/xcode/id497799835?mt=12) 13.0 及以上 + +- iOS 设备，版本 13.0 及以上 + + + + 声网推荐使用真机运行项目。部分模拟机可能存在功能缺失或者性能问题。 + + + +- 有效的苹果开发者账号 + +- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora Platform/sign_in_and_sign_up)和声网项目，请参考[开始使用声网平台](https://docs.agora.io/cn/Agora Platform/get_appid_token?platform=All Platforms)，从声网控制台获取以下信息： + + - App ID：声网随机生成的字符串，用于识别你的 app。 + - 临时 Token：你的 app 客户端加入频道时会使用 Token 对用户进行鉴权。临时 Token 的有效期为 24 小时。 + - rtm Token： + +### 创建项目 + +按照以下步骤来准备开发环境： + +1. + + + From be05e013ccdaa33176e2689b8263a111530bac96 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Mon, 11 Sep 2023 11:20:34 +0800 Subject: [PATCH 12/28] draft --- .../android-\351\233\206\346\210\220.md" | 42 ++++++++++--------- .../ios-\351\233\206\346\210\220.md" | 2 - 2 files changed, 22 insertions(+), 22 deletions(-) diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" index 924dce62a25..31ed6838583 100644 --- "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" @@ -2,6 +2,8 @@ 本文介绍如何通过 [AUIKitKaraoke 组件](#link-to-description)快速搭建一个含 UI 界面的在线 K 歌房。 +AUIKitKaraoke 是一个 + 下图展示搭建 K 歌房间的完整流程： image-20230830103826589 @@ -40,51 +42,51 @@ 2. 集成 asceneskit。 1. 将 [asceneskit 文件夹](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main/Android/asceneskit)复制到你的项目中。 - + 2. 在 `settings.gradle` 文件中添加 asceneskit 库： - + ```java include ':asceneskit' ``` - + 3. 在 `build.grade` 文件中添加以下依赖： - + ```java dependencies { implementation project(':asceneskit') } ``` - + 4. 添加权限并设置主题。在你的 `AndroidManifest.xml` 文件中添加下列内容： - + ```java - + - + - + - + ... - + - + ``` - + 5. 配置你的业务服务器域名。在你的项目的 `local.properties` 文件中添加你的业务服务器域名。你可以参考[后台服务](https://github.com/AgoraIO-Community/AUIKitKaraoke/blob/main/backend/README_zh.md)来搭建你的业务服务器，也可以使用声网用于测试的域名来体验：https://service.agora.io/uikit-karaoke - + ![image-20230830113539829](/Users/admin/Library/Application Support/typora-user-images/image-20230830113539829.png) - + ```java SERVER_HOST=你的业务服务器域名 ``` @@ -118,7 +120,7 @@ KaraokeUiKit.setup( // RtmClient 实例。如果的你的项目中还未集成声网 RTM SDK，请传入 null，KaraokeUiKit 内部会自行创建 rtmClient = null, // RtcEngineEx 实例。如果的你的项目中还未集成声网 RTC SDK，请传入 null，KaraokeUiKit 内部会自行创建 - rtcEngineEx = null, + rtcEngineEx = null, // KtvApi 实例。如果你的项目中还未集成 KtvApi，请传入 null，KaraokeUiKit 内部会自行创建 ktvApi = null ) @@ -153,10 +155,10 @@ KaraokeUiKit.getRoomList(lastCreateTime, 10, // 房间创建成功时调用 success = { roomList -> runOnUiThread { - + } }, - // 房间创建失败时调用 + // 房间创建失败时调用 failure = { error -> runOnUiThread { // update ui @@ -167,7 +169,7 @@ KaraokeUiKit.getRoomList(lastCreateTime, 10, ### 4. 拉起房间 -调用 `launchRooom` 拉起房间。至此，你已经成功搭建一个自带 UI 界面的在线 K 歌房间。 +调用 `launchRooom` 拉起房间。至此，你已经成功搭建一个带有 UI 界面的在线 K 歌房间。 在调用该方法前，你需要先调用 getRoomList 获取房间列表及相关房间信息。 @@ -188,7 +190,7 @@ config.rtcChorusRtcToken = "" // 拉起房间 KaraokeUiKit.launchRoom( roomInfo, - config, + config, karaokeRoomView ) diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" index 419c07821de..acbb2def2e5 100644 --- "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" @@ -35,5 +35,3 @@ 1. - - From cb41cf312c0880a91fe27680f8baa2bea7516841 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Thu, 14 Sep 2023 10:37:14 +0800 Subject: [PATCH 13/28] draft 40% --- .../AUIKaraoke/demo/AUIKaraoke-demo-iOS.md | 2 +- .../android-\351\233\206\346\210\220.md" | 23 ++++-- .../ios-\351\233\206\346\210\220.md" | 79 ++++++++++++++++++- 3 files changed, 93 insertions(+), 11 deletions(-) diff --git a/markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-iOS.md b/markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-iOS.md index bf948969a45..4063b864826 100644 --- a/markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-iOS.md +++ b/markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-iOS.md @@ -97,4 +97,4 @@ can't modify frozen string: "[Xcodeproject] unknown object version (56). pod cache clean --all ``` -3. 在 `AUIKitKaraoke/iOS/Example` 目录下运行 `pod install` 命令来安装 SDK 和相关依赖。安装完成后，终端会显示 `Pod installation complete!`。 \ No newline at end of file +3. 在 `AUIKitKaraoke/iOS/Example` 目录下运行重新 `pod install` 命令来安装 SDK 和相关依赖。安装完成后，终端会显示 `Pod installation complete!`。 \ No newline at end of file diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" index 31ed6838583..a040821997e 100644 --- "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" @@ -1,8 +1,14 @@ # 实现在线 K 歌房 -本文介绍如何通过 [AUIKitKaraoke 组件](#link-to-description)快速搭建一个含 UI 界面的在线 K 歌房。 +AUIKitKaraoke 是一个基于 [AUIKit](https://github.com/AgoraIO-Community/AUIKit/blob/main/Android/README.zh.md) 搭建的、针对 K 歌场景的开源 UI 组件，提供 K 歌房间相关功能。asceneskit 是 K 歌房的容器组件，你可以通过 asceneskit 自定义 K 歌房间的用户界面逻辑、实现房间管理等。 + +下图展示组件之间的关系图： + + -AUIKitKaraoke 是一个 +- AUIKit 是一个基础库，包含 Service 和 UI 两部分，为上层提供麦位管理、音乐播放、歌曲管理、合唱管理等能力及对应的 UI 模块。 + +本文介绍如何通过 [AUIKitKaraoke 组件](#link-to-description)快速搭建一个含 UI 界面的在线 K 歌房。 下图展示搭建 K 歌房间的完整流程： @@ -31,13 +37,13 @@ AUIKitKaraoke 是一个 ### 创建项目 -按照以下步骤来准备开发环境： +如需创建新项目，在 **Android Studio** 里，依次选择 **Phone and Tablet > Empty Activity**，创建 [Android 项目](https://developer.android.com/studio/projects/create-project)。如果你已有 Android 项目，可跳过这一步骤。 -1. 如需创建新项目，在 **Android Studio** 里，依次选择 **Phone and Tablet > Empty Activity**，创建 [Android 项目](https://developer.android.com/studio/projects/create-project)。 +创建项目后，**Android Studio** 会自动开始同步 gradle, 稍等片刻至同步成功后再进行下一步操作。 - 创建项目后，**Android Studio** 会自动开始同步 gradle, 稍等片刻至同步成功后再进行下一步操作。 + - +### 集成组件 2. 集成 asceneskit。 @@ -209,6 +215,9 @@ K 歌结束后，调用 `destroyRoom` 销毁房间。 ```kotlin KaraokeUiKit.destroyRoom(roomId) // 取消订阅房间事件 -KaraokeUiKit.unbindRespDelegate(this@RoomActivity) +KaraokeUiKit.unbindRespDelegate(this@RoomActivity) // auikit的接口 ``` +## 示例项目 + +声网在 GitHub 上提供一个开源的示例项目 [AUIKitKaraoke](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main/Android) 供你参考。 \ No newline at end of file diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" index acbb2def2e5..9b8c1b95914 100644 --- "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" @@ -6,6 +6,8 @@ ## 准备开发环境 +//todo https://github.com/AgoraIO-Community/AUIKitKaraoke/blob/main/iOS/doc/KaraokeUIKit_zh.md input里面的前提条件是已经跑通demo + ### 前提条件 - [Git](https://git-scm.com/downloads) @@ -29,9 +31,80 @@ - 临时 Token：你的 app 客户端加入频道时会使用 Token 对用户进行鉴权。临时 Token 的有效期为 24 小时。 - rtm Token： -### 创建项目 +### 创建并配置项目 + +按照下列步骤来创建并配置你的项目。 + +1. [创建一个新的项目](https://help.apple.com/xcode/mac/current/#/dev07db0e578)，**Application** 选择 **App**，**Interface** 选择 **Storyboard**，**Language** 选择 **Swift**。 + + 如果你没有添加过开发团队信息，会看到 **Add account…** 按钮。点击该按钮并按照屏幕提示登入 Apple ID，点击 **Next**，完成后即可选择你的 Apple 账户作为开发团队。 + +2. 为你的项目设置[自动签名](https://help.apple.com/xcode/mac/current/#/dev23aab79b4)。 + +3. 设置部署你的 app 的[目标设备](https://help.apple.com/xcode/mac/current/#/deve69552ee5)。 + +4. 在 `KeyCenter.swift` 文件中添加你的业务服务器域名，你也可以直接使用声网测试域名来进行体验：https://service.agora.io/uikit-karaoke。//TODO 这里的测试域名跟demo里面的不一致，要确认下 + + ```swift + struct KeyCenter { + static var HostUrl: String = "https://test-uikit-karaoke.bj2.agoralab.co" + // static var HostUrl: String = "https://service.agora.io/uikit-karaoke" //该域名仅限体验使用，请勿用户正式商用环境 + } + ``` + +5. 添加项目的设备权限。在项目导航栏中打开 `info.plist` 文件，配置麦克风和摄像头权限，如下图所示： + + ![image-20230911163222007](/Users/admin/Library/Application Support/typora-user-images/image-20230911163222007.png) + +​ +
    • Value 值填写使用麦克风或摄像头的目的即可。
    • 如果你的项目中需要添加第三方插件或库（例如第三方摄像头），且该插件或库的签名与项目的签名不一致，你还需勾选 Hardened Runtime > Runtime Exceptions 中的 Disable Library Validation。
    • 更多注意事项，可参考 Preparing Your App for Distribution。
    +​     + +### 集成组件 + +1. 将下列源码复制到你的项目中： + + - [AUIKit](https://github.com/AgoraIO-Community/AUIKit/tree/main/iOS) + - [AScenesKit](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main/iOS/AScenesKit) + - [KeyCenter.swift](https://github.com/AgoraIO-Community/AUIKitKaraoke/blob/main/iOS/Example/AUIKitKaraoke/KeyCenter.swift)// TODO 为什么这个也要复制？ + +2. 在 Podfile 文件里添加依赖。 + + ```ruby + pod 'AScenesKit', :path => './AScenesKit' + pod 'AUIKit', :path => './AUIKit' + ``` + +## 实现在线 K 歌房 + +### 1. 初始化 KaraokeUiKit + +创建 `AUiCommonConfig` 对象。//TODO 不用调setup吗❓ + +```swift +let commonConfig = AUICommonConfig() +commonConfig.host = KeyCenter.HostUrl +commonConfig.userId = userInfo.userId +commonConfig.userName = userInfo.userName +commonConfig.userAvatar = userInfo.userAvatar +//rtmClient可空 +let roomManager = AUIRoomManagerImpl(commonConfig: roomConfig, rtmClient: rtmClient) +``` + +### 2. 创建房间 + +调用 `createRoom` 创建房间。在创建房间之前，请确保你已经创建 `AUiCommonConfig` 对象。 + +```swift +let room = AUICreateRoomInfo() +// 房间名称 +room.roomName = text +// +room.thumbnail = userInfo.userAvatar +room.seatCount = 8 +roomManager.createRoom(room: roomInfo) { error, info in +} +``` -按照以下步骤来准备开发环境： -1. From d5a377fcf941c64a3865495106b444a409bce3f2 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Tue, 19 Sep 2023 10:38:08 +0800 Subject: [PATCH 14/28] =?UTF-8?q?Create=20=E7=BB=84=E4=BB=B6=E4=BB=8B?= =?UTF-8?q?=E7=BB=8D.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...04\344\273\266\344\273\213\347\273\215.md" | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 "markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" diff --git "a/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" "b/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" new file mode 100644 index 00000000000..c896e1e8724 --- /dev/null +++ "b/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" @@ -0,0 +1,68 @@ +本文介绍针对 K 歌场景的含 UI 解决方案 AUIKaraoke。 + +## 组件概述 + +AUIKaraoke 是声网针对 K 歌场景推出的开源 UI 组件，集成了 [K 歌房场景化 API]() 以及声网实时互动 SDK、RTM SDK 的核心功能。该组件基于 [AUIKit](https://github.com/AgoraIO-Community/AUIKit/tree/main) 开发，主要提供房间管理功能。 + +AUIKit 是一套场景化应用的脚手架，为 AUIKaraoke 提供可自定义的 UI 组件和一套通用的服务接口（Service），包括用户、麦位、合唱、播放管理。你可以查看 AUIKaraoke [组件源码](https://github.com/AgoraIO-Community/AUIKitKaraoke)快速搭建一个含 UI 界面的在线 K 歌房间，体验在线点歌、 K 歌、麦位管理、收发礼物、文字聊天等在线 K 歌场景中的核心交互。 + +下图展示 AUIKaraoke 和 AUIKit 之间的关系：（等确认好内容之后再优化图片） + +image-20230915152008777 + +1. App：接入 AUIKaraoke 的项目，其中 + + - RoomListActivity 是房间列表页 + + - RoomDetailActivity 是房间详情页（意思是通过这两个类来和 scenekit 交互吗？） + +2. AScenesKit：以源码方式集成的库，可在上面进行自定义，（和 AUIKaraoke 的关系是什么？）其中 + + 1. KaraokeUIKit 负责房间管理以及 Service、View 的统一调度 + 2. KaraokeRoomView 是默认的 K 歌房 View。你可以根据需求进行自定义修改。 + 3. binder 负责将 service 和 ui 逻辑绑定起来 + 4. AUIKiaraokeRoomService 负责管理用到的 AUIKit Service + +3. AUIKit 是一个基础库，包含Service 和 UI 两部分，为上层提供基础业务能力和 UI 组件。 + +## 核心功能 + +AUIKaraoke 提供下列核心功能： + +**房间管理**： + +- 创建、销毁房间。 +- 获取房间列表，便于对所有房间进行管理。 + +**麦位管理**： + +- 上麦和下麦：用户可以随时上下麦，实现多人互动 K 歌。 +- 踢人下麦：房主可以将用户从麦位上踢下来，以管理麦位的占用情况。（是房主可以踢人吗？还是主播也可以？） +- 封禁和锁麦：麦位可以被封禁或锁定，以更好维护 K 歌房间内秩序。 + +**音乐播放器**： + +- 歌曲控制：可以随时控制音乐的播放，如预加载、暂停、切歌等。 + +**歌曲管理**： + +- 搜索歌曲：通过歌曲或歌手关键词搜索，检索查找自己喜欢的歌曲。声网曲库涵盖 20万+ 正版歌曲。 +- 点歌和切歌：用户可以点播自己喜欢的歌曲，并在需要时切换到下一首。 +- 置顶歌曲：房主可以将某首歌曲置顶，确保它在播放列表中优先播放。（上麦的人都可以置顶还是只有房主有权限？） + +**合唱功能**： + +- 加入、离开合唱：用户可以随时加入或离开合唱，与上麦的演唱者一起享受 K 歌的乐趣。 +- 歌词同步：进行合唱时，主唱、伴唱、观众端的歌词可以实现同步，提供更出色的合唱体验。 + +**收发礼物**：房间内的用户彼此之间可以送礼物，增加互动趣味性。 + +**文字聊天**：除了上麦互动，K 歌房间内的用户彼此之间还可以发送文字消息。 + +image-20230918151926230 + +## 优势 + +## 方案对比 + +除了 AUIKaraoke 这一含 UI 的解决方案，目前声网针对在线 K 歌房场景还提供了无 UI 解决方案，其中无 UI 解决方案包括[无场景化方案](https://confluence.agoralab.co/)、[场景化 API 方案](https://confluence.agoralab.co/)，各方案之间的对比详见[方案对比]()。 \ No newline at end of file From ba651ed1bb4207fca5c56340a54283e65ee759df Mon Sep 17 00:00:00 2001 From: Suri539 Date: Tue, 19 Sep 2023 11:51:09 +0800 Subject: [PATCH 15/28] =?UTF-8?q?4.2.3=20=E2=9C=8C=EF=B8=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- dita/RTC-NG/API/enum_connectionchangedreasontype.dita | 4 ++++ dita/RTC-NG/config/keys-rtc-ng-api-cpp.ditamap | 7 +++++++ 2 files changed, 11 insertions(+) diff --git a/dita/RTC-NG/API/enum_connectionchangedreasontype.dita b/dita/RTC-NG/API/enum_connectionchangedreasontype.dita index 1ae6178ba54..409a60af00f 100644 --- a/dita/RTC-NG/API/enum_connectionchangedreasontype.dita +++ b/dita/RTC-NG/API/enum_connectionchangedreasontype.dita @@ -102,6 +102,10 @@ 20: 频道内主播人数已达上限。 + + + + 22: App 证书校验失败，可能的原因包括本地系统时间设置不正确，建议重新设置本地系统时间再重新加入频道。如需更多帮助，请。 diff --git a/dita/RTC-NG/config/keys-rtc-ng-api-cpp.ditamap b/dita/RTC-NG/config/keys-rtc-ng-api-cpp.ditamap index af845af9d13..adfa5997ce0 100644 --- a/dita/RTC-NG/config/keys-rtc-ng-api-cpp.ditamap +++ b/dita/RTC-NG/config/keys-rtc-ng-api-cpp.ditamap @@ -7611,6 +7611,13 @@ + + + + CONNECTION_CHANGED_CERTIFICATION_VERYFY_FAILURE + + + From 997511867e51a2c4c7c90b8729183b6a4ec66fef Mon Sep 17 00:00:00 2001 From: Suri539 Date: Tue, 19 Sep 2023 11:56:27 +0800 Subject: [PATCH 16/28] =?UTF-8?q?Revert=20"4.2.3=20=E2=9C=8C=EF=B8=8F"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This reverts commit ba651ed1bb4207fca5c56340a54283e65ee759df. --- dita/RTC-NG/API/enum_connectionchangedreasontype.dita | 4 ---- dita/RTC-NG/config/keys-rtc-ng-api-cpp.ditamap | 7 ------- 2 files changed, 11 deletions(-) diff --git a/dita/RTC-NG/API/enum_connectionchangedreasontype.dita b/dita/RTC-NG/API/enum_connectionchangedreasontype.dita index 409a60af00f..1ae6178ba54 100644 --- a/dita/RTC-NG/API/enum_connectionchangedreasontype.dita +++ b/dita/RTC-NG/API/enum_connectionchangedreasontype.dita @@ -102,10 +102,6 @@ 20: 频道内主播人数已达上限。 - - - - 22: App 证书校验失败，可能的原因包括本地系统时间设置不正确，建议重新设置本地系统时间再重新加入频道。如需更多帮助，请。 diff --git a/dita/RTC-NG/config/keys-rtc-ng-api-cpp.ditamap b/dita/RTC-NG/config/keys-rtc-ng-api-cpp.ditamap index adfa5997ce0..af845af9d13 100644 --- a/dita/RTC-NG/config/keys-rtc-ng-api-cpp.ditamap +++ b/dita/RTC-NG/config/keys-rtc-ng-api-cpp.ditamap @@ -7611,13 +7611,6 @@ - - - - CONNECTION_CHANGED_CERTIFICATION_VERYFY_FAILURE - - - From cc63adc83ee3a3e2ebe70b642ba5e6d815fbf6d6 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Tue, 19 Sep 2023 15:56:20 +0800 Subject: [PATCH 17/28] =?UTF-8?q?modify=20=E7=BB=84=E4=BB=B6=E4=BB=8B?= =?UTF-8?q?=E7=BB=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...Karaoke API \345\217\202\350\200\203-android.md" | 13 ++++++------- ...\273\204\344\273\266\344\273\213\347\273\215.md" | 11 ++++++----- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" index 7092aff518a..729c930887b 100644 --- "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" +++ "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" @@ -2,7 +2,7 @@ 本文介绍 AUIKitKaraoke 组件的 API。 -源码文件？ +源码文件？//TODO https://github.com/AgoraIO-Community/AUIKaraoke/blob/main/Android/asceneskit/src/main/java/io/agora/asceneskit/karaoke/KaraokeUiKit.kt ## KaraokeUIKit @@ -42,13 +42,13 @@ fun createRoom( 创建 K 歌房间。 -在 K 歌场景下，创建房间的人自动成为房主。成功创建房间后，会返回创建的房间信息。//TODO +在 K 歌场景下，创建房间的人自动成为房主。成功创建房间后，会返回创建的房间信息。//TODO input里面是这么写的，但是这个方法应该没有返回值..？ **参数** - `createRoomInfo`：房间信息，详见 [AUICreateRoomInfo](#AUICreateRoomInfo)。 - `success`：回调函数，当房间创建成功时调用。接受一个 `AUIRoomInfo` 参数，表示成功创建的房间信息，无返回值。//TODO -- `failure`：回调函数，当房间创建失败时调用。接受一个 `AUIException` 参数表示房间创建失败的异常， 无返回值。 +- `failure`：回调函数，当房间创建失败时调用。接受一个 `AUIException` 参数表示房间创建失败的异常，无返回值。 ### getRoomList @@ -164,8 +164,8 @@ public class AUICreateRoomInfo implements Serializable { ```kotlin public class AUIRoomInfo extends AUICreateRoomInfo implements Serializable { - public @NonNull String roomId = ""; - public @Nullable AUIUserThumbnailInfo roomOwner; + public @NonNull String roomId = ""; + public @Nullable AUIUserThumbnailInfo roomOwner; public int onlineUsers = 0; public long createTime = 0; } @@ -178,7 +178,7 @@ public class AUIRoomInfo extends AUICreateRoomInfo implements Serializable { - `roomId`：房间 ID。 - `roomOwner`：房主信息，详见 [AUIUserThumbnailInfo](#AUIUserThumbnailInfo)。 - `onlineUsers`：房间内的人数。 -- `createTime`：房间创建的时间（单位？//TODO） +- `createTime`：房间创建的时间（单位 ms？//TODO） ###

    AUIUserThumbnailInfo

    @@ -269,4 +269,3 @@ public class AUIRoomConfig { - \ No newline at end of file diff --git "a/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" "b/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" index c896e1e8724..3e8af2dff88 100644 --- "a/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" +++ "b/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" @@ -2,9 +2,9 @@ ## 组件概述 -AUIKaraoke 是声网针对 K 歌场景推出的开源 UI 组件，集成了 [K 歌房场景化 API]() 以及声网实时互动 SDK、RTM SDK 的核心功能。该组件基于 [AUIKit](https://github.com/AgoraIO-Community/AUIKit/tree/main) 开发，主要提供房间管理功能。 +AUIKaraoke 是声网针对 K 歌场景推出的开源 UI 组件，集成了 [K 歌房场景化 API]() 以及声网实时互动 SDK、RTM SDK。该组件基于 [AUIKit](https://github.com/AgoraIO-Community/AUIKit/tree/main) 开发，主要提供房间管理功能。AUIKit 是一套场景化应用的脚手架，为 AUIKaraoke 提供可自定义的 UI 组件和一套通用的服务接口（Service），支持你基于 UI 组件像搭积木一样快速搭建起自己的业务逻辑。 -AUIKit 是一套场景化应用的脚手架，为 AUIKaraoke 提供可自定义的 UI 组件和一套通用的服务接口（Service），包括用户、麦位、合唱、播放管理。你可以查看 AUIKaraoke [组件源码](https://github.com/AgoraIO-Community/AUIKitKaraoke)快速搭建一个含 UI 界面的在线 K 歌房间，体验在线点歌、 K 歌、麦位管理、收发礼物、文字聊天等在线 K 歌场景中的核心交互。 +你可以查看 AUIKaraoke [组件源码](https://github.com/AgoraIO-Community/AUIKitKaraoke)快速搭建一个含 UI 界面的在线 K 歌房间，体验在线点歌、 K 歌、麦位管理、收发礼物、文字聊天等在线 K 歌场景中的核心交互。 下图展示 AUIKaraoke 和 AUIKit 之间的关系：（等确认好内容之后再优化图片） @@ -61,8 +61,9 @@ AUIKaraoke 提供下列核心功能： image-20230918151926230 -## 优势 - ## 方案对比 -除了 AUIKaraoke 这一含 UI 的解决方案，目前声网针对在线 K 歌房场景还提供了无 UI 解决方案，其中无 UI 解决方案包括[无场景化方案](https://confluence.agoralab.co/)、[场景化 API 方案](https://confluence.agoralab.co/)，各方案之间的对比详见[方案对比]()。 \ No newline at end of file +除了 AUIKaraoke 这一含 UI 的解决方案，目前声网针对在线 K 歌房场景还提供了无 UI 解决方案，其中无 UI 解决方案包括[无场景化方案](https://confluence.agoralab.co/)、[场景化 API 方案](https://confluence.agoralab.co/)，各方案之间的对比详见[方案对比]()。 + + + From 62c6cda49f67c265bf3d067dc69e3c9e22a41780 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Wed, 20 Sep 2023 14:19:53 +0800 Subject: [PATCH 18/28] fix cs comments --- dita/RTC-NG/API/api_imediaplayer_getstreamcount.dita | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dita/RTC-NG/API/api_imediaplayer_getstreamcount.dita b/dita/RTC-NG/API/api_imediaplayer_getstreamcount.dita index 93254aa3690..332f9f965ce 100644 --- a/dita/RTC-NG/API/api_imediaplayer_getstreamcount.dita +++ b/dita/RTC-NG/API/api_imediaplayer_getstreamcount.dita @@ -24,7 +24,7 @@
    详情 - 你需要在 后调用该方法。
    + 请在 后并收到 回调报告播放状态为 后再调用调用该方法。
    参数 @@ -41,4 +41,4 @@
  • < 0: 方法调用失败，详见 。
    • - \ No newline at end of file + From bf37391c6b90f684daec0a29c47c5f418a62459f Mon Sep 17 00:00:00 2001 From: Suri539 Date: Wed, 20 Sep 2023 14:34:14 +0800 Subject: [PATCH 19/28] Revert "fix cs comments" This reverts commit 62c6cda49f67c265bf3d067dc69e3c9e22a41780. --- dita/RTC-NG/API/api_imediaplayer_getstreamcount.dita | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dita/RTC-NG/API/api_imediaplayer_getstreamcount.dita b/dita/RTC-NG/API/api_imediaplayer_getstreamcount.dita index 332f9f965ce..93254aa3690 100644 --- a/dita/RTC-NG/API/api_imediaplayer_getstreamcount.dita +++ b/dita/RTC-NG/API/api_imediaplayer_getstreamcount.dita @@ -24,7 +24,7 @@
    详情 - 请在 后并收到 回调报告播放状态为 后再调用调用该方法。
    + 你需要在 后调用该方法。
    参数 @@ -41,4 +41,4 @@
  • < 0: 方法调用失败，详见 。
    • - + \ No newline at end of file From c2c343c13b9a92a5e544d0633c775191637665eb Mon Sep 17 00:00:00 2001 From: Suri539 Date: Wed, 20 Sep 2023 17:21:12 +0800 Subject: [PATCH 20/28] technical review done --- ...e API \345\217\202\350\200\203-android.md" | 71 ++++++----- ...04\344\273\266\344\273\213\347\273\215.md" | 30 +++-- .../android-\351\233\206\346\210\220.md" | 118 ++++++++---------- 3 files changed, 105 insertions(+), 114 deletions(-) diff --git "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" index 729c930887b..c5dad65f238 100644 --- "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" +++ "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" @@ -1,8 +1,6 @@ -# AUIKitKaraoke Kotlin API (Android) +# AUIKaraoke Kotlin API (Android) -本文介绍 AUIKitKaraoke 组件的 API。 - -源码文件？//TODO https://github.com/AgoraIO-Community/AUIKaraoke/blob/main/Android/asceneskit/src/main/java/io/agora/asceneskit/karaoke/KaraokeUiKit.kt +本文介绍 AUIKaraoke 组件的 API。你可以在 GitHub 上查看[源码文件](https://github.com/AgoraIO-Community/AUIKaraoke/blob/main/Android)。 ## KaraokeUIKit @@ -42,12 +40,12 @@ fun createRoom( 创建 K 歌房间。 -在 K 歌场景下，创建房间的人自动成为房主。成功创建房间后，会返回创建的房间信息。//TODO input里面是这么写的，但是这个方法应该没有返回值..？ +在 K 歌场景下，创建房间的人自动成为房主。异步调用成功后，会返回成功创建的房间信息。 **参数** - `createRoomInfo`：房间信息，详见 [AUICreateRoomInfo](#AUICreateRoomInfo)。 -- `success`：回调函数，当房间创建成功时调用。接受一个 `AUIRoomInfo` 参数，表示成功创建的房间信息，无返回值。//TODO +- `success`：回调函数，当房间创建成功时调用。接受一个 `AUIRoomInfo` 参数，表示成功创建的房间信息，无返回值。 - `failure`：回调函数，当房间创建失败时调用。接受一个 `AUIException` 参数表示房间创建失败的异常，无返回值。 ### getRoomList @@ -67,10 +65,10 @@ fun getRoomList( **参数** -- `startTime`：开始时间 //TODO 是指获取某一特定时间之后创建的房间列表吗？ -- `pageSize`：房间列表页数，默认从 0 还是从 1开始？//TODO +- `startTime`：房间创建的时间。 +- `pageSize`：每一页房间列表所展示的房间数量。 - `success`：回调函数，当成功获取到 K 歌房间列表时调用，会返回一个房间信息列表，详见 [AUIRoomInfo](#AUIRoomInfo)。 -- `failure`：回调函数，当房间创建失败时调用。接受一个 `AUIException` 参数表示房间创建失败的异常， 无返回值。 +- `failure`：回调函数，当房间创建失败时调用。接受一个 `AUIException` 参数表示房间创建失败的异常， 无返回值。 ### launchRoom @@ -110,9 +108,7 @@ fun destroyRoom(roomId: String?) fun release() ``` -释放 `scenekit` 资源。 - -//TODO 和destroyRoom 方法之间是否有调用先后时序要求。 +释放 AUIKaraoke 的所有资源。 ## 数据模型 @@ -142,11 +138,11 @@ public class AUICommonConfig { ```kotlin public class AUICreateRoomInfo implements Serializable { - public @NonNull String roomName = ""; //房间名称 - public @NonNull String thumbnail = ""; //房间列表上的缩略图 - public int micSeatCount = 8; //麦位个数 - public @Nullable String password; //房间密码 - public String micSeatStyle = ""; //麦位样式 + public @NonNull String roomName = ""; + public @NonNull String thumbnail = ""; + public int micSeatCount = 8; + public @Nullable String password; + public String micSeatStyle = ""; } ``` @@ -155,10 +151,10 @@ public class AUICreateRoomInfo implements Serializable { **参数** - `roomName`：房间名。 -- `thumbnail`：房间列表上的缩略图？是指用户头像图片的url吗？ -- `micSeatCount`：房间中的麦位数量。//TODO 是否有取值范围？ +- `thumbnail`：房间列表上指用户头像的 URL。 +- `micSeatCount`：房间中的麦位数量，取值范围 [1-8]。 - `password`：房间密码。 -- `micSeatStyle`：麦位样式//TODO 什么样式？ +- `micSeatStyle`：房间中麦位的排列样式。 ###

    AUIRoomInfo

    @@ -178,7 +174,7 @@ public class AUIRoomInfo extends AUICreateRoomInfo implements Serializable { - `roomId`：房间 ID。 - `roomOwner`：房主信息，详见 [AUIUserThumbnailInfo](#AUIUserThumbnailInfo)。 - `onlineUsers`：房间内的人数。 -- `createTime`：房间创建的时间（单位 ms？//TODO） +- `createTime`：房间创建的时间，单位为毫秒。 ###

    AUIUserThumbnailInfo

    @@ -210,7 +206,7 @@ public AUIException(int code, String message) **参数** -- `code`：错误码// TODO 有哪些？ +- `code`：错误码。 - `message`：错误信息。 ###

    AUIRoomConfig

    @@ -239,33 +235,44 @@ public class AUIRoomConfig { **参数** -- `channelName`：主频道名，一般为 `roomId`。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。 +- `channelName`：RTM 频道的频道名，该频道用于同步数据信息、传输信令。 -- `rtmToken`：加入主频道时的 RTM Token。//TODO 这个 token 是用于什么鉴权？ +- `rtmToken`：登陆 RTM 系统时用的 RTM Token。 - 请确保你使用的 RTM Token 是 AccessToken2。 + 请确保你使用的 RTM Token 是 AccessToken2。//TODO 搬到新站后加相应的文档链接 -- `rtcToken`：加入主频道时用于鉴权的 RTC Token。 +- `rtcToken`：加入 RTM 频道时使用的 RTC Token。 + + + 请确保你使用的 RTC Token 是 AccessToken2。//TODO 搬到新站后加相应的文档链接 + + -- `rtcChannelName`：音视频频道名，一般为{roomId}_rtc。//TODO 音视频频道和主频道之间有什么区别？ +- `rtcChannelName`：主频道的频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。 -- `rtcRtcToken`： +- `rtcRtcToken`：加入主频道的 RTC Token。 + + + + 请确保你使用的 RTC Token 是 AccessToken2。//TODO 搬到新站后加相应的文档链接 + + -- `rtcRtmToken`：用于音乐内容中心鉴权的 RTM Token。 +- `rtcRtmToken`：RTM Token，用于音乐内容中鉴权。 - 请确保你使用的 RTM Token 是 AccessToken。//rtc mcc 使用是啥意思？ + 请确保你使用的 RTM Token 是 AccessToken。详见 使用 RTM Token 鉴权 -- `rtcChorusChannelName`：合唱频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。//TODO 独唱场景下，这个参数为空？ +- `rtcChorusChannelName`：合唱频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。独唱场景下，该参数可为空。 -- `rtcChorusRtcToken`：根据合唱频道名和用户 ID 生成的 RTC Token，用于加入合唱频道时进行鉴权。//TODO 在独唱场景下，该参数可以为空？ +- `rtcChorusRtcToken`：根据合唱频道名和用户 ID 生成的 RTC Token，用于加入合唱频道时进行鉴权。独唱场景下，该参数可为空。 diff --git "a/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" "b/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" index 3e8af2dff88..5f4ea0e6b6a 100644 --- "a/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" +++ "b/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" @@ -6,24 +6,20 @@ AUIKaraoke 是声网针对 K 歌场景推出的开源 UI 组件，集成了 [K 你可以查看 AUIKaraoke [组件源码](https://github.com/AgoraIO-Community/AUIKitKaraoke)快速搭建一个含 UI 界面的在线 K 歌房间，体验在线点歌、 K 歌、麦位管理、收发礼物、文字聊天等在线 K 歌场景中的核心交互。 -下图展示 AUIKaraoke 和 AUIKit 之间的关系：（等确认好内容之后再优化图片） +下图展示 AUIKaraoke 和 AUIKit 之间的关系： -image-20230915152008777 + -1. App：接入 AUIKaraoke 的项目，其中 +1. App：接入 AUIKaraoke 的项目 - - RoomListActivity 是房间列表页 +2. AUIKaraoke：以源码方式集成的库，可在上面进行自定义，其中 - - RoomDetailActivity 是房间详情页（意思是通过这两个类来和 scenekit 交互吗？） + - `KaraokeUIKit` 负责房间管理以及 Service、View 的统一调度 + - `KaraokeRoomView` 是默认的 K 歌房 View。你可以根据需求进行自定义修改。 + - binder 负责将 Service 和 UI 逻辑绑定起来。 + - `AUIKiaraokeRoomService` 负责管理用到的 AUIKit 提供的 Service。 -2. AScenesKit：以源码方式集成的库，可在上面进行自定义，（和 AUIKaraoke 的关系是什么？）其中 - - 1. KaraokeUIKit 负责房间管理以及 Service、View 的统一调度 - 2. KaraokeRoomView 是默认的 K 歌房 View。你可以根据需求进行自定义修改。 - 3. binder 负责将 service 和 ui 逻辑绑定起来 - 4. AUIKiaraokeRoomService 负责管理用到的 AUIKit Service - -3. AUIKit 是一个基础库，包含Service 和 UI 两部分，为上层提供基础业务能力和 UI 组件。 +3. AUIKit：基础库，包含 Service 和 UI 两部分，为上层提供基础业务能力和 UI 组件。 ## 核心功能 @@ -37,7 +33,7 @@ AUIKaraoke 提供下列核心功能： **麦位管理**： - 上麦和下麦：用户可以随时上下麦，实现多人互动 K 歌。 -- 踢人下麦：房主可以将用户从麦位上踢下来，以管理麦位的占用情况。（是房主可以踢人吗？还是主播也可以？） +- 踢人下麦：房主可以将用户从麦位上踢下来，以管理麦位的占用情况。 - 封禁和锁麦：麦位可以被封禁或锁定，以更好维护 K 歌房间内秩序。 **音乐播放器**： @@ -48,7 +44,7 @@ AUIKaraoke 提供下列核心功能： - 搜索歌曲：通过歌曲或歌手关键词搜索，检索查找自己喜欢的歌曲。声网曲库涵盖 20万+ 正版歌曲。 - 点歌和切歌：用户可以点播自己喜欢的歌曲，并在需要时切换到下一首。 -- 置顶歌曲：房主可以将某首歌曲置顶，确保它在播放列表中优先播放。（上麦的人都可以置顶还是只有房主有权限？） +- 置顶歌曲：房主可以将某首歌曲置顶，确保它在播放列表中优先播放。 **合唱功能**： @@ -59,7 +55,7 @@ AUIKaraoke 提供下列核心功能： **文字聊天**：除了上麦互动，K 歌房间内的用户彼此之间还可以发送文字消息。 -image-20230918151926230 + ## 方案对比 @@ -67,3 +63,5 @@ AUIKaraoke 提供下列核心功能： + + diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" index a040821997e..66dd66e0c73 100644 --- "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" @@ -1,14 +1,8 @@ # 实现在线 K 歌房 -AUIKitKaraoke 是一个基于 [AUIKit](https://github.com/AgoraIO-Community/AUIKit/blob/main/Android/README.zh.md) 搭建的、针对 K 歌场景的开源 UI 组件，提供 K 歌房间相关功能。asceneskit 是 K 歌房的容器组件，你可以通过 asceneskit 自定义 K 歌房间的用户界面逻辑、实现房间管理等。 +AUIKaraoke 是一个基于 [AUIKit](https://github.com/AgoraIO-Community/AUIKit/blob/main/Android/README.zh.md) 搭建的、针对 K 歌场景的开源 UI 组件，提供 K 歌房间相关功能。asceneskit 是 K 歌房的容器组件，你可以通过 asceneskit 自定义 K 歌房间的用户界面逻辑、实现房间管理等。 -下图展示组件之间的关系图： - - - -- AUIKit 是一个基础库，包含 Service 和 UI 两部分，为上层提供麦位管理、音乐播放、歌曲管理、合唱管理等能力及对应的 UI 模块。 - -本文介绍如何通过 [AUIKitKaraoke 组件](#link-to-description)快速搭建一个含 UI 界面的在线 K 歌房。 +本文介绍如何通过 [AUIKaraoke 组件](#link-to-description)快速搭建一个含 UI 界面的在线 K 歌房。 下图展示搭建 K 歌房间的完整流程： @@ -32,8 +26,8 @@ AUIKitKaraoke 是一个基于 [AUIKit](https://github.com/AgoraIO-Community/AUIK - 有效的声网[开发者账号](https://docs.agora.io/cn/Agora Platform/sign_in_and_sign_up)和声网项目，请参考[开始使用声网平台](https://docs.agora.io/cn/Agora Platform/get_appid_token?platform=All Platforms)，从声网控制台获取以下信息： - App ID：声网随机生成的字符串，用于识别你的 app。 - - 临时 Token：你的 app 客户端加入频道时会使用 Token 对用户进行鉴权。临时 Token 的有效期为 24 小时。 - - rtm token xxxx + - RTC Token：在你的业务服务器上生成的 RTC Token。你的 app 客户端加入频道时会使用 Token 对用户进行鉴权。 + - RTM Token（refer 到 rtm token 文档） ### 创建项目 @@ -45,67 +39,65 @@ AUIKitKaraoke 是一个基于 [AUIKit](https://github.com/AgoraIO-Community/AUIK ### 集成组件 -2. 集成 asceneskit。 +1. 将 [asceneskit 文件夹](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main/Android/asceneskit)复制到你的项目中。 - 1. 将 [asceneskit 文件夹](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main/Android/asceneskit)复制到你的项目中。 +2. 在 `settings.gradle` 文件中添加 `asceneskit` 库： - 2. 在 `settings.gradle` 文件中添加 asceneskit 库： + ```java + include ':asceneskit' + ``` - ```java - include ':asceneskit' - ``` +3. 在 `build.grade` 文件中添加以下依赖： - 3. 在 `build.grade` 文件中添加以下依赖： + ```java + dependencies { + implementation project(':asceneskit') + } + ``` - ```java - dependencies { - implementation project(':asceneskit') - } - ``` +4. 添加权限并设置主题。在你的 `AndroidManifest.xml` 文件中添加下列内容： - 4. 添加权限并设置主题。在你的 `AndroidManifest.xml` 文件中添加下列内容： + ```java + - ```java - + + + + + + + + - - - - - - - - + - + ... - ... + - + + ``` - - ``` +5. 配置你的业务服务器域名。在你的项目的 `local.properties` 文件中添加你的业务服务器域名。你可以参考[后台服务](https://github.com/AgoraIO-Community/AUIKitKaraoke/blob/main/backend/README_zh.md)来搭建你的业务服务器，也可以使用声网用于测试的域名来体验：https://service.agora.io/uikit-karaoke - 5. 配置你的业务服务器域名。在你的项目的 `local.properties` 文件中添加你的业务服务器域名。你可以参考[后台服务](https://github.com/AgoraIO-Community/AUIKitKaraoke/blob/main/backend/README_zh.md)来搭建你的业务服务器，也可以使用声网用于测试的域名来体验：https://service.agora.io/uikit-karaoke + ![image-20230830113539829](/Users/admin/Library/Application Support/typora-user-images/image-20230830113539829.png) - ![image-20230830113539829](/Users/admin/Library/Application Support/typora-user-images/image-20230830113539829.png) - - ```java - SERVER_HOST=你的业务服务器域名 - ``` + ```java + SERVER_HOST=你的业务服务器域名 + ``` ## 实现在线 K 歌房 -下图展示了创建一个在线 K 歌房的 API 调用时序： +下图展示了创建一个在线 K 歌房的 API 调用时序：（这个是时序图里面的KaraokeUiKit 后续都会统一改为 AUIKaraoke） image-20230830161719228 -### 1. 初始化 KaraokeUiKit +### 1. 初始化 AUIKaraoke -创建 `AUiCommonConfig` 对象，调用 `setup` 初始化 KaraokeUiKit。 +创建 `AUiCommonConfig` 对象，调用 `setup` 初始化 AUIKaraoke。 ```java // 创建 AUiCommonConfig 对象 @@ -156,8 +148,8 @@ KaraokeUiKit.createRoom( 调用 `getRoomList` 获取已创建房间的列表。 ```kotlin -// 获取房间列表 TODO 这里的参数名是lastCreateTime，但是api参考以及代码仓库里面都是startTime -KaraokeUiKit.getRoomList(lastCreateTime, 10, +// 获取房间列表 +KaraokeUiKit.getRoomList(startTime, 10, // 房间创建成功时调用 success = { roomList -> runOnUiThread { @@ -184,14 +176,15 @@ KaraokeUiKit.getRoomList(lastCreateTime, 10, val roomInfo : AUIRoomInfo val karaokeRoomView: KaraokeRoomView val config = AUiRoomConfig(roomInfo.roomId) -// 生成config.channelName及AUIRoomContext.shared().currentUserInfo.userId的token +// 登陆 RTM 时用的 RTM AccessToken2 config.rtmToken = "" +// 加入 RTM 频道时用的 RTC AccessToken2 config.rtcToken = "" -// 生成config.rtcChannelName及AUIRoomContext.shared().currentUserInfo.userId的token +// RTM AccessToken，用于音乐内容中心鉴权 config.rtcRtmToken = "" -// +//加入主频道用的 RTC AccessToken2 config.rtcRtcToken = "" -// 生成config.rtcChorusChannelName及AUIRoomContext.shared().currentUserInfo.userId的token +// 加入合唱频道用的 RTC AccessToken2 config.rtcChorusRtcToken = "" // 拉起房间 KaraokeUiKit.launchRoom( @@ -199,13 +192,6 @@ KaraokeUiKit.launchRoom( config, karaokeRoomView ) - -// 订阅房间事件 -KaraokeUiKit.bindRespDelegate(object: AUIRoomManagerRespDelegate{ - override fun onRoomDestroy(roomId: String){ - // 房间被销毁 - } -}) ``` ### 5. 销毁房间 @@ -213,11 +199,11 @@ KaraokeUiKit.bindRespDelegate(object: AUIRoomManagerRespDelegate{ K 歌结束后，调用 `destroyRoom` 销毁房间。 ```kotlin +// 销毁房间 KaraokeUiKit.destroyRoom(roomId) -// 取消订阅房间事件 -KaraokeUiKit.unbindRespDelegate(this@RoomActivity) // auikit的接口 ``` ## 示例项目 -声网在 GitHub 上提供一个开源的示例项目 [AUIKitKaraoke](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main/Android) 供你参考。 \ No newline at end of file +声网在 GitHub 上提供一个开源的示例项目 [AUIKitKaraoke](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main/Android) 供你参考。 + From 2ee96f05dac34dc9d85126a21798bcd79d937095 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Mon, 25 Sep 2023 18:19:03 +0800 Subject: [PATCH 21/28] add iOS --- ...e API \345\217\202\350\200\203-android.md" | 4 +- .../AUIKitKaraoke Objective-C API.md | 46 ++++++------ .../ios-\351\233\206\346\210\220.md" | 72 +++++++++++++++++-- ...57\345\214\226 Objective-C API for iOS.md" | 2 +- 4 files changed, 94 insertions(+), 30 deletions(-) diff --git "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" index c5dad65f238..832f3b3728a 100644 --- "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" +++ "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" @@ -254,7 +254,7 @@ public class AUIRoomConfig { - `rtcChannelName`：主频道的频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。 -- `rtcRtcToken`：加入主频道的 RTC Token。 +- `rtcRtcToken`：加入主频道的 RTC Token。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流。 @@ -266,7 +266,7 @@ public class AUIRoomConfig { - 请确保你使用的 RTM Token 是 AccessToken。详见 使用 RTM Token 鉴权 + 请确保你使用的 RTM Token 是 AccessToken。详见 使用 RTM Token 鉴权。 diff --git a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md index 19e6d11ef04..d6abb5ec2f3 100644 --- a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md +++ b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md @@ -1,8 +1,6 @@ # AUIKitKaraoke swift API（iOS） -本文介绍 AUIKitKaraoke 组件的 API。 - -源码文件？ +本文介绍 AUIKaraoke 组件的 API。你可以在 GitHub 上查看[源码文件](https://github.com/AgoraIO-Community/AUIKaraoke/tree/main/iOS)。 ## KaraokeUIKit @@ -38,7 +36,7 @@ func createRoom(roomInfo: AUICreateRoomInfo, 创建 K 歌房间。 -在 K 歌场景下，创建房间的人自动成为房主。成功创建房间后，会返回创建的房间信息。//TODO +在 K 歌场景下，创建房间的人自动成为房主。成功创建房间后，会返回创建的房间信息。 **参数** @@ -60,8 +58,8 @@ func getRoomInfoList(lastCreateTime: Int64?, **参数** -- `lastCreateTime`：（可选）开始时间 //TODO 是指获取某一特定时间之后创建的房间列表吗？ -- `pageSize`：房间列表页数，默认从 0 还是从 1开始？//TODO +- `lastCreateTime`：（可选）房间创建的时间。 +- `pageSize`：每一页房间列表所展示的房间数量。 - `callback`：用于处理获取房间列表结果的回调闭包，该闭包在函数执行完成后仍然可以被调用。回调闭包接受一个 `AUIRoomListCallback` 对象作为参数。//TODO ### launchRoom @@ -138,7 +136,7 @@ K 歌房间的相关信息。 - `roomId`：房间 ID。 - `roomOwner`：房主信息，详见 [AUIUserThumbnailInfo](#AUIUserThumbnailInfo)。 - `onlineUsers`：房间内的人数。 -- `createTime`：房间创建的时间（单位？//TODO） +- `createTime`：房间创建的时间，单位为毫秒。 ###

    AUIUserThumbnailInfo

    @@ -149,13 +147,13 @@ open class AUIUserThumbnailInfo: NSObject,AUIUserCellUserDataProtocol { public var userName: String = "" //用户名 public var userAvatar: String = "" //用户头像 public var seatIndex: Int = -1 //用户是否在麦上 - public var isOwner: Bool = false //是否是owner + public var isOwner: Bool = false //是否是owner TODO owner是指房主吗？但是这个本来就是房主相关信息了 public func isEmpty() -> Bool { guard userId.count > 0, userName.count > 0 else {return true} return false - } + } //TODO } ``` @@ -166,10 +164,8 @@ K 歌中房主的相关信息。//TODO 原型和input给的参数不一致 - `userId`：房主的 ID。 - `userName`：房主的用户名。 - `userAvatar`：房主的头像。 - -###

    AUIException

    - -//TODO iOS没有这个 +- `seatIndex`：int 类型参数，有哪些取值？ +- `isOwner`： ###

    AUIRoomConfig

    @@ -190,33 +186,39 @@ open class AUIRoomConfig: NSObject { **参数** -- `channelName`：主频道名，一般为 `roomId`。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。 +- `channelName`：RTM 频道的频道名，该频道用于同步数据信息、传输信令。 -- `rtmToken007`：加入主频道时的 RTM Token。//TODO 这个 token 是用于什么鉴权？ +- `rtmToken007`：登陆 RTM 系统时用的 RTM Token。 请确保你使用的 RTM Token 是 AccessToken2。 - +- `rtcToken007`：（rtm login 用）加入主频道的 RTC Token。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流。// 这个token和下面的 rtcrtctoken 可以为同一个吗？ -- `rtcToken007`：加入主频道时用于鉴权的 RTC Token。 +- `rtcChannelName`：主频道的频道名。 -- `rtcChannelName`：音视频频道名，一般为{roomId}_rtc。//TODO 音视频频道和主频道之间有什么区别？ +- `rtcRtcToken`：加入主频道的 RTC Token。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流。 -- `rtcRtcToken`： + + + 请确保你使用的 RTC Token 是 AccessToken2。//TODO 搬到新站后加相应的文档链接 + + - `rtcRtmToken`：用于音乐内容中心鉴权的 RTM Token。 - 请确保你使用的 RTM Token 是 AccessToken。//rtc mcc 使用是啥意思？ + 请确保你使用的 RTM Token 是 AccessToken。详见 使用 RTM Token 鉴权。 -- `rtcChorusChannelName`：合唱频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。//TODO 独唱场景下，这个参数为空？ +- `rtcChorusChannelName`：合唱频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。独唱场景下，该参数可为空。 + +- `rtcChorusRtcToken`：根据合唱频道名和用户 ID 生成的 RTC Token，用于加入合唱频道时进行鉴权。独唱场景下，该参数可为空。 -- `rtcChorusRtcToken`：根据合唱频道名和用户 ID 生成的 RTC Token，用于加入合唱频道时进行鉴权。//TODO 在独唱场景下，该参数可以为空？ +//TODO Java 有 aui exception 表述错误码和错误信息，ios 有类似的 api 吗？ diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" index 9b8c1b95914..c2125ffc08c 100644 --- "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" @@ -6,7 +6,7 @@ ## 准备开发环境 -//todo https://github.com/AgoraIO-Community/AUIKitKaraoke/blob/main/iOS/doc/KaraokeUIKit_zh.md input里面的前提条件是已经跑通demo +//todo h ttps://github.com/AgoraIO-Community/AUIKitKaraoke/blob/main/iOS/doc/KaraokeUIKit_zh.md input 里面的前提条件是已经跑通demo，新建一个空项目不可以吗？ ### 前提条件 @@ -57,7 +57,7 @@ ![image-20230911163222007](/Users/admin/Library/Application Support/typora-user-images/image-20230911163222007.png) ​ -
    • Value 值填写使用麦克风或摄像头的目的即可。
    • 如果你的项目中需要添加第三方插件或库（例如第三方摄像头），且该插件或库的签名与项目的签名不一致，你还需勾选 Hardened Runtime > Runtime Exceptions 中的 Disable Library Validation。
    • 更多注意事项，可参考 Preparing Your App for Distribution。
    +​
    • Value 值填写使用麦克风或摄像头的目的即可。
    • 如果你的项目中需要添加第三方插件或库（例如第三方摄像头），且该插件或库的签名与项目的签名不一致，你还需勾选 Hardened Runtime > Runtime Exceptions 中的 Disable Library Validation。
    • 更多注意事项，可参考 Preparing Your App for Distribution。
    ​     ### 集成组件 @@ -79,15 +79,19 @@ ### 1. 初始化 KaraokeUiKit -创建 `AUiCommonConfig` 对象。//TODO 不用调setup吗❓ +创建 `AUiCommonConfig` 对象。//TODO 这一步已经做了初始化了吗？ ```swift let commonConfig = AUICommonConfig() +// 你的业务服务器域名 commonConfig.host = KeyCenter.HostUrl +// 用户 ID commonConfig.userId = userInfo.userId +// 用户名 commonConfig.userName = userInfo.userName +// 用户头像 commonConfig.userAvatar = userInfo.userAvatar -//rtmClient可空 +// rtmClient 可为空 let roomManager = AUIRoomManagerImpl(commonConfig: roomConfig, rtmClient: rtmClient) ``` @@ -99,12 +103,70 @@ let roomManager = AUIRoomManagerImpl(commonConfig: roomConfig, rtmClient: rtmCli let room = AUICreateRoomInfo() // 房间名称 room.roomName = text -// +// 房主信息 room.thumbnail = userInfo.userAvatar +// 麦位数量 room.seatCount = 8 roomManager.createRoom(room: roomInfo) { error, info in } ``` +### 3. 获取房间列表 +调用 `getRoomList` 获取已创建房间的列表。你可以通过 `lastCreateTime` 指定房间创建的时间，从而筛选出某一时间之后创建的房间列表，还可以通过 `pageSize` 参数设置每一页展示的房间数量。 +```swift +roomManager.getRoomInfoList(lastCreateTime: lastCreateTime, pageSize: pageSize, callback: callback) +``` + +### 4. 拉起房间 + +调用 `launchRooom` 拉起房间。至此，你已经成功搭建一个带有 UI 界面的在线 K 歌房间。 + +在调用该方法前，你需要先调用 getRoomList 获取房间列表及相关房间信息。 + +```swift +let uid = KaraokeUIKit.shared.roomConfig?.userId ?? "" +// 创建房间容器 +let karaokeView = AUIKaraokeRoomView(frame: self.view.bounds) +// 通过 generateToken 方法获取到必须的token和appid //TODO 这里生成的 token 是 rtc token还是 rtm token？ +generateToken { roomConfig, appId in + KaraokeUIKit.shared.launchRoom(roomInfo: self.roomInfo!, + appId: appId, + config: roomConfig, + karaokeView: karaokeView) +} +``` + +### 5. 销毁房间 + +K 歌结束后，你可以调用 `destroyRoom` 销毁当前房间。 + +```swift +//AUIKaraokeRoomView 提供了 onClickOffButton 点击返回的 clousure TODO +karaokeView.onClickOffButton = { [weak self] in + self.navigationController?.popViewController(animated: true) + KaraokeUIKit.shared.destoryRoom(roomId: self.roomInfo?.roomId ?? "") +} +``` + +### 6. token 过期处理 //TODO 这个回调需要写文档吗 + +```swift +//在KaraokeUIKit.shared.launchRoom之后订阅AUIRtmErrorProxyDelegate的回调 +KaraokeUIKit.shared.subscribeError(roomId: self.roomInfo?.roomId ?? "", delegate: self) + +//在退出房间时取消订阅 +KaraokeUIKit.shared.unsubscribeError(roomId: self.roomInfo?.roomId ?? "", delegate: self) + +//然后通过AUIRtmErrorProxyDelegate回调方法中的onTokenPrivilegeWillExpire来renew所有的token +@objc func onTokenPrivilegeWillExpire(channelName: String?) { + generatorToken { config, _ in + KaraokeUIKit.shared.renew(config: config) + } +} +``` + +## 示例项目 + +声网在 GitHub 上提供一个开源的示例项目 [AUIKitKaraoke](https://github.com/AgoraIO-Community/AUIKaraoke/tree/main/iOS) 供你参考。 \ No newline at end of file diff --git "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Objective-C API for iOS.md" "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Objective-C API for iOS.md" index 60010afe98b..38271efa894 100644 --- "a/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Objective-C API for iOS.md" +++ "b/markdown/online-ktv/\346\224\271\350\277\233/\345\234\272\346\231\257\345\214\226\346\226\271\346\241\210/iOS/K \346\255\214\346\210\277\345\234\272\346\231\257\345\214\226 Objective-C API for iOS.md" @@ -633,7 +633,7 @@ K 歌的场景： -#### loadMusicType +### loadMusicType ```objective-c @objc public enum loadMusicType: Int { From 7bf3ee1fe4708fba1e4ae493d6a1db40f2bd172d Mon Sep 17 00:00:00 2001 From: Suri539 Date: Tue, 26 Sep 2023 16:19:43 +0800 Subject: [PATCH 22/28] ios docs --- ...e API \345\217\202\350\200\203-android.md" | 6 -- .../AUIKitKaraoke Objective-C API.md | 41 +++++-------- .../AUIKaraoke/demo/AUIKaraoke-demo-iOS.md | 4 +- .../ios-\351\233\206\346\210\220.md" | 60 +++++++++++-------- .../android-\351\233\206\346\210\220.md" | 6 +- 5 files changed, 57 insertions(+), 60 deletions(-) rename "markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" => "markdown/online-ktv/AUIKaraoke/ios-\351\233\206\346\210\220.md" (75%) diff --git "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" index 832f3b3728a..dead8c1bf2c 100644 --- "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" +++ "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" @@ -264,12 +264,6 @@ public class AUIRoomConfig { - `rtcRtmToken`：RTM Token，用于音乐内容中鉴权。 - - - 请确保你使用的 RTM Token 是 AccessToken。详见 使用 RTM Token 鉴权。 - - - - `rtcChorusChannelName`：合唱频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。独唱场景下，该参数可为空。 - `rtcChorusRtcToken`：根据合唱频道名和用户 ID 生成的 RTC Token，用于加入合唱频道时进行鉴权。独唱场景下，该参数可为空。 diff --git a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md index d6abb5ec2f3..2fde7c680e7 100644 --- a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md +++ b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md @@ -12,7 +12,7 @@ func setup(roomConfig: AUICommonConfig, ktvApi: KTVApiDelegate? = nil, rtcEngine: AgoraRtcEngineKit? = nil, - rtmClient: AgoraRtmClientKit? = nil) + rtmClient: AgoraRtmClientKit? = nil) ``` 初始化 `scenekit`。 @@ -47,8 +47,8 @@ func createRoom(roomInfo: AUICreateRoomInfo, ### getRoomList ```swift -func getRoomInfoList(lastCreateTime: Int64?, - pageSize: Int, +func getRoomInfoList(lastCreateTime: Int64?, + pageSize: Int, callback: @escaping AUIRoomListCallback) ``` @@ -60,7 +60,7 @@ func getRoomInfoList(lastCreateTime: Int64?, - `lastCreateTime`：（可选）房间创建的时间。 - `pageSize`：每一页房间列表所展示的房间数量。 -- `callback`：用于处理获取房间列表结果的回调闭包，该闭包在函数执行完成后仍然可以被调用。回调闭包接受一个 `AUIRoomListCallback` 对象作为参数。//TODO +- `callback`：用于处理获取房间列表结果的回调闭包，在成功获取房间列表结果后会被调用。回调闭包接受一个 `AUIRoomListCallback` 对象作为参数。 ### launchRoom @@ -68,7 +68,7 @@ func getRoomInfoList(lastCreateTime: Int64?, func launchRoom(roomInfo: AUIRoomInfo, appId: String? = nil, config: AUIRoomConfig, - karaokeView: AUIKaraokeRoomView) + karaokeView: AUIKaraokeRoomView) ``` 拉起 K 歌房间。 @@ -122,10 +122,10 @@ open class AUICommonConfig: NSObject { ```kotlin open class AUIRoomInfo: AUICreateRoomInfo { - public var roomId: String = "" - public var owner: AUIUserThumbnailInfo? - public var memberCount: UInt = 0 - public var createTime: Int64 = 0 + public var roomId: String = "" + public var owner: AUIUserThumbnailInfo? + public var memberCount: UInt = 0 + public var createTime: Int64 = 0 } ``` @@ -142,30 +142,28 @@ K 歌房间的相关信息。 ```swift open class AUIUserThumbnailInfo: NSObject,AUIUserCellUserDataProtocol { - + public var userId: String = "" //用户Id public var userName: String = "" //用户名 public var userAvatar: String = "" //用户头像 public var seatIndex: Int = -1 //用户是否在麦上 - public var isOwner: Bool = false //是否是owner TODO owner是指房主吗？但是这个本来就是房主相关信息了 + public var isOwner: Bool = false //是否是owner TODO owner是指房主吗？但是这个本来就是房主相关信息了 后面两个删掉 public func isEmpty() -> Bool { guard userId.count > 0, userName.count > 0 else {return true} - + return false - } //TODO + } } ``` -K 歌中房主的相关信息。//TODO 原型和input给的参数不一致 +K 歌中房主的相关信息。//TODO 原型和input给的参数不一致，研发说之后会删掉后两个参数，明天确认下 **参数** - `userId`：房主的 ID。 - `userName`：房主的用户名。 - `userAvatar`：房主的头像。 -- `seatIndex`：int 类型参数，有哪些取值？ -- `isOwner`： ###

    AUIRoomConfig

    @@ -194,7 +192,7 @@ open class AUIRoomConfig: NSObject { 请确保你使用的 RTM Token 是 AccessToken2。 -- `rtcToken007`：（rtm login 用）加入主频道的 RTC Token。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流。// 这个token和下面的 rtcrtctoken 可以为同一个吗？ +- `rtcToken007`：（rtm login 用）加入主频道的 RTC Token。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流。 - `rtcChannelName`：主频道的频道名。 @@ -208,20 +206,13 @@ open class AUIRoomConfig: NSObject { - `rtcRtmToken`：用于音乐内容中心鉴权的 RTM Token。 - - - 请确保你使用的 RTM Token 是 AccessToken。详见 使用 RTM Token 鉴权。 - - - - `rtcChorusChannelName`：合唱频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。独唱场景下，该参数可为空。 - `rtcChorusRtcToken`：根据合唱频道名和用户 ID 生成的 RTC Token，用于加入合唱频道时进行鉴权。独唱场景下，该参数可为空。 -//TODO Java 有 aui exception 表述错误码和错误信息，ios 有类似的 api 吗？ - \ No newline at end of file + diff --git a/markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-iOS.md b/markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-iOS.md index 4063b864826..fbbe54d3ca5 100644 --- a/markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-iOS.md +++ b/markdown/online-ktv/AUIKaraoke/demo/AUIKaraoke-demo-iOS.md @@ -1,4 +1,4 @@ -声网在 GitHub 上提供一个开源的 [AUIKaraoke 示例项目](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main)。本文介绍如何快速跑通该示例项目，体验在线 K 歌场景。//TODO 和生动互娱的demo的描述之间的差异 +声网在 GitHub 上提供一个开源的 [AUIKaraoke 示例项目](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main)。本文介绍如何快速跑通该示例项目，体验在线 K 歌场景。 ## 前提条件 @@ -68,7 +68,7 @@ git clone git@github.com:AgoraIO-Community/AUIKitKaraoke.git image-20230821174751911 - + ## 常见问题 diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/ios-\351\233\206\346\210\220.md" similarity index 75% rename from "markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" rename to "markdown/online-ktv/AUIKaraoke/ios-\351\233\206\346\210\220.md" index c2125ffc08c..5ea8cedc8de 100644 --- "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/ios-\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/AUIKaraoke/ios-\351\233\206\346\210\220.md" @@ -6,8 +6,6 @@ ## 准备开发环境 -//todo h ttps://github.com/AgoraIO-Community/AUIKitKaraoke/blob/main/iOS/doc/KaraokeUIKit_zh.md input 里面的前提条件是已经跑通demo，新建一个空项目不可以吗？ - ### 前提条件 - [Git](https://git-scm.com/downloads) @@ -29,9 +27,8 @@ - App ID：声网随机生成的字符串，用于识别你的 app。 - 临时 Token：你的 app 客户端加入频道时会使用 Token 对用户进行鉴权。临时 Token 的有效期为 24 小时。 - - rtm Token： -### 创建并配置项目 +### 创建并配置项目 按照下列步骤来创建并配置你的项目。 @@ -43,12 +40,11 @@ 3. 设置部署你的 app 的[目标设备](https://help.apple.com/xcode/mac/current/#/deve69552ee5)。 -4. 在 `KeyCenter.swift` 文件中添加你的业务服务器域名，你也可以直接使用声网测试域名来进行体验：https://service.agora.io/uikit-karaoke。//TODO 这里的测试域名跟demo里面的不一致，要确认下 +4. 在 `KeyCenter.swift` 文件中添加你的业务服务器域名，你也可以直接使用声网测试域名来进行体验：https://service.agora.io/uikit-karaoke。 ```swift struct KeyCenter { - static var HostUrl: String = "https://test-uikit-karaoke.bj2.agoralab.co" - // static var HostUrl: String = "https://service.agora.io/uikit-karaoke" //该域名仅限体验使用，请勿用户正式商用环境 + static var HostUrl: String = "https://service.agora.io/uikit-karaoke" } ``` @@ -64,9 +60,10 @@ 1. 将下列源码复制到你的项目中： - - [AUIKit](https://github.com/AgoraIO-Community/AUIKit/tree/main/iOS) + - [KaraokeUIKit](https://github.com/AgoraIO-Community/AUIKaraoke/blob/main/iOS/Example/AUIKaraoke/KaraokeUIKit.swift) + 加上 karaokeuikit - [AScenesKit](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main/iOS/AScenesKit) - - [KeyCenter.swift](https://github.com/AgoraIO-Community/AUIKitKaraoke/blob/main/iOS/Example/AUIKitKaraoke/KeyCenter.swift)// TODO 为什么这个也要复制？ + - [KeyCenter.swift](https://github.com/AgoraIO-Community/AUIKitKaraoke/blob/main/iOS/Example/AUIKitKaraoke/KeyCenter.swift) 2. 在 Podfile 文件里添加依赖。 @@ -77,22 +74,29 @@ ## 实现在线 K 歌房 -### 1. 初始化 KaraokeUiKit +### 1. 初始化 AUIKaraoke -创建 `AUiCommonConfig` 对象。//TODO 这一步已经做了初始化了吗？ +创建 `AUiCommonConfig` 对象，调用 `setup` 初始化 AUIKaraoke。 ```swift +// 创建 AUiCommonConfig 对象 let commonConfig = AUICommonConfig() // 你的业务服务器域名 commonConfig.host = KeyCenter.HostUrl // 用户 ID -commonConfig.userId = userInfo.userId +commonConfig.userId = userInfo.userId // 用户名 commonConfig.userName = userInfo.userName // 用户头像 commonConfig.userAvatar = userInfo.userAvatar -// rtmClient 可为空 -let roomManager = AUIRoomManagerImpl(commonConfig: roomConfig, rtmClient: rtmClient) +// 初始化 +KaraokeUIKit.shared.setup(roomConfig: commonConfig, + // KtvApi 对象。如果你的项目中还未集成 KtvApi，请传入 nil， AUIKaraoke 内部会自行创建 + ktvApi: nil, + // RtcEngine 对象。如果的你的项目中还未集成声网实时互动 SDK，请传入 AUIKaraoke 内部会自行创建 + rtcEngine: nil, + // RtmClient 对象。如果的你的项目中还未集成声网 RTM SDK，请传入 nil，AUIKaraoke 内部会自行创建 + rtmClient: nil) ``` ### 2. 创建房间 @@ -101,13 +105,18 @@ let roomManager = AUIRoomManagerImpl(commonConfig: roomConfig, rtmClient: rtmCli ```swift let room = AUICreateRoomInfo() -// 房间名称 +// 房间名 room.roomName = text // 房主信息 -room.thumbnail = userInfo.userAvatar +room.thumbnail = self.userInfo.userAvatar // 麦位数量 room.seatCount = 8 -roomManager.createRoom(room: roomInfo) { error, info in +KaraokeUIKit.shared.createRoom(roomInfo: room) { roomInfo in + let vc = RoomViewController() + vc.roomInfo = roomInfo + self.navigationController?.pushViewController(vc, animated: true) +} failure: { error in + //错误提示 } ``` @@ -116,12 +125,15 @@ roomManager.createRoom(room: roomInfo) { error, info in 调用 `getRoomList` 获取已创建房间的列表。你可以通过 `lastCreateTime` 指定房间创建的时间，从而筛选出某一时间之后创建的房间列表，还可以通过 `pageSize` 参数设置每一页展示的房间数量。 ```swift -roomManager.getRoomInfoList(lastCreateTime: lastCreateTime, pageSize: pageSize, callback: callback) +KaraokeUIKit.shared.getRoomInfoList(lastCreateTime: nil, + pageSize: kListCountPerPage, + callback: { error, list in +}) ``` ### 4. 拉起房间 -调用 `launchRooom` 拉起房间。至此，你已经成功搭建一个带有 UI 界面的在线 K 歌房间。 +调用 `launchRooom` 拉起房间。至此，你已经成功搭建一个带有 UI 界面的在线 K 歌房间，你可以 在调用该方法前，你需要先调用 getRoomList 获取房间列表及相关房间信息。 @@ -129,12 +141,12 @@ roomManager.getRoomInfoList(lastCreateTime: lastCreateTime, pageSize: pageSize, let uid = KaraokeUIKit.shared.roomConfig?.userId ?? "" // 创建房间容器 let karaokeView = AUIKaraokeRoomView(frame: self.view.bounds) -// 通过 generateToken 方法获取到必须的token和appid //TODO 这里生成的 token 是 rtc token还是 rtm token？ +// 通过 generateToken 方法获取到 rtc 和 rtmtoken 以及 appid generateToken { roomConfig, appId in KaraokeUIKit.shared.launchRoom(roomInfo: self.roomInfo!, appId: appId, config: roomConfig, - karaokeView: karaokeView) + karaokeView: karaokeView) } ``` @@ -146,11 +158,11 @@ K 歌结束后，你可以调用 `destroyRoom` 销毁当前房间。 //AUIKaraokeRoomView 提供了 onClickOffButton 点击返回的 clousure TODO karaokeView.onClickOffButton = { [weak self] in self.navigationController?.popViewController(animated: true) - KaraokeUIKit.shared.destoryRoom(roomId: self.roomInfo?.roomId ?? "") + KaraokeUIKit.shared.destoryRoom(roomId: self.roomInfo?.roomId ?? "") } ``` -### 6. token 过期处理 //TODO 这个回调需要写文档吗 +### 6. token 过期处理 //TODO 这个回调需要写文档吗 之后跟chunzhen确认一下是否要一起加 ```swift //在KaraokeUIKit.shared.launchRoom之后订阅AUIRtmErrorProxyDelegate的回调 @@ -169,4 +181,4 @@ KaraokeUIKit.shared.unsubscribeError(roomId: self.roomInfo?.roomId ?? "", delega ## 示例项目 -声网在 GitHub 上提供一个开源的示例项目 [AUIKitKaraoke](https://github.com/AgoraIO-Community/AUIKaraoke/tree/main/iOS) 供你参考。 \ No newline at end of file +声网在 GitHub 上提供一个开源的示例项目 [AUIKitKaraoke](https://github.com/AgoraIO-Community/AUIKaraoke/tree/main/iOS) 供你参考。 diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" index 66dd66e0c73..02d2626cfa3 100644 --- "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" @@ -115,11 +115,11 @@ config.userAvatar = "User Avatar" KaraokeUiKit.setup( // AUiCommonConfig 对象 config = config, - // RtmClient 实例。如果的你的项目中还未集成声网 RTM SDK，请传入 null，KaraokeUiKit 内部会自行创建 + // RtmClient 实例。如果的你的项目中还未集成声网 RTM SDK，请传入 null，AUIKaraoke 内部会自行创建 rtmClient = null, - // RtcEngineEx 实例。如果的你的项目中还未集成声网 RTC SDK，请传入 null，KaraokeUiKit 内部会自行创建 + // RtcEngineEx 实例。如果的你的项目中还未集成声网 RTC SDK，请传入 null，AUIKaraoke 内部会自行创建 rtcEngineEx = null, - // KtvApi 实例。如果你的项目中还未集成 KtvApi，请传入 null，KaraokeUiKit 内部会自行创建 + // KtvApi 实例。如果你的项目中还未集成 KtvApi，请传入 null，AUIKaraoke 内部会自行创建 ktvApi = null ) ``` From e9ab5a6b4662267047663db061299678a04c5a4e Mon Sep 17 00:00:00 2001 From: Suri539 Date: Tue, 26 Sep 2023 16:55:27 +0800 Subject: [PATCH 23/28] =?UTF-8?q?Update=20=E7=BB=84=E4=BB=B6=E4=BB=8B?= =?UTF-8?q?=E7=BB=8D.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...47\273\204\344\273\266\344\273\213\347\273\215.md" | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git "a/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" "b/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" index 5f4ea0e6b6a..95963c7074c 100644 --- "a/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" +++ "b/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" @@ -61,6 +61,17 @@ AUIKaraoke 提供下列核心功能： 除了 AUIKaraoke 这一含 UI 的解决方案，目前声网针对在线 K 歌房场景还提供了无 UI 解决方案，其中无 UI 解决方案包括[无场景化方案](https://confluence.agoralab.co/)、[场景化 API 方案](https://confluence.agoralab.co/)，各方案之间的对比详见[方案对比]()。 +【这篇文档链接到k歌房场景介绍里面的方案对比，为了方便review所以贴在这里，之后会删掉】 + +| 类别 | AUIKaraoke | 无场景化方案 | 场景化 API 方案 | +| :----------- | :----------------------------------------------------------- | :----------------------------------------------------------- | :----------------------------------------------------------- | +| 适用客户 | 适用于开发基础较弱、开发排期紧、需要快速上线的用户。 | 适用于开发能力强且定制化需求极高的用户。 | 适用于开发排期紧、需快速上线、有一定定制化需求的用户。 | +| 功能实现难度 | 低；可在 10 行代码内搭建一个的 K 歌场景应用。 | 中等；需直接使用实时互动 SDK 接口，并自行设计、开发所有业务逻辑和 UI。 | 较低；场景化 API 代码结构较为简单，使用场景化 API 可以简化歌曲管理、播放管理等逻辑，但房间管理、麦位管理等功能及 UI 需自行开发设计。 | +| 可拓展性 | 中等；支持通过组件自定义 K 歌房间的 UI 和相关业务逻辑，如 UI 的调整、业务的增删。如有更灵活的自定义需求，可以直接使用 AUIKit 提供的 UI 和 Service 组件进行组合开发。 | 高；可自行进行功能定制化修改。 | 较高，可自行进行功能定制化修改。 | +| 接入难度 | 较低；将实时互动 SDK、RTM SDK、场景化 API 统一封装在组件内，集成 AUIKaraoke、AUIKit 即可实现场景搭建。 | 中等；需要根据自己实际的业务需求自行集成实时互动、RTM 等 SDK。 | 低；需要集成集成场景化 API、实时互动 SDK。 | + +不同的方案计费方式不同，详情请联系[技术支持](https://docs.agora.io/cn/Agora%20Platform/ticket?platform=All%20Platforms)。 + From 4c675ba63732534efc511a1ca7591d8adea73e14 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Thu, 28 Sep 2023 14:06:05 +0800 Subject: [PATCH 24/28] Update AUIKitKaraoke Objective-C API.md --- .../AUIKitKaraoke Objective-C API.md | 52 ++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md index 2fde7c680e7..fcdf1cf8d90 100644 --- a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md +++ b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md @@ -84,7 +84,7 @@ func launchRoom(roomInfo: AUIRoomInfo, ### destroyRoom -```kotlin +```swift func destoryRoom(roomId: String) ``` @@ -94,6 +94,56 @@ func destoryRoom(roomId: String) - `roomId`：要销毁的房间的 ID。 +### subscribeError + +```swift +fun subscribeError(roomId: String, delegate: AUIRtmErrorProxyDelegate) { + mRoomManager?.rtmManager?.proxy?.subscribeError(roomId, delegate) + } +``` + +订阅房间相关的错误事件。 + +你可以通过该方法订阅与指定 `roomId` 相关的房间的错误事件，如 Token 过期、网络连接等问题。 + +**参数** + +- `roomId`：房间 ID。 +- `delegate`：[AUIRtmErrorProxyDelegate]() 对象，用于处理错误事件。 + +### unsubscribeError + +```swift +fun unsubscribeError(roomId: String, delegate: AUIRtmErrorProxyDelegate) { + mRoomManager?.rtmManager?.proxy?.unsubscribeError(roomId, delegate) + } +``` + +取消订阅房间相关的错误事件。 + +你可以调用该方法取消订阅与指定 `roomId` 相关的房间的错误事件。取消订阅后，不再接收与该房间相关的任何错误。 + + + +要成功取消订阅，请确保传入的 `roomId` 和你调用 `subscribeError` 时传入的 `roomId` 一致。//TODO + + + +**参数** + +- `roomId`：房间 ID。 +- `delegate`：[AUIRtmErrorProxyDelegate]() 对象，用于处理错误事件。 + +### bindRespDelegate + +```swift +fun bindRespDelegate(delegate: AUIRoomManagerRespDelegate) { + mRoomManager?.bindRespDelegate(delegate) + } +``` + + + ## 数据模型 ###

    AUICommonConfig

    From bb982fb525148e21ec7075eb2acfa5d598060496 Mon Sep 17 00:00:00 2001 From: Suri539 Date: Mon, 9 Oct 2023 12:02:03 +0800 Subject: [PATCH 25/28] Update AUIKitKaraoke Objective-C API.md --- .../AUIKitKaraoke Objective-C API.md | 47 +++++++++++++------ 1 file changed, 32 insertions(+), 15 deletions(-) diff --git a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md index fcdf1cf8d90..ac60a3ecf23 100644 --- a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md +++ b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md @@ -109,7 +109,7 @@ fun subscribeError(roomId: String, delegate: AUIRtmErrorProxyDelegate) { **参数** - `roomId`：房间 ID。 -- `delegate`：[AUIRtmErrorProxyDelegate]() 对象，用于处理错误事件。 +- `delegate`：[AUIRtmErrorProxyDelegate](https://github.com/AgoraIO-Community/AUIKaraoke/blob/dev/0.5.1/iOS/doc/KaraokeUIKit_zh.md#auirtmerrorproxydelegate) 对象，用于处理错误事件。 ### unsubscribeError @@ -125,14 +125,14 @@ fun unsubscribeError(roomId: String, delegate: AUIRtmErrorProxyDelegate) { -要成功取消订阅，请确保传入的 `roomId` 和你调用 `subscribeError` 时传入的 `roomId` 一致。//TODO +要成功取消订阅，请确保传入的 `roomId` 和你调用 `subscribeError` 时传入的 `roomId` 一致。 **参数** - `roomId`：房间 ID。 -- `delegate`：[AUIRtmErrorProxyDelegate]() 对象，用于处理错误事件。 +- `delegate`：[AUIRtmErrorProxyDelegate](https://github.com/AgoraIO-Community/AUIKaraoke/blob/dev/0.5.1/iOS/doc/KaraokeUIKit_zh.md#auirtmerrorproxydelegate) 对象，用于处理错误事件。 ### bindRespDelegate @@ -143,6 +143,31 @@ fun bindRespDelegate(delegate: AUIRoomManagerRespDelegate) { ``` +绑定对应房间的响应。 + +你可以调用该方法将实现了 `AUIRoomManagerRespDelegate` 的对象绑定到当前事件，以便在事件完成时，回调或通知这个对象以处理相应的结果或响应，例如房间被销毁、用户被踢出、房间的信息更新等。 + +请确保你的 `AUIRoomManagerRespDelegate` 对象实现了 `AUIRoomManagerRespDelegate` 中的方法，以便能够正确处理响应。 + +**参数** + +- `delegate`：[AUIRoomManagerRespDelegate](https://github.com/AgoraIO-Community/AUIKaraoke/blob/dev/0.5.1/iOS/doc/KaraokeUIKit_zh.md#auiroommanagerrespdelegate) 对象，用于处理与房间操作相关的各种响应事件。你可以根据你的业务需求选择性实现该协议中的方法。 + +### unbindRespDelegate + +```swift +fun unbindRespDelegate(delegate: AUIRoomManagerRespDelegate) { + mRoomManager?.unbindRespDelegate(delegate) + } +``` + +取消绑定对应房间的响应。 + +你可以调用该方法取消已绑定到当前操作或事件的 `AUIRoomManagerRespDelegate` 对象。解除绑定后，将不再通知 `AUIRoomManagerRespDelegate` 对象与房间管理操作相关的结果或响应。 + +**参数** + +`delegate`：[AUIRoomManagerRespDelegate](https://github.com/AgoraIO-Community/AUIKaraoke/blob/dev/0.5.1/iOS/doc/KaraokeUIKit_zh.md#auiroommanagerrespdelegate) 对象，用于处理与房间操作相关的各种响应事件。你可以根据你的业务需求选择性实现该协议中的方法。 ## 数据模型 @@ -193,21 +218,13 @@ K 歌房间的相关信息。 ```swift open class AUIUserThumbnailInfo: NSObject,AUIUserCellUserDataProtocol { - public var userId: String = "" //用户Id - public var userName: String = "" //用户名 - public var userAvatar: String = "" //用户头像 - public var seatIndex: Int = -1 //用户是否在麦上 - public var isOwner: Bool = false //是否是owner TODO owner是指房主吗？但是这个本来就是房主相关信息了 后面两个删掉 - - public func isEmpty() -> Bool { - guard userId.count > 0, userName.count > 0 else {return true} - - return false - } + public var userId: String = "" + public var userName: String = "" + public var userAvatar: String = "" } ``` -K 歌中房主的相关信息。//TODO 原型和input给的参数不一致，研发说之后会删掉后两个参数，明天确认下 +K 歌中房主的相关信息。 **参数** From 7779db12308acfbf1e9b6bf413947555b645f47f Mon Sep 17 00:00:00 2001 From: Suri539 Date: Mon, 9 Oct 2023 18:05:07 +0800 Subject: [PATCH 26/28] modify ios docs except for demo based on review comments --- ...e API \345\217\202\350\200\203-android.md" | 31 +---- .../AUIKitKaraoke Objective-C API.md | 112 +++++++++--------- .../ios-\351\233\206\346\210\220.md" | 70 ++++++----- .../android-\351\233\206\346\210\220.md" | 12 +- 4 files changed, 113 insertions(+), 112 deletions(-) diff --git "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" index dead8c1bf2c..1f7132a8c94 100644 --- "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" +++ "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" @@ -17,16 +17,16 @@ fun setup( ) ``` -初始化 `scenekit`。 +初始化 AUIKaraoke。 在调用 `KaraokeUIKit` 类下的其他 API 前，你需要先调用该方法进行初始化。 **参数** - `config`：初始化设置，详见 [AUICommonConfig](#AUICommonConfig)。 -- `ktvApi`：[场景化 API](https://docportal.shengwang.cn/cn/online-ktv/ktv_api_kotlin?platform=Android) 实例。如果你的项目中还未集成场景化 API，请传入 `null`，`scenekit` 内部会自行创建场景化 API 实例。 -- `rtcEngineEx`：[RtcEngineEx](https://docportal.shengwang.cn/cn/online-ktv/API%20Reference/java_ng/API/rtc_interface_class.html#class_irtcengineex) 实例。如果的你的项目中还未集成声网 RTC SDK，请传入 `null`，`scenekit` 内部会自行创建 `RtcEngineEx` 实例。 -- `rtmClient`：[RtmClient](https://doc.shengwang.cn/doc/rtm2/java/landing-page) 实例。如果的你的项目中还未集成声网 RTM SDK，请传入 `null`，`scenekit` 内部会自行创建 `RtmClient` 实例。 +- `ktvApi`：K 歌房[场景化 API](https://docportal.shengwang.cn/cn/online-ktv/ktv_api_kotlin?platform=Android) 实例。如果你的项目中还未使用场景化 API，请传入 `null`，AUIKaraoke 内部会自行创建场景化 API 实例。 +- `rtcEngineEx`：[RtcEngineEx](https://docportal.shengwang.cn/cn/online-ktv/API%20Reference/java_ng/API/rtc_interface_class.html#class_irtcengineex) 实例。如果的你的项目中还未使用声网 RTC SDK，请传入 `null`，AUIKaraoke 内部会自行创建 `RtcEngineEx` 实例。 +- `rtmClient`：[RtmClient](https://doc.shengwang.cn/doc/rtm2/java/landing-page) 实例。如果的你的项目中还未使用声网 RTM SDK，请传入 `null`，AUIKaraoke 内部会自行创建 `RtmClient` 实例。 ### createRoom @@ -134,28 +134,6 @@ public class AUICommonConfig { - `userName`：用户名。 - `userAvatar`：用户头像。 -###

    AUICreateRoomInfo

    - -```kotlin -public class AUICreateRoomInfo implements Serializable { - public @NonNull String roomName = ""; - public @NonNull String thumbnail = ""; - public int micSeatCount = 8; - public @Nullable String password; - public String micSeatStyle = ""; -} -``` - -需要创建的 K 歌房间的相关信息。 - -**参数** - -- `roomName`：房间名。 -- `thumbnail`：房间列表上指用户头像的 URL。 -- `micSeatCount`：房间中的麦位数量，取值范围 [1-8]。 -- `password`：房间密码。 -- `micSeatStyle`：房间中麦位的排列样式。 - ###

    AUIRoomInfo

    ```kotlin @@ -180,7 +158,6 @@ public class AUIRoomInfo extends AUICreateRoomInfo implements Serializable { ```kotlin public class AUIUserThumbnailInfo implements Serializable { - public @NonNull String userId = ""; public @NonNull String userName = ""; public @NonNull String userAvatar = ""; diff --git a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md index ac60a3ecf23..8d4c067157b 100644 --- a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md +++ b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md @@ -1,10 +1,10 @@ -# AUIKitKaraoke swift API（iOS） +# AUIKaraoke Swift API（iOS） 本文介绍 AUIKaraoke 组件的 API。你可以在 GitHub 上查看[源码文件](https://github.com/AgoraIO-Community/AUIKaraoke/tree/main/iOS)。 ## KaraokeUIKit -提供 `AUIKitKaraoke` 的核心类，可用于实现组件初始化、创建、销毁房间等基础功能。 +提供 `AUIKaraoke` 的核心类，可用于实现组件初始化、创建、销毁房间等基础功能。 ### setup @@ -15,16 +15,16 @@ func setup(roomConfig: AUICommonConfig, rtmClient: AgoraRtmClientKit? = nil) ``` -初始化 `scenekit`。 +初始化 AUIKaraoke。 在调用 `KaraokeUIKit` 类下的其他 API 前，你需要先调用该方法进行初始化。 **参数** -- `roomConfig`：初始化设置，详见 [AUICommonConfig](#AUICommonConfig)。 -- `ktvApi`：[KTVApiDelegate](https://docportal.shengwang.cn/cn/online-ktv/ktv_api_oc?platform=iOS#ktvapidelegate) 对象。如果你的项目中还未集成场景化 API，请传入 `nil`，`scenekit` 内部会自行创建 `KTVApiDelegate` 对象。 -- `rtcEngine`：[AgoraRtcEngineKit](https://docportal.shengwang.cn/cn/online-ktv/API%20Reference/ios_ng/API/rtc_interface_class.html#class_irtcengine) 对象。如果的你的项目中还未集成声网 RTC SDK，请传入 `nil`，`scenekit` 内部会自行创建 `AgoraRtcEngineKit` 对象。 -- `rtmClient`：[AgoraRtmClientKit](https://doc.shengwang.cn/doc/rtm2/oc/landing-page) 对象。如果的你的项目中还未集成声网 RTM SDK，请传入 `nil`，`scenekit` 内部会自行创建 `AgoraRtmClientKit` 对象。 +- `roomConfig`：初始化配置，详见 [AUICommonConfig](#AUICommonConfig)。 +- `ktvApi`：（可选）[KTVApiDelegate](https://docportal.shengwang.cn/cn/online-ktv/ktv_api_oc?platform=iOS#ktvapidelegate) 对象。如果你的项目中还未使用 K 歌房场景化 API，请传入 `nil`，AUIKaraoke 内部会自行创建 `KTVApiDelegate` 对象。 +- `rtcEngine`：（可选）[AgoraRtcEngineKit](https://docportal.shengwang.cn/cn/online-ktv/API%20Reference/ios_ng/API/rtc_interface_class.html#class_irtcengine) 对象。如果的你的项目中还未使用声网 RTC SDK，请传入 `nil`，AUIKaraoke 内部会自行创建 `AgoraRtcEngineKit` 对象。 +- `rtmClient`：（可选）[AgoraRtmClientKit](https://doc.shengwang.cn/doc/rtm2/oc/landing-page) 对象。如果的你的项目中还未使用声网 RTM 2.x SDK，请传入 `nil`，AUIKaraoke 内部会自行创建 `AgoraRtmClientKit` 对象。 ### createRoom @@ -40,11 +40,11 @@ func createRoom(roomInfo: AUICreateRoomInfo, **参数** -- `roomInfo`：一个 `AUICreateRoomInfo` 对象，包含要创建的房间信息 。 -- `success`：（可选）成功回调闭包，当房间创建成功时将被调用。闭包参数为一个 `AUIRoomInfo` 对象，表示创建的房间信息。 +- `roomInfo`：一个 [AUICreateRoomInfo](#AUICreateRoomInfo) 对象，包含要创建的房间信息。 +- `success`：（可选）成功回调闭包，当房间创建成功时将被调用。闭包参数为一个 [AUIRoomInfo](#AUIRoomInfo) 对象，表示创建的房间信息。 - `failure`：（可选）失败回调闭包，当房间创建失败时将被调用。闭包参数为一个 `Error` 对象，表示创建失败的错误信息。 -### getRoomList +### getRoomInfoList ```swift func getRoomInfoList(lastCreateTime: Int64?, @@ -54,11 +54,11 @@ func getRoomInfoList(lastCreateTime: Int64?, 获取 K 歌房间列表。 -你可以调用该方法获取当前的已创建的 K 歌房间列表。 +你可以调用该方法获取当前已创建的 K 歌房间列表。 **参数** -- `lastCreateTime`：（可选）房间创建的时间。 +- `lastCreateTime`：（可选）房间创建的时间。//TODO - `pageSize`：每一页房间列表所展示的房间数量。 - `callback`：用于处理获取房间列表结果的回调闭包，在成功获取房间列表结果后会被调用。回调闭包接受一个 `AUIRoomListCallback` 对象作为参数。 @@ -73,7 +73,7 @@ func launchRoom(roomInfo: AUIRoomInfo, 拉起 K 歌房间。 -当你成功调用 `createRoom` 创建房间后，你可以调用该方法拉起房间。 +当你成功调用 `createRoom` 创建房间后，你可以调用该方法拉起房间。在调用该方法前，你需要先调用 `getRoomList` 获取房间列表及相关房间信息。 **参数** @@ -97,49 +97,35 @@ func destoryRoom(roomId: String) ### subscribeError ```swift -fun subscribeError(roomId: String, delegate: AUIRtmErrorProxyDelegate) { - mRoomManager?.rtmManager?.proxy?.subscribeError(roomId, delegate) - } +func subscribeError(delegate: AUIRtmErrorProxyDelegate) ``` 订阅房间相关的错误事件。 -你可以通过该方法订阅与指定 `roomId` 相关的房间的错误事件，如 Token 过期、网络连接等问题。 +你可以通过该方法订阅房间相关的错误事件，如 Token 过期、网络连接等问题。 **参数** -- `roomId`：房间 ID。 - `delegate`：[AUIRtmErrorProxyDelegate](https://github.com/AgoraIO-Community/AUIKaraoke/blob/dev/0.5.1/iOS/doc/KaraokeUIKit_zh.md#auirtmerrorproxydelegate) 对象，用于处理错误事件。 ### unsubscribeError ```swift -fun unsubscribeError(roomId: String, delegate: AUIRtmErrorProxyDelegate) { - mRoomManager?.rtmManager?.proxy?.unsubscribeError(roomId, delegate) - } +func bindRespDelegate(delegate: AUIRoomManagerRespDelegate) ``` 取消订阅房间相关的错误事件。 你可以调用该方法取消订阅与指定 `roomId` 相关的房间的错误事件。取消订阅后，不再接收与该房间相关的任何错误。 - - -要成功取消订阅，请确保传入的 `roomId` 和你调用 `subscribeError` 时传入的 `roomId` 一致。 - - - **参数** -- `roomId`：房间 ID。 - `delegate`：[AUIRtmErrorProxyDelegate](https://github.com/AgoraIO-Community/AUIKaraoke/blob/dev/0.5.1/iOS/doc/KaraokeUIKit_zh.md#auirtmerrorproxydelegate) 对象，用于处理错误事件。 ### bindRespDelegate ```swift -fun bindRespDelegate(delegate: AUIRoomManagerRespDelegate) { - mRoomManager?.bindRespDelegate(delegate) - } +func bindRespDelegate(delegate: AUIRoomManagerRespDelegate) ``` @@ -156,9 +142,7 @@ fun bindRespDelegate(delegate: AUIRoomManagerRespDelegate) { ### unbindRespDelegate ```swift -fun unbindRespDelegate(delegate: AUIRoomManagerRespDelegate) { - mRoomManager?.unbindRespDelegate(delegate) - } +func unbindRespDelegate(delegate: AUIRoomManagerRespDelegate) ``` 取消绑定对应房间的响应。 @@ -185,7 +169,7 @@ open class AUICommonConfig: NSObject { 通用设置。 -**参数** +**属性** - `appId`：你的项目在控制台注册的 App ID，详见[获取 App ID](https://docportal.shengwang.cn/cn/Agora%20Platform/get_appid_token?platform=All%20Platforms#获取-app-id)。 - `host`：业务后端服务域名。 @@ -193,9 +177,31 @@ open class AUICommonConfig: NSObject { - `userName`：用户名。 - `userAvatar`：用户头像。 +###

    AUICreateRoomInfo

    + +```swift +open class AUICreateRoomInfo: NSObject { + public var roomName: String = "" + public var thumbnail: String = "" + public var micSeatCount: UInt = 8 + public var micSeatStyle: UInt = 8 + public var password: String? +} +``` + +需要创建的 K 歌房间的相关信息。 + +**属性** + +- `roomName`：房间名。 +- `thumbnail`：房间列表上指用户头像的 URL。 +- `micSeatCount`：房间中的麦位数量，取值范围 [1-8]。 +- `micSeatStyle`：房间中麦位的排列样式，默认值为 8，表示默认样式，目前 AUIKaraoke 暂不支持其他特殊的排列样式。 +- `password`：房间密码。 + ###

    AUIRoomInfo

    -```kotlin +```swift open class AUIRoomInfo: AUICreateRoomInfo { public var roomId: String = "" public var owner: AUIUserThumbnailInfo? @@ -206,18 +212,17 @@ open class AUIRoomInfo: AUICreateRoomInfo { K 歌房间的相关信息。 -**参数** +**属性** - `roomId`：房间 ID。 -- `roomOwner`：房主信息，详见 [AUIUserThumbnailInfo](#AUIUserThumbnailInfo)。 -- `onlineUsers`：房间内的人数。 +- `owner`：房主信息，详见 [AUIUserThumbnailInfo](#AUIUserThumbnailInfo)。 +- `memberCount`：房间内的人数。 - `createTime`：房间创建的时间，单位为毫秒。 ###

    AUIUserThumbnailInfo

    ```swift open class AUIUserThumbnailInfo: NSObject,AUIUserCellUserDataProtocol { - public var userId: String = "" public var userName: String = "" public var userAvatar: String = "" @@ -226,7 +231,7 @@ open class AUIUserThumbnailInfo: NSObject,AUIUserCellUserDataProtocol { K 歌中房主的相关信息。 -**参数** +**属性** - `userId`：房主的 ID。 - `userName`：房主的用户名。 @@ -236,7 +241,7 @@ K 歌中房主的相关信息。 K 歌房间设置。 -```kotlin +```swift open class AUIRoomConfig: NSObject { public var channelName: String = "" //正常rtm使用的频道 public var rtmToken007: String = "" //rtm login用，只能007 @@ -249,7 +254,7 @@ open class AUIRoomConfig: NSObject { } ``` -**参数** +**属性** - `channelName`：RTM 频道的频道名，该频道用于同步数据信息、传输信令。 @@ -259,27 +264,28 @@ open class AUIRoomConfig: NSObject { 请确保你使用的 RTM Token 是 AccessToken2。 -- `rtcToken007`：（rtm login 用）加入主频道的 RTC Token。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流。 - -- `rtcChannelName`：主频道的频道名。 +     -- `rtcRtcToken`：加入主频道的 RTC Token。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流。 +- `rtcToken007`： 登陆 RTM 系统时用的 RTC Token。 - 请确保你使用的 RTC Token 是 AccessToken2。//TODO 搬到新站后加相应的文档链接 + 请确保你使用的 RTC Token 是 AccessToken2。详见[使用 Token 鉴权](https://doc.shengwang.cn/doc/rtc/ios/basic-features/token-authentication)。 -- `rtcRtmToken`：用于音乐内容中心鉴权的 RTM Token。 - -- `rtcChorusChannelName`：合唱频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。独唱场景下，该参数可为空。 - -- `rtcChorusRtcToken`：根据合唱频道名和用户 ID 生成的 RTC Token，用于加入合唱频道时进行鉴权。独唱场景下，该参数可为空。 +- `rtcChannelName`：主频道的频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流。 +- `rtcRtcToken`：加入主频道的 RTC Token。 + + 请确保你使用的 RTC Token 是 AccessToken2，详见[使用 Token 鉴权](https://doc.shengwang.cn/doc/rtc/ios/basic-features/token-authentication)。 + +- `rtcRtmToken`：用于音乐内容中心鉴权的 RTM Token。 +- `rtcChorusChannelName`：合唱频道名。独唱场景下，该参数可为空。 +- `rtcChorusRtcToken`：根据合唱频道名和用户 ID 生成的 RTC Token，用于加入合唱频道时进行鉴权。独唱场景下，该参数可为空。 diff --git "a/markdown/online-ktv/AUIKaraoke/ios-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/ios-\351\233\206\346\210\220.md" index 5ea8cedc8de..d54a79575bb 100644 --- "a/markdown/online-ktv/AUIKaraoke/ios-\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/AUIKaraoke/ios-\351\233\206\346\210\220.md" @@ -1,8 +1,8 @@ -本文介绍如何通过 [AUIKitKaraoke 组件](#link-to-description)快速搭建一个含 UI 界面的在线 K 歌房。 +本文介绍如何通过 [AUIKaraoke 组件](#link-to-description)快速搭建一个含 UI 界面的在线 K 歌房。 下图展示搭建 K 歌房间的完整流程： -image-20230830103826589 + ## 准备开发环境 @@ -34,7 +34,7 @@ 1. [创建一个新的项目](https://help.apple.com/xcode/mac/current/#/dev07db0e578)，**Application** 选择 **App**，**Interface** 选择 **Storyboard**，**Language** 选择 **Swift**。 - 如果你没有添加过开发团队信息，会看到 **Add account…** 按钮。点击该按钮并按照屏幕提示登入 Apple ID，点击 **Next**，完成后即可选择你的 Apple 账户作为开发团队。 + 如果你没有添加过开发团队信息，会看到 **Add account…** 按钮。点击该按钮并按照屏幕提示登录 Apple ID，点击 **Next**，完成后即可选择你的 Apple 账户作为开发团队。 2. 为你的项目设置[自动签名](https://help.apple.com/xcode/mac/current/#/dev23aab79b4)。 @@ -50,10 +50,10 @@ 5. 添加项目的设备权限。在项目导航栏中打开 `info.plist` 文件，配置麦克风和摄像头权限，如下图所示： - ![image-20230911163222007](/Users/admin/Library/Application Support/typora-user-images/image-20230911163222007.png) + ![](https://web-cdn.agora.io/docs-files/1696838612771) ​ -​
    • Value 值填写使用麦克风或摄像头的目的即可。
    • 如果你的项目中需要添加第三方插件或库（例如第三方摄像头），且该插件或库的签名与项目的签名不一致，你还需勾选 Hardened Runtime > Runtime Exceptions 中的 Disable Library Validation。
    • 更多注意事项，可参考 Preparing Your App for Distribution。
    +​
    • Value 值填写使用麦克风或摄像头的目的即可。
    • 如果你的项目中需要添加第三方插件或库（例如第三方摄像头），且该插件或库的签名与项目的签名不一致，你还需勾选 **Hardened Runtime** > **Runtime Exceptions** 中的 **Disable Library Validation**。
    • 更多注意事项，可参考 Preparing Your App for Distribution。
    ​     ### 集成组件 @@ -61,19 +61,22 @@ 1. 将下列源码复制到你的项目中： - [KaraokeUIKit](https://github.com/AgoraIO-Community/AUIKaraoke/blob/main/iOS/Example/AUIKaraoke/KaraokeUIKit.swift) - 加上 karaokeuikit - [AScenesKit](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main/iOS/AScenesKit) - - [KeyCenter.swift](https://github.com/AgoraIO-Community/AUIKitKaraoke/blob/main/iOS/Example/AUIKitKaraoke/KeyCenter.swift) - -2. 在 Podfile 文件里添加依赖。 + - [KeyCenter.swift](https://github.com/AgoraIO-Community/AUIKaraoke/blob/main/iOS/Example/AUIKaraoke/KeyCenter.swift) + +2. 在 Podfile 文件里添加依赖。下列示例把 `AScenesKit` 放置在与 Podfile 同一级目录下。 ```ruby pod 'AScenesKit', :path => './AScenesKit' - pod 'AUIKit', :path => './AUIKit' + pod 'AUIKitCore' ``` ## 实现在线 K 歌房 +下图展示了创建一个在线 K 歌房的 API 调用时序： + + + ### 1. 初始化 AUIKaraoke 创建 `AUiCommonConfig` 对象，调用 `setup` 初始化 AUIKaraoke。 @@ -91,11 +94,11 @@ commonConfig.userName = userInfo.userName commonConfig.userAvatar = userInfo.userAvatar // 初始化 KaraokeUIKit.shared.setup(roomConfig: commonConfig, - // KtvApi 对象。如果你的项目中还未集成 KtvApi，请传入 nil， AUIKaraoke 内部会自行创建 + // KtvApi 对象。如果你的项目中还未使用 KtvApi，请传入 nil， AUIKaraoke 内部会自行创建 ktvApi: nil, - // RtcEngine 对象。如果的你的项目中还未集成声网实时互动 SDK，请传入 AUIKaraoke 内部会自行创建 + // RtcEngine 对象。如果的你的项目中还未使用声网实时互动 SDK，请传入 nil，AUIKaraoke 内部会自行创建 rtcEngine: nil, - // RtmClient 对象。如果的你的项目中还未集成声网 RTM SDK，请传入 nil，AUIKaraoke 内部会自行创建 + // RtmClient 对象。如果的你的项目中还未使用声网 RTM SDK，请传入 nil，AUIKaraoke 内部会自行创建 rtmClient: nil) ``` @@ -122,7 +125,7 @@ KaraokeUIKit.shared.createRoom(roomInfo: room) { roomInfo in ### 3. 获取房间列表 -调用 `getRoomList` 获取已创建房间的列表。你可以通过 `lastCreateTime` 指定房间创建的时间，从而筛选出某一时间之后创建的房间列表，还可以通过 `pageSize` 参数设置每一页展示的房间数量。 +调用 `getRoomInfoList` 获取已创建房间的列表。你可以通过 `lastCreateTime` 指定房间创建的时间，从而筛选出某一时间之后创建的房间列表，还可以通过 `pageSize` 参数设置每一页展示的房间数量。 ```swift KaraokeUIKit.shared.getRoomInfoList(lastCreateTime: nil, @@ -133,15 +136,19 @@ KaraokeUIKit.shared.getRoomInfoList(lastCreateTime: nil, ### 4. 拉起房间 -调用 `launchRooom` 拉起房间。至此，你已经成功搭建一个带有 UI 界面的在线 K 歌房间，你可以 +调用 `launchRooom` 拉起房间。至此，你已经成功搭建一个带有 UI 界面的在线 K 歌房间，你可以快速体验在线 K 歌场景。 -在调用该方法前，你需要先调用 getRoomList 获取房间列表及相关房间信息。 + + +在调用该方法前，你需要先调用 getRoomInfoList 获取房间列表及相关房间信息。 + + ```swift let uid = KaraokeUIKit.shared.roomConfig?.userId ?? "" // 创建房间容器 let karaokeView = AUIKaraokeRoomView(frame: self.view.bounds) -// 通过 generateToken 方法获取到 rtc 和 rtmtoken 以及 appid +// 获取 token 以及 appId generateToken { roomConfig, appId in KaraokeUIKit.shared.launchRoom(roomInfo: self.roomInfo!, appId: appId, @@ -152,33 +159,40 @@ generateToken { roomConfig, appId in ### 5. 销毁房间 -K 歌结束后，你可以调用 `destroyRoom` 销毁当前房间。 +K 歌结束后，你可以主动调用 `destroyRoom` 销毁当前房间。 ```swift -//AUIKaraokeRoomView 提供了 onClickOffButton 点击返回的 clousure TODO karaokeView.onClickOffButton = { [weak self] in self.navigationController?.popViewController(animated: true) + // 销毁房间 KaraokeUIKit.shared.destoryRoom(roomId: self.roomInfo?.roomId ?? "") } ``` -### 6. token 过期处理 //TODO 这个回调需要写文档吗 之后跟chunzhen确认一下是否要一起加 +### 6. 异常处理 + +调用 `subscribeError` 来订阅房间相关的异常回调，如 Token 过期。调用 `bindRespDelegate` 绑定对应房间的响应，如房间被销毁、用户被踢出等。 + +在退出房间时调用 `unsubscribeError` 和 `unbindRespDelegate` 来取消订阅和绑定。 ```swift -//在KaraokeUIKit.shared.launchRoom之后订阅AUIRtmErrorProxyDelegate的回调 +//在K拉起房间后订阅房间相关的异常回调 KaraokeUIKit.shared.subscribeError(roomId: self.roomInfo?.roomId ?? "", delegate: self) //在退出房间时取消订阅 KaraokeUIKit.shared.unsubscribeError(roomId: self.roomInfo?.roomId ?? "", delegate: self) -//然后通过AUIRtmErrorProxyDelegate回调方法中的onTokenPrivilegeWillExpire来renew所有的token -@objc func onTokenPrivilegeWillExpire(channelName: String?) { - generatorToken { config, _ in - KaraokeUIKit.shared.renew(config: config) - } -} +//在拉起房间后绑定房间的响应 +KaraokeUIKit.shared.bindRespDelegate(delegate: self) + +//在退出房间时取消绑定 +KaraokeUIKit.shared.unbindRespDelegate(delegate: self) ``` ## 示例项目 -声网在 GitHub 上提供一个开源的示例项目 [AUIKitKaraoke](https://github.com/AgoraIO-Community/AUIKaraoke/tree/main/iOS) 供你参考。 +声网在 GitHub 上提供一个开源的示例项目 [AUIKaraoke](https://github.com/AgoraIO-Community/AUIKaraoke/tree/main/iOS) 供你参考。 + +## API 参考 + +- [AUIKaraoke API]() \ No newline at end of file diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" index 02d2626cfa3..df227a867be 100644 --- "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" @@ -24,7 +24,7 @@ AUIKaraoke 是一个基于 [AUIKit](https://github.com/AgoraIO-Community/AUIKit/ -- 有效的声网[开发者账号](https://docs.agora.io/cn/Agora Platform/sign_in_and_sign_up)和声网项目，请参考[开始使用声网平台](https://docs.agora.io/cn/Agora Platform/get_appid_token?platform=All Platforms)，从声网控制台获取以下信息： +- 有效的声网开发者账号和声网项目，请参考[开通服务](https://doc.shengwang.cn/doc/rtc/ios/get-started/enable-service)，从声网控制台获取以下信息： - App ID：声网随机生成的字符串，用于识别你的 app。 - RTC Token：在你的业务服务器上生成的 RTC Token。你的 app 客户端加入频道时会使用 Token 对用户进行鉴权。 - RTM Token（refer 到 rtm token 文档） @@ -93,7 +93,7 @@ AUIKaraoke 是一个基于 [AUIKit](https://github.com/AgoraIO-Community/AUIKit/ 下图展示了创建一个在线 K 歌房的 API 调用时序：（这个是时序图里面的KaraokeUiKit 后续都会统一改为 AUIKaraoke） -image-20230830161719228 + ### 1. 初始化 AUIKaraoke @@ -167,9 +167,13 @@ KaraokeUiKit.getRoomList(startTime, 10, ### 4. 拉起房间 -调用 `launchRooom` 拉起房间。至此，你已经成功搭建一个带有 UI 界面的在线 K 歌房间。 +调用 `launchRooom` 拉起房间。至此，你已经成功搭建一个带有 UI 界面的在线 K 歌房间。你可以快速体验在线 K 歌场景。 -在调用该方法前，你需要先调用 getRoomList 获取房间列表及相关房间信息。 + + +在调用该方法前，你需要先调用 getRoomList 获取房间列表及相关房间信息。 + + ```kotlin // 房间信息，通过 getRoomList 获取 From c9e51b90ef4faefcfde57ff9b56ab119c3aa893c Mon Sep 17 00:00:00 2001 From: Suri539 Date: Tue, 10 Oct 2023 10:29:52 +0800 Subject: [PATCH 27/28] fix intro 30% --- ...273\204\344\273\266\344\273\213\347\273\215.md" | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git "a/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" "b/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" index 95963c7074c..ca20f514bda 100644 --- "a/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" +++ "b/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" @@ -12,11 +12,11 @@ AUIKaraoke 是声网针对 K 歌场景推出的开源 UI 组件，集成了 [K 1. App：接入 AUIKaraoke 的项目 -2. AUIKaraoke：以源码方式集成的库，可在上面进行自定义，其中 +2. AUIKaraoke：以源码方式集成的库，可在库中进行自定义，其中： - `KaraokeUIKit` 负责房间管理以及 Service、View 的统一调度 - `KaraokeRoomView` 是默认的 K 歌房 View。你可以根据需求进行自定义修改。 - - binder 负责将 Service 和 UI 逻辑绑定起来。 + - Binder 负责将 Service 和 UI 逻辑绑定起来。 - `AUIKiaraokeRoomService` 负责管理用到的 AUIKit 提供的 Service。 3. AUIKit：基础库，包含 Service 和 UI 两部分，为上层提供基础业务能力和 UI 组件。 @@ -34,7 +34,7 @@ AUIKaraoke 提供下列核心功能： - 上麦和下麦：用户可以随时上下麦，实现多人互动 K 歌。 - 踢人下麦：房主可以将用户从麦位上踢下来，以管理麦位的占用情况。 -- 封禁和锁麦：麦位可以被封禁或锁定，以更好维护 K 歌房间内秩序。 +- 封禁和锁麦：麦位可以被封禁或锁定，以更好维护 K 歌房间内的秩序。 **音乐播放器**： @@ -42,7 +42,7 @@ AUIKaraoke 提供下列核心功能： **歌曲管理**： -- 搜索歌曲：通过歌曲或歌手关键词搜索，检索查找自己喜欢的歌曲。声网曲库涵盖 20万+ 正版歌曲。 +- 搜索歌曲：声网曲库涵盖至少 20 万首正版歌曲，可以通过歌曲或歌手关键词搜索，检索查找自己喜欢的歌曲。 - 点歌和切歌：用户可以点播自己喜欢的歌曲，并在需要时切换到下一首。 - 置顶歌曲：房主可以将某首歌曲置顶，确保它在播放列表中优先播放。 @@ -51,9 +51,11 @@ AUIKaraoke 提供下列核心功能： - 加入、离开合唱：用户可以随时加入或离开合唱，与上麦的演唱者一起享受 K 歌的乐趣。 - 歌词同步：进行合唱时，主唱、伴唱、观众端的歌词可以实现同步，提供更出色的合唱体验。 -**收发礼物**：房间内的用户彼此之间可以送礼物，增加互动趣味性。 +**收发礼物**： -**文字聊天**：除了上麦互动，K 歌房间内的用户彼此之间还可以发送文字消息。 +- 房间内的用户彼此之间可以送礼物，增加互动趣味性。 + +**文字聊天**：除了上麦互动，K 歌房间内的用户还可以发送文字消息进行互动。 From 44f7838720315cc2ec88dda2a411d06d911493fc Mon Sep 17 00:00:00 2001 From: Suri539 Date: Tue, 10 Oct 2023 16:00:22 +0800 Subject: [PATCH 28/28] =?UTF-8?q?=E6=90=9E=E5=AE=8C=E4=BA=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...e API \345\217\202\350\200\203-android.md" | 87 +++++++++++++++--- .../AUIKitKaraoke Objective-C API.md | 26 ++---- .../ios-\351\233\206\346\210\220.md" | 24 ++++- ...04\344\273\266\344\273\213\347\273\215.md" | 22 +++-- .../android-\351\233\206\346\210\220.md" | 92 ++++++++++++++++--- 5 files changed, 195 insertions(+), 56 deletions(-) diff --git "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" index 1f7132a8c94..ae95c5286fd 100644 --- "a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" +++ "b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke API \345\217\202\350\200\203-android.md" @@ -65,10 +65,10 @@ fun getRoomList( **参数** -- `startTime`：房间创建的时间。 +- `startTime`：房间创建的时间，用于筛选在该时间之后创建的房间。 - `pageSize`：每一页房间列表所展示的房间数量。 - `success`：回调函数，当成功获取到 K 歌房间列表时调用，会返回一个房间信息列表，详见 [AUIRoomInfo](#AUIRoomInfo)。 -- `failure`：回调函数，当房间创建失败时调用。接受一个 `AUIException` 参数表示房间创建失败的异常， 无返回值。 +- `failure`：回调函数，当房间创建失败时调用，接受一个 `AUIException` 参数表示房间创建失败的异常，无返回值。 ### launchRoom @@ -110,6 +110,69 @@ fun release() 释放 AUIKaraoke 的所有资源。 +### subscribeError + +```kotlin +fun subscribeError(roomId: String, delegate: AUIRtmErrorProxyDelegate) +``` + +订阅房间相关的异常回调。 + +你可以通过该方法订阅房间相关的异常回调，如 Token 过期、网络连接等问题。 + +**参数** + +- `roomId`：房间 ID。 + +- `delegate`：[AUIRtmErrorProxyDelegate](https://github.com/AgoraIO-Community/AUIKaraoke/blob/main/Android/README.zh.md#auirtmerrorproxydelegate) 实例，用于处理异常回调。 + +### unsubscribeError + +```kotlin +fun unsubscribeError(roomId: String, delegate: AUIRtmErrorProxyDelegate) +``` + +取消订阅房间相关的异常回调。 + +你可以调用该方法取消订阅与指定 `roomId` 相关的房间的异常回调。取消订阅后，不再接收与该房间相关的任何异常回调。 + +**参数** + +- `roomId`：房间 ID。 + +- `delegate`：[AUIRtmErrorProxyDelegate](https://github.com/AgoraIO-Community/AUIKaraoke/blob/main/Android/README.zh.md#auirtmerrorproxydelegate) 实例，用于处理异常回调。 + +### bindRespDelegate + +```kotlin +fun bindRespDelegate(delegate: AUIRoomManagerRespDelegate) +``` + + +绑定对应房间的响应。 + +你可以调用该方法将实现了 `AUIRoomManagerRespDelegate` 的对象绑定到当前事件，以便在事件完成时，回调或通知这个对象以处理相应的结果或响应，例如房间被销毁、用户被踢出、房间的信息更新等。 + +请确保你的 `AUIRoomManagerRespDelegate` 对象实现了 `AUIRoomManagerRespDelegate` 中的方法，以便能够正确处理响应。 + +**参数** + +- `delegate`：[AUIRoomManagerRespDelegate](https://github.com/AgoraIO-Community/AUIKaraoke/blob/main/Android/README.zh.md#auiroommanagerrespdelegate) 实例，用于处理与房间操作相关的各种响应事件。你可以根据你的业务需求选择性实现该接口类中的方法。 + +### unbindRespDelegate + +```kotlin +fun unbindRespDelegate(delegate: AUIRoomManagerRespDelegate) +``` + +取消绑定对应房间的响应。 + +你可以调用该方法取消已绑定到当前操作或事件的 `AUIRoomManagerRespDelegate` 对象。解除绑定后，将不再通知 `AUIRoomManagerRespDelegate` 对象与房间管理操作相关的结果或响应。 + +**参数** + +`delegate`：[AUIRoomManagerRespDelegate](https://github.com/AgoraIO-Community/AUIKaraoke/blob/main/Android/README.zh.md#auiroommanagerrespdelegate) 实例，用于处理与房间操作相关的各种响应事件。你可以根据你的业务需求选择性实现该接口类中的方法。 + ## 数据模型 ###

    AUICommonConfig

    @@ -188,8 +251,6 @@ public AUIException(int code, String message) ###

    AUIRoomConfig

    -K 歌房间设置。 - ```kotlin public class AUIRoomConfig { @@ -210,6 +271,8 @@ public class AUIRoomConfig { } ``` +K 歌房间设置。 + **参数** - `channelName`：RTM 频道的频道名，该频道用于同步数据信息、传输信令。 @@ -218,30 +281,24 @@ public class AUIRoomConfig { - 请确保你使用的 RTM Token 是 AccessToken2。//TODO 搬到新站后加相应的文档链接 + 请确保你使用的 RTM Token 是 AccessToken2。 - `rtcToken`：加入 RTM 频道时使用的 RTC Token。 - 请确保你使用的 RTC Token 是 AccessToken2。//TODO 搬到新站后加相应的文档链接 + 请确保你使用的 RTC Token 是 AccessToken2。详见[使用 Token 鉴权](https://doc.shengwang.cn/doc/rtc/ios/basic-features/token-authentication)。 -- `rtcChannelName`：主频道的频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。 - -- `rtcRtcToken`：加入主频道的 RTC Token。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流。 - - - - 请确保你使用的 RTC Token 是 AccessToken2。//TODO 搬到新站后加相应的文档链接 +- `rtcChannelName`：主频道的频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流。伴唱需要加入合唱频道来同步领唱的人声。 - +- `rtcRtcToken`：加入主频道的 RTC Token。 - `rtcRtmToken`：RTM Token，用于音乐内容中鉴权。 -- `rtcChorusChannelName`：合唱频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流，伴唱需要加入合唱频道来同步领唱的人声。独唱场景下，该参数可为空。 +- `rtcChorusChannelName`：合唱频道名。独唱场景下，该参数可为空。 - `rtcChorusRtcToken`：根据合唱频道名和用户 ID 生成的 RTC Token，用于加入合唱频道时进行鉴权。独唱场景下，该参数可为空。 diff --git a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md index 8d4c067157b..5865628b25d 100644 --- a/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md +++ b/markdown/online-ktv/AUIKaraoke/AUIKitKaraoke Objective-C API.md @@ -243,14 +243,14 @@ K 歌房间设置。 ```swift open class AUIRoomConfig: NSObject { - public var channelName: String = "" //正常rtm使用的频道 - public var rtmToken007: String = "" //rtm login用，只能007 - public var rtcToken007: String = "" //rtm join用 - public var rtcChannelName: String = "" //rtc使用的频道 - public var rtcRtcToken: String = "" //rtc join使用 - public var rtcRtmToken: String = "" //rtc mcc使用 - public var rtcChorusChannelName: String = "" //rtc 合唱使用的频道 - public var rtcChorusRtcToken: String = "" //rtc 合唱join使用 + public var channelName: String = "" + public var rtmToken007: String = "" + public var rtcToken007: String = "" + public var rtcChannelName: String = "" + public var rtcRtcToken: String = "" + public var rtcRtmToken: String = "" + public var rtcChorusChannelName: String = "" + public var rtcChorusRtcToken: String = "" } ``` @@ -274,17 +274,11 @@ open class AUIRoomConfig: NSObject { -- `rtcChannelName`：主频道的频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流。 +- `rtcChannelName`：主频道的频道名。在合唱场景下，领唱需要加入两个频道，在主频道发布人声和播放器的混流，在合唱频道发布麦克风采集的音频流。伴唱需要加入合唱频道来同步领唱的人声。 - `rtcRtcToken`：加入主频道的 RTC Token。 - - - 请确保你使用的 RTC Token 是 AccessToken2，详见[使用 Token 鉴权](https://doc.shengwang.cn/doc/rtc/ios/basic-features/token-authentication)。 - - - -- `rtcRtmToken`：用于音乐内容中心鉴权的 RTM Token。 +- `rtcRtmToken`：RTM Token，用于音乐内容中鉴权。 - `rtcChorusChannelName`：合唱频道名。独唱场景下，该参数可为空。 diff --git "a/markdown/online-ktv/AUIKaraoke/ios-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/ios-\351\233\206\346\210\220.md" index d54a79575bb..3526ebae341 100644 --- "a/markdown/online-ktv/AUIKaraoke/ios-\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/AUIKaraoke/ios-\351\233\206\346\210\220.md" @@ -169,9 +169,13 @@ karaokeView.onClickOffButton = { [weak self] in } ``` -### 6. 异常处理 +## 后续步骤 -调用 `subscribeError` 来订阅房间相关的异常回调，如 Token 过期。调用 `bindRespDelegate` 绑定对应房间的响应，如房间被销毁、用户被踢出等。 +成功搭建一个在线 K 歌房间后，你还可以参考本节对房间的异常状态进行处理。 + +### 异常处理 + +调用 `subscribeError` 来订阅房间相关的异常回调，如 Token 过期、房间被销毁等。调用 `bindRespDelegate` 绑定对应房间的响应，如房间被销毁、用户被踢出等。 在退出房间时调用 `unsubscribeError` 和 `unbindRespDelegate` 来取消订阅和绑定。 @@ -182,11 +186,23 @@ KaraokeUIKit.shared.subscribeError(roomId: self.roomInfo?.roomId ?? "", delegate //在退出房间时取消订阅 KaraokeUIKit.shared.unsubscribeError(roomId: self.roomInfo?.roomId ?? "", delegate: self) -//在拉起房间后绑定房间的响应 +//Token 即将过期回调，更新 Token +@objc func onTokenPrivilegeWillExpire(channelName: String?) { + generatorToken { config, _ in + KaraokeUIKit.shared.renew(config: config) + } +} + +//在拉起房间后绑定对应房间的响应 KaraokeUIKit.shared.bindRespDelegate(delegate: self) //在退出房间时取消绑定 KaraokeUIKit.shared.unbindRespDelegate(delegate: self) + +// 通过 onRoomDestroy 来处理房间销毁 +func onRoomDestroy(roomId: String) { + //处理房间被销毁 +} ``` ## 示例项目 @@ -195,4 +211,4 @@ KaraokeUIKit.shared.unbindRespDelegate(delegate: self) ## API 参考 -- [AUIKaraoke API]() \ No newline at end of file +- [AUIKaraoke Swift API]() \ No newline at end of file diff --git "a/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" "b/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" index ca20f514bda..c21f6d92bb8 100644 --- "a/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" +++ "b/markdown/online-ktv/AUIKaraoke/\347\273\204\344\273\266\344\273\213\347\273\215.md" @@ -55,7 +55,9 @@ AUIKaraoke 提供下列核心功能： - 房间内的用户彼此之间可以送礼物，增加互动趣味性。 -**文字聊天**：除了上麦互动，K 歌房间内的用户还可以发送文字消息进行互动。 +**文字聊天**： + +- 除了上麦互动，K 歌房间内的用户还可以发送文字消息进行互动。 @@ -63,16 +65,18 @@ AUIKaraoke 提供下列核心功能： 除了 AUIKaraoke 这一含 UI 的解决方案，目前声网针对在线 K 歌房场景还提供了无 UI 解决方案，其中无 UI 解决方案包括[无场景化方案](https://confluence.agoralab.co/)、[场景化 API 方案](https://confluence.agoralab.co/)，各方案之间的对比详见[方案对比]()。 -【这篇文档链接到k歌房场景介绍里面的方案对比，为了方便review所以贴在这里，之后会删掉】 - -| 类别 | AUIKaraoke | 无场景化方案 | 场景化 API 方案 | +| 类别 | AUIKaraoke | 场景化 API 方案 | 无场景化方案 | | :----------- | :----------------------------------------------------------- | :----------------------------------------------------------- | :----------------------------------------------------------- | -| 适用客户 | 适用于开发基础较弱、开发排期紧、需要快速上线的用户。 | 适用于开发能力强且定制化需求极高的用户。 | 适用于开发排期紧、需快速上线、有一定定制化需求的用户。 | -| 功能实现难度 | 低；可在 10 行代码内搭建一个的 K 歌场景应用。 | 中等；需直接使用实时互动 SDK 接口，并自行设计、开发所有业务逻辑和 UI。 | 较低；场景化 API 代码结构较为简单，使用场景化 API 可以简化歌曲管理、播放管理等逻辑，但房间管理、麦位管理等功能及 UI 需自行开发设计。 | -| 可拓展性 | 中等；支持通过组件自定义 K 歌房间的 UI 和相关业务逻辑，如 UI 的调整、业务的增删。如有更灵活的自定义需求，可以直接使用 AUIKit 提供的 UI 和 Service 组件进行组合开发。 | 高；可自行进行功能定制化修改。 | 较高，可自行进行功能定制化修改。 | -| 接入难度 | 较低；将实时互动 SDK、RTM SDK、场景化 API 统一封装在组件内，集成 AUIKaraoke、AUIKit 即可实现场景搭建。 | 中等；需要根据自己实际的业务需求自行集成实时互动、RTM 等 SDK。 | 低；需要集成集成场景化 API、实时互动 SDK。 | +| 适用用户 | 适用于开发基础较弱、开发排期紧、需要快速上线的用户。 | 适用于开发排期紧、需快速上线、有一定定制化需求的用户。 | 适用于开发能力强且定制化需求极高的用户。 | +| 功能实现难度 | 低；可在 10 行代码内搭建一个 K 歌场景应用。 | 较低；场景化 API 代码结构较为简单，使用场景化 API 可以简化歌曲管理、播放管理等逻辑，但房间管理、麦位管理等功能及 UI 需自行开发设计。 | 中等；需直接使用实时互动 SDK 接口，并自行设计、开发所有业务逻辑和 UI。 | +| 可拓展性 | 中等；支持通过组件自定义 K 歌房间的 UI 和相关业务逻辑，如 UI 的调整、业务的增删。如有更灵活的自定义需求，可以直接使用 AUIKit 提供的 UI 和 Service 组件进行组合开发。 | 较高，可自行进行功能定制化修改。 | 高；可自行进行功能定制化修改。 | +| 接入难度 | 较低；将实时互动 SDK、RTM SDK、场景化 API 统一封装在组件内，集成 AUIKaraoke、AUIKit 即可实现场景搭建。 | 低；需要集成场景化 API、实时互动 SDK。 | 中等；需要根据自己实际的业务需求自行集成实时互动、RTM 等 SDK。 | + + + +不同的方案计费方式不同，详情请联系[技术支持](https://docs.agora.io/cn/Agora%20Platform/ticket?platform=All%20Platforms)。 -不同的方案计费方式不同，详情请联系[技术支持](https://docs.agora.io/cn/Agora%20Platform/ticket?platform=All%20Platforms)。 + diff --git "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" index df227a867be..66df6e912ab 100644 --- "a/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" +++ "b/markdown/online-ktv/AUIKaraoke/\351\233\206\346\210\220/android-\351\233\206\346\210\220.md" @@ -13,27 +13,41 @@ AUIKaraoke 是一个基于 [AUIKit](https://github.com/AgoraIO-Community/AUIKit/ ### 前提条件 - [Git](https://git-scm.com/downloads) + - Android API Level 24 及以上 + - Android Studio 3.5 及以上 + - Android 设备，版本 Android 7.0 及以上 -- [Java Development Kit](https://www.oracle.com/java/technologies/javase-downloads.html) 17 及以上 - + -声网推荐使用真机运行项目。部分模拟机可能存在功能缺失或者性能问题。 + 声网推荐使用真机运行项目。部分模拟机可能存在功能缺失或者性能问题。 - + + +- [Java Development Kit](https://www.oracle.com/java/technologies/javase-downloads.html) 17 及以上 - 有效的声网开发者账号和声网项目，请参考[开通服务](https://doc.shengwang.cn/doc/rtc/ios/get-started/enable-service)，从声网控制台获取以下信息： - - App ID：声网随机生成的字符串，用于识别你的 app。 - - RTC Token：在你的业务服务器上生成的 RTC Token。你的 app 客户端加入频道时会使用 Token 对用户进行鉴权。 - - RTM Token（refer 到 rtm token 文档） + - App ID：声网随机生成的字符串，用于识别你的 App。 + + - RTC 临时 Token：在声网控制台获取，用于客户端加入频道时对用户鉴权，有效期为 24 小时。 + + - RTM 临时 Token：在声网控制台获取，有效期为 24 小时。 + + + + 在生产环境中，为保证通信安全，声网推荐你部署业务服务器生成 Token，详情请参考[使用 Token 鉴权](https://doc.shengwang.cn/doc/rtc/android/basic-features/token-authentication) 。 + + ### 创建项目 如需创建新项目，在 **Android Studio** 里，依次选择 **Phone and Tablet > Empty Activity**，创建 [Android 项目](https://developer.android.com/studio/projects/create-project)。如果你已有 Android 项目，可跳过这一步骤。 -创建项目后，**Android Studio** 会自动开始同步 gradle, 稍等片刻至同步成功后再进行下一步操作。 + + +创建项目后，**Android Studio** 会自动开始同步 gradle, 稍等片刻至同步成功后再进行下一步操作。 @@ -57,7 +71,7 @@ AUIKaraoke 是一个基于 [AUIKit](https://github.com/AgoraIO-Community/AUIKit/ 4. 添加权限并设置主题。在你的 `AndroidManifest.xml` 文件中添加下列内容： - ```java + ```xml @@ -99,12 +113,12 @@ AUIKaraoke 是一个基于 [AUIKit](https://github.com/AgoraIO-Community/AUIKit/ 创建 `AUiCommonConfig` 对象，调用 `setup` 初始化 AUIKaraoke。 -```java +```kotlin // 创建 AUiCommonConfig 对象 val config = AUiCommonConfig() config.context = application -// 获取你在声网控制台获取的 app ID -config.appId = "Agora APP ID" +// 获取你在声网控制台获取的 App ID +config.appId = "APP ID" // 用户 ID config.userId = "User ID" // 用户名 @@ -205,9 +219,63 @@ K 歌结束后，调用 `destroyRoom` 销毁房间。 ```kotlin // 销毁房间 KaraokeUiKit.destroyRoom(roomId) +// 取消订阅房间相关的异常回调 +KaraokeUiKit.unsubscribeError(roomId, errorDelegate) +// 取消绑定对应房间的响应 +KaraokeUiKit.unbindRespDelegate(respDelegate) +``` + +## 后续步骤 + +成功搭建一个在线 K 歌房间后，你还可以参考本节对房间的异常状态进行处理。 + +### 异常处理 + +成功拉起房间后，你可以调用 `subscribeError` 来订阅房间相关的异常回调，如 Token 过期等。调用 `bindRespDelegate` 绑定对应房间的响应，如房间被销毁、用户被踢出等。 + +在退出房间时调用 `unsubscribeError` 和 `unbindRespDelegate` 来取消订阅和绑定。 + +```swift +// 订阅房间相关的异常回调 +val errorDelegate = object: AUIRtmErrorProxyDelegate{ + override fun onTokenPrivilegeWillExpire(channelName: String?) { + // Token过期时回调 + } +} +KaraokeUiKit.subscribeError(roomInfo.roomId, errorDelegate) + +// 绑定响应 +val respDelegate = object: AUIRoomManagerRespDelegate{ + override fun onRoomDestroy(roomId: String){ + // 房间被销毁 + } +} +KaraokeUiKit.bindRespDelegate(respDelegate) +``` + +当你的 Token 过期后，你需要调用 `renewToken` 来传入新的 Token。关于 Token 的详细解释请参考 [AUiRoomConfig](#)。 + +```kotlin +val config = AUiRoomConfig(roomInfo.roomId) +// 登陆 RTM 系统时用的 RTM Token +config.rtmToken = "" +// 登陆 RTM 系统时用的 RTC Token +config.rtcToken = "" +// RTM Token，用于音乐内容中鉴权 +config.rtcRtmToken = "" +// 加入主频道的 RTC Token +config.rtcRtcToken = "" +// 根据合唱频道名和用户 ID 生成的 RTC Token，用于加入合唱频道时进行鉴权。 +config.rtcChorusRtcToken = "" +// 更新 Token +KaraokeUiKit.renewToken(config) ``` ## 示例项目 声网在 GitHub 上提供一个开源的示例项目 [AUIKitKaraoke](https://github.com/AgoraIO-Community/AUIKitKaraoke/tree/main/Android) 供你参考。 +## API 参考 + +- [AUIKaraoke Kotlin API]() +