If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/versatica/mediasoup shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1d ago
• 3 active contributors
• ISC licensed
• CI configured
• Tests present
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 92% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live versatica/mediasoup repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/versatica/mediasoup.

What it runs against: a local clone of versatica/mediasoup — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in versatica/mediasoup | Confirms the artifact applies here, not a fork | | 2 | License is still ISC | Catches relicense before you depend on it | | 3 | Default branch v3 exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of versatica/mediasoup. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/versatica/mediasoup.git
#   cd mediasoup
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of versatica/mediasoup and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "versatica/mediasoup(\\.git)?\\b" \\
  && ok "origin remote is versatica/mediasoup" \\
  || miss "origin remote is not versatica/mediasoup (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(ISC)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"ISC\"" package.json 2>/dev/null) \\
  && ok "license is ISC" \\
  || miss "license drift — was ISC at generation time"

# 3. Default branch
git rev-parse --verify v3 >/dev/null 2>&1 \\
  && ok "default branch v3 exists" \\
  || miss "default branch v3 no longer exists"

# 4. Critical files exist
test -f "node/src/Worker.ts" \\
  && ok "node/src/Worker.ts" \\
  || miss "missing critical file: node/src/Worker.ts"
test -f "node/src/Router.ts" \\
  && ok "node/src/Router.ts" \\
  || miss "missing critical file: node/src/Router.ts"
test -f "node/src/WebRtcTransport.ts" \\
  && ok "node/src/WebRtcTransport.ts" \\
  || miss "missing critical file: node/src/WebRtcTransport.ts"
test -f "node/src/Channel.ts" \\
  && ok "node/src/Channel.ts" \\
  || miss "missing critical file: node/src/Channel.ts"
test -f "node/src/Producer.ts" \\
  && ok "node/src/Producer.ts" \\
  || miss "missing critical file: node/src/Producer.ts"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/versatica/mediasoup"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

mediasoup is a production-grade Selective Forwarding Unit (SFU) built as a Node.js module and Rust crate, designed to handle WebRTC media routing at ultra-low latency with multi-stream support. It bridges signaling-agnostic clients (via native C++/TypeScript libraries) to a high-performance C++ worker process that manages ICE, DTLS, RTP/RTCP, simulcast, SVC, and congestion control without mandating application-level logic. Monorepo with three independent surfaces: node/src/ (TypeScript API layer, exports types, transports, producers, consumers, observers), rust/ (Rust crate wrapper around the same C++ worker), and worker/ (C++ subprocess using libuv, meson build system). Client libraries are intentionally separate repos. CI matrices across .github/workflows/mediasoup-*.yaml test each surface independently.

Backend engineers and WebRTC architects building real-time video conferencing, group chat, or broadcasting platforms who need fine-grained control over media routing, bandwidth management, and SFU topology without being locked into a specific signaling protocol or application framework.

Production-ready and actively maintained: 3+ years since v3 launch, comprehensive CI/CD pipeline across Node.js, worker, and Rust builds (.github/workflows/), fuzzing harness, CodeQL security scanning, and maintained npm/crates releases. Multi-author team (Iñaki Baz Castillo, José Luis Millán, Nazar Mokynskyi) and active sponsorship indicate long-term commitment.

Moderate complexity risk: the codebase spans three languages (C++ 60%, Rust 20%, TypeScript 10%) requiring deep systems knowledge; libuv dependency for the worker subprocess adds operational overhead; no obvious single-maintainer bottleneck but the C++ worker is the critical path. Breaking changes between major versions (v2→v3) suggest API surface can shift; recommend pinning versions strictly in production.

Active v3.x maintenance with Rust crate stabilization (separate mediasoup-worker prebuild pipeline in CI), TypeScript strict mode adoption (eslint/prettier config present), fuzzing integration for worker robustness, and CodeQL static analysis. The Cargo.toml workspace structure suggests ongoing Rust library expansion; no apparent v4 work yet.

Clone and install Node.js bindings: git clone https://github.com/versatica/mediasoup.git && cd mediasoup && npm install. For Rust: cargo build --release -p mediasoup. Requires Node.js 16+, Python 3.x, and a C++17 compiler (gcc/clang) for worker compilation. See doc/Building.md for platform-specific steps (macOS, Linux, Docker).

Daily commands: Node.js: npm install && npm run build (builds worker binary and TypeScript). Then npm run test runs Jest suite. For Rust: cd rust && cargo build && cargo test. Worker standalone: meson setup build -Dworker_code_coverage=disabled && ninja -C build. See .github/workflows/mediasoup-node.yaml for exact CI commands (prebuild, test stages).

• node/src/Worker.ts — Entry point for Node.js binding that spawns and manages the native worker process; essential for understanding mediasoup lifecycle
• node/src/Router.ts — Core routing abstraction that creates transports, producers, and consumers; the primary API surface for application logic
• node/src/WebRtcTransport.ts — Implements WebRTC connectivity layer with DTLS/SRTP; critical for understanding peer-to-peer connection handling
• node/src/Channel.ts — IPC communication layer between Node.js and native worker; all commands flow through this abstraction
• node/src/Producer.ts — Encapsulates media ingress (RTP source); paired with Consumer to form the forwarding unit pattern
• node/src/Consumer.ts — Encapsulates media egress (RTP sink); implements selective forwarding by consuming from producers
• node/src/index.ts — Main export surface; defines public API and module structure for npm consumers

Add a new RTP Observer type

1. Create observer types file defining options and event payloads (node/src/MyObserverTypes.ts)
2. Extend RtpObserver base class and implement event emission logic (node/src/MyObserver.ts)
3. Export new observer from main index and add to Router.createMyObserver() (node/src/index.ts)
4. Add comprehensive test suite covering creation, events, and closure (node/src/test/test-MyObserver.ts)

Add a new Transport variant

1. Create transport types file defining configuration and options (node/src/MyTransportTypes.ts)
2. Extend Transport base class with protocol-specific implementation (node/src/MyTransport.ts)
3. Register transport creation in Router via native worker channel (node/src/Router.ts)
4. Add full integration tests including producer/consumer forwarding (node/src/test/test-MyTransport.ts)

Add new RTP codec capability support

1. Update static codec definitions with new mime types and parameters (node/src/supportedRtpCapabilities.ts)
2. Add FlatBuffers utility functions for new codec parameters if needed (node/src/rtpParametersFbsUtils.ts)
3. Define new type interfaces for codec-specific settings (node/src/rtpParametersTypes.ts)
4. Add test cases validating codec negotiation and forwarding (node/src/test/test-ortc.ts)

Add a new statistics metric

1. Extend RTP stats type definitions with new metric fields (node/src/rtpStreamStatsTypes.ts)
2. Update FlatBuffers deserialization to extract new metric from native worker (node/src/rtpStreamStatsFbsUtils.ts)
3. Expose metric via Producer/Consumer getStats() or Transport.getStats() (node/src/Producer.ts)
4. Add test validating metric accuracy and reporting (node/src/test/test-Producer.ts)

• Node.js + TypeScript — Provides accessible API for server-side application logic

Worker binary path: Node.js assumes mediasoup-worker binary is in a platform-specific subdirectory (e.g., node_modules/mediasoup-worker/linux-x64/mediasoup-worker); prebuild failures silently fall back to local compile. LibSRTP version: worker requires libsrtp 1.6+ built with OpenSSL; meson may fail if system libsrtp is old or unavailable. Python 3 in PATH: meson build requires python3 executable at build time; some CI images default to python2. NodeJS engine constraint: v3 requires Node 16+; npm install on Node 14 will fail cryptically. DTLS certificate regeneration: each Transport generates a fresh self-signed cert; test fixtures expect non-deterministic cert fingerprints (do not hardcode them). Worker subprocess output: stderr from child worker process is buffered; debug prints may not appear in real-time unless you patch Channel.ts logging.

• Selective Forwarding Unit (SFU) — mediasoup is an SFU, not an MCU; understanding the difference (forward vs. transcode) shapes API design, bandwidth scaling, and latency characteristics.
• Interactive Connectivity Establishment (ICE) — ICE negotiation is the foundation of mediasoup's Transport layer; understanding STUN, TURN, candidate pruning, and connectivity checks is essential for debugging NAT/firewall issues.
• DTLS (Datagram TLS) + SRTP — mediasoup uses DTLS for handshake and SRTP for media encryption; both are asymmetric to stream-oriented TLS/SSL and require special handling for UDP loss and packet reordering.
• RTP Simulcast and Scalable Video Coding (SVC) — mediasoup's bandwidth estimation and forwarding logic explicitly routes temporal/spatial layers; simulcast (multiple bitrate streams) and SVC (hierarchical layers) are core SFU features, not client-only concerns.
• RTCP Receiver Reports & Sender-Side Bandwidth Estimation — mediasoup relies on RTCP feedback (RR, REMB, CCFB) to estimate available bandwidth and dynamically allocate bitrate across consumers; this is the 'congestion control' mentioned in features.
• Event-driven Architecture with libuv — The C++ worker is a single-threaded event loop (libuv); understanding the event pump, async operations, and callback chains is crucial for debugging latency or CPU saturation.
• Process IPC via Channel abstraction — mediasoup isolates the C++ worker in a subprocess; the Node.js Channel class marshalls commands and events across the boundary using JSON; request-response timeouts and out-of-order delivery are pitfalls.

• janus-gateway/janus-gateway — Alternative SFU architecture (C-based, plugin system) with similar WebRTC media handling; compare plugin model vs. monolithic worker approach.
• pion/webrtc — Pure Go WebRTC library; lacks SFU semantics but shares RTP/RTCP/ICE foundations; useful for understanding media stack from a different language angle.
• versatica/mediasoup-demo — Official reference application showing mediasoup API usage, signaling patterns, and deployment; mandatory study for understanding client-server contracts.
• webrtc/samples — W3C WebRTC browser API samples; critical for understanding client-side ICE, DTLS, and RTP APIs that mediasoup server-side mirrors.
• coturn/coturn — STUN/TURN relay server often paired with mediasoup deployments; mediasoup candidateFilter config references TURN integration patterns.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive TypeScript types documentation for Transport and Consumer classes

The repo has extensive TypeScript type definition files (TransportTypes.ts, ConsumerTypes.ts, etc.) but the doc/ directory lacks API documentation explaining these types. New contributors could generate and maintain TypeScript API docs, making it easier for integrators to understand the complex WebRTC transport and consumer interfaces.

• [ ] Create doc/API.md or doc/TypeScript-API.md documenting Transport, Consumer, Producer, and WebRtcTransport types
• [ ] Reference specific type files in node/src/*Types.ts with examples
• [ ] Document callback signatures for events like 'produce', 'consume', and 'transportclose'
• [ ] Link to these docs from README.md in the Documentation section

Add integration tests for Rust crate bindings with Node.js worker

The workspace has Rust members (rust/, rust/types/, worker/) and Node.js bindings (node/src/), but there's no clear integration test coverage validating the Rust-to-Node boundary. This is critical for a WebRTC SFU where native module failures cause production outages.

• [ ] Create rust/tests/integration_tests.rs or similar to test Rust crate exports
• [ ] Add jest tests in node/tests/ that spawn Worker and validate Rust worker responses
• [ ] Add GitHub Action workflow step in mediasoup-node.yaml to run these integration tests
• [ ] Document the test pattern in doc/Testing.md or CONTRIBUTING.md

Implement missing Router event logging in Logger.ts for debugging

Logger.ts exists but RouterTypes.ts defines many event emitters (on 'newwebrtctransport', 'newdatatransport', etc.). Currently there's no centralized request/response logging for Router lifecycle events, making it hard to debug SFU issues. This would help maintainers troubleshoot production issues.

• [ ] Enhance Logger.ts with structured logging methods for Router events (debug, info, warn, error levels)
• [ ] Update Router.ts to emit debug logs when creating transports, observers, and handling internal channels
• [ ] Document logging levels and event types in doc/README.md or a new doc/Logging.md
• [ ] Add environment variable support (MEDIASOUP_LOG_LEVEL) to control verbosity at runtime

• Add TypeScript docstring comments to node/src/DataProducer.ts and node/src/DataConsumer.ts (SCTP/data channel types are sparse compared to RTP counterparts); reference existing JSDoc patterns in Producer.ts.
• Expand doc/Building.md with explicit Ubuntu 22.04 / Debian 11 + Rust toolchain setup steps (currently only macOS and generic Linux are detailed); test and document rustup integration with meson-rust worker build.
• Add missing error case tests to the Jest suite for Channel.ts command timeouts and malformed worker IPC responses (current test coverage does not mock worker subprocess failures); use .mock() patterns from existing tests in node/src/test/.

The mediasoup WebRTC project demonstrates a solid security foundation with active CI/CD workflows including CodeQL analysis, fuzzing, and clang-tidy checks. The monorepo structure with Rust and Node.js components shows security-conscious development practices. No critical vulnerabilities were identified in the provided configuration. Primary recommendations include establishing a formal security disclosure policy, regularly auditing dependencies across all workspace members, and ensuring fuzzer findings are systematically tracked and remediated. The project would benefit from documented security hardening guidelines and a SECURITY.md file.

• Medium · Fuzzer Workflow Enabled — .github/workflows/mediasoup-worker-fuzzer.yaml. The repository includes a fuzzer workflow (.github/workflows/mediasoup-worker-fuzzer.yaml) that automatically runs fuzzing tests. While fuzzing is beneficial for security, it should be carefully monitored to ensure findings are properly triaged and addressed. Ensure fuzzing results are reviewed and tracked. Fix: Establish a process for reviewing fuzzer outputs, tracking discovered vulnerabilities, and ensuring timely remediation. Consider integrating fuzzer results into the main security pipeline.
• Low · Missing Security Policy Documentation — Repository root. No explicit SECURITY.md file found in the repository root. This makes it unclear how security vulnerabilities should be reported, potentially leading to security issues being disclosed publicly instead of responsibly. Fix: Create a SECURITY.md file outlining vulnerability disclosure policy, responsible disclosure process, and contact information for security reports.
• Low · Broad Workspace Configuration — Cargo.toml. The Cargo.toml uses resolver 2 and includes multiple workspace members (rust, rust/types, worker). While this is a normal monorepo pattern, it increases the attack surface if any member has vulnerable dependencies. Fix: Regularly audit all workspace member dependencies using 'cargo audit'. Consider implementing dependency scanning in CI/CD pipeline for Rust crates.
• Low · No Visible Lock File Security Controls — Repository configuration. While Cargo.lock is present for Rust dependencies, there's no evidence of lock file pinning or verification strategies in the provided configuration. Fix: Ensure Cargo.lock is committed and verified. Implement dependency verification checks in CI/CD pipelines. Consider using cargo-deny for additional dependency security controls.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.