junkpile

41 · wgpu Appliance Runtime

A native Tauri 2 + wgpu example for running Junkpile as an unattended media appliance.

The application creates one authoritative GPU texture and can route it to:

• Optional native preview
• NDI
• Syphon on macOS or Spout on Windows
• H.264 or ProRes file recording

Both application windows can remain hidden while offscreen rendering and external outputs continue.

Purpose

This example demonstrates the operational layer needed for installations, dedicated playback/capture machines, gallery systems, embedded workstations, and distributed render nodes:

• Configuration-driven startup
• Optional output autostart
• Windowless operation
• CLI overrides
• Continuous machine-readable health snapshots
• Timed runs
• Clean multi-output shutdown
• Runtime inspection without restarting the renderer

The unresolved network-streaming examples are not included.

Requirements

Core:

• Rust
• Node.js
• Tauri CLI 2
• FFmpeg for recording

Optional outputs:

• NDI SDK and runtime for NDI
• Syphon framework on macOS, bundled in the project
• Spout2 build requirements on Windows

Development modes

Normal control mode

npm install
npm run dev

The controls window opens. The appliance configuration is loaded, but outputs do not autostart with the built-in defaults.

Headless NDI + Syphon/Spout appliance

npm run dev:appliance

Equivalent application arguments:

--headless --autostart --profile headless-shared-1080p60

Both windows are hidden. NDI and the platform-native sharing sink start automatically. Stop the development process with Ctrl+C.

Headless NDI + H.264 capture appliance

npm run dev:capture

Equivalent arguments:

--headless --autostart --profile headless-capture-1080p30

The runtime writes a finalized H.264 file to the configured recording folder while also publishing NDI.

Appliance configuration

Edit:

config/appliance.json

Built-in configuration:

{
  "schemaVersion": 1,
  "startupProfile": "headless-shared-1080p60",
  "autoStartOutputs": false,
  "controlsVisible": true,
  "previewPolicy": "profile",
  "heartbeatMs": 1000,
  "statusFile": "appliance-status.json",
  "exitAfterSeconds": null
}

Fields

Field	Purpose
startupProfile	I/O profile armed during startup
autoStartOutputs	Starts all external outputs enabled by the startup profile
controlsVisible	Initial controls-window state
previewPolicy	profile, hidden, or visible
heartbeatMs	Status-file update interval, 200–60000 ms
statusFile	Absolute path or path relative to the appliance config directory
exitAfterSeconds	Optional timed shutdown; null runs indefinitely

Use Apply appliance config after editing. Applying the configuration:

1. Stops active outputs and waits for recording finalization.
2. Reloads and validates appliance.json.
3. Arms the requested I/O profile.
4. Applies controls and preview visibility.
5. Starts outputs when autostart is enabled.
6. Writes a fresh status snapshot.

CLI overrides

Supported application arguments:

--profile <id>
--autostart
--no-autostart
--headless
--show-controls
--hide-controls
--show-preview
--hide-preview
--profile-preview
--status-file <path>
--exit-after <seconds>

CLI values override appliance.json for the current launch without rewriting the file.

Machine-readable status

The runtime continuously writes a JSON status snapshot. In development, the default is:

config/appliance-status.json

The file includes:

• Startup and active profiles
• Applied CLI overrides
• Uptime and heartbeat timestamp
• Window policies
• Output-active state
• Renderer and GPU information
• Recording status and drop diagnostics
• NDI status and queue telemetry
• Syphon/Spout status and queue telemetry
• Configuration watcher status
• Last runtime event and error

The file is written through a temporary file and replacement step so external monitoring tools do not normally read a partially serialized snapshot.

Window behavior

• Closing the controls window performs a clean multi-output shutdown.
• Closing the preview window hides presentation while offscreen rendering continues.
• Hide controls intentionally removes the UI while the runtime continues; use Ctrl+C during development to stop a fully hidden run.
• Show preview temporarily restores local inspection.
• Stop outputs and exit finalizes recording, stops all external sinks, writes final status, and exits.
• In a fully hidden development launch, use Ctrl+C when no controls window is available.

Included profiles

The I/O profiles remain editable in:

config/io-profiles.json

Notable appliance profiles:

• headless-shared-1080p60 — hidden preview, NDI + Syphon/Spout
• headless-capture-1080p30 — hidden preview, NDI + H.264 recording
• broadcast-1080p30 — preview, NDI, Syphon/Spout, and recording
• archive-4k30 — demanding 4K ProRes + NDI + platform share route

Recommended validation

1. Run npm run dev.
2. Confirm appliance-status.json updates every second.
3. Change heartbeatMs to 500, apply the appliance config, and confirm faster updates.
4. Set previewPolicy to hidden, apply, and confirm offscreen frame counts continue.
5. Set controlsVisible to false, apply, and confirm the controls window hides.
6. Run npm run dev:appliance and verify NDI plus Syphon/Spout externally.
7. Run npm run dev:capture, allow a short recording, stop with the UI in normal mode or use a timed run, and verify file finalization.
8. Set exitAfterSeconds to a short value and verify clean automatic shutdown.

Known limitations

• This is an offscreen/hidden-window runtime, not a platform-specific display-server-free GPU context. A native surface is still created and then hidden.
• NDI development builds require the NDI SDK and runtime.
• Spout remains pending full Windows validation.
• Syphon/Spout resolutions above 1080p can become bandwidth-limited because the current route stages frames through CPU memory.
• Network output is intentionally excluded until its separate implementation is resolved.

This site is open source. Improve this page.