HanabiSync 🎆🔊

Turn your music into fireworks.
HanabiSync is an open-source project featuring a Python-based audio analysis tool that generates synchronized firework cue maps from any song or audio track, and an optional web-based visualizer to bring those cues to life.

Perfect for backyard firework shows, synced holiday displays, creating music videos, or just nerding out with music-reactive explosions.

---

🚀 What It Does

HanabiSync has two main components that work together:

1. Python Audio Analyzer (src/hanabi.py):

   • This intelligent script listens to your audio file and figures out the best moments for fireworks. It identifies things like beats, loud parts, and sudden changes in sound.
   • You can choose different Profiles (balanced, noisy, quiet) to tell it how sensitive to be, making it work well for various types of music or audio environments.
   • It then generates a detailed, timestamped "cue map" (a JSON file) that lists exactly when and what kind of firework effect should happen. This file is like a blueprint for your show.
   • This cue file can be used with our included web visualizer, or you can even use it to control real firework systems with a microcontroller or Raspberry Pi!

2. Web Visualizer (hanabiVisualizer/): (Optional)

   • This is where your cue map comes to life! It's a simple web page that plays your audio alongside dynamic firework animations, perfectly synced to the cues generated by the Python tool.

---

✨ Web Visualizer (hanabiVisualizer/)

Bring your generated cues to life! The web visualizer (open hanabiVisualizer/index.html in a browser) offers:

• Easy File Loading: Pick your original audio file and the _cues_<profile_name>.json file generated by the Python script.
• Synchronized Playback: Audio playback is tightly synced with firework animations.
• Dynamic Firework Animations:
  • Unique particle effects, colors, and behaviors for each firework type.
  • A special background pulsing effect for bass_pulse cues.
  • Fireworks are rendered on an HTML5 Canvas.
• Playback Controls: Play, pause, stop, and a seekable progress bar.
• Real-time Log: See which cues are being triggered and when.

---

🔧 Getting Started / How to Use

1. Generate Cues (Python)

• Prerequisites:
  • Python 3.x
  • Pip (Python package installer)
  • ffmpeg (a tool often required by the underlying audio library Librosa for MP3s and other compressed audio formats – ensure it's installed and accessible in your system's PATH).
• Setup:
  1. Clone this repository: git clone https://github.com/your-username/HanabiSync.git (Replace with your actual repo URL if forked)
  2. Navigate to the project directory: cd HanabiSync
  3. Install Python dependencies: pip install librosa numpy
• Run the Analyzer:
  • To analyze a specific audio file with a chosen profile (e.g., noisy):

    python src/hanabi.py -f path/to/your/audio.mp3 --profile noisy

  • Available profiles: balanced (default), noisy, quiet.
  • If no file is specified with -f, the script will look for the first compatible audio file in an audio/ directory in the project root (create audio/ if it doesn't exist, and place your audio file there).

    python src/hanabi.py --profile balanced 

• Output:
  • A JSON cue file (e.g., my_song_cues_noisy.json) will be saved in an output/ directory in the project root. This file contains all the generated cues and basic audio details.
  • Detailed processing logs will be printed to the console.

2. Visualize Your Show (Web)

1. Open the hanabiVisualizer/index.html file in a modern web browser (e.g., Chrome, Firefox, Edge).
2. Using the file input controls on the page:
   • Load your original audio file.
   • Load the _cues_<profile_name>.json file generated in the previous step (e.g., my_song_cues_noisy.json).
3. Once both files are loaded, the "Play" button will become active.
4. Click "Play" and enjoy your music-synchronized firework display!

---

🎆 Firework Types & Visuals (Default in Web Visualizer)

The Python script identifies distinct audio events and maps them to firework types. The web visualizer then renders them with default effects:

• mid_burst:
  • Audio Trigger: Typically associated with general energy on musical beats with mid-range frequency content.
  • Visuals: Bursts of red/orange particles with a moderate lifespan.
• high_sparkle:
  • Audio Trigger: Caused by energetic beats characterized by bright, high-frequency sounds.
  • Visuals: Cascading gold/yellow sparkling particles with a longer duration.
• kick_boom:
  • Audio Trigger: Fired by strong, impactful onsets like kick drums or impactful rhythmic hits.
  • Visuals: Intense purple/violet particle explosions, short but impactful.
• bass_pulse:
  • Audio Trigger: Triggered by deep bass frequencies detected during onsets.
  • Visuals: A rhythmic pulse of deep color in the background of the visualizer (e.g., deep purples, blues).
• comet_tail:
  • Audio Trigger: Generated by sharp, quick accents in the music that show a rapid change in spectral content.
  • Visuals: Streaking light blue/white particles with visible trails, simulating a comet.

Note: The visualizer's legend in index.html provides a quick reference for these types as well.

---

💡 Ideas & Roadmap

• [✔️] Web version using JavaScript + WebAudio API for visualization.
• [✔️] Profile-based parameter tuning (via CLI args for Python script).
• Advanced Timeline Editor/GUI: A web-based or desktop interface for manually adjusting, adding, or removing cues generated by the Python script.
• Export cue maps in multiple formats (e.g., CSV, FSEQ for xLights/Vixen).
• More advanced parameter tuning for Python script (e.g., via a dedicated config file).
• More customization options for web visualizer (e.g., user-defined colors, particle effects, background choices).

---

🧠 For the Curious: How it All Works (The Nerd Out Section)

Want to dive deeper into the audio analysis algorithms, dynamic thresholds, and the nitty-gritty of how HanabiSync figures out those firework cues? We've got a dedicated document for you:

Deep Dive into HanabiSync's Audio Analysis