快速集成 PaaS 方案

技术原理Copy Anchor Link

在线 K 歌房内用户角色说明如下：

实现在线 K 歌房场景中不同角色流程如下：

房主实现流程Copy Anchor Link

1. 房主通过第三方云服务发起指令创建歌房，创建成功后调用 joinChannel 方法加入歌房。
   • 加入歌房前，调用 create [2/2] 方法创建并初始化 RtcEngine 实例，并将实例的音频场景设置为合唱（CHORUS）。
   • 调用 setClientRole 方法将用户角色设置为主播（ BROADCASTER）。
2. 房主自动上麦成为连麦主播，可以点歌成为主唱，并邀请其他连麦主播进行合唱；也可以接受主唱的邀请，成为合唱者。
3. 房主可以通过第三方云服务对连麦主播发起下麦指令，同时房间内所有用户会收到该连麦主播的下麦信息并更新房间内麦位信息。
4. 房主离开歌房后，房间对象自动销毁，其他成员自动离开歌房。

主唱实现流程Copy Anchor Link

下图展示在线 K 歌房场景的主唱端的实现流程：

1. 用户选择歌房，调用 joinChannel 方法加入歌房。 加入歌房前，调用 create [2/2] 方法创建并初始化 RtcEngine 实例，并将实例的音频场景设置为合唱（CHORUS）。

2. 用户通过第三方云服务发起上麦指令，并调用 setClientRole 方法将用户角色设置为主播（ BROADCASTER）。上麦后成为连麦主播，此时可以与房间内其他连麦主播进行语音互动。同时房间内所有用户收到主播端的上麦信息并更新房间内麦位信息。

3. 用户可以点歌，从声网内容中心获取歌单，并下载歌曲文件和歌词文件，成为主唱。

4. 主唱可以独唱，也可以发起合唱邀请指令，邀请房间内其他连麦主播一起合唱歌曲。

5. 主唱调用 IMediaPlayer 类的方法播放歌曲，并伴随歌曲唱歌。如需切换原唱或伴奏模式，可以调用 setAudioDualMonoMode 方法。同时，主唱调用 joinChannelEx 方法，实现合唱。

6. 主唱在唱歌的同时，调用 sendStreamMessage 方法将当前歌曲播放进度同步到房间内所有用户。合唱者和听众可以结合歌词组件实现歌词同步显示，并自定义歌词界面，详见歌词组件。

7. 主唱通过第三方云服务发起下麦指令，并调用 leaveChannel 方法离开歌房。

合唱者实现流程Copy Anchor Link

下图展示在线 K 歌房场景的合唱者的实现流程：

1. 用户选择歌房，调用 joinChannel 方法加入歌房。 加入歌房前，调用 create [2/2] 方法创建并初始化 RtcEngine 实例，并将实例的音频场景设置为合唱（CHORUS）。

2. 用户通过第三方云服务发起上麦指令，并调用 setClientRole 方法将用户角色设置为主播（ BROADCASTER）。上麦后成为连麦主播，此时可以与房间内其他连麦主播进行语音互动。同时房间内所有用户收到主播端的上麦信息并更新房间内麦位信息。

3. 主唱点歌并发出合唱邀请指令后，连麦主播可以接受主唱的邀请，并下载歌曲文件和歌词文件，成为合唱者。

4. 合唱者调用 IMediaPlayer 类的方法播放本地歌曲，并伴随歌曲与主唱一起唱歌，并调用 muteRemoteAudioStream 方法静音主唱的歌曲。

5. 合唱者通过 onStreamMessage 回调接收主唱发送的数据流，实现歌曲同步。同时结合歌词组件实现歌词同步显示，并自定义歌词界面，详见歌词组件。

6. 合唱者通过第三方云服务发起下麦指令，并调用 leaveChannel 方法离开歌房。

听众实现流程Copy Anchor Link

1. 用户选择歌房，调用 joinChannel 方法加入歌房。

   • 加入歌房前，调用 create [2/2] 方法创建并初始化 RtcEngine 实例，并将实例的音频场景设置为合唱（CHORUS）。
   • 调用 setClientRole 方法将用户角色设置为听众（ AUDIENCE）。

2. 主播上麦成为主唱后，听众通过第三方云服务同步房间内麦位信息。

3. 主唱发起指令设置当前歌曲 ID，听众接收主唱指令并更新当前歌曲 ID。主唱唱歌时，听众接收主唱的音频流。

   听众如需上麦，需要再次调用 setClientRole 方法将用户角色设为 BROADCASTER，才可以在房间内发布音频流。

4. 听众通过第三方云服务发起获取当前歌词指令，并下载歌词。同时结合 onStreamMessage 回调和歌词组件，实时同步歌词进度。

5. 听众调用 leaveChannel 方法离开歌房。

前提条件Copy Anchor Link

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

• Android Studio 4.0.0 或以上版本。
• Android 4.1 或以上版本的设备。声网推荐使用真机，部分模拟机可能无法支持本项目的全部功能。
• Python 3.X。
• 第三方云服务命令行工具。
• 有效的声网开发者账号。
• 有效的声网项目，获取项目的 App ID 以及一个 RTM Token。详情请参考使用 RTM Token 鉴权。

• 如果你的网络环境部署了防火墙，请参考应用企业防火墙限制以正常使用声网服务。

项目配置Copy Anchor Link

根据下表提供的链接，下载对应平台的 SDK 并集成到你的项目中，并联系 sales@shengwang.cn 开通内容中心服务。

实现在线 K 歌Copy Anchor Link

本节介绍如何实现在线 K 歌。

初始设置Copy Anchor Link

加入歌房前，调用以下方法进行初始设置：

示例代码如下：

RtcEngineConfig config = new RtcEngineConfig();
config.mContext = mContext;
config.mAppId = appid;
config.mEventHandler = mIRtcEngineEventHandler;
config.mChannelProfile = Constants.CHANNEL_PROFILE_LIVE_BROADCASTING;
config.mAudioScenario = Constants.AUDIO_SCENARIO_CHORUS;
mRtcEngine = RtcEngine.create(config);

加入/离开歌房Copy Anchor Link

调用以下方法加入或离开歌房：

独唱场景下，主唱发布播放器音频流和麦克风采集音频流，示例代码如下：

mediaPlayer = engine.createMediaPlayer();
mediaPlayer.registerPlayerObserver(this);
mediaPlayer.open(url, 0);
ChannelMediaOptions options = new ChannelMediaOptions();
options.autoSubscribeVideo = true;
options.autoSubscribeAudio = true;
options.publishScreenCaptureVideo = false;
options.publishCameraTrack = false;
// 发布麦克风采集音频流
options.publishMicrophoneTrack = true;
options.enableAudioRecordingOrPlayout = true;
options.publishMediaPlayerId = mediaPlayer.getMediaPlayerId();
// 发布播放器音频流
options.publishMediaPlayerAudioTrack = true;
engine.updateChannelMediaOptions(options);

合唱场景下，主唱调用 joinChannelEx 发布另一路音频流，示例代码如下：

mediaPlayer = engine.createMediaPlayer();
mediaPlayer.registerPlayerObserver(this);
mediaPlayer.open(url, 0);
ChannelMediaOptions mediaOptions = new ChannelMediaOptions();
mediaOptions.autoSubscribeAudio = false;
mediaOptions.autoSubscribeVideo = false;
mediaOptions.publishMicrophoneTrack = false;
mediaOptions.publishCameraTrack = false;
mediaOptions.publishMediaPlayerId = mediaPlayer.getMediaPlayerId();
// 发布播放器音频流
mediaOptions.publishMediaPlayerAudioTrack = true;
mediaOptions.enableAudioRecordingOrPlayout = false;
mediaOptions.clientRoleType = Constants.CLIENT_ROLE_BROADCASTER;
rtcConnection.channelId = channel2;
rtcConnection.localUid = channel2Uid;
int ret = engine.joinChannelEx(null, rtcConnection, mediaOptions, iRtcEngineEventHandler2);

上麦/下麦Copy Anchor Link

调用以下方法进行上麦或下麦：

音频相关Copy Anchor Link

主唱调用以下方法设置音频流：

播放器相关Copy Anchor Link

参考获取版权音乐来创建并初始化音乐播放器，获取并加载版权音乐。

当你无需再使用音乐播放器时，你需要：

1. 调用 IAgoraMusicPlayer 类下的 destroy 销毁音乐播放器；

2. 调用 IAgoraMusicContentCenter 类下的 destroy 销毁音乐内容中心实例；

3. 调用 RtcEngine 类下的 destroy 销毁引擎。

   Copy Text

   void destroy() {
   musicPlayer.unRegisterPlayerObserver(mediaPlayerObserver);
   musicPlayer.destroy();
   musicPlayer = null;
   
   mcc.unregisterEventHandler();
   IAgoraMusicContentCenter.destroy();
   
   contentCenterConfiguration.eventHandler = null;
   contentCenterConfiguration = null;
   mcc = null;
   
   rtcEngine.destroy();
   rtcEngine = null;
   }

你可以参考版权音乐 API 文档了解更多详细信息，音乐播放器的参数调节、推流设置、事件回调等请参考媒体播放器 API 文档。

歌曲/歌词同步Copy Anchor Link

示例代码如下：

// 以下代码发送接收的 json 格式仅为示例格式，具体协议格式根据你的具体项目而定。
DataStreamConfig cfg = new DataStreamConfig();
cfg.syncWithAudio = true;
cfg.ordered = true;
mStreamId = getRtcEngine().createDataStream(cfg);
private void sendSyncLrc(String lrcId, long duration, long time) {
    Map<String, Object> msg = new HashMap<>();
    msg.put("cmd", "setLrcTime");
    msg.put("lrcId", lrcId);
    msg.put("duration", duration);
    msg.put("time", time);//ms
    JSONObject jsonMsg = new JSONObject(msg);
    int streamId = RoomManager.Instance(mContext).getStreamId();
    int ret = RoomManager.Instance(mContext).getRtcEngine().sendStreamMessage(streamId, jsonMsg.toString().getBytes());
    if (ret < 0) {
        mLogger.e("sendSyncLrc() sendStreamMessage called returned: ret = [%s]", ret);
    }
}
@Override
public void onStreamMessage(int uid, int streamId, byte[] data) {
    JSONObject jsonMsg;
        String strMsg = new String(data);
        jsonMsg = new JSONObject(strMsg);
        if (jsonMsg.getString("cmd").equals("setLrcTime")) {
            long position = jsonMsg.getLong("time");
            if (position == 0) {
                mHandler.obtainMessage(ACTION_ON_RECEIVED_PLAY, uid).sendToTarget();
            } else if (position == -1) {
                mHandler.obtainMessage(ACTION_ON_RECEIVED_PAUSE, uid).sendToTarget();
            } else {
                Bundle bundle = new Bundle();
                bundle.putInt("uid", uid);
                bundle.putLong("time", position);
                Message message = Message.obtain(mHandler, ACTION_ON_RECEIVED_SYNC_TIME);
                message.setData(bundle);
                message.sendToTarget();
            }
        }
}

原唱及伴奏切换Copy Anchor Link

附加功能Copy Anchor Link

人声音效Copy Anchor Link

调用 setAudioEffectPreset 方法，在不改变原声的性别特征的前提下，设置人声音效。设置音效后，频道内所有用户都能听到该效果。详见设置人声效果。

耳返Copy Anchor Link

调用 enableInEarMonitoring [2/2] 方法开启主唱的耳返功能。

歌唱评分Copy Anchor Link

调用 enableAudioVolumeIndication 方法开启歌唱评分功能，并通过 onAudioVolumeIndication 回调，结合声网歌词组件实现歌唱评分效果，详见歌词打分组件。

相关文档Copy Anchor Link

• RESTful API
• 歌词打分组件
• 实时互动 API 参考

本文介绍如何通过声网实时互动 SDK 在你的 iOS 项目里实现在线 K 歌房的主要功能。

技术原理Copy Anchor Link

在线 K 歌房内用户角色说明如下：

实现在线 K 歌房场景中不同角色流程如下：

房主实现流程Copy Anchor Link

1. 房主通过第三方云服务发起指令创建歌房，创建成功后调用 joinChannelByToken 方法加入歌房。
   • 加入歌房前，调用 sharedEngineWithConfig 方法创建并初始化 AgoraRtcEngineKit 实例，并将实例的音频场景设置为合唱（AgoraAudioScenarioChorus）。
   • 调用 setClientRole 方法将用户角色设置为主播（ AgoraClientRoleBroadcaster）。
2. 房主自动上麦成为连麦主播，可以点歌成为主唱，并邀请其他连麦主播进行合唱；也可以接受主唱的邀请，成为合唱者。
3. 房主可以通过第三方云服务对连麦主播发起下麦指令，同时房间内所有用户会收到该连麦主播的下麦信息并更新房间内麦位信息。
4. 房主离开歌房后，房间对象自动销毁，其他成员自动离开歌房。

主唱实现流程Copy Anchor Link

参考下图实现在线 K 歌房场景的主唱端流程：

1. 用户选择歌房，调用 joinChannelByToken 方法加入歌房。 加入歌房前，调用 sharedEngineWithConfig 方法创建并初始化 AgoraRtcEngineKit 实例，并将实例的音频场景设置为合唱（AgoraAudioScenarioChorus）。

2. 用户通过第三方云服务发起上麦指令，并调用 setClientRole 方法将用户角色设置为主播（ AgoraClientRoleBroadcaster）。上麦后成为连麦主播，此时可以与房间内其他连麦主播进行语音互动。同时房间内所有用户收到主播端的上麦信息并更新房间内麦位信息。

3. 用户可以点歌，从声网内容中心获取歌单，并下载歌曲文件和歌词文件，成为主唱。

4. 主唱可以独唱，也可以发起合唱邀请指令，邀请房间内其他连麦主播一起合唱歌曲。

5. 主唱调用 AgoraRtcMediaPlayerProtocol 类的方法播放歌曲，并伴随歌曲唱歌。如需切换原唱或伴奏模式，可以调用 setAudioDualMonoMode 方法。同时，主唱调用 joinChannelExByToken 方法，实现合唱。

6. 主唱在唱歌的同时，调用 sendStreamMessage 方法将当前歌曲播放进度同步到房间内所有用户。合唱者和听众可以结合歌词组件实现歌词同步显示，并自定义歌词界面，详见歌词打分组件。

7. 主唱通过第三方云服务发起下麦指令，并调用 leaveChannel 方法离开歌房。

合唱者实现流程Copy Anchor Link

下图展示在线 K 歌房场景的合唱者实现流程：

1. 用户选择歌房，调用 joinChannelByToken 方法加入歌房。 加入歌房前，调用 sharedEngineWithConfig 方法创建并初始化 AgoraRtcEngineKit 实例，并将实例的音频场景设置为合唱（AgoraAudioScenarioChorus）。

2. 用户通过第三方云服务发起上麦指令，并调用 setClientRole 方法将用户角色设置为主播（ AgoraClientRoleBroadcaster）。上麦后成为连麦主播，此时可以与房间内其他连麦主播进行语音互动。同时房间内所有用户收到主播端的上麦信息并更新房间内麦位信息。

3. 主唱点歌并发出合唱邀请指令后，连麦主播可以接受主唱的邀请，并下载歌曲文件和歌词文件，成为合唱者。

4. 合唱者调用 AgoraRtcMediaPlayerProtocol 类的方法播放本地歌曲，并伴随歌曲与主唱一起唱歌，并调用 muteRemoteAudioStream 方法静音主唱的歌曲。

5. 合唱者通过 receiveStreamMessageFromUid 回调接收主唱发送的数据流，实现歌曲同步。同时结合歌词组件实现歌词同步显示，并自定义歌词界面，详见歌词打分组件。

6. 合唱者通过第三方云服务发起下麦指令，并调用 leaveChannel 方法离开歌房。

听众实现流程Copy Anchor Link

1. 用户选择歌房，调用 joinChannelByToken 方法加入歌房。

   • 加入歌房前，调用 sharedEngineWithConfig 方法创建并初始化 AgoraRtcEngineKit 实例，并将实例的音频场景设置为合唱（AgoraAudioScenarioChorus）。
   • 调用 setClientRole 方法将用户角色设置为听众（ AgoraClientRoleAudience）。

2. 主播上麦成为主唱后，听众通过第三方云服务同步房间内麦位信息。

3. 主唱发起指令设置当前歌曲 ID，听众接收主唱指令并更新当前歌曲 ID。主唱唱歌时，听众接收主唱的音频流。

   听众如需上麦，需要再次调用 setClientRole 方法将用户角色设为 AgoraClientRoleBroadcaster，才可以在房间内发布音频流。

4. 听众通过第三方云服务发起获取当前歌词指令，并下载歌词。同时结合 receiveStreamMessageFromUid 回调和歌词组件，实时同步歌词进度。

5. 听众调用 leaveChannel 方法离开歌房。

前提条件Copy Anchor Link

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

• Xcode 12.0 或以上版本。
• 已安装 CocoaPods。
• iOS 11.0 或以上版本的设备。部分模拟机可能无法支持本项目的全部功能，所以推荐使用真机。
• Python 3.X。
• 第三方云服务命令行工具。
• 有效的声网开发者账号。
• 有效的声网项目，获取项目的 App ID 以及一个 RTM Token。详情请参考使用 RTM Token 鉴权。

• 如果你的网络环境部署了防火墙，请参考应用企业防火墙限制以正常使用声网服务。

项目配置Copy Anchor Link

根据下表提供的链接，下载对应平台的 SDK 并集成到你的项目中，并联系 sales@shengwang.cn 开通内容中心服务。

实现在线 K 歌Copy Anchor Link

本节介绍如何实现在线 K 歌。

初始设置Copy Anchor Link

加入歌房前，调用以下方法进行初始设置：

AgoraRtcEngineConfig *config = [AgoraRtcEngineConfig new];
config.appId = appId;
config.audioScenario = AgoraAudioScenarioChorus;
config.channelProfile = AgoraChannelProfileLiveBroadcasting;
AgoraRtcEngineKit *rtcEngine = [AgoraRtcEngineKit sharedEngineWithConfig:config delegate:self];

let config = AgoraRtcEngineConfig();
config.appId = BuildConfig.AppId
config.audioScenario = .chorus
config.channelProfile = .liveBroadcasting
rtcEngine = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self)

加入/离开歌房Copy Anchor Link

调用以下方法加入或离开歌房：

独唱场景下，主唱发布播放器音频流和麦克风采集音频流，示例代码如下：

id<AgoraRtcMediaPlayerProtocol> rtcMediaPlayer = [rtcEngine createMediaPlayerWithDelegate:self];
AgoraRtcChannelMediaOptions *option = [AgoraRtcChannelMediaOptions new];
option.publishMicrophoneTrack = YES;
option.publishMediaPlayerAudioTrack = YES;
option.enableAudioRecordingOrPlayout = YES;
option.publishMediaPlayerId = [rtcMediaPlayer getMediaPlayerId];
NSInteger ret = [rtcEngine joinChannelByToken:nil channelId:channelId uid:uid mediaOptions:option joinSuccess:nil];

rtcMediaPlayer = rtcEngine.createMediaPlayer(with: self)
let option = AgoraRtcChannelMediaOptions()
option.publishMicrophoneTrack = .of(true)
option.publishMediaPlayerAudioTrack = .of(true)
option.enableAudioRecordingOrPlayout = .of(true)
option.publishMediaPlayerId = rtcMediaPlayer.getMediaPlayerId()
let ret = rtcEngine.joinChannel(byToken: nil, channelId: channelId, uid: uid, mediaOptions: option)

合唱场景下，主唱调用 joinChannelExByToken 发布另一路音频流，示例代码如下：

id<AgoraRtcMediaPlayerProtocol> rtcMediaPlayer = [rtcEngine createMediaPlayerWithDelegate:self];
AgoraRtcChannelMediaOptions *option = [AgoraRtcChannelMediaOptions new];
option.autoSubscribeAudio = NO;
option.autoSubscribeVideo = NO;
option.publishMicrophoneTrack = NO;
option.publishMediaPlayerId = [rtcMediaPlayer getMediaPlayerId];
/// 发布播放器音频流
option.publishMediaPlayerAudioTrack = YES;
option.enableAudioRecordingOrPlayout = NO;
AgoraRtcConnection *connection = [AgoraRtcConnection new];
connection.channelId = @"";
connection.localUid = 0;

NSInteger ret = [rtcEngine joinChannelExByToken:@"" connection:connection delegate:self mediaOptions:option joinSuccess:nil];

rtcMediaPlayer = rtcEngine.createMediaPlayer(with: self)
rtcMediaPlayer.open(url, 0);
let option = AgoraRtcChannelMediaOptions()
option.autoSubscribeAudio = AgoraRtcBoolOptional.of(false)
option.autoSubscribeVideo = AgoraRtcBoolOptional.of(false)
option.publishMicrophoneTrack = .of(false)
option.publishMediaPlayerId = rtcMediaPlayer.getMediaPlayerId();
// 发布播放器音频流
option.publishMediaPlayerAudioTrack = .of(true)
option.enableAudioRecordingOrPlayout = .of(false)
let connection = AgoraRtcConnection()
connection.channelId = ""
connection.localUid = 0

int ret = rtcEngine?.joinChannelEx(byToken: nil, connection: connection, delegate: self, mediaOptions: mediaOption, joinSuccess: nil)

上麦/下麦Copy Anchor Link

调用以下方法进行上麦或下麦：

音频相关Copy Anchor Link

主唱调用以下方法设置音频流：

播放器相关Copy Anchor Link

参考获取版权音乐来创建并初始化音乐播放器，获取并加载版权音乐。

当你无需再使用音乐播放器时，你需要：

1. 调用 destroyMediaPlayer 销毁音乐播放器；
2. 调用 AgoraMusicContentCenter 下的 destroy 销毁音乐内容中心对象；
3. 调用 AgoraRtcEngineKit 的 destroy 销毁引擎。

- (void)destroy {
    [self.mcc destroyMusicPlayer:self.player];
    self.player = nil;

    [self.mcc registerEventDelegate:nil];
    [AgoraMusicContentCenter destroy];
    self.mcc = nil;

    [AgoraRtcEngineKit destroy];
    self.agoraKit = nil;
}

你可以参考版权音乐 API 文档了解更多详细信息，音乐播放器的参数调节、推流设置、事件回调等请参考内置媒体播放器 API 文档。

歌曲/歌词同步Copy Anchor Link

示例代码如下：

AgoraDataStreamConfig *config = [AgoraDataStreamConfig new];
config.ordered = NO;
config.syncWithAudio = NO;
NSInteger dataStreamId = -1;
int ret = [rtcEngine createDataStream:&dataStreamId config:config];
if (ret < 0) {
    NSLog(@"createDataStream error");
}
ret = [rtcEngine sendStreamMessage:dataStreamId data:[NSData new]];
if (ret < 0) {
    NSLog(@"sendStreamMessage error");
}

/// receiveStreamMessage in remote
- (void)rtcEngine:(AgoraRtcEngineKit * _Nonnull)engine receiveStreamMessageFromUid:(NSUInteger)uid streamId:(NSInteger)streamId data:(NSData * _Nonnull)data {
}

let config = AgoraDataStreamConfig()
config.ordered = false
config.syncWithAudio = false
var ret = rtc.createDataStream(&dataStreamId, config: config)
if ret < 0 {
    print("createDataStream error")
}

let ret = rtcEngine.sendStreamMessage(streamId, data: jsonData)
if code < 0 {
    print("sendRtcStreamMessage error")
}

func rtcEngine(_: AgoraRtcEngineKit, receiveStreamMessageFromUid uid: UInt, streamId: Int, data: Data) {
}

原唱及伴奏切换Copy Anchor Link

附加功能Copy Anchor Link

人声音效Copy Anchor Link

调用 setAudioEffectPreset 方法，在不改变原声的性别特征的前提下，设置人声音效。设置音效后，频道内所有用户都能听到该效果。详见设置人声效果。

耳返Copy Anchor Link

调用 enableInEarMonitoring [2/2] 方法开启主唱的耳返功能。

歌唱评分Copy Anchor Link

调用 enableAudioVolumeIndication 方法开启歌唱评分功能，并通过 reportAudioVolumeIndicationOfSpeakers 回调，结合声网歌词组件实现歌唱评分效果，详见歌词打分组件。

相关文档Copy Anchor Link

• RESTful API
• 歌词打分组件
• 实时互动 API 参考