PyChimes — Ambient Generative Windchimes

A browser-based generative instrument that blends real-time synthesis, procedural rhythm, and tonal systems. Runs entirely client-side with a Python engine in Pyodide and a Web Audio worklet for smooth, local playback.

Overview

PyChimes renders evolving wind-chime textures by simulating strikes whose timing and force are driven by an algorithmic wind model. The musical layer constrains pitch selection to user-selectable scales and root/octave. A lightweight stereo reverb adds space. The entire instrument runs in the browser:

Pyodide Worker hosts the Python engine (chimes_core.py) and generates audio blocks.
SharedArrayBuffer streams interleaved stereo frames to the audio thread with zero copies.
AudioWorklet consumes frames deterministically for low-latency output.
HTML/CSS UI provides controls for wind, musicality, overtones, reverb, gust mode, and tonal context.

Architecture

┌───────────────────────────┐      SharedArrayBuffer       ┌─────────────────────┐
│  Web Worker (Pyodide)     │  ─────────────────────────▶  │  AudioWorkletNode   │
│  - Python engine          │                              │  - pulls stereo L/R │
│  - NumPy DSP              │                              │  - outputs to DAC   │
└─────────────▲─────────────┘                              └──────────┬──────────┘
              │   postMessage (params, gust events)                   │
              │                                                       ▼
       ┌──────┴─────────────────────────────────────────────────────────────┐
       │                  Web UI (HTML/CSS/JS)                              │
       │    sliders, selects, checkboxes → worker param messages            │
       └────────────────────────────────────────────────────────────────────┘

Key Files

Path	Role
`/app/chimes_core.py`	Python synthesis & generative logic (wind, gusts, musical system, reverb)
`/worker/pychimes-worker.js`	Boots Pyodide, runs the engine, fills the ring buffer, emits gust events
`/worklet/pychimes-processor.js`	AudioWorklet processor that reads from the shared buffer
`main.js`	Wires UI → worker, sets up worklet and SharedArrayBuffer
`index.html`	Web UI layout and styles

Serving the App

Because the project uses SharedArrayBuffer, browsers require cross-origin isolation. Serve over HTTPS (or localhost) with these headers:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Resource-Policy: same-origin

Local quick start (example)

Run a dev server that sets the headers above (any static server or proxy that can inject headers). Examples: Caddy, nginx, Vite preview, or an Express script.
Open https://localhost:<port>/ and click Start Wind Chime.

Plain python -m http.server does not set COOP/COEP headers. If you must use it, front it with a proxy that adds the headers.

Directory layout

project/
  index.html
  main.js
  /worker/pychimes-worker.js
  /worklet/pychimes-processor.js
  /app/chimes_core.py

Engine Design (chimes_core.py)

Wind Model

User wind (0–100) maps to a strike rate via a nonlinear curve.
Inter-strike times are drawn from an exponential distribution with mean 1/λ.
Strike force derives from wind with added jitter and an energy cap.

Gust System

Enabled by the “Gust mode” checkbox; frequency set by the “Gust frequency” slider.
Internally, the slider value g (0–1) maps to a Poisson-like process with average gap:
```
T(g) = 30 - 27 * (g^1.25)   seconds  (approx. 30 s → 3 s)
```
Active gusts multiply both strike rate and force (soft-knee envelope). The worker periodically polls engine.is_gust_active() and toggles the UI badge.

Pitch & Musicality

Root and scale (major, modes, pentatonics, several Japanese scales, and a few Indian ragas).
“Musicality” biases selection toward consonant degrees and smooth motion; lower values increase randomness.

Synthesis

Each tube is a damped oscillator with optional partials (2x, 2.7x, 3x) mixed by overtone amount, low-passed for warmth.
Soft saturation (tanh) prevents harsh peaks.
Light stereo reverb (parallel combs + all-pass) with denormal protection and a DC blocker.
Per-block rendering produces (N,2) float32 stereo frames.

Signal Flow

wind  ──▶ rate model ─┐
                      │      ┌─ envelopes/partials ─┐
gust ──▶ modifiers ───┼─▶ strikes ───────────────▶ mix ─▶ reverb ─▶ DC block ─▶ out(L/R)
                      │      └─ soft saturation ──┘
scale/root/octave ───▶ pitch selection

Technologies

Layer	Tool	Purpose
Browser	Web Audio API (AudioWorklet)	Deterministic, low-latency audio output
Browser	SharedArrayBuffer	Zero-copy streaming between worker and audio thread
Python	Pyodide 0.26 + NumPy	Runs DSP and generative logic client-side
UI	HTML/CSS/JS	Web UI Interface and controls

Extending

Add alternative synthesis voices (e.g., modal resonators, FM metallic, noise-excited bars).
Swap in different reverbs or filters (convolution, Schroeder/Moorer variants, feedback delay networks).
Drive the engine with live weather data; map gusts to real wind gusts.
Record or export output buffers to WAV/WebM.

Notes on Deployment

Ensure cross-origin isolation (COOP/COEP headers) in production.
Serve Pyodide files with correct MIME types if hosting locally.
Prefer HTTP/2 or HTTP/3 for faster module delivery.

Return to the app: index.html