Standalone WebRTC conferencing service (mediasoup SFU + coturn) for the existing NestJS backend. Handles WebRTC signaling, media routing, meeting state, and presence; the backend keeps auth, user management, notifications, and scheduling. No Twilio/Agora/Daily/LiveKit, no managed TURN — only mediasoup, coturn, Socket.IO, Node.js, TypeScript.
React / Mobile → Existing NestJS Backend (JWT, scheduling) → call-service (this repo) → mediasoup Workers → coturn
Wiring this up against your backend or frontend? See docs/INTEGRATION.md for the full REST + Socket.IO contract (endpoints, event payloads, auth, a complete join/produce/consume client flow).
This service exposes two separate Socket.IO namespaces and REST prefixes, not one generic "calls" surface, because 1:1 calls and group meetings have genuinely different shapes:
/calls (1:1) |
/meetings (group / large standup) |
|
|---|---|---|
| REST prefix | POST /calls, GET /calls/:id, POST /calls/:id/end |
POST /meetings, GET /meetings/:id, POST /meetings/:id/end, DELETE /meetings/:id, plus /meetings/:id/{mute,kick,remove,promote,demote,lock,unlock} |
| Gateway | CallsGateway |
MeetingsGateway |
| Host/moderator hierarchy | none — either party can end the call | host + moderator + participant, configurable permissions |
| Chat, reactions, raise hand | — | ✅ |
| Waiting room, lock meeting | — | ✅ |
| Screen share | ✅ | ✅ |
Both gateways delegate the actual mediasoup work (transports, producers, consumers,
simulcast, ICE restart, active-speaker detection) to one shared SignalingService
(src/websocket/signaling.service.ts) — see that file's doc comment for why this is
composition rather than a shared gateway base class (Nest's @SubscribeMessage scanner
does not reliably pick up handlers declared only in a parent class).
A Meeting's type (one_to_one | group) fixes which namespace it lives on
(NAMESPACE_BY_TYPE in meeting.entity.ts); RealtimeBroadcaster is namespace-aware so
REST-triggered moderation (e.g. a backend call to POST /meetings/:id/kick) reaches the
right namespace's live sockets without the broadcaster having to guess.
joinRoom, createTransport, connectTransport, produce, consume, etc. are called
with a Socket.IO ack callback:
socket.emit('produce', { meetingId, transportId, kind, rtpParameters }, (ack) => {
if (!ack.success) return console.error(ack.error);
console.log(ack.data.id); // producerId
});Every such handler returns { success: boolean, data?, error? } (see
websocket/ws-response.util.ts) instead of throwing a raw WsException, because Nest's
default WS exception filter doesn't feed back into ack callbacks — this keeps client-side
error handling uniform. One-way broadcasts (userJoined, newProducer, reaction,
chatMessage, ...) are plain emits to the room, listed in
src/interfaces/socket-events.enum.ts.
- Sockets (both namespaces):
handshake.auth.tokenor anAuthorization: Bearerheader, a JWT issued by the existing backend, verified withJWT_SECRET/JWT_ALGORITHM. Client-supplied role/permission claims are never trusted — role is always resolved server-side (ParticipantService.resolveRole:hostIdmatch → host, everyone else → participant, promotions tracked live). - REST (backend → call-service only, never called by browsers/mobile):
X-API-Keyheader checked againstINTERNAL_API_KEYS(comma-separated, supports rotation) with a constant-time comparison. These endpoints treat the caller as already-authorized — the backend is expected to have checked the requesting user's host/moderator permission before calling e.g.POST /meetings/:id/mute.
- Workers (
workers/worker-pool.service.ts): one per CPU core by default (MEDIASOUP_NUM_WORKERSto override), each pinned to its own OS process. A crashed worker is respawned automatically; rooms it was hosting are unrecoverable (mediasoup has no live migration) and clients must rejoin. - Routers (
mediasoup/router-manager.service.ts): one per meeting, created lazily on the least-loaded worker (WorkerPoolService.getLeastLoadedWorker) — this is the CPU-aware allocation and room-sharding foundation the spec asks for. Each router also owns anAudioLevelObserverfor active-speaker detection, broadcast asactiveSpeakerChanged. - Transports/Producers/Consumers (
mediasoup/transport.service.ts,producer-consumer.service.ts): standard WebRTC transports, Opus/VP8/VP9/H264 codecs, 3-layer simulcast (SIMULCAST_ENCODINGSinconfig/mediasoup.config.ts), consumers created paused and resumed by the client once ready,setPreferredLayersexposed for quality downgrade of off-screen/inactive tiles, ICE restart wired end-to-end (restartIcesocket event →transport.restartIce()). - Data producers/consumers: mediasoup supports these natively and nothing here blocks
adding them, but chat/reactions/raise-hand are deliberately carried over the existing
Socket.IO connection instead of a mediasoup
DataChannel— one signaling transport is simpler to reason about and rate-limit than two, and Socket.IO already fans out to a room correctly at the scales this spec targets.
coturn/coturn.service.ts issues short-lived TURN credentials using coturn's
use-auth-secret REST API convention — username = "<expiry>:<userId>",
credential = base64(HMAC-SHA1(TURN_SECRET, username)). coturn re-derives the same value
independently at auth time, so there's no per-user secret to provision, store, or rotate —
only TURN_SECRET, which is never sent to a client (iceServers handed to the browser only
ever contains the derived, time-limited username/credential pair). Config template:
docker/coturn/turnserver.conf — replace the CHANGE_ME placeholders before deploying.
Per an explicit scoping decision, this pass prioritized a real, running core over shallow coverage of every line item in the original spec:
Fully wired, not stubs: JWT + API-key auth, mediasoup workers/routers/transports/
producers/consumers, simulcast, active-speaker detection, ICE restart, 1:1 calls, group
meetings, chat (bounded in-memory history), reactions (validated + rate-limited), raise
hand, screen share (single-presenter enforcement), host controls (mute/unmute-request/
kick/lock/unlock/end/disable-chat/disable-reactions/disable-screenshare/promote/demote),
configurable permissions (interfaces/permission.enum.ts + per-meeting overrides), waiting
room (admit/reject), coturn credential generation, rate limiting (connection + per-event),
structured logging, health check, Prometheus metrics, graceful worker respawn, Docker,
cross-instance signaling (opt-in via REDIS_URL — Socket.IO Redis adapter, a
Redis-backed meeting-ownership directory, sticky routing at socket join, and transparent
REST forwarding for moderation calls that land on a non-owning instance; see
"Multi-instance deployment" in docs/INTEGRATION.md).
Architecture only, not fully implemented:
- Recording: no muxing/storage pipeline. The natural extension point is a
PlainTransportconsuming each producer server-side and piping to an external recorder (e.g. GStreamer/ffmpeg over RTP) — intentionally not built, since it needs a storage/ encoding decision this spec didn't make. - Room sharding across instances: cross-instance signaling now works (see above),
but a single meeting's mediasoup Router still only ever exists on the one instance that
created it — there is no cross-instance mediasoup piping yet (
router.pipeToRouter), so a meeting whose participant count exceeds one instance's local worker capacity has nowhere to overflow to. The worker-pool load-balancing (WorkerPoolService) is the foundation for this; theshardId/consistent-hash routing layer across instances isn't built. IMeetingRepositorystays in-memory on purpose: a Meeting's live Participants own process-bound mediasoup Transport/Producer/Consumer objects (seeparticipant/entities/participant.entity.ts) that can't be serialized into Redis or reconstructed on another instance — so instead of swapping this repository's storage, cross-instance visibility is handled by a separate, purpose-built ownership directory (meeting/meeting-directory.service.ts) plus REST forwarding to whichever instance actually holds the live state. See that file's doc comment for the full reasoning.
No browser or WebRTC-capable client was available in this environment, so the actual
media path (DTLS handshake, RTP flow, simulcast switching) has not been exercised
end-to-end — that requires a real mediasoup-client in a browser or a WebRTC stack like
wrtc/node-webrtc, neither of which can run headless here. What was tested: a 10
simulated-client signaling load test (scripts/signaling-load-test.ts) exercising auth,
joinRoom/leaveRoom, transport/producer/consumer request shapes up to (not including)
the real DTLS connectTransport step, chat, reactions, raise hand, host mute/kick, lock,
and disconnect cleanup — see that script's own output for current pass/fail status.
Before relying on this in production, run a real two-browser call end-to-end.
See .env.example for the full list with defaults and comments. Required with no default:
JWT_SECRET, INTERNAL_API_KEYS, MEDIASOUP_ANNOUNCED_IP, TURN_HOST, TURN_SECRET.
cp .env.example .env # then fill in the required vars above
npm install
npm run start:devdocker-compose.yml runs call-service + coturn together (docker compose up --build);
add --profile scaling to also start Redis.
src/
├── auth/ JWT (sockets) + API key (backend REST) auth
├── calls/ 1:1 call REST controller + gateway
├── chat/ room chat (bounded history)
├── config/ env validation, mediasoup config
├── coturn/ TURN/STUN credential generation
├── health/ GET /health
├── interfaces/ shared enums/types (roles, permissions, event names)
├── meeting/ meeting state, repository, waiting room, REST controller
├── mediasoup/ router/transport/producer/consumer management
├── metrics/ GET /metrics (Prometheus)
├── moderation/ host controls, permission checks
├── participant/ per-peer state + REST listing
├── reactions/ emoji reaction validation + throttling
├── screen-share/ single-presenter enforcement
├── utils/ WS payload validation, rate limiting
├── websocket/ shared signaling core + /meetings gateway
└── workers/ mediasoup worker pool