particled 0.9.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- particled-0.9.0/LICENSE +21 -0
- particled-0.9.0/PKG-INFO +283 -0
- particled-0.9.0/README.md +249 -0
- particled-0.9.0/particled/README.md +381 -0
- particled-0.9.0/particled/__init__.py +43 -0
- particled-0.9.0/particled/__main__.py +7 -0
- particled-0.9.0/particled/app.py +52 -0
- particled-0.9.0/particled/assets/fonts/JetBrainsMonoNLNerdFont-Regular.ttf +0 -0
- particled-0.9.0/particled/assets/fonts/ShureTechMonoNerdFont-Regular.ttf +0 -0
- particled-0.9.0/particled/audio.py +319 -0
- particled-0.9.0/particled/cli.py +856 -0
- particled-0.9.0/particled/compat.py +443 -0
- particled-0.9.0/particled/config.py +225 -0
- particled-0.9.0/particled/logger.py +321 -0
- particled-0.9.0/particled/visuals/__init__.py +18 -0
- particled-0.9.0/particled/visuals/base.py +314 -0
- particled-0.9.0/particled/visuals/gl_renderer.py +544 -0
- particled-0.9.0/particled/visuals/imgui_overlay.py +306 -0
- particled-0.9.0/particled/visuals/overlay.py +860 -0
- particled-0.9.0/particled/visuals/param_panels.py +335 -0
- particled-0.9.0/particled/visuals/particle_cloud/__init__.py +7 -0
- particled-0.9.0/particled/visuals/particle_cloud/base.py +189 -0
- particled-0.9.0/particled/visuals/particle_cloud/gravitas.py +355 -0
- particled-0.9.0/particled/visuals/particle_cloud/impact.py +152 -0
- particled-0.9.0/particled/visuals/penrose.py +359 -0
- particled-0.9.0/particled/visuals/torus_knot.py +187 -0
- particled-0.9.0/pyproject.toml +89 -0
particled-0.9.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Alaa
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
particled-0.9.0/PKG-INFO
ADDED
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: particled
|
|
3
|
+
Version: 0.9.0
|
|
4
|
+
Summary: A Black on White Sound-Interactive Particle Visualiser
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Keywords: audio,visualizer,particles,opengl,realtime
|
|
8
|
+
Author: Alaa
|
|
9
|
+
Author-email: self@alaa.sh
|
|
10
|
+
Requires-Python: >=3.13,<4.0
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
18
|
+
Classifier: Topic :: Multimedia :: Graphics
|
|
19
|
+
Classifier: Topic :: Multimedia :: Sound/Audio
|
|
20
|
+
Requires-Dist: glfw (>=2.7.0,<3.0.0)
|
|
21
|
+
Requires-Dist: imgui-bundle (>=1.92.700,<2.0.0)
|
|
22
|
+
Requires-Dist: inquirerpy (>=0.3.4,<0.4.0)
|
|
23
|
+
Requires-Dist: moderngl (>=5.12.0,<6.0.0)
|
|
24
|
+
Requires-Dist: numpy (>=2.3.5,<3.0.0)
|
|
25
|
+
Requires-Dist: pillow (>=11.0.0,<12.0.0)
|
|
26
|
+
Requires-Dist: pyopengl (>=3.1.10,<4.0.0)
|
|
27
|
+
Requires-Dist: sounddevice (>=0.5.3,<0.6.0)
|
|
28
|
+
Project-URL: Changelog, https://github.com/crafted-glitches/particled/blob/main/CHANGELOG.md
|
|
29
|
+
Project-URL: Homepage, https://github.com/crafted-glitches/particled
|
|
30
|
+
Project-URL: Issues, https://github.com/crafted-glitches/particled/issues
|
|
31
|
+
Project-URL: Repository, https://github.com/crafted-glitches/particled
|
|
32
|
+
Description-Content-Type: text/markdown
|
|
33
|
+
|
|
34
|
+
# Particled
|
|
35
|
+
|
|
36
|
+
Audio-reactive particle visualizer with multiple visualization styles and modes.
|
|
37
|
+
|
|
38
|
+
## Status
|
|
39
|
+
|
|
40
|
+
- Runtime and packaging are release-hardened for PyPI/Homebrew workflows.
|
|
41
|
+
- CI includes Linux and macOS checks for lint, tests, type checks, and build validation.
|
|
42
|
+
- Publish workflows are in place; remaining release steps are maintainer submission actions.
|
|
43
|
+
|
|
44
|
+
## Overview
|
|
45
|
+
|
|
46
|
+
Particled is a real-time particle visualization system that responds to microphone input, featuring:
|
|
47
|
+
|
|
48
|
+
- **Torus Knot**: Complex mathematical knot patterns with 3D geometry
|
|
49
|
+
- **Particle Cloud - Gravitas Mode**: Physics-based gravity-centered expansion with audio reactivity
|
|
50
|
+
- **Particle Cloud - Impact Mode**: Whole-cloud breathing animation with gentle drift
|
|
51
|
+
- **Penrose Triangle**: Impossible triangle geometry with audio-reactive particle flow
|
|
52
|
+
|
|
53
|
+
```mermaid
|
|
54
|
+
flowchart LR
|
|
55
|
+
Mic[Microphone Input] --> Meter[Audio Meter + Features]
|
|
56
|
+
Meter --> Main[Main Render Loop]
|
|
57
|
+
Main --> Impact[Particle Cloud: Impact]
|
|
58
|
+
Main --> Gravitas[Particle Cloud: Gravitas]
|
|
59
|
+
Main --> Torus[Torus Knot]
|
|
60
|
+
Main --> Penrose[Penrose Triangle]
|
|
61
|
+
Main --> Overlay[ImGui Params Overlay]
|
|
62
|
+
Overlay --> Presets[Preset Save / Load]
|
|
63
|
+
Impact --> Frame[GPU Frame]
|
|
64
|
+
Gravitas --> Frame
|
|
65
|
+
Torus --> Frame
|
|
66
|
+
Penrose --> Frame
|
|
67
|
+
|
|
68
|
+
classDef audio fill:#0f766e,color:#ffffff,stroke:#0b5f58,stroke-width:2px;
|
|
69
|
+
classDef core fill:#1d4ed8,color:#ffffff,stroke:#1e40af,stroke-width:2px;
|
|
70
|
+
classDef vis fill:#9333ea,color:#ffffff,stroke:#7e22ce,stroke-width:2px;
|
|
71
|
+
classDef ui fill:#ea580c,color:#ffffff,stroke:#c2410c,stroke-width:2px;
|
|
72
|
+
classDef out fill:#16a34a,color:#ffffff,stroke:#15803d,stroke-width:2px;
|
|
73
|
+
|
|
74
|
+
class Mic,Meter audio;
|
|
75
|
+
class Main core;
|
|
76
|
+
class Impact,Gravitas,Torus,Penrose vis;
|
|
77
|
+
class Overlay,Presets ui;
|
|
78
|
+
class Frame out;
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Features
|
|
82
|
+
|
|
83
|
+
- Real-time audio reactivity via microphone input
|
|
84
|
+
- Multiple visualization styles and sub-modes
|
|
85
|
+
- Interactive CLI configuration
|
|
86
|
+
- Runtime parameters panel with live tuning
|
|
87
|
+
- Per-band particle count and size mapping (8 configurable bands)
|
|
88
|
+
- Preset save/load from the parameters panel
|
|
89
|
+
- Resizable window with fullscreen support
|
|
90
|
+
- Configurable particle physics and return mechanics
|
|
91
|
+
- Frequency-based particle mapping (Gravitas mode)
|
|
92
|
+
- Adjustable motion trails and visual effects
|
|
93
|
+
|
|
94
|
+
## Installation
|
|
95
|
+
|
|
96
|
+
Requires Python 3.13+ and Poetry.
|
|
97
|
+
|
|
98
|
+
### System dependencies
|
|
99
|
+
|
|
100
|
+
**PortAudio** (required by `sounddevice` for microphone input):
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
# Ubuntu / Debian
|
|
104
|
+
sudo apt install -y libportaudio2 portaudio19-dev
|
|
105
|
+
|
|
106
|
+
# macOS
|
|
107
|
+
brew install portaudio
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**SDL2** (only needed if building `pygame-ce` from source — pre-built wheels are available for most platforms):
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
# Ubuntu / Debian
|
|
114
|
+
sudo apt install -y libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Install
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
# Clone the repository
|
|
121
|
+
git clone https://github.com/crafted-glitches/particled.git
|
|
122
|
+
cd particled
|
|
123
|
+
|
|
124
|
+
# Install dependencies
|
|
125
|
+
poetry install
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### Optional: install as a package command
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
python -m pip install -e .
|
|
132
|
+
particled --version
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Quick Start
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
# Run with interactive configuration
|
|
139
|
+
poetry run particled --selective
|
|
140
|
+
|
|
141
|
+
# Or run with defaults
|
|
142
|
+
poetry run particled
|
|
143
|
+
|
|
144
|
+
# Version check (non-interactive)
|
|
145
|
+
poetry run particled --version
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
The application will prompt you to:
|
|
149
|
+
1. Select visualization style (Torus Knot or Particle Cloud)
|
|
150
|
+
2. Select mode (for Particle Cloud: Gravitas or Impact)
|
|
151
|
+
3. Optionally configure parameters interactively
|
|
152
|
+
|
|
153
|
+
**Controls:**
|
|
154
|
+
- `ESC` - Exit the application
|
|
155
|
+
- `TAB` - Toggle parameters panel
|
|
156
|
+
- `G` - Toggle audio graph
|
|
157
|
+
- Window is resizable by default
|
|
158
|
+
|
|
159
|
+
## macOS Runtime Notes
|
|
160
|
+
|
|
161
|
+
macOS-specific runtime permissions and external-display caveats are documented in
|
|
162
|
+
[.0folder.bak/publishing/macos-runtime-notes.md](.0folder.bak/publishing/macos-runtime-notes.md).
|
|
163
|
+
|
|
164
|
+
## Visualization Modes
|
|
165
|
+
|
|
166
|
+
### Torus Knot
|
|
167
|
+
Complex mathematical patterns based on torus knot geometry with audio-driven distortion and rotation.
|
|
168
|
+
|
|
169
|
+
### Particle Cloud - Gravitas (Default)
|
|
170
|
+
Physics-based particle system where audio pushes particles radially outward from center:
|
|
171
|
+
- Audio threshold to prevent ambient noise jitter
|
|
172
|
+
- Three return mechanics: Exponential (default), Spring, or Linear
|
|
173
|
+
- Frequency-band particle mapping (bass/mid/treble)
|
|
174
|
+
- Drift and rotation when idle
|
|
175
|
+
|
|
176
|
+
### Particle Cloud - Impact
|
|
177
|
+
Gentle whole-cloud breathing animation with:
|
|
178
|
+
- Soft expansion and contraction
|
|
179
|
+
- Drift motion for organic feel
|
|
180
|
+
- Audio-reactive size and motion
|
|
181
|
+
|
|
182
|
+
## Documentation
|
|
183
|
+
|
|
184
|
+
See [particled/README.md](particled/README.md) for comprehensive documentation including:
|
|
185
|
+
- Package structure and module details
|
|
186
|
+
- Complete parameter reference
|
|
187
|
+
- Configuration examples
|
|
188
|
+
- API usage guide
|
|
189
|
+
|
|
190
|
+
Publishing and release docs:
|
|
191
|
+
- [.0folder.bak/publishing/pypi-readiness.md](.0folder.bak/publishing/pypi-readiness.md)
|
|
192
|
+
- [.0folder.bak/publishing/homebrew-readiness.md](.0folder.bak/publishing/homebrew-readiness.md)
|
|
193
|
+
- [RELEASING.md](RELEASING.md)
|
|
194
|
+
- [CHANGELOG.md](CHANGELOG.md)
|
|
195
|
+
|
|
196
|
+
## Configuration
|
|
197
|
+
|
|
198
|
+
All parameters can be configured either:
|
|
199
|
+
- **Interactively** via CLI prompts at startup
|
|
200
|
+
- **Programmatically** via the `Config` dataclass
|
|
201
|
+
|
|
202
|
+
Example programmatic configuration:
|
|
203
|
+
|
|
204
|
+
```python
|
|
205
|
+
from particled import Config, ParticleCloudGravitas
|
|
206
|
+
|
|
207
|
+
cfg = Config()
|
|
208
|
+
cfg.num_particles = 8000
|
|
209
|
+
cfg.audio_noise_threshold = 0.05
|
|
210
|
+
cfg.gravitas_push_strength = 2.5
|
|
211
|
+
cfg.gravitas_return_mechanic = "spring"
|
|
212
|
+
|
|
213
|
+
field = ParticleCloudGravitas(cfg)
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
## Development
|
|
217
|
+
|
|
218
|
+
```bash
|
|
219
|
+
# Install development dependencies
|
|
220
|
+
poetry install --with dev
|
|
221
|
+
|
|
222
|
+
# Run linter
|
|
223
|
+
poetry run ruff check .
|
|
224
|
+
|
|
225
|
+
# Run CI lint gate used in workflow
|
|
226
|
+
poetry run ruff check . --select E9,F63,F7,F82
|
|
227
|
+
|
|
228
|
+
# Run tests
|
|
229
|
+
poetry run pytest
|
|
230
|
+
|
|
231
|
+
# Build distributable artifacts and verify metadata
|
|
232
|
+
poetry run python -m build
|
|
233
|
+
poetry run twine check dist/*
|
|
234
|
+
|
|
235
|
+
# Type checks (CI target)
|
|
236
|
+
poetry run mypy particled/config.py particled/visuals/param_panels.py particled/visuals/particle_cloud/base.py particled/visuals/particle_cloud/impact.py
|
|
237
|
+
|
|
238
|
+
# Install pre-commit hooks
|
|
239
|
+
poetry run pre-commit install
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
## License
|
|
243
|
+
|
|
244
|
+
MIT. See [LICENSE](LICENSE).
|
|
245
|
+
|
|
246
|
+
## Release Process
|
|
247
|
+
|
|
248
|
+
Release policy and checklist are documented in [RELEASING.md](RELEASING.md), and version history is tracked in [CHANGELOG.md](CHANGELOG.md).
|
|
249
|
+
|
|
250
|
+
Submission-only release steps:
|
|
251
|
+
1. Update version and changelog.
|
|
252
|
+
2. Push tag `vX.Y.Z`.
|
|
253
|
+
3. Publish release (triggers PyPI workflow).
|
|
254
|
+
4. Update Homebrew formula URL/SHA for the released artifact.
|
|
255
|
+
|
|
256
|
+
```mermaid
|
|
257
|
+
flowchart TD
|
|
258
|
+
Start[Prepare Release] --> Bump[Bump Version + Update Changelog]
|
|
259
|
+
Bump --> Tag[Create and Push Tag]
|
|
260
|
+
Tag --> GH[GitHub Release Published]
|
|
261
|
+
GH --> PyPI[Trusted Publishing to PyPI]
|
|
262
|
+
PyPI --> Verify[Verify pip install + package metadata]
|
|
263
|
+
Verify --> Brew[Update Homebrew Formula URL + SHA]
|
|
264
|
+
Brew --> Done[Release Complete]
|
|
265
|
+
|
|
266
|
+
classDef prep fill:#334155,color:#ffffff,stroke:#1e293b,stroke-width:2px;
|
|
267
|
+
classDef ship fill:#047857,color:#ffffff,stroke:#065f46,stroke-width:2px;
|
|
268
|
+
classDef dist fill:#7c3aed,color:#ffffff,stroke:#6d28d9,stroke-width:2px;
|
|
269
|
+
classDef done fill:#166534,color:#ffffff,stroke:#14532d,stroke-width:2px;
|
|
270
|
+
|
|
271
|
+
class Start,Bump,Tag,GH prep;
|
|
272
|
+
class PyPI,Verify,Brew ship;
|
|
273
|
+
class Done done;
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
## Credits
|
|
277
|
+
|
|
278
|
+
Built with:
|
|
279
|
+
- [Pygame](https://www.pygame.org/) - Graphics and window management
|
|
280
|
+
- [NumPy](https://numpy.org/) - Numerical computations
|
|
281
|
+
- [sounddevice](https://python-sounddevice.readthedocs.io/) - Audio input
|
|
282
|
+
- [InquirerPy](https://inquirerpy.readthedocs.io/) - Interactive CLI
|
|
283
|
+
|
|
@@ -0,0 +1,249 @@
|
|
|
1
|
+
# Particled
|
|
2
|
+
|
|
3
|
+
Audio-reactive particle visualizer with multiple visualization styles and modes.
|
|
4
|
+
|
|
5
|
+
## Status
|
|
6
|
+
|
|
7
|
+
- Runtime and packaging are release-hardened for PyPI/Homebrew workflows.
|
|
8
|
+
- CI includes Linux and macOS checks for lint, tests, type checks, and build validation.
|
|
9
|
+
- Publish workflows are in place; remaining release steps are maintainer submission actions.
|
|
10
|
+
|
|
11
|
+
## Overview
|
|
12
|
+
|
|
13
|
+
Particled is a real-time particle visualization system that responds to microphone input, featuring:
|
|
14
|
+
|
|
15
|
+
- **Torus Knot**: Complex mathematical knot patterns with 3D geometry
|
|
16
|
+
- **Particle Cloud - Gravitas Mode**: Physics-based gravity-centered expansion with audio reactivity
|
|
17
|
+
- **Particle Cloud - Impact Mode**: Whole-cloud breathing animation with gentle drift
|
|
18
|
+
- **Penrose Triangle**: Impossible triangle geometry with audio-reactive particle flow
|
|
19
|
+
|
|
20
|
+
```mermaid
|
|
21
|
+
flowchart LR
|
|
22
|
+
Mic[Microphone Input] --> Meter[Audio Meter + Features]
|
|
23
|
+
Meter --> Main[Main Render Loop]
|
|
24
|
+
Main --> Impact[Particle Cloud: Impact]
|
|
25
|
+
Main --> Gravitas[Particle Cloud: Gravitas]
|
|
26
|
+
Main --> Torus[Torus Knot]
|
|
27
|
+
Main --> Penrose[Penrose Triangle]
|
|
28
|
+
Main --> Overlay[ImGui Params Overlay]
|
|
29
|
+
Overlay --> Presets[Preset Save / Load]
|
|
30
|
+
Impact --> Frame[GPU Frame]
|
|
31
|
+
Gravitas --> Frame
|
|
32
|
+
Torus --> Frame
|
|
33
|
+
Penrose --> Frame
|
|
34
|
+
|
|
35
|
+
classDef audio fill:#0f766e,color:#ffffff,stroke:#0b5f58,stroke-width:2px;
|
|
36
|
+
classDef core fill:#1d4ed8,color:#ffffff,stroke:#1e40af,stroke-width:2px;
|
|
37
|
+
classDef vis fill:#9333ea,color:#ffffff,stroke:#7e22ce,stroke-width:2px;
|
|
38
|
+
classDef ui fill:#ea580c,color:#ffffff,stroke:#c2410c,stroke-width:2px;
|
|
39
|
+
classDef out fill:#16a34a,color:#ffffff,stroke:#15803d,stroke-width:2px;
|
|
40
|
+
|
|
41
|
+
class Mic,Meter audio;
|
|
42
|
+
class Main core;
|
|
43
|
+
class Impact,Gravitas,Torus,Penrose vis;
|
|
44
|
+
class Overlay,Presets ui;
|
|
45
|
+
class Frame out;
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Features
|
|
49
|
+
|
|
50
|
+
- Real-time audio reactivity via microphone input
|
|
51
|
+
- Multiple visualization styles and sub-modes
|
|
52
|
+
- Interactive CLI configuration
|
|
53
|
+
- Runtime parameters panel with live tuning
|
|
54
|
+
- Per-band particle count and size mapping (8 configurable bands)
|
|
55
|
+
- Preset save/load from the parameters panel
|
|
56
|
+
- Resizable window with fullscreen support
|
|
57
|
+
- Configurable particle physics and return mechanics
|
|
58
|
+
- Frequency-based particle mapping (Gravitas mode)
|
|
59
|
+
- Adjustable motion trails and visual effects
|
|
60
|
+
|
|
61
|
+
## Installation
|
|
62
|
+
|
|
63
|
+
Requires Python 3.13+ and Poetry.
|
|
64
|
+
|
|
65
|
+
### System dependencies
|
|
66
|
+
|
|
67
|
+
**PortAudio** (required by `sounddevice` for microphone input):
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
# Ubuntu / Debian
|
|
71
|
+
sudo apt install -y libportaudio2 portaudio19-dev
|
|
72
|
+
|
|
73
|
+
# macOS
|
|
74
|
+
brew install portaudio
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
**SDL2** (only needed if building `pygame-ce` from source — pre-built wheels are available for most platforms):
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
# Ubuntu / Debian
|
|
81
|
+
sudo apt install -y libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### Install
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
# Clone the repository
|
|
88
|
+
git clone https://github.com/crafted-glitches/particled.git
|
|
89
|
+
cd particled
|
|
90
|
+
|
|
91
|
+
# Install dependencies
|
|
92
|
+
poetry install
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Optional: install as a package command
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
python -m pip install -e .
|
|
99
|
+
particled --version
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Quick Start
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
# Run with interactive configuration
|
|
106
|
+
poetry run particled --selective
|
|
107
|
+
|
|
108
|
+
# Or run with defaults
|
|
109
|
+
poetry run particled
|
|
110
|
+
|
|
111
|
+
# Version check (non-interactive)
|
|
112
|
+
poetry run particled --version
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
The application will prompt you to:
|
|
116
|
+
1. Select visualization style (Torus Knot or Particle Cloud)
|
|
117
|
+
2. Select mode (for Particle Cloud: Gravitas or Impact)
|
|
118
|
+
3. Optionally configure parameters interactively
|
|
119
|
+
|
|
120
|
+
**Controls:**
|
|
121
|
+
- `ESC` - Exit the application
|
|
122
|
+
- `TAB` - Toggle parameters panel
|
|
123
|
+
- `G` - Toggle audio graph
|
|
124
|
+
- Window is resizable by default
|
|
125
|
+
|
|
126
|
+
## macOS Runtime Notes
|
|
127
|
+
|
|
128
|
+
macOS-specific runtime permissions and external-display caveats are documented in
|
|
129
|
+
[.0folder.bak/publishing/macos-runtime-notes.md](.0folder.bak/publishing/macos-runtime-notes.md).
|
|
130
|
+
|
|
131
|
+
## Visualization Modes
|
|
132
|
+
|
|
133
|
+
### Torus Knot
|
|
134
|
+
Complex mathematical patterns based on torus knot geometry with audio-driven distortion and rotation.
|
|
135
|
+
|
|
136
|
+
### Particle Cloud - Gravitas (Default)
|
|
137
|
+
Physics-based particle system where audio pushes particles radially outward from center:
|
|
138
|
+
- Audio threshold to prevent ambient noise jitter
|
|
139
|
+
- Three return mechanics: Exponential (default), Spring, or Linear
|
|
140
|
+
- Frequency-band particle mapping (bass/mid/treble)
|
|
141
|
+
- Drift and rotation when idle
|
|
142
|
+
|
|
143
|
+
### Particle Cloud - Impact
|
|
144
|
+
Gentle whole-cloud breathing animation with:
|
|
145
|
+
- Soft expansion and contraction
|
|
146
|
+
- Drift motion for organic feel
|
|
147
|
+
- Audio-reactive size and motion
|
|
148
|
+
|
|
149
|
+
## Documentation
|
|
150
|
+
|
|
151
|
+
See [particled/README.md](particled/README.md) for comprehensive documentation including:
|
|
152
|
+
- Package structure and module details
|
|
153
|
+
- Complete parameter reference
|
|
154
|
+
- Configuration examples
|
|
155
|
+
- API usage guide
|
|
156
|
+
|
|
157
|
+
Publishing and release docs:
|
|
158
|
+
- [.0folder.bak/publishing/pypi-readiness.md](.0folder.bak/publishing/pypi-readiness.md)
|
|
159
|
+
- [.0folder.bak/publishing/homebrew-readiness.md](.0folder.bak/publishing/homebrew-readiness.md)
|
|
160
|
+
- [RELEASING.md](RELEASING.md)
|
|
161
|
+
- [CHANGELOG.md](CHANGELOG.md)
|
|
162
|
+
|
|
163
|
+
## Configuration
|
|
164
|
+
|
|
165
|
+
All parameters can be configured either:
|
|
166
|
+
- **Interactively** via CLI prompts at startup
|
|
167
|
+
- **Programmatically** via the `Config` dataclass
|
|
168
|
+
|
|
169
|
+
Example programmatic configuration:
|
|
170
|
+
|
|
171
|
+
```python
|
|
172
|
+
from particled import Config, ParticleCloudGravitas
|
|
173
|
+
|
|
174
|
+
cfg = Config()
|
|
175
|
+
cfg.num_particles = 8000
|
|
176
|
+
cfg.audio_noise_threshold = 0.05
|
|
177
|
+
cfg.gravitas_push_strength = 2.5
|
|
178
|
+
cfg.gravitas_return_mechanic = "spring"
|
|
179
|
+
|
|
180
|
+
field = ParticleCloudGravitas(cfg)
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## Development
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
# Install development dependencies
|
|
187
|
+
poetry install --with dev
|
|
188
|
+
|
|
189
|
+
# Run linter
|
|
190
|
+
poetry run ruff check .
|
|
191
|
+
|
|
192
|
+
# Run CI lint gate used in workflow
|
|
193
|
+
poetry run ruff check . --select E9,F63,F7,F82
|
|
194
|
+
|
|
195
|
+
# Run tests
|
|
196
|
+
poetry run pytest
|
|
197
|
+
|
|
198
|
+
# Build distributable artifacts and verify metadata
|
|
199
|
+
poetry run python -m build
|
|
200
|
+
poetry run twine check dist/*
|
|
201
|
+
|
|
202
|
+
# Type checks (CI target)
|
|
203
|
+
poetry run mypy particled/config.py particled/visuals/param_panels.py particled/visuals/particle_cloud/base.py particled/visuals/particle_cloud/impact.py
|
|
204
|
+
|
|
205
|
+
# Install pre-commit hooks
|
|
206
|
+
poetry run pre-commit install
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
## License
|
|
210
|
+
|
|
211
|
+
MIT. See [LICENSE](LICENSE).
|
|
212
|
+
|
|
213
|
+
## Release Process
|
|
214
|
+
|
|
215
|
+
Release policy and checklist are documented in [RELEASING.md](RELEASING.md), and version history is tracked in [CHANGELOG.md](CHANGELOG.md).
|
|
216
|
+
|
|
217
|
+
Submission-only release steps:
|
|
218
|
+
1. Update version and changelog.
|
|
219
|
+
2. Push tag `vX.Y.Z`.
|
|
220
|
+
3. Publish release (triggers PyPI workflow).
|
|
221
|
+
4. Update Homebrew formula URL/SHA for the released artifact.
|
|
222
|
+
|
|
223
|
+
```mermaid
|
|
224
|
+
flowchart TD
|
|
225
|
+
Start[Prepare Release] --> Bump[Bump Version + Update Changelog]
|
|
226
|
+
Bump --> Tag[Create and Push Tag]
|
|
227
|
+
Tag --> GH[GitHub Release Published]
|
|
228
|
+
GH --> PyPI[Trusted Publishing to PyPI]
|
|
229
|
+
PyPI --> Verify[Verify pip install + package metadata]
|
|
230
|
+
Verify --> Brew[Update Homebrew Formula URL + SHA]
|
|
231
|
+
Brew --> Done[Release Complete]
|
|
232
|
+
|
|
233
|
+
classDef prep fill:#334155,color:#ffffff,stroke:#1e293b,stroke-width:2px;
|
|
234
|
+
classDef ship fill:#047857,color:#ffffff,stroke:#065f46,stroke-width:2px;
|
|
235
|
+
classDef dist fill:#7c3aed,color:#ffffff,stroke:#6d28d9,stroke-width:2px;
|
|
236
|
+
classDef done fill:#166534,color:#ffffff,stroke:#14532d,stroke-width:2px;
|
|
237
|
+
|
|
238
|
+
class Start,Bump,Tag,GH prep;
|
|
239
|
+
class PyPI,Verify,Brew ship;
|
|
240
|
+
class Done done;
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
## Credits
|
|
244
|
+
|
|
245
|
+
Built with:
|
|
246
|
+
- [Pygame](https://www.pygame.org/) - Graphics and window management
|
|
247
|
+
- [NumPy](https://numpy.org/) - Numerical computations
|
|
248
|
+
- [sounddevice](https://python-sounddevice.readthedocs.io/) - Audio input
|
|
249
|
+
- [InquirerPy](https://inquirerpy.readthedocs.io/) - Interactive CLI
|