Add raw-frame streaming endpoint to BaseVideo alongside MJPEG

[thusser]

Implements the basevideo-raw-frame-streaming plan/design.

What

• New /video.raw multipart endpoint: JSON FITS-keyed meta header (X-Pyobs-Frame-Meta) + raw little-endian bytes, event-driven via a new asyncio.Event with latest-frame-wins backpressure (coalesces bursts into a single wake).
• VideoCapabilities.video renamed to mjpeg, plus a new raw field (both str | None). Collapsed live_view + video_path into a single video_path: str | None, added raw_path: str | None. /, /video.mjpg, and /video.raw routes are now registered only when their path is configured.
• Split add_fits_headers() into add_local_fits_headers() (no VFS I/O) plus the persistent FRAMENUM VFS step, so the raw path builds headers without per-frame VFS writes.
• Added Image.from_ndarray() reconstruction helper (consumer side of the wire contract).
• Fixed video_handler's hardcoded 1 fps interval (now uses self._interval).
• Lowered sleep_time default 600s -> 60s.
• Also guarded the once-per-frame DET-CPX warning (it fired every frame when centre is unset).

Breaking changes

• VideoCapabilities.video removed in favor of mjpeg/raw.
• BaseVideo(live_view=...) removed; use video_path=None to disable the MJPEG live view.

Both acceptable per the plan (project is 2.0.0.dev).

Tests

Added coverage for: capability round-trip (XML), route gating, _new_frame set + coalescing, raw meta/little-endian framing, raw handler wake/write + activity, add_local_fits_headers VFS-free, and Image.from_ndarray.

[thusser]

Code review

Found 6 issues, most-severe first.

1. raw_handler can let the camera sleep out from under it forever. Activity is only refreshed on frame arrival (await self.activate_camera() runs right after _new_frame.wait() returns). If the producer gates frame generation behind _active (as DummyVideo._frame_task does — the only in-repo BaseVideo subclass), and the frame interval approaches/exceeds sleep_time (now 60s, was 600s), _active_update() deactivates the camera, no more frames get produced, and the handler blocks on _new_frame.wait() forever — never reactivates, and can't even detect client disconnect since it never reaches response.write(). This directly contradicts specs/design/basevideo-raw-frame-streaming.md §5, which requires the raw handler to keep touching _active_time continuously (mirroring video_handler's poll loop) specifically to prevent a raw-only session from letting the camera sleep out from under it.

pyobs-core/pyobs/modules/camera/basevideo.py

Lines 275 to 280 in 85d6374

	# wait for a new frame; the event coalesces multiple frames that
	# arrive while a slow consumer is still writing into a single wake
	await self._new_frame.wait()
	self._new_frame.clear()
	# keep activity fresh for the duration of this connection

2. DATE-OBS is stamped at send time, not capture time. _raw_frame() only receives the bare last.data ndarray — no capture timestamp travels with it — so DATE-OBS reflects when the handler happened to process the frame, not when it was acquired. Under the coalescing this code explicitly expects (multiple _set_image() calls collapsing into one wake) or event-loop delay, this can drift arbitrarily from true acquisition time. The FITS path (_create_image/grab_data()) avoids this by threading NextImage.date_obs through.

pyobs-core/pyobs/modules/camera/basevideo.py

Lines 316 to 319 in 85d6374

	# path (no VFS I/O, no cross-module comm) -- see design doc §3
	image = Image(data)
	image.header["DATE-OBS"] = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S.%f")
	image.header["IMAGETYP"] = self._image_type

3. Redundant per-client work. _raw_frame() runs inside each connection's own raw_handler task rather than once per frame and shared. With N simultaneous raw clients (explicitly anticipated by the design doc — "guiding, a recorder, a second viewer"), the header build, JSON serialization, and ascontiguousarray+tobytes() copy all happen N times per frame for identical output.

pyobs-core/pyobs/modules/camera/basevideo.py

Lines 316 to 319 in 85d6374

	# path (no VFS I/O, no cross-module comm) -- see design doc §3
	image = Image(data)
	image.header["DATE-OBS"] = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S.%f")
	image.header["IMAGETYP"] = self._image_type

4. Building the meta dict by iterating image.header collapses duplicate FITS keys. for key in image.header: meta[key] = ... writes into a plain dict, so duplicate/commentary cards (COMMENT/HISTORY, or a configured fits_headers entry colliding with a computed key) silently lose all but the last value on the wire. Not covered by any test.

pyobs-core/pyobs/modules/camera/basevideo.py

Lines 324 to 327 in 85d6374

	meta: dict[str, Any] = {}
	for key in image.header:
	meta[key] = self._json_safe(image.header[key])
	meta["DTYPE"] = data.dtype.newbyteorder("<").str

5. _json_safe() duplicates existing numpy-scalar normalization. pyobs/comm/xmpp/serializer.py:73-74 already has if isinstance(value, np.generic): value = value.item() for the same reason. This adds a second local copy of the same idiom instead of reusing/extracting a shared helper.

pyobs-core/pyobs/modules/camera/basevideo.py

Lines 335 to 340 in 85d6374

	@staticmethod
	def _json_safe(value: Any) -> Any:
	"""Convert a FITS header value to a JSON-serializable Python scalar."""
	if isinstance(value, np.generic):
	return value.item()
	return str(value) if isinstance(value, StrEnum) else value

6. Plan checklist claims a trade-off comment that isn't there. The checklist item is marked [x] and requires flagging "in a code comment that it trades off against _activate_camera()/_deactivate_camera() cost" — but sleep_time: int = 60 has no such comment anywhere in the file.

pyobs-core/specs/plans/2026-08-11-basevideo-raw-frame-streaming.md

Lines 70 to 76 in 85d6374

	— see design doc §3 for why. This is producer/wire-contract scope (`pyobs-core`), not a
	guiding consumer module.
	- [x] Lower `sleep_time`'s default from 600s to **60s** (`basevideo.py`, param TBD exact location) —
	a raw-only consumer session that dies previously left hardware streaming for up to 10 minutes
	with nothing consuming it. 60s is a starting point, not measured — flag in a code comment that
	it trades off against `_activate_camera()`/`_deactivate_camera()` cost (driver-specific,
	mostly unknown today) and risks flapping if that cost is high relative to 60s. Stays a single

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[thusser]

Thanks, useful review. I agree with 1, 2, and 6 and will fix those. Pushing back on 4 and 5, and 3 is real but has a tradeoff.

1. Valid, real liveness bug. Will keep _active_time fresh independent of frame arrival.

2. Valid. Will capture the timestamp in _set_image() and carry it in LastImage instead of stamping at send time.

3. Real, but precomputing in _set_image() (the obvious fix) contradicts the design's "costs nothing when no raw client is connected". Would need a lazy cache keyed by frame_num. Happy to do it if multiple simultaneous raw consumers is a near-term reality, otherwise I'd leave it.

4. Not as stated. astropy stores COMMENT/HISTORY as a _HeaderCommentaryCards list, so meta['COMMENT'] = header['COMMENT'] preserves all cards; iteration yields the key twice but writes the same full list both times. And non-commentary duplicates can't happen here because the mixin uses header[key] = ... assignment (overwrite), never append. Nothing is lost.

5. Technically true but it's a two-line idiom; extracting a shared helper would couple the camera module to the XMPP serializer. The StrEnum branch isn't in the serializer's path either. I'd leave it.

6. Valid, sloppy of me. Will add the comment.

[thusser]

Filed #769 to track the lazy per-frame-num cache for #3 (deferred until multiple simultaneous raw consumers are a near-term reality). Sounds good on the rest — thanks.

[thusser]

Agreed, that's the right split. One consequence worth stating up front for #1: refreshing _active_time independent of frame arrival means a connected-but-idle raw client keeps the hardware awake indefinitely (producer paused/dead but connection still held). That's correct per design §5 and matches what video_handler already does, just noting it so it's a deliberate behavior, not an accident.