This page introduces how to implement the main functions of Online Karaoke in your iOS app through Agora Voice SDK v4.0.0 Beta.
The user roles in the online karaoke room are described as follows:
Role | Description |
---|---|
Room owner | The person who created the online karaoke room. They become the original cohost and can receive and send audio streams. |
Cohost | After entering the karaoke room, a user can become a cohost through a third-party cloud service, which means they can also receive and send audio streams. |
Lead singer | The cohosts of a room sing in order after selecting songs. Each cohost in turn becomes the lead singer, who can receive and send audio streams. |
Chorus member | After the lead singer initiates the chorus, a cohost can accept the invitation and become a member of the chorus. Chorus members can receive and send audio streams. |
Audience member | Users who enter the karaoke room as audience members can only receive audio streams. |
The process of realizing different roles in an online karaoke room is as follows:
The room owner initiates an instruction to create a karaoke room through the third-party cloud service. After the creation is successful, the room owner calls joinChannelByToken
method to join the karaoke room.
sharedEngineWithConfig
method to create and initialize an instance of AgoraRtcEngineKit
and set the instance's audio scenario to chorus (AgoraAudioScenarioChorus
).setClientRole
method to set the user role as the broadcaster (AgoraClientRoleBroadcaster
).The room owner automatically becomes a cohost. They can select a song and become the lead singer, and also invite other cohosts to join the chorus. The room owner can also accept the invitation of the lead singer and become a chorus.
The room owner can initiate an instruction through a third-party cloud service to turn a cohost into an audience member. At the same time, all users in the room receive notification of the change in role of the cohost and update the host seats in the room.
After the room owner leaves the karaoke room, the room object is automatically destroyed, and other members automatically leave the karaoke room.
The following figure shows the flow of events for the lead singer in a karaoke room:
joinChannelByToken
method to join the karaoke room. Before joining the karaoke room, call the sharedEngineWithConfig
method to create and initialize an instance of AgoraRtcEngineKit
, and set the instance's audio scenario to chorus (AgoraAudioScenarioChorus
).setClientRole
method to set the user role as broadcaster (AgoraClientRoleBroadcaster
). The user becomes a cohost and can interact with other cohosts in the room. At the same time, all users in the room receive notification of the role change from the cohost and an update to the host seats in the room.AgoraRtcMediaPlayerProtocol
class to play the song and sing along with the song. To switch between vocal or accompaniment mode, you can call the setAudioDualMonoMode
method. At the same time, the lead singer calls the joinChannelExByToken
method to implement the chorus.sendStreamMessage
method to synchronize the playback progress of the current song to all users in the room. Chorus and audience members can use the lyrics component to display the lyrics synchronously. They can also customize the lyrics interface.leaveChannel
method to leave the karaoke room.joinChannelByToken
method to join the karaoke room. Before joining the karaoke room, call the sharedEngineWithConfig
method to create and initialize an instance of AgoraRtcEngineKit
, and set the instance's audio scenario to chorus (AgoraAudioScenarioChorus
).setClientRole
method to set the user role as broadcaster (AgoraClientRoleBroadcaster
). The user becomes a cohost and can interact with other cohosts in the room. At the same time, all users in the room receive notification of the role change from the cohost and an update to the host seats in the room.AgoraRtcMediaPlayerProtocol
class to play the local songs and sings along with the lead singer. The member also calls the muteRemoteAudioStream
method to mute the lead singer's song.receiveStreamMessageFromUid
callback to synchronize with the current song. At the same time, chorus member can use the lyrics component to display lyrics synchronously with the song and customize the lyrics interface.leaveChannel
method to leave the karaoke room.joinChannelByToken
method to join the karaoke room.sharedEngineWithConfig
method to create and initialize an instance of AgoraRtcEngineKit
, and set the instance's audio scenario to chorus (AgoraAudioScenarioChorus
).setClientRole
method to set the user's role to audience member (AgoraClientRoleAudience
).After a cohost becomes the lead singer, the audience members synchronize the host seats in the room through a third-party cloud service.
The lead singer initiates an instruction to set the current song ID, and the audience members receive the lead singer's instruction and update the current song ID. While the lead singer sings, the audience members receive the lead singer's audio stream.
If an audience member wants to become a cohost, they need to call the setClientRole
method to set their user role to AgoraClientRoleBroadcaster
, and then they can publish the audio streams in the room.
The audience members initiate an instruction to obtain the current lyrics through a third-party cloud service and download the lyrics. At the same time, the progress of the lyrics is synchronized through the receiveStreamMessageFromUid
callback in real time.
The audience members can call leaveChannel
method to leave the channel.
Before proceeding, ensure that your development environment meets the following requirements:
The following table shows the links needed to download the SDK of the corresponding platform and integrate it into your project, in order to enable the Agora Content Center service.
Product | SDK downloads | Integration guide |
---|---|---|
Agora Voice SDK v4.0.0 Beta | Agora Voice SDK v4.0.0 Beta | Start a Voice Call |
Third-party cloud services | Third-party cloud service | SDK Installation Guide |
Agora Lyrics Component | Source code | / |
Refer to the following API sequence diagram to implement the Online Karaoke functions. You can also refer to the source code in the sample project on the github.
Creating and joining a karaoke room
Singing a song solo
Singing a song with a chorus
The following tables provide the core API references of Agora Voice SDK v4.0.0 Beta. Functions related to third-party cloud services need to be implemented on your own.
Before joining the karaoke room, call the following methods for initialization:
API | Function |
---|---|
sharedEngineWithConfig |
Before calling other APIs, you need to call this method to create and initialize AgoraRtcEngineKit and set audioScenario in AgoraRtcEngineConfig to AgoraAudioScenarioChorus(7) . |
The sample code is as follows:
let config = AgoraRtcEngineConfig();
config.appId = BuildConfig.AppId
config.audioScenario = .chorus
config.channelProfile = .liveBroadcasting
rtcEngine = AgoraRtcEngineKit.sharedEngine(with: config, delegate: self)
Call the following methods to join or leave the karaoke room:
API | Function |
---|---|
joinChannelByToken |
Joins the karaoke room. A user must join the karaoke room before publishing or receiving audio streams. |
updateChannelWithMediaOptions |
Updates the channel media options after joining the karaoke room. |
leaveChannel |
Leaves the karaoke room. If the room owner leaves the room, the room object is destroyed, and other room members leave the room automatically. |
joinChannelExByToken |
In the chorus scenario, the lead singer needs to call joinChannel to publish the audio stream of the media player and call joinChannelEx to publish the audio stream captured by the microphone. You must set different uid values in the two calls. |
updateChannelExWithMediaOptions |
In the chorus scenario, the media options are updated after the lead singer joins another channel. |
leaveChannelEx |
In the chorus scenario, the lead singer leaves the channel after stopping the chorus. |
In the solo scenario, the lead singer publishes the media player audio stream and the audio stream captured by the microphone. The sample code is as follows:
rtcMediaPlayer = rtcEngine.createMediaPlayer(with: self)
rtcMediaPlayer.open(url, 0);
let option = AgoraRtcChannelMediaOptions()
option.autoSubscribeAudio = AgoraRtcBoolOptional.of(true)
option.autoSubscribeVideo = AgoraRtcBoolOptional.of(true)
option.publishAudioTrack = .of(true)
In the chorus scenario, the lead singer calls joinChannelExByToken
to publish another audio stream. The sample code is as follows:
rtcMediaPlayer = rtcEngine.createMediaPlayer(with: self)
rtcMediaPlayer.open(url, 0);
let option = AgoraRtcChannelMediaOptions()
option.autoSubscribeAudio = AgoraRtcBoolOptional.of(true)
option.autoSubscribeVideo = AgoraRtcBoolOptional.of(true)
option.publishAudioTrack = .of(true)
option.publishMediaPlayerId = rtcMediaPlayer.getMediaPlayerId();
// Publish the media player audio stream
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)
Call the following methods to become a cohost or audience member:
API | Function |
---|---|
setClientRole |
Set the client role. After joining a karaoke room, you need to set the lead singer's user role to AgoraClientRoleBroadcaster and each audience member's user role to AgoraClientRoleAudience . After an audience member successfully becomes a cohost, this method needs to be called to switch the user role to AgoraClientRoleBroadcaster before the audio stream can be published in the room. |
The lead singer calls the following methods to set up the audio stream:
API | Function |
---|---|
setAudioProfile [2/2] |
Sets the audio parameters and application scenarios. |
muteLocalAudioStream |
The lead singer can mute or unmute the local microphone. |
adjustRecordingSignalVolume |
Adjusts the volume. |
The lead singer calls the following methods to use the media player:
API | Function |
---|---|
createMediaPlayerWithDelegate |
Creates a media player instance. |
delegate |
Sets and retrieves AgoraRtcEngineDelegate . The SDK uses AgoraRtcEngineDelegate to inform the app on engine runtime events. |
open |
Opens the media resource. |
play |
Plays the media file. |
pause |
Pauses the playback. |
resume |
Resumes playing the media file. |
stop |
Stops playing the media track. |
seekToPosition |
Seeks to a new playback position. |
setAudioDualMonoMode |
Sets the channel mode of the current audio file.AgoraAudioDualMonoL (1) : Accompaniment onlyAgoraAudioDualMonoR (2) : Original song onlyAgoraAudioDualMonoMix (3) : Both original song and accompaniment |
adjustPlaybackSignalVolume |
Adjusts the audio volume of the current song. |
getPosition |
Gets the playback progress (ms) of the current song. |
didChangedToPosition |
Reports the current playback progress (ms). |
API | Function |
---|---|
createDataStream [2/2] |
The lead singer creates a data stream and synchronizes song playback progress. |
sendStreamMessage |
The lead singer sends data streams to all users in the karaoke room. |
receiveStreamMessageFromUid |
All users in the karaoke room receive the data streams sent by the lead singer, and the lyrics are displayed synchronously through the lyrics component. |
The sample code is as follows:
let config = AgoraDataStreamConfig()
config.ordered = false
config.syncWithAudio = false
rtc.createDataStream(&dataStreamId, config: config)
if dataStreamId == -1 {
Logger.log(self, message: "error dataStreamId == -1", level: .error)
}
let jsonEncoder = JSONEncoder()
do {
let jsonData = try jsonEncoder.encode(msg)
let str = NSString(data: jsonData, encoding: String.Encoding.utf8.rawValue)
let code = rtcEngine.sendStreamMessage(streamId, data: jsonData)
if code != 0 {
Logger.log(self, message: "sendRtcStreamMessage error((code)", level: .error)
}
} catch {
Logger.log(self, message: error.localizedDescription, level: .error)
}
func rtcEngine(_: AgoraRtcEngineKit, receiveStreamMessageFromUid uid: UInt, streamId: Int, data: Data) {
do {
guard let content: NSDictionary = try JSONSerialization.jsonObject(with: data, options: .mutableContainers) as? NSDictionary,
let cmd: String = content["cmd"] as? String else { return }
var state: RtcMusicState?
switch cmd {
case "setLrcTime":
let duration = content["duration"] as? Int ?? 0
let position = content["time"] as? Int ?? -1
state = RtcMusicState(uid: uid, streamId: getOrderedDataStreamId(), position: position, duration: duration, state: .playing, type: .position)
}
} catch {
Logger.log(self, message: error.localizedDescription, level: .error)
}
}
Call the setAudioEffectPreset
method to set an SDK preset audio effect for the lead singer. This audio effect does not change the gender characteristics of the original voice. After setting an audio effect, all users in the karaoke room can hear the effect. For details, see Set the VoiceEffect.
Call the enableInEarMonitoring [2/2]
method to enable in-ear monitoring.
Call the enableAudioVolumeIndication
method to enable the singing scoring function, and use the reportAudioVolumeIndicationOfSpeakers
callback in conjunction with the Agora lyrics component to display the singing scoring interface.
Agora provides an open source example project of Online Karaoke on GitHub. You can download it to try it out.