Kakao i Connect Live::Kakao i Connect Live 2.0::API 레퍼런스::iOS::Room

페이지 이동경로

Room

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

Room 클래스 전체 목록
클래스 구분 항목 설명
Room Property status Room의 연결 상태를 반환
localParticipant 로컬 미디어를 송출하는 로컬 참여자 객체 정보
remoteParticipants 리모트 미디어를 송출하는 로컬 리모트 참여자 객체들의 Dictionary
Method connect() 특정 ID의 Room에 연결하고 스트림의 송수신을 위한 모든 절차 시작
disconnect() Room과의 연결 종료
publish() 나 자신의 미디어인 로컬 미디어(Local Media)를 Room에 게시(송출)
unpublish() 나 자신의 미디어인 로컬 미디어(Local Media)의 Room에 게시(송출) 중단
subscribe() Remote Participant가 게시(송출)한 비디오 구독
unsubscribe() Remote Participant가 게시(송출)한 비디오 구독을 해제
getVideoOccupants() 비디오를 구독 중인 참여자 ID 데이터를 가져옴
getAudioOccupants() 오디오를 구독 중인 참여자 ID 데이터를 가져옴
setMuted() 수신 중인 모든 오디오를 무음으로 설정
sendUserMessage() Room의 다른 참여자에게 메시지 전달
requestScreenShare() 화면 공유(Screen Share)를 요청
stopScreenShare() 화면 공유를 중단
getAudioLevels() 현재 발화 중인 참여자의 평균 오디오 레벨을 가져옴
getLocalStatsReport() 내가 생성한 로컬 미디어의 송출 스트림에 대한 WebRTC 통계 정보를 가져옴
getRemoteStatsReport() Remote Participant가 생성한 원격 미디어(Remote Media)의 수신 스트림에 대한 WebRTC 통계 정보를 가져옴

Property

status

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

status Property
프로퍼티 타입 설명
status Roomstatus Room 클래스의 상태 프로퍼티(읽기 전용)
initialized: Room이 초기화됨
connecting: Room에 연결 중
connected: Room에 연결 완료
disconnecting: Room에 연결 해제 중
disconnected: Room에 연결 해제 완료

localParticipant

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

localParticipant Property
프로퍼티 타입 설명
localParticipant LocalParticipant Room의 로컬 참여자 객체

remoteParticipants

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

remoteParticipants Property
프로퍼티 타입 설명
remoteParticipant [String: RemoteParticipant] Room의 Remote Participant 객체들의 Dictionary

Method

connect()

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

코드예제connect() Syntax

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

connect() Parameters
파라미터 타입 필수 여부 설명
roomId String 필수 Room의 고유 아이디
- 영문 대문자, 숫자, -만 허용
- 최대 길이: 32자

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)

publish() Parameters
파라미터 타입 필수 여부 설명
_localMedia LocalMedia 필수 Room에 게시할 로컬 미디어 클래스

Return

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

unpublish()

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

코드예제unpublish() Syntax

room.unpublish(localMedia)

publish() Parameters
파라미터 타입 필수 여부 설명
_localMedia LocalMedia 필수 Room에 송출을 중단할 로컬 미디어

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):
		// 구독 실패
	}
}

subscribe() Parameters
파라미터 타입 필수 여부 설명
videoId Int 필수 구독할 비디오 ID
completion Result 필수 구독 결과를 알려주는 Callback
success: 구독 시작
failure: 구독 실패

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):
		// 구독 해제 실패
	}
}

unsubscribe() Parameters
파라미터 타입 필수 여부 설명
videoId Int 필수 구독을 해제할 비디오 ID
completion Result 필수 구독 해제 결과를 알려주는 Callback
success: 구독 해제
failure: 구독 해제 실패

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)

usetMuted() Parameters
파라미터 타입 필수 여부 설명
_isMuted Boolean 필수 수신 중인 오디오의 무음 설정 여부
true: 수신 중인 오디오를 무음으로 설정
false(기본값): 수신 중인 오디오를 무음으로 설정하지 않음

sendUserMessage()

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

코드예제sendUserMessage() Syntax

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

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

sendUserMessage() Parameters
파라미터 타입 필수 여부 설명
participantIds [String] 필수 대상 참여자 ID 배열
- 빈 배열인 경우 전체 참여자
message String 필수 다른 참여자에게 전달할 메시지
completion Result 필수 메시지 전달 결과
success: 메시지 전송 성공
failure: 메시지 전송 실패

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:
		// 익스텐션 중단
	}
}

requestScreenShare() Parameters
파라미터 타입 필수 여부 설명
appGroup String 필수 Apple Developer에서 발급받은 앱 그룹 ID
extensionName String 필수 Extension의 번들 ID
completion ExtensionStatus 필수 익스텐션 상태에 대한 Callback
notAvailable: 익스텐션이 아직 시작되지 않음
broadcastReady: 익스텐션 구동 및 준비됨
broadcastStarted: 익스텐션 송출 중
broadcastClosed: 익스텐션 중단

stopScreenShare()

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

코드예제stopScreenShare() Syntax

room.stopScreenShare(isLeftRoom: false)

stopScreenShare() Parameters
파라미터 타입 필수 여부 설명
isLeftRoom Boolean 필수 참여자가 Room에서 퇴장하여 화면 공유가 중지되었는지 여부
true: 참여자가 Room에서 퇴장한 경우
false(기본값): 참여자가 Room에서 퇴장이 아닌 경우

getAudioLevels()

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

코드예제getAudioLevels() Syntax

room.getAudioLevels() { levels in

}

getAudioLevels() Parameters
파라미터 타입 필수 여부 설명
completion [String: Int] 필수 참여자의 평균 오디오 레벨 획득에 대한 Callback
Key: 참여자
Value: 오디오 레벨

getLocalStatsReport()

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

코드예제getLocalStatsReport() Syntax

room.getLocalStatsReport() { stats in

}

getLocalStatsReport() Parameters
파라미터 타입 필수 여부 설명
completion [String: Statistics] 필수 로컬 미디어의 송출 스트림에 대한 WebRTC 통계 정보 Callback
Key: 통계 ID
Value: Statistics Dictionary

getRemoteStatsReport()

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

코드예제getRemoteStatsReport() Syntax

room.getRemoteStatsReport() { stats in

}

getRemoteStatsReport() Parameters
파라미터 타입 필수 여부 설명
completion [String: Statistics] 필수 리모트 미디어의 송출 스트림에 대한 WebRTC 통계 정보 Callback
Key: 통계 ID
Value: Statistics Dictionary
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 documentation@kakaoenterprise.com 으로 제보해주세요.