场景化 API 方案的集成和实现文档 #2871
场景化 API 方案的集成和实现文档 #2871
Conversation
markdown/online-ktv/改进/场景化方案/iOS/K 歌房场景化 Objective-C API for iOS.md
Outdated
Show resolved
Hide resolved
markdown/online-ktv/改进/场景化方案/iOS/K 歌房场景化 Objective-C API for iOS.md
Outdated
Show resolved
Hide resolved
|
|
||
| #### 参数 | ||
|
|
||
| - `songCode`: 歌曲编号。 |
There was a problem hiding this comment.
歌曲编号和歌词编号是通过什么获取的？用户自己随便填的么，还是要和音乐文件的名字对应之类的？建议写清楚
There was a problem hiding this comment.
在 songCode 参数要填一次歌曲编号，然后 config 里又要填一个 songCode 参数。这两个参数有区别么？
| - `KTVLoadSongStateOK`: 加载成功 | ||
| - `KTVLoadSongStateInProgress`: 正在加载中 | ||
| - `KTVLoadSongStateNoLyricUrl`: 歌曲无法加载，缺少歌词地址 | ||
| - `KTVLoadSongStatePreloadFail`: 加载失败 |
markdown/online-ktv/改进/场景化方案/iOS/K 歌房场景化 Objective-C API for iOS.md
Outdated
Show resolved
Hide resolved
markdown/online-ktv/改进/场景化方案/iOS/K 歌房场景化 Objective-C API for iOS.md
Outdated
Show resolved
Hide resolved
| - (void)playSong:(NSInteger)songCode | ||
| ``` | ||
|
|
||
| 播放歌曲。 |
There was a problem hiding this comment.
一个 KTV API 模块里，可以多次调用 playSong 播放多个歌曲么？还是不管调用多少次 playSong，只会播放最后一次调用的歌曲？
建议写清楚。
| - `songCode`: 歌曲编号。 | ||
|
|
||
| ### stopSong | ||
|
|
There was a problem hiding this comment.
stop、pause、resume、seek、selectTrackMode、setKaraokeView 这几个 API 都没有传 songCode 的地方，看起来是只有成功调用 playSong 之后才能对当前的歌曲进行设置，建议加上调用时序限制。
尤其是 seek、selectTrackMode、setKaraokeView 这类功能和 play 的关系。比如我调了 play 播放音乐，再调了 pause，这个时候调用 seek，再调用 resume，会按照我在 seek 里设置的时间点去放音乐么？
|
|
||
| 实现点歌、独唱、合唱前，请确保你已完成如下步骤： | ||
|
|
||
| 1. 参考<a href="https://docs.agora.io/cn/online-ktv/chorus_client_ios?platform=iOS#项目配置">项目配置</a>集成所需 SDK。 |
There was a problem hiding this comment.
建议这块内容以 fragment 的形式呈现，用户就不需要点击跳转去别的地方看了。
KTV 的两篇客户端实现文档是全然不同的方案，担心用户跳转去了另一篇，就不知道回到场景化 API 的快速开始了
建议将前提条件整个章节改为：
前提条件
- 项目配置
fragment - 在工程文件中引入 xxx
疑问：使用场景化 API 不需要 xcode 这些前提条件么？
|
|
||
| 实例化 `rtcEngine`、`musicCenter`、`musicPlayer`、`streamId` 实例，并将它们通过 `initWithRtcEngine` 方法传入 KTV API 模块。调用 KTV API 模块的 API 前，请确保已调用 `initWithRtcEngine` 初始化 KTV API 实例。 | ||
|
|
||
| <div class="alert note">考虑到数据流的消息通道有频率限制，为了确保 KTV 模块和其他模块不会相互影响，声网建议你在不同模块中为数据流创建的 <code>streamId</code> 都不同。例如，如果你在其他模块中也使用 <code>sendStreamMessage</code>，请确保两个模块中创建的 <code>streamId</code> 不同。同时，每个用户在每个频道中最多只能创建 5 个数据流，请不要超出上限。</div> |
There was a problem hiding this comment.
这条 note 加在步骤 4 里是不是好些？
在这之前的描述中都没提到要使用数据流的概念，只提到了 streamId 参数，我会有点 get 不到想表达的意思，滑到步骤 4 了才知道是用 createDataStream 去创建 stream，才能有 streamid 去传入 init 方法。
There was a problem hiding this comment.
如果你在其他模块中也使用 sendStreamMessage
这里的 sendStreamMessage 要改成 createDataStream 不？我看全文只有这一个地方提到了 sendStreamMessage，不确定是不是写错了。
|
|
||
| 下图展示点歌的 API 调用时序图： | ||
|
|
||
|  |
There was a problem hiding this comment.
初始化 KTV 模块调用了 5 个 API，但图片里只写了 initWithRtcEngine。是因为只有 initWithRtcEngine 属于 KTV 场景化 API 么？
sharedEngineWithAppId、sharedContentCenterWithConfig、createMusicPlayerWithDelegate、createDataStream 这四个 API 都是必须调用的么？如果是的话，还是建议时序图里加上。
| contentCenterConfiguration.token = "<Your_Rtm_Token>"; | ||
| // self.AgoraMcc 是定义的 AgoraMusicContentCenter 的全局变量 | ||
| self.AgoraMcc = [AgoraMusicContentCenter sharedContentCenterWithConfig:contentCenterConfiguration]; | ||
| [self.AgoraMcc registerEventDelegate:<Your_DELEGATE_RECEIVER>]; |
There was a problem hiding this comment.
52 和 53 是监听回调相关实现，文内没有其他地方有解释说明，建议这里加个行内注释说明下
| ``` | ||
|
|
||
| ### 2. 获取歌曲列表 | ||
|
|
There was a problem hiding this comment.
这里面的四个 API 有 API 文档么？我没搜索到
| // 歌曲加载成功的操作 | ||
| ... | ||
| } else if(state == KTVLoadSongStateNoLyricUrl) { | ||
| // 歌曲加载失败，重试三次 |
There was a problem hiding this comment.
歌曲加载失败的操作
因为当前这步骤没代码，看不出重试三次的逻辑。
| }]; | ||
| ``` | ||
|
|
||
| ### 5. 监听并控制歌曲播放 |
There was a problem hiding this comment.
这步骤没有监听回调的示例代码。标题是不是只需写控制歌曲播放？
|
|
||
| 歌曲播放时，音乐播放器会通过 `didChangedToState` 回调向业务层通知歌曲播放状态改变。收到 `didChangedToState(AgoraMediaPlayerStatePlaying)` 回调后，你可以使用 `seek`、`pause`、`resume`、`selectAudioTrack` 等方法控制播放器。 | ||
|
|
||
| <div class="alert note">KTV API 模块内部会自动处理播放器同步，因此你也可以通过 `didChangedToState` 回调获取远端播放器的状态。</div> |
|
|
||
|  | ||
|
|
||
| 下图展示独唱的 API 调用时序图： |
There was a problem hiding this comment.
建议 note 这里简单写下：
通过更新媒体选项切换用户角色、是否发布麦克风流等
然后原文的两条内容放到步骤 5 的详细描述里。
- 主唱和上麦 xxx
- 普通听众 xxx
建议理由：看到时序图的这两句话，有点不知道什么意思，理解前后文才知道是建议xx角色设置是否发布麦克风流，所以建议图片里简单写设置的目的，然后步骤里详细写各角色要怎么设置。
| // 歌曲加载成功，则播放歌曲 | ||
| [self.ktvApi playSong:songCode]; | ||
| } else if(state == KTVLoadSongStateNoLyricUrl) { | ||
| // 歌曲加载失败，重试三次 |
|
|
||
| ```objective-c | ||
| // KTVSongType: 歌唱类型（合唱或独唱） | ||
| // KTVSingRole: 用户角色 |
There was a problem hiding this comment.
K 歌用户角色
修改理由：整篇有 clientrole 和 singrole 两种用户角色，容易引起混淆。
| // 加入频道 | ||
| [self.RTCKit joinChannelByToken:<Your_Rtc_Token> | ||
| channelId:<Your_Channel_Name> | ||
| info:nil |
| // 歌曲加载成功，则播放歌曲 | ||
| [self.ktvApi playSong:songCode]; | ||
| } else if(state == KTVLoadSongStateNoLyricUrl) { | ||
| // 歌曲加载失败，重试三次 |
| [self.RTCKit updateChannelWithMediaOptions:options]; | ||
|
|
||
|
|
||
| // 针对未上麦的听众更新媒体选项 |
| 听众的用户角色为 `AgoraClientRoleAudience`，因此无法在频道内发布音频流。如果听众想上麦与主唱语聊，需要将用户角色修改为 `AgoraClientRoleBroadcaster`。修改角色后，SDK 默认发布该连麦听众的音频流，主唱和其他听众都能听到连麦听众的声音。 | ||
|
|
||
| ```objective-c | ||
| // 针对需要上麦聊天的听众更新媒体选项 |
|
|
||
| - 主唱：加入频道，加载并播放歌曲，发布麦克风采集的音频流。KTV API 模块内部控制音乐播放器播放音乐，发布音乐到远端，将音乐播放进度同步到远端，让歌词组件进入歌词滚动状态等逻辑。 | ||
| - 伴唱：加入频道，加载并播放歌曲，发布麦克风采集的音频流。KTV API 模块内部控制音乐播放器播放音乐，同步主唱的音乐播放进度，让歌词组件进入歌词滚动状态等逻辑。 | ||
| - 听众：加入频道，加载歌曲。KTV API 模块内部控制听众订阅主唱的人声和音乐的音频合流，同步主唱的音乐播放进度，让歌词组件进入歌词滚动状态等逻辑。如果普通观众需要上麦聊天，可以更新媒体选项。 |
|
|
||
| 实时合唱场景对低延时和音质的要求很高。开启合唱前，你需要在初始化 AgoraRtcEngineKit 的方法里设置如下私有参数。 | ||
|
|
||
| ```objective-c |
There was a problem hiding this comment.
AgoraRtcEngineKit 缺代码格式
| // 加入频道 | ||
| [self.RTCKit joinChannelByToken:<Your_Rtc_Token> | ||
| channelId:<Your_Channel_Name> | ||
| info:nil |
| // 歌曲加载成功，则播放歌曲 | ||
| [self.ktvApi playSong:songCode]; | ||
| } else if(state == KTVLoadSongStateNoLyricUrl) { | ||
| // 歌曲加载失败，重试三次 |
| config.songCode = <Song_Code>; | ||
| // 伴唱一定要填主唱 UID | ||
| config.mainSingerUid = <Main_Singer_UID>; | ||
| config.coSingerUid = <Chorus_Singer_UID>; |
There was a problem hiding this comment.
伴唱 UID 可以为 0
建议和之前的角色一样加上 uid 的描述
There was a problem hiding this comment.
主唱实现那里可以不填伴唱 UID。这里的伴唱实现需要填伴唱 UID。
|
|
||
| 调用 `loadSong` 加载歌曲。加载结果会异步地通过 `withCallback` 回调通知你。收到 `withCallback(KTVLoadSongStateOK)` 回调状态后，调用 `playSong`。 | ||
|
|
||
| 听众加入频道后，默认订阅主唱发布的音频合流，即主唱人声和音乐混合的音频流。听众只需调用 `playSong` 进入歌曲播放状态即可。 |
|
|
||
| 通过 [`updateChannelWithMediaOptions`](https://docs.agora.io/cn/online-ktv/API%20Reference/ios_ng/API/toc_core_method.html#api_irtcengine_updatechannelmediaoptions) 方法在听众加入频道后更新频道媒体选项，例如是否开启本地音频采集，是否发布本地音频流等。 | ||
|
|
||
| 听众的用户角色为 `AgoraClientRoleAudience`，因此无法在频道内发布音频流。如果听众想上麦与主唱语聊，需要将用户角色修改为 `AgoraClientRoleBroadcaster`。修改角色后，SDK 默认发布该连麦听众的音频流，主唱和其他听众都能听到连麦听众的声音。 |
There was a problem hiding this comment.
如果听众想上麦与主唱或伴唱语聊
主唱、伴唱和其他听众
主语中有主唱的，是不是都可以加上伴唱？
疑问：听众上麦只能语聊、不能合唱么？
上线格式检查可参考 preprod 链接：