Processing Server - Multi-User Web Controller

A multi-user web-based controller for Processing.org visual sketches. Multiple users can connect via web browsers, interact with UI controls (touch areas, sliders, buttons), stream audio, and use phone motion sensors, all aggregated in real-time on a server-side Processing canvas.

Table of Contents

• Features
• Prerequisites
• Getting Started
• Project Structure
• Configuration
• Browser UI
• API Endpoints
• Troubleshooting
• Development
• Architecture
• Customization
• Next Steps
• Technology Stack
• Acknowledgments

Features

• Multi-user support: Multiple concurrent browser clients
• Real-time WebSocket communication: Low-latency bidirectional messaging
• Stronger session lifecycle handling: Session names, heartbeat updates, explicit browser close, and stale-session reaping
• Touch/mouse input: Position tracking with visual feedback
• Keyboard input: Desktop browser key events over the same WebSocket channel
• Audio streaming: Per-user audio buffering, visual level response, and optional dominant-frequency mapping in sample sketches
• Phone motion input: Tilt and shake from supported mobile browsers over HTTPS
• Selectable sketch classes: Launch alternate sketches with processing.sketch-class
• Local operator controls: Processing-window selection, drag, wheel adjustment, HUD, and pause/slow controls layered on top of browser input
• Gravity-orbit sketch samples: Physics-based sketch variants, including a gradient-background version
• HTTPS/TLS: Secure connections required for mobile microphone access
• Cross-device: Works on desktop and mobile browsers

Prerequisites

Contents:

• Required Software
• Environment Setup
• Verify Prerequisites

Required Software

Software	Version	Download
Java JDK	21 minimum, 25+ recommended	Adoptium or Oracle
Maven	3.9+	Apache Maven
Git	Latest	Git SCM

Environment Setup

Windows (PowerShell):

$env:JAVA_HOME = "C:\Program Files\Java\jdk-25"  # or jdk-21 minimum

Mac/Linux (Bash):

export JAVA_HOME=/usr/lib/jvm/jdk-25  # or jdk-21 minimum  # or wherever JDK is installed
# Add to ~/.bashrc or ~/.zshrc for persistence

Verify Prerequisites

Windows (PowerShell):

java -version
mvn -version
echo $env:JAVA_HOME

Mac/Linux (Bash):

java -version
mvn -version
echo $JAVA_HOME

Getting Started

Contents:

• 1. Clone the Repository
• 2. Try It Locally Over HTTP
• 3. Enable HTTPS for LAN or Mobile Browsers
• 4. Build the Project
• 5. Run the Server
• 6. Access the Application

1. Clone the Repository

Windows (PowerShell):

cd C:\Users\yourname\Dev
git clone <repository-url> processing-server
cd processing-server

Mac/Linux (Bash):

cd ~/Dev
git clone <repository-url> processing-server
cd processing-server

2. Try It Locally Over HTTP

No certificate is required for local testing on this machine.

Windows (PowerShell):

.\run.ps1

Mac/Linux (Bash):

./run.sh

Open http://localhost:8080.

3. Enable HTTPS for LAN or Mobile Browsers

HTTPS is only needed when you want to connect from another device on your LAN, especially for browser microphone access.

Windows (PowerShell):

# Auto-detect your local IP and write keystore.p12 to the project root
.\create-keystore.ps1

# Or specify your IP manually
.\create-keystore.ps1 192.168.1.100

# Use -Force to overwrite an existing keystore
.\create-keystore.ps1 -Force

Mac/Linux (Bash):

chmod +x create-keystore.sh

# Auto-detect your local IP and write keystore.p12 to the project root
./create-keystore.sh

# Or specify your IP manually
./create-keystore.sh 192.168.1.100

# Use --force to overwrite an existing keystore
./create-keystore.sh --force

What the script does:

1. Writes keystore.p12 to the project root.
2. Exports the CA certificate as processing-server-ca.cer.
3. Adds SAN entries for localhost, 127.0.0.1, your current LAN IP, and hostname.local.
4. Leaves local HTTP unchanged and enables HTTPS only when you launch with the HTTPS config overlay.

To turn HTTPS on:

1. Run one of the keystore scripts.
2. Trust processing-server-ca.cer on the devices that will use the HTTPS URL.
3. Start the server with .\run-https.ps1 or ./run-https.sh.
4. Open https://<hostname>.local:8443/ or https://<LAN-IP>:8443/.

4. Build the Project

Windows (PowerShell):

$env:JAVA_HOME = "C:\Program Files\Java\jdk-25"  # or jdk-21 minimum
mvn clean package -DskipTests

Mac/Linux (Bash):

export JAVA_HOME=/usr/lib/jvm/jdk-25  # or jdk-21 minimum  # adjust as needed
mvn clean package -DskipTests

Packaging note:

• This project intentionally builds an executable shaded jar so it can be launched with java -jar target/processing-server-<version>.jar
• That differs from the stock Helidon example layout in processing-client, which follows the thinner target/libs runtime pattern
• The tradeoff is a larger packaged jar and more shading warnings during build in exchange for a simpler launch experience for users
• For this application, that tradeoff is intentional because the app is used more like a runnable desktop/server tool than a minimal framework example

5. Run the Server

Option A: Using shell script

Windows (PowerShell):

.\run.ps1

With extra Java properties:

.\run.ps1 -Properties "-Dprocessing.sketch-class=com.processing.server.GravityOrbitSketch"

Notes:

• the run scripts accept a plain properties argument and insert it before -jar
• the run scripts now auto-build with mvn -q -DskipTests package when sources are newer than the packaged jar
• because of that auto-build step, mvn must be available on PATH

Mac/Linux (Bash):

./run.sh

With extra Java properties:

./run.sh "-Dprocessing.sketch-class=com.processing.server.GravityOrbitSketch"

Option A2: Using shell script with HTTPS

Windows (PowerShell):

.\run-https.ps1

With extra Java properties:

.\run-https.ps1 -Properties "-Dprocessing.sketch-class=com.processing.server.GravityOrbitGradientSketch"

Mac/Linux (Bash):

./run-https.sh

With extra Java properties:

./run-https.sh "-Dprocessing.sketch-class=com.processing.server.GravityOrbitGradientSketch"

Option B: Using Maven

Windows (PowerShell):

$env:JAVA_HOME = "C:\Program Files\Java\jdk-25"  # or jdk-21 minimum
mvn package -DskipTests
java -jar .\target\processing-server-1.0-SNAPSHOT.jar

Mac/Linux (Bash):

export JAVA_HOME=/usr/lib/jvm/jdk-25  # or jdk-21 minimum
mvn package -DskipTests
java -jar ./target/processing-server-1.0-SNAPSHOT.jar

Option C: Using Java directly

Windows (PowerShell):

$env:JAVA_HOME = "C:\Program Files\Java\jdk-25"  # or jdk-21 minimum
java -jar .\target\processing-server-1.0-SNAPSHOT.jar

Mac/Linux (Bash):

export JAVA_HOME=/usr/lib/jvm/jdk-25  # or jdk-21 minimum
java -jar ./target/processing-server-1.0-SNAPSHOT.jar

6. Access the Application

Access Point	URL
Local UI	http://localhost:8080/
Local API	http://localhost:8080/api/status
LAN/Mobile UI	https://YOUR_HOSTNAME.local:8443/ or https://YOUR_IP:8443/
WebSocket	ws://localhost:8080/ws locally, wss://YOUR_IP:8443/ws over HTTPS

First-time local access:

1. Open http://localhost:8080/
2. No certificate is required for same-machine testing

Mobile device access:

1. Generate the keystore and trust processing-server-ca.cer
2. Start the server with .\run-https.ps1 or ./run-https.sh
3. On mobile, navigate to https://YOUR_IP:8443/ or https://YOUR_HOSTNAME.local:8443/
4. Accept the certificate warning if the CA is not yet trusted

Project Structure

The keystore lives at the project root, and HTTPS is enabled through config/application-https.yaml plus -Dapp.config=... at launch time.

processing-server/
|-- pom.xml                           # Maven configuration
|-- README.md                         # This file
|-- ARCHITECTURE.md                   # Detailed architecture documentation
|-- CUSTOMIZATION.md                  # Guide for modifying and extending
|-- TODO.md                           # Follow-up tasks and ideas
|-- GRAVITY_ORBIT_SKETCH_TUTORIAL.md  # Walkthrough of the gravity-orbit sample sketches
|-- run.ps1                           # PowerShell run script
|-- run.sh                            # Bash run script
|-- run-https.ps1                     # PowerShell HTTPS launch script
|-- run-https.sh                      # Bash HTTPS launch script
|-- create-keystore.ps1               # PowerShell keystore generator
|-- create-keystore.sh                # Bash keystore generator
|-- keystore.p12                      # Generated TLS keystore
|-- processing-server-ca.cer          # Exported CA certificate
|-- config/
|   `-- application-https.yaml        # HTTPS overlay config for -Dapp.config
|-- generated-src/
|   `-- main/java/com/processing/server/
|       `-- ...                       # Reviewed generated sketches kept separate from handwritten server code
|-- src/
|   `-- main/
|       |-- java/com/processing/server/
|       |   |-- Main.java             # Entry point and socket configuration
|       |   |-- ProcessingSketch.java # Processing canvas behavior
|       |   |-- GravityOrbitSketch.java # Alternate orbiting multi-user sketch
|       |   |-- GravityOrbitGradientSketch.java # Orbit sketch with attraction-based background field
|       |   |-- LocalOperatorLayer.java # Shared Processing-window operator controls for selectable sketches
|       |   |-- StarterSketch.java    # Minimal alternate sketch example
|       |   |-- WebSocketHandler.java # WebSocket session and message handling
|       |   |-- InputService.java     # REST API endpoints
|       |   |-- SessionManager.java   # User session tracking
|       |   |-- EventQueue.java       # Thread-safe event queue
|       |   |-- AudioBuffer.java      # Per-session audio buffering
|       |   |-- AudioConfig.java      # Audio configuration
|       |   |-- DebugConfig.java      # Debug logging settings
|       |   `-- UserInputEvent.java   # Event data structure
|       `-- resources/
|           |-- application.yaml      # Default local HTTP configuration
|           `-- static/
|               `-- index.html        # Browser UI
`-- target/                           # Build output created after the first Maven build

target/ is created by Maven after the first build. It is not part of the files cloned from GitHub.

Generated-sketch workflow:

• raw converter output belongs under target/pde-output/...
• reviewed generated sketches that you want to compile with the app can live under generated-src/main/java/...
• Maven compiles generated-src/main/java in addition to src/main/java

Configuration

Contents:

• application.yaml
• Motion Configuration
• Changing the Port
• Changing Audio Quality

application.yaml

server:
  port: 8080                        # HTTP port
  host: "127.0.0.1"                 # Local-only HTTP listener

processing:
  sketch-class: "com.processing.server.ProcessingSketch"  # Sketch class to launch
  width: 800                        # Canvas width
  height: 600                       # Canvas height
  fps: 60                           # Target frame rate

audio:
  mode: "high-quality-mono"         # Audio mode
  debug:
    logging: false                  # Enable audio-analysis debug output
    sample-limit: 5                 # Max audio debug samples to print
  modes:
    high-quality-stereo:
      sample-rate: 44100
      channels: 2
      description: "44.1kHz Stereo"
    high-quality-mono:
      sample-rate: 44100
      channels: 1
      description: "44.1kHz Mono"
    voice:
      sample-rate: 22050
      channels: 1
      description: "22.05kHz Mono"
  buffer-size: 2048
  max-buffer-chunks: 20

debug:
  logging: false                    # Enable debug output

processing.sketch-class lets you run a different sketch class without editing Main.java. The class must:

• extend PApplet
• provide the same constructor shape as ProcessingSketch
• provide a public runSketch() method

Example:

java "-Dprocessing.sketch-class=com.processing.server.StarterSketch" -jar .\target\processing-server-1.0-SNAPSHOT.jar

Using the helper script:

.\run.ps1 -Properties "-Dprocessing.sketch-class=com.processing.server.GravityOrbitSketch"

Gradient variant:

.\run.ps1 -Properties "-Dprocessing.sketch-class=com.processing.server.GravityOrbitGradientSketch"

StarterSketch is included as a minimal alternate sketch. It proves that the config switch works and reacts to browser touch, size-slider, and keyboard input.

Additional sample sketches included in src/main/java/com/processing/server/:

• GravityOrbitSketch: orbiting multi-user circles with touch anchors, shake repulsion, and motion-modified attraction
• GravityOrbitGradientSketch: the same sketch plus a soft attraction-based background gradient

The default ProcessingSketch and the gravity sketches also share a local Processing-window operator layer. That local layer is separate from browser controls and currently supports:

• click to select a circle
• drag to move the selected user target
• Shift + mouse wheel to adjust selected user size
• Ctrl + mouse wheel to adjust selected user gain
• D toggle the local HUD
• N toggle on-canvas names
• P pause local sketch physics/easing updates
• S slow motion
• R scatter all circles
• C re-center all circles

In the gravity sketches, the same layer also drives optional local overlays for velocity vectors and attraction lines.

See GRAVITY_ORBIT_SKETCH_TUTORIAL.md for a walkthrough of how those sketches were built by starting from ProcessingSketch and modifying key methods.

For reviewed converted sketches, keep the generated Java separate from the main server source tree:

• raw converter output: target/pde-output/<sketch-name>/
• launchable reviewed sketch classes: generated-src/main/java/com/processing/server/

Motion Configuration

Phone motion input is configured in src/main/resources/application.yaml:

motion:
  update-hz: 20
  clamp:
    alpha-degrees: 180
    beta-degrees: 60
    gamma-degrees: 60
    acceleration-g: 3.0
    magnitude-g: 4.0
  mapping:
    tilt-offset-normalized: 0.12
    shake-threshold-g: 0.6
    shake-burst-scale: 1.8
  debug:
    logging: false
    sample-limit: 5

Adjustable motion settings:

• motion.update-hz: browser send rate for combined motion samples
• motion.clamp.beta-degrees and motion.clamp.gamma-degrees: max tilt accepted by the server
• motion.clamp.acceleration-g: max absolute acceleration retained per axis
• motion.clamp.magnitude-g: max retained acceleration magnitude
• motion.mapping.tilt-offset-normalized: how far tilt can offset the rendered position around the touch target
• motion.mapping.shake-threshold-g: minimum shake signal before a burst is triggered
• motion.mapping.shake-burst-scale: scales the shake-driven burst intensity
• motion.debug.logging: enables a few motion debug samples in the server/sketch

Important:

• this file is packaged into the jar
• changing these values requires a rebuild with mvn clean package -DskipTests

Changing the Port

Edit application.yaml or pass system property:

Windows (PowerShell):

java -Dserver.port=9090 -jar .\target\processing-server-1.0-SNAPSHOT.jar

Mac/Linux (Bash):

java -Dserver.port=9090 -jar ./target/processing-server-1.0-SNAPSHOT.jar

Changing Audio Quality

Edit application.yaml:

audio:
  mode: "voice"  # Options: high-quality-stereo, high-quality-mono, voice

Audio Debug Logging

Audio-analysis debug logging is configured separately from general debug logging:

audio:
  debug:
    logging: true
    sample-limit: 12

Or via system property:

.\run.ps1 -Properties "-Daudio.debug.logging=true -Daudio.debug.sample-limit=12 -Dprocessing.sketch-class=com.processing.server.GravityOrbitGradientSketch"

With audio.debug.logging enabled, the gravity sketches emit audio debug lines only when the analyzed level is above the current detection threshold, so quiet buffers that merely retain the last frequency do not spam the log.

Browser UI

Contents:

• Enabling Debug Mode

The web interface (index.html) provides:

1. Touch Area: Drag to move your circle on the canvas
2. Size Slider: Adjust the core circle size while keeping the outer audio ring proportional
3. Speed Slider: Adjust movement responsiveness and the decay speed of temporary effects
4. Action Buttons: Burst, Spin Color, and Scatter trigger visual effects
5. Audio Input: Start or stop microphone audio (HTTPS is required for mobile and remote browsers)
6. Audio Gain Slider: Attenuate or amplify how strongly incoming audio drives the sketch
7. Motion Input: Enable phone motion sensors, view live tilt values, and send tilt/shake control over HTTPS
8. Motion Trim Slider: Adjust motion sensitivity in the browser before motion samples are sent to the server
9. Keyboard Input: Desktop browsers can send key events while the page has focus, and phones/tablets can open a compact on-screen keyboard with Tap for simple keyboard input
10. Session Name: A browser client can save a short display name for its session, and the sketch will use that name as the on-canvas label when available
11. Session Lifecycle: The browser sends heartbeats while connected and sends a best-effort close notification when the page is leaving, which helps remove stale circles more reliably

Separately from the browser UI, the Processing window now also has a local operator layer for the person sitting at the machine. Those controls do not travel over the WebSocket and do not replace browser-side session input.

The touch area uses touch-action: none, which helps avoid accidental browser text selection or gesture interference while dragging.

The motion trim is a client-only setting. It scales the browser's outgoing motion sample before transmission, so different devices can feel less or more responsive without changing the shared server config.

Keyboard notes:

• keyboard input depends on page focus
• on phones and tablets, use Tap for simple keyboard input to focus the compact keyboard field and open the on-screen keyboard
• the default sketch uses arrows or WASD to nudge the circle and space to trigger a burst
• the browser UI also exposes the last key seen so you can confirm the protocol is active
• if a custom sketch also keeps local Processing keyPressed() logic, that local keyboard path only works when the Processing window has focus
• mobile soft keyboards are best for simple character input; important mobile controls should still prefer buttons, sliders, and touch

Processing-window local operator notes:

• these controls are separate from browser key events in EventQueue
• local controls only work when the Processing window has focus
• click selects the nearest visible circle
• drag moves that selected user's local target position
• Shift + mouse wheel changes selected size
• Ctrl + mouse wheel changes selected gain
• D, N, P, S, R, and C are reserved for local operator actions
• the gravity sketches also support V for velocity vectors and L for attraction lines
• the local HUD shows selected-user details; freq=n/a in the default sketch and live dominant frequency in the gravity sketches

Enabling Debug Mode

Add ?debug to the URL:

http://localhost:8080/?debug

This enables console logging in the browser.

API Endpoints

Contents:

• REST Endpoints
• WebSocket Endpoint

REST Endpoints

Method	Endpoint	Description
POST	/api/session	Create new session (returns JSON with sessionId)
GET	/api/status	Get status (session count, queue size, and session metadata such as saved names and lastSeenAt)
POST	/api/event	Submit event (requires sessionId in body)

WebSocket Endpoint

Connect to ws://localhost:8080/ws for local HTTP, or wss://localhost:8443/ws when launched with -Dapp.config=config/application-https.yaml.

Server -> Client Messages:

{
  "type": "session",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Ava"
}

{
  "type": "session-meta-ack",
  "name": "Ava"
}

{
  "type": "server-shutdown",
  "reason": "Processing Server is shutting down."
}

Client -> Server Messages:

{
  "type": "touch",
  "controlId": "touchArea",
  "x": 0.5,
  "y": 0.3,
  "timestamp": 1234567890
}

{
  "type": "slider",
  "controlId": "sizeSlider",
  "value": 0.75,
  "timestamp": 1234567890
}

{
  "type": "motion",
  "controlId": "deviceMotion",
  "alpha": 12.0,
  "beta": -8.5,
  "gamma": 24.0,
  "ax": 0.1,
  "ay": 0.4,
  "az": 1.0,
  "magnitude": 1.08,
  "timestamp": 1234567890
}

{
  "type": "key",
  "controlId": "keyboard",
  "key": "ArrowLeft",
  "keyCode": 37,
  "action": "pressed",
  "timestamp": 1234567890
}

{
  "type": "session-meta",
  "name": "Ava"
}

{
  "type": "heartbeat",
  "timestamp": 1234567890
}

{
  "type": "session-close",
  "timestamp": 1234567890
}

Audio is sent as binary WebSocket frames (not JSON).

Troubleshooting

Contents:

• "Port already in use"
• "SSL handshake failure" / "Can't connect"
• "Session ID: connecting..." or controls do nothing
• "The browser says the server disconnected"
• "Microphone not working on mobile"
• "Motion works, but shake is weak or invisible"
• "Audio not streaming"
• "Users initialize on same position"
• "Java version errors"
• "Maven not found"
• "IP address changed / certificate invalid"

"Port already in use"

Another process is using port 8080. Either:

• Stop the conflicting process
• Change the port in application.yaml

Windows (PowerShell):

netstat -ano | findstr :8080

Mac/Linux (Bash):

lsof -i :8080
# or
netstat -tulpn | grep 8080

"SSL handshake failure" / "Can't connect"

Ensure:

1. keystore.p12 exists in the project root
2. The server was started with .\run-https.ps1, ./run-https.sh, or -Dapp.config=config/application-https.yaml
3. Keystore has proper structure (CA + signed server cert)
4. Server started successfully (check console output)

Verify TLS is working:

# Local HTTP
curl http://localhost:8080/api/status

# Optional HTTPS socket when started with the HTTPS config overlay
curl -k https://localhost:8443/api/status

# Local HTTP
curl http://localhost:8080/api/status

# Optional HTTPS socket
curl -k https://localhost:8443/api/status

# View certificate details
openssl s_client -connect localhost:8443 -showcerts

Expected output: JSON with activeSessions, queueSize, etc.

If curl fails with SSL error, the keystore is malformed. Regenerate with create-keystore.ps1.

"Session ID: connecting..." or controls do nothing

• Confirm the page is using the matching WebSocket URL for its current scheme
• Use ws://localhost:8080/ws for local HTTP or wss://<host>:8443/ws for HTTPS
• Check http://localhost:8080/api/status or https://localhost:8443/api/status
• If the page is open and connected, activeSessions should be greater than 0

"The browser says the server disconnected"

• On a clean shutdown, the server sends a final server-shutdown WebSocket message before closing connections
• The browser shows a banner and scrolls back to the top so the notice is visible
• On an unexpected disconnect, the browser also shows a banner and attempts to reconnect
• If a browser disappears abruptly, the server now reaps stale sessions after a timeout, so sketch-side user state should eventually be removed even when a clean close is missed

"Microphone not working on mobile"

• Must use HTTPS (not HTTP)
• Local http://localhost:8080 works on the same machine but not for mobile microphone access
• Must accept certificate warning
• Browser requires user gesture before microphone access

"Motion works, but shake is weak or invisible"

• Motion tuning in src/main/resources/application.yaml requires a rebuild
• Restart after mvn clean package -DskipTests
• Try lowering motion.mapping.shake-threshold-g
• Try raising motion.mapping.shake-burst-scale
• Enable motion.debug.logging: true to inspect sample values

The current shake effect is driven by:

• acceleration magnitude change
• axis-to-axis acceleration change

So short sharp shakes should produce a stronger burst than slow movement.

"Audio not streaming"

• Check browser console for errors
• Verify HTTPS is active
• Try manual audio start: click "Start Audio" button
• Check debug output: http://localhost:8080/?debug

"Users initialize on same position"

Users are placed at random non-overlapping positions. If many users connect simultaneously, some overlap may occur. Refresh the browser page to reinitialize.

"Java version errors"

Ensure Java 21+ is installed and JAVA_HOME is set (Java 25+ recommended for best performance):

Windows (PowerShell):

$env:JAVA_HOME = "C:\Program Files\Java\jdk-25"  # or jdk-21 minimum
java -version

Mac/Linux (Bash):

export JAVA_HOME=/usr/lib/jvm/jdk-25  # or jdk-21 minimum
java -version

No preview flags required for Java 21+.

"Maven not found"

Install Maven or use the full path:

Windows (PowerShell):

# If installed via Chocolatey
C:\ProgramData\chocolatey\lib\maven\apache-maven-3.9.14\bin\mvn

# Or add to PATH
$env:PATH += ";C:\ProgramData\chocolatey\lib\maven\apache-maven-3.9.14\bin"

Mac/Linux (Bash):

# If installed via Homebrew (Mac)
/opt/homebrew/bin/mvn

# Or add to PATH
export PATH=$PATH:/opt/homebrew/bin

"IP address changed / certificate invalid"

The keystore certificate includes your local IP address in the Subject Alternative Name (SAN) extension. If your laptop connects to a different network, your IP will likely change, causing certificate validation errors in browsers.

Current behavior: You must regenerate the keystore when your IP changes.

Workarounds (choose one):

1. Regenerate keystore (current approach):

   .\create-keystore.ps1  # auto-detects new IP
   .\run-https.ps1

2. Use hostname instead of IP:

   The keystore scripts already include HOSTNAME.local in the SAN list.

   Then connect via: https://YOURHOSTNAME.local:8443/

   Works on most networks with mDNS/Bonjour (Windows 10+, macOS, Linux with avahi).

3. Accept browser warnings (not recommended for classrooms):

   Proceed past the security warning. The connection still encrypts, but users see a scary warning.

4. Use a real domain with Let's Encrypt (production):

   Requires a registered domain and DNS pointing to your server.

Development

Contents:

• Building Without Running Tests
• Running Tests
• Debug Logging

Building Without Running Tests

Windows (PowerShell):

mvn package -DskipTests

Mac/Linux (Bash):

mvn package -DskipTests

Running Tests

mvn test

Debug Logging

Enable in application.yaml:

debug:
  logging: true

Or via system property:

Windows (PowerShell):

java -Ddebug.logging=true -jar .\target\processing-server-1.0-SNAPSHOT.jar

Mac/Linux (Bash):

java -Ddebug.logging=true -jar ./target/processing-server-1.0-SNAPSHOT.jar

With debug logging enabled, the app now logs more session-lifecycle detail, including:

• WebSocket open/close/error
• browser-requested session-close
• heartbeat receipt
• stale-session reaping and cleanup completion

General debug logging does not control the gravity sketches' audio-analysis traces. Use audio.debug.logging for those.

Architecture

See ARCHITECTURE.md for detailed documentation on:

• Component interactions
• Threading model
• Audio streaming implementation
• Event processing flow
• HTTPS/TLS configuration details

Customization

See CUSTOMIZATION.md for guidance on:

• Changing canvas size, colors, and audio quality
• Adding new UI controls (sliders, buttons, color pickers)
• Creating your own Processing sketches
• Using audio data for visualizations
• Adding new event types
• Complete example: Building a particle system
• Using AI coding assistants to speed up development

Next Steps

Now that you have the server running:

1. Try the demo: Open multiple browser tabs/mobile devices to see multi-user interaction
2. Customize the sketch: See CUSTOMIZATION.md for step-by-step guides
3. Learn the architecture: See ARCHITECTURE.md for technical details

Technology Stack

Component	Technology
Web Framework	Helidon 4.4 (SE)
WebSocket	Helidon WebSocket
HTTP Server	Helidon WebServer
Visual Output	Processing 4.5.3 (Java)
Audio	Raw PCM processing
Build Tool	Maven
Java Version	JDK 21 (min), 25+ recommended
HTTPS	Self-signed PKCS12 certificate

Acknowledgments

• Processing Foundation - Visual arts programming
• Helidon - Lightweight Java web framework
• Oracle - Java Development Kit