feat(video-conf): add a layout picker with grid, spotlight, and sidebar modes (NV-11)

A dropdown in the call controls lets users switch the video tile layout
between grid (equal tiles), spotlight (active speaker fills the stage
with a self-view PiP), and sidebar (active speaker large, others in a
strip). The choice is persisted in localStorage across calls.

Active speaker detection uses a single AudioContext with one
AnalyserNode per participant, sampling at ~12 Hz with 1.5 s hysteresis
to avoid flicker.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: rodrigok

docs/features/video-conference-persistent-chat/README.md

@@ -213,6 +213,18 @@ The conference is a column: a row holding the call and the chat panel, then `Cal
 
 The panel is docked to the inline end, so its close button sits at the far end of its header — matching every other closable surface in the product. Both panels share that header (`CallPanelHeader`, the contextual bar's own header/title/close), so two docked side by side can't disagree about where their own edges are.
 
+### Stage layout
+
+The call stage (`CallStage`) supports three layouts, cycled by a button in the control bar:
+
+- **Grid** (default) — all participants in equal-sized tiles, rows/cols computed by `useTileGridLayout` to fill the stage within a [3:4 .. 16:9] aspect band.
+- **Spotlight** — the active speaker fills the stage; the local user's self-view floats as a small PiP in the bottom-right corner. When the local user *is* the active speaker, the first remote participant is shown large instead.
+- **Sidebar** — the active speaker is large on the left, all other participants are shown in a thumb column on the right (or row at the bottom on narrow stages), reusing the same structure as the screen-share spotlight.
+
+Active speaker detection runs in `useActiveSpeakerId`: a single `AudioContext` with one `AnalyserNode` per participant, sampling at ~12 Hz. A 1.5 s hold prevents flickering between speakers during conversational pauses. When nobody is speaking, the fallback is the first remote participant.
+
+When a screen share is active, the existing screen-share spotlight takes over regardless of the selected layout — the screen always wins.
+
 The bar carries two counts: how many people are in the call, and what is unread in the chat while its panel is
 closed. The unread one goes through `useUnreadDisplay`, the sidebar's own rules, so a mention reads as urgent in
 both places and a muted room stays quiet in both. The members count is deliberately `secondary` — a count of who is
@@ -1002,6 +1014,7 @@ could not be loaded" panel, because the detail panel is contact-call-shaped.
 | Conference model | `packages/models/src/models/VideoConference.ts` |
 | Route + viewport | `apps/meteor/client/views/conference/ConferenceRoute.tsx`, `ConferenceViewport.tsx` |
 | Call chrome | `apps/meteor/client/views/conference/ConferenceEmbeddedPage.tsx`, `ConferenceIframe.tsx`, `components/CallBar/`, `components/CallPanel/` |
+| Stage layout + active speaker | `packages/ui-voip/src/views/MediaCallRoomSection/CallStage.tsx`, `MediaCallRoomSection.tsx`, `providers/useActiveSpeakerId.ts` |
 | Chat panel | `apps/meteor/client/views/conference/ConferenceChat.tsx`, `ConferenceRoom.tsx`, `ConferenceThread.tsx`, `ConferenceThreadChat.tsx`, `ConferenceThreadModal.tsx`, `ConferenceStoresReady.tsx`, `CallPanelHeader.tsx`, `ConferenceChatNotShared.tsx` |
 | Nothing to show | `apps/meteor/client/views/conference/ConferenceStatePage.tsx`, `ConferencePageError.tsx`, `ConferenceUnauthorizedPage.tsx` |
 | Conference data | `apps/meteor/client/views/conference/hooks/useConferenceEmbedded.tsx` |

packages/ui-voip/src/components/LayoutPicker.tsx

@@ -0,0 +1,56 @@
+import { Box, RadioButton } from '@rocket.chat/fuselage';
+import { GenericMenu } from '@rocket.chat/ui-client';
+import type { GenericMenuItemProps } from '@rocket.chat/ui-client';
+
+import { ActionButton } from '.';
+import type { StageLayout } from '../views/MediaCallRoomSection/CallStage';
+
+const LAYOUTS: StageLayout[] = ['grid', 'spotlight', 'sidebar'];
+
+const LAYOUT_ICONS: Record<StageLayout, string> = {
+	grid: 'squares',
+	spotlight: 'user',
+	sidebar: 'stack',
+};
+
+const LAYOUT_LABELS: Record<StageLayout, string> = {
+	grid: 'Grid',
+	spotlight: 'Spotlight',
+	sidebar: 'Sidebar',
+};
+
+type LayoutPickerProps = {
+	layout: StageLayout;
+	onLayoutChange: (layout: StageLayout) => void;
+};
+
+const LayoutPicker = ({ layout, onLayoutChange }: LayoutPickerProps) => {
+	const items: GenericMenuItemProps[] = LAYOUTS.map((l) => ({
+		id: l,
+		textValue: LAYOUT_LABELS[l],
+		icon: LAYOUT_ICONS[l] as any,
+		content: (
+			<Box is='span' title={LAYOUT_LABELS[l]} fontSize={14}>
+				{LAYOUT_LABELS[l]}
+			</Box>
+		),
+		addon: <RadioButton checked={layout === l} readOnly />,
+	}));
+
+	return (
+		<GenericMenu
+			title='Layout'
+			items={items}
+			placement='top-end'
+			selectionMode='multiple'
+			onAction={(id) => {
+				if (typeof id === 'string' && LAYOUTS.includes(id as StageLayout)) {
+					onLayoutChange(id as StageLayout);
+				}
+			}}
+			button={<ActionButton secondary label='Layout' icon={LAYOUT_ICONS[layout] as any} />}
+		/>
+	);
+};
+
+export default LayoutPicker;

packages/ui-voip/src/components/index.ts

@@ -13,5 +13,6 @@ export { default as PeerAutocomplete } from './PeerAutocomplete';
 export { default as Timer } from './Timer';
 export { default as DevicePicker } from './DevicePicker';
 export { default as CameraPicker } from './CameraPicker';
+export { default as LayoutPicker } from './LayoutPicker';
 export { default as CallHistoryInternalUser } from './CallHistoryInternalUser';
 export { default as CallHistoryExternalUser } from './CallHistoryExternalUser';

packages/ui-voip/src/providers/useActiveSpeakerId.ts

@@ -0,0 +1,113 @@
+import { useEffect, useRef, useState } from 'react';
+
+const SAMPLE_INTERVAL_MS = 80;
+const SPEAKING_THRESHOLD = 0.12;
+// How long a speaker holds the "active" slot after they stop, to avoid
+// flickering between speakers during natural conversation pauses.
+const HOLD_MS = 1500;
+
+/**
+ * Tracks the dominant speaker across all participants by sampling audio levels
+ * from a single shared AudioContext. Returns the participant id that is speaking
+ * the loudest (above threshold), with hysteresis to avoid flicker.
+ *
+ * Falls back to `fallbackId` when nobody is speaking.
+ */
+export const useActiveSpeakerId = (
+	participants: ReadonlyArray<{ id: string; audioStream?: MediaStream | null }>,
+	fallbackId: string | null,
+): string | null => {
+	const [activeSpeakerId, setActiveSpeakerId] = useState<string | null>(null);
+
+	// Stable identity for the participant list so the effect only re-runs when
+	// the actual set of (id, stream) pairs changes — not on every render.
+	const participantsKey = participants
+		.map((p) => `${p.id}:${p.audioStream?.id ?? 'none'}`)
+		.sort()
+		.join(',');
+
+	const holdRef = useRef<{ id: string | null; changedAt: number }>({ id: null, changedAt: 0 });
+
+	useEffect(() => {
+		const AC: typeof AudioContext | undefined = (window as any).AudioContext || (window as any).webkitAudioContext;
+		if (!AC) return undefined;
+
+		const ctx = new AC();
+		const sources: Array<{ id: string; source: MediaStreamAudioSourceNode; analyser: AnalyserNode }> = [];
+
+		for (const p of participants) {
+			if (!p.audioStream || typeof p.audioStream.getAudioTracks !== 'function') continue;
+			const tracks = p.audioStream.getAudioTracks();
+			if (!tracks.length) continue;
+
+			const source = ctx.createMediaStreamSource(p.audioStream);
+			const analyser = ctx.createAnalyser();
+			analyser.fftSize = 512;
+			analyser.smoothingTimeConstant = 0.5;
+			source.connect(analyser);
+			sources.push({ id: p.id, source, analyser });
+		}
+
+		if (sources.length === 0) {
+			setActiveSpeakerId(null);
+			return () => void ctx.close().catch(() => undefined);
+		}
+
+		const buf = new Uint8Array(512);
+		let cancelled = false;
+		let rafId = 0;
+		let lastUpdate = 0;
+
+		const tick = (ts: number) => {
+			if (cancelled) return;
+			if (ts - lastUpdate >= SAMPLE_INTERVAL_MS) {
+				let maxLevel = 0;
+				let maxId: string | null = null;
+
+				for (const { id, analyser } of sources) {
+					analyser.getByteTimeDomainData(buf);
+					let sumSq = 0;
+					for (let i = 0; i < buf.length; i++) {
+						const v = (buf[i] - 128) / 128;
+						sumSq += v * v;
+					}
+					const rms = Math.sqrt(sumSq / buf.length);
+					const level = Math.min(1, rms * 4);
+					if (level > maxLevel && level > SPEAKING_THRESHOLD) {
+						maxLevel = level;
+						maxId = id;
+					}
+				}
+
+				const now = Date.now();
+				const hold = holdRef.current;
+
+				if (maxId && maxId !== hold.id && (now - hold.changedAt > HOLD_MS || !hold.id)) {
+					hold.id = maxId;
+					hold.changedAt = now;
+					setActiveSpeakerId(maxId);
+				}
+
+				lastUpdate = ts;
+			}
+			rafId = requestAnimationFrame(tick);
+		};
+		rafId = requestAnimationFrame(tick);
+
+		return () => {
+			cancelled = true;
+			cancelAnimationFrame(rafId);
+			for (const { source } of sources) {
+				try {
+					source.disconnect();
+				} catch {
+					// may already be disconnected
+				}
+			}
+			void ctx.close().catch(() => undefined);
+		};
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [participantsKey]);
+
+	return activeSpeakerId ?? fallbackId;
+};

packages/ui-voip/src/views/MediaCallRoomSection/CallStage.tsx

@@ -4,6 +4,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import CallTile from './CallTile';
 import type { RemoteParticipantInfo } from '../../context/MediaCallViewContext';
+import { useActiveSpeakerId } from '../../providers/useActiveSpeakerId';
 import { usePlayMediaStream } from '../../providers/usePlayMediaStream';
 import { useTileGridLayout } from '../../providers/useTileGridLayout';
 
@@ -20,12 +21,16 @@ type LocalParticipant = {
 	audioStream?: MediaStream | null;
 };
 
+export type StageLayout = 'grid' | 'spotlight' | 'sidebar';
+
 type CallStageProps = {
 	localParticipant: LocalParticipant;
 	remoteParticipants: RemoteParticipantInfo[];
 	onStopLocalScreenShare?: () => void;
 	/** Map from participantId → 1-based queue position for the raise-hand badge. */
 	handPositions?: Record<string, number>;
+	/** Which layout to use when no screen share is active. Defaults to `'grid'`. */
+	layout?: StageLayout;
 };
 
 const stageStyles = css`
@@ -213,6 +218,19 @@ const ownBadgeStyles = css`
 	pointer-events: none;
 `;
 
+// Spotlight layout: active speaker fills the stage, local user floats in the corner.
+const spotlightSelfPipStyles = css`
+	position: absolute;
+	bottom: 16px;
+	right: 16px;
+	width: 180px;
+	aspect-ratio: 16 / 9;
+	border-radius: 8px;
+	overflow: hidden;
+	box-shadow: 0 4px 12px rgba(0, 0, 0, 0.4);
+	z-index: 2;
+`;
+
 type ScreenViewerProps = {
 	stream: MediaStream;
 	label: string;
@@ -273,7 +291,7 @@ const ScreenShareThumb = ({
 };
 
 // eslint-disable-next-line react/no-multi-comp
-const CallStage = ({ localParticipant, remoteParticipants, onStopLocalScreenShare, handPositions }: CallStageProps) => {
+const CallStage = ({ localParticipant, remoteParticipants, onStopLocalScreenShare, handPositions, layout = 'grid' }: CallStageProps) => {
 	// All currently-active screen shares (local + remote), in a stable shape
 	// the rest of the component consumes. Re-derived each render from the
 	// participants list; tracking of "when did each share start" lives in a
@@ -373,6 +391,18 @@ const CallStage = ({ localParticipant, remoteParticipants, onStopLocalScreenShar
 		return all;
 	}, [localParticipant, remoteParticipants, handPositions]);
 
+	// Active speaker: used by spotlight and sidebar layouts to decide which
+	// participant gets the large view. Falls back to the first remote
+	// participant when nobody is speaking.
+	const audioParticipants = useMemo(
+		() => [
+			{ id: localParticipant.id, audioStream: localParticipant.audioStream },
+			...remoteParticipants.map((p) => ({ id: p.id, audioStream: p.audioStream })),
+		],
+		[localParticipant.id, localParticipant.audioStream, remoteParticipants],
+	);
+	const activeSpeakerId = useActiveSpeakerId(audioParticipants, remoteParticipants[0]?.id ?? localParticipant.id);
+
 	// IMPORTANT: hooks must run unconditionally on every render. Both the
 	// grid layout hook and its companion ref live above any conditional
 	// return — when a screen share starts mid-call featuredScreen flips
@@ -448,6 +478,58 @@ const CallStage = ({ localParticipant, remoteParticipants, onStopLocalScreenShar
 		);
 	}
 
+	// Spotlight layout: active speaker fills the stage, local user's self-view
+	// floats as a small PiP in the bottom-right corner.
+	if (layout === 'spotlight') {
+		const featured = tiles.find((t) => t.id === activeSpeakerId) ?? tiles[0];
+		const selfTile = tiles.find((t) => t.id === localParticipant.id);
+		// When the local user is the active speaker, show the first remote instead.
+		const mainTile = featured.id === localParticipant.id && tiles.length > 1 ? tiles.find((t) => t.id !== localParticipant.id)! : featured;
+		return (
+			<Box className={stageStyles}>
+				<Box display='flex' width='full' height='full' position='relative'>
+					<Box className={mainStreamStyles}>
+						<CallTile {...mainTile} />
+					</Box>
+					{selfTile && selfTile.id !== mainTile.id && (
+						<Box className={spotlightSelfPipStyles}>
+							<CallTile {...selfTile} compact />
+						</Box>
+					)}
+				</Box>
+			</Box>
+		);
+	}
+
+	// Sidebar layout: active speaker large on the left, everyone else in a
+	// thumb column on the right — the same structure as the screen-share
+	// spotlight, but with a camera feed instead of a screen.
+	if (layout === 'sidebar') {
+		const isSideBySide = spotlightOrientation === 'side-by-side';
+		const featured = tiles.find((t) => t.id === activeSpeakerId) ?? tiles[0];
+		const others = tiles.filter((t) => t.id !== featured.id);
+		return (
+			<Box className={stageStyles} ref={stageRefCallback}>
+				<Box className={isSideBySide ? spotlightSideBySideStyles : spotlightStackedStyles}>
+					<Box className={mainStreamStyles}>
+						<CallTile {...featured} />
+					</Box>
+					{others.length > 0 && (
+						<Box className={isSideBySide ? thumbColumnStyles : thumbStripStyles} data-thumb-orientation={isSideBySide ? 'column' : 'row'}>
+							{others.map((t) => (
+								<Box key={t.id} className={isSideBySide ? thumbItemColumnStyles : thumbItemStyles}>
+									<CallTile {...t} compact />
+								</Box>
+							))}
+						</Box>
+					)}
+				</Box>
+			</Box>
+		);
+	}
+
+	// Grid layout (default): all participants in equal-sized tiles.
+
 	// When the last row has fewer tiles than `cols`, we center the orphans at
 	// their natural single-column width using `gridColumnStart` — never spanning.
 	// An earlier version expanded each orphan to fill remaining columns, which

packages/ui-voip/src/views/MediaCallRoomSection/MediaCallRoomSection.tsx

@@ -1,12 +1,13 @@
 import { css } from '@rocket.chat/css-in-js';
 import { Box, ButtonGroup } from '@rocket.chat/fuselage';
+import { useLocalStorage } from '@rocket.chat/fuselage-hooks';
 import { memo, useEffect, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import { useTranslation } from 'react-i18next';
 
 import CallReactions, { type CallReaction } from './CallReactions';
-import CallStage from './CallStage';
-import { ToggleButton, Timer, DevicePicker, CameraPicker, ActionButton, ActionStrip, ActionToggleChat } from '../../components';
+import CallStage, { type StageLayout } from './CallStage';
+import { ToggleButton, Timer, DevicePicker, CameraPicker, LayoutPicker, ActionButton, ActionStrip, ActionToggleChat } from '../../components';
 import { useMediaCallInstance } from '../../context/MediaCallInstanceContext';
 import type { RemoteParticipantInfo } from '../../context/MediaCallViewContext';
 import { useMediaCallView } from '../../context/MediaCallViewContext';
@@ -224,6 +225,8 @@ const MediaCallRoomSection = ({
 	const [reactionPickerOpen, setReactionPickerOpen] = useState(false);
 	const reactionPickerRef = useRef<HTMLDivElement>(null);
 
+	const [stageLayout, setStageLayout] = useLocalStorage<StageLayout>('videoconf-stage-layout', 'grid');
+
 	// Click-outside dismiss for the reaction popover. Stays open while the
 	// user clicks emojis inside it (so they can send several in a row), but
 	// closes when they click anywhere else on the page.
@@ -389,6 +392,7 @@ const MediaCallRoomSection = ({
 					onToggle={onToggleHand}
 				/>
 			)}
+			{isLiveKitCall && <LayoutPicker layout={stageLayout} onLayoutChange={setStageLayout} />}
 			{onSendReaction && (
 				<Box className={reactionPickerWrapStyles} ref={reactionPickerRef}>
 					<ToggleButton
@@ -462,6 +466,7 @@ const MediaCallRoomSection = ({
 					remoteParticipants={remoteParticipants}
 					onStopLocalScreenShare={onToggleScreenSharing}
 					handPositions={handPositions}
+					layout={stageLayout}
 				/>
 				<CallReactions reactions={reactions} />
 			</Box>