feat(video): pause the video broadcast to hidden-tab viewers

[rmounce]

The web client already sends STOP_VIDEO on tab-hide and START_VIDEO (+ decoder re-init + watchdog) on tab-show. For the display's owning client this stops the capture — but for shared viewers, who never get a client_display_id, STOP_VIDEO was a silent no-op: a hidden viewer tab kept receiving the full video bitrate and discarding it. With several viewers parked on background tabs, that's most of the stream's bandwidth doing nothing.

This tracks paused viewer sockets in a set and excludes them from the primary video broadcast; capture keeps running and the socket stays connected for control/cursor/audio. On START_VIDEO the viewer rejoins and falls through to the existing shared-client resync (PIPELINE_RESETTING + scheduled IDR + cursor resend), so resume is one IDR away. A resuming paused viewer bypasses the 30 s viewer START_VIDEO throttle — resume is a real state change, and the throttle would otherwise blank quick tab switches — but still arms it, so resets can't be spammed faster than pause/resume cycles.

Found while building a multi-viewer portal on top of #254's token roles. Draft pending runtime testing on our lsio-based image (multi-viewer hide/show, rapid toggling, bandwidth verification); will mark ready once validated.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a mechanism to pause video feeds for shared viewers when they hide their tab (sending STOP_VIDEO), while keeping their control, cursor, and audio connections active. This is achieved by tracking paused viewers in a new self.video_paused_viewers set and excluding them from the primary video broadcast. The reviewer identified a critical bug where non-viewer clients (such as collaborative controllers) who send STOP_VIDEO will be added to self.video_paused_viewers but never removed upon sending START_VIDEO because the discard logic is nested inside a viewer-only check. This would permanently pause their video feed. A code suggestion was provided to discard the websocket from self.video_paused_viewers regardless of the client's role.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Currently, self.video_paused_viewers.discard(websocket) is only called if the client's role is "viewer". However, non-viewer clients (such as collaborative controllers) can also be added to self.video_paused_viewers if they send a STOP_VIDEO message (e.g., when backgrounding their tab). If they subsequently send a START_VIDEO message, they will never be removed from self.video_paused_viewers, causing their video feed to be permanently paused.

We should check if the client was paused and discard them from self.video_paused_viewers regardless of their role, while still preserving the throttle-bypass logic for viewers.

Suggested change

	perms = client_permissions.get(websocket)
	if perms and perms.get("role") == "viewer":
	now = time.time()
	last_req_time = self.last_start_video_request_times.get(websocket, 0)
	if now - last_req_time < 30.0:
	data_logger.warning(f"Throttled START_VIDEO request from viewer {remote_address}. Ignoring.")
	continue
	self.last_start_video_request_times[websocket] = now
	if websocket in self.video_paused_viewers:
	# A paused viewer resuming (tab visible again) is a
	# real state change, not spam: it must rejoin the
	# broadcast set and get a decode entry point, so it
	# bypasses the redundant-request throttle below —
	# but still arms it, so a resume can't be used to
	# spam resets any faster than pause/resume cycles.
	self.video_paused_viewers.discard(websocket)
	data_logger.info(f"START_VIDEO from paused viewer ({remote_address}): resuming its video feed.")
	self.last_start_video_request_times[websocket] = now
	else:
	last_req_time = self.last_start_video_request_times.get(websocket, 0)
	if now - last_req_time < 30.0:
	data_logger.warning(f"Throttled START_VIDEO request from viewer {remote_address}. Ignoring.")
	continue
	self.last_start_video_request_times[websocket] = now
	was_paused = websocket in self.video_paused_viewers
	self.video_paused_viewers.discard(websocket)
	perms = client_permissions.get(websocket)
	if perms and perms.get('role') == 'viewer':
	now = time.time()
	if was_paused:
	# A paused viewer resuming (tab visible again) is a
	# real state change, not spam: it must rejoin the
	# broadcast set and get a decode entry point, so it
	# bypasses the redundant-request throttle below —
	# but still arms it, so a resume can't be used to
	# spam resets any faster than pause/resume cycles.
	data_logger.info(f'START_VIDEO from paused viewer ({remote_address}): resuming its video feed.')
	self.last_start_video_request_times[websocket] = now
	else:
	last_req_time = self.last_start_video_request_times.get(websocket, 0)
	if now - last_req_time < 30.0:
	data_logger.warning(f'Throttled START_VIDEO request from viewer {remote_address}. Ignoring.')
	continue
	self.last_start_video_request_times[websocket] = now

[ehfd]

Integrated into #254 with additional nit fixes.

[rmounce]

Validated the incorporated version on comprehensive-fixes (da1b55e): backgrounding a viewer tab now pauses its video feed and foregrounding resumes it cleanly with the reset+IDR resync. The incorporation is a strict superset of this draft — among other hardening, the role-agnostic unpause also addresses the review bot's finding here, and adding STOP_VIDEO to allowed_viewer_prefixes fixes a gap this draft had (the viewer message gate silently denied the pause request). Closing as superseded. Thanks!

🤖 Generated with Claude Code