wireweave 0.3.46 → 0.3.48

package/README.md

@@ -151,6 +151,31 @@ voice.addEventListener('participants', e => console.log(e.detail.list));
 
 Voice carries every empirically-discovered reliability pattern: perfect negotiation (RFC 8840), ICE restart on disconnect, track-stall detection, SFU hub election (mesh→star at 3+ peers), exponential-backoff reconnect.
 
+### voice quality/input settings
+
+`VoiceSession` (and `ensureVoice`) accepts real, constructor-configurable options for input mode, mic sensitivity, echo/noise handling, and Opus quality — every one of them threaded into an actual `getUserMedia`/`RTCRtpSender`/SDP call site, not just stored:
+
+```js
+const voice = ww.ensureVoice({
+  serverId: 'abc:xyz',
+  displayName: 'you',
+  pttMode: true,              // push-to-talk (default) vs. open-mic/VAD mode
+  micSensitivity: 0.045,      // RMS threshold the speaker-activity detector uses
+  noiseSuppression: true,     // getUserMedia audio constraints — real MediaTrackConstraints
+  echoCancellation: true,
+  autoGainControl: true,
+  audioQuality: 'high',       // Opus bitrate tier: 'low' (16kbps) | 'medium' (32kbps) | 'high' (48kbps) | 'max' (64kbps)
+  dtx: true                   // discontinuous transmission (silence suppression), SDP fmtp usedtx=1
+});
+```
+
+- **`pttMode`** (push-to-talk vs. voice-activity/open-mic): `true` (default) starts the session muted; the caller opens the mic via `setMuted(false)`/`requestTransmit()`. `false` starts unmuted — the mic stays live and the speaker-activity detector (RMS threshold) drives the `isSpeaking` UI flag instead of gating transmission. Live-togglable: `voice.setPttMode(false)`.
+- **`micSensitivity`** — the RMS level (0–1) above which a stream counts as "speaking" in the speaker-activity poller. Live-togglable: `voice.setMicSensitivity(0.09)`.
+- **`noiseSuppression` / `echoCancellation` / `autoGainControl`** — real [`MediaTrackConstraints`](https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints) passed straight into the `getUserMedia({ audio: {...} })` call `connect()` makes.
+- **`audioQuality`** — an Opus bitrate ladder tier (`low`/`medium`/`high`/`max`, mapping to 16/32/48/64 kbps) applied via the real `RTCRtpSender.setParameters()` call on every connected peer's audio sender. Live-togglable and re-applies immediately to every open connection: `voice.setAudioQuality('low')`.
+- **`dtx`** — discontinuous transmission (silence suppression), negotiated per the real WebRTC spec via the Opus `a=fmtp` SDP line (`usedtx=1`), not an `RTCRtpEncodingParameters` field (that isn't where DTX lives in the real spec). Applied at every offer/answer/ICE-restart. Live-togglable: `voice.setDtx(false)` (takes effect on the next SDP exchange for already-open peers).
+- **Per-room bandwidth shaping for large rooms** — this module is audio-only (no video sender exists anywhere in it), so real per-layer RTP simulcast (which is video-only in every browser implementation) doesn't apply. The honest, reachable analog is what's already built: SFU hub election (`_sfuElect`/`_sfuRankCandidates`) picks the highest-uplink participant as the hub and fans out audio to everyone via zero-copy `replaceTrack`, so bandwidth concentrates on whoever the room is actually routing through, combined with the per-connection Opus bitrate ladder above.
+
 ## node usage (relay + auth only)
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wireweave",
-  "version": "0.3.46",
+  "version": "0.3.48",
   "description": "nostr + webrtc voice + data SDK. networking layer for 247420 projects.",
   "type": "module",
   "main": "./src/index.js",

package/src/relay-pool.js

@@ -64,7 +64,15 @@ class RelayHealth {
     this.rank = 50;
   }
 
-  recordConnectAttempt() { this.attempts++; }
+  // Recomputes rank on every attempt, not just on a successful signal —
+  // otherwise a relay that NEVER once connects (rank frozen at the ctor's
+  // neutral 50 forever, since recordConnectLatency/recordSustainedConnection/
+  // recordEoseLatency — the only other rank-recomputing call sites — never
+  // fire for it) reads as perpetually "average" no matter how many failed
+  // attempts pile up, defeating both healthReport() ranking and
+  // _maybeRotate's rank-gap rotation trigger for the exact "never connects
+  // at all" relay auto-rotation exists to route around.
+  recordConnectAttempt() { this.attempts++; this.rank = computeRank(this); }
 
   recordConnectLatency(ms) {
     this.connectLatencyMs = ewma(this.connectLatencyMs, ms);
@@ -250,7 +258,13 @@ export class RelayPool extends EventTarget {
   // Swap the worst currently-active relay for the best-ranked unused
   // candidate (fallback pool, or a previously-tried relay we disconnected
   // from) when the gap is large enough to be worth the churn of a new
-  // connection. Never rotates below MIN_ACTIVE_RELAYS active URLs.
+  // connection. Never rotates below MIN_ACTIVE_RELAYS active URLs. Called
+  // from every ws.onclose (both the sustained-then-dropped branch AND the
+  // never-connected/failed-fast branch) — a relay that never manages to
+  // connect at all still needs evaluating here, since that IS the
+  // "consistently unhealthy" case rotation exists to route around, and its
+  // rank already reflects the failures via recordConnectAttempt's own
+  // computeRank call once attempts >= 2 (the sample floor enforced below).
   _maybeRotate() {
     if (!this.autoRotate || this._closed) return;
     const MIN_ACTIVE_RELAYS = 2;
@@ -378,11 +392,17 @@ export class RelayPool extends EventTarget {
         relay.reconnectDelay = 1000;
         health.recordSustainedConnection();
         this._scheduleSaveHealth();
-        this._maybeRotate();
       } else {
         relay.failCount++;
         relay.reconnectDelay = Math.min(relay.reconnectDelay * 2, 30000);
       }
+      // Evaluate rotation on EVERY close, not just a sustained-then-dropped
+      // connection — a relay that never manages to connect at all (the
+      // `else` branch above) is exactly the "consistently unhealthy"
+      // relay auto-rotation exists to route around, and its rank already
+      // reflects that via computeRank's uptime/latency components once
+      // `attempts >= 2` (the sample floor _maybeRotate itself enforces).
+      this._maybeRotate();
       relay._openedAt = null;
       if (this._closed) return;
       const t = setTimeout(() => this._open(url), jitter(relay.reconnectDelay));