API operations for chit-chat room scenarios on iOS-Apsara Video SDK(Apsara Video SDK)-阿里云帮助中心

This topic describes the API operations for chit-chat room scenarios on iOS.

API overview

Class or protocol	API operation	Description
ARTCVoiceRoomEngine Chit-chat room engine	init	Initializes an engine instance.
	addObserver	Adds an observer to listen for a room event callback.
	removeObserver	Removes the observer that listens for a room event callback.
	roomService	Specifies or queries an instance that conforms to ARTCRoomServiceInterface.
	roomInfo	Queries the information about the chit-chat room.
	isAnchor	Queries whether a user is the owner of the chit-chat room.
	isJoinRoom	Queries whether a user joins the chit-chat room.
	joinRoom	Joins the chit-chat room.
	leaveRoom	Leaves the chit-chat room.
	dismissRoom	Terminates the chit-chat room. Only the streamer can terminate the chit-chat room.
	micSeatInfo	Queries the information about a streamer seat.
	isJoinMic	Queries whether co-streaming is started.
	joinMic	Directly starts co-streaming.
	leaveMic	Stops co-streaming.
	requestMic	Applies for co-streaming.
	switchMicrophone	Turns on or off your microphone.
	switchAudioOutput	Switches the audio output between your microphone and earpiece.
	switchEarBack	Enables or disables in-ear monitoring.
	getIsEarBack	Queries whether in-ear monitoring is enabled.
	setRecordingVolume	Specifies the audio recording volume. Default value: 50. Valid values: [0,100].
	getRecordingVolume	Queries the audio recording volume. Default value: 50. Valid values: [0,100].
	startPlayAudioEffect	Starts the playback of a sound effect.
	stopPlayAudioEffect	Stops the playback of a sound effect.
	setAudioEffectVolume	Specifies the volume of a sound effect.
	startPlayBackgroundMusic	Starts the playback of the background music.
	stopPlayBackgroundMusic	Stops the playback of the background music.
	setBackgroundMusicVolume	Specifies the volume of the background music.
	bgMusicStatus	Queries the playback status of the background music.
	setVoiceChangerMode	Specifies the voice changer effect.
	getVoiceChangerMode	Queries the current voice changer effect.
	sendTextMessage	Sends a live comment.
	sendCommand	Sends a signaling message.
	sendTextMessage	Sends a live comment.
	sendCommand	Sends a signaling message.
ARTCVoiceRoomEngineDelegate Chit-chat room engine delegate	onJoinedRoom	Indicates that a user joins the chit-chat room.
	onLeavedRoom	Indicates that a user leaves the chit-chat room.
	onKickoutRoom	Indicates that you are removed from the chit-chat room.
	onDismissedRoom	Indicates that the chit-chat room is terminated.
	onOnlineCountChanged	Indicates that the number of users in the chit-chat room changes.
	onJoinedMic	Indicates that a user starts co-streaming.
	onLeavedMic	Indicates that a user stops co-streaming.
	onMicUserStreamChanged	Indicates that the audio stream of the co-streamer experiences a change in stream ingest status. The stream ingest may either start or stop.
	onMicUserMicrophoneChanged	Indicates whether the microphone of the co-streamer is turned on or off.
	onMicUserSpeakStateChanged	Indicates whether the co-streamer is speaking.
	onNetworkStateChanged	Indicates that the network status changes.
	onBackgroundMusicStatusChanged	Indicates that the playback status of your background music changes. The playback may start, stop, or fail.
	onAudioEffectPlayCompleted	Indicates that the playback of your sound effect stops.
	onReceivedTextMessage	Indicates that a live comment is sent to you.
	onError	Indicates that an error occurred.

Details of ARTCVoiceRoomEngine

init

Description: initializes an engine instance.

Sample code:

public init(_ roomInfo: ARTCVoiceRoomInfo)

Parameters

Parameter	Type	Description
roomInfo	ARTCVoiceRoomInfo	The information about the chit-chat room.

addObserver

Description: adds an observer to listen for a room event callback.

Sample code:

public func addObserver(delegate: ARTCVoiceRoomEngineDelegate)

Parameters

Parameter	Type	Description
delegate	ARTCVoiceRoomEngineDelegate	The observer to be added.

removeObserver

Description: removes the observer that listens for a room event callback.

Sample code:

public func removeObserver(delegate: ARTCVoiceRoomEngineDelegate)

Parameters

Parameter	Type	Description
delegate	ARTCVoiceRoomEngineDelegate	The observer to be removed.

roomService

Description: specifies or queries an instance that conforms to ARTCRoomServiceInterface.

Sample code:

public var roomService: ARTCRoomServiceInterface? = nil

Parameters

None.

roomInfo

Description: queries the information about the chit-chat room.

Sample code:

public let roomInfo: ARTCVoiceRoomInfo

Parameters

None.

isAnchor

Description: queries whether a user is the owner of the chit-chat room.

Sample code:

public var isAnchor: Bool

Parameters

None.

isJoinRoom

Description: queries whether a user joins the chit-chat room.

Sample code:

public private(set) var isJoinRoom: Bool = false

Parameters

None.

joinRoom

Description: joins the chit-chat room.

Sample code:

public func joinRoom(completed: ARTCRoomCompleted?)

Parameters

Parameter	Type	Description
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

leaveRoom

Description: leaves the chit-chat room.

Sample code:

public func leaveRoom(_ completed: (()->Void)? = nil)

Parameters

Parameter	Type	Description
completed	()->Void	The callback that is triggered when the operation is complete.

dismissRoom

Description: terminates the chit-chat room. Only the streamer can terminate the chit-chat room.

Sample code:

public func dismissRoom(completed: ARTCRoomCompleted?)

Parameters

Parameter	Type	Description
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

micSeatInfo

Description: queries the information about a streamer seat.

Sample code:

public var micSeatInfo: AUIVoiceRoomMicSeatInfo?

Parameters

None.

isJoinMic

Description: queries whether co-streaming is started.

Sample code:

public var isJoinMic: Bool

Parameters

None.

joinMic

Description: directly starts co-streaming.

Sample code:

public func joinMic(seatIndex: Int32, completed: ARTCRoomCompleted?)

Parameters

Parameter	Type	Description
seatIndex	Int32	The streamer seat.
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

leaveMic

Description: stops co-streaming.

Sample code:

public func leaveMic(completed: ARTCRoomCompleted?)

Parameters

Parameter	Type	Description
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

requestMic

Description: applies for co-streaming.

Sample code:

public func requestMic(completed: ARTCRoomCompleted?)

Parameters

Parameter	Type	Description
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

switchMicrophone

Description: turns on or off your microphone.

Sample code:

public func switchMicrophone(off: Bool, completed: ARTCRoomCompleted? = nil)

Parameters

Parameter	Type	Description
off	Bool	Specifies whether to turn off your microphone.
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

switchAudioOutput

Description: switches the audio output between your microphone and earpiece.

Sample code:

public func switchAudioOutput(type: ARTCRoomAudioOutputType, completed:  ARTCRoomCompleted? = nil)

Parameters

Parameter	Type	Description
type	ARTCRoomAudioOutputType	The type of the audio output device, which can be the microphone or earpiece.
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

switchEarBack

Description: enables or disables in-ear monitoring.

Sample code:

public func switchEarBack(on: Bool, completed: ARTCRoomCompleted? = nil)

Parameters

Parameter	Type	Description
on	ARTCRoomAudioOutputType	Specifies whether to enable in-ear monitoring.
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

getIsEarBack

Description: queries whether in-ear monitoring is enabled.

Sample code:

public func getIsEarBack() -> Bool

Parameters

None.

setRecordingVolume

Description: specifies the audio recording volume. Default value: 50. Valid values: [0,100].

Sample code:

public func setRecordingVolume(volume: Int32, completed: ARTCRoomCompleted? = nil)

Parameters

Parameter	Type	Description
volume	Int32	The audio recording volume. Default value: 50. Valid values: [0,100].
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

getRecordingVolume

Description: queries the audio recording volume.

Sample code:

public func getRecordingVolume() -> Int32

Parameters

None.

startPlayAudioEffect

Description: starts the playback of a sound effect.

Sample code:

public func startPlayAudioEffect(effectId: Int32, localPath: String, volume: Int32, onlyLocalPlay: Bool, completed:  ARTCRoomCompleted? = nil)

Parameters

Parameter	Type	Description
effectId	Int32	The sound effect ID.
localPath	String	The local path of the sound effect file.
volume	Int32	The volume of the sound effect. Default value: 50. Valid values: [0,100].
onlyLocalPlay	Bool	Specifies whether to play the sound effect only on the local side without stream ingest.
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

stopPlayAudioEffect

Description: stops the playback of a sound effect.

Sample code:

public func stopPlayAudioEffect(effectId: Int32, completed: ARTCRoomCompleted? = nil)

Parameters

Parameter	Type	Description
effectId	Int32	The sound effect ID.
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

setAudioEffectVolume

Description: specifies the volume of a sound effect.

Sample code:

public func setAudioEffectVolume(effectId: Int32, volume: Int32, completed: ARTCRoomCompleted? = nil)

Parameters

Parameter	Type	Description
effectId	Int32	The sound effect ID.
volume	Int32	The volume of the sound effect. Default value: 50. Valid values: [0,100].
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

startPlayBackgroundMusic

Description: starts the playback of the background music.

Sample code:

public func startPlayBackgroundMusic(musicId: Int32, localPath: String, volume: Int32, onlyLocalPlay: Bool, completed:  ARTCRoomCompleted? = nil)

Parameters

Parameter	Type	Description
musicId	Int32	The background music ID.
localPath	String	The local path of the background music file.
volume	Int32	The volume of the background music. Default value: 50. Valid values: [0,100].
onlyLocalPlay	Bool	Specifies whether to play the background music only on the local side without stream ingest.
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

stopPlayBackgroundMusic

Description: stops the playback of the background music.

Sample code:

public func stopPlayBackgroundMusic(completed:  ARTCRoomCompleted? = nil)

Parameters

Parameter	Type	Description
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

setBackgroundMusicVolume

Description: specifies the volume of the background music.

Sample code:

public func setBackgroundMusicVolume(volume: Int32, completed: ARTCRoomCompleted? = nil)

Parameters

Parameter	Type	Description
volume	Int32	The volume of the background music. Default value: 50. Valid values: [0,100].
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

bgMusicStatus

Description: queries the playback status of the background music.

Sample code:

public lazy var bgMusicStatus: ARTCVoiceRoomAudioPlayingStatus

Parameters

None.

setVoiceChangerMode

Description: specifies the voice changer effect.

Sample code:

public func setVoiceChangerMode(mode: ARTCRoomVoiceChangerMode, completed: ARTCRoomCompleted? = nil)

Parameters

Parameter	Type	Description
mode	ARTCRoomVoiceChangerMode	The voice changer effect.
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

getVoiceChangerMode

Description: queries the current voice changer effect.

Sample code:

public func getVoiceChangerMode() -> ARTCRoomVoiceChangerMode

Parameters

None.

setVoiceReverbMode

Description: specifies the reverberation mode.

Sample code:

public func setVoiceReverbMode(mode: ARTCRoomVoiceReverbMode, completed: ARTCRoomCompleted? = nil)

Parameters

Parameter	Type	Description
mode	ARTCRoomVoiceReverbMode	The reverberation mode.
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

getVoiceChangerMode

Description: queries the reverberation mode.

Sample code:

public func getVoiceReverbMode() -> ARTCRoomVoiceReverbMode

Parameters

None.

sendTextMessage

Description: sends a live comment.

Sample code:

public func sendTextMessage(text: String, completed: ARTCRoomCompleted? = nil)

Parameters

Parameter	Type	Description
text	String	The content of the live comment.
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

sendCommand

Description: sends a signaling message. If you leave the userId parameter empty, the signaling message is broadcasted to all users in the chit-chat room.

Sample code:

public func sendCommand(type: ARTCRoomMessageType, data:[AnyHashable: Any]? = nil , userId: String? = nil, completed: ARTCRoomCompleted? = nil)

Parameters

Parameter	Type	Description
type	ARTCRoomMessageType	The type of the signaling message.
data	[AnyHashable: Any]	The custom content.
userId	String	The ID of the user to whom the signaling message is to be sent. If you leave this parameter empty, the signaling message is broadcasted to all users in the chit-chat room.
completed	ARTCRoomCompleted	The callback that is triggered when the operation is complete.

Details of ARTCVoiceRoomEngineDelegate

onJoinedRoom

Description: indicates that a user joins the chit-chat room.

Sample code:

@objc optional func onJoinedRoom(user: ARTCRoomUser)

Parameters

Parameter	Type	Description
user	ARTCRoomUser	The user who joins the chit-chat room.

onLeavedRoom

Description: indicates that a user leaves the chit-chat room.

Sample code:

@objc optional func onLeavedRoom(user: ARTCRoomUser)

Parameters

Parameter	Type	Description
user	ARTCRoomUser	The user who leaves the chit-chat room.

onKickoutRoom

Description: indicates that you are removed from the chit-chat room.

Sample code:

@objc optional func onKickoutRoom()

Parameters

None.

onDismissedRoom

Description: indicates that the chit-chat room is terminated.

Sample code:

@objc optional func onDismissedRoom()

Parameters

None.

onOnlineCountChanged

Description: indicates that the number of users in the chit-chat room changes.

Sample code:

@objc optional func onOnlineCountChanged(count: Int)

Parameters

Parameter	Type	Description
count	Int	The number of users.

onJoinedMic

Description: indicates that a user starts co-streaming.

Sample code:

@objc optional func onJoinedMic(seatIndex: Int32, user: ARTCRoomUser)

Parameters

Parameter	Type	Description
seatIndex	Int32	The streamer seat.
user	ARTCRoomUser	The co-streamer.

onLeavedMic

Description: indicates that a user stops co-streaming.

Sample code:

@objc optional func onLeavedMic(seatIndex: Int32, user: ARTCRoomUser)

Parameters

Parameter	Type	Description
seatIndex	Int32	The streamer seat.
user	ARTCRoomUser	The co-streamer.

onMicUserStreamChanged

Description: indicates that the audio stream of the co-streamer experiences a change in stream ingest status. The stream ingest may either start or stop.

Sample code:

@objc optional func onMicUserStreamChanged(seatIndex: Int32, user: ARTCRoomUser, publishing: Bool)

Parameters

Parameter	Type	Description
seatIndex	Int32	The streamer seat.
user	ARTCRoomUser	The co-streamer.
publishing	Bool	Indicates whether stream ingest is in progress.

onMicUserMicrophoneChanged

Description: indicates whether the microphone of the co-streamer is turned on or off.

Sample code:

@objc optional func onMicUserMicrophoneChanged(seatIndex: Int32, user: ARTCRoomUser, off: Bool)

Parameters

Parameter	Type	Description
seatIndex	Int32	The streamer seat.
user	ARTCRoomUser	The co-streamer.
off	Bool	Indicates whether the microphone is turned off.

onMicUserSpeakStateChanged

Description: indicates whether the co-streamer is speaking.

Sample code:

@objc optional func onMicUserSpeakStateChanged(seatIndex: Int32, isSpeaking: Bool)

Parameters

Parameter	Type	Description
seatIndex	Int32	The streamer seat.
isSpeaking	Bool	Indicates whether the co-streamer is speaking.

onNetworkStateChanged

Description: indicates that the network status changes.

Sample code:

@objc optional func onNetworkStateChanged(user: ARTCRoomUser, state: String)

Parameters

Parameter	Type	Description
user	ARTCRoomUser	The user whose network status changes.
state	String	The network status.

onBackgroundMusicStatusChanged

Description: indicates that the playback status of your background music changes. The playback may start, stop, or fail.

Sample code:

@objc optional func onBackgroundMusicStatusChanged(status: ARTCVoiceRoomAudioPlayingStatus)

Parameters

Parameter	Type	Description
status	ARTCVoiceRoomAudioPlayingStatus	The playback status of the background music.

onAudioEffectPlayCompleted

Description: indicates that the playback of your sound effect stops.

Sample code:

@objc optional func onAudioEffectPlayCompleted(effectId: Int32)

Parameters

Parameter	Type	Description
effectId	Int32	The sound effect ID.

onReceivedTextMessage

Description: indicates that a live comment is sent to you.

Sample code:

@objc optional func onReceivedTextMessage(user: ARTCRoomUser, text: String)

Parameters

Parameter	Type	Description
user	ARTCRoomUser	The user who sends the live comment.
text	String	The information about the live comment.

onError

Description: indicates that an error occurred.

Sample code:

@objc optional func onError(_ error: NSError)

Parameters

Parameter	Type	Description
error	NSError	The error information.