{"id":29105104,"url":"https://github.com/chubes4/visualizer-block","last_synced_at":"2025-08-19T03:13:45.443Z","repository":{"id":300891016,"uuid":"1007488587","full_name":"chubes4/visualizer-block","owner":"chubes4","description":"Interactive, audio-reactive particle system block for WordPress. Real-time controls, canvas rendering, audio sync, magnetism, and advanced visual effects. Built for Gutenberg.","archived":false,"fork":false,"pushed_at":"2025-06-27T00:22:44.000Z","size":287,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-25T07:33:58.655Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://chubes.net/visualizer","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chubes4.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-24T04:46:33.000Z","updated_at":"2025-06-27T00:24:23.000Z","dependencies_parsed_at":"2025-06-24T05:35:52.372Z","dependency_job_id":"f2e9a2ab-1aa1-4571-95f2-1316aed958a6","html_url":"https://github.com/chubes4/visualizer-block","commit_stats":null,"previous_names":["chubes4/visualizer-block"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/chubes4/visualizer-block","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chubes4%2Fvisualizer-block","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chubes4%2Fvisualizer-block/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chubes4%2Fvisualizer-block/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chubes4%2Fvisualizer-block/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chubes4","download_url":"https://codeload.github.com/chubes4/visualizer-block/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chubes4%2Fvisualizer-block/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271093391,"owners_count":24698003,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-19T02:00:09.176Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-29T01:06:56.211Z","updated_at":"2025-08-19T03:13:45.392Z","avatar_url":"https://github.com/chubes4.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Visualizer Block\n\nAn interactive particle system WordPress block with real-time controls and canvas rendering. Create stunning animated particle visualizations that your visitors can customize in real-time.\n\n## Features\n\n- **Interactive Particle System**: Advanced particle effects with customizable behaviors\n- **Mouse Interaction Modes**: Attract, repel, orbital, or none\n- **Real-time Controls**: Visitors can customize colors, animation speed, particle count, and effects\n- **Canvas-Based Rendering**: Smooth 60fps animations using HTML5 Canvas API\n- **Responsive Design**: Automatically adapts to container width\n- **Connection Lines**: Dynamic connections between nearby particles\n- **Gutenberg Integration**: Full block editor support with live preview\n- **Modern WordPress Standards**: Built with block.json API v2 and follows WordPress coding standards\n\n## Demo\n\nSee it in action at [chubes.net/visualizer](https://chubes.net/visualizer)\n\n## Installation\n\n### From WordPress Admin (Recommended)\n\n1. Download the latest release ZIP file\n2. Go to `Plugins \u003e Add New \u003e Upload Plugin`\n3. Upload the ZIP file and activate the plugin\n4. The \"Particle Visualizer\" block will be available in the block editor\n\n### Manual Installation\n\n1. Download or clone this repository\n2. Upload the `visualizer-block` folder to `/wp-content/plugins/`\n3. Activate the plugin through the 'Plugins' menu in WordPress\n\n### Development Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/chubes4/visualizer-block.git\ncd visualizer-block\n\n# Install dependencies\nnpm install\n\n# Build the block assets\nnpm run build\n\n# Create distribution package\nnpm run dist\n```\n\n## Usage\n\n### Adding the Block\n\n1. Create a new post or page\n2. Click the \"+\" to add a new block\n3. Search for \"Particle Visualizer\" or find it in the Widgets category\n4. Insert the block\n\n### Block Settings\n\nThe particle system automatically takes the full width of its container. Configure these settings in the block inspector:\n\n- **Background Color**: Set the canvas background color\n- **Primary Color**: Particle color\n- **Secondary Color**: Connection line color\n- **Animation Speed**: Control the speed of animations (0.1x to 5x)\n- **Particle Count**: Number of particles in the system (10-1000)\n- **Particle Size**: Size of individual particles (1-10)\n- **Connection Distance**: How close particles need to be to connect (0-300)\n- **Mouse Interaction**: How particles respond to mouse movement (attract, repel, orbital, none)\n- **Bounce Off Walls**: Enable/disable wall collision\n- **Rubberize Particles**: Enable/disable rubberized movement\n- **Particle Magnetism**: Enable/disable magnetic behavior\n- **Collision Color Change**: Enable/disable color change on collision\n- **Audio Sync**: Enable/disable audio-reactive effects\n- **Glow Effect**: Enable/disable glow effect\n- **Show Controls**: Toggle whether visitors can customize the visualization\n\n### Frontend Interaction\n\nWhen frontend controls are enabled, visitors can:\n\n- Switch between mouse interaction modes\n- Adjust colors using color pickers\n- Control animation speed, particle count, and size\n- Click to create particle bursts\n- See changes applied immediately\n\n### Mouse Interactions\n\n- **Attract**: Particles are drawn toward the mouse cursor\n- **Repel**: Particles move away from the mouse cursor\n- **Orbital**: Particles orbit around the mouse cursor\n- **None**: No mouse interaction\n\n**Note:** Only circular particles are currently supported. There is no option for squares, triangles, or stars.\n\n## Technical Features\n\n### Responsive Design\n- Automatically calculates canvas dimensions based on container width\n- Maintains aspect ratio across different screen sizes\n- Minimum height enforcement for very narrow containers\n- Proper canvas scaling for high-DPI displays\n\n### Performance Optimizations\n- Uses `requestAnimationFrame` for smooth 60fps animations\n- Dynamic asset loading - frontend assets only load when block is present\n- Efficient particle system with proper cleanup\n- Memory management for particle bursts\n\n### WordPress Integration\n- Modern block development with block.json API v2\n- **Dynamic asset versioning using `filemtime()`** for all enqueued CSS and JS assets (both development and production)\n- Proper sanitization and security measures\n- Accessibility considerations\n- Clean, semantic HTML output\n\n## Customization\n\n### CSS Styling\n\nThe plugin uses modular CSS classes you can override. The main frontend container uses `.visualizer-block-container`:\n\n```css\n/* Customize the canvas container */\n.visualizer-block-container {\n    border-radius: 16px;\n    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.2);\n}\n\n/* Style the controls panel */\n.visualizer-controls {\n    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);\n    color: white;\n}\n\n/* Make canvas take full width */\n.visualizer-block-container {\n    width: 100%;\n}\n```\n\n## Development\n\n### Requirements\n\n- WordPress 5.0+\n- PHP 7.4+\n- Node.js 16+ (for development)\n\n### File Structure\n\n```\nvisualizer-block/\n├── visualizer-block.php          # Main plugin file (singleton class VisualizerBlock)\n├── block.json                    # Block configuration\n├── src/\n│   ├── core/visualizer.js        # Main frontend logic\n│   ├── index.js                  # Editor JavaScript (block registration)\n│   ├── editor.css                # Editor styles\n│   ├── style.css                 # Frontend styles (development)\n│   ├── ...                       # Modular JS/CSS by feature\n├── build/                        # Compiled assets (generated for production)\n├── package.json                  # Build configuration\n├── webpack.config.js             # Webpack configuration\n├── build-dist.sh                 # Distribution build script\n└── README.md                     # Documentation\n```\n\n### Building from Source\n\n```bash\n# Install dependencies\nnpm install\n\n# Development build with watch\nnpm run start\n\n# Production build\nnpm run build\n\n# Create distribution package\nnpm run dist\n\n# Lint code\nnpm run lint\n```\n\n### Extensibility\n\n- The main PHP class is `VisualizerBlock` (singleton pattern). You can extend or hook into its methods by using standard WordPress hooks and actions.\n- All assets are enqueued with dynamic versioning using `filemtime()`.\n- The block is registered as `visualizer-block/visualizer` with the title \"Particle Visualizer\" in the block editor.\n\n## Notes\n\n- The README previously referenced a filter `visualizer_block_default_attributes`, which does **not** exist in the codebase. For extensibility, use standard WordPress hooks or extend the `VisualizerBlock` class as needed.\n- The main frontend entry point is `src/core/visualizer.js` (not `src/visualizer.js`).\n- The main frontend container uses the class `visualizer-block-container`.\n- All architectural or extensibility changes should be reflected in this documentation immediately.\n\n## Browser Support\n\n- Chrome 60+\n- Firefox 55+\n- Safari 12+\n- Edge 79+\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n\n## License\n\nGPL v2 or later\n\n## Author\n\nCreated by Chris Huber (https://chubes.net)\n\n## Version\n\n1.0.0 \n\n## Recent Fixes\n\n### Audio Sync Collision Detection (Latest)\nFixed an issue where collision detection was inaccurate when audio sync was enabled:\n\n- **Problem**: Collision hitboxes used base particle size while rendering used audio-enlarged size\n- **Solution**: Enhanced collision detection to account for audio size multipliers\n- **Impact**: Collision detection now matches visual particle size during audio swelling\n- **Files modified**: `src/physics/collision-detector.js`\n\nThe collision detector now includes a `getEffectiveParticleSize()` method that applies the same audio size multiplier used in rendering, ensuring collision accuracy when particles swell with bass/volume.\n\n### Magnetic Burst Effects (New Feature)\nAdded dramatic cluster breakup effects when magnetism and audio sync are both enabled:\n\n- **Feature**: Audio spikes temporarily convert magnetism from attraction to repulsion with enhanced range and power\n- **Effect**: Creates explosive \"burst\" effects that break up magnetic clusters and scatter particles\n- **Trigger**: Volume spikes above 75% threshold with 1.5x volume increase over previous level\n- **Duration**: 400ms burst duration with 300ms cooldown between bursts\n- **Parameters**: \n  - **Range multiplier**: 2.5x normal magnetic range during burst\n  - **Power multiplier**: 3x normal magnetic strength during burst\n  - **Conversion**: Attraction becomes repulsion for dramatic scatter effect\n- **Files modified**: `src/audio/audio-effects.js`, `src/physics/physics-effects.js`\n\nThis creates a spectacular effect where tight magnetic clusters explode outward on music peaks, then reform as the burst fades, adding rhythmic drama to magnetism visualizations.\n\n### 3-Tier Magnetic Inversion System (Latest)\nReplaced simple magnetic bursts with a sophisticated tolerance-based inversion system:\n\n- **Concept**: Audio volume spikes dynamically adjust the attraction/repulsion \"tolerance level\"\n- **Effect**: Creates nuanced burst patterns where closer particles repel while distant ones still attract\n- **Enhanced Sensitivity**: 20% more responsive with lower thresholds and stronger effects\n- **3-Tier System**:\n  - **Tier 1 (55-65% volume)**: 36% tolerance reduction, 1.44x power boost - gentle burst effects\n  - **Tier 2 (65-75% volume)**: 72% tolerance reduction, 2.16x power boost - moderate cluster breakup  \n  - **Tier 3 (75%+ volume)**: 100% tolerance reduction, 3.0x power boost - dramatic explosions\n- **Smart Timing**: 420ms duration per tier, 160ms cooldown between tier changes\n- **Dynamic Range**: Each tier creates different visual patterns based on how close particles are\n- **Files modified**: `src/audio/audio-effects.js`, `src/physics/physics-effects.js`\n\nThis creates incredibly sophisticated burst effects where the intensity and pattern of cluster breakup varies smoothly with music dynamics, from subtle ripples to explosive scattering.\n\n## Performance Optimizations\n\n### Frame Rate Management\n- **Adaptive processing**: Audio, physics, and collision systems scale processing frequency based on particle count\n- **Smart batching**: Color and opacity-based particle rendering batches\n- **Early culling**: Distance and opacity thresholds prevent unnecessary calculations\n\n### Collision Detection\n- **Spatial partitioning**: O(n²) to O(n) collision detection optimization\n- **Forward neighbor checking**: Eliminates duplicate collision checks\n- **Audio-aware grid sizing**: Spatial grid adapts to audio-enlarged particle sizes\n\n### Audio Processing\n- **Efficient FFT**: 256-sample analysis for balance of resolution and performance\n- **Smoothed responses**: Prevents jarring visual changes\n- **Magnetism compatibility**: Audio effects adapt behavior when other physics are active\n\n## Architecture\n\n### Modular Design\n- `src/core/` - Main visualizer logic\n- `src/audio/` - Audio analysis and effects\n- `src/physics/` - Collision detection and physics\n- `src/rendering/` - Connection and particle rendering\n- `src/visual-effects/` - Color effects and visual enhancements\n- `src/interaction/` - Mouse and fullscreen management\n- `src/ui/` - Control center interface\n\n### Performance Philosophy\nBuilt on KISS (Keep It Simple, Stupid) and DRY (Don't Repeat Yourself) principles with aggressive performance optimization. All effects scale gracefully from low-end to high-end hardware.\n\n### Audio-Reactive Visualizations\n- **Real-time microphone analysis** with frequency separation (bass, mid, high)\n- **Audio-reactive color waves** with 128-color spectrum system\n- **Motion effects**: Beat detection, volume peaks, frequency-based turbulence\n- **Audio + collision integration**: Particle collision history offsets position in global audio wave\n- **Accurate collision detection**: Hitboxes match visual size when audio sync is enabled\n- **3-tier magnetic inversion**: Sophisticated volume-based tolerance adjustment creating nuanced burst patterns ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchubes4%2Fvisualizer-block","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchubes4%2Fvisualizer-block","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchubes4%2Fvisualizer-block/lists"}