Add WebRTC-based chat to web

README.md

@@ -319,8 +319,10 @@ These values are parsed by the Go backend and applied to WHIP/WHEP `PeerConnecti
 | `CHAT_DEFAULT_TTL`      | How long idle chat sessions stay alive before they expire.     |
 | `CHAT_CLEANUP_INTERVAL` | How often expired chat sessions are cleaned up.                |
 
-Broadcast Box also attaches a WebRTC data channel (`bb-chat-v1`) to WHIP/WHEP peer connections for simple
-per-stream chat state, although the bundled frontend does not currently expose a chat UI.
+Broadcast Box attaches a WebRTC data channel (`bb-chat-v1`) to WHIP/WHEP peer connections for simple per-stream
+chat state. The bundled frontend does not currently expose a chat UI, but you can connect from your own client.
+
+See [CONNECTING.md](internal/chat/CONNECTING.md) for the message contract and a minimal standalone client example.
 
 ## CLI Flags
 

internal/chat/CONNECTING.md

@@ -0,0 +1,116 @@
+# Chat Connection Quick Reference
+
+Use the WebRTC data channel label `bb-chat-v1` to connect to per-stream chat.
+
+## What the server expects
+
+- Data channel label: `bb-chat-v1`
+- Outbound client message type: `chat.send`
+- `text` length: 1-2000 chars
+- `displayName` length: 1-80 chars
+
+Client -> server payload:
+
+```json
+{
+  "type": "chat.send",
+  "clientMsgId": "uuid-or-any-unique-id",
+  "text": "hello",
+  "displayName": "alice"
+}
+```
+
+Server -> client message types:
+
+- `chat.connected`
+- `chat.history` (contains `{ type: "message", message: ... }[]`)
+- `chat.message` (single live message)
+- `chat.ack` (echoes `clientMsgId`)
+- `chat.error` (may include `clientMsgId`)
+
+Message shape:
+
+```json
+{
+  "id": "message-id",
+  "ts": 1730000000,
+  "text": "hello",
+  "displayName": "alice"
+}
+```
+
+## Simple client example
+
+```ts
+const CHAT_LABEL = "bb-chat-v1";
+
+type Outbound =
+  | { type: "chat.connected" }
+  | { type: "chat.history"; events: Array<{ type: "message"; message: ChatMessage }> }
+  | { type: "chat.message"; eventId: number; message: ChatMessage }
+  | { type: "chat.ack"; clientMsgId: string }
+  | { type: "chat.error"; error: string; clientMsgId?: string };
+
+type ChatMessage = {
+  id: string;
+  ts: number;
+  text: string;
+  displayName: string;
+};
+
+const chatChannel = peerConnection.createDataChannel(CHAT_LABEL);
+const pending = new Map<string, (error?: Error) => void>();
+
+chatChannel.addEventListener("message", (event) => {
+  const payload = JSON.parse(event.data) as Outbound;
+
+  if (payload.type === "chat.history") {
+    payload.events.forEach((e) => console.log("history", e.message));
+  }
+
+  if (payload.type === "chat.message") {
+    console.log("live", payload.message);
+  }
+
+  if (payload.type === "chat.ack") {
+    pending.get(payload.clientMsgId)?.();
+    pending.delete(payload.clientMsgId);
+  }
+
+  if (payload.type === "chat.error" && payload.clientMsgId) {
+    pending.get(payload.clientMsgId)?.(new Error(payload.error));
+    pending.delete(payload.clientMsgId);
+  }
+});
+
+function sendChat(text: string, displayName: string) {
+  if (chatChannel.readyState !== "open") {
+    throw new Error("chat channel is not open");
+  }
+
+  const clientMsgId = crypto.randomUUID();
+  const payload = {
+    type: "chat.send",
+    clientMsgId,
+    text,
+    displayName,
+  };
+
+  return new Promise<void>((resolve, reject) => {
+    pending.set(clientMsgId, (error?: Error) => {
+      if (error) reject(error);
+      else resolve();
+    });
+
+    chatChannel.send(JSON.stringify(payload));
+  });
+}
+```
+
+## Connection flow
+
+1. Create `RTCPeerConnection`.
+2. Create chat data channel with label `bb-chat-v1` before SDP offer.
+3. Handle inbound `chat.connected`, `chat.history`, `chat.message`, `chat.ack`, and `chat.error` payloads.
+4. Send messages as `{ "type": "chat.send", "clientMsgId", "text", "displayName" }`.
+5. Treat `chat.ack` as send success and `chat.error` as send failure.

web/src/components/player/Player.tsx

@@ -1,19 +1,25 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { MouseEvent } from 'react';
 import PlayPauseComponent from "./components/PlayPauseComponent";
 import VideoLayerSelectorComponent from "./components/VideoLayerSelectorComponent";
 import AudioLayerSelectorComponent from "./components/AudioLayerSelectorComponent";
 import CurrentViewersComponent from "./components/CurrentViewersComponent";
 import { StreamStatus } from '../../providers/StatusProvider';
 import { CurrentLayersMessage, PeerConnectionSetup, SetupPeerConnectionProps } from './functions/peerconnection';
-import { ArrowsPointingOutIcon, Square2StackIcon } from '@heroicons/react/20/solid';
+import { ChatAdapter } from '../../hooks/useChatSession';
+import { ArrowsPointingOutIcon, Square2StackIcon, XMarkIcon } from '@heroicons/react/20/solid';
+import { ChatBubbleLeftRightIcon } from '@heroicons/react/24/outline';
 import VolumeComponent from './components/VolumeComponent';
 import { StatusMessageComponent } from './components/StatusMessageComponent';
-import { StreamMOTD } from './components/StreamMOTD';
 
 interface PlayerProps {
 	streamKey: string;
 	cinemaMode: boolean;
-	onCloseStream?: () => void;
+	isChatOpen?: boolean;
+	onToggleChat?(): void;
+	onChatAdapterChange?(streamKey: string, adapter: ChatAdapter | undefined): void;
+	onStreamStatusChange?(streamKey: string, status: StreamStatus): void;
+	onCloseStream?(): void;
 }
 
 interface FullscreenElement extends HTMLElement {
@@ -23,8 +29,15 @@ interface FullscreenElement extends HTMLElement {
 }
 
 const Player = (props: PlayerProps) => {
-	const { cinemaMode } = props;
-	const streamKey = decodeURIComponent(props.streamKey).replace(' ', '_')
+	const {
+		cinemaMode,
+		isChatOpen,
+		onToggleChat,
+		onChatAdapterChange,
+		onStreamStatusChange,
+		onCloseStream,
+	} = props
+	const streamKey = decodeURIComponent(props.streamKey).replace(/ /g, '_')
 
 	const [currentStreamStatus, setCurrentStreamStatus] = useState<StreamStatus>({
 		streamKey: streamKey,
@@ -64,7 +77,8 @@ const Player = (props: PlayerProps) => {
 		onLayerEndpointChange: (endpoint) => setLayerEndpoint(endpoint),
 		onLayerStatus: (status) => setCurrentLayersStatus(status),
 		onStreamStatus: (status) => {
-			setCurrentStreamStatus(() => status)
+			setCurrentStreamStatus(status)
+			onStreamStatusChange?.(streamKey, status)
 
 			if (!status.isOnline) {
 				setStreamState("Offline")
@@ -80,7 +94,8 @@ const Player = (props: PlayerProps) => {
 			setStreamState("Loading")
 		},
 		onError: () => setStreamState("Error"),
-	}), [streamKey])
+		onChatAdapterChange: (adapter) => onChatAdapterChange?.(streamKey, adapter),
+	}), [onChatAdapterChange, onStreamStatusChange, streamKey])
 
 	const handleEnterFullscreen = () => {
 		const videoElement = videoRef.current as FullscreenElement | null;
@@ -107,14 +122,14 @@ const Player = (props: PlayerProps) => {
 
 
 	const resetTimer = useCallback((isVisible: boolean) => {
-		setVideoOverlayVisible(() => isVisible);
+		setVideoOverlayVisible(isVisible);
 
 		if (videoOverlayVisibleTimeoutRef) {
 			clearTimeout(videoOverlayVisibleTimeoutRef.current)
 		}
 
 		videoOverlayVisibleTimeoutRef.current = setTimeout(() => {
-			setVideoOverlayVisible(() => false)
+			setVideoOverlayVisible(false)
 		}, 2500)
 	}, [])
 
@@ -139,6 +154,11 @@ const Player = (props: PlayerProps) => {
 		handleEnterFullscreen();
 	};
 
+	const stopOverlayClickPropagation = (event: MouseEvent<HTMLElement>) => {
+		event.preventDefault();
+		event.stopPropagation();
+	};
+
 	useEffect(() => {
 		const player = document.getElementById(streamVideoPlayerId)
 		const handleMouseUp = () => resetTimer(true)
@@ -170,6 +190,7 @@ const Player = (props: PlayerProps) => {
 		setupPeerConnection()
 
 		return () => {
+			onChatAdapterChange?.(streamKey, undefined)
 			player?.removeEventListener('mouseup', handleMouseUp)
 			player?.removeEventListener('mouseenter', handleMouseEnter)
 			player?.removeEventListener('mouseleave', handleMouseLeave)
@@ -179,19 +200,20 @@ const Player = (props: PlayerProps) => {
 			currentPeerConnection?.close()
 			clearTimeout(videoOverlayVisibleTimeoutRef.current)
 		}
-	}, [peerConnectionConfig, resetTimer, streamVideoPlayerId])
+	}, [onChatAdapterChange, onStreamStatusChange, peerConnectionConfig, resetTimer, streamKey, streamVideoPlayerId])
 
 	return (
-		<div
-			key={`${streamVideoPlayerId}`}
-			id={streamVideoPlayerId}
-			className="inline-block w-full relative z-0 aspect-video rounded-md mb-6"
-			style={cinemaMode ? {
-				maxHeight: '100vh',
-				maxWidth: '100vw',
-			} : {}}>
-
-			<div className="absolute flex rounded-md w-full h-full">
+		<div className="w-full flex items-end">
+			<div
+				key={`${streamVideoPlayerId}`}
+				id={streamVideoPlayerId}
+				className="inline-block w-full relative z-0 aspect-video rounded-md"
+				style={cinemaMode ? {
+					maxHeight: '100vh',
+					maxWidth: '100vw',
+				} : {}}>
+
+				<div className="absolute flex rounded-md w-full h-full">
 
 				<div
 					onClick={handleVideoPlayerClick}
@@ -216,7 +238,8 @@ const Player = (props: PlayerProps) => {
 						{videoElement !== null && (
 						<div className="absolute bottom-0 h-8 w-full flex place-items-end z-30">
 							<div
-								onClick={(e) => e.stopPropagation()}
+								onClick={stopOverlayClickPropagation}
+								onDoubleClick={stopOverlayClickPropagation}
 								className="bg-blue-950 w-full flex flex-row gap-2 h-1/14 p-1 max-h-8 min-h-8 rounded-md">
 
 								<PlayPauseComponent videoRef={videoRef} />
@@ -255,24 +278,35 @@ const Player = (props: PlayerProps) => {
 						state={streamState}
 					/>
 
-					{!!props.onCloseStream && (
+					<div
+						onDoubleClick={stopOverlayClickPropagation}
+						className="absolute top-2 right-2 flex flex-row gap-2 pointer-events-auto z-60">
+					{!!onToggleChat && (
 						<button
-							onClick={props.onCloseStream}
-							className="absolute top-2 right-2 p-2 rounded-full bg-red-400 hover:bg-red-500 pointer-events-auto z-60">
-							<svg
-								xmlns="http://www.w3.org/2000/svg"
-								className="h-6 w-6 text-gray-700"
-								viewBox="0 0 24 24"
-								fill="black">
-								<path
-									fillRule="evenodd"
-									d="M6.225 6.225a.75.75 0 011.06 0L12 10.94l4.715-4.715a.75.75 0 111.06 1.06L13.06 12l4.715 4.715a.75.75 0 11-1.06 1.06L12 13.06l-4.715 4.715a.75.75 0 11-1.06-1.06L10.94 12 6.225 7.285a.75.75 0 010-1.06z"
-									clipRule="evenodd"
-								/>
-							</svg>
+							onClick={(e) => {
+								e.preventDefault();
+								e.stopPropagation();
+								onToggleChat();
+							}}
+							className={`p-2 rounded-full border ${isChatOpen ? 'bg-blue-600 border-blue-500 text-white' : 'bg-black/60 border-gray-700 text-gray-200 hover:bg-gray-800'}`}
+						>
+							<ChatBubbleLeftRightIcon className="h-5 w-5" />
 						</button>
 					)}
 
+						{!!onCloseStream && (
+							<button
+								onClick={(e) => {
+									e.preventDefault();
+									e.stopPropagation();
+									onCloseStream();
+								}}
+								className="p-2 rounded-full bg-red-400 hover:bg-red-500">
+								<XMarkIcon className="h-6 w-6 text-black" />
+							</button>
+						)}
+					</div>
+
 				</div>
 
 					<video
@@ -282,25 +316,19 @@ const Player = (props: PlayerProps) => {
 					muted
 					playsInline
 					className="rounded-md w-full h-full relative bg-gray-950"
-					onPlaying={() => setStreamState(() => "Playing")}
-					onLoadStart={() => setStreamState(() => "Loading")}
+					onPlaying={() => setStreamState("Playing")}
+					onLoadStart={() => setStreamState("Loading")}
 						onLoadedData={(event) => {
 							console.log("VideoPlayer.onLoadedMetadata", event)
 							event.currentTarget.play()
 						}}
 					onError={(error) => console.log("VideoPlayer.Error", error)}
 					onErrorCapture={(error) => console.log("VideoPlayer.ErrorCapture", error)}
-					onEnded={() => setStreamState(() => "Offline")}
+					onEnded={() => setStreamState("Offline")}
 				/>
 
+				</div>
 			</div>
-
-			{/* Stream MOTD*/}
-			<StreamMOTD
-				isOnline={currentStreamStatus.isOnline}
-				motd={currentStreamStatus.motd}
-			/>
-
 		</div>
 	)
 }