Nisualizer

This project aims to combine music visualizers, such as GLava and Cava, with wallpaper engines, such as Wallpaper Engine and Lively, and bring them to the next level.
A simple example can be found here.

Showcase

Snowstorm

Chaotic Cubes

Features

• Lightweight
• Simple and Powerful JSON Config
• Live Config Reload
• System Fonts
• Digital Clock

Roadmap

• Add config and cli arguments for setting the display
• Launch on startup
• Arguments(e.g. using different configs for 2 displays)
• Change the config directory for Windows(and their shit system structure)
• Implement system font support on Windows
• Polish sending window to the background layer on windows
• Implement configurable paths for the file system watcher used in live config reload
• Config volume profile
• Slideshow
• Build more commands into the app itself(e.g. wttr.in, now playing etc.)
• Completely modularize components such as vfx graphs etc.
• JSON variables(to reduce code duplication)
• Font materials
• Picking up system audio on Windows
• Picking up system audio on Linux
• Music Reactive Particle System
• Music Reactive VFX Graph
• Music Reactive Volume
• Clock, Date and Day
• Background From Local Files
• Live Reload JSON Config
• Custom Fonts
• Multiple Scenes
• Per Scene Config
• Automatic Scene Creation
• Dynamic Text(Weather, DateTime, FPS, Shell etc.)
• Modular UI
• Media Info(via Player CTL)
• Sourcing other files in config

Usage

Nisualizer is ready to use out of the box with very little setup, and the option of cloning/forking and making your own scenes.
Thanks to the modularity of components, creating your own backgrounds should be relatively easy, more can be read in Extending Nisualizer.

Requirements

Linux Requirements

1. Window Wrapper, to send Nisualizer to the background layer, such as:
   • hyprwinwrap - Hyprland
   • xwinwrap - most X desktop environments
     
2. pipewire-pulse or Pulse Audio, so Nisualizer can capture audio

Windows Requirements

1. Lively(optional), an alternative way to send Nisualizer to the background layer

Setup

Linux Setup

1. Download Nisualizer
2. Configure the window wrapper of your choice, e.g. hyprwinwrap:
   • Follow the official plugins guide for Hyprland
   • Add the following to your Hyprland config:

     plugin {
         hyprwinwrap {
             class = Nisualizer.x86_64
         }
     }
     

3. Launch Nisualizer to generate the default config
4. Configure Nisualizer
5. Make Nisualizer launch on startup(native implementation is WIP), e.g. with Hyprland:

   exec-once = Path/To/Nisualizer.x86_64
   

Windows Setup

1. Download Nisualizer
2. Launch Nisualizer to generate the default config
3. Configure Nisualizer
4. Make Nisualizer launch on startup(native implementation is WIP)

Configuration

WIP

FAQ

1. Do you plan to support Mac?
   • Fuck no, you are free to make a PR tho.
2. How's the performance?
   • It depends on your config. Nisualizer is just a Unity application with only necessary objects in the scene, you add the rest via config. It shouldn't be any more demanding than WPE whilst achieving way more.
3. Can I fork this project and make my own visualizer?
   • Absolutely, I am really interested to see what the community is capable of creating. After all, there are much more skilled artists and developers than me out there. You are also welcome to make a PR to get your scene merged into the master branch.

How Nisualizer Works

Nisualizer is just a Unity application that captures system audio and reacts to it. It supports pipewire-pulse/Pulse Audio(Linux) and Windows Core Audio(Windows, most of the code was taken from NAudio). TODO: Explain how it sends itself to the background layer Nisualizer utilizes simple JSON configuration with some additional features, such as comments, sourcing other files etc.

Extending Nisualizer

Nisualizer is built on top of modular components and utilities, allowing anyone to expand it with minimal effort.

Contributing

If you've made something that would fit into the actual project, feel free to make a pull request and I'll merge it if I like it. Have fun!

Contributing Instructions

1. Make a fork of Nisualizer
2. Clone the fork recursively git clone --recurse https://github.com/YourName/Nisualizer
3. Make changes
4. Create a PR with a detailed description of your contribution

Creating Scenes

Automatic(Recommended)

Assets -> Create -> Nisualizer Scene

Manual(Outdated, painful and prone to changes)

1. Create a new directory under Assets/Scenes/
2. Give it an original, descriptive name, e.g. Snowstorm
3. Add a new scene with the same name as the directory
4. Create a new script that derives from the SceneScript and call it SceneNameManager, e.g. SnowstormManager
5. Add a new object to your scene, name it SceneNameManager, e.g. SnowstormManager, and attach the previously created script
6. Create a SceneNameConfig.json file in your scene directory, e.g. SnowstormConfig.json, this will be your default scene config
7. Make a new script in your scene directory and call it SceneNameConfigData, e.g. SnowstormConfigData, that inherits from the ConfigData class, this class is used as a container to store values from your JSON config
8. Create a new scriptable object menu item by adding the following above the class name [CreateAssetMenu(fileName = "SceneNameConfigData", menuName = "Config/SceneNameConfigData")]
9. Create a new instance of this scriptable object
10. Attach all the components to the ConfigScript under your SceneManager, and make sure that the ConfigName value matches your scene name, scene loading won't work otherwise
11. Drag the GameManager prefab to your scene so you can start the playmode directly from your scene without any issues
12. Make sure you added your scene to the build settings
13. Utilize powerful scripts built with modularity in mind, such as InteractiveVFX, InteractiveVolume etc.