junkpile

Junkpile 26 — wgpu I/O Config Foundation

A standalone Tauri 2 + native wgpu example that establishes the configuration layer for future Junkpile recording, streaming, NDI, Syphon, Spout, receiver, and routing examples.

This project does not implement those media sinks yet. It establishes the contract they will consume.

io.json
   + platform override
            ↓ deep merge
strict typed Rust schema
            ↓ validation
last-known-good active state
            ↓ bounded renderer command
native wgpu diagnostic surface

What this example demonstrates

• Versioned JSON schema
• Strict rejection of unknown fields
• macOS, Windows, and Linux override files
• Deep merge of base and platform configuration
• Independent render, preview, recording, and streaming dimensions
• Independent render, recording, and streaming frame rates
• Queue-capacity configuration for future CPU-frame workers
• NDI and shared-texture configuration placeholders
• Platform validation for Syphon and Spout selections
• Filesystem hot reload using the actual resolved files
• Debounced watcher events
• Last-known-good behavior after invalid edits
• Manual reload
• Built-in restore operation
• Native renderer telemetry
• A renderer visualization that changes when the active generation changes

Run

npm install
npm run dev

The project follows the established Junkpile two-window native-wgpu architecture:

• controls: HTML/CSS/JavaScript WebView
• renderer: separate native OS window rendered by wgpu

First test

1. Launch the example.
2. Confirm both windows open.
3. Confirm the controls report configuration active.
4. Click Write valid change.
5. Recording and streaming should toggle, render target FPS should change, and the generation should increment.
6. Click Write invalid change.
7. The controls should report a rejected configuration.
8. The previous generation should remain active and the renderer should continue.
9. Click Restore defaults.
10. The watcher should apply the restored files automatically.

Manual editing

Click Open config folder, then edit:

config/io.json
config/io.macos.json
config/io.windows.json
config/io.linux.json

During development, the project-local config/ directory is used. A production bundle uses the operating system application-config directory and seeds the same defaults on first launch.

The active platform override is merged after io.json.

Configuration model

Authoritative render

"render": {
  "width": 1920,
  "height": 1080,
  "targetFps": 60
}

This describes the frame produced by the renderer or processing graph.

Preview

"preview": {
  "enabled": true,
  "width": 1280,
  "height": 720,
  "scaling": "fit"
}

Valid scaling values:

• fit
• fill
• stretch
• pixel

Recording and streaming

Each worker output has its own dimensions, FPS, and bounded queue capacity:

"recording": {
  "enabled": false,
  "width": 1920,
  "height": 1080,
  "fps": 60,
  "queueCapacity": 3
}

The configuration deliberately prevents recording or streaming resolution from silently resizing the authoritative render target.

Shared texture

Valid backends:

• auto
• syphon
• spout
• disabled

The platform override resolves the default backend:

• macOS → Syphon
• Windows → Spout
• Linux → disabled

No sender is created in this example. The field is validated and visualized only.

Validation rules

• schemaVersion must be 1
• Dimensions must be between 64 and 8192
• A configured frame may not exceed 67.1 megapixels
• FPS must be between 1 and 240
• Queue capacity must be between 1 and 16
• Hot-reload debounce must be between 50 and 5000 milliseconds
• Unknown JSON fields are rejected
• Syphon is rejected outside macOS
• Spout is rejected outside Windows
• Enabled shared texture cannot use the disabled backend

Last-known-good behavior

A failed reload updates the error telemetry but does not replace the active configuration. The renderer keeps the previous valid generation.

This behavior is essential for live systems: a malformed edit should not collapse the running application.

Important files

config/io.json                         base configuration
config/io.macos.json                   macOS override
config/io.windows.json                 Windows override
config/io.linux.json                   Linux override
src-tauri/src/config.rs                schema, merge, validation, watcher
src-tauri/src/renderer.rs              native wgpu renderer and config command
src-tauri/src/shader.wgsl              diagnostic output visualization
src-tauri/src/main.rs                  Tauri commands and window lifecycle
src/index.html                         controls and effective-state view
src/app.js                             polling and test actions
src/styles.css                         controls presentation

Why this comes before FFmpeg

The later recording and streaming examples need stable answers to these questions first:

• Which dimensions belong to the renderer?
• Which dimensions belong to each sink?
• Which frame rate belongs to each sink?
• How large may a worker queue become?
• What happens when configuration is malformed?
• Which platform-specific capability is selected?
• Can configuration change while the renderer stays alive?

This example answers those questions without mixing them with codecs, subprocesses, GPU readback, or network behavior.

Validation status

The project structure, JSON files, frontend JavaScript, and generated archive were statically checked in the creation environment. Rust compilation and runtime testing must be performed on a machine with Rust, Cargo, Tauri prerequisites, and a supported GPU; Cargo was not available in the creation environment.

License

MIT.

This site is open source. Improve this page.