🪟 Mosaic

The Mosaic page provides a live, at-a-glance grid of stream previews so you can monitor multiple feeds at once. Previews are low-FPS JPEG snapshots, optimized for quick scanning rather than full playback.
Double-clicking a playable stream opens full-framerate playback. Recast-only streams display an explanation instead.

Open Mosaic

• Navigate to Mosaic from the left sidebar.
• Only streams marked as active appear in the grid.

Mosaic pages (tabs)

Mosaic is organized into pages (tabs) so you can group streams by mission, team, or geography.

• Add - creates a new Mosaic page.
• Edit - rename the current page and reassign streams using the Available/Assigned lists.
• Remove - deletes the current page (disabled when only one page exists).

To add streams to the mosaic page, use the transfer list in the edit dialog:

Mosaic pages, assignments, and ordering are stored in your browser's local storage. They are not shared with other users or devices.

Organize streams

• Reorder within a page: drag a stream card and drop it onto another stream card to reposition it.
• Move between pages: drag a stream card and drop it onto a different tab.
• Open a stream: double-click a card to jump to the Player view for that stream.
• Select a card: click once to highlight; click outside to clear the selection.

Preview behavior

• Previews refresh automatically.
• Refresh cadence is adaptive: faster when fewer than 10 streams are shown, slower for larger mosaics.
• No preview means the server has not produced a snapshot yet.
• Timeout indicates the stream is waiting for data.
• Each image shows its capture age. A successful browser refresh can return the same cached image, so its age continues increasing until the server captures a new frame.
• The last valid image remains visible during temporary capture failures. Offline and timeout states take precedence.

Configuration parameters

Mosaic previews are configured in Server Configuration -> Preview. These values control how the backend captures preview frames for the Mosaic grid (and other preview consumers).

Setting	Field	Default	Description
Preview workers	previewWorkers	6	Maximum concurrent adaptive preview sessions, including startup and cleanup. More workers can refresh waiting channels faster, using more CPU, GPU and RAM.
Preview RAM budget (MiB)	previewMemoryBudgetMiB	512	Operating budget for adaptive preview helpers and their owned queues/cache. Zero restores 512 MiB. Does not include playback/recast decoding.
Recast-only preview interval (ms)	recastPreviewIntervalMs	5000	Recast-only: delay after each successful JPEG before another capture becomes eligible. Zero restores 5000 ms. Keyframes and resource limits can extend the actual interval.
Preview framerate	previewFramerate	1	Target frames per second for playback previews. Recast-only uses its separate interval. Higher values increase load.
Preview width	previewWidth	320	Output width of preview images in pixels.
Preview height	previewHeight	180	Output height of preview images in pixels.
Capture timeout (ms)	previewCaptureTimeoutMs	12000	Maximum time allowed for one preview capture attempt before it is treated as a miss and retried later.
Warm-up grace (ms)	previewTargetWarmupGraceMs	15000	Grace period after creating a preview target where misses are tolerated while the stream starts producing frames.
Backoff min (ms)	previewBackoffMinMs	1000	Initial delay before retrying after a capture miss. Retry delay increases exponentially on consecutive misses.
Backoff max (ms)	previewBackoffMaxMs	30000	Upper limit for retry delay between capture attempts after misses. Must be greater than or equal to Backoff min.

Notes:

• Values must be zero or positive. Setting a value to 0 uses the built-in default.
• For best results, keep width/height close to a 16:9 ratio to match the Mosaic card aspect ratio.
• Changes apply at runtime; the next snapshot cycle will use the new settings.
• Actual preview cadence depends on CPU load, stream profile/encoding complexity, the number of active streams, and worker availability. Setting a framerate is a target, not a guarantee.

Adaptive preview rollout (Windows and Linux)

Recast-only uses supervised one-shot previews by default. Playback preview migration remains opt-in, pending cross-platform media and memory release checks; set SKY_VIEW_ADAPTIVE_PREVIEW=1 to include playback modes in the supervisor. Package the matching skyview-jpeg-extractor helper alongside the server; SKY_VIEW_JPEG_EXTRACTOR_PATH can select its location. An absent or incompatible helper disables adaptive previews with a diagnostic.

For supervised previews (Recast-only by default; playback when opted in):

• A small set of playback streams can keep their own decoder processes running for frequent images.
• Recast-only always releases its preview decoder after one fresh JPEG, even for a single stream. The first capture starts immediately when capacity permits; later captures default to a five-second delay. Forwarding continues independently. Disabling previews leaves no preview decoder or subscription after cleanup.
• Larger sets take turns within the worker and memory limits. Each reassignment creates a fresh process; decoder state is never reused between streams.
• The worker count includes processes still stopping. Hung processes are terminated; unreaped processes retain their slots until exit.
• The server reserves 20% memory headroom. RSS sampling allows brief overshoot, so this setting is not a hard operating-system memory limit. Streams too large for the budget are deferred until their source or settings change.
• Every eligible running stream receives background preview service, including streams not shown on the selected Mosaic tab. Actual freshness may be slower than the requested framerate under load.
• Changing preview settings restarts preview sessions without restarting playback or recasting. RTSP previews temporarily use an additional source connection while their helper is assigned.

Without the adaptive flag, playback modes retain their existing preview implementation. The supervised worker/RAM limits apply to Recast-only helpers and exclude legacy playback decoders. With the flag, all preview helpers share those bounds. Missing helpers never cause Recast-only to fall back to continuous decoding.