The quickest way to get started is to install the TidalCycles pattern engine, the SuperDirt synthesiser and the Atom editor. You’ll need all three, although there are alternatives to using SuperDirt and Atom - see later in the document for info.

All software is free of charge, and distributed according to free software/open source principles and licenses.

Installing TidalCycles

The following installation instructions work for Linux, MacOS and Windows.

There is an automated script for MacOS X users, along with a helpful walkthrough video, as an alternative to the below.

Pre-requisites

You first need to install the following three pieces of software, Haskell, Atom, and SuperCollider. You can download them from their websites - click on each of the below:

For the curious: Haskell is the programming language that TidalCycles is written in, Atom is a programmers’ editor that you will use to write TidalCycles patterns in, and SuperCollider will make all the noise, by hosting the SuperDirt synth that was made for TidalCycles. Git is a program that lets your computer retrieve the source code for SuperDirt for use in SuperCollider.

If you are installing on Windows, make sure you follow Step 3 of the Haskell installation instructions. Also on Windows, when installing SuperCollider, you must also download the sc3-plugins zip file. Run SuperCollider once in order to create user directories. Then open the zip file and extract the SC3plugins directory to C:\Users\<username>\AppData\Local\SuperCollider\Extensions. You may have to manually create the Extensions directory. Restart SuperCollider so that it finds the SC3plugins directory.

If you are installing on Linux or Mac you need the SuperCollider sc3-plugins for using many of the synths included in SuperDirt. Most of the examples in the documentation will still work, so you could skip this step and return to it later. You can either install the latest version from github according to the instructions there, or if you are using Linux, you may find it in your package manager. On Fedora the package is called supercollider-sc3-plugins.

Once you have the above applications downloaded and installed, you will need to follow the following three steps to complete the installation:

1. Install the TidalCycles pattern engine

Open a Terminal window and type in the following command, to install TidalCycles:

cabal install tidal

If you’re unsure how to open a terminal window: in Windows it’s “command prompt” under accessories, in Mac OS it’s “Terminal” under Utilities, Linux varies according to distribution but generally find “Terminal” in the menus).

2. Install the SuperDirt synth

Start SuperCollider, and in the editor window paste in the following line of code:

include("SuperDirt")

Run the code by clicking on it, to make sure the cursor is on this line, then hold down shift and press enter.

It will download SuperDirt and you will see it has completed when the Post Window displays:

... the class library may have to be recompiled.
-> SuperDirt

After it has completed, you will need to restart SuperCollider (or alternatively, recompile the class library via the “Language” menu).

If you instead see a message like this:

  "ERROR: Quarks requires git to be installed"

Then you will need install git from https://git-scm.com/downloads, and return to SuperCollider to run include("SuperDirt") again.

3. Install the TidalCycles Atom plugin

Start Atom, and install the TidalCycles plugin. You can find it via the menus under edit > settings > install, then typing “tidalcycles” into the search box. Once that’s installed, restart atom.

That’s it! You’re now ready to start TidalCycles and SuperDirt for the first time.

Running TidalCycles

There are two steps to starting TidalCycles each time, first starting SuperDirt inside SuperCollider, and then starting TidalCycles inside Atom.

To start SuperDirt, paste the following code into a SuperCollider window, click on the code, hold down shift and press enter.

SuperDirt.start

To start TidalCycles in Atom, first create a new document and save it with a filename that ends in .tidal, e.g. test.tidal. Then open the Packages menu and select TidalCycles -> Boot TidalCycles. A small window will open at the bottom of the window and display some text to tell you that the GHCi interpreter is running. Try running a simple pattern by typing in the code below and holding down shift and pressing enter to evaluate it (Holding down control and pressing enter will also work, this evaluates multiple lines).

d1 $ sound "bd sn"

If you hear sound, congratulations! Time to move on to the tutorial.

If you get stuck, you are very welcome to ask questions and share problems on the forum, or on the #tidal channel of the TOPLAP slack.

As is common with free software, you have alternative choices for the different components that make up a TidalCycles system. Atom and SuperDirt might be all you ever need, but read on if you want to learn what other editors and synths you can use.

Alternative editors

If you prefer using another editor (rather installing Atom as described above), you can try one of the following.

Sublime Text

Sublime Text is a popular cross-platform text editor. It is closed source and costs 70 USD.

To do live coding in Sublime Text, install the package Sublime REPL via Package Control.

To avoid fiddling with the existing Haskell REPL supplied by Sublime REPL simply clone this modified version of it:

cd ~/Library/Application Support/Sublime Text 3/Packages/SublimeREPL/config
git clone https://gist.github.com/lvm/e0943b0d42507af60eee174ed263adde Tidal

If you are using classic Dirt rather than the new SuperDirt, an older version of the config can be used:

cd ~/Library/Application Support/Sublime Text 3/Packages/SublimeREPL/config
git clone https://gist.github.com/lennart/8b811cd4f568f7d7100e Tidal

This way, cmd+shift+p > “Sublime REPL: Tidal” will load up a ghci instance that loads Tidal, binds dirt channels and adds macros for hush and cps.

Splitting windows beforehand (e.g. cmd+alt+shift+2 for two row layout) will load the REPL into the other splitscreen, so you can code in one and evaluate into the other.

Code by line evaluation is mapped to ctrl+, l by default but this can be customized to what you prefer:

{ "keys": ["shift+enter"], "command": "repl_transfer_current", "args": {"scope": "lines"} }

If you get the error Cannot find REPL for 'plain', try renaming your file to .hs instead of .tidal, since we are using a modified version of a Haskell REPL.

Of course you have to make sure dirt is already running when you can hear any sound.

Emacs

Emacs is a classic programmer’s editor, very well developed but a little difficult to use at first. For a while Emacs was the only editor that worked with Tidal, but if you’re not feeling confident, you may wish to try the Atom editor instead, using the instructions above.

Emacs under Linux

Debian, Ubuntu and Linux Mint users can install emacs, along with its haskell front-end, this way:

sudo apt-get install emacs24 haskell-mode

To install the emacs interface to tidal, you’ll need to edit a configuration file in your home folder called .emacs. If it doesn’t exist, create it. Then, add the following, replacing ~/projects/tidal with the location of the tidal.el file.

(add-to-list 'load-path "~/projects/tidal")
(require 'haskell-mode)
(require 'tidal)

If tidal.el did not come with this document, you can grab it here: https://raw.github.com/yaxu/Tidal/master/tidal.el

Now see under ‘Testing, testing’ below to check everything is working.

Emacs under Mac OS

Install emacs, and make it appear in your applications folder:

brew install emacs --cocoa
brew linkapps

Ok now time to configure emacs.. Do the following:

mkdir ~/tidal
cd ~/tidal
curl -L https://raw.githubusercontent.com/yaxu/Tidal/master/tidal.el > tidal.el

Then create a file in your home folder called .emacs (unless it exists already), then open the file in a text editor and insert the following lines:

(require 'package)
(add-to-list 'package-archives 
    '("marmalade" .
      "http://marmalade-repo.org/packages/"))
(package-initialize)
(setq load-path (cons "~/tidal/" load-path))
(require 'tidal)
(setq tidal-interpreter "/usr/local/bin/ghci")

The above ensures that emacs has access to the extensions in the ‘marmalade’ repository (in particular, haskell-mode), that the tidal.el file you downloaded earlier is is loaded, and that tidal can find the haskell interpreter.

Note: If you have already installed Haskell using the Haskell Platform installer, make the following change to the above:

(setq tidal-interpreter "/usr/bin/ghci")

Now start emacs (or if it’s already loaded, restart it to make sure .emacs is read), it should be in your Applications folder (if you start it from the terminal it’ll probably load an old version). Once emacs has started, press alt-x (i.e. hold down alt while pressing x) and type:

package-refresh-contents

Then do alt-x again and type:

package-install

and then:

haskell-mode

Now see under ‘Testing, testing’ below to check everything is working.

Emacs under Windows

Download Emacs for Windows from http://ftp.gnu.org/gnu/emacs/windows/. Extract the zip file, then simply run Emacs from bin\runemacs.exe.

Next you will need to find or create the .emacs file located in your home directory. This is the Emacs config file. Your exact location may vary depending on how Emacs is installed/run.

  1. If you run runemacs.exe by double-clicking on it, then your .emacs file will probably be located at C:\Users\<username>\AppData\Roaming\.
  2. If you put the runemacs.exe folder on your path and run it from a command prompt, then your .emacs file will probably be located at c:\users\<username>\

Be aware of how you started runemacs.exe, and create the .emacs in the appropriate folder if it does not exist already.

Alternately, you can try to have Emacs create the .emacs file for you automatically by changing a config setting from one of the Emacs menus and saving your configuration.

Haskell-mode needs to be installed in Emacs. The easiest way to do this in Windows is add the Marmalade package manager in Emacs. There are other ways to install haskell-mode (detailed at https://github.com/haskell/haskell-mode), but Marmalade is probably easiest.

Enable Marmalade by adding this to your .emacs file:

(require 'package)
(add-to-list 'package-archives
             '("marmalade" . "http://marmalade-repo.org/packages/"))
(package-initialize)

Refresh the package index by M-x package-refresh-contents. Then install haskell-mode via M-x package-install [RET] haskell-mode.

Note the M-x key combination is alt-x in Windows.

In .emacs add this to enable Tidal:

(add-to-list 'load-path "c:/projects/tidal")
  (require 'haskell-mode)
  (require 'tidal)

… but replace c:/projects/tidal with the path to the folder that contains tidal.el. tidal.el can be obtained from the Tidal repository, at https://github.com/yaxu/Tidal. The easiest way to use it is to clone the Tidal repository and modify the .emacs file to use the path where you cloned it:

git clone https://github.com/yaxu/Tidal c:\tidal

then:

(add-to-list 'load-path "c:/tidal")
  (require 'haskell-mode)
  (require 'tidal)

Now see under ‘Testing, testing’ below to check everything is working.

Testing, testing…

Now start emacs, and open a new file called something like “helloworld.tidal”. Once the file is opened, you still have to start tidal, you do that by typing Ctrl-C then Ctrl-S.

To check everything is working, type the following line, then type Ctrl-Enter:

d1 $ brak $ sound "bd sn/2"

All being well you’ll hear a bass drum and a kick, and can progress to the ‘patterns’ menu to start learning Tidal.

Vim

Installation instructions for the Vim editor have not yet been integrated into the documentation, but you can find details in this forum thread.

Alternative synths

SuperDirt allows you to trigger and granulate samples, and apply a range of effects, as well as trigger SuperCollider synths. However there are alternatives.

One is MIDI software and hardware synths, see the “howto” page for info.

It’s also possible to use TidalCycles to send custom Open Sound Control (OSC) messages. This is not currently documented, but ask in the forum or chat system for info, it’s not too tricky.

Another alternative is “classic dirt” - the native sampler that SuperDirt is based upon. It does not have all the effects that SuperDirt has, but has its own character, and is more efficient, so ideal for running on older hardware or “single board computers” such as the Raspberry PI. You can find installation instructions for Dirt in its github repository.