User Guide

How do I run this?

Want to know how install Cacophony? Read this.

On Windows and MacOS, just double-click the app.

On Linux, you can't launch Cacophony by double-clicking the app. I don't know why. Sorry. To run Cacophony, open a terminal, type each of these, press enter each time:

1. cd path_to/cacophony (replace path_to with the actual path)
2. ./cacophony

What even is this?

Cacophony is an terminal-esque MIDI sequencer. By "terminal-esque" I mean that it looks like a terminal shell and doesn't support mouse input. By "MIDI sequencer" I mean that the music you're going to make is defined by MIDI messages.

You aren't going to record audio. You going to input MIDI messages which will be processed when the music plays or is exported. A MIDI message is several numbers that a synthesizer or computer program interprets as messages. How they interpret these messages is up to them, though there is a MIDI standard that everyone is supposed to follow. In Cacophony, MIDI messages can be interpreted as note-on/off events or to control the app.

In Cacophony, music is divided into tracks, and tracks are divided into notes. A note is a discrete pitch, volume, start time, and duration. A note is *not* audio. It's just some data that will tell the app how to generate audio.

Every track needs a SoundFont in order to convert notes to audio. A SoundFont is a file with instruments, called "presets", that are divided into "banks". A SoundFont can take a MIDI event (or a Cacophony note, which is essentially the same thing) and use that to "render" audio.

To use Cacophony, you need to first download at least one SoundFont. I like this site. Move the .sf2 file you just downloaded to Documents/cacophony/soundfonts/

When you save your music, the save file will include the music/track/note data (similar to a .mid) file, along with the filepaths to the SoundFonts you've assigned to each track and some other data too.

How do I do anything?

You can only use your MIDI controller and your qwerty keyboard. You can't use your mouse.

There aren't any tooltips because that would go against Cacophony's design principles. Instead, you've got Casey the Cacodemon, who I've hooked up to your computer's text-to-speech engine. Press F1, F2, F3, or F4 and Casey will tell you what to do.

Before doing anything else, I recommend pressing F3 to get an overview of the app and F4 to learn how to save, export, etc. You'll use F1 and F2 often; they're contextual and they'll tell you how to use the panel or widget you've selected, *what* it is you've selected, etc.

The best way to use Cacophony is to listen to Casey and gradually learn the controls.

If you want to get started right away, try this: First, download a SoundFont and move it to the directory, like I recommended in the previous section. Then launch Cacophony and do this:

1. PageUp Cycle to the Tracks Panel
2. = Add a new track
3. Return Show the open-file dialogue to load a SoundFont
4. Return Select the SoundFont
5. PageUp Cycle to the Piano Roll Panel
6. Return Arm the track
7. Play notes with your MIDI controller or your qwerty keyboard. Not sure how? Press F2 to ask Casey.

I'm going to given you a few more useful pointers but I'm not going to tell you the controls. Ask Casey.

Cacophony lets you add notes whenever you want and doesn't support live recording; it won't do anything until you enter a new note. You can set the next note's duration. To add silence between notes, go to Time and move the cursor. The cursor defines where the next note starts.

Cacophony has several volume controls. The Music Panel has an overall gain value. Each track has its own gain value. When you input notes, you can either use the velocity value from messages originating from a MIDI controller or you can manually set the volume of the next note.

When you like how it sounds, you can export your music to wav, ogg, mp3, or mid. You can export each track separately if you want.

Cacophony's interface can be controlled from a MIDI controller. By default, the tooltips are for my own MPK Mini III. More on this in a moment:

Can I customize Cacophony?

Cacophony's font, color scheme, every keyboard binding, and lots of other settings, are in a config file. To edit the config file, first copy it from cacophony/data/config.ini to Documents/cacophony/config.ini (the app will always prefer the one in Documents/ if it exists). Feel free to experiment with editing the file. If you mess up you can always copy+paste the default file again.

For MIDI bindings to work correctly, your MIDI controller needs to support Inc/Dec input, e.g. the values are always 1 or 127. Sorry, I know that's weird, but it makes it a lot easier to support input that is meant to wrap around values (e.g. cycling around panels). For my own controller, I used the MPK Mini III Program Editor to set each knob to be Inc/Dec.

Command line arguments

If you launch Cacophony from the terminal, you can add the path of a save file to open it at launch: ./cacophony ~/Documents/cacophony/saves/my_music.cac

You can set the data directory as an environment variable. This is useful if you're on Linux and you don't want to cd cacophony to run the app:

For example: export CACOPHONY_DATA_DIR=~/cacophony/data && ./~/cacophony/cacophony

Or, you can do this: ./~/cacophony/cacophony --data_directory ~/cacophony/data

To enable fullscreen, you can edit the config file or do this:

export CACOPHONY_FULLSCREEN=1 && ./cacophony or ./cacophony --fullscreen

What if I still need help?

Ask Casey for help whenever you get stuck.

Oh, you want help from a *human*?? In *this* economy??

Well, fine. If you want to report a bug, the best way to do so is to create a GitHub Issue. You can also join the Discord and ask for help.