October 22, 2007 10:22 am - PCE, tech

Chiptune Tutorial: PC Engine music via HuSIC on Mac OS X

HuSIC is a version of the well-known ppmckc MML compiler that's been customized to produce music for the PC Engine/Turbo Grafx-16's sound hardware instead of the NES/Famicom. I've had a request for a tutorial on getting HuSIC working on Mac OS X. Thanks to some fantastic tools by boukichi, the process is easier than it used to be, but tracking down all the relevant pieces and configuring them can be a hassle. So, I sat down to lay out how to get everything up and running. This is a first draft, so if anything is unclear or just doesn't work, let me know and I'll fix it up.


  1. Download the latest version of HuSIC (mirror) and extract it somewhere sensible, like, say, your home directory (for example, /Users/your name/husic026osx).

  2. Download ezMML (mirror), extract the archive, and copy it into your Applications folder.

  3. Open up the songs folder in your HuSIC folder, and open the script named make_hes.sh. This is the script that will take your MML text file and eventually spit out a complete HES music file. You'll notice a lot of relative paths in the script. These will have to be changed to absolute paths in order for the script to work with ezMML. To fix this, you can download my custom make_hes.sh and replace the existing file in the songs directory.

  4. Open up this new script and look for the line that says export HUSIC="/Users/your name/husic026osx". Change the path in this line to point to the folder where you placed HuSIC.

  5. The last line of my custom script will open the generated HES file in whatever player you have associated with HES files. Recent builds of the all-around lovely multi-format music player Cog support HES, so I recommend grabbing that.

  6. To associate your HES files with Cog, right-click on any given HES file, click Get Info, select Cog from the Open With drop-down box, click Change All, and then click Continue when the confirmation dialog comes up.

  7. Finally, you need to configure ezMML to use your custom make_hes.sh and run HuSIC. Start ezMML and open the Preferences menu. You'll see a dialog that looks like this:

    In the config name field, enter HuSIC (HES). Click the "..." box next to the filename field and browse to the custom make_hes.sh script that you've configured. Click the Add button, and then click OK.


  8. Finally, once you've got a masterpiece MML composition ready to go, pull down the box that says ppmck (Internal) and select HuSIC (HES). Click Compile and you're off and running!


If you're looking to start from the beginning at composing for the PC Engine, you can take a look at Neonemypr's Ultimate PPMCK Reference and Tutorial, which is focused on MML coding for NES/Famicom, but the vast majority of the commands will work in HuSIC. For a list of the additional commands you'll need to use (especially the @WTxx wavetable definitions), open up hmckc.txt in the docs folder of your HuSIC folder. For some example HuSIC MML code, you can check out Rophon's site or Zero.

Posted by trevor w.