Room

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

Property

Method

Room 클래스의 메서드는 다음과 같습니다.

connect()

roomId로 식별되는 특정 Room에 접속하고 스트림의 송신 및 수신을 위한 절차를 시작합니다.

코드예제connect() Syntax

try {
	await room.connect('{roomId}');
} catch (err) {
	console.log(err);
}

//or

room.connect('{roomId}').then(()=>{
	
}).catch((err)=>{
	console.log(err);
});

disconnect()

현재 접속 중인 Room과 연결을 끊습니다.

코드예제disconnect() Syntax

try {
	await room.disconnect();
} catch (err) {
	console.log(err);
}

//or

room.disconnect().then(()=>{
	
}).catch((err)=>{
	console.log(err);	
});

publish()

Local Participant(로컬 참여자)가 생성한 로컬 미디어(비디오/오디오)를 Room으로 송출하거나, 로컬 참여자의 화면을 다른 리모트 참여자들과 공유합니다.

코드예제publish() Syntax

try {
	await room.publish([{mediaType}]) 
} catch(err) {
	console.log(err);
}

//or

room.publish([{mediaType}]).then(()=>{
	
}).catch((err)=>{
	console.log(err);
});

unpublish()

Local Participant(로컬 참여자)가 Room에 공유 중인 로컬 미디어(비디오 / 오디오)의 송출 또는 화면 공유를 중단합니다.

코드예제unpublish() Syntax

try {
	await room.unpublish([{mediaType}]) 
} catch(err) {
	console.log(err);
}

//or

room.unpublish([{mediaType}]).then(()=>{
	
}).catch((err)=>{
	console.log(err);
});

subscribe()

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

코드예제subscribe() Syntax

const remoteVideos = await room.subscribe({subscribeType});

try {
	const remoteVideos = await room.subscribe([{vedioId}]);
} catch (err) {
	console.log(err);
}

//or

room.subscribe([{vedioId}]).then((remoteVideos)=>{
	
}).catch((err)=>{
	console.log(err);	
});

unsubscribe()

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

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

코드예제unsubscribe() Syntax

const remoteVideos = await room.unsubscribe({unsubscribeType}); 

try {
	const remoteVideos = await room.unsubscribe([{vedioId}]);
} catch (err) {
	console.log(err);
}

//or

room.unsubscribe([{vedioId}]).then((remoteVideos)=>{
	
}).catch((err)=>{
	console.log(err);	
});

getRemoteParticipant()

ParticipantId(참여자 아이디)를 인자로 사용하여, 특정 리모트 참여자의 RemoteParticipant 객체를 반환합니다.

코드예제getRemoteParticipant() Syntax

const remoteParticipant = room.getRemoteParticipant('{participantId}');

getAudioOccupants()

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

코드예제getAudioOccupants() Syntax

const audioOccupants = room.getAudioOccupants();

getRemoteVideo()

특정 리모트 비디오 ID의 RemoteVideo 객체를 반환합니다.

코드예제getRemoteVideo() Syntax

const remoteVideo = room.getRemoteVideo('{videoId}');

getRemoteAudio()

audioId(리모트 오디오 ID)를 인자로 사용하여 해당하는 RemoteAudio(리모트 오디오) 객체를 반환합니다. audioId는 getAudioId() 메서드를 통해 확인할 수 있습니다.

코드예제getRemoteAudio() Syntax

const remoteAudio = room.getRemoteAudio('{audioId}');

getRemoteAudioLevels()

현재 오디오를 생성하고 있는 리모트 참여자의 목록과 오디오 레벨을 반환합니다. 서비스에서는 주기적으로 이 값을 획득하여, 오디오 레벨을 표시하는 데 사용할 수 있습니다.

코드예제getRemoteAudioLevels() Syntax

const remoteAudioLevels = room.getRemoteAudioLevels();
// [{ level: 0, remoteParticipant: RemoteParticipant }]

switchSpeaker()

현재 출력 중인 스피커를 변경합니다.

코드예제switchSpeaker() Syntax

try {
	await room.switchSpeaker('{devieId}');
} catch(err) {
	console.log(err);
}

//or

room.switchSpeaker('{devieId}').then(()=>{
	
}).catch((err)=>{
	console.log(err);
});

주의
해당 기능은 특정 브라우저에서 동작하지 않을 수 있습니다. 동작 가능한 브라우저는 Can I use 사이트에서 확인하실 수 있습니다.

sendUserMessage()

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

코드예제sendUserMessage() Syntax

try {
	await room.sendUserMessage([], 'message');
} catch (err) {
	console.log(err);
}

//or

room.sendUserMessage([], 'message').then(()=>{
	
}).catch((err)=>{
	console.log(err);
});

getStats()

전송 중 또는 수신 중인 미디어에 대한 품질 지표를 확인할 수 있는 값을 반환합니다.

코드예제getStats() Syntax

await room.getStats();

Event

Web 버전의 카카오 i 커넥트 라이브 SDK에서 제공하는 Event는 다음과 같습니다.

connecting

Room에 접속하기까지 단계별 진행률을 전달합니다.

코드예제connecting Syntax

room.on('connecting', (param)=>{
	//param.progress
});

connected

참여자가 Room과의 연결이 완료되었을 때 발생하는 이벤트입니다. 참여자가 Room에 연결이 완료되면, 현재 Room에 참여 중인 모든 사용자 ID 목록을 반환합니다.

코드예제connected Syntax

room.on('connected', (param)=>{
	//param.remoteParticipants
});

disconnected

Room과 연결이 종료되면 호출됩니다.

코드예제disconnected Syntax

room.on('disconnected', ()=>{

});

participantEntered

새로운 Remote Participant(리모트 참여자)가 Room에 입장했을 때 호출됩니다.

코드예제participantEntered Syntax

room.on('participantEntered', (param)=>{
	//param.remoteParticipant
});

participantLeft

Remote Participant(리모트 참여자)가 Room에서 퇴장하여 Room과 연결이 끊겼을 때 호출됩니다.

코드예제participantLeft Syntax

room.on('participantLeft', (param)=>{
	//param.remoteParticipantId
});

localAudioPublished

Local Participant(로컬 참여자)가 자신의 오디오(음성)를 공유했을 때 호출됩니다.

코드예제localAudioPublished Syntax

room.on('localAudioPublished', (param)=>{
	//param.localAudio
});

localAudioUnpublished

Local Participant(로컬 참여자)가 Room에 공유 중인 오디오를 공유 해제했을 때 호출됩니다.

코드예제localAudioUnpublished Syntax

room.on('localAudioUnpublished', (param)=>{
	//param.localAudio
});

localVideoPublished

Local Participant(로컬 참여자)가 자신의 비디오를 공유했을 때 호출됩니다.

코드예제localVideoPublished Syntax

room.on('localVideoPublished', (param)=>{
	//param.localVideo
});

localVideoUnpublished

Local Participant(로컬 참여자)가 Room에 송출했던 비디오의 송출을 해제하면 호출됩니다.

코드예제localVideoUnpublished Syntax

room.on('localVideoUnpublished', (param)=>{
	//param.localVideo
});

remoteAudioPublished

Remote Participant(리모트 참여자)가 Room에 오디오를 송출했을 때 호출됩니다.

코드예제remoteAudioPublished Syntax

room.on('remoteAudioPublished', (param)=>{
	//param.remoteAudio
	//param.remoteParticipant
});

remoteAudioUnpublished

Remote Participant(리모트 참여자)가 Room에 송출 중인 오디오의 송출을 해제했을 때 호출됩니다.

코드예제remoteAudioUnpublished Syntax

room.on('remoteAudioUnpublished', (param)=>{
	//param.remoteAudio
	//param.remoteParticipant
});

remoteVideoPublished

Remote Participant(리모트 참여자)가 비디오를 공유했을 때 호출됩니다.

코드예제remoteVideoPublished Syntax

room.on('remoteVideoPublished', (param)=>{
	//param.remoteVideo
	//param.remoteParticipant
});

remoteVideoUnpublished

Remote Participant(리모트 참여자)가 비디오를 공유 해제하면 호출됩니다.

코드예제remoteVideoUnpublished Syntax

room.on('remoteVideoUnpublished', (param)=>{
	//param.remoteVideo
	//param.remoteParticipant
});

remoteAudioSubscribed

Room에 송출 중인 Remote Participant(리모트 참여자)의 오디오를 구독(오디오 리시버 점유)했을 때 호출되는 이벤트입니다. 오디오 구독 또는 해제는 별도 요청이 아닌 각 참여자의 발화에 따라 자동으로 처리됩니다.

코드예제remoteAudioSubscribed Syntax

room.on('remoteAudioSubscribed', (param)=>{
	//param.remoteParticipant
});

remoteAudioUnSubscribed

Remote Participant(리모트 참여자)의 오디오가 오디오 리시버의 점유를 해제하여 오디오 구독이 중단됐을 때 호출됩니다.

코드예제remoteAudioUnSubscribed Syntax

room.on('remoteAudioUnsubscribed', (param)=>{
	//param.remoteParticipant
});

remoteAudioStateChanged

Remote Participant(리모트 참여자)의 오디오 상태가 변경되면 호출됩니다.
SDK에서는 기본적으로 오디오 송출 시, Room에서 오디오 레벨이 가장 큰 4명의 오디오를 내보냅니다. 만약, 4명의 오디오 레벨과 상관 없이 로컬 참여자의 오디오를 항상 내보내도록 설정하려면 setAlwaysOn 프로퍼티를 true로 설정하여 always 상태를 설정하면 됩니다. 이렇게 오디오 상태가 always 상태였다가 변경되거나, 또는 그 반대일 때 remoteAudioStateChanged 이벤트가 호출됩니다.

코드예제remoteAudioStateChanged Syntax

room.on('remoteAudioStateChanged', (param)=>{
	//param.remoteParticipant
	//param.remoteAudio
});

remoteVideoStateChanged

Remote Participant(리모트 참여자)의 비디오 상태가 변경되면 호출됩니다. 예를 들어 리모트 참여자의 비디오 상태가 활성(active) 상태였다가 비활성 상태로 변경되었을 때 호출됩니다.

코드예제remoteVideoStateChanged Syntax

room.on('remoteVideoStateChanged', (param)=>{
	//param.remoteParticipant
	//param.remoteVideo
});

userMessage

Remote Participant(리모트 참여자)가 메시지를 전송하면 호출됩니다.

코드예제userMessage Syntax

room.on('userMessage', (param)=>{
	//param.sender
	//param.message
});

error

Room에서 에러가 발생했을 때 호출됩니다.

코드예제error Syntax

room.on('error', (err)=>{
	//err.code      -> 에러 코드
	//err.message   -> 에러 메시지
	//err.origin    -> 원본 에러 객체
});

recordFailed

publish() 메서드 호출 시 isRecording를 true로 설정했을 때, 녹화가 시작됩니다. 만약 이때 녹화가 실패하면 recordFailed 이벤트가 호출됩니다.

코드예제recordFailed Syntax

room.on('recordFailed', (param)=>{
	//param.reason
});