From 582ef5aba2e2b4b103052dd3728b4e6e14f4dd97 Mon Sep 17 00:00:00 2001 From: Claude Agent Date: Thu, 5 Nov 2026 10:45:33 +0000 Subject: [PATCH] feat: broadcast global mute state to all participants over data channel (#678) Extend the existing advisory remote-mute directive so an admin's mute is reflected in every participant's list, not just the mute target. When an admin mutes a participant, in addition to the existing targeted self-mute directive we broadcast an EndpointMessage mute-state message (muteState + participantId) to all endpoints. Each client parses it and stores per-endpointId advisory mute state in call state (participantMuteState), which the participant list renders as a muted indicator. Enforcement stays advisory, matching the already-merged behaviour: the broadcast only mirrors what an admin asked for and is not server-enforced. Authoritative/server-enforced mute with backend persistence and self-unmute prevention (option (b) in #678) is a deferred follow-up product decision and is documented as out of scope in the code. Co-Authored-By: Claude Opus 4.8 --- .../data-channel-parser.test.ts | 84 +++++++++++++++++++ .../ui/production-line/data-channel-parser.ts | 59 ++++++++++++- .../ui/production-line/production-line.tsx | 26 ++++++ .../use-rtc-connection.test.ts | 32 +++++++ .../ui/production-line/use-rtc-connection.ts | 18 +++- .../ui/production-line/user-list.tsx | 30 ++++++- src/global-state/global-state-actions.ts | 9 ++ src/global-state/global-state-reducer.test.ts | 58 +++++++++++++ src/global-state/global-state-reducer.ts | 18 ++++ src/global-state/types.ts | 6 ++ src/hooks/use-initiate-production-call.tsx | 1 + 11 files changed, 337 insertions(+), 4 deletions(-) diff --git a/src/components/ui/production-line/data-channel-parser.test.ts b/src/components/ui/production-line/data-channel-parser.test.ts index 8db2276a..6d0de6b9 100644 --- a/src/components/ui/production-line/data-channel-parser.test.ts +++ b/src/components/ui/production-line/data-channel-parser.test.ts @@ -3,6 +3,7 @@ import { parseDataChannelMessage, isRemoteMute, isForceDisconnect, + getMuteStateBroadcast, type EndpointMessage, } from "./data-channel-parser.ts"; @@ -73,6 +74,36 @@ describe("parseDataChannelMessage", () => { } }); + it("parses a global mute-state broadcast (#678)", () => { + const data = JSON.stringify({ + type: "EndpointMessage", + payload: { muteState: "mute", participantId: "ep-9" }, + to: "", + from: "ep-admin", + }); + + const result = parseDataChannelMessage(data); + + expect(result.type).toBe("EndpointMessage"); + if (result.type === "EndpointMessage") { + expect(result.payload.muteState).toBe("mute"); + expect(result.payload.participantId).toBe("ep-9"); + } + }); + + it("returns unknown when muteState is present but participantId is missing", () => { + const data = JSON.stringify({ + type: "EndpointMessage", + payload: { muteState: "mute" }, + to: "", + from: "ep-admin", + }); + + const result = parseDataChannelMessage(data); + + expect(result.type).toBe("unknown"); + }); + it("returns unknown for invalid JSON", () => { const result = parseDataChannelMessage("not json at all"); @@ -149,6 +180,59 @@ describe("isRemoteMute", () => { }); }); +describe("getMuteStateBroadcast", () => { + it("returns participantId and muted=true for a mute broadcast", () => { + const msg: EndpointMessage = { + type: "EndpointMessage", + payload: { muteState: "mute", participantId: "ep-9" }, + to: "", + from: "ep-admin", + }; + + expect(getMuteStateBroadcast(msg)).toEqual({ + participantId: "ep-9", + muted: true, + }); + }); + + it("returns muted=false for an unmute broadcast", () => { + const msg: EndpointMessage = { + type: "EndpointMessage", + payload: { muteState: "unmute", participantId: "ep-9" }, + to: "", + from: "ep-admin", + }; + + expect(getMuteStateBroadcast(msg)).toEqual({ + participantId: "ep-9", + muted: false, + }); + }); + + it("returns null for a targeted self-mute directive (no broadcast fields)", () => { + const msg: EndpointMessage = { + type: "EndpointMessage", + payload: { muteParticipant: "mute" }, + to: "ep-1", + from: "ep-2", + }; + + expect(getMuteStateBroadcast(msg)).toBeNull(); + }); + + it("does not report a mute-state broadcast as a remote self-mute or kick", () => { + const msg: EndpointMessage = { + type: "EndpointMessage", + payload: { muteState: "mute", participantId: "ep-9" }, + to: "", + from: "ep-admin", + }; + + expect(isRemoteMute(msg)).toBe(false); + expect(isForceDisconnect(msg)).toBe(false); + }); +}); + describe("isForceDisconnect", () => { it("returns true when forceDisconnect is disconnect and to !== from", () => { const msg: EndpointMessage = { diff --git a/src/components/ui/production-line/data-channel-parser.ts b/src/components/ui/production-line/data-channel-parser.ts index 17990787..2dbcd81d 100644 --- a/src/components/ui/production-line/data-channel-parser.ts +++ b/src/components/ui/production-line/data-channel-parser.ts @@ -10,11 +10,30 @@ export type DominantSpeakerMessage = { export type EndpointMessage = { type: "EndpointMessage"; - payload: { muteParticipant?: string; forceDisconnect?: string }; + payload: { + muteParticipant?: string; + forceDisconnect?: string; + // Advisory global-mute state broadcast (#678). `muteState` is "mute" | + // "unmute" and `participantId` is the endpointId the state refers to. This + // is broadcast to ALL endpoints so every client can reflect the mute state + // in its participant list; it is distinct from `muteParticipant`, which is + // a targeted directive telling a single endpoint to mute its own input. + muteState?: string; + participantId?: string; + }; to: string; from: string; }; +/** + * Result of parsing a global-mute-state broadcast (#678): which participant the + * state refers to (by endpointId) and whether they are now muted. + */ +export type MuteStateBroadcast = { + participantId: string; + muted: boolean; +}; + export type ParsedDataChannelMessage = | DominantSpeakerMessage | EndpointMessage @@ -55,7 +74,11 @@ export const parseDataChannelMessage = ( (("muteParticipant" in message.payload && typeof message.payload.muteParticipant === "string") || ("forceDisconnect" in message.payload && - typeof message.payload.forceDisconnect === "string")) + typeof message.payload.forceDisconnect === "string") || + ("muteState" in message.payload && + typeof message.payload.muteState === "string" && + "participantId" in message.payload && + typeof message.payload.participantId === "string")) ) { return message as EndpointMessage; } @@ -76,3 +99,35 @@ export const isRemoteMute = (msg: EndpointMessage): boolean => */ export const isForceDisconnect = (msg: EndpointMessage): boolean => msg.payload.forceDisconnect === "disconnect" && msg.to !== msg.from; + +/** + * Extract an advisory global-mute-state broadcast (#678) from an + * EndpointMessage, or `null` if this message is not a mute-state broadcast. + * + * This is the receive side of option (a) from issue #678: an admin broadcasts + * the mute state of a participant to every endpoint so each client can show the + * correct mute indication in its participant list. It carries NO enforcement — + * the model is intentionally advisory, matching the already-merged + * `muteParticipant` directive, which only asks the target to mute itself. A + * muted participant can still unmute locally; nothing here prevents that. + * + * Deferred follow-up (option (b), out of scope for #678): an + * authoritative/server-enforced mute that persists per-participant admin-mute + * state in the backend and prevents self-unmute. That requires a new product + * decision and is intentionally NOT implemented here. + */ +export const getMuteStateBroadcast = ( + msg: EndpointMessage +): MuteStateBroadcast | null => { + if ( + typeof msg.payload.muteState === "string" && + typeof msg.payload.participantId === "string" + ) { + return { + participantId: msg.payload.participantId, + muted: msg.payload.muteState === "mute", + }; + } + + return null; +}; diff --git a/src/components/ui/production-line/production-line.tsx b/src/components/ui/production-line/production-line.tsx index d57ef8e6..d84f9fde 100644 --- a/src/components/ui/production-line/production-line.tsx +++ b/src/components/ui/production-line/production-line.tsx @@ -145,6 +145,7 @@ export const ProductionLine = ({ dataChannel, isRemotelyMuted, isRemotelyDisconnected, + participantMuteState, } = callState; const { isActiveParticipant } = useActiveParticipant( audioLevelAboveThreshold @@ -634,6 +635,8 @@ export const ProductionLine = ({ }); const muteParticipant = () => { + // Targeted advisory directive (already merged behaviour): asks the single + // target endpoint to mute its own input. const msg = JSON.stringify({ type: "EndpointMessage", to: userId, @@ -642,8 +645,30 @@ export const ProductionLine = ({ }, }); + // Global mute-state broadcast (#678): tell every endpoint that this + // participant is now muted so each client reflects it in its participant + // list. An empty `to` broadcasts to all other endpoints on the SMB + // conference. Advisory only — not server-enforced (authoritative mute is + // deferred follow-up option (b), which would persist state in the backend + // and prevent self-unmute). + const broadcast = JSON.stringify({ + type: "EndpointMessage", + to: "", + payload: { + muteState: "mute", + participantId: userId, + }, + }); + if (dataChannel && dataChannel.readyState === "open") { dataChannel.send(msg); + dataChannel.send(broadcast); + // The broadcast reaches every OTHER endpoint; update the acting admin's + // own participant list locally so it reflects the change immediately. + dispatch({ + type: "UPDATE_PARTICIPANT_MUTE_STATE", + payload: { callId: id, participantId: userId, muted: true }, + }); setMuteError(false); setConfirmModalOpen(false); } else { @@ -1066,6 +1091,7 @@ export const ProductionLine = ({ { }); }); + it("dispatches UPDATE_PARTICIPANT_MUTE_STATE on a mute-state broadcast (#678)", () => { + renderHook(() => useRtcConnection(connectedOptions), { wrapper }); + + capturedMessageHandler?.({ + data: JSON.stringify({ + type: "EndpointMessage", + payload: { muteState: "mute", participantId: "ep-9" }, + to: "", + from: "ep-admin", + }), + } as MessageEvent); + + expect(mockDispatch).toHaveBeenCalledWith({ + type: "UPDATE_PARTICIPANT_MUTE_STATE", + payload: { + callId: "test-call-id", + participantId: "ep-9", + muted: true, + }, + }); + // A broadcast must NOT flip the receiving client's own self-mute state. + expect(mockDispatch).not.toHaveBeenCalledWith( + expect.objectContaining({ + payload: expect.objectContaining({ + updates: expect.objectContaining({ + isRemotelyMuted: expect.anything(), + }), + }), + }) + ); + }); + it("dispatches isRemotelyDisconnected on a forceDisconnect EndpointMessage", () => { renderHook(() => useRtcConnection(connectedOptions), { wrapper }); diff --git a/src/components/ui/production-line/use-rtc-connection.ts b/src/components/ui/production-line/use-rtc-connection.ts index dc98ae5d..d228ccc0 100644 --- a/src/components/ui/production-line/use-rtc-connection.ts +++ b/src/components/ui/production-line/use-rtc-connection.ts @@ -16,6 +16,7 @@ import { parseDataChannelMessage, isRemoteMute, isForceDisconnect, + getMuteStateBroadcast, } from "./data-channel-parser.ts"; import { waitForIceGathering } from "./ice-gathering.ts"; import { startRtcStatInterval } from "./rtc-stat-interval.ts"; @@ -223,7 +224,22 @@ const establishConnection = ({ }, }); } else if (message.type === "EndpointMessage") { - if (isForceDisconnect(message)) { + const muteBroadcast = getMuteStateBroadcast(message); + if (muteBroadcast) { + // Advisory global-mute state broadcast (#678): an admin muted/unmuted + // this participant and broadcast the new state to all endpoints. Record + // it per-endpointId so this client's participant list reflects the mute + // state of every participant, not just itself. Advisory only — this is + // not server-enforced (authoritative mute is deferred option (b)). + dispatch({ + type: "UPDATE_PARTICIPANT_MUTE_STATE", + payload: { + callId, + participantId: muteBroadcast.participantId, + muted: muteBroadcast.muted, + }, + }); + } else if (isForceDisconnect(message)) { // A client with admin rights kicked this participant. Flag the call so // production-line can tear down the RTCPeerConnection, leave the line // and surface a "You were removed from the call" notification. diff --git a/src/components/ui/production-line/user-list.tsx b/src/components/ui/production-line/user-list.tsx index 97a73538..93ccd75f 100644 --- a/src/components/ui/production-line/user-list.tsx +++ b/src/components/ui/production-line/user-list.tsx @@ -1,5 +1,5 @@ import styled from "@emotion/styled"; -import { UserIcon, WhipIcon } from "../../../assets/icons/icon.tsx"; +import { MicMuted, UserIcon, WhipIcon } from "../../../assets/icons/icon.tsx"; import { TParticipant } from "./types.ts"; import { getStatusClass, @@ -39,8 +39,26 @@ const IsTalkingIndicator = styled.div` : ""} `; +// Advisory global-mute indicator (#678): shown next to a participant whose +// endpointId is flagged muted in the call's participantMuteState map. The mark +// is fed by mute-state broadcasts on the data channel and therefore reflects +// the same state on every client. Advisory only — it mirrors what an admin +// asked for and is not server-enforced. +const MutedIndicator = styled.div` + display: flex; + align-items: center; + margin-right: 1rem; + flex-shrink: 0; + + svg { + width: 2rem; + fill: #f96c6c; + } +`; + type TUserListOptions = { participants: TParticipant[]; + participantMuteState?: Record; sessionId: string | null; dominantSpeaker: string | null; audioLevelAboveThreshold: boolean; @@ -60,6 +78,7 @@ type TUserListOptions = { export const UserList = ({ participants, + participantMuteState, sessionId, dominantSpeaker, audioLevelAboveThreshold, @@ -91,6 +110,7 @@ export const UserList = ({ {participants.map((p) => { const isYou = p.sessionId === sessionId; const truncatedUsername = truncateParticipantName(p.name); + const isMuted = participantMuteState?.[p.endpointId] ?? false; return ( @@ -111,6 +131,14 @@ export const UserList = ({ {truncatedUsername} {p.isActive ? "" : "(inactive)"} + {isMuted && ( + + + + )} = {}): CallState { dataChannel: null, isRemotelyMuted: false, isRemotelyDisconnected: false, + participantMuteState: {}, ...overrides, }; } @@ -347,6 +348,63 @@ describe("globalReducer", () => { }); }); + // ── UPDATE_PARTICIPANT_MUTE_STATE ─────────────────────────────────────── + + describe("UPDATE_PARTICIPANT_MUTE_STATE", () => { + it("should set a participant's advisory mute state keyed by endpointId", () => { + const state = stateWithCall("call-1"); + + const next = globalReducer(state, { + type: "UPDATE_PARTICIPANT_MUTE_STATE", + payload: { callId: "call-1", participantId: "ep-1", muted: true }, + }); + + expect(next.calls["call-1"].participantMuteState).toEqual({ + "ep-1": true, + }); + }); + + it("should merge without clobbering other participants' mute state", () => { + const state = stateWithCall("call-1", { + participantMuteState: { "ep-1": true }, + }); + + const next = globalReducer(state, { + type: "UPDATE_PARTICIPANT_MUTE_STATE", + payload: { callId: "call-1", participantId: "ep-2", muted: true }, + }); + + expect(next.calls["call-1"].participantMuteState).toEqual({ + "ep-1": true, + "ep-2": true, + }); + }); + + it("should flip a participant from muted to unmuted (advisory unmute)", () => { + const state = stateWithCall("call-1", { + participantMuteState: { "ep-1": true }, + }); + + const next = globalReducer(state, { + type: "UPDATE_PARTICIPANT_MUTE_STATE", + payload: { callId: "call-1", participantId: "ep-1", muted: false }, + }); + + expect(next.calls["call-1"].participantMuteState["ep-1"]).toBe(false); + }); + + it("should return the same state when the call does not exist", () => { + const state = stateWithCall("call-1"); + + const next = globalReducer(state, { + type: "UPDATE_PARTICIPANT_MUTE_STATE", + payload: { callId: "missing", participantId: "ep-1", muted: true }, + }); + + expect(next).toBe(state); + }); + }); + // ── REMOVE_CALL ──────────────────────────────────────────────────────── describe("REMOVE_CALL", () => { diff --git a/src/global-state/global-state-reducer.ts b/src/global-state/global-state-reducer.ts index 0baeec40..685bc5b0 100644 --- a/src/global-state/global-state-reducer.ts +++ b/src/global-state/global-state-reducer.ts @@ -122,6 +122,24 @@ export const globalReducer: Reducer = ( }, }, }; + case "UPDATE_PARTICIPANT_MUTE_STATE": { + const { callId, participantId, muted } = action.payload; + const call = state.calls[callId]; + if (!call) return state; + return { + ...state, + calls: { + ...state.calls, + [callId]: { + ...call, + participantMuteState: { + ...call.participantMuteState, + [participantId]: muted, + }, + }, + }, + }; + } case "REMOVE_CALL": { // eslint-disable-next-line @typescript-eslint/naming-convention const { [action.payload.id]: _, ...remainingCalls } = state.calls; diff --git a/src/global-state/types.ts b/src/global-state/types.ts index b0016032..77c9e90b 100644 --- a/src/global-state/types.ts +++ b/src/global-state/types.ts @@ -34,6 +34,12 @@ export interface CallState { dataChannel: RTCDataChannel | null; isRemotelyMuted: boolean; isRemotelyDisconnected: boolean; + // Advisory global-mute state (#678), keyed by participant endpointId. Updated + // from mute-state broadcasts on the conference data channel so the + // participant list can reflect each participant's current admin-mute state + // for every client, not just the mute target. Advisory only: it mirrors what + // an admin asked for and is not server-enforced. + participantMuteState: Record; } export type TGlobalState = { diff --git a/src/hooks/use-initiate-production-call.tsx b/src/hooks/use-initiate-production-call.tsx index 9493d5a8..d22adf63 100644 --- a/src/hooks/use-initiate-production-call.tsx +++ b/src/hooks/use-initiate-production-call.tsx @@ -128,6 +128,7 @@ export const useInitiateProductionCall = ({ dataChannel: null, isRemotelyMuted: false, isRemotelyDisconnected: false, + participantMuteState: {}, hotkeys: { muteHotkey: "m", speakerHotkey: "n",