Deep-research validation of the decisions in WATTROOM.md, run 2026-07-16. Three research passes: domain tech (107 agents, 25 claims adversarially verified 3–0), dev tooling & CI (105 agents, 24 claims verified 3–0), and a gap-fill pass (in flight — see §8). Confidence tiers: verified = survived 3-vote adversarial verification against primary sources; extracted = sourced claim from the research pass, not adversarially verified.
Every run here predates ADR-0058 (2026-09-22), which took the room apart, and describes the product as it was researched. Where a section says room, read the session for riding, the voice channel for a call or a deck, and the crew for membership, identity or a door.
Verified:
- Web Bluetooth ships on Chromium only: Chrome 70+/Edge 79+ on Windows (10 1703+), macOS, Android 6+. Safari/WebKit: "not supported and no plan to support it." No native iOS path exists. (implementation-status, caniuse ~76% global, Chromium-only)
- FTMS v1.0 (still current) has exactly our two control procedures: Set Target Power (0x05), SINT16 watts, 1 W resolution; Set Indoor Bike Simulation (0x11), 6-byte payload — wind SINT16 @0.001 m/s, grade SINT16 @0.01 % (signed percentage), Crr UINT8 @0.0001, Cw UINT8 @0.01 kg/m. (FTMS v1.0 spec, corroborated by Auuki/pycycling/SmartSpin2k)
- Live ERG↔slope switching is spec-legal: one Request Control (0x00) grant covers all procedures until disconnect; contradicting ops are last-write-wins. But: every procedure completes via indicated Response Code (0x80), and a write during an in-progress procedure errors un-queued → the FTMS layer must serialize control-point writes behind each indication.
- Auuki is AGPL-3.0, actively maintained (pushed 2026-03). Its BLE layout is the reference pattern:
src/ble/with one folder per GATT service (ftms/, wcps/ Wahoo, fec/ Tacx FE-C, hrs/, cps/, cscs/, bas/) over shared connection primitives. It implements proprietary fallbacks because FTMS alone leaves real trainers uncontrollable — pre-2020 Wahoo lack FTMS, Tacx NEO exposes only FE-C.
Consequences applied to the doc: control-point write queue is mandatory; WCPS fallback is the named escape hatch (Kickr v2 test unit may need it — gap-fill pass verifying); Auuki is read-reference only.
Verified:
- Licensing clean: server Apache-2.0 (Go/Pion), Go server SDK
github.com/livekit/server-sdk-go/v2Apache-2.0, v2.18.1 published 2026-07-15, active cadence. Token minting lives ingithub.com/livekit/protocol/auth:NewAccessToken → SetVideoGrant (AddGrant deprecated) → ToJWT. - Deployment: Redis not required single-node (recommended for prod, required multi-node — split-brain otherwise). TURN is embedded (TURN/TLS 5349, TURN/UDP 443) — no coturn. Ports: 7880 WS signaling, 7881 WebRTC/TCP, UDP 50000–60000 media. k8s requires
hostNetwork: true(one pod per node) and direct firewall exposure; private/NAT-ed clusters unsupported. (deployment docs, k8s docs) - Capacity: LiveKit's benchmark sustains 150 pub × 150 sub (720p simulcast) at 85 % CPU on a 16-core c2-standard-16. A 12-rider room ≈ 132 forwarded streams — a small fraction of one node even at half the vendor numbers. One room must fit on one node (irrelevant at our size); scale = spread rooms across nodes.
- LiveKit server current: v1.13.3 (2026-07-03), ~monthly release cadence.
Consequences: Natron-cluster deploy must budget hostNetwork + UDP exposure on node IPs — this is the ops constraint to check against the shared-cluster decision before alpha widens.
Verified against RMF (updated 2026-04-28) + Developer Policies:
- No overlays/frames/visual elements in front of any part of the embedded player, including controls.
- Player viewport ≥ 200×200 px, cannot be shrunk or hidden.
- No programmatic playback until >50 % of the player is visible on screen.
- Policies III.I.7/III.I.9: no separating audio from video, no background players → audio-only jukebox mode is prohibited.
Applied to the doc: jukebox = dedicated always-visible ≥200×200 tile, nothing overlaid, auto-advance only while visible, no audio-only mode. Whether multi-client synchronized playback itself is compliant was not settled — gap-fill pass researching how Watch2Gether-class apps survive.
- Nov 2024 API agreement: third-party apps may only display a user's Strava data to that user; bans Strava data in AI/ML models. Upload-only usage (our case) appears unaffected; never display Strava-pulled data to other room members. (Strava press, DC Rainmaker) — gap-fill pass verifying upload mechanics, rate limits, VirtualRide conventions.
- .fit encoding in Go: muktihari/fit — actively maintained (v0.28.1, 2026-05-20, 93 releases); tormoder/fit unmaintained since Sept 2024, its README points to muktihari/fit.
- WebSocket: coder/websocket — gorilla/websocket is archived; coder/websocket is maintained, context-aware, safe concurrent writes. (websocket.org guide)
- goose v3.27.2 (2026-06-30):
validatecommand = CI migration lint; hybrid workflow (timestamped in dev,goose fix→ sequential in CI); supports go:embed self-migrating binary. - sqlc + pgx v5 remain the standard pairing (sqlc docs first-class pgx support).
| Thing | Pin | Note |
|---|---|---|
| Go | 1.26.x (1.26.5, 2026-07-07) | Air requires ≥1.25 |
| SvelteKit | ≥2.68 | config now passable via Vite plugin; scaffold with sv create (sv@0.16) |
| Vitest | 4.x (4.1.10) | browser mode stable; vitest-browser-svelte is first-party for Svelte 5 |
| Playwright | ~1.61 | official CI image v1.61.0-noble; checkout@v5/setup-node@v6; don't cache browser binaries (restore ≈ download time) |
| golangci-lint | v2.12.x | v2 YAML config; golangci-lint migrate exists for v1 configs |
| goose | v3.27.x | extracted tier |
| LiveKit server | v1.13.3 | monthly cadence, and no bot watches it — the tag is written into docker-compose.yml, deploy/docker-compose.prod.yml and e2e.yml by hand (see §7) |
| livekit server-sdk-go | v2.18.x + livekit/protocol for auth | |
| CloudNativePG | 1.30.x (2026-06-29) | PG major version support: check CNPG docs at scaffold (releases page doesn't state it) |
| PostgreSQL | 18 (via CNPG) | inference: PG18 GA since 2025-09; verify against CNPG 1.30 support matrix |
| Node / pnpm / Tailwind / TS | Node 24 LTS, pnpm 10, Tailwind v4, TS current | knowledge-cutoff tier — confirm at scaffold |
Local loop:
- Go hot reload: Air (v1.65.3, 2026-05-21; ~24k stars, dominant over wgo).
- Topology: Vite dev server in front, proxying to Go —
server.proxywithws: truehandles the room WebSocket; one/apiprefix key routes REST. - Containers: Postgres + LiveKit in compose; run Go (air) and Vite natively for sub-second iteration. Compose Watch only helps for locally-built services (sync for Vite, rebuild for Go) — native + proxy is simpler. Tilt/Skaffold: overkill at 2 services.
Testing:
- Goroutine-heavy hub code:
testing/synctest(Go 1.24+, experimental) — fake clock advances when all goroutines block; interval-timer and tick-coalescing tests run instantly and deterministically. Made for exactly our room hub. - DB integration: testcontainers-go Postgres module —
WithInitScriptsfor goose migrations/seed, snapshot/restore for fast per-test resets (don't name the container DBpostgres), set an explicit wait strategy (log + port) or CI flakes. - Race detector on in CI; golden-file tests for .fit output.
- Svelte 5 components: Vitest browser mode + vitest-browser-svelte (first-party).
CI/CD:
- Actions: checkout@v5, setup-node@v6, upload-artifact@v5 (per Playwright's current docs); setup-go built-in caching; pnpm needs explicit store caching keyed on pnpm-lock.yaml.
Renovate over Dependabot: 90+ ecosystems incl. Docker Compose, k8s manifests, Helm; built-in automerge; regex managers for versions embedded in Dockerfiles/CI — all present in this repo.Reversed 2026-09-17 (#2343, ADR-0054) — every reason above still holds, and none of it happened. Renovate is a GitHub App:
renovate.jsonwas committed with the first CI workflow, #9 asked someone to install the app, and two months latergh pr list --author app/renovate --state allwas still empty. A bot that opens no pull requests has no feature set. Dependabot is activated by a file on the default branch and nothing else, which is a thing this repo's own contributors and agents can actually ship — it is.github/dependabot.ymlnow, andrenovate.jsonis gone rather than kept beside it, because two bots means two PRs per bump. What was genuinely given up is the last item on the list: nothing watches a version embedded in a Dockerfile or a workflow any more, so the LiveKit pin above and the Dockerfile'snode:/golang:build stages are a human's edit. Worth revisiting if anyone installs the app.- Load testing: k6
k6/websocketsmodule (living-standard API; older k6/experimental/websockets deprecated); VU = long-lived socket with event loop — fits a riders×rooms telemetry simulation; assert on HTTP 101. - Deploy proportionality (extracted, opinion-tier): Kustomize > Helm for own services; ArgoCD threshold ≈ >3 environments — plain apply from CI is proportionate for alpha. Staging = a namespace; PR preview deploys not worth it at this scale.
The workflow pass for these areas was killed three times by transient API overload; researched inline instead.
Kickr FTMS reality:
- FTMS arrived via firmware in 2021: Kickr Core fw 1.1.1 (2021-06-01), Kickr v5 fw 4.2.1/4.2.3 (2021). (Core release notes, v5 notes)
- Kickr v2 (2016) has its own firmware line with no FTMS mention (v2 notes) — presume WCPS-only. Definitive answer is one GATT service enumeration away: M0's first hardware session must enumerate services on the v2; if no FTMS, the WCPS module moves from "later" to M1.
- Smoking gun for sprint switching: Kickr Core fw 1.4.8 (2024-03-05) fixed a "2000 watt power spike when switching between ERG/SIM" — the exact transition sprint moments perform. Consequence: require/recommend current trainer firmware, and ramp the slope-mode entry gently rather than assuming a clean switch.
Testing without hardware:
- Chromium has a CDP BluetoothEmulation domain (FakeBluetooth backend) used by Web Platform Tests (Chromium bluetooth test docs), but Playwright does not expose it as a supported API in 2026.
- Practical answer (as planned): dependency-injected BLE layer — the app's trainer interface has a
SimulatedTrainerimplementation (models: first-order power lag toward target, cadence, gaussian noise, optional dropout injection) selectable via dev flag. Playwright drives the app with the simulator; no real Bluetooth in CI. Hardware-side emulators (ESP32ftms_emu) exist for bench testing real Web Bluetooth paths, optional.
WS schema codegen — winner: Go-first with tygo.
- The Go structs (which the server already needs) are the single source of truth; tygo emits TypeScript interfaces from them in CI. One tool, no schema files, satisfies the "defined once, both sides generated" decision with the least machinery.
- Alternative if runtime validation from schema becomes needed: JSON Schema files → json-schema-to-typescript + go-jsonschema; Google shipped an official jsonschema-go package (Jan 2026) for validation.
Watch-together sync mechanics:
- Standard architecture matches ours: server/host is the clock authority issuing authoritative PlaybackState snapshots; clients chase. State-of-practice drift correction is tiered: small drift → nudge
playbackRate(soft-sync, imperceptible), large drift (~>2 s) → hardseekTo. ~200 ms cross-client alignment is achievable. (soft-sync architecture, SyncTube, ViewSync) - No TOS findings against coordinated play/pause/seek itself beyond the RMF rules already in the doc; Watch2Gether/SyncTube-class apps operate openly on the IFrame API. Their pain point is embed-disabled music content (labels/Vevo) — mitigate by resolving queue entries via Data API and surfacing "not embeddable" before playback. Quota note (knowledge tier):
search.listcosts 100 units of the 10k/day default — prefer paste-a-URL +videos.list(1 unit) over in-app search for MVP.
Strava upload path:
- Upload =
POST /uploadswithactivity:writescope, .fit is the native format (FIT_FILE_TYPE=4), async processing with status polling. (uploads docs) - New apps start in "Single Player Mode" (athlete capacity 1); the Standard Tier covers up to 10 users without application review; Extended Access (review required) for more. Default rate limits 200 req/15 min, 2 000/day. (rate limits, API FAQ)
- This maps perfectly onto the alpha plan: your own circle fits the ≤10 Standard Tier with no review; Extended Access review only becomes necessary when widening. Upload-only usage doesn't touch the Nov-2024 display restrictions.
The actual alpha hardware: one Kickr Core (FTMS since fw 1.1.1) and friends on Kickr v2 (2016). The v2 predates FTMS and never received it — it's controlled via Wahoo's proprietary BLE protocol (WCPS): an unlisted characteristic A026E005-0A7D-4AB3-97FA-F1500F9FEB8B hanging off the standard Cycling Power Service (0x1818). Undocumented by Wahoo; protocol facts recovered from open implementations (Auuki src/ble/wcps, GoldenCheetah PR #3472, sensors-swift-trainers). Zwift/TrainerRoad controlled the v2 this way for years — it's proprietary but battle-tested.
WCPS protocol (facts, from reference implementations — write our own code):
| Command | Op | Payload (little-endian) |
|---|---|---|
| Unlock (required first) | 0x20 | [0x20, 0xEE, 0xFC] |
| Set ERG power | 0x42 | uint16 watts, 1 W resolution |
| SIM mode params | 0x43 | weight ×0.01 kg, Crr ×0.0001, wind resistance ×0.001 kg/m |
| Grade | 0x46 | (grade/100 + 1) × 32768, −100…+100 % |
| Wind speed | 0x47 | (v + 32.768) × 1000 m/s |
| Load level / intensity | 0x41 / 0x40 | level 0–9 / (1 − x) × 16383 |
| Wheel circumference | 0x48 | ×0.1 mm |
Responses arrive as notifications: [status (0x01 ok), request op, type, …] — so WCPS writes get the same serialized-behind-response queue as FTMS.
Driver architecture (client):
Trainer interface: setTargetPower(w) · setSim(grade) · streams(power, cadence, speed)
├─ FtmsTrainer (0x1826: Set Target Power 0x05 / Indoor Bike Sim 0x11, Indoor Bike Data)
├─ WcpsTrainer (0x1818 + A026E005: unlock → 0x42 ERG / 0x43+0x46 sim-grade, data from CPS 0x2A63)
└─ SimulatedTrainer (dev/CI)
- Detection:
requestDevicefilters on services[0x1826, 0x1818]with both inoptionalServices(Web Bluetooth only exposes pre-declared services). After connect: FTMS present → FtmsTrainer; else CPS + Wahoo characteristic → WcpsTrainer. The Kickr Core exposes both — prefer FTMS. - Sprint moments work on both: FTMS flips 0x05↔0x11; WCPS flips 0x42↔0x46 (with 0x43 sim params set once at session start). Same rider UX, two encodings.
- Data: Core streams power+cadence via FTMS Indoor Bike Data; v2 streams power via standard Cycling Power Measurement (0x2A63). The 2016 v2 does not reliably provide cadence — v2 riders pair a BLE cadence sensor (CSC profile, already in scope). The spiral-of-death guard must degrade gracefully when cadence is absent (fall back to power-collapse detection).
- Spindown/calibration: proprietary on the v2 — defer to the Wahoo app for both trainers in MVP (standard practice among third-party apps).
- Licensing: protocol constants (UUIDs, op codes, scaling) are facts and fine to use; the WCPS driver is written fresh, no Auuki code copied.
Confirmed on hardware (2026-08-29, GATT dump on a second Kickr Core, fw 3.0.23, #43) — two identical dumps four minutes apart:
- FTMS and WCPS coexist on the same unit.
0x1826with Control Point (0x2AD9, write+indicate) and Indoor Bike Data (0x2AD2), anda026e005-…on0x1818. "The Kickr Core exposes both — prefer FTMS" was inference; it is now read off the device. - Supported Power Range (0x2AD8) = 0–2000 W, 1 W increment; Supported Resistance Range (0x2AD6) = 0–100, 1. Resolves the clamping debt below — and the driver now reads 0x2AD8 on connect and clamps every ERG target to it (#59), width-defensively per the 0x2A65 quirk. 0x2A65 itself is never read: the CPS driver decodes per-packet flags from 0x2A63, so the short read cannot bite unless someone adds a capability read later.
- Cadence is supported, asserted twice over: the FTMS Feature cadence bit (
0x2ACCmachine0x00004003) and the CPS crank-revolution bit (0x2A65→0x120e). A capability read — the sprint-to-soft-pedal dropout in §11 is still unobserved. - FTMS Feature targets
0x0000600c: Resistance, Power (ERG), Indoor Bike Simulation, Wheel Circumference. - The Zwift ZAP service is present on a Core (three characteristics: notify / writeNoResp / indicate). Says nothing about third-party usability — see §11 on virtual shifting.
Two quirks that will break a naive parser:
0x2A65(CPS Feature) returned 2 bytes, not the spec's uint32. The bits we want sit in the low half so nothing is lost, but a parser reading a fixed 4 bytes throws on this trainer. Read defensively.0x2AD3(Training Status) readsfb ff, which does not decode —0xfbis not a defined flags value and0xffnot a defined status. We do not parse it; do not start without checking a second unit.
This unit is the alpha hardware, and it undercuts §9's premise. The dump is from a colleague's trainer, and the team's colleagues ride KICKR CORE v2 — a different machine from the KICKR v2 (2016) this section was written about. Two similar names, two products: the 2016 v2 is the old flagship that predates FTMS; the CORE v2 is a current Core, and the dump shows it speaking FTMS with ERG and cadence.
So the actual alpha hardware is one Kickr Core plus several Kickr Core v2 — all FTMS. Nobody on the team owns a pre-FTMS Wahoo. That removes the justification for WcpsTrainer being M1 scope (WATTROOM.md line 105: "Alpha hardware = one Core + several v2s, so WCPS is M1 scope, not a fallback"), and with it the premise of #43 and #4.
Not re-decided here — it changes a locked doc, so it needs an ADR. The WCPS protocol map below stays either way: it is correct research, and it is what a rider who does bring a 2016 v2 would need.
- Zwift Cog / virtual shifting: irrelevant in ERG (trainer holds watts regardless of gear — the Cog works fine, as with TrainerRoad/MyWhoosh). In slope mode a Cog'd trainer is one fixed gear: virtual shifting is Zwift-proprietary (Click/Play pair only with the Zwift app; patented — US11986700/US12465816), no third-party API shipped yet despite announcements.
Consequence: sprint moments get a per-rider sprint-grade setting instead of shifting (#31); don't implement app-side virtual shifting unless the official API lands.(written 2026-07-22, struck 2026-09-29) Revised 2026-09-29 (#3322, ADR-0084): the claims were read from the USPTO full text on 2026-09-28. US 11,986,700 (filed 2021-12-31, granted 2024-05-21) needs, in every independent claim, a shift or braking made by "at least one rapid near-cessation of resistance"; a resistance per virtual gear is not claimed on its own. US 12,465,816 (filed 2023-06-13, granted 2025-11-11) claims a three-part link, the shape of Zwift's ZAP. Pending and not enforceable until granted: 18/640,559 (a '700 continuation: auto-shift, a countdown, a smooth transition), 18/334,110 (a separate gear-shifting device feeding a virtual world) and 19/360,268 (a '816 continuation); a grant with its published claims substantially unchanged can reach back to publication (35 USC §154(d)). No EP or CH right to virtual shifting is granted; EP4631586 and any further divisional of EP4205825 stay on watch. Prior art runs from ICON's US 2013/0059698 (2011) through the Wattbike Atom (2017), the Tacx NEO Bike and KICKR BIKE (2019) and Wahoo's US 2021/0060380 to qdomyos-zwift's app-side gears (2021). WattRoom ships virtual gears without a freedom-to-operate opinion (Jan, 2026-09-28), inside ADR-0084's hard rules (no resistance dip on a shift, no auto-shift or easing, no Zwift protocol), and checks the pending applications at the first release of each week (#3323). Not legal advice. (DC Rainmaker, Makinolo protocol analysis, Zwift Cog third-party guide)
YouTube IFrame API for the jukebox:
setPlaybackRaterounds unsupported rates toward 1 — a 1.03× nudge may silently become 1.0×. Gate ongetAvailablePlaybackRates(); onlyonPlaybackRateChangeconfirms. → SPEC revised to a seek-first design.seekToneedsallowSeekAhead=truefor unbuffered regions and may land on an earlier keyframe — always re-measure drift after a seek.- Blocked entries surface at play time via
onError: 100 removed/private, 101/150 embed-disallowed (150 also fires for some region/age cases), 153 missing referrer (new July 2025 — serve the embed with a proper referrer policy). - Reference implementation: OpenTogetherTube ships single-tier hard-seek at >1 s drift with 250 ms local dead-reckoning and no clock-offset estimation at all — the field gets away with much simpler than our spec assumed.
LiveKit JS SDK (v2.22.0, Aug 2026 — stable 2.x line, no migration risk):
- Ducking:
RoomEvent.ActiveSpeakersChanged(loudest-first, includes local participant) drives it;RemoteParticipant.setVolume(v, source)ducks specific sources;RoomOptions.webAudioMix(default false) routes all LiveKit audio through a caller-supplied AudioContext for one unified mixing graph with jukebox + SFX. adaptiveStreamanddynacastare both OFF by default — must be explicitly enabled; they're the core scaling levers for 12-rider rooms.publishDefaultsare a sound baseline (simulcast on, VP8+backup, music audio preset with DTX+RED, screenshare 1080p15).- Reconnect UX: distinct
Reconnecting(media interrupted → persistent dashboard status) vsSignalReconnecting(transparent) events;ConnectionQualityChangedcovers per-rider badges. - Tokens: the server proactively refreshes tokens for connected clients — Go only mints short-TTL join tokens (page reload still needs a fresh mint).
Web platform for the feel layer:
- One user gesture (the "join room" click) resumes a suspended AudioContext for all future SFX — hang the unlock there. The YouTube iframe additionally needs
allow="autoplay"delegation + prior domain interaction for unmuted starts. - Screen Wake Lock is Baseline since March 2025 — rely on it, but handle rejection (battery saver) and re-acquire on
visibilitychange.
Settled by doing (2026-08-29, #5/#47): the muktihari/fit message sequence Strava accepts for a synthetic VirtualRide. FileId → Record… → Lap → Session → Activity, sport=cycling, sub_sport=virtual_activity. Uploaded a synthetic 120-sample ride to Strava: accepted, classified as Virtual Ride, power/cadence/HR all parsed. Two conventions found: Strava derives elapsed time from record timestamps (N one-second samples read as N−1 s) and recomputes averages from records rather than trusting Session fields, so our summaries round the same way. filedef.Activity.ToFIT emits Session before Lap, which is why the encoder builds the sequence by hand. Distance/speed are not encoded and show as 0 km — fine for a VirtualRide, revisit with #34.
Settled by doing (2026-08-31, #286): fine-grained playbackRate on current embeds — a setPlaybackRate(1.05) on a live youtube-nocookie embed reads back as 1.05; setPlaybackRate(1.02) rounds to 1. So the documented "rounds unsupported rates toward 1" is real, but the floor sits near 0.05, not at the 0.25 steps getAvailablePlaybackRates() lists — fine enough for an inaudible drift-closing tier, which docs/SPEC.md now specifies. Also settled: clock sync is NOT optional for us. OTT gets away with none because it seeks on >1 s drift and never claims tighter; WattRoom's anchor is server millis added to the client's own Date.now(), so a skewed rider clock became a permanently wrong target no drift chase could recover. The tick's at is enough — max of the last 8 samples, no ping/pong.
Still open (no surviving claims — settle by doing): Go-side tick-layout patterns (→ decide in M2 implementation).
FTMS Indoor Bike Data (0x2AD2) parsing — the driver's core loop:
- Bit-0 is inverted: More Data = 0 means Instantaneous Speed IS present. And the spec's Table 4.10 prints bit-2 (cadence) inverted too — that's a known spec typo: real trainers set bit 2 = 1 with cadence included. Parse bit 0 inverted, bit 2 normal (qdomyos-zwift's battle-tested reading).
- Conditional fields in ascending bit order: speed (bit0), avg speed, cadence (bit2, half-rpm resolution), avg cadence, distance, resistance, power (bit6, SINT16), avg power, energy trio (bit8, sentinels 0xFFFF/0xFF = not available), HR (bit9), MET, elapsed, remaining. Notifications ~1 Hz, server-fixed.
- Control-point contract: completion indication is
[0x80, request-op, result]with results 0x01 Success … 0x05 Control Not Permitted; concurrent writes rejected at ATT level ("Procedure Already In Progress") — confirms the serialize-behind-indication design. Subscribe to Fitness Machine Status (0x2ADA) and re-Request-Control on its 0xFF (Control Permission Lost). - Spindown exists in-band (op 0x13 start/ignore; progress via 0x2ADA op 0x14 incl. "Stop Pedaling") but requires the 0x2ADA subscription — M1 defers calibration to the Wahoo app as planned; the flow is documented for later.
Kickr specifics:
- Kickr cadence is firmware-estimated (no sensor; added Sept 2019 to Kickr 2018/Core, initially FTMS-stream-only) and demonstrably drops out on sprint→easy transitions. Treat trainer cadence as low-trust; prefer a paired cadence/power-meter source — which matters for the spiral guard and Watt Golf.
- JetBlack Victory (a friend-of-friend likely target) is verified FTMS-conformant across apps — but has non-defeatable ERG power smoothing (reported power is smoothed): flag smoothed-power trainers in execution-score contexts.
Multi-source arbitration (TrainerRoad's mature pattern, adopt as-is): a paired power meter always wins display/record over the trainer; PowerMatch closes the loop by offsetting the ERG command by the measured meter↔trainer delta (default sensitivity 0.5). Cadence: dedicated sensor > power-meter crank data > trainer estimate.
Zwift accessories (reverse-engineered state):
- Play/Ride controllers expose proprietary service
00000001-19ca-4651-86e5-fa29dcdd09d1speaking protobuf "ZAP" messages; Ride-family button presses are message 0x23 with an active-low 32-bit bitmap.But the handshake/encryption story is unresolved (all three competing accounts refuted each other) — reading Click/Play buttons from Web Bluetooth is NOT currently viable to plan on. Sprint-grade-instead-of-shifting stands validated: virtual shifting runs on Zwift's closed per-agreement trainer protocol (Elite/JetBlack/Van Rysel firmware deals; SHIFTR/BikeControl exist precisely to bridge it).(written 2026-08-25, struck 2026-09-29) Revised 2026-09-29 (#3322, ADR-0084): the Play and Ride handshakes are documented (Makinolo, 2023-10-08 and 2024-07-26); Click v2 adds a daily unlock; OpenBikeControl exists as an open controller protocol (MIT, spec v1); and Rouvy has belonged to Zwift since 2026-04-29. WattRoom speaks none of Zwift's protocols. Its shift input is its own: the on-screen Easier / Harder pair, the keyboard, the rider's phone as a remote, and OpenBikeControl controllers over Web Bluetooth. Since then Click v2 and Ride v2 lock to Zwift's app daily, and a direct driver stays out: see §23 (2026-11-12). - Tacx NEO generation needs FE-C tunneled over BLE: service
6e40fec1-b5a3-f393-e0a9-e50e24dcca9e, FEC_TX…fec2notify / FEC_RX…fec3write (Nordic-UART framing of ANT+ FE-C pages; pycycling has a clean reference module). A futureFecTrainerdriver slots behind the sameTrainerinterface if a NEO owner joins. - Pre-2020 proprietary-BLE trainers: shipping apps simply declare them unsupported (ANT+-dongle advice doesn't transfer to Web Bluetooth). M1 support line = FTMS + WCPS is validated.
HR strap parsing (0x2A37): flags bit 0 selects UINT8 vs UINT16 heart rate; bit 4 signals RR intervals — a variable count of UINT16s fills the rest of the packet (loop, don't assume one; overflow continues next notification).
- Confirmed on hardware (Polar H10, 55 packets, 2026-08-29, #11): flags alternate
0x10(53 packets) and0x00(2) — the strap sends RR only when a beat fell in the notification window. Six packets carried two intervals, so the variable count is real at resting heart rate, not just under load; reading only the first would have dropped those beats while still displaying a correct bpm, which is a failure that never shows on screen. Bytes pinned as a regression test inweb/src/lib/ble/heartrate.test.ts. Energy expended (bit 3) was never set by this strap, so that skip stays unit-tested only. Note the H10's HR field is smoothed: it read 62 bpm while the instantaneous RR implied ~55 — expected, not a parse error.
Research debt (no surviving claims — resolve during driver work): 0x2A63 crank-revolution rollover math + stale-data thresholds, CSC 0x2A5B parsing, WCPS status/notification codes beyond the op table (capture real notifications during the #10 hardware session), Kickr ERG-smoothing specifics. Supported Power/Resistance Range (0x2AD8) reads for clamping — resolved, numbers in §9.
The road and gears numbers (research for #3351, run of 2026-10-25; ADR-0088 puts this in the Kickr sitting's place). Each feeds a row of docs/spec/roads.md "Route rides" or docs/spec/riding.md "Virtual gears".
- Drag convention: Cw is ρ·CdA. FTMS v1.0 (2017-02-14) §4.16.2.18, Table 4.20, defines the four fields of op 0x11 (wind SINT16 at 0.001 m/s, grade SINT16 at 0.01 %, Crr UINT8 at 0.0001, Cw UINT8 at 0.01 kg/m) and obliges the trainer to use them. It gives no force model. ANT+ FE-C defines the same kg/m coefficient as frontal area × drag coefficient × air density (Garmin Connect IQ,
AntPlus.SimulationSettings). FortiusANT, an open trainer bridge that speaks both FE-C and FTMS, reads FTMS's Cw into that coefficient and resists with ½·Cw·(v + wind)²; its default 0.51 kg/m is 1.275 × 0.40 × 1.0. The #10 Kickr Core rules out the other reading. Sent Cw 0.51 at 2 %, it averaged 209 W at 26.7–30.0 km/h, where Cw·v² as drag predicts about 410 W at 83 kg and ½·Cw·v² about 280 W. - Crr and Cw honoured. FTMS requires it, and no published report has a Kickr ignoring either field. P2a and P2b in HARDWARE-SESSIONS.md stay the way a rider's trainer can say otherwise.
- The trainer's mass. Op 0x11 carries none. The #43 dump shows no User Data Service among the Kickr Core's six services, and its Fitness Machine Features (
0x00004003) leave bit 16, User Data Retention, clear. So no FTMS client can give it a weight. It simulates the weight its maker's app gave it: Best Bike Split's trainer guide has KICKR riders set it in the Wahoo app (Sensors > Weight), and Wahoo forum users report 75 kg as the Wahoo apps' default. WCPS op 0x43 carries a weight, and WattRoom never sends it. m_t is therefore not a constant WattRoom can know. - Wheel circumference, op 0x12. FTMS §4.16.2.19 says only that the trainer takes the new value. The Kickr Core advertises it (Target Setting Features
0x0000600c, bit 14). Rider reports on the TrainerRoad and Slowtwitch forums have it moving a Kickr's reported speed and distance, and none has it moving resistance: display-only, by every published account. - Descents and MinTrainerGrade. Wahoo publishes a maximum simulated grade of 16 % for the gen-1 Kickr Core and the Core 2, and a minimum of −10 % for the Core 2 (KICKR CORE 2, gen-1 KICKR CORE, both read 2026-10-25). The gen-1 page names no minimum. A Core brakes and never drives, so it renders a descent until its road force reaches zero: on the default road at 83 kg that is −2.1 % at 30 km/h of flywheel speed and −5.1 % at 50 km/h. Below that it sits at its own floor. At −10 % it has nothing to brake up to 72 km/h at 83 kg and up to 68 km/h at 75 kg, and 53×11 at 110 rpm turns it at 67 km/h.
- Cadence, and so the ratio noise. Kickr cadence is estimated, not sensed (above). Zwift Insider found it accurate and steady in 2019, but a few seconds behind after a hard sprint. The #10 Kickr Core rode one Zwift Cog, so all its 113 samples at 60–110 rpm share one true ratio. Speed ÷ (cadence × 2.096 m) has a median of 2.94 and a robust per-sample σ (1.4826 × the median absolute deviation) of 2.4 %. Runs of samples at least 5 % off on the same side last at most 3.
Music-over-voice acoustics — the room-audio defaults change:
- Chrome historically cancelled only WebRTC far-end audio from the mic (local tab audio was rebroadcast!); chrome-wide AEC (fixed Oct 2023) now cancels Chrome-played audio incl. cross-origin iframes — but never system audio, the present-tense behavior rests on bug-tracker comments not docs, and the explicit
echoCancellationMode: 'all'constraint is Chromium-141+ only (WebKit: no position). Treat AEC as a quality improver, never a correctness guarantee. - Discord — the closest precedent — solves music+open-mic with transmit gating, not AEC: push-to-talk or tightened voice-activity sensitivity is their official guidance; Watch Together plays YouTube per-user in local iframes with local volume, music never entering the voice path — exactly WattRoom's architecture, validated.
- → SPEC: mic default = voice-activity gating; when the jukebox plays, tighten VAD and offer one-tap PTT; nudge headphones on join when music is active.
Noise suppression (fan noise):
- Krisp is LiveKit-Cloud-only — the self-hosted feature request was closed "not planned", and the npm filter package is commercially licensed. Self-hosted gets browser-native
noiseSuppression(leave on, per LiveKit's own recommendation) plus optionally an OSS RNNoise/DTLN track processor on the local mic — the integration point (livekit-client processor interface) is identical to Krisp's, so an upgrade path exists.
Tab throttling vs the ERG loop:
- Chrome's intensive throttling can delay hidden-tab timer chains up to ~60 s per tick — but an active WebRTC connection exempts the tab (1-second alignment instead). Riders in a room are protected by the call itself; solo riders with a hidden tab are NOT. → Ride-critical timing runs in a Web Worker with Wake Lock held; never trust main-thread setInterval for the target loop.
- Measured (#51, Chrome 141/macOS, same page, two timers, 439 s hidden): main-thread
setIntervalfired 159 times — 280 s lost; a workersetIntervalfired 438 times — 1 s lost. Confirms the claim and the fix. Note an attached debugger (CDP/DevTools) suppresses throttling entirely, so this only reproduces in a genuinely backgrounded tab — a foreground-tab test will show no problem and prove nothing. - Degradation ladder is nearly free: LiveKit
adaptiveStreampauses server-side flow for invisible tracks,pauseVideoInBackground(default true) stops remote video decode when backgrounded — audio and data unaffected.
Still open (no surviving claims):
- Bluetooth coexistence (BLE trainer/HR + BT-Classic headphone audio on one adapter; A2DP→HFP quality collapse when the headset mic activates) — settle empirically in the #10 hardware session; expect "wired headphones or phone-for-audio" as rider guidance.
- Temporal coherence (klaxon↔sprint-UI alignment thresholds; server-clock-scheduled cue playback as the pattern) — design-time question for M4 sprint moments; working hypothesis stands: schedule cues on the synced server clock, accept that coach voice can never align (~100–300 ms WebRTC latency).
Three parallel research passes (models/formulas, product-UX teardowns, athlete needs & heuristics), synthesized. Feeds the SPEC addition + ADR that gate #222's load/recommendation slices. Per-rider analysis is already blessed by ADR-0008 ("fitness trend across months, power curve… that is where the value is"); cross-rider aggregation stays out.
TSS®, NP®, IF®, CTL/ATL/TSB are Peaksware (TrainingPeaks) trademarks. The math is published and freely implementable; the names are not usable — GoldenCheetah was made to rename (TSS→BikeStress, NP→IsoPower, GC FAQ). Adopt intervals.icu's naming, which every novice-friendly product converged on: Load, Intensity, Fitness, Fatigue, Form.
Spec-ready formulas (TrainingPeaks NP/IF/TSS, Coggan PMC):
NormPower = ( mean( (rollavg_30s(watts))⁴ ) )^0.25 # per ride, 1 Hz input
Intensity = NormPower / FTP
Load = Intensity² × hours × 100 # 1 h at FTP = 100 by construction
Fitness_d = Fitness_d-1 + (Load_d − Fitness_d-1) / 42 # daily EWMA, rest day Load = 0
Fatigue_d = Fatigue_d-1 + (Load_d − Fatigue_d-1) / 7
Form_d = Fitness_d-1 − Fatigue_d-1 # yesterday's values, deliberately
- Form is displayed as % of Fitness (intervals.icu's fix — absolute Friel bands assume a ~100 Load/day athlete; forum). Zones (Friel-derived): > +20 Transition / +5…+20 Fresh / −10…+5 Grey / −30…−10 Optimal / < −30 High Risk.
- Cold start: EWMA from 0 makes every new rider look dangerously ramping. Suppress load-based warnings for the first ~4–6 weeks and label the chart "building history", or seed Fitness ≈ weekly hours × 60 ÷ 7 (Coggan's 50–75 Load/h heuristic).
- Ramp guidance: +5–8 Fitness/week is the Friel band (CTL ramp rate); Couzens argues 3–5 for working-age athletes. Fatigue/Fitness ratio 0.8–1.3 "sweet spot", warn > ~1.4 — but ACWR science is contested (mathematical coupling, retraction requests); word it as "load rising fast", never as injury-risk claims.
- Monotony (Foster, rolling 7 d, zeros included):
mean(daily Load) / stdev(daily Load)— > 2.0 flags "same ride every day"; cheap and catches what the EWMA misses. - eFTP: fit the 2-param critical-power model to the rider's 90-day curve bests (two points:
W′ = (P1−P2)·t1·t2/(t2−t1),CP = P1 − W′/t1; 3+ points: least squares) and surface CP as "estimated FTP" with one-tap accept. This is intervals.icu's continuous-estimation pattern (eFTP thread) and it kills the stale-FTP problem — the single biggest corruption vector, since Load, zones and execution all key off FTP. - HR (already stored per ADR-0008): Efficiency Factor
EF = NormPower / HRavgand aerobic decoupling(EF_1st_half − EF_2nd_half) / EF_1st_half— meaningful only on steady rides ≥ ~60 min; < 5 % = solid base (Friel). No TRIMP/HRSS needed — power is always present on a trainer app.
Data seams: rides already has seconds, avg_watts, kj, execution, ftp_watts at ride time (FTP history is free) and curve bests {5s, 1m, 5m, 20m}. Missing: per-ride NormPower/Load and time-in-zones (compute at save time going forward; one-pass backfill over existing blobs — consistent with "samples read per-ride only"), and more curve windows (add ~3m/8m/12m/30m for CP fitting and overlay resolution). Weight is not historical — accept that w/kg trends use current weight.
13.2 UX patterns (teardown of intervals.icu, TP, Strava, Garmin, Whoop/Oura, Xert, TrainerRoad, Zwift)
What recurs across the products athletes actually like:
- Banded form line — one line through named, colored horizontal zones; the bands do the interpreting. The classic acronym PMC (TrainingPeaks) is the thing everyone else fixes: words beat acronyms, interpretation lives in the UI, not the user.
- Status words describe the day or the workout, never the athlete. Garmin's "Unproductive" is the cautionary tale (users report months of feeling "like a failure" off a misconfigured max-HR); TrainerRoad's per-workout tags (Recovery / Achievable / Productive / Stretch / Breakthrough) are the same mechanism aimed at the pick, and they're loved. That tag vocabulary is the proven pattern for #222's picker badge.
- Single number + color embed, "why" one tap away (Whoop/Oura/Garmin readiness). Best at-a-glance pattern ever shipped and the anxiety pattern — Oura's named contributors are the accepted mitigation. Any WattRoom embed needs its one-clause reason inline.
- Progressive disclosure — Strava shows the Fitness line only by default, everything else opt-in; one question per surface ("how hard today?" / "is it working?" / "what should I ride?"). Opacity = several questions on one chart (raw PMC, Xert). Xert's other lesson: invented jargon is a moat and an adoption ceiling — don't coin vocabulary beyond the SPEC glossary.
- Zwift ships none of this layer — the social-indoor incumbent leaves it entirely to intervals.icu. A progression layer inside the social product is differentiation, not table stakes.
Synthwave mapping: the form/fitness line is data → it gets the --color-watt glow; zone bands are quiet chrome. The mid-ride rules don't bite (this is all off-bike UI), but arm's-length legibility still argues for band-position-readable-in-a-second over dense multi-series charts.
- Weekly consistency/streak — strongest motivational evidence for this audience ("time in saddle + consistency" wins rider surveys by 5–8×; Strava's streaks are deliberately weekly, with forgiveness). Immune to partial-data corruption.
- One-line form status in plain words ("fresh", "carrying fatigue — recovery is where the gains land"), always scoped "from your WattRoom rides".
- Suggested for today with a one-clause why + visible override — TrainerRoad forums prove the why and the override are what preserve trust (honest "that was hard" answers spiraling into forced easy weeks is the #1 resentment).
- Power-curve bests / PRs — monotonic, unambiguous, always good news; safest fitness signal we own.
- FTP freshness + retest prompt (no test or maximal 8–20 min effort in ~6–8 weeks, or eFTP ≥ ~3–5 % above set FTP).
- Fitness chart — last, for those who want it.
Candidate rules with thresholds (confidence): ramp brake > ~8 Fitness/week sustained (high); big day yesterday > ~1.5× median ride Load → suggest easy (high); Form < −30 %, never suggest intensity (high on the band, medium on the number); no ride ≥ 10–14 d → gentle restart, scaled by layoff (high — detraining is real but < 2 weeks is nearly free); recovery week after 3 loading weeks (high as practice); monotony > 2.0 → "vary it" (medium); collapsed week → "20 min with hard efforts keeps fitness" (high — maintenance needs intensity, not volume). All nudges: never gate a workout a rider wants to ride.
- Partial-data "fake detraining" — WattRoom only sees its own rides; an outdoor season reads as decay. Mitigation ladder: honest scoping label (always) → one-tap "I trained elsewhere" (duration × easy/moderate/hard) → Strava activity read (§13.5). Absolute fitness claims are indefensible; "your WattRoom riding" claims are fine.
- Stale FTP corrupts everything → continuous eFTP + staleness notice, not silent drift.
- Judgment words ("unproductive", "failed") → describe the load, never grade the rider.
- Small-N cold start → suppress warnings ~4–6 weeks or seed from self-reported hours.
- Execution ≠ difficulty — 100 % in-band on a recovery spin and on 5×5 VO2 are different achievements; don't let execution double as a fitness or difficulty metric.
- Daily unforgiving streaks curdle into anxiety (Duolingo pathology) → weekly cadence + repair mechanic + "new week, fresh start" reframe on a break.
- ACWR as settled science / strict 80-20 policing — both indefensible at this audience's volume; soft language only.
Re-read against the primary pages on 2026-09-08 (#229). The findings below held; two dates were missing and are now the last two bullets. WATTROOM.md's row was refreshed at the same time and no longer cites Nov-2024.
The Nov-2024 agreement WATTROOM.md used to cite is no longer current. A new API Agreement + API Policy took effect June 1, 2026. What changed and what it means:
- Standard Tier now requires the developer to hold a paid Strava subscription (~$12/mo) — and Standard is what any >1-athlete app needs, so the existing auto-upload for the alpha fleet already sits under this requirement (grace ended June 30, 2026). Two Standard levels exist: 10 users and 9,999 users; Extended review only beyond that. (policy §3.3, fee-change thread)
- Display restriction unchanged in spirit (§2.3): Strava data — and anything derived from it (§5.4) — may be shown only to that athlete. Exactly the shape of #222; the one hard rule is that Strava-derived numbers never leak into room-visible state.
- AI prohibition got much broader (§5.3): not just model training — "ingestion into a context window" is now explicitly banned. A deterministic rule-based load calc is fine (no model involved; Strava's own press blessed "tools that help users understand their data"). Consequence for this repo: an architectural firewall — Strava-sourced data must never reach any LLM/agent feature (feedback agents, future "ask about my training" ideas). The no-aggregation clause (§5.4) additionally means: compute per-user, store per-user, display per-user, never tune the product on it.
- Scopes: want
activity:read_all, notactivity:read— "Only You" rides otherwise vanish from the calc, and privacy flips even arrive as delete webhook events. Adding a scope = full re-auth flow; the token response echoes what was actually granted, so track granted scopes per user and gate the feature on them. - Summary data suffices — no streams needed:
GET /athlete/activities(≤200/page) carriesmoving_time,kilojoules,average_watts,weighted_average_watts(NP-like; trust whendevice_watts=true), plus undocumented-but-returnedaverage_heartrate/suffer_score(the latter subscriber-only). Load fallback chain: power → HR → duration-only. Backfill is a handful of requests per athlete against 1,000–2,000 reads/day — trivial at alpha scale. - Obligations: raw Strava payloads are a ≤7-day cache (§6.2); derived values inherit the rules — everything wiped ≤30 days after deauthorization (webhook
athlete/authorized:false; new/oauth/revoke); on-Strava activity deletions reflected ≤48 h. Clean fit with our seams: durable per-day load numbers in Postgres, raw payloads treated as re-fetchable cache. Deauthorization is handled (#2823): Strava's push webhook is the primary signal and an upload refused for a revoked grant the backstop; either way Strava is asked to refresh the grant first, since its events are unsigned, and only a refusal naming the refresh token forgets the tokens and activity ids. - A hard date nobody has diarised: 2026-09-30. The subscription requirement bit on June 30, 2026, but active developers without one got three months free — and that window closes at the end of September 2026. After it, an unsubscribed developer account loses Standard Tier, which is what the existing auto-upload runs on. (developer program update)
- A second date, further out: 2027-06-01 technical migration. Three breaking changes. The base URL moves from
https://www.strava.com/api/v3tohttps://api-v3.strava.com— nowww, and per the changelog it does not exist to test against until 2027-01-04. Authorization tokens must travel in headers rather than form or query params on API requests; our upload path already sendsAuthorization: Bearer(strava.go), so that half is done. Andoauth/deauthorizeretires in favour ofoauth/revoke— done in #1093. Do not read the header rule as applying tooauth/revoke. It does not: revoke is RFC 7009 in shape, the client authenticates with Basic auth and the token being revoked is a form field, which is what Strava's own curl example shows. The rule is about requests that authenticate with a token, not about the one request whose subject is a token. Conflating the two is the mistake this bullet made when it was written. - Dedup of our own rides is already wired: uploads set
external_id: "wattroom-<ride uuid>"(strava.go), so the pull side skips that prefix (or excludes by theactivity_idthe upload poller already reads back). WattRoom rides count from our own DB, never from their Strava copies. - Alternatives, one line each: intervals.icu API (free, computes fitness/fatigue/form for us, OAuth creds on request — power-user option, small audience); Wahoo Cloud API (light approval, overlaps our KICKR audience, Wahoo-recorded only); Garmin (weeks-long partner review — not for a tiny app); manual .fit import (zero legal exposure,
fitexportcompetence already in repo, but sweaty riders don't do chores — fallback only).
Bottom line: the read integration is compliant and cheap in the exact shape #222 already has (per-user, private, rule-based), costs the developer a Strava subscription, and needs its own ADR covering scope re-consent, the 7-day/30-day retention duties, and the AI firewall.
Inline research tier — every claim below is sourced, none survived a 3-vote adversarial pass; items marked extracted were read off the primary page rather than a summary. Feeds #995 (room stats), #993 (profile counts) and #996 (self-comparison), which were blocked on it deliberately: these are the surfaces most likely to change how a crew treats each other, and picking their metrics by taste is how a friendly room turns into a ladder nobody enjoys.
§13.2 point 5 says "Zwift ships none of this layer". That is true of progression and false of the social layer — Zwift ships a great deal of it, and what it refuses to ship at the same time is the most useful finding in this section (§14.1).
| product | what a group sees | shape |
|---|---|---|
| Zwift (Companion, Meetups, Club events) | live position, group text, meetup members highlighted in the rider list; "Keep Everyone Together" rubberbands a mixed-ability group to one pace | presence + chat; results optional and exclusive |
| Peloton | live class leaderboard, Here Now, high fives, milestone badges, an activity feed of friends' workouts | rank + lightweight acknowledgement |
| Strava clubs | a weekly leaderboard of members, current and previous week, top 100 only; no club-authored challenges | rank, reset weekly, capped |
| WHOOP Teams | leaderboards over strain / recovery / sleep, daily / weekly / monthly, metric set chosen at team creation and immutable after | rank, with consent fixed up front |
| Garmin Connect | connection and group challenges with individual rankings; leaderboard hidden from anyone who has not synced in 24 h | rank, and auto-enrolling |
| Discord | presence, activity, who is in the voice channel — no performance metric at all | presence only |
What recurs: a weekly cadence, presence as a first-class display, and lightweight acknowledgement (high five, kudos, cheer) that costs the sender nothing and is not a ranking.
What got removed or fenced, and why — the more instructive half:
- Zwift will not run rubberbanding and results at the same time. "Keep Everyone Together" is Club-events-only, cannot be enabled together with Event Results, and segment times under it reflect the group's collective speed rather than individual effort. (extracted — Zwift Insider) The social-indoor incumbent, holding the largest mixed-ability dataset in the category, treats riding together and ranking each other as mutually exclusive modes. That is the single strongest evidence in this pass, and it is a design decision, not a technical limit.
- Strava turned Flyby off for everyone in October 2020 and made it opt-in, after riders showed it could be used to learn another athlete's routine and route. Few re-enabled it, so the feature is effectively dead. (DC Rainmaker, Cycling Weekly) A presence-derived feature that ships on-by-default gets switched off wholesale later; the migration is one-way.
- Garmin auto-enrols. Group challenges cannot be left without leaving the group, and the support site carries an article titled "I Am in a Garmin Connect Challenge I Did Not Accept". (Garmin support, leaving a challenge) A room that enrols its members in a ladder by existing is this bug.
- Nobody ships the cooperative total. The most-repeated Garmin feature request is a combined, whole-group number rather than individual rankings (forum). It is unoccupied ground in every product torn down here.
The audience is 3–10 people who ride together weekly and know each other. Almost all leaderboard evidence is drawn from large anonymous populations, and it does not transfer cleanly.
- Small is the recommended size, not the compromise. Leung et al.'s pre-registered field experiment (>1,000 users) found contribution rises when peers' scores are more dispersed — the opposite of the standard model — that falling average peer contribution also motivates, and that both effects are mediated by group size; the paper recommends leaderboards of 10–20 people. (CHI 2019) A crew of six is inside the band the literature actually endorses, and a wide fitness spread inside it is not automatically a problem.
- Duolingo's leagues are 30 randomly assigned users, reset weekly, with promotion and demotion. The cohort size, the randomisation and the weekly reset are the design; the anxiety it produces is documented and comes from the demotion threat, which is available to everyone not already at the bottom. (Deconstructor of Fun) A standing crew cannot be re-randomised — the same six people are there next week — so the mechanism Duolingo uses for engagement is exactly the one WattRoom cannot borrow.
- The 95 % claim has no study behind it. "Leaderboards motivate the top 5 % and demotivate the bottom 95 %" is practitioner writing, repeated widely without a citation (Yu-kai Chou). The directional worry is real and the number is folklore; do not quote it in the product, and do not design against it as if it were measured.
- Vendor-reported, treat accordingly: Peloton says socially engaged members work out ~15 % more often. Self-reported by the party selling the feature, and confounded by the obvious direction of causation (people who ride more join things).
Helps: when rank is against your own past, when the group is small and known, when the cadence resets often enough that a bad week is not permanent, and when the thing ranked is effort shown up for rather than capacity.
Harms: when the ordering is stable — in a standing crew the same person is last every week, which is the one configuration none of the cited products has to survive, because all of them re-randomise, cap, or reset the pool.
Mitigations that actually shipped, ranked by how well they fit a room:
- Do not rank at all while riding together (Zwift's exclusivity). Strongest, and free.
- Fix what is shared at join time and make it immutable (WHOOP Teams: the metric set is chosen at team creation, cannot be changed afterwards, and a joiner sees exactly what will be shared before joining).
- Weekly reset with no accumulating history (Strava clubs: current and previous week only; Duolingo: one week).
- Cap the board (Strava: top 100 — irrelevant at crew size, but the principle that a board has a floor it does not print is not).
- Suppress on thin data (Garmin hides the leaderboard from anyone who has not synced in 24 h — the same instinct as §13.4's small-N rule).
- Opt in, per person, and be able to leave — the one Garmin gets wrong, and the reason it has a support article about it.
There is no defensible single crew metric, and the evidence points at not looking for one:
- kJ rewards mass and duration; a 95 kg rider doing 90 easy minutes beats a 55 kg rider's hard hour, and both did the right session.
- w/kg inverts it, and WattRoom already owns a fairer form of it: Category (D–A from the 90-day w/kg curve, moves both directions, SPEC glossary). That is a bracket, not a rank — it says who to compare with, which is the useful half.
- Execution score cannot carry this: §13.4 is explicit that 100 % in-band on a recovery spin and on 5×5 VO2 are different achievements, so a board sorted by execution ranks workout choice.
- Time in zone / duration is the only raw quantity that means roughly the same thing to every body, and it is what the training-load evidence in §13.3 already ranks first for this audience ("time in saddle + consistency" beating performance metrics by 5–8× in rider surveys).
Recommendation: the room's primary number should be a cooperative total — the crew's combined work for the week, one figure nobody is ranked inside — beside a per-rider showed-up strip. This is unoccupied ground (§14.1), it is fair by construction because it does not order anyone, it is the metric the small-group evidence supports, and it is the only shape compatible with Zwift's finding that riding together and ranking each other do not coexist. If a room wants an ordered board, it is a second, opt-in, weekly-resetting surface — never the default view, and never the one a new member is enrolled in by joining.
Rank the crew against itself over time (this week vs the crew's own average), never its members against each other by default. That keeps the "always good news, monotonic" property §13.3 ranks power-curve PRs fourth for, at group scale.
The line is not presence vs no presence. It is ephemeral and mutual vs durable and one-sided:
- Ephemeral, inside a known group, everyone equally visible — Peloton's Here Now, Discord's voice channel, Zwift's highlighted meetup list. Universally shipped, no backlash on file.
- Durable, derived, and readable by people you did not choose — Strava Flyby. Turned off for everyone (§14.1).
A WattRoom room is a closed membership with mutual consent (ADR-0013) rather than an open network, which puts a "who showed up" strip on the Here Now side of the line — provided three things hold, all borrowed from products that survived: the set of what the room can see is fixed and shown before joining (WHOOP), it does not aggregate across rooms into a profile of a person's week, and it stays inside the room (WATTROOM.md is already absolute on this). Workplace-wellness research is the warning for the failure case: participation collapses the moment a health display reads as monitoring rather than company (step-challenge privacy guidance) — and a room whose members did not choose each other freely (a coach's crew, a team) is structurally that case.
This settles the overlap with #985: a session recap listing who was there and how long is durable and therefore in scope for the fixed-at-join consent set; the live "here now" strip is ephemeral and already covered by the room's own tick and ADR-0022.
Everything above is nameable in docs/SPEC.md words — room, session, coach, rider, execution score, level, category, medals, cheers — with two gaps that must be closed deliberately rather than coined in passing:
- Streak is used in the XP formula (
25 × current-week-streak) and in #992's mockups but is not a glossary entry. If consistency becomes a room surface, the glossary grows by one line, in the same PR. - "Consistency" has no SPEC definition and is doing load-bearing work in this section and in #992. Either define it (rides per week over N weeks, forgiveness rule included) or use streak and say what a streak counts.
Do not coin ladder, board, or a crew-metric name. §13.2 point 4 already ruled on this: invented jargon is a moat and an adoption ceiling.
- Who rode this week, and whether that is the crew's normal — attendance as company, not as compliance. Fairest metric available, immune to fitness spread, and the one the small-group and consistency evidence both point at.
- The crew's combined work for the week (kJ or hours — one number, unranked, cooperative). Unoccupied ground; safe because nobody is inside it.
- Lightweight acknowledgement between riders — cheers already exist and cost the sender nothing. Every product torn down here ships this and none has regretted it.
- A rider against their own past (#996's job) — always good news, no privacy argument, no comparison to defend.
- A session recap — who was here, when they came, how long they stayed (#985), under the fixed-at-join consent set.
- An ordered board, opt-in per room, weekly reset, bracketed by Category so it compares like with like. Last, and never the default.
- Enrolment by existence — being in a room must not put a rider on a board. Garmin's mandatory group challenges are the shipped counter-example.
- The permanent last place. A standing crew does not re-randomise; a stable ordering is the failure mode none of the cited products has to survive. Reset weekly, or do not order.
- A board that is the room's front page. Zwift's exclusivity is the pattern: what a room shows while riding together should not be a ranking.
- Aggregating a person across rooms — that is a profile of their week, not a room's stats, and it is the Flyby shape.
- Reading a ladder into an attendance strip — "showed up 1/4 weeks" beside four green weeks grades attendance. Describe, never grade (ADR-0016).
- Strava-derived numbers anywhere room-visible — §13.5, hard rule, and it applies to every number in this section.
- Heart rate in any shared artifact — ADR-0008, unchanged.
- Quoting the 95 % folklore as if it were evidence (§14.2).
- What a room may show about its members, and when they consent to it — extends ADR-0024 and ADR-0013; the WHOOP pattern (fixed at creation, visible before joining, immutable after) is the candidate. Blocks #995 and #985.
- Whether a room has an ordered board at all, and if so its cadence, its bracket and its opt-in. The evidence here recommends cooperative total by default, ordered board opt-in; that is a product decision, not a finding.
- Streak and consistency as SPEC terms — one glossary addition, with the forgiveness rule, since ADR-0027 already lets earned things travel and this decides whether consistency is one of them.
Inline research tier — sourced, no adversarial pass; extracted marks a claim read off the primary page rather than a summary, and unverified marks one carried over from #296's body that this pass did not confirm. Feeds ADR-0037 and the desktop/ skeleton.
Why this section exists twice. #296 cites "RESEARCH.md §14" throughout for exactly this material. That §14 was written on claude/desktop-app-planning-aa6eae, never merged, and the branch is gone from the remote; §14 was subsequently taken by the social-stats pass (#994). The substance survived only in an issue body. This is the section-number collision #1021 warns about, and the lesson is the one it states: take the number at merge, and land research before the work that cites it.
Electron is not a browser with a title bar. Four things Chrome does for you are absent, and each fails in a way that looks like a bug in WattRoom.
-
select-bluetooth-device— Electron ships no device chooser. extracted from webContents docs: "If no event listener is added for this event, all bluetooth requests will be cancelled."This corrects #296, which says
requestDevice()"never resolves" without a handler. It is cancelled, so the promise rejects — bad, but visible, andmedia-error.tsalready turns a rejection into copy. The genuinely dangerous half is the next line: "Ifevent.preventDefaultis not called when handling this event, the first available device will be automatically selected." A handler that forgetspreventDefaultsilently pairs whatever answers first — in a room where several riders' sensors are advertising, that is someone else's trainer, with no prompt.Upside worth taking: our own picker can filter to FTMS/HR/CSC and remember the last trainer, which Chrome's chooser cannot.
-
setPermissionRequestHandler— the default is to allow. Electron approves permission requests unless a handler says otherwise; with remote content that hands camera and microphone to anything that gets the renderer to navigate. (Doyensec, Diving Into Electron Web API Permissions; Electron security tutorial) Deny by default, allowlist our origin, and pair it withsetWindowOpenHandler→openExternaland awill-navigateguard. -
setDisplayMediaRequestHandler— Electron does not implement standardgetDisplayMediawithout it, so the stage (#280) silently breaks. The handler must also survive cancellation: the picker throws into the handler to signal abort, and an unhandled rejection there leaves the renderer waiting (electron#47980, electron#45517). -
Info.plist usage descriptions —
NSBluetoothAlwaysUsageDescription,NSMicrophoneUsageDescription,NSCameraUsageDescription, and the audio-capture key for system audio. Necessary, and not sufficient — see 15.2.
-
Ad-hoc signing breaks capture, silently. electron-builder#9529: since v26.0.13, ad-hoc-signed macOS builds (
mac.identity: "-"or the implicit fallback) lose Camera and Microphone — no prompt, the stream resolves, and no frames or audio arrive. A regression between 26.0.12 and 26.0.13. This is the worst failure shape this product has: the mic reportsliveand the room hears nothing. -
The Hardened Runtime denies by default, and notarization requires it. So the trap is an app that is signed, notarized, launches clean, and still cannot see the trainer. Four entitlements, each extracted from its own page in Apple's entitlement documentation — the page title is the evidence, since the bodies do not render for a fetcher:
key Apple's page title com.apple.security.cs.allow-jit"Allow execution of JIT-compiled code entitlement" — V8; electron-builder documents it as required to stop framework crashes com.apple.security.device.audio-input"Audio Input Entitlement" com.apple.security.device.camera"Camera entitlement" com.apple.security.device.bluetooth"com.apple.security.device.bluetooth" The method is worth stating because it is the only one that worked: a canonical entitlement URL resolves and a fabricated one (
…device.bluetooth-nonsense-control) returns 404, so a page existing at the canonical path is evidence the key is real. Titles were read; bodies were not. -
Helper processes need their own entitlements file — confirmed. electron-builder auto-detects
build/entitlements.mac.plistandbuild/entitlements.mac.inherit.plist, the inherit file applying to child processes (helpers, renderer). The renderer's microphone lives in a helper, so an entitlement present only in the main file leaves the mic dead. From electron-builder v27 the signing options (hardenedRuntime,entitlements,entitlementsInherit) moved undermac.sign— pin the config shape to the major actually used. (electron-builder macOS docs, notarization)
The shell is worth building for two capabilities. It is worth being precise about which, because three of the reasons commonly given are already solved in the browser build.
| claim | status |
|---|---|
| ANT+ | real — BLE-only Web Bluetooth cannot reach a proprietary USB protocol behind a vendor driver |
| system audio into the room | real on macOS only — Chrome's getDisplayMedia captures tab audio everywhere and full system audio on Windows when sharing a screen |
| "hold the machine awake" | already shipped — workout/wakelock.ts (#58) re-requests the lock on every return to visibility |
| "keep running when hidden" | already shipped — workout/ticker.ts (#51) ticks from a worker and reports wall-clock elapsed, so the ride stays correct even if the worker is throttled |
| HUD over fullscreen, tray, deep links | real, and genuinely browser-impossible — but conveniences, not the justification |
app.setLoginItemSettings/getLoginItemSettingsare macOS and Windows only — extracted, the platform annotation on app docs readsmacOS Windows. Linux launch-at-login means writing a~/.config/autostart/*.desktopfile ourselves.- Deep links need the single-instance lock. Without it every
wattroom://link opens a second window against the same session. - Media keys on macOS — #296 reports they need Accessibility permission, report success when they did not register, and get routed to whatever is playing audio (the YouTube iframe). unverified here. If it holds, register them on Windows/Linux only and spend the effort on a global push-to-talk instead.
Playwright's _electron fixture can assert the packaged app launches, a window opens, window.wattroom carries the expected keys, the navigation guard rejects an off-origin URL, and the app quits cleanly — Linux under xvfb. Native dialogs, the tray and menus are not Playwright-drivable, and BLE and audio are not CI-testable at all, so the four handlers in 15.1 are exactly the code CI cannot prove. They need a hardware session per OS (docs/HARDWARE-SESSIONS.md). The existing e2e suite stays pointed at the browser build.
The three non-JIT entitlement keys— resolved, see the table in 15.2.Whether electron-builder applies an inherit entitlements file— resolved:build/entitlements.mac.inherit.plist, auto-detected, applied to child processes.- The macOS media-key behaviour (15.4) — still carried from #296 unverified.
- Which Electron major to pin, and whether macOS system audio through ScreenCaptureKit actually works on it — ADR-0037 names this as the thing that would reverse it. This is the one that needs a machine, not a search.
Inline research tier — sourced, no adversarial pass; extracted marks a claim read off the primary page rather than a summary. Feeds ADR-0038 (already merged, which is the wrong order and is noted as such below) and #1106, the cutover whose risk this is about.
The headline: the chosen model is stricter than Discord's in the two places that matter and more mechanism in one place Discord deliberately has none. The strictness is defensible and the extra mechanism probably is not. One concrete gap — no un-removable crew owner — has no counterpart in any product torn down here, and it is the finding worth acting on before the cutover.
Order-of-work note. ADR-0038 merged before this section landed, which is exactly the failure §15 warned about in the opposite direction. Nothing here is fatal to it, but two findings (16.4, 16.6) argue for an amendment rather than a clean read.
extracted from the Discord developer permissions docs. Overwrites resolve in eight ordered tiers — base @everyone guild permissions, guild role permissions, then channel-level @everyone deny, @everyone allow, role deny, role allow, member deny, member allow — so a member overwrite has ultimate priority and a role overwrite beats @everyone. Within a tier the computation is:
permissions &= ~deny
permissions |= allow
This corrects the most widely repeated claim about Discord permissions. Community guides state that any role denying a permission wins over another role allowing it. The primary source says the opposite: denies and allows are accumulated across the member's roles into one pair, deny is applied first and allow second, so at the role tier allow wins. A model copied from the folklore rather than the spec would be subtly stricter than the thing it is imitating, and the bug would appear as "why can this person not see the room" long after the rule was written.
The trap this creates for us: an eight-tier resolution order is only auditable if it is written down once. Discord's is a documented algorithm with a reference implementation; a hand-rolled equivalent scattered across query WHERE clauses is the same algorithm with no single place to read it, which is 16.2's question.
The industrial answer is Zanzibar, Google's authorization system, and its useful idea is small: rather than duplicating a viewer list onto every document, write a rule that says to check who may view this, look up its parent and include the parent's viewers. Inheritance is expressed once, as a relation, not copied.
The industrial implementation is not the answer here. Zanzibar exists to serve over ten million checks a second across Drive, YouTube and Photos; the open-source descendants (SpiceDB, OpenFGA, Topaz) are separate services with their own storage and consistency model. WattRoom's numbers are a handful of crews, tens of rooms and tens of people, and ADR-0002 is one VM with no extra moving parts.
So: take Zanzibar's rule-shape, not Zanzibar. At this size the single expression is a SQL view — rooms_visible_to(user_id) — that every gate and every visibility join selects from, so the eight-tier order of 16.1 exists in exactly one file. A view also fails safe in a way a query fragment does not: a new join that forgets it does not silently over-permit, it fails to compile against a table that is not there. Cost at these sizes is not the consideration; auditability is the whole point. A materialized table is the upgrade path if it ever measurably matters, and it will not.
The canonical case is Google Buzz, 2010. Buzz auto-connected users from their most frequent Gmail contacts and exposed that list by default; Google received thousands of complaints about public disclosure of contacts that included, per the FTC, ex-spouses, patients, students and employers. The FTC charged that users "were not adequately informed that the identity of individuals they emailed most frequently would be made public by default" and that Google "violated its privacy policies by using information provided for Gmail for another purpose — social networking — without obtaining consumers' permission in advance" (extracted, FTC press release).
The remedy is the sentence that matters here. The order requires Google to "obtain users' consent before sharing their information with third parties if Google changes its products or services in a way that results in information sharing that is contrary to any privacy promises made when the user's information was collected" (extracted, same source).
Read that against the literal reading of crew-visible-by-default: a room created under a schema comment promising "rooms are private/unlisted by default" becomes visible to everyone in its owner's other rooms, on upgrade, without being asked. That is the described shape almost exactly — a change to the product that results in sharing contrary to the promise made when the data was collected.
ADR-0038 already lands on the right side of this: the crew-visible default applies only to rooms created after the cutover, and existing rooms migrate private with their current membership as named exceptions. This section is the evidence that the derivation was not merely cautious. §14 already carried the sibling case — Strava turned Flyby off for everyone in 2020 and made it opt-in, and few re-enabled it — and the lesson repeats: a visibility default is easy to loosen once and impossible to walk back.
ADR-0038 specifies bans at both levels: a room ban as it exists today (a memberships role that keeps the seat), plus a crew ban that removes a person from every room and prevents rejoining.
Discord, doing the same job at vastly larger scale, has one. There is no per-channel ban; the only ban is server-wide. Excluding someone from a single channel is a View Channel deny overwrite — the same permission mechanism as everything else in 16.1, not a second kind of exclusion.
That is a real argument against the two-level design as written, and it is the shape of finding #1021 asked to be told loudly. The cost of two ban mechanisms is not conceptual, it is that every visibility join must consult both, forever, and the failure mode is silent over-permission rather than an error. ADR-0038 already names this cost ("every query that reads role != 'banned' must additionally honour the crew ban") and lists the sites; #1109 is the proof it is not hypothetical — one of those very queries is already missing its single-level guard today, before a second level exists to forget.
The cheaper shape, if #1106 wants it: keep one ban, at the crew, and express "out of this room" as a deny in the override mechanism ADR-0038 is introducing anyway. One ban, one permission system, one expression to audit — which is also 16.2's view, so the guard cannot be forgotten by a new join. The counter-argument is migration: room bans exist in rows today and would have to become overrides. That is a decision for the cutover, not a fact this pass settles.
Resolved, and this recommendation was not taken (ADR-0038, amended 2026-09-08). The Discord finding above stands; the inference from it does not, for three WattRoom-specific reasons this pass did not check. ADR-0038 lets a non-member crew admin manage a room's permissions while explicitly forbidding them to ban from it — so making exclusion an override collapses two operations the design deliberately separates, and grants the withheld one.
docs/SPEC.mdalso defines a ban as more than state: it "severs the live socket and voice on the spot", which an override does not do. And SPEC's roles matrix puts ban/unban on the room owner alone, so the change would move moderation from the room to the crew.The correction to draw from it: the count of ban levels is not what made the guard forgettable — the count of places it is written by hand is. #1109 and #1114 are four joins that each omitted it at one level. So 16.2's single expression is the fix, and ADR-0038 now makes it load-bearing: one view is the only place allowed to answer "is this person excluded here", and it reads both levels.
Discord's protection against permission lockout is an actor who cannot be locked out: the server owner can access any channel's permissions at all times, and ADMINISTRATOR "overrides any potential permission overwrites, so there is nothing to do here" (extracted, permissions docs). Lockout is a documented, recoverable state precisely because one role is outside the permission system.
ADR-0038 and #1022 name crew admins and never a crew owner. Rooms keep an owner; the crew layer has only admins, who manage each other's roles. Two admins can therefore demote each other, and there is no stated actor guaranteed to still hold the crew afterwards. Every product surveyed here has that actor. This is a gap in the model rather than a disagreement with it, and it is cheap to close now and awkward later — the migration creates one crew per existing owner, so the owner it is named after is the obvious crew owner, and the row already exists.
Note the deliberate divergence beside it, which is not a gap: ADR-0038 gives a crew admin who has not joined a room "crew-level things only" — they may not read its contents. Discord's administrator can read everything. Ours is the stricter choice and it is consistent with room-scoped privacy being architecture, but it will surprise anyone who expects Discord's behaviour, and the surprise should be designed for in #1023 rather than discovered.
Community data (inline, CommunityOne): 90 % of Discord servers have fewer than 15 members, and 86 % have fewer than 500. The overwhelmingly common case for a "server" — the object a crew imitates — is a group smaller than a single WattRoom room's comfortable voice size.
Two consequences:
- No evidence for a hard social ceiling on a crew was found in this pass, so no number for SPEC. What the distribution says instead is that the cap is not the interesting number: crews will be small whatever it is, and a cap exists to bound cost and blast radius, not to shape behaviour.
- ADR-0020's arithmetic survives better than expected. Its one-column sidebar rests on "Discord has forty servers of thirty channels. WattRoom has five rooms of five places"; ADR-0038 makes the tree three deep and asks for that to be re-argued. The distribution says the realistic shape is one or two crews of a few rooms, not forty of thirty — closer to the original arithmetic than to Discord's. #1023 should draw it before anyone concludes the depth forces a second strip.
Outside, the name is good and the alternatives are worse. In cycling, club and team carry established meanings — a club is the organization, a team is the group that races together and talks tactics (Cycle-Smart, Wikipedia: cycling club) — and both are already taken by the products riders use: Strava has clubs, Zwift has clubs. Crew is colloquial and carries no organizational or racing baggage, which is what this object wants: a group that hangs out and trains, not an entity that races. Reusing "club" would import an external meaning riders already hold for a different thing.
Inside, it collides, and ADR-0038 records this: docs/SPEC.md says "A room is a crew, not an attendance register", WATTROOM.md uses "Crew-level" for room-level collective goals, and crew-chief is a shipped medal slug earned for sessions in a room. The first two are prose the cutover rewords. The third stays, because an earned badge travels (ADR-0027) and renaming a slug is a migration over medals.
Not answered by this pass, and left to #1023 rather than guessed: what the private-room state is called, and what a crew admin is called. No external source settles either, and ADR-0020's rule against coining vocabulary makes it a design question, not a research one.
Add a crew owner (16.5)— resolved: ADR-0038 amended, and the migration supplies the row. Deletion turned out to force the design; the ADR has it.Decide one ban level or two (16.4)— resolved: both levels stay, and the single expression in (3) is what fixes the forgettable guard. See the note in 16.4 for why this section's own recommendation was not taken.- Build the single permission expression as a view (16.2), so 16.1's resolution order lives in one file. Promoted from advice to a requirement by the ban-levels decision — it is now the thing that stops (2) being a hazard.
- Carry the existing-rooms-migrate-private rule (16.3) as settled — it now has a regulator-tested precedent behind it, not just caution.
Both numbers were asserted in docs/SPEC.md and taken as locked by the code without a citation. A rider asked, after a real ramp test, whether either is defensible. Short answer: the 75 % has a basis and a known error band; the LTHR estimate is a rough midpoint that a field test replaces.
The ramp reaches maximal aerobic power (MAP) in its last sustained minute. The link from MAP to FTP was quantified by coach and sports scientist Ric Stern in the late 1990s: in the riders he tested, best ~1-hour power fell in 72–77 % of MAP for over 97 % of them, and 75 % is the midpoint every platform since has used (CycleCoach on the MAP ramp test; the same source on its validity as an FTP estimator). Trained endurance athletes span a wider 72–82 % (Roadman's protocol comparison).
What the band means for a rider: a fixed 75 % is a generalisation. A deeply aerobic rider with a modest one-minute peak reads low; a punchy rider with a big top end reads high (Cycling Weekly's coach's guide). The 20-minute test (0.95 × best 20 min) and the 8-minute test (0.90 × best 8 min) carry their own fixed factors with the same shape of error (Carmichael on the three tests).
Verdict. Keep 75 % as the default and say on the result panel that it is an estimate of ±5 %; the rider who cares can confirm with a 20-minute test, and the FTP-suggestion path (0.95 × best 20 min) already does that arithmetic from a hard ride. The rolling-60-second choice (SPEC) stays: it is what makes "best minute" mean the last full minute the rider held rather than a step boundary.
The literature places the second lactate threshold's heart rate at 85–92 % of maximum heart rate for most endurance athletes (RunnersConnect; PeakVO2), so 90 % sits inside the band. Two caveats make it a rougher number than the FTP factor:
- The ramp's peak is not necessarily HRmax. Heart rate lags power; a rider who blows on step 9 has not reached the heart rate they would on step 12. 90 % of a submaximal peak underestimates LTHR, and the error grows the earlier the test ends.
- The band is wide. ±3–4 % of HRmax is 6–8 bpm at 180 — a full zone boundary in the Coggan 5-zone table.
The measurement the field uses instead is Joe Friel's 30-minute time trial: ride 30 minutes alone as hard as sustainable, press lap at 10 minutes, and the average heart rate of the last 20 minutes is LTHR (Friel: determining your LTHR; Friel's zone guide on TrainingPeaks). It correlates well with lab-measured LTHR and has two decades of use; some coaches shave 3–5 % off for the 30-minute version against a 60-minute effort (Steel City Endurance's protocol).
Verdict. Keep the ramp's 0.90 × peak as what it already is in SPEC — a suggestion, one tap, never auto-applied — but label it a rough estimate, and offer the 30-minute field test as the way to a real number: the app records HR on every ride, so "average HR of the last 20 minutes of a 30-minute all-out ride" is one derived number away from a proper LTHR suggestion, the same shape as the FTP suggestion. That is a feature, not a docs change, and it is the honest upgrade path.
Stoat is Revolt renamed: an open-source Discord alternative, Rust backend, Solid.js client — and LiveKit for voice, which makes it the closest mirror WattRoom has for ADR-0020's "the app takes Discord's shape". Read for ideas; nothing copied (their client is a different framework and their backend is a different language, so the value is in decisions, not code).
ADR-0043 left one upgrade path open:
"an RNNoise/DTLN track processor on the local mic… a rider-side choice behind
the 95 % rule". That path has a ready-made implementation, so nobody needs to
derive it again: Stoat's VoiceProcessor.ts implements livekit-client's
TrackProcessor around livekit-rnnoise-processor (npm, v3.0.2 as of
2026-07), wrapping RNNoise's WASM build in an AudioWorklet with a Web Audio
chain of highpass → RNNoise → compressor → gain, rebuilt live when the setting
changes. mic-chain.svelte.ts is already that shape.
RNNoise itself is Xiph's 2017 hybrid suppressor: classic DSP splits each 10 ms frame into 22 Bark bands, a ~85 k-weight GRU outputs one gain per band, the DSP applies them. It cannot synthesise a voice, only attenuate bands, and it costs a fraction of a core.
It is parked, and the "bad voice on a fresh join" report (#2120) is not a reason to unpark it. A suppressor is bad consistently; that symptom improves over time, which makes it a convergence problem (AGC ramp, jitter buffer, AEC adaptation) that a second processor would not fix. The reasons ADR-0043 gave also still stand: RNNoise is nine years old, beaten by modern DNN suppressors on hard cases, close to redundant against a fan (the stationary case Chrome's suppressor already handled), and it eats heavy breathing — which in a cycling room is arguably signal.
The only non-upstream commits on stoatchat/livekit-server are
feat: Send webhook on mute and unmute, plus participant count and room
metadata on telemetry events. Worth knowing before anything server-side is
planned around authoritative mute state: upstream does not publish it, and
closing that gap is a fork, not a config flag. Our seam is the client reporting
setVoice(id, 'live' | 'muted' | null) (#151), and it should stay that way.
- #2121 — no
offlineconnection state. Theirdoc/src/components/client/session-lifecycle.mdspecifies a state machine every Stoat client must implement, with OFFLINE split from DISCONNECTED and permanent failure split from temporary. We are missing the OFFLINE node. - #2122 — SPEC bounds typed twice and drifting twice (#1393, #1986). Stoat
publishes every backend limit to the client as
client.limitsand makes mirroring mandatory; we have a better seam already (make protocol). - #2123 — file-drop hand-rolled three times. They mount one
FileDropAnywhereCollectoronce.
Per-rider volume with a 0–200 % fader lives in the person menu (#874, #463) —
their enableBoosting plus per-participant volume, in one control. Drafts
restore a refused line to the box on purpose (#1762). Unread dividers, context
menus, the GIF picker, sign-out-everywhere and reduced-motion handling are all
present.
- i18n. Stoat carries ~60 Lingui catalogs; we are English-only with strings inline in Svelte, and the retrofit cost grows weekly. Deferred with no issue (maintainer's call, 2026-09-11) — the alpha is not blocked on it and deciding early buys nothing.
- Per-crew identity (their
ServerIdentity— a different nickname and avatar per server). Runs against privacy-is-architecture and ADR-0036; not proposed, recorded here so the question is not mistaken for an oversight.
Research for #2993 and #2995. Two passes: search demand, competitors and AI-search visibility; and READMEs, social cards, Search Console and distribution. Tier: extracted (sourced, not adversarially verified). Keyword volumes are unverified: no tool publishes them. The demand signal is Google autocomplete (suggestqueries, 2026-09-26).
- As GPTBot saw it,
https://wattroom.ch/was a 5 KB shell: a title, a meta description,WebSiteJSON-LD and "Opening WattRoom…". - OpenAI's, Anthropic's and Perplexity's crawlers run no script (Vercel/MERJ, Dec 2024). Googlebot renders, after a queue.
/sitemap.xml,/favicon.ico,/llms.txtand any typo answered 200 with the shell. Those are soft 404s.- Google's documented fixes for a SPA are a JS redirect to a URL that 404s, or
noindex(JavaScript SEO basics). A server that knows its route segments can just answer 404 with the shell. - Google treats dynamic rendering as a workaround, not a recommendation (SEL). Prerendering at build time is what ADR-0061 does.
- Zwift already scales a group workout to each rider's FTP (forum). What it lacks is built-in voice, which riders have asked for for years (forum, 2025), and a private group workout goes through a Meetup (Zwift Insider).
- TrainerRoad has group workouts with voice and video: up to 11 riders, each on their own FTP, desktop apps only, every rider subscribed (TrainerRoad).
So "the only way to ride one workout on your own FTP" is false. What holds, as far as this search found, is the combination:
- free, and in the browser
- a standing crew space with text and voice channels
- one synced ERG workout started by anyone in the channel
- games decided by watts alone
- a shared jukebox
web/src/lib/site/rivals.ts carries the comparison facts with their sources, and says both corrections in its header.
| App | Price | Group story |
|---|---|---|
| Zwift | US$19.99/mo, $199.99/yr (DCR) | FTP-scaled group workouts; text chat; crews run Discord (Zwift Insider) |
| TrainerRoad | US$21.99/mo | Group workouts with voice and video, up to 11 riders |
| MyWhoosh | Free | Group rides and pacer-led workouts in a 3D world; text chat |
| Rouvy | €179.99/yr | Owned by Zwift since 29 Apr 2026, with FulGaz (DCR); in-ride chat is text (support) |
| icTrainer | $29.99/yr | Built-in video calls, individual zones; the German incumbent |
| dundring | Free, Apache-2.0 | Browser group sessions with live data, no voice; the closest open-source overlap |
| Auuki, BullWatt | Free, AGPL | Browser, solo |
BKOOL was retired into Rouvy on 30 Nov 2025 (Rouvy).
- "zwift workout with friends", "can you ride with friends on zwift". Best fit, low to medium difficulty. Target:
/group-workouts. - "does zwift have voice chat". Low difficulty. Answered in
/group-workouts' FAQ. - "create/custom group workout zwift", "zwift group workout meetup". Low difficulty.
- "free zwift alternative", "zwift alternative". High demand, high difficulty. Page one is publisher listicles, AlternativeTo, a vendor page, and one small site with a dated table and FAQ. Target:
/zwift-alternativeand/vs/*. - "zwift open source alternative". Low volume, low difficulty.
- "zwift chromebook" (7 autocomplete variants). Web Bluetooth ships on ChromeOS (status), but the page says "tell us" rather than claiming it untested.
- "ramp test online", "ftp test", "ftp calculator". Medium difficulty. Target:
/ftp-test, with a calculator. - "free erg mode app", "smart trainer app free". Target:
/smart-trainer-app. - German, for
hl=de, gl=ch: "zwift alternative kostenlos / ohne abo", "zwift mit freunden fahren", "indoor cycling app deutsch kostenlos". One German page with hreflang (/de), saying plainly that the app is in English.
"Indoor cycling with friends" returned no autocomplete. It stays hero copy, not a page target.
Google's review guidance asks for:
- first-hand evidence
- quantitative comparison
- pros and cons
- alternatives named
The pages built on it (/vs/*) add:
- a "we make WattRoom" disclosure
- prices linked to the vendor's own pages, with the date checked
- a "pick them if…" section that means it
- a trademark note
- Off-site mentions matter more than anything on the page. In Ahrefs' 75K-brand study, web mentions correlated 0.664 with AI visibility, backlinks 0.218, and YouTube mentions about 0.74. Hence the distribution list in LAUNCH.md.
- ChatGPT citations and Bing's top 10. One study found 87 % of ChatGPT citations in Bing's top 10 (Seer); a replication found 27 %. Uncertain, but Bing Webmaster Tools costs nothing.
- llms.txt is close to unused: 97 % of 137K files got zero requests in May 2026 (Ahrefs). Not built.
- FAQ rich results are gone. Restricted in 2023 and removed on 7 May 2026 (SEJ). The FAQs stay as visible text, which is what AI answers quote; there is no FAQPage markup.
- The software-app rich result needs
aggregateRatingorreview(Google). We have neither, and inventing one is what gets penalised.WebApplicationis marked up anyway so the entity is understood.
- What good product READMEs share (Excalidraw, Plane, Immich):
- a pitch in one line
- a row of links for users, not only contributors
- a captioned hero image
- one screenshot per feature
- self-host instructions
- dev setup below the fold
- GitHub markdown: dark and light images use
<picture>withprefers-color-scheme(GitHub blog). Use one or two alerts at most. - The repo's social preview is set by hand in the repo's settings. It should be at least 640×320, 1280×640 is best, and under 1 MB (docs).
- Share-card crops and limits:
- X shows only the image and a domain, so the message has to be inside the image (TechCrunch).
- WhatsApp wants under 600 KB (Meta).
- iMessage reportedly crops toward a square (unverified), hence the centred cards.
- Avoid WebP for Slack and Discord.
ADR-0076 parks the always-on open road behind a measured condition, and that
rests on how empty a road is at WattRoom's size. This is the model, its inputs
and its answer. scripts/road-density.py computes every number below; run it
to reproduce the table.
The model. The chance that someone else is on my 5 km of road, when R riders spread over stretches ridden with Zipf popularity p:
P(meet) ≈ 1 − exp(−(R − 1) / M_eff), with M_eff = 1 / Σ p²
M_eff is the effective number of stretches: how many equally popular stretches would give the same chance of company. For the async counterpart and the alpha instance, λ is the mean number of other riders on one road at a moment of prime time: rides a week × ride hours ÷ prime-time hours.
Inputs (facts, dated).
- Swiss roads: 85,151 km (BFS, 2025: https://www.bfs.admin.ch/bfs/de/home/statistiken/mobilitaet-verkehr/verkehrsinfrastruktur-fahrzeuge/streckenlaenge.html).
- Zwift roads: 408.5 km, or 834.7 km with Climb Portal and Gravel Mountain (https://zwiftinsider.com/how-many-km-of-road/, updated 2025-10-15).
- Zwift's peak: about 40,600 concurrent riders (https://the5krunner.com/2026/01/23/peak-zwift-2026-indoor-cycling-trends/, 2026-01-23).
Assumptions (guesses, each labelled; change them in the script).
- 100 WattRoom riders online at once, 40 of them solo on a road.
- Home roads: Swiss 5 km stretches ridden with Zipf popularity, exponent 0.5 (spread out) to 0.8 (bunched near where riders live).
- The library: 12 roads of about 20 km (4 stretches each), ridden with Zipf exponent 0.8; half of the solo road riders are on one.
- A col of the month draws 75 % of the library's riders.
- Zwift's stretches ridden with Zipf exponent 0.8.
- The alpha instance: 40 active riders, 3 one-hour rides a week each, 30 % of rides solo on the 12 library roads, 21 prime-time hours a week (three hours an evening).
The answer.
| Where | Result |
|---|---|
| Home roads (17,030 stretches) | 0.6–9 % chance someone else is on my 5 km |
| The 12-road library (20 riders) | about 46 % |
| A col of the month | about 93 % |
| Zwift at peak, spread evenly over 834.7 / 408.5 km | about 243 / 495 others per 5 km |
| Zwift at peak, Zipf 0.8 over 408.5 km | about 1,505 others per 5 km |
The alpha instance ADR-0076 quotes. 40 × 3 × 30 % = 36 solo library rides a week, 3 a road. λ ≈ 0.14, so at any given moment 87 % of those rides have nobody else on their road. Over the whole hour, counting anyone who starts within an hour either side, it is 75 %.
The async counterpart. Over 90 days those rides leave about 39 efforts on an average library road, and about 120 on the most popular one. Ghosts and times on a climb fill up; live company does not.
ADR-0076's reopen condition, in the same units. At least 60 solo rides a week on one road gives λ ≈ 2.9. Nobody else is there at a given moment only 6 % of the time.
What that leaves for strangers. At WattRoom's size a road is empty. A rider meets someone live only where riders are concentrated on purpose — a library climb, a col of the month, a scheduled open ride — and meets them far more often across time, as ghosts and times, than at the same moment. Zwift's roads are full because tens of thousands of riders share a few hundred kilometres, and no amount of design makes 40 riders on 85,000 km feel like that. The lab run that planned ADR-0076 quoted 0.5–12 %, about 49 % and about 500–2,000 with assumptions it did not record. The table above is the same model with the assumptions written down.
Question. Jan, 2026-11-02: the generated house radio is too repetitive. Could the lounge play real lofi instead, free to use inside a hosted app and in sync for everyone in the voice channel? Each licence below was read on its own terms page. No audio was downloaded. This is a reading of the terms, not legal advice.
Fits.
| Source | Licence | Credit | Self-host | Catalogue |
|---|---|---|---|---|
| HoliznaCC0 on FMA | CC0 1.0 | none | yes | 692 tracks; 1 h 28 min of lofi and chiptune albums counted by hand |
| Free Music Archive, per track | CC0 or CC BY (skip NC and ND) | CC BY: title, artist, FMA, licence, with links (FAQ) | yes; FMA's terms forbid deep-linking its audio | the Lo-fi Hip-Hop genre lists 24,251 tracks, no licence filter |
| Kevin MacLeod | CC BY 4.0 | "Title Kevin MacLeod (incompetech.com) Licensed under Creative Commons: By Attribution 4.0" plus the licence link, on a credits screen | yes, by CC BY 4.0 | little lofi; filler only |
FMA album pages tell the listener to check each track's own licence, so a track's licence field is checked one by one before it ships, even inside a CC0 album.
Does not fit.
- Pixabay: no credit needed, but the terms forbid distributing content "standalone". A radio plays tracks unchanged, which reads as standalone. Fits only if Pixabay confirms in writing.
- Chillhop: no use in apps or games without a paid licence; the creator terms cover YouTube and Twitch.
- Lofi Girl: free sharing on YouTube, TikTok, Twitch and Instagram only.
- StreamBeats: a sync licence for streams and videos; bans standalone redistribution and music-only radio.
- SomaFM: no third-party clients, no embedding in an app.
- Jamendo: API free for non-commercial use, no caching or offline copies, so no self-hosting; commercial radio is a paid licence.
Not verified. ccMixter (licence per track, no filter found), OpenGameArt (pages returned 403; Holizna's collections there are said to be CC0), Internet Archive (uploader-asserted licences, one "public domain" hit was a Nujabes track) and itch.io packs (claims seen only in search snippets).
How it would play: self-hosted files, not a stream URL. Every stream checked forbids app use, so only CC0 or CC BY files on our own server are open to us. Files also keep the lounge's sync: a fixed playlist whose track and offset follow from the server clock plays the same second on every screen, the way house radio and the jukebox's anchor already do. An Icecast-style stream buffers per listener and cannot seek, so riders would drift apart.
The jukebox already plays uploaded MP3s, but its pool is each rider's own uploads. A radio shelf would be new: tracks the operator places once (CC0 first, CC BY with a credits line in the deck), shared by every crew, picked by crew id and clock. Do that only after counting the hours: about 1.5 h is verified CC0 today, and a 3-hour evening would come round twice.
Shipped (2026-11-04). Records, house radio's default style, plays 44
HoliznaCC0 lofi hip hop tracks (1 h 59 min), each CC0 by its own FMA licence
field. scripts/house-radio.py checks the licence, evens loudness to −16 LUFS
and re-encodes to 96 kbps (86 MB); the tarball is the house-radio-1 release
asset, which the Dockerfile copies into the image by checksum. The credits
list is web/src/lib/lounge/records.json.
22. Why a call sounded bad, and what cleans it (research for the voice-quality reports; run of 2026-11-06)
Question. Jan, 2026-11-06: voices sound bad, the gate is bugged, noise is not cancelled at all, and it should sound like a good TeamSpeak. Everything below was measured on an Apple M2 Pro in Chromium 156 or Chrome 157, or read where a link says so. Scripts: web/e2e/voice-measure.spec.ts, scripts/voice-mixes.py, scripts/voice-measure.py. Tier: measured on synthetic speech (macOS say, which stops at 11 kHz) over synthetic fan, drivetrain and breath noise. No real voice, and no real mic: the listening is Jan's.
A WAV goes in as Chromium's fake mic, through the real chain and a local LiveKit, and is tapped after the capture, after the chain and at the listener. In a quiet room (noise −62 dBFS), against the clean speech:
| Stage | Speech | Peak | PESQ-WB |
|---|---|---|---|
| The mix going in | −26.0 dBFS | −12.1 | 3.22 |
| After Chrome's capture (AEC, AGC) | −22.4 | −8.8 | 3.26 |
| After our chain, as sent | −22.4 | −8.8 | 3.20 |
| At the listener | −22.3 | −8.9 | 3.19 |
So the chain was never what hurt a voice in a quiet room. Opus at 96 kbps, RED, the jitter buffer (30 to 60 ms) and the receive graph together cost 0.01 PESQ between sent and heard, nothing clips, and under 0.7 % of samples are concealed on a loopback. RED doubles the wire to about 192 kbit/s while the gate is open. Opus is negotiated with stereo=1, because livekit-client writes it into every offer (PCTransport.ts), so the rider's one channel goes out twice. Forcing it to one channel was not tried: that whole path costs 0.01, so there is nothing there to win.
TeamSpeak's channel codecs top out lower than this: Opus Voice at 7.71 KiB/s (about 62 kbit/s) and Opus Music at 11.87 KiB/s (about 95 kbit/s), by a TeamSpeak community thread. No official table exists. A good TeamSpeak setup sounds clean for its noise removal and its mic, not its bitrate.
- Nothing took noise out from under a voice. The browser's suppressor was off (ADR-0043), the light one was opt-in and capped at 10 dB, and the gate only chooses between the room and silence. At the listener, PESQ fell from 3.18 in a quiet room to 1.31 with a fan and 1.15 on the bike mix.
- A level gate cannot find a voice in that noise. It reproduced as Jan said. The automatic mark sits 12 dB over the quietest moment and stops at −26 dBFS. Breathing and the pedal stroke rise over it, so on the bike mix (speech 9 dB over the noise) it stayed open through 67 % of the pauses. At 4 dB it opened once and never closed in 86 s, because the room sat above the close mark. Keeping the close mark over the room (tried) moved that from 100 % to 99 %: the input is the fault, not the rule.
- The first sound of a word still arrived late. With the mark at −40 dBFS and worse over a fan, a soft "s" or "h" stayed under it. The gate opened up to 150 ms into a sentence, past the 10.7 ms lookahead, and the first 80 ms arrived 4.9 dB down.
Two things look like causes and are not ours to fix:
- Chrome's audio processing band-limits the capture. Any of AEC, AGC or noise suppression on stops the signal at 16 kHz on this Mac: broadband noise fell 16 dB at 14 to 16 kHz and 55 dB above that, which looks like a 32 kHz internal rate. Off, it runs to 22 kHz. Above 16 kHz a voice has little left, and AEC is the only thing between a rider on speakers and the call, so it stays.
- A Bluetooth headset's mic is 16 kHz. The default input here was a WH-1000XM5 at 16 kHz, and Chrome's default capture then stopped at 8 kHz: a phone call, in the mic, before any of our code. Measuring on Chromium's "default" fake device inherits that rate, which is why the rig pins Fake Input 1. The rider's own pick of a headset mic always wins (#4161), so a rider who picked one sounds like this.
The same mixes, offline, the same Wasm a browser runs, no gate. Noise in pauses and PESQ against the clean speech:
| Suppressor | Fan (15 dB) | Bike (9 dB) | Loud (4 dB) | Size | Cost per 10 ms |
|---|---|---|---|---|---|
| None | −41 dBFS, 1.23 | −35, 1.12 | −30, 1.07 | ||
| Our spectral one, 10 dB, with the gate | −51, 1.74 | −45, 1.31 | not run | in the bundle | |
Chrome's noiseSuppression, in the capture |
−54, 2.16 | −37, 1.38 | not run | in the browser | |
| RNNoise | −111, 2.97 | −92, 2.47 | −88, 1.86 | 157 KB | 1 to 2 ms, plain build |
| DeepFilterNet3, 100 dB limit | −72, 3.33 | −71, 2.90 | −66, 2.43 | 23 MB, 12 MB gzipped | 0.5 ms |
| DeepFilterNet3, 25 dB limit | −64, 2.93 | −59, 2.27 | −54, 1.75 | same | same |
- RNNoise (BSD): small and instant, 0.4 to 0.6 PESQ under DeepFilterNet3, and 0.5 dB down at 8 to 11 kHz on the fan mix where DeepFilterNet3 stays within 0.1 dB.
- DeepFilterNet3 (paper, MIT/Apache): full band at 48 kHz, real-time factor 0.19 natively on an i5-8250U. In Wasm on Apple silicon, others report 0.3 to 0.9 ms a frame (friendspeak, gwar). It adds 41 ms: 30 ms model, 10.7 ms to reframe 128-sample quanta into 480. Jan chose it for quality, 2026-11-06.
- GTCRN and DTLN run at 16 kHz and send nothing above 8 kHz, the fault this work is removing.
- Krisp needs LiveKit Cloud and a proprietary licence, §12. Chrome's
noiseSuppressionis what ADR-0043 turned off, and the numbers agree with it: it leaves the bike mix's noise where it was, and takes 1.7 dB (fan) to 3.7 dB (bike) off the voice at 8 to 11 kHz.voiceIsolationreports[false]on macOS Chrome 157. - The desktop shell gains nothing here: Electron is the same Chromium with the same Wasm, and the app's own suppressor needs no switch.
The package is @workadventure/noise-suppression (MIT), which wraps libDF in an AudioWorklet and watches its load. It needs 'wasm-unsafe-eval' in script-src, checked against the real server's CSP: compile 198 ms, model ready 248 ms later, no violation. The model load holds that context's audio thread for about 240 ms, once per open mic (the worst gap between gate posts). Behind a live track, every listener concealed 17,000 samples and held a jitter target of 55 to 60 ms against 25 to 38 ms without the model, in three pairs of runs. So an open waits up to 1 s for it before it publishes. Five calls after that concealed 0.01 to 0.1 % of samples, and one bike run 1.1 %, with every packet sent and this machine at a load average of 23. Without the model the same rig showed 0 to 0.7 %. A compiled module reaches a worklet only through processorOptions; SharedArrayBuffer would need COOP and COEP, which break the YouTube player, and nothing here needs it.
The attenuation limit is a listening call. 100 dB scores best, and the package's listening tests found it gates the room to silence between words and leaves a metallic edge. 40 dB scored PESQ 3.01 on a fan against 3.13 and 2.81 at 25 dB. The call hears a noise floor 40 dB down, which is under −80 dBFS on a fan and is shipped.
Real call, real chain, last whole loop, at the listener:
| Scene (speech over noise) | PESQ-WB | Noise in pauses | Gate, opens and closes | Latest word start |
|---|---|---|---|---|
| Quiet (36 dB) | 3.19 → 4.04 | −61 → −89 dBFS | 13, 12 → 13, 12 | 59 → 43 ms |
| Fan (15 dB) | 1.31 → 3.19 | −45 → −83 | 12, 12 → 14, 13 | 153 → 40 ms |
| Bike: fan, drivetrain, breath (9 dB) | 1.14 → 2.72 | −38 → −78 | 12, 12, open 71 % → 14, 13, open 63 % | 157 → 49 ms |
| Loud (4 dB) | 1.07 → 2.29 | −30 → −72 | 1, 0, open 100 % → 14, 13, open 63 % | never shut → 80 ms |
The speech level stays at −26.5 dBFS with peaks at −13 and nothing clipped, and the 8 to 11 kHz band stays within 0.3 dB of the clean speech. Fourteen opens is one per sentence over the two loops, so the gate no longer reads the room at all.
The gate reads what the model leaves, so its mark sits at the new −50 dBFS floor in every scene and it opens and closes once per sentence. That floor is what brings word starts forward: the first 80 ms of a word arrive within 1 dB of the clean speech, where a fan cost up to 4.9 dB.
A handheld runs no gate and no model (#2142), so its call carried the whole room. It now captures with the browser's noiseSuppression. Real call, a sender whose pointer reads coarse, last whole loop, at the listener, without → with:
| Scene (speech over noise) | PESQ-WB | Noise in pauses | Speech | First 80 ms of a word | STOI |
|---|---|---|---|---|---|
| Quiet (36 dB) | 3.25 → 3.69 | −59 → −76 dBFS | −22.4 → −22.5 | −0.2 → −0.7 dB | 0.998 → 0.997 |
| Fan (15 dB) | 1.24 → 2.17 | −42 → −54 | −26.1 → −22.7 | 0.3 → −2.2 | 0.933 → 0.927 |
| Bike (9 dB) | 1.13 → 1.39 | −35 → −38 | −25.9 → −23.0 | 0.7 → −2.5 | 0.869 → 0.885 |
| Loud (4 dB) | 1.07 → 1.16 | −30 → −34 | −24.8 → −23.8 | 2.5 → −1.5 | 0.817 → 0.808 |
A fan drops 12 dB and the bike mix barely moves, so a phone in a loud room stays well behind the desktop chain's 2.72 and 2.29. STOI, the intelligibility score, moves by 0.02 at most, and nothing clips. AGC lifts the speech about 3 dB on the fan and bike mixes. The first sound of a word comes out about 2.5 dB softer, and the 8 to 11 kHz loss from §22.3 stays.
These numbers are Chrome's suppressor on this Mac. A phone may run its platform's own processing instead, so they say which way the change goes and not what a phone sounds like. The constraint is a bare value, which the spec treats as ideal, so a browser that cannot honour it still opens the mic.
Report after noise cancellation shipped: voices sound over-cancelled while music, the radio or a video plays. Noise cancellation is not the cause. The echo canceller is.
Chrome's default echoCancellation: true is Chrome-wide echo cancellation (kChromeWideEchoCancellation, enabled by default): its reference is the output device, so it holds everything the browser plays. With --mute-audio, true cancelled nothing here, so the rig cannot run this path without sound leaving the Mac. To reproduce it, music played through a remote track into an element under remote-only, which puts it in the same canceller's reference silently. Raw capture through the real model and gate, offline, speech at −26 dBFS:
| Case | PESQ-WB | STOI | First 80 ms of a word |
|---|---|---|---|
| No music | 4.40 | 0.999 | −0.3 dB |
| Headphones: music in the reference, none in the mic | 1.58 | 0.815 | −7.2 |
| Same, music 12 dB quieter | 3.02 | 0.944 | −4.4 |
| Speakers: music in the reference and at −30 dBFS in the mic | 1.24 | 0.516 | −14.4 |
| Speakers: a song, same level | 1.37 | 0.702 | −47.7 |
| Speakers: music at −30 dBFS, not in the reference | 3.06 | 0.973 | 0.1 |
| Speakers: a song at −30 dBFS, not in the reference | 1.38 | 0.852 | 3.8 |
The canceller suppresses wherever it expects echo, so it takes the voice under the music, on headphones too. It had not stopped after 80 s. The damage follows the music's level. Instrumental music in the mic is noise to the model. A singer is speech to it, so a song leaks at −31 dBFS into the pauses and lifts the automatic mark to its ceiling. That leak is what a rider on speakers now pays, and it costs less than the words: STOI 0.85 against 0.70.
remote-only keeps music out of the reference. It only counts audio an element plays, and a remote track played through WebAudio is not in it, so voices would come back. createMediaElementSource does not help: WebMediaPlayerMS has no audio provider, so the element goes on playing and reads silence. The element itself has to play. Echo of a voice at −30 dBFS, by element volume:
| Element volume | Echo left in the mic |
|---|---|
| 1 | −81 to −95 dBFS |
| 0.2 | −75 to −90 |
| 0.1 | −33, none cancelled |
| 0.03 | −33, none cancelled |
The reference has to sit over a level the canceller reacts to, somewhere between −46 and −40 dBFS for this voice. 2026.11.24 played each voice's element at 0.2 beside the graph; §22.8 replaced that copy with the element as the voice's only path. A share stays out because it is music. In a real call through LiveKit, a second rider's mic carrying the first rider's voice at −26 dBFS sent it back at −24 dBFS without that copy. With it the echo reached −56 dBFS within 10 s and sat between −56 and −81 after that.
A mic test keeps true: it plays the rider back through WebAudio, and on speakers nothing else stops that howling. A handheld keeps true too, because its voices never reach an element at any volume.
truewith music in its reference on real speakers. The table reproduces it with the same canceller by another route.- A real phone, with its own mic and its own processing.
- A real mic, a real fan, a real voice: synthetic speech stops at 11 kHz, and a neural model may treat a real rider's breathing differently.
- Chrome's AEC under double-talk on speakers (a rider talking over the crew) needs a real speaker in the loop. It is the suspected cause of voices cutting out on speakers (#4339's note).
- Chrome's input volume control moving a real mic's gain: the fake device has none.
- A slower machine than an M2 Pro. The overload check falls back to the gate at 70 % of real time for 4 s.
Report the morning after 2026.11.24: riders did not hear each other, or heard a voice twice or strange, and restarted the app to fix it. LiveKit's log of that call (10:00 to 10:52 UTC, three riders, all on the desktop app) shows the mic republished six times within a session and ten restarts, nine of them inside six minutes. Every unmute publishes a new mic track, because a muted mic holds no capture (#4177). Twice the old track's subscription outlived it, and once the new track was published before the old one left.
Two causes, both in how a listener plays a voice:
- The old track's goodbye took the new voice. A listener keys a rider's voice by connection, and the new track can arrive before the old one leaves. The old one's unsubscribe then dropped the graph the new one had just built and set the rider to muted. Since 2026.11.24 the element still played its 0.2 copy, so that rider was faint, without a fader or a speaking ring, rather than silent. It held until the next republish or a restart. A seat is now owned by its track, the way pictures already were. LiveKit also detaches a track's elements before it says the track is gone, so the handler's own
detach()found nothing, and every unmute left a dead<audio>element behind: the rig counted nine after eight unmutes. - Two copies of every voice. The graph reads a stream through
WebAudioMediaStreamAudioSink, whose FIFO holds six batch reads (source): the graph trails the element by whatever that FIFO holds, a different amount after every join, with drops and gaps where the two clocks part. Both audible is the phaser of #1339. At 0.2 it was quieter, and it was back. On a computer a voice now plays from its element alone, at the rider's fader, and the graph only meters it. That is also exactly whatremote-onlyhears. A fader above 100 % moves the voice to the graph, becausevolumestops at 1, and the canceller loses it.
Echo from a rider on speakers, the §22.6 call (B's mic carrying A's voice at −26 dBFS), level B sends per 5 s:
| B's elements | Echo sent back |
|---|---|
| Silent, no reference | −19 to −28 dBFS throughout |
| 0.2 copy (2026.11.24) | −25, −42, −63, then −69 to −85 |
| One path, a clean run | −43, −69, −53, then −67 to −84 |
Two of three one-path runs stalled (concealment, and about 100 ms taken out of the jitter buffer), and the echo then leaked at −20 to −28 dBFS for 5 to 15 s. The rig's echo is a second playback of the file, so a jitter-buffer jump moves it against the reference. Real echo moves with the reference.
Not reproduced: the order flip on a local LiveKit. Eight unmutes over loopback all arrived in order, so a unit test pins the flipped order instead. The doubled sound was never heard here: --mute-audio keeps the element's output out of reach.
Question. Jan, 2026-11-12: a Zwift Click, Play or Ride reaches WattRoom only
through BikeControl speaking OpenBikeControl (OBC), which is a second app to
install, start and pair. Could WattRoom talk to these controllers itself, from
the browser or from the desktop shell? This builds on §11's revision of
2026-09-29 and on ADR-0084 (in git, docs/decisions/0084-wattroom-shifts.md
before #4318), whose rule 4 is WATTROOM.md's "no Zwift protocol". Not legal
advice.
Short answer: don't build a Zwift driver; keep BikeControl and say what it costs. A third party can still read the older models and firmware (Click v1, the 2024 Ride, a Play before 2.0.1). Click v2 and Ride v2 are locked to Zwift's app by a daily unlock that only Zwift's app can perform. Reading even the open ones means speaking ZAP, which ADR-0084 keeps out for patent reasons.
- Click v2's lock is server-side and daily. BikeControl's author, 2025-11-22: "Zwift's new encryption is server-side and difficult to work around" (#68). Without it a Click v2 sends button events for about a minute after it connects. Connecting it in Zwift's own app (no subscription needed) unlocks it for about 24 hours. The unlock is a vendor message (opcode 0xFF04) that differs on every connection; replaying it does nothing (same thread, 2025-09-30).
- Ride v2 is locked too. BikeControl's guide (2026-05-14, updated 2026-09-28) gives Ride v2 firmware 1.3 and later the same daily unlock: "the daily unlock with the Zwift app is currently the way to use a Ride V2 outside Zwift."
- Ride moved its service. A January 2025 Ride firmware replaced
00000001-19ca-4651-86e5-fa29dcdd09d1with the 16-bit UUID0xFC82(Makinolo, Ride protocol, updated 2025-01-31). - Play joined the newer line. Play firmware 2.0.1 (2026-05-27) merges the two controllers into one Bluetooth connection "in line with the Click v2 and Zwift Ride controllers" (Zwift Insider). Whether it also took the daily lock is not published; we found no report either way.
- Zwift owns the one third-party app that read them. Rouvy reverse-engineered the protocol in February 2025 (DC Rainmaker). Zwift bought Rouvy on 2026-04-29, and Rouvy's 2026/27 update lists Cog, Click and Ride as compatible (bike-magazin, 2026-09-02). That is first-party support. We found no SDK, licence programme or published spec for anyone else.
- Zwift's terms name this. The Terms of Service of 2026-06-02, §5(a)(ix), forbid users to "bypass, or tamper with authentication measures, firmware, or software of any Platform connected devices, including any action intended to circumvent security measures of connected devices to interact with, transmit data to, or be controlled by any platform, application, or service other than the official Zwift Platform" (terms). §5(a)(xiii) adds "applications that emulate or redirect the communication protocols used by Zwift in any way."
- BikeControl costs a rider money. A 5-day trial (7 on Windows), then 15 button actions a day until the rider buys Base (about $4.99 per platform, free on Linux) or Pro, a subscription (bikecontrol.app, read 2026-11-12). Its licence is now a non-commercial one; versions before the
gpl3tag stay GPL-3.0 (LICENSE).
| Controller | BLE service | Handshake | Encryption | Third party today |
|---|---|---|---|---|
| Click (v1) | 00000001-19ca-… |
"RideOn" | optional; runs without | yes; replaced by Click v2 (2025-09) |
| Play, firmware before 2.0.1 | 00000001-19ca-…, two devices |
"RideOn" + 01 02 + a P-256 public key | ECDH P-256, HKDF-SHA256, AES-CCM (Makinolo) or AES-GCM (ajchellew): the two accounts disagree | yes, with the crypto |
| Play, firmware 2.0.1 | one connection | not published | not published | unknown |
| Ride (2024) | 0xFC82 since 2025-01 (before: 00000001-19ca-…) |
"RideOn" | none | yes |
| Click v2; Ride v2 at firmware 1.3+ | same family | "RideOn", then Zwift's vendor message | server-side, renewed every ~24 h | only after the rider unlocks it in Zwift's app that day |
- All of them speak ZAP behind the handshake: protobuf messages on a three-part link (Measurement notify
…0002, Control Point write…0003, Command Response indicate…0004). Ride buttons are message 0x23, a 32-bit little-endian bitmap, active low; the two orange paddles are analog, −100 to 100; haptics use the Play's command (Makinolo, Play, 2023-10-08; Ride, above). Zwift's company ID is 0x094A. - Makinolo's pages are prose with no licence and say "no information contained in this document is official." Nothing is documented by Zwift.
- WebCrypto has ECDH P-256 and HKDF but no AES-CCM (W3C Web Crypto), so an encrypted Play would need CCM built on AES-CTR plus a CBC-MAC, or a library.
Who implements it, and under which licence (pointers; none of this may be copied into WattRoom while rule 4 holds):
- ajchellew/zwiftplay: Android and .NET, Play handshake and decryption. No licence, so all rights reserved. Last push 2024-02.
- jat255/zwift_click_handling: Python, Click v1 without encryption ("I couldn't get that part working"). MIT, 2024.
- qdomyos-zwift (
src/zwift_play): GPL-3.0. - BikeControl: Click, Click v2 with the unlock bridge, Play, Ride. Non-commercial licence. Read for comments and UUID constants only, as for #3335.
- Auuki: AGPL-3.0, carries the Zwift service in its Web Bluetooth layer. Named only; not opened.
| Where WattRoom runs | Web Bluetooth | Zwift controllers directly | BikeControl today |
|---|---|---|---|
| Chrome / Edge, macOS and Windows | yes | the open ones; a Play before 2.0.1 or a Click v2 is two choosers, one per side | OBC over BLE, BikeControl on a phone |
| Chrome, Linux | only behind the experimental-features flag, BlueZ 5.41+ (status) | same, with the flag | same, with the flag |
| Chrome, Android | yes | the open ones | OBC over BLE from a second phone; BikeControl on the same phone cannot reach the browser |
| iOS, any browser | no (WebKit has no Web Bluetooth) | no | no; the phone is the remote |
| Desktop shell, Web Bluetooth | as Chrome, through select-bluetooth-device (desktop/bluetooth.js) |
as Chrome | OBC over BLE, and OBC over the network (#3336) with BikeControl on the same computer |
| Desktop shell, a native module | @stoprocent/noble (MIT, active): native macOS and Windows bindings, BlueZ over D-Bus without root. @abandonware/noble (MIT, last push 2025-02) needs a WinUSB dongle on Windows and raw-socket privileges on Linux | as Web Bluetooth, plus Linux without the flag and no chooser per side | — |
- Neither Zwift UUID is on the Web Bluetooth blocklist (gatt_blocklist); HID (0x1812) is. So BLE-HID buttons never reach a page as BLE, only as keys when they act as a keyboard.
- The shell passes no switch that enables Web Bluetooth on Linux (
desktop/main.js). Whether its Linux build pairs anything at all is untested; that is a hardware question for all of BLE, not for this one. - A native module reaches no controller that Web Bluetooth cannot. It gains Linux without the flag and one pairing for a two-sided controller, and it loses the chooser, which §15.1 keeps so that a rider never silently pairs someone else's device, and it adds a native build per OS to sign.
- The lock is the same on every platform. Transport does not matter for a Click v2.
- Other controllers: Shimano Di2 (D-Fly), SRAM AXS and eTap, Wahoo KICKR Bike shifters, CYCPLUS BC2, Thinkrider VS200, Magene Onelap, Elite Sterzo and Square, Stages SB20, cheap BLE and classic HID buttons (README). A Zwift driver removes BikeControl only for riders whose one controller is an open Zwift one.
- The Click v2 / Ride v2 unlock. BikeControl advertises a bridge that Zwift's app connects to and unlocks the controller through, and it keeps the 24-hour window. Doing that ourselves is exactly what ToS §5(a)(ix) names.
- Firmware churn. Zwift has changed the service UUID, the connection count and the lock in two years. BikeControl tracks it; we would chase it.
- Ride's analog paddles. OBC carries analog (brake 0x1A, steering 0x1B). WattRoom uses neither, so nothing is lost today.
- Haptics. WattRoom already sends OBC Haptic Feedback (
controller.ts,feel). Whether BikeControl passes it on to a Zwift controller's motor was not checked. - Not lost: keys and the phone remote are WattRoom's own inputs (ADR-0084, "Inputs"), and gamepads, if ever, would come through the browser's Gamepad API, not BikeControl.
- It reaches a shrinking set. Click v1 is replaced; Click v2 and Ride v2 are locked; Play 2.0.1 is unknown. The rider who asked is most likely holding a Click v2, the one bundled with today's Cog trainers (DC Rainmaker, 2025-09), and a direct driver would still send them to Zwift's app every day, or to BikeControl.
- It breaks rule 4. ADR-0084 rejected ZAP because US 12,465,816 claims a three-part link of ZAP's shape, and the controllers use that same notify / write / indicate trio. The pending 19/234,077 (EP4670807A1), Zwift's own application on controller pairing, claims an input device that sends the game client a bitmap of the inputs it supports; OBC runs the other way. A ZAP reader is the app end of both. Their status was not re-read for this question.
- The terms. For the open controllers there is nothing to circumvent, and WattRoom is not a party to Zwift's terms. A rider is, and §5(a)(xiii) reads on "applications that emulate or redirect the communication protocols used by Zwift". For the locked ones, any route other than the rider unlocking in Zwift's app is circumvention under §5(a)(ix), and in the US a question under 17 USC §1201 as well.
- The cost is not one driver. A handshake, a protobuf decoder, an optional AES-CCM, two-sided devices, a stall detector for locked firmware, and a hardware report per controller and firmware, all of it for code Zwift can break with an over-the-air update.
Revisit when Zwift publishes the controller protocol or a licence for it, or Rouvy's support turns into a programme others can join; or a granted 19/234,077 or '816 continuation is read and leaves a controller reader outside it.
Keep BikeControl as the bridge. Most of the short path already exists: the Controllers section in settings (#4236) explains BikeControl's keystroke mode, the sensor overview points a Zwift rider there, and the desktop shell's Network shifter pairs the first BikeControl it hears (#3336). What the copy does not say is what §23.1 found. The two issues below would be filed for that. They touch no Zwift protocol and need no change to WATTROOM.md.
fix(web): the Controllers section says what BikeControl costs and that a Click v2 locks daily Context: #4540, RESEARCH.md §23. A rider who installs BikeControl on the strength of "BikeControl bridges them" meets a 15-press daily cap after the trial, and a Click v2 or Ride v2 that goes quiet after a minute. Scope: two lines in "Zwift Click, Play and Ride" (
settings/equipment/Controllers.svelte): BikeControl is free to try, then a one-time Base purchase per platform (free on Linux); a Click v2 or a Ride v2 must be opened in Zwift's app once a day (no subscription), or set to BikeControl's one-side mode. No prices in the copy, which go stale; link BikeControl's own page. No Zwift UUID or detection in the code. Acceptance: the section reads right at phone width; the link opens.
test(desktop): does the Linux shell pair BLE at all (
needs-human-input) Context: Chrome enables Web Bluetooth on Linux only behind a flag, and the shell passes none (§23.3). Scope: a hardware report from a Linux machine: a trainer, a heart-rate strap and BikeControl as an OBC controller, through the shell's chooser. If it fails, a follow-up adds the switch on Linux only.
If Jan overrides and wants a direct driver, these come first, in order:
docs: amend "no Zwift protocol" for a read-only controller reader Scope: WATTROOM.md's gears line and ADR-0084 rule 4 narrowed to "never sends Zwift-format gear commands, never a trainer-side ZAP"; read US 12,465,816's claims and 19/234,077's current claims against a reader that only receives button bitmaps; record Jan's decision and the risk he accepts, as ADR-0084 did. Nothing below starts before this merges.
feat(ble): Zwift Click v1 and Ride over Web Bluetooth, its own input switch Scope:
createZwiftController()beside the OBC controller, behindgearsEnabled()'s ownzwiftswitch; filter on Zwift's company ID 0x094A, optional services0xFC82and00000001-19ca-…; unencrypted "RideOn" handshake; decode message 0x23's active-low bitmap to Harder/Easier and Talk; haptics by the Play command; a lost link drops every hold. Written from Makinolo's prose only, fixtures from his published bytes; nothing from BikeControl, qdomyos-zwift, ajchellew or Auuki. Play waits for its own issue (crypto, or 2.0.1 once documented). The Controllers section's "never show under Shifter" changes with it. Acceptance: fixture tests; the desktop chooser pairs it; a hardware report per controller and firmware.
feat(ble): a locked Zwift controller says so instead of going quiet Scope: a Click v2 or Ride v2 that stops sending events after connecting is shown as "Locked by Zwift: open the Zwift app once today, or pair it through BikeControl." WattRoom never sends the vendor message and never bridges for Zwift's app. Acceptance: a fixture of a silent controller produces the hint, never a failed shift.
Kickr v2 lacks FTMSResolved → planned work — confirmed the v2 is WCPS-only; full protocol mapped (§9) and the WcpsTrainer driver is now M1 scope. Residual risk (low): protocol facts come from reverse-engineered implementations, not Wahoo docs — verify against the real v2 early in M1.- YouTube jukebox TOS (high, confirmed) — RMF constraints reshape the room UI (always-visible ≥200×200 player, no overlays, no audio-only). Coordinated sync itself appears tolerated in practice (Watch2Gether-class apps); embed-disabled music content is the practical annoyance.
- ERG↔SIM switching is firmware-sensitive (medium, evidenced) — Wahoo fixed a 2 kW power spike on exactly this transition in 2024. Sprint-moment code should ramp into slope mode and treat the transition defensively.
- LiveKit on shared Natron cluster (medium, confirmed constraint) — hostNetwork + public UDP on node IPs on a company cluster; revisit before widening.
- Strava API terms drift (medium, materialized June 2026 — see §13.5) — the predicted drift happened: Standard Tier (any >1-athlete app, including our existing auto-upload) now requires the developer to hold a paid Strava subscription, and the AI clause broadened to ban LLM context-window ingestion of Strava data. Upload math otherwise unchanged; Extended review still gates public widening. WATTROOM.md's Nov-2024 framing is stale.
- Web Bluetooth = Chromium forever (low, accepted) — Safari's explicit refusal caps the platform; already a locked decision.