iscream-webrtc-sdk

I-scream WebRTC SDK (Browser)

LiveKit 기반의 브라우저용 WebRTC SDK로, 특히 교육 환경을 위한 선생님/학생 역할 시스템을 제공합니다.

Note: 이 패키지는 브라우저 전용입니다. Node.js 환경에서는 동작하지 않습니다.

특징

• 🎓 2:N 구조: 선생님 + 발표자만 미디어 송출 가능
• 👥 역할 기반 시스템: 선생님/학생 역할 자동 관리
• 🎤 발표자 관리: 선생님이 학생 중 발표자 지정 가능
• 🔒 강력한 검증: 선생님 중복 방지, 학생 수 제한 (50명)
• 👻 유령 사용자 정리: 비정상 종료된 참가자 자동 정리
• 📹 고급 미디어 제어: 화질 설정, 화면 공유, 오디오 장치 선택
• 🔐 OAuth 2.0 인증: Client Credentials 방식 지원

설치

GitHub Private Repository에서 설치

# SSH 방식 (권장)
npm install git+ssh://[e-mail]:i-screammedia/iscream-webrtc-sdk.git

# HTTPS 방식 (GitHub Personal Access Token 필요)
npm install git+https://github.com/i-screammedia/iscream-webrtc-sdk.git

# 특정 버전/태그 설치
npm install git+ssh://[e-mail]:i-screammedia/iscream-webrtc-sdk.git#v2.4.1

# package.json에 추가
{
  "dependencies": {
    "iscream-webrtc-sdk": "git+ssh://[e-mail]:i-screammedia/iscream-webrtc-sdk.git#v2.4.1",
    "livekit-client": "^2.0.0"
  }
}

npm에서 설치 (공개 버전)

npm install @supermon2018/iscream-webrtc-sdk-node livekit-client

기본 사용법

import IScreamWebRTC from 'iscream-webrtc-sdk';
// 또는 npm 버전
// import IScreamWebRTC from '@supermon2018/iscream-webrtc-sdk-node';

// SDK 초기화
const rtc = new IScreamWebRTC({
  serverHost: 'rtc.i-screammedia.com',
  auth: {
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret'
  },
  debug: true
});

// 이벤트 리스너 등록
rtc.on('connected', (data) => {
  console.log('룸 연결됨:', data);
});

rtc.on('participantJoined', (participant) => {
  console.log('참가자 입장:', participant.name);
});

rtc.on('trackSubscribed', (track, publication, participant) => {
  // 비디오/오디오 트랙 처리
});

// 룸 연결
await rtc.connect({
  roomName: 'classroom-1',
  participantName: '김선생님',
  role: 'teacher',
  publishOnJoin: true
});

// 미디어 제어
await rtc.enableVideo(true);
await rtc.enableAudio(true);

// 발표자 지정 (선생님만 가능)
await rtc.setPresenter('student-identity');

주요 API

연결 관리

• connect(options) - 룸 연결
• disconnect() - 연결 해제
• isConnectionActive() - 연결 상태 확인

미디어 제어

• enableVideo(enabled) - 비디오 켜기/끄기
• enableAudio(enabled) - 오디오 켜기/끄기
• toggleCamera() - 카메라 토글
• toggleMicrophone() - 마이크 토글
• startScreenShare() - 화면 공유 시작
• stopScreenShare() - 화면 공유 중지
• isScreenShareActive() - 화면 공유 상태 확인

발표자 관리 (선생님 전용)

• setPresenter(participantId) - 발표자 지정
• clearPresenter() - 발표자 해제
• getCurrentPresenter() - 현재 발표자 조회

참가자 관리

• getParticipants() - 전체 참가자 목록
• getParticipantsByRole(role) - 역할별 참가자 목록
• cleanupGhostParticipants() - 유령 사용자 정리 (선생님 전용)

메시지 전송

• sendMessage(message) - 채팅 메시지 전송

화질 설정

• setVideoQuality(quality) - 비디오 화질 설정 ('low', 'medium', 'high', 'ultra', 'auto')
• setAudioQuality(quality) - 오디오 화질 설정 ('low', 'medium', 'high')

이벤트

• connected - 룸 연결 완료
• disconnected - 연결 해제
• participant:joined - 참가자 입장
• participant:left - 참가자 퇴장
• trackSubscribed - 미디어 트랙 구독
• trackUnsubscribed - 미디어 트랙 구독 해제
• presenter:changed - 발표자 변경
• chatMessage - 채팅 메시지 수신
• error - 오류 발생

룸 정책

• 선생님 정책

  • 룸당 선생님은 1명만 허용
  • 선생님은 항상 미디어 송출 가능
  • 발표자 지정/해제 권한 보유

• 학생 정책

  • 최대 50명까지 입장 가능
  • 발표자로 지정된 경우에만 미디어 송출 가능
  • 일반 학생은 시청만 가능

• 발표자 정책

  • 학생 중 1명만 발표자 지정 가능
  • 발표자 지정 시 자동으로 카메라/마이크 활성화
  • 발표자 해제 시 미디어 자동 비활성화

개발

# 의존성 설치
npm install

# 빌드
npm run build

# 개발 모드 (watch)
npm run dev

라이선스

Private - I-scream Media

지원

• 문서: https://rtc.i-screammedia.com/sdk/docs
• 이슈: https://github.com/i-screammedia/iscream-webrtc-sdk/issues