iscream-webrtc-sdk/README.md

I-scream WebRTC SDK for browser - LiveKit based real-time communication with teacher/student roles

# I-scream WebRTC SDK (Browser)

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

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

## 특징

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

## 설치

### GitHub Private Repository에서 설치

```bash
# SSH 방식 (권장)
npm install git+ssh://git@github.com: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://git@github.com:i-screammedia/iscream-webrtc-sdk.git#v2.4.1

# package.json에 추가
{
  "dependencies": {
    "iscream-webrtc-sdk": "git+ssh://git@github.com:i-screammedia/iscream-webrtc-sdk.git#v2.4.1",
    "livekit-client": "^2.0.0"
  }
}
```

### npm에서 설치 (공개 버전)

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

## 기본 사용법

```javascript
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. **선생님 정책**
   - 룸당 선생님은 1명만 허용
   - 선생님은 항상 미디어 송출 가능
   - 발표자 지정/해제 권한 보유

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

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

## 개발

```bash
# 의존성 설치
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