junkpile

31 — wgpu I/O Profile Router

A native wgpu + Tauri 2 teaching example for describing render and file-output routes as validated, hot-reloadable JSON profiles.

This example is built from two confirmed working Junkpile foundations:

• Example 26: typed I/O configuration, validation, hot reload, and last-known-good behavior
• Examples 28 and 30: bounded FFmpeg file recording and native high-resolution rendering

It does not reuse the paused network-streaming implementation from Example 29.

What this example demonstrates

• Named I/O profiles stored in config/io-profiles.json
• Strict typed JSON with unknown-field rejection
• Unique profile IDs and validated default profile
• Last-known-good behavior after invalid edits
• Debounced filesystem hot reload
• Explicit profile arming before route changes
• Native source reconfiguration when a profile is armed
• GPU preview route that remains active
• Optional bounded FFmpeg file route
• H.264/MP4 and ProRes/MOV profiles
• 1080p, 4K, 5K, and 8K profiles
• GPU texture-limit validation
• Profile changes blocked while recording or finalizing
• FFmpeg and ffprobe verification inherited from the stable recorder

Architecture

config/io-profiles.json
        ↓ parse + validate
last-known-good profile registry
        ↓ arm one profile
native authoritative wgpu texture
        ├── GPU window preview
        └── optional mapped readback
                ↓ bounded queue
             FFmpeg file worker
                ↓
             MP4 or MOV

The control panel never sends arbitrary dimensions or codec settings to the renderer. It selects a profile ID. Rust resolves that ID against the validated profile registry and uses the stored settings.

Profile schema

{
  "id": "delivery-4k",
  "label": "Delivery · 4K H.264",
  "description": "Native 4K render and H.264 recording.",
  "frame": {
    "width": 3840,
    "height": 2160
  },
  "recording": {
    "enabled": true,
    "codec": "h264",
    "fps": 30,
    "workerDelayMs": 0
  }
}

Supported codecs:

h264
prores

Supported recording frame rates:

24
30
60

The renderer itself continues running at 60 Hz. The recording route captures at the profile’s configured output frame rate.

Built-in profiles

• Preview only · 1080p
• Delivery · 1080p H.264
• Delivery · 4K H.264
• Archive · 4K ProRes
• Stress test · 5K H.264
• Stress test · 8K H.264 at 24 FPS

Prerequisites

• Rust
• Node.js and npm
• Tauri 2 system prerequisites
• FFmpeg and ffprobe on PATH

Verify the tools before starting:

ffmpeg -version
ffprobe -version

Optional executable overrides:

export FFMPEG_PATH=/absolute/path/to/ffmpeg
export FFPROBE_PATH=/absolute/path/to/ffprobe

Run

cd 31-wgpu-io-profile-router
npm install
npm run dev

Two windows should open:

1. HTML/CSS profile and telemetry controls
2. Native wgpu renderer preview

Test sequence

1. Preview-only route

The default profile is Preview only · 1080p.

Confirm:

• The route graph shows preview only
• The file-route button is disabled
• The native preview continues rendering

2. Arm and record 1080p

1. Select Delivery · 1080p H.264
2. Click Arm selected profile
3. Confirm the armed badge and route graph update
4. Click Start file route
5. Record for about five seconds
6. Click Stop and finalize
7. Wait for Complete
8. Play the verified MP4

3. Change profiles

Arm Delivery · 4K H.264 or Archive · 4K ProRes while idle.

The native authoritative texture and recording stage should reconfigure immediately. Profile changes are rejected while a recording is active or finalizing.

4. Verify hot reload

Open the config folder from the controls and edit:

config/io-profiles.json

Change a label or add a valid profile. Save the file. The generation and profile list should update without restarting.

Then deliberately make the JSON invalid. The UI should show the validation error while the previously valid profile registry remains usable.

Use Restore built-ins to recover the original file.

Output location

Recordings are written to:

./recordings/

Example filenames:

junkpile-31-h264-1920x1080-30fps-<timestamp>.mp4
junkpile-31-prores-3840x2160-30fps-<timestamp>.mov

Validation rules

• schemaVersion must be 1
• Profile IDs must be unique
• defaultProfile must reference an existing profile
• Dimensions must be even
• Maximum profile dimensions are 7680 × 4320
• Recording FPS must be 24, 30, or 60
• 8K is limited to 24 or 30 FPS
• Worker delay must be between 0 and 500 ms
• Unknown JSON fields are rejected
• The selected dimensions must fit the GPU’s reported texture limit

Why this matters

A reusable I/O system should not require every application to hardcode its delivery settings. A small processor, recorder, feedback instrument, or routing utility should be able to load a known profile and expose the same predictable route contract.

This example proves a focused version of that model:

Configuration chooses the route, Rust validates it, the renderer prepares it, and each sink remains responsible for its own lifecycle and backpressure.

Future examples can extend the same profile format with NDI and platform-native shared-texture outputs after those individual sinks are independently verified.

This site is open source. Improve this page.