-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathllms.txt
More file actions
136 lines (100 loc) · 8.51 KB
/
Copy pathllms.txt
File metadata and controls
136 lines (100 loc) · 8.51 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
# SOOPAPI - 비공식 SOOP 채팅 API
> SOOP(한국 라이브 스트리밍 플랫폼) 채팅 시스템과 상호작용하기 위한 비공식 Java 25+ 라이브러리.
> WebSocket 기반 실시간 채팅 연결, 93개 이상의 타입 안전한 이벤트 디코딩, 이벤트 기반 아키텍처를 제공합니다.
이 문서는 **요점 정리**입니다. 전체 API 시그니처·이벤트별 필드·프로토콜·내부 구조 등 상세 레퍼런스는
[llms-full.txt](llms-full.txt)에 있으며, 각 절 끝의 `→ llms-full.txt §...` 링크로 바로 이동할 수 있습니다.
## 핵심 정보
- GitHub: https://github.com/getCurrentThread/soopapi
- 버전: v0.14.0
- 라이선스: MIT
- 언어: Java 25 이상
- 빌드: Gradle 9.3.1
- 배포: JitPack (com.github.getCurrentThread:soopapi)
- 런타임 의존성: Gson
## 설치
```groovy
repositories { maven { url 'https://jitpack.io' } }
dependencies {
implementation 'com.github.getCurrentThread:soopapi:v0.13.0' // 최신 버전은 핵심 정보 참조
}
```
→ 상세: [llms-full.txt § 설치](llms-full.txt#설치)
## 빠른 시작 (권장: SOOPClient)
```java
try (SOOPClient client = new SOOPClient()) {
// 글로벌 리스너 — 이후 add()되는 모든 스트림에 자동 attach. 핸들러: (streamerId, event)
client.on(ChatEvent.CHAT_MESSAGE, (bid, ChatMessageEvent e) ->
System.out.println("[" + bid + "] " + e.senderNickname() + ": " + e.message()));
client.on(ChatEvent.SEND_BALLOON, (bid, SendBalloonEvent e) ->
System.out.println("[" + bid + "] " + e.senderNickname() + "님이 풍선 " + e.count() + "개!"));
client.add("streamerA"); // 등록 즉시 비동기 연결, bid 기준 dedup
client.add("streamerB");
client.connectAll().join(); // 모든 연결이 끊길 때까지 대기
}
```
- authCookie 없이 연결하면 **익명(읽기 전용)** 모드 — 수신은 되지만 `sendChat()`은 `AuthenticationException`.
- 인증/전송: `client.auth().signIn(id, pw)` → `AuthCookie` → `SOOPChatConfig.Builder().authCookie(cookie)` → `sendChat(...)`.
→ 직접 연결 · 인증+전송 · 연결 상태 이벤트 · 에러 핸들링 예제: [llms-full.txt § 빠른 시작](llms-full.txt#빠른-시작)
## API 핵심
**SOOPClient** (파사드, `AutoCloseable`) — 통합 진입점
- `add(streamerId)` / `add(config)` → 등록 + 즉시 비동기 연결 (bid dedup, 자동 재연결)
- `remove(id)` · `get(id)` · `streamerIds()` · `clients()`
- `on/off(ChatEvent, (streamerId, event) -> …)` → 글로벌 리스너 (모든 스트림 + 이후 추가분에 자동 attach)
- `connectAll()` · `reconnect(id)` · `reconnectAll()` · `close()`
- `auth()` → SOOPAuth · `live()` → SOOPLive · `channel()` → SOOPChannel
**SOOPChatClient** (단일 채팅 연결, `AutoCloseable`)
- `on/once/off(ChatEvent, listener)` · `getEventEmitter()`
- `connectToChat()` (연결 해제 시 완료) · `connectAndAwait()` (블로킹) · `disconnect()` · `reconnect()` · `forceReconnect()`
- `sendChat(message)` (인증 필요) · `isConnected()` · `getConnectionStatus()` · `getBid()`
**HTTP API**: `SOOPAuth.signIn(id, pw)` → `AuthCookie` · `SOOPLive.detail(id[, bno[, cookie]])` → `LiveDetail` · `SOOPChannel.station(id)` → `StationInfo`
→ 전체 메서드 시그니처 · `SOOPChatConfig.Builder` 옵션 · record 필드: [llms-full.txt § API 레퍼런스](llms-full.txt#api-레퍼런스)
## 이벤트 시스템
모든 이벤트는 Java `record`이며 sealed 계층에 속합니다. 공통 필드: `eventType()`, `raw()`, `timestamp()`.
```
BaseEvent (sealed)
├── ChatBaseEvent 채팅 (메시지, 입퇴장)
├── DonationBaseEvent 후원 (풍선, 초콜릿, 구독)
├── SystemBaseEvent 시스템 (연결, 서버 상태)
├── ModerationBaseEvent 관리 (킥, 채금, 차단)
├── ItemBaseEvent 아이템 (구매, 드롭)
├── NotificationBaseEvent 알림 (공지, 미션)
└── UnknownEvent 알 수 없는 타입
```
- 서비스 코드 `0`~`128` + 클라이언트 합성 이벤트(`-2` RAW, `-3` DISCONNECTED, `-4` RECONNECTING, `-5` RECONNECTED, `-1` NONE_TYPE).
- `ChatEvent.fromCode(int)`는 미지의 코드에 대해 `NONE_TYPE`(센티넬)을 반환합니다.
- 자주 쓰는 이벤트:
| 코드 | ChatEvent | Record | 설명 |
|------|-----------|--------|------|
| 5 | CHAT_MESSAGE | ChatMessageEvent | 채팅 메시지 |
| 9 | DIRECT_CHAT | DirectChatEvent | 귓속말 |
| 18 | SEND_BALLOON | SendBalloonEvent | 별풍선 후원 |
| 37 | CHOCOLATE | ChocolateEvent | 초콜릿 후원 |
| 108 | SEND_SUBSCRIPTION | SendSubscriptionEvent | 구독 선물 |
| 11 | KICK | KickEvent | 강제 퇴장 |
| 8 | SET_DUMB | SetDumbEvent | 채금 |
→ 전체 코드↔이벤트 표(범주별): [llms-full.txt § 전체 이벤트 목록](llms-full.txt#전체-이벤트-목록)
→ 이벤트별 record 필드 상세: [llms-full.txt § 이벤트 Record 필드 상세](llms-full.txt#이벤트-record-필드-상세)
→ 실제 캡처 패킷의 필드 값 예시(30개): [llms-full.txt § Fixture 검증 데이터](llms-full.txt#fixture-검증-데이터-30개-이벤트-실제-캡처)
## 코드표 (지연 디코딩)
`...soopapi.code` 패키지가 원시 코드/플래그를 타입으로 **지연 디코딩**합니다. 원시 필드(String/int)는 그대로 유지되고, 이벤트 record의 접근자가 **호출 시점에만** 파싱합니다. 알 수 없는 코드는 센티넬(`UNKNOWN` / `UserLevel.EMPTY`)을 반환하며 예외를 던지지 않습니다.
- `UserLevel.parse("주|보조")` → `UserFlag`(주) · `UserFlag2`(보조) 집합. 두 그룹은 비트값이 겹쳐 enum을 분리(예: 16 = GUEST(주) vs GAMEGOD(보조)). 부호 비트(`NOTITOPFAN = 1<<31`)는 `(mask & bit) == bit`로 안전 처리.
- 접근자: `ChatMessageEvent.senderLevel()`, `LoginEvent.userLevel()`, `JoinChannelEvent.userLevel()`, `SetUserFlagEvent.oldLevel()/newLevel()`, `SetAdminFlagEvent.level()`, `ChatUserEntry.level()`, `AdminChatUserEntry.level()`.
- `ChatIceType.fromCode(int)`(레거시 0~4) + `ChatIceType.Flag.fromMask(int)`(v2 비트). 접근자: `IceModeEvent`/`IceModeExEvent`/`GetIceModeRelayEvent`의 `iceType()`, `iceFlags()`, `isIceFlagMode()`.
- `ChatQuitStatus.fromCode(int)`(0~6). 접근자: `QuitChannelEvent.quitStatus()`.
→ 플래그 비트값 · 접근자 전체 목록: [llms-full.txt § 코드표 및 플래그 해석](llms-full.txt#코드표-및-플래그-해석)
## 연결 라이프사이클 & 에러 처리
- `SOOPClient.add()`는 등록과 동시에 비동기 연결을 시작하므로 별도 `connectToChat()`이 불필요합니다. 저수준 `SOOPChatClient`를 직접 쓸 때만 `connectToChat()`/`connectAndAwait()`를 사용합니다.
- `connectToChat()`이 반환하는 `CompletableFuture`는 v0.5.0부터 연결이 해제될 때 완료됩니다.
- 예외 계층: `SOOPChatException`(RuntimeException) ← `AuthenticationException` · `ConnectionException` · `EventEmitterException`(`getChatEvent()` 제공).
→ 상세: [llms-full.txt § connectToChat() 동작 방식](llms-full.txt#connecttochat-동작-방식) · [§ 에러 처리](llms-full.txt#에러-처리)
## 더 알아보기 (llms-full.txt)
기여자·심화용 레퍼런스는 전부 [llms-full.txt](llms-full.txt)에 있습니다.
- 아키텍처 개요(패키지 구조 · 컴포넌트 관계 · 메시지 파이프라인) → [§ 아키텍처 개요](llms-full.txt#아키텍처-개요-기여자용)
- 내부 구조 상세(ConnectionManager · SOOPConnection · WebSocketManager · Listener) → [§ 내부 구조 상세](llms-full.txt#내부-구조-상세)
- WebSocket 프로토콜(패킷 구조 · 명령 코드 · 구분자 · 핸드셰이크) → [§ WebSocket 프로토콜](llms-full.txt#websocket-프로토콜)
- 디코더 시스템(IMessageDecoder · 팩토리 · 디코딩 규칙) → [§ 디코더 시스템](llms-full.txt#디코더-시스템)
- 이벤트 시스템 내부(EventEmitter · once() 구현 · sealed 계층) → [§ 이벤트 시스템 내부](llms-full.txt#이벤트-시스템-내부)
- 테스트 · 빌드 시스템 · 기여 가이드 · 성능 고려사항 → [§ 테스트](llms-full.txt#테스트) · [§ 빌드 시스템](llms-full.txt#빌드-시스템) · [§ 기여 가이드](llms-full.txt#기여-가이드) · [§ 성능 고려사항](llms-full.txt#성능-고려사항)
## 면책 조항
이는 비공식 API이며 SOOP와 제휴되거나 승인되지 않았습니다. 사용에 따른 책임은 사용자에게 있습니다.
SOOP 플랫폼의 웹소켓 통신 방식이 변경되면 동작하지 않을 수 있습니다.