Room

Room 클래스는 카카오 i 커넥트 라이브 SDK의 주요 클래스 중 하나입니다. 카카오 i 커넥트 라이브에서 Room은 서비스에 따라 회의실, 채팅방 등 스트리밍 서비스를 사용하는 공간을 의미합니다. Room 클래스는 Property, Method, RoomDelegate로 구성됩니다.

Property

status

Room의 연결 상태를 반환합니다.

localParticipant

로컬 미디어를 송출하는 로컬 참여자 객체 정보입니다.

remoteParticipants

리모트 미디어를 송출하는 리모트 참여자 객체들의 Dictionary입니다. 키(Key)는 참여자 ID이고, 값(Value)은 참여자 객체입니다.

Method

connect()

roomId로 식별되는 특정 Room에 접속하고 스트림의 송신 및 수신을 위한 절차를 시작합니다. Room에서 발생하는 모든 이벤트는 RoomDelegate Callback으로 전달됩니다.

코드예제connect() Syntax

room.connect(roomId: "{roomId}")

disconnect()

현재 접속 중인 Room과 연결을 끊습니다. Room에서 발생하는 모든 이벤트는 Room.Delegate Callback으로 전달됩니다.

코드예제disconnect() Syntax

room.disconnect()

publish()

Local Participant(로컬 참여자)가 생성한 로컬 미디어(비디오/오디오)를 Room으로 송출합니다. 송출에 성공하면 RoomDelegate의 onLocalMediaPublished Callback이 호출되고, 송출에 실패하면 RoomDelegate의 onError Callback이 호출됩니다.

코드예제publish() Syntax

room.publish(localMedia)

Return

송출을 위한 설정에 문제가 있을 경우 Error가 전달됩니다.

unpublish()

Local Participant(로컬 참여자)가 Room에 송출 중인 로컬 미디어(비디오/오디오)의 송출을 중단합니다.

코드예제unpublish() Syntax

room.unpublish(localMedia)

subscribe()

Room의 Remote Participant(리모트 참여자)가 공유한 비디오를 수신(구독)합니다. 오디오의 경우 발화자에 따라 자동으로 구독, 해제가 이루어지므로 추가적인 처리 없이 상대방의 소리를 수신하게 됩니다. 반면 비디오의 경우에는 자동으로 구독이 이루어지지 않으므로, 서비스별 화면 구성에 맞게 비디오 구독 여부를 결정해야 합니다.
구독을 통해 상대방의 비디오를 수신하기 위해서는 Room의 remoteParticipants 프로퍼티에서 해당 참여자의 비디오 스트림 ID를 얻어 직접 구독 처리를 진행해야 합니다. 최대 구독 가능 개수는 Config의 videoReceiverMaximumCount로 결정되고, 비디오 구독 수가 늘어날수록 많은 데이터와 자원을 사용합니다. 따라서 필요한 비디오만을 구독하고 불필요한 비디오는 구독을 해제해야 합니다.

코드예제subscribe() Syntax

// participantId : 참여자 id
// videoId : 비디오 id

guard let participant = room.remoteParticipants[participantId] else { return }
guard let video = participant.videos[videoId] else { return }

if video.isSubscribed {
	return
}

room.subscribe(videoId: video.id) { result in
	switch result {
	case .success():
		// 구독 시작

	case .failure(let error):
		// 구독 실패
	}
}

unsubscribe()

Remote Participant(리모트 참여자)가 송출한 비디오의 구독을 중단합니다. 비디오 수신 중단은 비디오 아이디별(videoId)로 선택적으로 리모트 비디오를 수신하지 않도록 설정할 수 있습니다.

• 오디오는 별도의 수신(구독)을 설정하지 않아도 SDK 자체적으로 수신을 진행합니다.

코드예제unsubscribe() Syntax

// participantId : 참여자 id
// videoId : 비디오 id

guard let participant = room.remoteParticipants[participantId] else { return }
guard let video = participant.videos[videoId] else { return }

if !video.isSubscribed {
	return
}

room.unsubscribe(videoId: video.id) { result in
	switch result {
	case .success():
		// 구독 해제

	case .failure(let error):
		// 구독 해제 실패
	}
}

getVideoOccupants()

비디오를 구독 중인 참여자 ID 데이터를 가져옵니다.

코드예제getVideoOccupants() Syntax

let ids = room.getVideoOccupants()

Return

성공 시 비디오를 구독 중인 참여자 ID 데이터를 배열 형태([String])로 가져옵니다. 실패 시 Error를 반환합니다.

getAudioOccupants()

오디오를 구독 중인 리모트 참여자의 목록을 반환합니다. SDK에는 4개의 오디오 리시버가 존재하며, 최대 참여자 4명의 오디오를 재생하는 역할을 합니다.
참고로 현재 말을 하고 있지 않은 참여자(A)도 오디오 리시버를 점유할 수 있습니다. 기본적으로 참여자(A)가 현재 말을 하고 있어 오디오 리시버를 차지했다가, 다른 참여자(B)가 말할 경우 오디오 리시버는 다른 참여자(B)로 변경됩니다. 하지만 참여자(A)가 말을 하다가 중단한 상황에서 다른 참여자(B)가 아무 말도 하지 않으면 여전히 참여자(A)가 오디오 리시버를 점유하게 됩니다.

안내
오디오의 구독은 발화에 따라 매우 빠르게 변경됩니다. 오디오를 구독 중인 참여자 정보는 요청 시점의 정보를 기준으로 하며, 시간 차에 의해 실제 정보와 차이가 발생할 수 있습니다.

코드예제getAudioOccupants() Syntax

let ids = room.getAudioOccupants()

Return

성공 시 오디오를 구독 중인 참여자 ID 데이터를 배열 형태([String])로 가져옵니다. 실패 시 Error를 반환합니다.

setMuted()

Room에서 수신하고 있는 모든 오디오를 무음(Mute)으로 설정합니다.

코드예제setMuted() Syntax

room.setMuted(true)

sendUserMessage()

Room에 있는 특정 리모트 참여자 또는 전체 리모트 참여자에게 메시지를 전송합니다.

코드예제sendUserMessage() Syntax

room.sendUserMessage(participantIds: [], message: "message") { result in
	switch result {
	case .success():
		// 성공

	case .failure(let error):
		// 실패
}

requestScreenShare()

화면 공유(Screen Share)를 요청합니다. 각 앱에서 화면 공유를 위해 broadcastExtension을 구성해야 합니다. 화면 공유를 요청하면 Broadcast Picker가 Extension을 가져오는데, 여기에 표시되는 이름은 Broadcast Extension의 Display Name입니다. 자세한 설명은 부가 기능 문서의 화면 공유 구현을 참고하시기 바랍니다.

코드예제requestScreenShare() Syntax

room.requestScreenShare(appGroup: "appGroup", extensionName: "extension-bundleId") { status in
	switch status {
	case .notAvailable:
		// 익스텐션이 아직 시작되지 않음

	case .broadcastReady:
		// 익스텐션 구동 및 준비됨

	case .broadcastStarted:
		// 익스텐션 송출 중

	case .broadcastClosed:
		// 익스텐션 중단
	}
}

stopScreenShare()

화면 공유를 중단합니다. 화면 공유는 별도 프로세스로 동작하는 Broadcast Extension을 사용합니다.
Extension은 중지 요청 후, 각 세션 및 Extension 정리는 약 5초 정도의 시간이 필요합니다. Extension에서 중지 얼럿이 표시되어야 종료가 완료된 것이므로, 다음 화면 공유는 최소 5초 이상 시간이 지난 후 시도해야 합니다.

코드예제stopScreenShare() Syntax

room.stopScreenShare(isLeftRoom: false)

getAudioLevels()

Room에서 현재 발화 중인 참여자의 평균 오디오 레벨을 가져옵니다. Local Participant(로컬 참여자)의 오디오 레벨은 LocalMedia 클래스에서 얻을 수 있습니다.

코드예제getAudioLevels() Syntax

room.getAudioLevels() { levels in

}

getLocalStatsReport()

Local Participant(로컬 참여자)가 생성한 로컬 미디어의 송출 스트림에 대한 WebRTC 통계 정보를 가져옵니다. Callback을 통해 전달된 Statistics의 id, type, timeStamp, values 값은 WebRTC 정보를 그대로 전달합니다. 통계 데이터는 처리 시간이 필요하기 때문에, 짧은 시간 간격으로 호출하면 정상적으로 작동하지 않을 수 있습니다. 따라서 이 메서드는 필요한 경우에만 제한적으로 사용하시기 바랍니다.

코드예제getLocalStatsReport() Syntax

room.getLocalStatsReport() { stats in

}

getRemoteStatsReport()

Remote Participant(리모트 참여자)가 생성한 원격 미디어(Remote Media)의 수신 스트림에 대한 WebRTC 통계 정보를 가져옵니다. 통계 정보는 Callback을 통해 전달됩니다.

코드예제getRemoteStatsReport() Syntax

room.getRemoteStatsReport() { stats in

}