From 6343890e82e1fff8981de582b30ac5ee945b35af Mon Sep 17 00:00:00 2001 From: Christian Date: Wed, 28 Oct 2026 00:19:42 +0100 Subject: [PATCH 1/3] fix(encoders): live view should now work, but bad --- backend/base_config.yaml | 6 +- backend/docs/LIVE-IMAGE-PIPELINE.md | 28 ++++----- .../broadcasters/encoders/h264_encoder.py | 8 ++- backend/newswitch/broadcasters/frame.py | 1 + backend/newswitch/routes/ws/liveview.py | 62 ++++++++++++++----- backend/tests/test_auth.py | 28 ++++++++- 6 files changed, 96 insertions(+), 37 deletions(-) diff --git a/backend/base_config.yaml b/backend/base_config.yaml index 36074e4..1d87248 100644 --- a/backend/base_config.yaml +++ b/backend/base_config.yaml @@ -4,7 +4,7 @@ # Host and port are not set here. They come from BACKEND_HOST / BACKEND_PORT in the # repository's root .env (deployment via docker is still an open point). -use_virtual_microscope: true +use_virtual_microscope: false # SQLite file of the rekuest agent (state history); relative to the working directory db_path: agent_data.db available_cubes: [cube1, cube2, cube3] @@ -15,8 +15,8 @@ schema_dir: configs/schemas # Device configuration; bare names are resolved against config_dir. # newswitch never writes static_config_path; changes always go into persistent_config_path. -static_config_path: newswitch-config.yaml -persistent_config_path: newswitch-config.persistent.yaml +static_config_path: camTest_config.yaml +persistent_config_path: camTest_config.persistent.yaml # true: read static_config_path; on shutdown persistent_config_path is overwritten # with it plus the runtime changes # false: read (and write back) persistent_config_path; on first start it is created diff --git a/backend/docs/LIVE-IMAGE-PIPELINE.md b/backend/docs/LIVE-IMAGE-PIPELINE.md index 6897050..55664ba 100644 --- a/backend/docs/LIVE-IMAGE-PIPELINE.md +++ b/backend/docs/LIVE-IMAGE-PIPELINE.md @@ -277,8 +277,8 @@ sequenceDiagram H->>H: accept BR->>H: auth frame with token H->>H: authenticate_stream_websocket, close 1008 if invalid - H->>H: get_broadcaster_from_websocket - Note over H: Fails today, the agent has no get_context_for_type (issue 1) + H->>H: await_broadcaster, context frame_broadcaster from agent.contexts + Note over H: waits up to 10 s for the agent's startup hooks, then closes 1011 H->>FB: get_subscription_(slot, H264EncoderConfig()) FB->>EN: create if no encoder for (slot, config), store in _encoders FB->>EN: astart() if not running @@ -303,7 +303,7 @@ sequenceDiagram end BR--xH: disconnect (LivePlane unmounts, e.g. live view stopped) - Note over H: noticed only when the next send_bytes fails (issue 3) + Note over H: noticed only when the next send_bytes fails (issue 1) H->>FB: arelease_subscription(subscription) FB->>EN: aunsubscribe, astop() if it was the last subscriber EN->>FF: kill @@ -396,17 +396,12 @@ after `onopen` the hook sends the auth frame (`authFrame()`, the token). A close Tracked in `.claude/OpenPoints.md`. -1. **The stream route crashes on every connection (OP #28).** - `get_broadcaster_from_websocket` (`liveview.py:75`) calls `agent.get_context_for_type(...)`, - which rekuest_next 2.3.1 does not have (it offers `agent.contexts[key]` / - `aget_context(key)`; the key is `frame_broadcaster`). The handler raises `AttributeError` - before `get_subscription_`. No encoder is ever created, and no image reaches the frontend. - Reproduced with camTest: 0 encoders and 0 bytes with a connected, authenticated client. - `tests/test_auth.py` only tests the rejected path. -2. **ffmpeg's stderr is never read (OP #29).** `stderr=PIPE` (`h264_encoder.py:118`) without a - reader: ffmpeg writes progress lines continuously, and once the pipe buffer (about 64 KB) is - full, ffmpeg blocks and the stream freezes. -3. **Further risks (OP #30):** +Fixed on 2026-10-27: the stream route crashed on every connection (it called +`agent.get_context_for_type`, which rekuest_next 2.3.1 does not have), and ffmpeg's unread +stderr pipe froze the H.264 stream after a few minutes (ffmpeg now runs with +`-loglevel error -nostats`, stderr discarded). + +1. **Further risks (OP #30):** - Thread safety. `encode_frame` runs on the worker thread: H.264 calls `StreamWriter.write` there, Zstd calls `asyncio.Queue.put_nowait`. Neither is thread-safe. - Dropped H.264 chunks. The queue keeps one 4096-byte chunk and drops the oldest. Dropping @@ -423,7 +418,7 @@ Tracked in `.claude/OpenPoints.md`. `uint8` full frames (unused today). - Dead frontend code. `components/microscope/LiveView.tsx` is not mounted anywhere; its `StreamingView` connects to `VITE_WEBSOCKET_URL + "/video"`, a route that does not exist. -4. **Frame rate limited by `koil.sleep` (OP #3).** The live loop's 10 ms pause takes about +2. **Frame rate limited by `koil.sleep` (OP #3).** The live loop's 10 ms pause takes about 140 ms, which limits the stream to about 7 fps. --- @@ -442,4 +437,5 @@ Tracked in `.claude/OpenPoints.md`. `--verbose` is given. - **Browser side:** DevTools → Network → WS: is there a connection to `/stream/h264/`, on the right port, and with which close code? 1006 (no close frame) points to a - server-side exception, 1008 to a rejected token. + server-side exception, 1008 to a rejected token, 1011 to a FrameBroadcaster the agent did + not provide within 10 s (startup hooks failed or still running). diff --git a/backend/newswitch/broadcasters/encoders/h264_encoder.py b/backend/newswitch/broadcasters/encoders/h264_encoder.py index 3146e62..8752c82 100644 --- a/backend/newswitch/broadcasters/encoders/h264_encoder.py +++ b/backend/newswitch/broadcasters/encoders/h264_encoder.py @@ -71,8 +71,14 @@ async def astart(self) -> None: if self._running: return + # Nobody reads ffmpeg's stderr, and a full pipe would block ffmpeg and freeze the + # stream: keep it quiet (no banner, no progress line) and discard what is left. command = [ "ffmpeg", + "-hide_banner", + "-loglevel", + "error", + "-nostats", "-y", "-f", "rawvideo", @@ -115,7 +121,7 @@ async def astart(self) -> None: *command, stdin=asyncio.subprocess.PIPE, stdout=asyncio.subprocess.PIPE, - stderr=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.DEVNULL, ) self._running = True self._reader_task = asyncio.create_task(self._read_output()) diff --git a/backend/newswitch/broadcasters/frame.py b/backend/newswitch/broadcasters/frame.py index 28794f2..beb1c57 100644 --- a/backend/newswitch/broadcasters/frame.py +++ b/backend/newswitch/broadcasters/frame.py @@ -136,6 +136,7 @@ async def arelease_subscription(self, subscription: EncoderSubscriptionProtocol) def _schedule_encoder_frames(self, detector_slot: int, frame: np.ndarray) -> None: """Schedule frame encoding for active encoders of one detector slot.""" + # print(f"Scheduling frame for detector slot {detector_slot} with shape {frame.shape}, dtype {frame.dtype}, max {frame.max()}, min {frame.min()}, encoders: {len(self._encoders.items())} ") for (slot, _), encoder in self._encoders.items(): if slot != detector_slot: continue diff --git a/backend/newswitch/routes/ws/liveview.py b/backend/newswitch/routes/ws/liveview.py index 204d493..8b8e35d 100644 --- a/backend/newswitch/routes/ws/liveview.py +++ b/backend/newswitch/routes/ws/liveview.py @@ -4,6 +4,7 @@ from fastapi import APIRouter, WebSocket, WebSocketDisconnect import asyncio +from rekuest_next.agents.context import get_context_name from newswitch.auth import Authenticator from newswitch.broadcasters import FrameBroadcaster, ZstdEncoderConfig, H264EncoderConfig @@ -14,6 +15,12 @@ #: because the frame is sent from the client's `onopen` handler. AUTH_FRAME_TIMEOUT = 10.0 +#: How long a stream waits for the agent to provide the FrameBroadcaster. The agent's +#: startup hooks run in a task started after the app began serving, so a client that +#: connects right after startup can arrive before the context exists - and the frontend +#: does not reconnect when the socket is closed. +BROADCASTER_WAIT_TIMEOUT = 10.0 + async def authenticate_stream_websocket(websocket: WebSocket) -> bool: """Consume and validate the client's opening auth frame. @@ -59,26 +66,43 @@ async def _close_unauthorized(websocket: WebSocket) -> None: pass -# This is a helper function to get the broadcaster from the app state via WebSocket. -# By default, the app agent, which is set on app.state.agent holds references -# to all contexts, including the FrameBroadcaster context which manages video streaming. -def get_broadcaster_from_websocket(websocket: WebSocket) -> FrameBroadcaster: - """ - Get the FrameBroadcaster from the app state via WebSocket. +async def await_broadcaster(websocket: WebSocket) -> FrameBroadcaster | None: + """Get the FrameBroadcaster from the agent's contexts, waiting until it is provided. - The broadcaster is set on app.state.agent context during startup. - """ - agent = getattr(websocket.app.state, "agent", None) - if agent is None: - raise RuntimeError("Agent not available") + The agent (`app.state.agent`) keeps its contexts in a dict keyed by context name; + `get_context_name` gives the same key rekuest assigns when the startup hook returns + the broadcaster. - broadcaster = agent.get_context_for_type(FrameBroadcaster) - if broadcaster is None: - raise RuntimeError("FrameBroadcaster not available") + Returns: + The broadcaster, or None if it did not appear within `BROADCASTER_WAIT_TIMEOUT`. + Raises: + TypeError: The context under the broadcaster's name is something else. + """ + contexts = websocket.app.state.agent.contexts + key = get_context_name(FrameBroadcaster) + deadline = asyncio.get_running_loop().time() + BROADCASTER_WAIT_TIMEOUT + + while (broadcaster := contexts.get(key)) is None: + if asyncio.get_running_loop().time() > deadline: + return None + await asyncio.sleep(0.1) + + if not isinstance(broadcaster, FrameBroadcaster): + raise TypeError( + f"Context {key!r} is a {type(broadcaster).__name__}, not a FrameBroadcaster" + ) return broadcaster +async def _close_unavailable(websocket: WebSocket) -> None: + """Close with 1011, tolerating a client that already went away.""" + try: + await websocket.close(code=1011, reason="frame broadcaster unavailable") + except RuntimeError: + pass + + @router.websocket("/zstd/{detector_slot}") async def stream_zstd(websocket: WebSocket, detector_slot: int) -> None: """ @@ -92,7 +116,10 @@ async def stream_zstd(websocket: WebSocket, detector_slot: int) -> None: if not await authenticate_stream_websocket(websocket): return - broadcaster = get_broadcaster_from_websocket(websocket) + broadcaster = await await_broadcaster(websocket) + if broadcaster is None: + await _close_unavailable(websocket) + return # Get subscription to shared encoder config = ZstdEncoderConfig(level=1, threshold=0.0, use_delta=True) @@ -137,7 +164,10 @@ async def stream_h264(websocket: WebSocket, detector_slot: int) -> None: if not await authenticate_stream_websocket(websocket): return - broadcaster = get_broadcaster_from_websocket(websocket) + broadcaster = await await_broadcaster(websocket) + if broadcaster is None: + await _close_unavailable(websocket) + return # Get subscription to shared encoder config = H264EncoderConfig() diff --git a/backend/tests/test_auth.py b/backend/tests/test_auth.py index 421b231..39a6aa6 100644 --- a/backend/tests/test_auth.py +++ b/backend/tests/test_auth.py @@ -7,8 +7,9 @@ """ import base64 +import time from pathlib import Path -from typing import Iterator +from typing import Callable, Iterator import pytest import yaml @@ -325,6 +326,31 @@ def test_stream_websocket_rejects_a_wrong_token(client: TestClient) -> None: assert excinfo.value.code == 1008 +def test_stream_websocket_accepts_an_in_band_token( + authed_app: FastAPI, client: TestClient, token: str +) -> None: + """An accepted auth frame subscribes the socket to a shared encoder. + + Zstd rather than H.264, so the test needs no ffmpeg. The encoder is checked rather + than received bytes: frames only flow while a live view runs. + """ + contexts = authed_app.state.agent.contexts + with client.websocket_connect("/stream/zstd/1") as websocket: + websocket.send_json({"type": "auth", "token": token}) + assert wait_until(lambda: "frame_broadcaster" in contexts) + assert wait_until(lambda: contexts["frame_broadcaster"].encoder_count == 1) + + +def wait_until(condition: Callable[[], bool], timeout: float = 5.0) -> bool: + """Poll `condition` until it holds; the server side runs on the client's portal.""" + deadline = time.monotonic() + timeout + while not condition(): + if time.monotonic() > deadline: + return False + time.sleep(0.05) + return True + + # ---------------------------------------------------------------- authenticator From 38933324e6414074b3148799abded58e4280fd9f Mon Sep 17 00:00:00 2001 From: Christian Date: Thu, 29 Oct 2026 00:32:28 +0100 Subject: [PATCH 2/3] docs(fixes): bug report for encoder --- docs/encoder_bugreport.md | 268 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 docs/encoder_bugreport.md diff --git a/docs/encoder_bugreport.md b/docs/encoder_bugreport.md new file mode 100644 index 0000000..e94d624 --- /dev/null +++ b/docs/encoder_bugreport.md @@ -0,0 +1,268 @@ +# Bugreport: H.264-Livebild zwischen `FrameBroadcaster` und Frontend + +Stand: 2026-10-28, Branch `KC/CamAdapter` (Commit `6343890`). + +## Symptome + +Simulierte Kamera aus uc2_cam_py (`use_virtual_microscope: false`, +`static_config_path: camTest_config.yaml`), Frontend über `just dev`. Die Frames kommen in +`FrameBroadcaster._schedule_encoder_frames` an. Mit aktivem Livestream im Frontend: + +- es wird nur ein Ausschnitt des Bildes dargestellt, +- die Bildrate ist sehr niedrig, +- nach einiger Zeit friert das Bild ein. + +## Kurzfassung + +| Symptom | Ursache | Bug | +|---|---|---| +| Einfrieren | Der H.264-Bytestrom wird im Backend zerstückelt (ein Drittel der Bytes und praktisch alle Keyframes gehen verloren). Der Browser-Decoder bricht beim ersten beschädigten Frame ab, und das Frontend erholt sich davon nicht. | 1, 2 | +| Ausschnitt | Die Live-Ebene ist ≈ 328 Szeneneinheiten groß, die 2D-Kamera zeigt bei `zoom={5}` aber nur Canvas-Pixel / 5 Einheiten. | 3 | +| niedrige Bildrate | `koil.sleep(0.01)` dauert ≈ 100 ms: Die Live-Loop schafft 10–13 fps statt der 20 fps der Kamera. Dazu kommen beschädigte Frames und die feste Annahme von 30 fps im Player. | 4, 1, 5 | + +Das Backend selbst friert nicht ein: In 3 Minuten Messung lief der Strom mit konstant ≈ 13 fps +bis zum WebSocket. + +## Messungen + +Aufbau: Backend in-process mit camTest (Auth aus, `camera_debug_window: false`), Live-View per +`POST /start_live_view`, ein Python-WebSocket-Client an `/stream/h264/1`. An jeder Stufe wurde +mitgezählt, und der empfangene sowie der vollständige ffmpeg-Strom wurden mitgeschnitten. Die +Mitschnitte wurden anschließend in headless Chromium (Playwright) über JMuxer 2.1.0 abgespielt, +mit denselben Optionen wie in `useH264LiveTexture`. Die Skripte lagen im Session-Scratchpad und +sind nicht im Repository. + +| Stufe | Messwert (Lauf über 180 s) | +|---|---| +| Kamera (konfiguriert) | 20 fps, 640×480, `uint16` | +| `broadcast_sync` ohne Client | 10,0 fps (Median-Abstand 100 ms) | +| `broadcast_sync` mit Client | 13,3 fps (Median-Abstand 88 ms) | +| `H264Encoder.encode_frame` | Median 2,3 ms, max. 107 ms, läuft im Detektor-Thread | +| ffmpeg-Ausgabe | 10,0 MB in 3200 Chunks; 80 Keyframes, jeder mit SPS/PPS; 7 Slices pro Bild | +| in `EncoderSubscription` verworfen | 812 Chunks = 3,3 MB (33 %) | +| WebSocket empfangen | 2387 Chunks (genau 1 pro Frame), 6,7 MB | +| davon SPS/PPS | 1 von 80 (nur der allererste) | +| davon IDR-Slices | 81 von 560 | +| Bilder ohne ersten Slice | 733 von 2388 (31 %) | + +Abspielen im Browser (Mitschnitt über 25 s): + +- **Vollständiger ffmpeg-Strom:** 327 von 327 Frames decodiert, kein Fehler. +- **Beim Client angekommener Strom:** `video.error` Code 3, + `PIPELINE_ERROR_DECODE: Failed to send video packet for decoding` bei Medienzeit 0,627 s. + JMuxer meldet danach `InvalidStateError` und setzt sich zurück, ohne dass bis zum Ende des + Mitschnitts noch ein Frame decodiert wird. + +--- + +## 1 · H.264-Bytestrom wird in der Subscription-Queue zerstückelt (Hauptursache) + +**Beschreibung.** +[`EncoderSubscription`](../backend/newswitch/broadcasters/encoders/subscription.py#L29-L31) +hält genau einen Chunk (`asyncio.Queue(maxsize=1)`). Ist die Queue voll, verwirft +[`push_chunk`](../backend/newswitch/broadcasters/encoders/subscription.py#L56) den ältesten. +Für Zstd ist das vertretbar, weil dort ein Chunk ein ganzes Frame ist. Für H.264 sind es +4096-Byte-Stücke eines fortlaufenden Bytestroms +([`_read_output`](../backend/newswitch/broadcasters/encoders/h264_encoder.py#L133-L138)). + +Dass fast immer etwas verworfen wird, liegt an asyncio: `StreamReader.read(4096)` kehrt ohne +Rückgabe an den Event-Loop zurück, solange sein Puffer Daten enthält. Die Reader-Task schiebt +deshalb alle Chunks eines ffmpeg-Ausgabeblocks direkt hintereinander in die Queue, und der +WebSocket-Handler ([`liveview.py:185`](../backend/newswitch/routes/ws/liveview.py#L185)) kommt +erst danach wieder an die Reihe. Pro Frame überleben so nur die letzten ≤ 4096 Bytes, gemessen: +genau ein WebSocket-Chunk pro Frame. + +Folgen: + +- Keyframes (IDR mit SPS/PPS, meist deutlich größer als 4 KB) kommen praktisch nie an: 1 von 80. + Damit gibt es keinen Punkt, an dem sich der Decoder erholen kann. +- `-tune zerolatency` lässt x264 jedes Bild in 7 Slices aufteilen (sliced threads). Fehlt der + erste Slice eines Bildes (31 % der Bilder), hängt JMuxer die restlichen Slices an das + vorherige Sample. Es entstehen ungültige Samples, und der Decoder bricht ab (siehe Bug 2). + Ein fehlertoleranterer Decoder würde stattdessen nur Teile des Bildes (einzelne Streifen) + aktualisieren, was ebenfalls wie ein Ausschnitt aussehen kann. + +Bereits als Risiko in OP #30 und +[`LIVE-IMAGE-PIPELINE.md`](../backend/docs/LIVE-IMAGE-PIPELINE.md) §8 erwähnt. Hiermit ist +bestätigt, dass dies die Hauptursache ist. + +**Fixvorschlag.** + +1. Sofortmaßnahme: Der H.264-Pfad darf keine Bytes verwerfen. Eine Queue ohne Größenlimit + (oder ein großes Limit) für H.264-Subscriptions, z. B. über einen Parameter `maxsize` von + `EncoderSubscription`, den der H.264-Encoder anders setzt als der Zstd-Encoder. Zusätzlich + in größeren Blöcken lesen (`read(65536)`), das spart WebSocket-Nachrichten. +2. Robuste Lösung: ganze Frames (Access Units) statt 4096-Byte-Stücken verteilen. Dazu z. B. + ffmpeg mit `-x264-params aud=1` starten und am Access Unit Delimiter trennen. Läuft die Queue + eines langsamen Clients über, alles bis zum nächsten IDR (mit SPS/PPS) verwerfen. Der Client + verliert dann ganze Frames, aber nie Teile davon. Ein neuer Client bekommt erst ab dem + nächsten Keyframe Daten. Alternativ SPS/PPS und den letzten IDR zwischenspeichern und beim + Subscribe zuerst senden. +3. Test: einen Ausgabeblock > 4096 Bytes einspeisen und prüfen, dass alle Bytes vollständig und + in Reihenfolge beim Subscriber ankommen. + +Die Zstd-Route verwendet `use_delta=True` +([`liveview.py:125`](../backend/newswitch/routes/ws/liveview.py#L125)). Dort zerstört ein +verworfenes Delta-Frame die Rekonstruktion ebenfalls. Das betrifft das Frontend derzeit nicht, +weil der Zstd-Pfad dort nicht genutzt wird. + +## 2 · Frontend erholt sich nicht von einem Decoder-Fehler (dauerhaftes Einfrieren) + +**Beschreibung.** +[`useH264LiveTexture`](../frontend/src/components/stage/hooks/useH264LiveTexture.tsx#L66-L98) +setzt weder JMuxers `onError` noch einen Listener für `error` am `