Caveats & Known Limitations

■ DOCUMENTATION

□

CPU Pixel Readback for Syphon and Spout

Syphon and Spout still require getImageData() to make WebView pixels CPU-readable before Rust uploads them into Metal or D3D11. This remains a full GPU → CPU → GPU architecture. Pass 51 retains the Worker-owned local WebSocket and adds a strict two-credit pipeline so browser readback for a following 720p frame can overlap native publication without creating an unbounded latency queue.

Why zero-copy isn't implemented: The WebView does not expose its rendered Canvas2D surface as a native shareable texture handle. Pass 51 improves overlap rather than removing readback. HUFF Classic Syphon is therefore fixed at 1280×720: 60 fps is the optimized worker-direct target and 30 fps is the safe fallback.

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.