-
Notifications
You must be signed in to change notification settings - Fork 0
01. Windows Quick‐Start
As of version 4.0.0, an install program is available on the release page. The installer can also update older versions or uninstall the current version.
The installer is the recommended approach for getting the application and content installed. It will download and install the app itself, visualization content, and if necessary, the .NET runtime. (Unlike earlier versions, no audio loopback libraries or third-party drivers are required.)
If you use the install program, that is ALL you really need to know. The wiki home page shows you how to test your setup.
The rest of this page explains manual installation and various optional features that might make your use of the program easier.
- A modern video card (or integrated GPU) that supports OpenGL API 4.5 (most non-Intel GPUs are OK)
- .NET 8 runtime or Visual Studio with the .NET 8 SDK
- Recommended: Monkey-Droid GUI
- For content creators: GLSL editor or Visual Studio extension
- Optional: Windows Terminal
- Optional: OpenSSH server and client (ships with Windows but inactive)
And of course, you will need a source of music such as Spotify or Soundcloud. Spotify has a decent native Windows client (download) which has the benefit that it allows remote-control of music playing through your PC from any other client on the same network -- such as your phone or a laptop.
If you are not a .NET developer, download and install the latest .NET version 8 runtime from Microsoft. You only need the basic runtime on the bottom right, not the Desktop or ASP.NET runtimes (although those will work). If you are a developer, the .NET 8 SDK is fine or any of the Visual Studio "workloads" that include the SDK. If you want to check whether .NET 8 is already installed, open a command-line window and type dotnet --info. If you get an error message or don't see any 8.x versions listed, you don't have it.
Run the installer (Windows x64 link at the bottom right):
Obviously, you need to install monkey-hi-hat itself. Download the manual-setup archive file, which contains two other archive files -- the app files, and content files. Create a directory and unzip the app files into it. Create another directory and unzip the content files there. (If you want to follow the installer standards, the app directory should be C:\Program Files\mhh and the content directory should be C:\ProgramData\mhh-content, but you will also have to deal with folder and file permissions, which the installer normally handles for you. Using these standard locations means future installers should be able to auto-update your installation.)
Now it's "installed" but you still must configure it. The configuration file is a plain text file you can read and edit with Notepad. It has many detailed comments to help you understand the settings. The recommendation is to copy mhh.conf from the application's ConfigFiles template directory to the app's top-level directory. Modify that top-level copy. At a minimum you have to change mhh.conf settings in the [windows] section to point to the content directories. Refer to comments in the config file and also the config wiki topic for more details.
If you're a programmer and you plan to create your own visualizations and effects, create a separate directory structure on your computer or your network for those files (your config file can point to both sets of directories). Using separate directories for your custom content makes it easier to update the "off the shelf" content with future releases. Your custom directory structure should look like this:
📂 x:\monkey-hi-hat-content
|--📂 fx
|--📂 libraries
|--📂 playlists
|--📂 shaders
|--📂 templates
+--📂 textures
The wiki documentation home page has a basic first-time walk-through, but usage is simple: open a command-line window, change to the install directory, and run mhh.exe. This loads the low-overhead "idle" visualizer. To send commands to the running instance, open another command-line window, change to the install directory, and run mhh --help to see the command-line help options. If you're using the sample content, start up some music and run the command mhh --playlist variety.
The program window recognizes several keyboard commands. Two of them are:
-
ESCends the program -
→loads the next playlist visualizer (right-arrow)
If you didn't change anything, at this point the program is running in a window. You can resize or maximize that window, but you probably want to open the mhh.conf configuration file and change the StartFullScreen setting to true. But then, unless you have multiple monitors, you can't use a second window to send commands (well, technically you could ALT-TAB between the two), and if you're running it remotely (for example, in your AV stack outputting to your TV), you don't want to be chained to the keyboard.
This is where remote control comes into play, which is covered in the next section.
Windows and Android users can install Monkey Droid, a simple dedicated GUI application for controlling monkey-hi-hat running on another computer. The Windows msix or the Android apk install packages are available on this repo's release v3.1.0 page. It's on that older release page because the Monkey Droid application is being rewritten.
The Monkey Hi Hat mhh.conf config file includes an UnsecuredPort setting. By default, port 50001 will be used, but you can use any open port you wish. The official TCP custom or "dynamic" port range is 49152 to 65535, which is your safest bet for avoiding collisions with other things running on your system.
Start Monkey Hi Hat, then launch Monkey Droid on the device of your choosing. Hit the +Add button at the top right of the Server List page. Enter the name of the computer where Monkey Hi Hat is running, enter the port number, and hit the Save button. After returning to the Server List page, choose the server you just defined, and choose the Use option from the pop-up. (You can also try the Test option just to verify network connectivity.)
Once a server is selected, you'll be sent to the Playlist page. It's initially empty, so ask the server what playlists are available: Hit the ↺Refresh button at the top right of the page. If you're using the content provided in the Volts Laboratory repo, you'll see at least one playlist named variety. Select that and Monkey Hi Hat will load and use that playlist.
The Visualizer tab works similarly. It's initially empty, so hit the ↺Refresh button at the top right. You can use this page to jump to any specific visualizer (shader). Note this will terminate the playlist, if one is active. Initially each entry will not have a description loaded. A background thread will read visualizer descriptions and whether or not they are audio-reactive (indicated by a music note icon).
The other tabs are self-explanatory. You can issue the other standard Monkey Hi Hat commands, or issue commands manually (which is useful for Monkey Hi Hat commands that haven't been added to Monkey Droid yet).
You can also control Monkey Hi Hat from an SSH terminal, which relies on named pipes instead of TCP network connections. Refer to the directions in the last section of this page for more details.
If you want to create or modify the visualization shaders, it's extremely useful to have an editor that "speaks" GLSL, the OpenGL Shader Language. There are probably plugins for popular editors like Notepad++ or (shudder) Visual Studio Code, but since I use the grown-up version of Visual Studio, I strongly recommend Daniel Scherzer's GLSL language integration extension.
This will recognize .vert, .frag, and .glsl filename extensions, and It Just Works. It's a pretty nice workflow to run Monkey Hi Hat on another monitor or off to the side in a window, and use Visual Studio to modify the shader, then just issue an mhh --reload command to immediately see the results.
This is completely unnecessary for using Monkey Hi Hat, but I thought I'd plug the new(ish) Windows Terminal application. This replaces the tired-old "DOS prompt" / CMD command-line, as well as the default Powershell command-line and more. I use it as my default everywhere I can, now, and can't recommend it strongly enough. Other than Visual Studio and .NET, I rarely have anything nice to say about Microsoft's software decisions any more, but they knocked it out of the park with Terminal.
You can even run shaders as the background... and Mr. Rånge has even made it relatively easy to install and configure.
Since you probably want to run Monkey Hi Hat full screen, and you might want to control it from your couch with a tablet, your phone, a laptop, or some other separate device, I recommend setting up SSH (Secure Shell). SSH is a remote-terminal protocol that has been used in the UNIX world for ages. Relatively recently, Microsoft finally got with the program and began shipping an SSH server and client, although they require a few extra steps to make them easier to use.
Important: The instructions below create a relatively insecure SSH setup. I trust everything inside my network, so I'm not concerned about this, but that's your decision and I accept no responsibility if Evil Chinese Hax0rs gain access to your secret hoard of hipster coffee blends, or whatever else is on your network. Secured key-based configuration is beyond the scope of this quick-start. Put on your big-boy pants and search the Interwebs, it's actually pretty easy to do.
The first step is to tell Windows you want to use OpenSSH Server and OpenSSH Client. From the Start menu, open Settings, click on Apps, click on Optional Features, and if you see OpenSSH Server and OpenSSH Client in this list, they're already installed and you're done. Otherwise, click (Win10) Add a feature , or (Win11) click the View features button on the Add an optional feature line. Choose the checkbox next to OpenSSH Server and/or OpenSSH Client, then click the (Win10) Install button, or (Win11) click the Next button then the Install button. The installer will take a minute or two to download and install the apps.
The next step is to make sure OpenSSH Server is always running. Open the Start menu and type Services and you should see the Services app show up. Click on it, then scroll down to find OpenSSH SSH Server. At the right, you'll probably see that startup mode is Manual and nothing in the status column, indicating it is not running. Double-click on it, and in the properties dialog, change Startup type to Automatic or Automatic (Delayed Start) (which lets Windows start more quickly), and under Service status click on the Start button, then click Ok and close the Services app.
Finally, you need to open port 22 on your computer's firewall so that it can receive SSH traffic. Open the Start menu and type "Firewall" and you should see Firewall & network protection pop up. Click on it, then click Advanced settings, which opens a Windows Defender dialog. Click Inbound Rules at the top left, then New Rule at the top right. The New Rule Wizard dialog opens. Click the Port option, then click the Next button. Keep the default TCP and Specific local ports options, and type 22 in the field next to Specific local ports, then click the Next button. Keep the default Allow the connection setting and click Next again. For monkey-hi-hat purposes, you most likely only want OpenSSH to respond on Private networks, so uncheck Domain and uncheck Public unless you intend to configure secure access. Finally, click Next again, enter OpenSSH Server as the firewall rule name, and click Finish. You can close the Windows Defender and Settings windows.
I also run ConnectBot on my Android phone. It's a little bit buggy, but it's free, it's actively maintained, and it doesn't harangue you with bullshit ads that you'll never intentionally click on.
You can test this from a computer running the SSH client, including locally on the same computer where Monkey Hi Hat and OpenSSH server is running. Open a command-line window and type ssh user@computer and press Enter. It will warn you that it can't positively identify the server and ask you if you wish to proceed. This looks and works differently with different clients. With OpenSSH Client on Windows, you'll have to type the word yes to proceed. Other clients may show a dialog, or prompt for the Y key etc. Then you'll be prompted for the password. On Windows, you may have to alter your user login to accept a password, particularly if you're using a "Microsoft account" and/or the Windows Hello PIN, rather than a simple local account. These steps are beyond the scope of this Quick Start, but it's pretty easy to find more details online.