Historical recipe — not current setup guidance. Measurements and implementation links below belong to their original workload and revision. Deployment labels and defaults may be obsolete. Use the reviewed performance recipes; browse historical evidence.

AVPlumber · Mixer optimization cookbook

Browser frame hand-off

Implementation links are pinned to develop at c20464a5 (2026-10-09). The mixer has changed since; this page was checked against develop at 8fa15c92 on 2026-10-13. Measurements retain their original workload and scope. Watch the current 192-input L4 demo.

Current scope. The poll-based handoff and reconnect behavior remain relevant. The CPU A/B below is historical; crash/reload frame holding has a separate validation scope.

Each browser window passes its painted frames to the mixer as DMA-BUF descriptors over a Unix socket, and the mixer acks every frame back (since 2026-10-12 one ack per arriving frame, not the moment a frame is let go). The sender's socket thread now sleeps in poll() instead of waking every millisecond, a vanished socket file is re-bound, and a failed page reloads without dropping the mixer's connection. While a failed or crashed page reloads, the sender by default holds: it sends nothing more, so the mixer keeps showing the page's last frame instead of Chromium's error page.

Measured: old vs. new browser image

Same 110-source 1080p25 show (40 NVDEC, 36 browser pages, 30 raw NV12 files and 4 DSK key pages) on the 16 GB T4 test host, with the same avplumber build. Only the browser image changed.

Browser wake-ups fell by about 35,000 a second, consistent with 1000 a second for each of the 40 windows. Even so, the table measures everything that changed between the two images, not the poll() rewrite alone. The 5 ms cut-latency difference is within run-to-run noise.

What changed

1. The socket thread waits in poll(). Before, each window's accept thread tried accept(), read acks from every client, then slept 1 ms: about 1000 wake-ups a second per window. Now it blocks in poll() on an eventfd (stop, re-bind, client removal), the listening socket and every client, and reads each ack as it arrives. Acks are read before new connections are accepted, so a reused descriptor number is never taken for the old client. A descriptor already removed is ignored. A persistent error pauses 1 ms, so poll() cannot spin.
2. A vanished socket file is re-bound. The 1 s socket monitor notices the missing file and calls createServer, which binds a new socket and moves it under the old descriptor with dup3, so connected consumers keep their frames. If that fails, the file is unlinked, since nothing listens behind it, and the next check retries. Before, createServer returned early and the file stayed gone.
3. Failed pages reload; the capture channel stays. A main-frame load failure, a load past the watchdog (30 s by default) or a renderer crash reloads the page after 1 s, doubling up to 30 s while reloads keep failing, and logs each failure and the delay to the next reload to stderr. Sub-frame failures and ERR_ABORTED (a cancelled or superseded navigation) are ignored. The consumer keeps its connection and the frames it holds. Before, any did-fail-load tore the window down: the socket closed, the mixer quarantined its frames, and a failed re-create left the source frozen for good with no alarm. A renderer crash had no handler at all.
4. Hold the last frame. A main-frame load failure or a renderer crash also puts the window's capture channel on hold: each paint is dropped as held and its texture goes straight back to Chromium, so the mixer's repeat_last_frame keeps showing the source's last frame instead of Chromium's empty error page or a half-loaded reload. A load watchdog timeout reloads without holding, because a slow page is still painting its own content. The hold needs a frame to hold: until the window has delivered at least one frame to a connected consumer, its paints go through even while held. The hold ends at the first did-finish-load with no failure since the last reload; Chromium also fires did-finish-load for its own error page, and that one does not count. A refresh or URL update starts a clean attempt, so its clean load also ends the hold. /status counts held paints under droppedReasons.held. The window option is holdLastFrame (default true); the mixer sets it from each browser source's hold_last_frame, and --dmabuf-open windows always hold. The mixer checks that the browser service echoes holdLastFrame back, as it already did for ringSize: a browser service too old for the option stops the mixer at start with “Browser service did not apply holdLastFrame; update dma-browser before starting the mixer”. Without the check, such a service would ignore the option, run without the hold, and have every window closed and reopened on each mixer start, because its windows never match the requested settings. Before, the error page was sent, so the source went transparent or black until a reload loaded cleanly.
5. Per-window frame queue. A show's browser_frame_queue (1 to 9, default 9 at every rate; the earlier key browser_ring_size is still read), sent as each window's ringSize, limits how many of that window's frames may be out of the browser at once. It is not a pool of buffers: the buffers are Chromium's (Browser frames go back one per new frame). Without it, the process-wide DMA_BROWSER_DMABUF_POOL_SIZE applies (default 11).
6. Two no-op nodes dropped. Each browser window's mixer chain ran an assume_video_format node and a settb filter_video, each on its own thread. Neither did anything: drm_prime_to_cuda reads geometry and format from every frame, and smooth_timestamps already stamps in 1/fps. Both are gone. The filter's one real job, tagging Chromium's premultiplied alpha, moved into the mixer's colour node (add_source takes premultiplied_alpha) and, since 2026-10-13, to the source's fan-out, which stamps alpha_mode=premultiplied with the colour tags; a browser source has no colour node any more (Colour tags at the fan-out). Measured on a later show than the table above (68 inputs: 18 NVDEC, 29 browser pages, 17 raw NV12 files and 4 browser key pages, 60 fps, T4 test host with 16 vCPU): avplumber threads 555 → 491, avplumber CPU 4.72 → 4.63 cores, within run-to-run noise. A cleanup, not a CPU win.

At a glance

• WhatMostly browser sender changes, in deps/dma-browser:
  • the fd-passing thread waits in poll();
  • a vanished capture socket is re-bound;
  • failed loads and renderer crashes reload the page;
  • the window holds its last frame while a failed or crashed page reloads;
  • a per-window frame queue.

  On the mixer side only Python changed: each browser source's hold_last_frame reaches its window, a browser service that ignores the option stops the mixer at start, each window's assume_video_format and settb filter_video nodes are gone, and Chromium's premultiplied alpha is tagged on blended browser sources and keys, at first by the colour node and now by the source's fan-out. The avplumber binary is unchanged.

• WhyWith 40 windows, the 1 ms loop alone meant about 40,000 wake-ups a second, most of them finding nothing. A page that failed to load, or whose renderer crashed, froze its source with no alarm. With reloads in place, a failed page's source showed Chromium's empty error page, transparent or black, until a reload loaded cleanly.
• Latency0 frames added to program and to command-to-screen: no queue, buffer or node added; item 6 only removes two per window. Acks are read as they arrive instead of at the next 1 ms tick, so each frame returns to the browser's pool up to 1 ms sooner. Median cut latency measured 70 ms old and 75 ms new, within run-to-run noise. Holding adds no queue either: the mixer repeats the last frame at the canvas rate, as it already does for a page that stops painting.
• Side effects

  While a page is down, Chromium paints its own empty error page. After a main-frame load failure or a renderer crash, a window that has already delivered a frame no longer sends it: the sender drops paints until a reload loads cleanly, and the mixer's repeat_last_frame keeps showing the last frame.

  A page that fails its first load has no frame to hold, so its error page is sent until one frame reaches a consumer, and then held. The source shows transparent or black until a clean load, but the mixer's chain gets a frame and can start.

  A load watchdog timeout alone does not hold: a slow page is reloaded but keeps sending its live paints. A browser source with hold_last_frame: false passes the error page through, transparent or black until the next clean load. Sub-frame failures and ERR_ABORTED are only logged.

• Cost0 nodes, 0 queues, 0 VRAM for the sender changes: browser processes held 1,272 MiB before and 1,265 MiB after. Item 6 removes two nodes and their queues from every browser window's chain: avplumber threads 555 → 491 on the 68-input show. One eventfd per window; each wake-up rebuilds the pollfd list of the eventfd, the listener and the window's clients. The hold is one flag check per paint, and a held paint's texture is released at once. Code: in the fd-passing addon, +51/−28 lines for the poll() loop and +39/−16 for the re-bind; a 60-line page reloader with tests. The hold: +32/−8 lines in the browser sender and +13/−5 in the mixer's Python, without tests and docs.
• Risk

  Low. The poll() loop's hazards are covered: acks are read before accept(), removed descriptors are skipped, removeClient() calls wake() because close() does not end a poll(), and a persistent error pauses 1 ms. A URL that never loads retries every 30 s indefinitely, logged each time.

  From the code, not observed: the “frame to hold” test counts frames over the window's lifetime, not per consumer. The mixer reuses a matching window, and its start-up refresh ends a hold only if the page then loads cleanly. So a mixer restarted while a reused window is held gets no frame from it until the page loads cleanly, and start-up fails after --preheat-timeout (60 s by default). Closing that window first, so the mixer opens a new one, or setting hold_last_frame: false on the source avoids it.

• Switch it offNo runtime switch for the reload. hold_last_frame: false on a browser source turns off only the hold, for that window. To remove the changes, revert the browser and mixer commits together and rebuild the browser image: a mixer that sends holdLastFrame to a browser service without it stops at start. The avplumber binary needs no change.

Where in the code

• deps/dma-browser/addons/fdpass/addon.cc: wake() and acceptLoop(), one poll() with acks read before accepting; source the 1 ms pause on a persistent error.
• addon.cc: a descriptor no longer in the client list is ignored; source removeClient() retires the client's frames, closes it and calls wake().
• addon.cc: rebind(), dup3 under the same descriptor, unlink on failure; source createServer re-binds a server whose file vanished.
• deps/dma-browser/src/main/capture/FrameCaptureChannel.ts: the 1 s socket monitor that calls createServer.
• deps/dma-browser/src/main/PageReloader.ts: which load failures count, and the doubling backoff.
• deps/dma-browser/src/main/ManagedWindow.ts: load failures, the watchdog and renderer crashes all reload the page; source the 1 s and 30 s delays.
• ManagedWindow.ts: recover() holds for a load failure or a crash; the watchdog passes hold = false. source a clean did-finish-load ends the hold; source the window reports holdLastFrame, which the mixer checks.
• FrameCaptureChannel.ts: hold(); source a paint is dropped as held only once a frame went out; source a frame counts as sent only when a consumer received it.
• PageReloader.ts: loaded() is false after a failure since the last reload, so the error page's own did-finish-load does not end the hold.
• deps/dma-browser/src/main/config/ConfigService.ts: holdLastFrame defaults to true; WindowConfig.ts the window option.
• pyplumber/mixer/config.py: a source's hold_last_frame, default true; source a config error unless it is a boolean on a browser source.
• pyplumber/mixer/application.py: the source's hold_last_frame becomes its window's holdLastFrame.
• pyplumber/mixer/dmabuf_inputs.py: --dmabuf-open windows always hold; source the mixer stops when the browser service does not apply ringSize or holdLastFrame; source the repeat_last_frame node that repeats the last frame at the canvas rate.
• dmabuf_inputs.py: why the chain has no format or time-base node of its own: geometry and format come from each frame, and smooth_timestamps stamps in 1/fps; source smooth_timestamps writes the chain's output edge directly, with no filter after it.
• pyplumber/mixer/graph.py (pinned to develop at 8fa15c92): _frame_color adds alpha_mode: premultiplied to the tags the fan-out stamps for a source registered with premultiplied_alpha; pyplumber/mixer/application.py sets it for the browser sources that scenes blend or downstream keys use.
• deps/dma-browser/src/main/Application.ts: the window's ringSize, else the process-wide pool size.
• Docs: dma-browser README · Frame lifetime and transport counters (the ack protocol); the paragraph above it describes page recovery and holdLastFrame, but not yet its two exceptions: a page that fails its first load still sends its error page, and a watchdog reload keeps sending live paints. Mixer config · sources lists hold_last_frame. Browser CPU is per painted frame puts the hand-off in Chromium's per-frame cost: the browser's main process (paint event, fd pass, release ack) is about 6 % of a core per window at 60 paints/s.

Source links are pinned to the reviewed revision.