{"_id":"@colyseus/webrtc","name":"@colyseus/webrtc","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@colyseus/webrtc","version":"1.0.0","description":"WebRTC Signaling Server for Colyseus and Client Tools","type":"module","input":"./src/index.ts","main":"./build/index.cjs","module":"./build/index.js","typings":"./build/index.d.ts","exports":{".":{"@source":"./src/index.ts","types":"./build/index.d.ts","import":"./build/index.js","require":"./build/index.cjs"},"./client":{"@source":"./src/client.ts","types":"./build/client.d.ts","import":"./build/client.js","require":"./build/client.cjs"},"./package.json":"./package.json"},"scripts":{"build":"tsup","dev":"tsup --watch","prepublishOnly":"tsup"},"peerDependencies":{"colyseus":">=0.17.0"},"peerDependenciesMeta":{"colyseus":{"optional":true}},"devDependencies":{"colyseus":"^0.17.0","tsup":"^8.5.1","typescript":"^5.5.0"},"repository":{"type":"git","url":"git+ssh://git@github.com/colyseus/webrtc.git"},"keywords":["colyseus","webrtc","signaling"],"author":{"name":"Endel Dreyer"},"license":"MIT","bugs":{"url":"https://github.com/colyseus/webrtc/issues"},"homepage":"https://github.com/colyseus/webrtc#readme","publishConfig":{"access":"public"},"_id":"@colyseus/webrtc@1.0.0","gitHead":"ff557c12413574fb6cda0c3a3416a3782f07f795","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-UUN9GhZhhpvOBwTSke/qPGOt4vf8HOkUOrinQmkUW+H984V0ks1x93c1Q1A47eaREbdFy1R5hyZ7xg8RnHC86Q==","shasum":"41ba32c4d5668eee4ec01d9413b90dc2b9c374db","tarball":"https://registry.npmjs.org/@colyseus/webrtc/-/webrtc-1.0.0.tgz","fileCount":13,"unpackedSize":31592,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCT1WqbLQMy66i0VADG0BZcyVORWFYCBqYpnWiaprIa6gIgGpXJvHNVSbMJzh3XSFjRACyttZHhZiR9huRXaA1mdzU="}]},"_npmUser":{"name":"endel","email":"endel.dreyer@gmail.com"},"directories":{},"maintainers":[{"name":"endel","email":"endel.dreyer@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/webrtc_1.0.0_1774643489600_0.6551998255544558"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-27T20:31:29.451Z","1.0.0":"2026-03-27T20:31:29.744Z","modified":"2026-03-27T20:31:30.087Z"},"maintainers":[{"name":"endel","email":"endel.dreyer@gmail.com"}],"description":"WebRTC Signaling Server for Colyseus and Client Tools","homepage":"https://github.com/colyseus/webrtc#readme","keywords":["colyseus","webrtc","signaling"],"repository":{"type":"git","url":"git+ssh://git@github.com/colyseus/webrtc.git"},"author":{"name":"Endel Dreyer"},"bugs":{"url":"https://github.com/colyseus/webrtc/issues"},"license":"MIT","readme":"# @colyseus/webrtc\n\nA signaling server utility for establishing WebRTC peer-to-peer connections through [Colyseus](https://colyseus.io/) rooms. Use it to add audio/video communication between clients.\n\nThis package handles **signaling only** — the exchange of SDP offers/answers and ICE candidates needed to establish WebRTC connections. It does not provide state synchronization over peer-to-peer; Colyseus state sync continues to work through the server as usual.\n\nThis package provides two entry points:\n\n| Import | Environment | Purpose |\n|---|---|---|\n| `@colyseus/webrtc` | Server | Room message handlers for WebRTC signaling |\n| `@colyseus/webrtc/client` | Browser | `WebRTCClient` that consumes signaling and manages peer connections |\n\n## Installation\n\n```bash\nnpm install @colyseus/webrtc\n```\n\n## Server-side usage\n\nSpread the `signaling` object into your room's `messages` to add all the WebRTC signaling handlers. Call `onPeerDisconnected` from `onLeave` so peers are notified when someone disconnects.\n\n```ts\nimport { Room, Client } from \"colyseus\";\nimport { signaling, onPeerDisconnected } from \"@colyseus/webrtc\";\n\nclass VideoRoom extends Room {\n  messages = { ...signaling };\n\n  onLeave(client: Client) {\n    onPeerDisconnected(this, client);\n  }\n}\n```\n\nYou can mix your own message handlers alongside signaling:\n\n```ts\nclass VideoRoom extends Room {\n  messages = {\n    ...signaling,\n    chat(client: Client, message: string) {\n      this.broadcast(\"chat\", `${client.sessionId}: ${message}`);\n    },\n  };\n}\n```\n\n### Signaling messages handled\n\n| Message | Direction | Description |\n|---|---|---|\n| `webrtc:join` | client -> server | Client signals readiness; server replies with peer list and broadcasts to others |\n| `webrtc:offer` | client -> server -> client | Relay SDP offer to the target peer |\n| `webrtc:answer` | client -> server -> client | Relay SDP answer to the target peer |\n| `webrtc:ice-candidate` | client -> server -> client | Relay ICE candidate to the target peer |\n| `webrtc:peers` | server -> client | List of existing peer session IDs (sent on join) |\n| `webrtc:peer-joined` | server -> client | A new peer has joined |\n| `webrtc:peer-left` | server -> client | A peer has left |\n\n## Client-side usage\n\n```ts\nimport { Client } from \"@colyseus/sdk\";\nimport { WebRTCClient } from \"@colyseus/webrtc/client\";\n\nconst client = new Client(\"ws://localhost:2567\");\nconst room = await client.joinOrCreate(\"video\");\n\nconst webrtc = new WebRTCClient(room);\n\nwebrtc.onLocalStream = (stream) => {\n  // Attach to a <video> element for self-preview\n  localVideo.srcObject = stream;\n};\n\nwebrtc.onPeerConnected = (peerId, stream) => {\n  // Attach remote stream to a <video> element\n};\n\nwebrtc.onPeerDisconnected = (peerId) => {\n  // Remove the peer's video element\n};\n\n// Request camera/mic and start signaling\nawait webrtc.join({ audio: true, video: true });\n\n// Later, to stop and clean up:\nwebrtc.leave();\nroom.leave();\n```\n\n### `WebRTCClient` API\n\n#### Constructor\n\n```ts\nnew WebRTCClient(room, options?)\n```\n\n- **`room`** — Any object with `send(type, message)` and `onMessage(type, callback)` (e.g. a Colyseus `Room` instance).\n- **`options.iceServers`** — Custom ICE servers. Defaults to Google STUN servers.\n\n#### Methods\n\n| Method | Description |\n|---|---|\n| `join(constraints?)` | Request user media with the given [`MediaStreamConstraints`](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamConstraints) and start signaling. Defaults to `{ audio: true, video: true }`. |\n| `leave()` | Close all peer connections, stop local tracks, and unbind signaling listeners. |\n\n#### Callbacks\n\n| Callback | Signature | Description |\n|---|---|---|\n| `onLocalStream` | `(stream: MediaStream) => void` | Fired after `getUserMedia` succeeds |\n| `onPeerConnected` | `(peerId: string, stream: MediaStream) => void` | Fired when a remote peer's media stream is received |\n| `onPeerDisconnected` | `(peerId: string) => void` | Fired when a peer connection closes |\n\n#### Properties\n\n| Property | Type | Description |\n|---|---|---|\n| `localStream` | `MediaStream \\| null` | The local media stream |\n| `peers` | `Map<string, RTCPeerConnection>` | Active peer connections keyed by session ID |\n| `streams` | `Map<string, MediaStream>` | Remote media streams keyed by session ID |\n\n## Running the example\n\nThe `example/` directory contains a full working demo with a Colyseus server and a React client.\n\n```bash\ncd example\nnpm install\nnpm run dev\n```\n\nThis starts two processes concurrently:\n\n- **Server** on `ws://localhost:2567` (Colyseus + WebSocket transport)\n- **Client** on `http://localhost:3000` (Vite + React)\n\nOpen `http://localhost:3000` in two browser tabs (or two devices on the same network) to test video calling. The browser will ask for camera/microphone permissions.\n\n## How it works\n\n```\nClient A                     Server                      Client B\n   |                           |                            |\n   |--- webrtc:join ---------->|                            |\n   |<-- webrtc:peers []        |                            |\n   |                           |                            |\n   |                           |<-------- webrtc:join ------|\n   |                           |--------- webrtc:peers [A]->|\n   |<-- webrtc:peer-joined B --|                            |\n   |                           |                            |\n   |                           |<------ webrtc:offer (A) ---|\n   |<-- webrtc:offer (B) ------|                            |\n   |                           |                            |\n   |--- webrtc:answer (B) ---->|                            |\n   |                           |------- webrtc:answer (A)-->|\n   |                           |                            |\n   |<-------- ICE candidates exchanged via server --------->|\n   |                           |                            |\n   |<=============== peer-to-peer audio/video ==============>|\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-de5ae745b94604a8200bd7c7007a8b45"}