[WebRTC] WebRTC 화상채팅 실습 (SpringBoot + React)

 

 

 

🎆 Preview

---

 

 

 

 

📖 개요

---

반갑습니다.

WebRTC 이론에 이어서 화상 채팅 실습을 해보려고 합니다.

 

[WebRTC] WebRTC 찢어버리기 - 이론 정리

해당 글을 읽고 오신다면 실습 코드를 더 쉽게 이해할 수 있습니다.

 

GitHub - BenchPress200/webrtc-tutorial: A WebRTC tutorial for learning peer-to-peer audio/video communication with custom signal

실습 코드는 로컬환경에서 실행할 수 있습니다.

README와 소스 코드 주석을 상세하게 작성했으나, 본 글에서 더 디테일한 설명을 전달합니다.

 

Signaling을 포함하여 모든 서버와의 통신은 WebSocket으로 진행합니다.

간단하게 이름 입력만으로 가입하며, 해당 정보는 백엔드 측 메모리에 저장됩니다. 통화 요청을 통해서 가입한 유저 간 화상채팅이 가능합니다.

 

이번 포스팅의 구성은 다음과 같습니다.

• 실행환경 및 애플리케이션 구조
• 실습 코드 따라가기
• 마치며

 

 

 

⚙️ 실행환경 및 애플리케이션 구조

---

실습 코드의 실행 흐름을 이해하기 위해 WebRTC의 P2P 연결 원리를 되짚어보고 프론트엔드 코드와 백엔드 코드의 구조, 주요 API의 동작을 살펴보겠습니다.

 

 

기술 스택

• 프론트엔드: TypeScript, React, Styled-component, Zustand, WebSocket, WebRTC
• 백엔드: Java, SpringBoot, WebSocket

 

 

화상 채팅을 위한 P2P 연결과정

두 명의 유저가 있고, 화상채팅을 위한 P2P 연결수립 과정을 다시 한 번 살펴봅시다.

Signaling 과정은 WebSocket으로 진행한다고 가정하겠습니다.

1. 뚱이와 스폰지밥이 Signaling Server 와 WebSocket 연결
2. 뚱이가 Signaling Server 로 offer 전송 (caller의 SDP)
   • offer 전송과 동시에, 본인의 ICE Candidate 수집 및 전송
   • STUN/TURN 서버를 사용해서 ICE Candidate 수집
3. 스폰지밥이 Signaling Server 로부터 뚱이의 offer (caller의 SDP) 수신 및 설정
   • 뚱이의 SDP 가 설정되면, 뚱이가 보내고 있는 ICE Candidate 추가 및 테스트 진행
4. 스폰지밥이 Signaling Server 로 받은 offer에 대한 answer 전송 (callee의 SDP)
   • answer 전송과 동시에, 본인의 ICE Candidate 수집 및 전송
   • STUN/TURN 서버를 사용해서 ICE Candidate 수집
5. 뚱이가 Signaling Server 로부터 스폰지밥의 answer(callee의 SDP) 수신 및 설정
   • 스폰지밥의 SDP 가 설정되면, 스폰지밥이 보내고 있는 ICE Candidate 추가 및 테스트 진행
6. offer와 answer, ICE Candidate 교환이 완료되고 정상 연결 테스트를 마쳤다면 화상채팅 준비 완료
7. 화상채팅 시작

 

 

WebSocket 메시지 구조

{
	"type" : 메시지의 타입,
	"sender" : 보낸 유저 닉네임,
	"receiver" : 받을 유저 닉네임,
	"data" : any
}

위 JSON은 원활히 메시지를 주고 받기위해 임의로 정의한 메시지 구조입니다.

각 필드에 대한 설명은 다음과 같습니다.

• type: 어떤 메시지인지 타입을 명시합니다.
  • join: 회원가입
  • activeUsers: 활성유저 닉네임 리스트 조회
  • call: 통화 요청
  • acceptCall: 걸려온 통화 수락
  • cancelCall: 걸려온 통화 거절
  • hangUp: 통화종료
  • offer: offer 메시지 전송
  • answer: answer 메시지 전송
  • candidate: ICE Candidate 메시지 전송
• sender: 보내는 유저의 닉네임을 명시합니다.
• receiver: 받는 유저의 닉네임을 명시합니다.
• data: 각 메시지 타입에 따라서 필요한 데이터를 할당합니다.

 

 

프론트엔드 실행흐름

페이지에 해당하는 컴포넌트가 세 개 있고, WebSocket 연결은 Zustand를 통해 전역으로 관리하고 있습니다.

회원가입부터 통화 연결까지 순서대로 살펴보겠습니다.

1. Join 페이지
   • 원하는 이름을 입력하여 간단하게 가입을 진행할 수 있습니다.
   • 중복 검사에 통과하여 가입에 성공하면 Home 페이지로 이동합니다.
2. Home 페이지
   • 가입 유저 목록을 실시간으로 받아오며, 통화중 상태가 아닌 유저에게 통화요청을 할 수 있습니다.
   • 또한, 다른 유저에게 통화 요청이 오면 수락 혹은 거절할 수 있습니다.
   • 통화를 수락한다면 Call 페이지로 이동합니다.
3. Call 페이지
   통화 요청을 한 유저는 caller, 통화 요청을 수락한 유저는 callee로서 구분됩니다.
   Signaling을 수행하기 위해 다음과 같은 절차를 따릅니다.
   1. 미디어 스트림 설정 - caller callee
   2. offer 생성 및 전송 - caller
      • offer 생성되면, ICE Candidate 수집 및 전송
   3. offer 수신 및 설정 - callee
      • offer 설정되면, 받은 ICE Candidate 추가 시작
   4. answer 생성 및 전송 - callee
      • answer 생성되면, ICE Candidate 수집 및 전송
   5. answer 수신 및 설정 - caller
      • answer 설정되면, 받은 ICE Candidate 추가 시작
   6. 교환하고 각 피어 정보에 추가했었던 ICE Candidate 중에서 유효하고 가장 원활한 후보를 찾았다면 연결 상태가 connected, 혹은 completed로 업데이트 - caller callee
   7. 화상 통화 시작

 

 

백엔드 실행흐름

백엔드에서는 WebSocket 연결을 처리하기 위한 설정과 핸들러가 존재합니다.

메시지를 서버로 전송했을 때 파싱하여 타입을 확인한 후 해당하는 서비스 로직을 수행합니다.

 

메시지 타입에 따른 로직 처리는 레이어드 아키텍처를 따르고 있습니다.

각 계층의 역할은 다음과 같습니다.

• presentation
  • WebSocket 연결, 해제, 메시지 타입에 따른 서비스 클래스의 메서드를 호출합니다.
• application
  • WebSocket 연결, 해제, 메시지 타입에 따른 유스케이스를 처리합니다.
• domain
  • application 레이어에서 필요로하는 핵심 도메인 로직을 수행합니다.
  • 유저의 이름과 세션을 저장하는 해시맵을 클래스 변수로 관리합니다.

 

 

WebRTC 주요 API

WebRTC의 P2P 연결에 필요한 주요 API를 효과적으로 다루기 위해 커스텀 훅을 작성했습니다.

그 중 일부 코드를 함께 살펴보겠습니다.

 

const peerConnection = new RTCPeerConnection();

peerConnection.ontrack = (event) => {}

peerConnection.onicecandidate = (event) => {}

peerConnection.oniceconnectionstatechange = (event) => {}

• new RTCPeerConnection()
  • P2P 통신을 위한 WebRTC 커넥션 객체를 생성합니다.
• ontrack
  • 상대 peer로부터 전달된 미디어 트랙(영상/음성 등)을 수신했을 때 실행되는 이벤트 핸들러입니다.
• onicecandidate
  • 후보를 비동기적으로 수집하고 하나 발견될 때마다 실행되는 이벤트 핸들러입니다.
• oniceconnectionstatechange
  • ICE 연결 상태가 변경될 때마다 호출되는 이벤트 핸들러입니다.

 

navigator.mediaDevices.getUserMedia()

• getUserMedia()
  • 브라우저에서 미디어 장치(카메라/마이크)를 사용자로부터 권한을 얻어 접근합니다.
  • 비동기로 동작하며, MediaStream 객체를 반환합니다.

 

peerConnection.createOffer()

peerConnection.createAnswer()

peerConnection.setLocalDescription()

peerConnection.setRemoteDescription()

peerConnection.addIceCandidate()

• createOffer()
  • P2P 연결을 시작하는 caller가 상대에게 보낼 SDP를 생성합니다.
  • Promise<RTCSessionDescriptionInit> 객체를 반환합니다.
• createAnswer()
  • offer를 받은 callee가 응답을 보낼 SDP를 생성합니다.
  • 마찬가지로, Promise<RTCSessionDescriptionInit> 객체를 반환합니다.
• setLocalDescription()
  • createOffer() 나 createAnswer() 로 생성한 자기 자신의 SDP 정보를 설정합니다.
  • 설정이 된 이후에 ICE Candidate 수집이 시작됩니다.
• setRemoteDescription()
  • 상대방으로부터 받은 SDP (offer 또는 answer) 정보를 설정합니다.
  • 설정이 된 이후에 상대가 보낸 ICE Candidate를 등록할 수 있습니다.
• addIceCandidate()
  • 상대방이 보내준 ICE Candidate 후보를 등록합니다.

 

 

애플리케이션의 구조를 살펴봤으니, 이제 실습으로 넘어가 봅시다 !

 

 

 

🚀 실습 코드 따라가기

---

드디어 실습 코드를 실행할 차례가 왔습니다.

코드를 실행할 수 있는 환경을 갖추고, 최종 목적인 화상채팅이 동작할 수 있도록 단계별로 따라가 보겠습니다.

 

🌕 사전 준비

깃허브에 있는 실습 코드를 실행하기 위해서 사전에 준비해야할 사항이 몇 가지 있습니다.

• 브라우저(Chrome, Safari 등)
• VS Code
• node (v22.10.0 이상)
• npm (v10.9.0 이상)
• IntelliJ IDEA
• JDK 17

 

 

🌕 애플리케이션 실행

1. 저장소 클론

git clone https://github.com/BenchPress200/webrtc-tutorial

• 로컬환경에 실습 코드 저장소를 클론합니다.

 

2. 리액트 소스 코드 열기

• VS Code를 통해 클론받은 webrtc-tutorial 디렉터리 하위에 있는 frontend 디렉터리를 오픈합니다.

 

3. 필요한 패키지 설치

npm install

• 오픈한 frontend 디렉터리에서 터미널을 열고 npm install 을 입력해서 필요한 패키지를 설치합니다.

 

4. 리액트 앱 실행

npm start

• 패키지 설치가 완료되었으면, npm start 를 입력해서 리액트 앱을 실행합니다.

 

• 정상 실행되었음을 확인합니다.

 

5. 스프링 부트 소스 코드 열기

• IntelliJ를 통해 클론받은 webrtc-tutorial 하위에 있는 backend/build.gradle 을 오픈합니다.

 

6. 롬복 설정

• IntelliJ에서 롬복을 인식하고 정상 동작시키기 위해 설정을 확인합니다.

 

7. 스프링 부트 앱 실행

• 우측 상단에 실행 버튼을 클릭하여 스프링 부트 앱이 정상 실행되었음을 확인합니다.

 

 

🌕 화상 채팅

이제 브라우저의 동작과 소스 코드를 동시에 확인하면서 화상 채팅까지 어떤 과정을 수행하는지 살펴보겠습니다.

 

1. 리액트 앱 접근

• 사용하는 브라우저를 통해 2개의 탭을 열고 localhost:3000로 이동합니다.

 

2. 미디어 장치 권한 설정

• 원활한 진행을 위해 localhost:3000의 미디어 장치 권한을 허용합니다.
• 접근을 허용하지 않는다면 에러가 발생할 수 있습니다.

 

3. 테스트 유저 가입

• 각 탭에서 '뚱이'와 '스폰지밥'을 입력하고 join 버튼을 클릭합니다.

 

프론드엔드 동작 - caller callee

• 원하는 이름을 입력하고 join 버튼을 클릭하면 Join.tsx 페이지에 있는 handleJoin() 함수를 호출합니다.
• join에 성공하면 Call.tsx 페이지로 이동합니다.

 

백엔드 동작

1. presentation.SignalingHandler
   • handleTextMessage(): JOIN에 해당하는 application 메서드 호출합니다.
2. application.SignalingService
   • join() : 가입 처리를 위한 domain 메서드 호출합니다.
3. domain.SignalingDomainService
   • existsName(): 유저 이름 중복검사를 진행합니다
   • sendJoinResultMessage(): 가입 결과 메시지 전송합니다.
   • broadcastUpdatedActiveUsers(): 가입 결과에 따른 최신 유저 목록을 모든 유저에게 전송합니다.

 

4. 전화걸기

• 뚱이가 스폰지밥에게 통화를 요청합니다.
• 스폰지밥은 뚱이의 통화를 수락합니다.

 

프론드엔드 동작 - caller

• 통화 상대를 클릭하면 Home.tsx 페이지에 있는 handleRequestCall() 호출됩니다.
• caller는 상대의 통화 수락을 대기하는 UI가 나타납니다.

 

백엔드 동작

1. presentation.SignalingHandler
   • handleTextMessage(): CALL에 해당하는 application 메서드 호출합니다.
2. application.SignalingService
   • call(): 통화 요청 처리를 위한 domain 메서드 호출합니다.
3. domain.SignalingDomainService
   • call(): 송수신자의 통화상태를 확인하고 수신자에게 통화 요청 메시지 전송합니다.
   • broadcastUpdatedActiveUsers(): 통화상태 변화에 따른 최신 유저 목록을 모든 유저에게 전송합니다.

 

프론드엔드 동작 - callee

• 통화요청 메시지를 수신하면 Home.tsx 페이지에 있는 handleWebSocketMessage에서 handleReceiveCall() 를 호출합니다.
• 통화 요청이 왔다는 UI가 표시됩니다.
• 통화 요청 수락 아이콘을 클릭하면, handleAcceptCall() 를 호출합니다.
• caller에게 통화를 수락했다는 메시지를 보내고 Call.tsx 페이지로 이동합니다.

 

백엔드 동작

1. presentation.SignalingHandler
   • handleTextMessage(): ACCEPT_CALL에 해당하는 application 메서드 호출합니다.
2. application.SignalingService
   • acceptCall(): 통화 요청 수락 처리를 위한 domain 메서드 호출합니다.
3. domain.SignalingDomainService
   • acceptCall(): 통화 요청을 수락했다는 메시지를 caller에게 전송합니다.

 

프론트엔드 동작 - caller

• 통화 요청 수락 메시지를 수신하면 Home.tsx 페이지에 있는 handleWebSocketMessage에서 handleEnterCallRoom() 를 호출합니다.
• 상대의 수락이 확인되었으므로 Call.tsx 페이지로 이동합니다.

 

5. Signaling

Call.tsx 페이지에서 진행하는 Signaling 과정입니다.

이해를 돕기 위해, 실습 코드에서는 유저의 동작에 따라 Signaling이 단계적으로 진행되도록 구성되어 있습니다.

실제로 기능을 구현한다면, 유저의 행동없이 통화를 수락했을 때 곧바로 offer와 answer를 주고받고 ICE Candidate를 교환하도록 하는 것이 일반적입니다.

✅ SDP와 ICE Candidate 를 주고 받는 흐름은 앞서 설명한 내용을 통해 충분히 이해할 수 있다고 판단하여, 이후 코드 레벨의 설명은 생략헀습니다. WebRTC연결에 사용된 핵심 API가 궁금하다면 실습 저장소의 useWebRTC.ts 를 참고하시면 됩니다.

 

미디어 스트림 설정

• 뚱이와 스폰지밥은 각각 미디어 스트림 세팅 버튼을 클릭합니다.
  • 뚱이는 offer를 보낼 수 있는 상태가 됩니다.
  • 스폰지밥은 뚱이의 offer를 기다리는 상태가 됩니다.
• 같은 장치를 사용하는 두 명의 유저를 시각적으로 명확히 구분하기 위해서 아이폰 연속성을 활용했습니다.

 

offer 전송 및 설정

• 뚱이가 Create and Send Offer 버튼을 클릭합니다.
  • 자신의 SDP(offer)가 생성되고 설정되면 ICE Candidate 수집 및 전송을 시작합니다.
  • 스폰지밥에게 offer 전송이 완료되면 answer를 기다리는 상태가 됩니다.
• 스폰지밥은 뚱이의 offer를 기다렸다가 Set Offer 버튼을 클릭합니다.
  • 뚱이의 SDP(offer)가 설정되면, answer 생성 및 전송 버튼이 활성화됩니다.
  • 뚱이의 SDP(offer)가 설정되면, 별도의 유저 동작없이 받은 ICE Candidate를 자동으로 추가합니다.

 

answer 전송 및 설정

• 스폰지밥이가 Create and Send Answer 버튼을 클릭합니다.
  • 자신의 SDP(answer)가 생성되고 설정되면 ICE Candidate 수집 및 전송을 시작합니다.
• 뚱이은 스폰지밥의 answer를 기다렸다가 Set Answer 버튼을 클릭합니다.
  • 스폰지밥의 SDP(answer)가 설정되면, 별도의 유저 동작없이 ICE Candidate를 자동으로 추가합니다.
• 서로 교환한 ICE Candidate를 추가했을 때, 유효한 연결이 생성된다면 통화시작 가능 상태가 됩니다.

 

6. 화상 채팅 시작

• 뚱이와 스폰지밥이 정상적으로 SDP와 ICE Candidate를 교환하고 화상채팅을 시작합니다.

 

✅ 로컬환경의 미디어 스트림과 peer의 미디어 스트림은 useWebRTC 커스텀 훅에서 MediaStream 타입으로 상태관리를 하고 있습니다.
해당 객체를 video 태그의 ref속성에 할당해주면 정상적으로 미디어 스트림이 렌더링 됩니다. video 태그에 정확히 어떻게 전달하고, 어떤 속성이 추가적으로 필요한지는 frontend/src/components 패키지에 있는 비디오 관련 컴포넌트에서 확인하실 수 있습니다.

 

 

 

👋🏻 마치며

---

이전에 팀 프로젝트를 진행하면서, 미디어 중계 서버인 Kurento를 사용하여 N대 N 화상채팅 서비스를 구현했었습니다.

WebRTC API를 한 번 감싼 Kurento API, 다수의 peer가 중복으로 Signaling 수행, 명확하지 않은 상태 관리, WebSocket 세션이 의도치 않게 닫혔을 때의 동작, Nginx의 WebSocket 연결 리버스 프록시 문제, coturn 배포 등 정말 많은 문제를 만났었습니다.

 

문제가 발생한 근본적인 원인은 WebRTC 의 연결 방식을 정확히 이해하지 못하고 있다고 판단했습니다.

그래서 다시 학습하고 실습 코드를 직접 작성하면서 이해도를 높일 수 있었습니다. 또한, 이렇게 글로 남길수도 있게 되었구요.

WebRTC 기술에 대해 호기심 혹은 필요하신 분에게 도움이 되었으면 좋겠습니다.

 

읽어주셔서 감사합니다. 궁금한 점에 대한 질문 환영합니다!

부족한, 잘못된 설명이 있다면 알려주시면 감사하겠습니다 🙏🏻