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.
@@ -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.
@@ -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