Euterpea is a cross-platform, domain-specific language for computer music applications embedded in the Haskell programming language. Euterpea is a wide-spectrum language, suitable for high-level music representation, algorithmic composition, music analysis, working with MIDI, low-level audio processing, sound synthesis, and virtual instrument design.
- OS: Windows 7+, OS X 10.12+, some Linux distributions (requires ALSA)
- Recommended GHC versions: 8.2.x – 8.6.3
- Usually compatible up through GHC 8.10.x (see installation details below)
If you already have GHC but it’s outside any of the ranges listed above, Euterpea may still work – give it a try before installing a different version.
Getting Started with Euterpea
Here’s what you need to do to install Euterpea for the first time and play your first note in four general steps: installing Haskell, installing Euterpea, setting up a synthesizer, and installing HSoM.
Step 1: Install Haskell
Install Haskell for your operating system. Ideally use one of the GHC versions listed at the top of the page.
Linux users: you must install ALSA (ex: sudo apt-get install libasound2-dev)
Step 2: Install Euterpea
Download or clone the Euterpea2 repository on GitHub. If downloading as a ZIP file, unzip it. Open a command prompt (Windows) or terminal (Mac/Linux) and cd into the repository folder where the euterpea.cabal file is located. Run the following:
cabal v1-update cabal v1-install
Newer GHC version users: If your GHC version is newer than 8.6.x and the above install command doesn’t work, try using this extra flag:
cabal v1-install --allow-newer
Older version users: if the v1-style commands are not recognized, try simply “cabal update” and “cabal install.” (Be aware that Euterpea is unlikely to work on GHC versions <8.0.x)
If you can’t get Euterpea to install with the commands listed here, check the troubleshooting page.
Step 3: Setup a Synth and Test Euterpea
Mac/Linux users: install a MIDI software synthesizer, such as SimpleSynth or Fluidsynth. Make sure it’s running before you start Euterpea in GHCi.
Windows users typically will already have a synth installed and can simply move on to testing Euterpea with GHCi.
Open a command prompt, powershell, or terminal and run the following commands.
play $ c 4 qn
You should hear a note play if your synth is configured correctly.
Step 4: Install HSoM (Optional)
If you also want HSoM, which is the companion library for the Haskell School of Music textbook, you can install it similarly to Euterpea. Download/clone the the HSoM repository on GitHub, cd into the repository folder, and run the cabal v1-install command as you did for Euterpea.
Mac users: to use HSoM’s musical user interfaces (MUIs), you must compile to executable rather than using the interpreter. There’s an example of how to do this on the Compiling to Executable page.
Now you’re ready to head to the Tutorials and Examples pages to learn about how to use Euterpea and try out some existing code. Once you’re ready to start building your own programs with Euterpea, head to the API Documentation for more information on Euterpea’s features.
Having installation trouble or don’t hear any sound?
Check out the Troubleshooting page for a list of solutions for common problems organized by OS and category. For sound-related problems, you can also check out the Setting up MIDI page.
Looking for a text editor to use with Haskell & Euterpea?
Here are some suggestions:
- Notepad++ (Windows only)
- Atom with a Haskell plugin (Windows/Mac/Linux)
- Or check out this extensive list of editor options.
Please send questions and comments related to Euterpea to Donya Quick (but please read the FAQ below first to see if your question is answered there). Donya Quick is the current maintainer of the Euterpea and HSoM libraries.
- Is there a textbook corresponding to Euterpea? Yes, The Haskell School of Music is a textbook by Paul Hudak and Donya Quick that is about Euterpea.
- Is Euterpea still under development? No. Euterpea won’t be changed or added to except for possible future compatibility and/or bug fixes that do not affect its functionality.
- Can I contribute to Euterpea? No. Euterpea is open-source but not open to community contributions. However, you are free to do what you want with your own local copy. You can also fork the repository and build on it under your own account.
- I found a bug or am having installation trouble with Euterpea/HSoM; how do I get help? First check the Troubleshooting page. Next, check the issues page for the repository to see if it’s a known issue with a solution. If it’s something new, you can either email the Euterpea maintainer (Donya Quick) or create a new issue post. Do not use the pull requests feature on github to propose solutions (pull requests are ignored).
- I’m having trouble installing Haskell/GHC; where can I get help? The installation process for Haskell has changed a lot in the last few years, having switched from all-in-one installers to version managers (Chocolatey, GHCup, etc.). Your best bet is to contact the maintainers of the particular version manager you’re using to install GHC.
- Who created Euterpea? Euterpea was created by Paul Hudak and the Yale Haskell Group (which no longer exists). The library is currently maintained by Donya Quick, who started helping with it in 2008 and became the primary maintainer in 2015.