In [1]:
%load_ext abjadext.ipython
import abjad

Installing Abjad and friends

Note: This tutorial assumes you are working in a Unix-like environment (which, without splitting hairs, OSX and Linux are). Whenever possible, we'll provide information about how working in a Windows environment differs.

Getting comfortable with your terminal

We're going to do a lot of work in the terminal. Editing files, executing scripts, etc. That includes installing and working with Abjad and its dependencies.

Hold on, what's a terminal?

A terminal, or terminal emulator, gives you access to the textual or command-line interface to your computer. By typing commands in text you can start and stop programs, inspect the state of your machine, move files around and so forth. The terminal is very powerful and potentially intimidating, but we won't be doing anything too complicated.

Turning it on

  • OSX: Look for Terminal.app in /Applications/Utilities
  • Debian: It depends.
  • Windows: Look for Command Prompt

Useful commands (Bash)

  • cd: change directory
  • pwd: print the current directory
  • ls: list the contents of the current directory
  • echo: print something
  • cat: print the contents of a fail
  • head/tail: show the first or last few lines of a file
  • mkdir: make a new directory
  • rm: remove a file or directory
  • which: find the location of an executable


  • tab completion
  • wildcard expansion
  • pipes and redirection
  • .. and directory separators

For example, here are some terminal commands (not counting the ! which is special to the IPython Notebook):

In [2]:


In [3]:
!ls -l

total 696
-rwxr-xr-x@ 1 Davi  staff  130659 21 Jun 16:05 1-installation.ipynb
-rwxr-xr-x@ 1 Davi  staff  220057 21 Jun 16:34 2-leaves.ipynb
-rwxr-xr-x@ 1 Davi  staff    1932 24 Mar  2019 presentation.py

LilyPond: http://lilypond.org/development.html

Now that we've dipped our toes into the terminal, let's start collecting the bits and pieces we need to start working with Abjad. Starting with LilyPond!

What is it?

LilyPond is a music engraving program, devoted to producing the highest-quality sheet music possible. It brings the aesthetics of traditionally engraved music to computer printouts.


LilyPond is a compiled system: it is run on a text file describing the music. The resulting output is viewed on-screen or printed. In some ways, LilyPond is more similar to a programming language than graphical score editing software.


You do not write music by dragging notes from a graphical toolbar and placing them on a dynamically refreshing score; you write music by typing text. This text is interpreted (or “compiled”) by LilyPond, which produces beautifully engraved sheet music.

What does Abjad use it for?

LilyPond is Abjad's musical typesetting engine. Abjad generates LilyPond input files (.ly) and then runs LilyPond against those files, creating PDFs.

How do I install it?

Always, always install LilyPond from LilyPond's website: http://lilypond.org.

While package managers (more on that soon) often provide versions of LilyPond, their always old. Use a recent development version instead.

How do I know it works?

In [4]:
!lilypond --version

GNU LilyPond 2.21.0

Copyright (c) 1996--2020 by
  Han-Wen Nienhuys <hanwen@xs4all.nl>
  Jan Nieuwenhuizen <janneke@gnu.org>
  and others.

This program is free software.  It is covered by the GNU General Public
License and you are welcome to change it and/or distribute copies of it
under certain conditions.  Invoke as `lilypond --warranty' for more

Python: https://python.org

What is it?

From Wikipedia:

Python is a widely used high-level, general-purpose, interpreted, dynamic programming language.[24][25] Its design philosophy emphasizes code readability, and its syntax allows programmers to express concepts in fewer lines of code than possible in languages such as C++ or Java.[26][27] The language provides constructs intended to enable clear programs on both a small and large scale.[28]

Python supports multiple programming paradigms, including object-oriented, imperative and functional programming or procedural styles. It features a dynamic type system and automatic memory management and has a large and comprehensive standard library.[29]

Python interpreters are available for many operating systems, allowing Python code to run on a wide variety of systems. Using third-party tools, such as Py2exe or Pyinstaller,[30] Python code can be packaged into stand-alone executable programs for some of the most popular operating systems, so Python-based software can be distributed to, and used on, those environments with no need to install a Python interpreter.

CPython, the reference implementation of Python, is free and open-source software and has a community-based development model, as do nearly all of its variant implementations. CPython is managed by the non-profit Python Software Foundation.

How do I install it?

If you're on OSX or a *nix system like Debian, Arch, Ubuntu etc. then you almost certainly have some version of Python installed. Abjad works with both Python 2.7 and 3.3+, but for the sake of modernity, let's try to work in Python 3.5.

Installing a new version of Python won't erase your old versions, so no harm done.

What does Abjad use it for?

Abjad is written in Python!

We chose Python for many of the reasons listed in the description above. It has a clean, simple syntax that (generally) encourages clearly-written code. It works on all modern operating systems. It's used extensively by many different people and organizations all over the world (scientific computing, financial computing, systems operations) which in turn means that it has a huge ecosystem of libraries we can tap into, and tens of thousands of programmers and users looking into its every aspect. And because Python is interpreted and not compiled, the cycle of development - writing code, trying it out, revising - is fast.

How do I know it works?

In [5]:
!python --version

Python 2.7.16

Some Python tips

Running a command:

 python -c "print('i am printing this')"

Executing a file:

 python my-python-file.py

Executing a file but keeping the interpreter alive:

 python -i my-python-file.py

Quitting the interpreter:


Package managers

For OSX and *nix users, many dependencies are best installed via a package manager: a program that knows how to find and install other programs and whatever programs those programs depend upon.

*nix systems come with package managers installed, like yum or apt. OSX users will have to install manually. Luckily, HomeBrew (http://brew.sh) is really easy to get. Just run the following command in your terminal:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Once HomeBrew is installed you can verify it works like this:

In [6]:
!brew --version

Homebrew 2.3.0
Homebrew/homebrew-core (git revision 300c1; last commit 2020-06-05)
Homebrew/homebrew-cask (git revision 961315; last commit 2020-06-05)

Command-line dependencies

Abjad relies on a number of command-line tools and libraries to get work done. These include image-processing libraries like ImageMagick, image-generation libraries like Graphviz and LilyPond, and typesetting tools like LaTeX.

Git: https://git-scm.com/

What is it?

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.

What does Abjad use it for?

Abjad uses git as its source control.

How do I install it?

If you're on OSX, there's a good chance your machine already has Git installed. Likewise under *nix.

How do I know it works?

In [7]:
!git --version

git version 2.19.1

ImageMagick: http://www.imagemagick.org/script/index.php

What is it?

ImageMagick® is a software suite to create, edit, compose, or convert bitmap images. It can read and write images in a variety of formats (over 200) including PNG, JPEG, JPEG-2000, GIF, TIFF, DPX, EXR, WebP, Postscript, PDF, and SVG. Use ImageMagick to resize, flip, mirror, rotate, distort, shear and transform images, adjust image colors, apply various special effects, or draw text, lines, polygons, ellipses and Bézier curves.

The functionality of ImageMagick is typically utilized from the command-line or you can use the features from programs written in your favorite language.

What does Abjad use it for?

Abjad uses ImageMagick's convert tool to crop images when building its documentation, and when inserting images into IPython notebooks like this one.

How do I install it?

How do I know it works?

In [8]:
!convert --version

Version: ImageMagick 7.0.7-28 Q16 x86_64 2018-03-25 http://www.imagemagick.org
Copyright: © 1999-2018 ImageMagick Studio LLC
License: http://www.imagemagick.org/script/license.php
Features: Cipher DPC HDRI Modules 
Delegates (built-in): bzlib freetype jng jpeg ltdl lzma png tiff xml zlib

TiMIDIty: http://timidity.sourceforge.net/

What is it?

TiMidity++ is a software synthesizer. It can play MIDI files by converting them into PCM waveform data; give it a MIDI data along with digital instrument data files, then it synthesizes them in real-time, and plays. It can not only play sounds, but also can save the generated waveforms into hard disks as various audio file formats.

What does Abjad use it for?

Abjad uses timidity to convert MIDI files into audio for embedding in IPython notebooks.

For example, we can create a staff in Abjad and call the function play() on it to create some audio:

In [9]:
staff = abjad.Staff(r"c'4 \times 2/3 { d'8 e'8 f'8 } g'4")

How do I install it?

  • OSX: brew install timidity
  • Debian: apt-get install timidity

How do I know it works?

In [10]:
!timidity --version

TiMidity++ version 2.15.0

Copyright (C) 1999-2018 Masanao Izumo <iz@onicos.co.jp>
Copyright (C) 1995 Tuukka Toivonen <tt@cgs.fi>

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.

Graphviz: http://graphviz.org/

What is it?

Graphviz is open source graph visualization software. Graph visualization is a way of representing structural information as diagrams of abstract graphs and networks. It has important applications in networking, bioinformatics, software engineering, database and web design, machine learning, and in visual interfaces for other technical domains.

What does Abjad use it for?

Abjad uses Graphviz's dot tool for creating inheritance graphs in its documentation, and to graph various kinds of musical score structures.

In [11]:
staff = abjad.Staff("c'4 d' e'")

G Staff_0 Staff Note_0 Note c'4 Staff_0->Note_0 Note_1 Note d'4 Staff_0->Note_1 Note_2 Note e'4 Staff_0->Note_2

How do I install it?

  • OSX: brew install graphviz
  • Debian: apt-get install graphviz

How do I know it works?

In [12]:
!dot -V

dot - graphviz version 2.40.1 (20161225.0304)

LaTeX / TeX Live: https://www.tug.org/texlive/ (optional)

What is it?


TeX is a typesetting language. Instead of visually formatting your text, you enter your manuscript text intertwined with TeX commands in a plain text file. You then run TeX to produce formatted output, such as a PDF file. Thus, in contrast to standard word processors, your document is a separate file that does not pretend to be a representation of the final typeset output, and so can be easily edited and manipulated.

TeX Live:

TeX Live is an easy way to get up and running with the TeX document production system. It provides a comprehensive TeX system with binaries for most flavors of Unix, including GNU/Linux, and also Windows. It includes all the major TeX-related programs, macro packages, and fonts that are free software, including support for many languages around the world.

What does Abjad use it for?

Abjad's abjad-book tool pre-processes LaTeX files, allowing you to embed notation as well as arbitrary interpreted Python code alongside professionally-typeset text.

We often use LaTeX when creating the front and back covers as well as performance notes to scores generated with Abjad.

How do I install it?

How do I know it works?

In [13]:
!xetex --version

XeTeX 3.14159265-2.6-0.99999 (TeX Live 2018)
kpathsea version 6.3.0
Copyright 2018 SIL International, Jonathan Kew and Khaled Hosny.
There is NO warranty.  Redistribution of this software is
covered by the terms of both the XeTeX copyright and
the Lesser GNU General Public License.
For more information about these matters, see the file
named COPYING and the XeTeX source.
Primary author of XeTeX: Jonathan Kew.
Compiled with ICU version 61.1; using 61.1
Compiled with zlib version 1.2.11; using 1.2.11
Compiled with FreeType2 version 2.9.0; using 2.9.0
Compiled with Graphite2 version 1.3.11; using 1.3.11
Compiled with HarfBuzz version 1.7.6; using 1.7.6
Compiled with libpng version 1.6.34; using 1.6.34
Compiled with poppler version 0.63.0
Using Mac OS X Core Text and Cocoa frameworks

Choose a text editor

To work with Abjad, LilyPond and LaTeX, you're going to need a text editor. Most people new to working at the command-line will want to use a graphical text editor. Obviously there are text editors available from within the command-line, but they often have a steep learning curve. Go with what's comfortable for you.

Command-line text editors

  • nano (easy mode)
  • vim (hard mode)

Graphical text editors

  • TextMate
  • SublimeText
  • etc.

Virtual environments (optional)

Virtual environments (virtualenvs) allow you to isolate Python installations, including their installed 3rd-party libraries, from one another. We strongly recommend working in a virtual environment, as it will prevent you from installing packages globally which can have unintended or undesirable consequences.

This lets you work with different versions of Python, different versions of Abjad, whatever you like. In any case, it's cleaner!

  • sudo pip install virtualenvwrapper
  • pip install virtualenvwrapper-win (on Windows)

Once you have the appropriate package installed:

  • mkvirtualenv myvirtualenv will create and activate the myvirtualenv environment.
  • workon will list virtualenvs.
  • workon myvirtualenv will activate myvirtualenv.
  • deactivate will exit the current virtual environment.

Install Abjad

Now that all of the dependencies are installed, let's get Abjad.

Installing Abjad from source

To install from source, you need to clone Abjad from its repository on GitHub, navigate into the resulting folder and then run Python's pip command to install it:

git clone https://github.com/Abjad/abjad.git
cd abjad
pip install -e .[development,ipython]

Installing Abjad from PyPI

Alternatively, you can install the latest published version from the Python Package Index:

pip install abjad[development,ipython]

Installing Abjad this way will make it hard to inspect the source code of the project, so for our purposes we'll install from source instead.

Hello world!

Now that Abjad is installed, let's verify that it's working as expected.

Start by launching your Python interpreter:


Once the interpreter is active, run the following lines, one by one:

from abjad import *
note = Note()

After running the last line, a PDF should appear!

If that worked, go ahead and quit Python:


That's it!

If you want to keep digging in to more advanced topics (which we'll get to later in the course as well), keep reading.

Checking for Abjad's command-line tools

Abjad comes with its own tools for use on the command-line outside of Python. Let's check that they're available:

In [14]:
!ajv --help

usage: abj-dev-script [-h] [--version]

Entry-point to Abjad developer scripts catalog.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

    help                print subcommand help
    list                list subcommands
    builds              Manage score package build targets.
    clean               Clean *.pyc, *.swp, .cache, __pycache__ and tmp* files
                        and folders from PATH.
    material            Manage score package materials.
    replace             Replace text.
    score               Manage score packages.
    segment             Manage score package segments.
    stats               Build statistics about Python modules in PATH.

Running Abjad's test suite

To run Abjad's test suite, navigate into wherever you installed Abjad, then run py.test and/or ajv doctest:

cd ~/Abjad/abjad
py.test -rf
ajv doctest

Building Abjad's documentation

To build Abjad's documentation, run the following command:

ajv api -M

This will take a long time (~1 hour), so only if you really want to.

You can see what the documentation looks like here: http://abjad.mbrsi.org/

In [ ]: