Skip to content
TidalCycles
Blog

Installation

As mentioned in the Introduction, TidalCycles consists of a stack of components. Specifically, the stack contains, from the bottom up:

  1. SuperCollider, the backend audio server that makes the sound, with the additional SC3 plugins;
  2. SuperDirt, the sample library and synth engine used by Tidal, installed in SuperCollider;
  3. the Tidal pattern engine (TidalCycles itself), which runs on the Haskell Language (usually installed with ghcup), and which can be installed through cabal, Haskell’s package manager;
  4. and a code editor such as Pulsar, which talks to Tidal via a plugin.

On this page you will find guides for building up this stack for Linux, macOS, and Windows. This can possibly be done automatically, so use whichever method suits your situation best. Don’t be afraid to reach out for help via the community if you get stuck!

Install the components

Automatic installation

On Linux, you can use the Ansible playbook by Bernard Gray. For more information, see the linked repository, as well as the Tidal Club thread.

There is also a Nix flake by @mitchmindtree that you can use.

Manual installation

Most modern distros will have all or most of the components of a Tidal installation available via their respective package managers.

  1. Preparation

    First, make sure your user is a a member of the audio group:

    Terminal window
    sudo usermod -a -G audio $USER

    Logout and log back in for it to take effect. You can check if it worked with:

    Terminal window
    groups | grep audio

    Next, install the necessary dependencies.

    Terminal window
    sudo apt update && sudo apt install \
      git jackd2 qjackctl zlib1g-dev gcc g++ ghc cabal-install

  2. Install SuperCollider and the SC3-Plugins

    Terminal window
      sudo apt install supercollider sc3-{plugins,plugins-language,plugins-server}

  3. SuperDirt Installation

    SuperDirt is a plugin or “Quark” for SuperCollider, and functions as the audio engine for TidalCycles. It also provides the default set of samples.

    Get the version number of the latest SuperDirt release by checking the GitHub releases page or by running

    Terminal window
    git ls-remote https://github.com/musikinformatik/SuperDirt.git | grep tags | tail -n1 | awk -F/ '{print $NF}'

    Install SuperDirt by starting the SuperCollider shell with the sclang command, then running the following (update the version number if required):

    Quarks.checkForUpdates({Quarks.install("SuperDirt", "v1.7.3"); thisProcess.recompile()})

    The command returns immediately but processes in the background. Wait for it to finish and, once completed, press Ctrl+d to exit sclang.

  4. Tidal Installation

    Terminal window
      cabal update && cabal install tidal --lib

  5. Almost done! The final installation step is to choose and install a text editor (see below) to interact with TidalCycles.

Get a text editor

To use Tidal, code needs to be run in the Tidal interface, which is a REPL (like a command line). It’s inconvenient and impractical to type and run commands directly in the REPL, so we use a text editor of our choice together with a plugin or extension to run the REPL.

Below are short introductions to the most popular text editors used with Tidal (and for code in general), and how to set them up. If you are new to code editing, choose between Pulsar and VS Code.

Pulsar

A screenshot of the Pulsar editor.

Pulsar is a code editor that is open-source and community-led. It is based on Atom and was started after the announcement that Atom will be sunset. Pulsar has a Package Manager which provides for community contributions, including our TidalCycles package.

See the #pulsar channel on Discord for support and discussion.

VS Code

A screenshot of the VS Code editor.

VSCode is currently the most popular general purpose code editor. It is published by Microsoft, with some open-source components. TidalCycles code can be written in VS Code through the TidalCycles Extension. Also see the extension repository on GitHub if you want to report an issue or contribute to its development.

The VS Code TidalCycles extension features an audio file browser. After installation, click on the TidalCycles logo in the left pane to see all the samples currently available for Tidal. From there you can preview them, and insert them directly in your code.

Vim / Neovim

A screenshot of a customised neovim installation.

Vim is the classic and ubiquitous text editor. This editor is famous for its minimalistic approach, flexibility, and for its unique approach to modal editing. Vim and Neovim, a version with new and updated features, are free, cross-platform, and open-source. They can be extended through the help of plugins, and are generally more configurable than other text editors. Vim has a very long history and has the reputation of being very stable and fast. It does, however, have a steep learning curve, and is mostly used by experienced users, but fluency allows the user to edit text very fast.

Vim-Tidal is the recommended plugin to interact with TidalCycles. It will work for both Vim and Neovim, and will adapt to your setup. You can use Neovim’s native terminal functionality, as well as tmux or other multiplexers. Check the README file for more information about the installation process.

Other Vim plugins can add functionality that could be useful for livecoding. For example — as suggested by @guiot on the Tidal Club Forum — you can keep track of your improvisations using the undotree. Using the undotree wisely is a great way to backtrack in time or to keep a plaintext trace of your improvisations. By default, undotree will record every little tiny changes in your text file. Activate the undotree for a file by entering the :UndotreeToggle command.

Emacs

A screenshot of the a Doom Emacs setup.

Emacs is, like Vim, a classic programmer’s editor with a long history. Emacs is much more than just a text editor, but it (also) has the reputation of being a little difficult to use at first. For a while, Emacs was the only editor that worked with Tidal!

Emacs has packages for both Tidal and SuperCollider. Learning Emacs can be intimidating at first, but it is also a very rewarding experience. Emacs is actually a whole computing environment, and you can do pretty much everything you can imagine with this software (including sending emails and reading books). The heart of Emacs is customization: there is a fully-fledged programming language (Emacs-Lisp) to do so.

Depending on your OS, you might have to install it in very different ways. Check what is the recommended distribution for your system. Once installed, be sure to check out one of the most popular configuration frameworks if you want to make things easier:

The tidal.el file can be found here: tidal.el.

To install the Emacs interface to Tidal, you’ll need to edit the 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 you are using the Spacemacs custom distribution for Emacs, you should be able to use a layer made for it by rbino. If you are using the develop branch, you just need to add tidalcycles to dotspacemacs-configuration-layers, and it should work out of the box. Reload the configuration with SPC f e R or restart Spacemacs for the changes to take effect. The Tidal mode will load automatically whenever you open a .tidal file. Press Ctrl/Cmd+Return to evaluate a line. Explore the other shortcuts or map them to your liking.

If you are using Doom Emacs, edit your packages.el file (enter space f p and select packages.el) and add (package! tidal) in a new line. In your terminal, go to ~/.emacs.d/bin and run ./doom sync. Wait until the update process is done and relaunch Doom Emacs. Edit your BootTidal.hs path by typing space f p, and selecting config.el. Anywhere in this file, enter the following line:

(setq tidal-boot-script-path "~/.cabal/share/x86_64-osx-ghc-8.8.4/tidal-1.7.4/BootTidal.hs")

You can now open any .tidal file you want. If the highlighting is not showing up, run tidal-mode. Launch Haskell with C-c C-s, and eval regions with C-c C-e.

A MELPA package is also provided for TidalCycles integration within Emacs. You must first make sure you have MELPA installed on your machine (instructions; basically modifying your init.el or .emacs files with the first code snippet and then executing M-x package-refresh-contents in Emacs. Simply run M-x package-install, followed by tidal. This extension provides a major mode for *.tidal files. Once the package is installed, you can just open a Tidal script and press C-c C-s to start Tidal in Emacs, then C-return to run the statement under your cursor.

Test Tidal with Emacs

You should now have installed the Tidal Mode for Emacs. Open a new file, and give it a random name like helloworld.tidal. Once the file is opened, you still have to start Tidal. Enter Ctrl-C and then Ctrl-S to start. Check if Emacs and Tidal are working correctly by entering the following line and by pressing Ctrl+Enter to evaluate the single-line block:

d1 $ brak $ sound "bd sn/2"

Helix

A screenshot of the Helix editor.

Helix is a code editor — written in Rust — with a fast-growing community. It takes inspiration from other modal editors like Vim, but aims to be vastly simplified while just as capable. Helix also aims to have things “just work”, and features such as LSPs work out of the box. It does not, however, have a plugin system yet.

To send text from Helix to Tidal, you can use Helix’s “pipe to command” feature to pipe the text to a command which sends the text on to the Tidal REPL. This can be done by using, for example, tmux or the kitty terminal emulator. See this post by @trespaul on the Tidal Club forum for more details.

Sublime Text

A screenshot of Sublime Text.

Sublime Text is a popular cross-platform text editor. It is closed source and costs $70 USD. You can still use Sublime Text without buying it but be ready to deal with an ominous pop-up window that remind you to buy it every few minutes. Sublime Text is very lightweight and highly configurable.

To do live coding in Sublime Text, you need to install the Sublime REPL package via Package Control. To avoid fiddling with the existing Haskell REPL supplied by Sublime REPL, clone this modified version of it into the Sublime REPL config folder (which is found in e.g., ~/Library/Application Support/Sublime Text 3/Packages/SublimeREPL/config):

Terminal window
git clone https://gist.github.com/lvm/e0943b0d42507af60eee174ed263adde Tidal

Other installation operations

Upgrading

TidalCycles is a composite software. To upgrade it, it is highly recommended to upgrade everything along with the pattern library (the text editor and the SuperDirt audio engine as well). Each time a new version of Tidal is released, a new version of SuperDirt will likely follow, etc…

Ghc

If you are using windows, you will need at least version 9.4.2 of ghc installed, e.g. via chocolatey.

For linux and mac, you don’t need to upgrade ghc.

Library

Upgrade tidal with the following from a terminal window (Linux/MacOS/Windows):

Terminal window
cabal update
cabal v1-install tidal

If you originally installed tidal with ‘cabal install’ rather than ‘cabal v1-install’, you might have to run the following command instead. However this tends to be less reliable than the above method.

Terminal window
cabal update
cabal install tidal --lib

If things get messed up, under linux and macos you can remove the folders .ghc and .cabal from your home folder, and try again. Under windows, you can try the same but by deleting the c:\Users\<user>\AppData\Roaming\cabal where <user> is your username.

Editor plugin

Your text editor might refer to the TidalCycles plugin as an extension or as a package. Check the sidebar to get more information about ways to update your favorite text editor.

SuperDirt

To upgrade the SuperDirt sound synthesiser/sampler, open SuperCollider, and paste the following command in the interactive editor. Select the text and press Shift+Enter:

Quarks.update("SuperDirt")

You’ll need to recompile the class library. You can do this either by simply restarting the software or via the Recompile class library entry on the Language top-bar menu.

Downgrading

Sometimes, you might want to return to an earlier version of Tidal. Use the ghc-pkg command to do so. Enter the following commands in your terminal (or Powershell for Windows users) to downgrade your Tidal installation.

Listing all the currently installed versions

This command will list the versions of Tidal you have installed. If there is more than one, the most recent will be used:

Terminal window
ghc-pkg list tidal

Uninstalling a version

To uninstall a version, you can do, for example:

Terminal window
ghc-pkg unregister tidal-1.0.6

Do this for each version until the most recent is the one you want.

Choosing a specific version

If you don’t have the one you want installed, you can select the desired version:

Terminal window
cabal install tidal-0.9.10

Uninstallation

TidalCycles does not provide an easy uninstaller. To uninstall Tidal, you will need to:

  • Uninstall SuperDirt and/or SuperCollider if you are not already using it for another purpose.
  • Uninstall the Tidal library and the GHC compiler.

Linux

Uninstalling TidalCycles on Linux can be tricky. There are multiple ways of installing it depending on the distribution you are using. Here are some tips you can use to locate all the components that are part of the Tidal install.

Using whereis

Type whereis scide sclang scsynth in a terminal path to get the path to SuperCollider binaries.

SuperDirt Quark

Open SuperCollider. In the File menu, click on Open user support directory. This menu will take you where SuperDirt is currently installed on your computer. Check in the downloaded-quarks for SuperDirt. Don’t forget to uninstall the Dirt-Samples folder as well. It can be quite heavy (all the samples are located here).

Uninstall stack

If you installed Tidal using Stack, you can use a dirty but simple solution to uninstall it. Run rm -rf $HOME/.stack. This command will delete the hidden stack folder located in your root directory.

Stack will sometimes install a binary located here: $HOME/.local/bin. Delete it if you want.

Clean up cabal and GHC

To clean up cabal and GHC (user-installed packages), try running the following command in a terminal window:

Terminal window
rm ~/.cabal ~/.ghc

Windows

For chocolatey installs, see the instructions for Windows Chocolatey Cleanup.

MacOS

Using uninstall-hs

Open a terminal window and type uninstall-hs. This command will delete many things Haskell related from your computer.

Uninstalling ghcup

If you installed Tidal using ghcup, you can try a hacky solution. Open a terminal window and paste rm -rf ~/.ghcup. This will delete the .ghcup hidden directory that was living in your root directory.

Clean up cabal and GHC

To clean up cabal and GHC (user-installed packages), try running the following command in a terminal window:

Terminal window
rm ~/.cabal ~/.ghc

Getting Help

If you are having trouble with installation, here are options:

  • Review this page carefully and make sure you are following all instructions.
  • For individual component problems - such as SuperCollider and SuperDirt - check their ReadMe pages in GitHub:
  • TidalCycles Discord - Installation Help Channel
    • Try searching this channel to see if your problem has been experienced by others
    • Be sure to post details - what exact problem, error messages, what Windows version, etc.
    • See the “how to ask” channel for more about getting help from our community
  • Forums - Tidal Club A lot of smart people hang out here.
  • Don’t get discouraged! Tidal has a complex stack, but these components are all proven, robust and stable. Once it is all working, it rarely needs to have any attention.