Metadata-Version: 2.4
Name: wav-fourier-chladni
Version: 1.0.0
Summary: Generate Chladni plate resonant pattern signatures from WAV audio waveforms using Fourier peak frequency estimation
Author-email: ganidhu <ganidhu@example.com>
Project-URL: Homepage, https://github.com/ganidhu/wav-fourier-chladni
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# WAV → Fourier → Chladni Pattern

> An interactive tool to analyze WAV audio files, perform discrete Fourier analysis to extract dominant peak frequencies, and map those peaks to physical resonant modes on a square Chladni vibrating plate.

For the mathematical background of plate vibration models, see [this paper](https://ddonle.com/docs/Chladni_Plate.pdf) on Chladni Plates.

## Project Structure

* [voca-spectral.py](voca-spectral.py) — The main interactive Python pipeline script (3-step TUI: input selection, Fourier peak analysis, and visualizer exporting).
* [fourier_analysis.html](fourier_analysis.html) — Dynamic HTML report template displaying audio waveform and FFT spectrum charts (Chart.js).
* [chladni_simulator.html](chladni_simulator.html) — Interactive 2D vibrating plate simulator displaying nodal sand patterns corresponding to the wave equation.
* [fourier_transform_analysis.md](fourier_transform_analysis.md) — Document summarizing Fourier transform calculations and eigenvalue mapping.

## Features

* **WAV Audio Analysis** — Parse 16-bit PCM mono WAV waveforms and compute dominant peak frequencies using discrete Fourier analysis.
* **Mac-Native UI Dialogs** — Native macOS file picker window dialogs (`osascript`) for importing audio and selecting export folders, with terminal fallback prompts for Windows/Linux.
* **Immediate Validation** — Immediate WAV format parsing and corruption checks during step 1 before starting computation.
* **Vector SVG Exports** — Generate resolution-independent SVG designs of the resulting nodal sand patterns for graphic/branding usage.
* **Portable Web Visualizers** — Export standalone HTML dashboards to inspect audio waveforms, FFT spectra, and simulated 2D plate nodal lines.
* **Zero External Python Dependencies** — Built entirely on the standard Python library (no numpy/scipy/matplotlib required to run the core script).

## Advanced Wave Mechanics

This project models Chladni sand patterns using Cartesian standing wave solutions of the multi-dimensional wave equation.

### The Cartesian Wave Equation
For a square vibrating plate $\Omega = \{(x,y) \in \mathbb{R}^2 \mid -L \le x, y \le L\}$, the displacement $u(x, y, t)$ is modeled by:

$$u_{tt} = c^2\nabla^2u = c^2\left(\frac{\partial^2u}{\partial x^2} + \frac{\partial^2u}{\partial y^2}\right)$$

Assuming clamped boundary conditions at the edges, the standing wave solutions (eigenmodes) can be approximated by:

$$u(x, y, t) = \sum_{n=1}^{\infty}\sum_{m=1}^{\infty} w_{nm} \cdot \left(\sin\left(\frac{n\pi x}{L}\right)\sin\left(\frac{m\pi y}{L}\right) + \beta\sin\left(\frac{m\pi x}{L}\right)\sin\left(\frac{n\pi y}{L}\right)\right)\cos(\omega_{nm} t)$$

Where:
* $n, m$ are the integer mode parameters (eigenvalues).
* $w_{nm}$ is the weight of each mode, mapped directly from the dominant audio frequency amplitudes computed via Fourier analysis.
* $\beta$ is the symmetry factor (typically $\pm 1$ for square plates).
* The sand particles accumulate at the **nodal lines** where the plate displacement is zero, i.e., $u(x,y,t) \approx 0$.

---

## Installation & Running

Since the core pipeline runs entirely on the Python standard library, there are **no third-party Python libraries** to install.

### 1. Install via pip
You can install the package directly as a global CLI tool from the repository folder:
```bash
pip install .
```

Once installed, you can launch the pipeline from anywhere using the global command:
```bash
wav-fourier-chladni
```

### 2. Alternative: Run the source script directly
If you do not want to install it globally, you can execute the script directly from the source directory:
```bash
python3 wav_fourier_chladni/cli.py
```

### 3. Prerequisites (Optional)
To run the core analysis and visualizers, you only need **Python 3** installed.

If you wish to use the **live microphone recording** feature:
* **macOS**: `brew install sox` or ensure `ffmpeg` is in your system path.
* **Linux**: `sudo apt install alsa-utils` (for `arecord`) or `sox`.

The script will guide you through:
1. **Audio Selection**: Pick a WAV file using a native macOS window picker or record live from the microphone.
2. **Analysis**: Performs the discrete Fourier calculations.
3. **Resonant Signatures**: Renders an ASCII art preview of the pattern in the terminal, and lets you choose to export SVG files or HTML dashboards.


## 🤝 Contributing

Got ideas? Found a bug?

PRs and issues are very welcome! This is a community tool and it gets better when more people chip in. Even small improvements — better selectors, new step actions, docs fixes — make a real difference.

[Open an issue](https://github.com/ganidhu/wav-fourier-chladni/issues) or just submit a PR. Let's build it together. 🙌

---

## 📄 License

MIT

---

<p align="center">
  <sub>Built by Ganidhu and Baymax</sub>
</p>
