Caveats & Known Limitations

■ DOCUMENTATION

□

CPU Pixel Readback for Syphon and Spout

Both Syphon and Spout routes use getImageData() to read the canvas pixels back from the GPU to CPU inside the WebView, ship them over the loopback WebSocket, then re-upload to a Metal or D3D11 texture in Rust. This is a full GPU → CPU → GPU round-trip per frame.

Why zero-copy isn't implemented: The WebView (WKWebView on macOS, WebView2 on Windows) does not expose its render surface as a native texture handle. This is a Tauri/browser architecture constraint, not a fixable bug. At 720p/30fps the readback costs roughly 3–6ms per frame — well within budget. Do not set the FPS cap higher than your canvas draw rate. For 4K output use OBS window capture.

Frame Ring Memory at High Resolution

Resolution	Bytes/frame	Max frames (quality=1)
720p (1280×720)	~3.7 MB	51 frames
1080p (1920×1080)	~8.3 MB	23 frames
1440p (2560×1440)	~14.7 MB	13 frames
4K (3840×2160)	~33.2 MB	5 frames

At 4K the datamosh effect loses most of its temporal depth. 720p or 1080p is the practical sweet spot.

Syphon is macOS-Only. Spout is Windows-Only.

No cross-platform texture sharing equivalent exists. Options for cross-platform output:

OBS window capture → NDI (via OBS-NDI plugin) for network distribution
OBS window capture → stream/record directly
Canvas mirror window opened in any browser on the local network

Camera Permissions Require Codesigning (macOS)

In distribution builds on macOS, the app must be codesigned with the NSCameraUsageDescription entitlement for the camera permission dialog to appear. Without codesigning, getUserMedia() will fail silently on macOS 12+.

Port 8787 Must Be Free

huff binds the WS relay on 127.0.0.1:8787 at startup. If another application is using this port, the canvas window shows "WS: disconnected" and never receives frames.

# macOS / Linux — find what is using the port lsof -i :8787 # Windows netstat -ano | findstr :8787

To change the port: edit const PORT: u16 = 8787; in src-tauri/src/main.rs and __getWSURL__ in src/index.html, then rebuild.

No Multi-Instance Support

Running two huff instances simultaneously causes a port conflict on 8787. Build two copies from source with different PORT values if you need parallel instances.

MIDI/OSC Maps Stored in localStorage

Best practice: Always save your maps as JSON files alongside your project. Treat localStorage as a cache, not a primary store. Maps are lost if you clear WebView data or reinstall.

Linux is Untested

The Tauri scaffolding supports Linux and build prerequisites are documented in Installation. No binary has been tested against a Linux runtime in this release. Syphon and Spout do not exist on Linux. The canvas mirror window and MIDI/OSC will work if the build succeeds.

Feedback Instability at High Values

FEEDBACK above ~2.5 combined with non-neutral FB Z can cause the buffer to saturate (full white or full black) within seconds. This is natural behaviour for a positive-feedback system. Recovery: lower FEEDBACK to 0 or click ↺ Reset in the Feedback group. The buffer clears over the next few frames.

Cluster Physics State Not Saved in Presets

Cluster centre positions and velocities are runtime JavaScript state and are not serialised into preset files. Loading a preset restores all slider values but cluster centres will be at whatever position they were at load time.