Abjad

Abjad helps composers build up complex pieces of music notation in an iterative and incremental way. Use Abjad to create symbolic representations of all the notes, rests, staves, tuplets, beams and slurs in any score. Because Abjad extends the Python programming language, you can use Abjad to make systematic changes to your music as you work. And because Abjad wraps the powerful LilyPond music notation package, you can use Abjad to control the typographic details of the symbols on the page.

GitHub | PyPI | Documentation | Mailing list | Issue Tracker | Travis-CI

[](https://github.com/ambv/black)

Installation

Abjad works on Unix/Linux, OSX, and Windows on Python versions 3.6+.

Install Abjad

To install the most recent official release of Abjad from PyPI, the Python Package Index, via pip:

~$ sudo pip install abjad

Caution:

We strongly encourage you to not install Abjad globally via sudo pip install, but to use a :ref:`virtual environment <virtual-environments>` instead. If you're already working in a virtual environment, simply omit the sudo.

Note:

Abjad supports Python 3.6 and above.

To install the cutting-edge version Abjad from its GitHub repository, via git and pip:

~$ git clone https://github.com/Abjad/abjad.git
~$ cd abjad
abjad$ pip install .

Once you have Abjad installed, fire up Python and import it:

~$ python
Python 3.6.5 (v3.6.5:f59c0932b4, Mar 28 2018, 03:03:55)
[GCC 4.2.1 (Apple Inc. build 5666) (dot 3)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import abjad
>>> abjad.__version__
'3.0.0'

Congratulations!

Install LilyPond

Abjad uses LilyPond, an open-source automated engraving engine, to produce notational output.

Abjad targets whichever is the most recent version of LilyPond. At the time of this writing, that means 2.18-stable or 2.19-development. We recommend installing directly from LilyPond's website, rather than using whichever version of LilyPond your package manager provides, as these packages are often out-of-date.

Once you have installed LilyPond, test if LilyPond is callable from your command-line by running the following command:

~$ lilypond --version

GNU LilyPond 2.19.82

Copyright (c) 1996--2015 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
information.

If LilyPond is not callable from your command-line, you should add the location of the LilyPond executable to your PATH environment variable. If you are using OSX, simply run the following line in your terminal:

export PATH="$PATH:/Applications/LilyPond.app/Contents/Resources/bin/"

You can add the above line to your ~/.profile to make the change permanent.

The LilyPond documentation also provides instructions for making the lilypond command available on the command-line under OSX at http://www.lilypond.org/macos-x.html.

If you are new to working with the command-line you should use Google to get a basic introduction to navigating in the shell, editing your profile and setting environment variables. There are more tutorials than we can count!

Install Graphviz (optional)

Abjad uses Graphviz, an open-source graph visualization library, to create graphs of rhythm-trees and other tree structures, and to create visualizations of class hierarchies for its documentation. Graphviz is not necessary for creating notation with Abjad.

To install Graphviz on Debian and Ubuntu:

~$ sudo apt-get install graphviz

To install Graphviz on OSX via Homebrew:

~$ brew install graphviz

Once you have install Graphviz, test if Graphviz is callable from your command-line by running the following command:

~$ dot -V
dot - graphviz version 2.38.0 (20140413.2041)

All of the graph images in Abjad's API documentation were created via graphviz. See :py:func:`~abjad.top.graph` for more details.

Install extension packages

Abjad's extension packages can be installed via the following commands:

~$ pip install abjad[book]      # documentation tools
~$ pip install abjad[cli]       # score package command-line tools
~$ pip install abjad[ipython]   # ipython integration
~$ pip install abjad[nauert]    # quantization tools
~$ pip install abjad[rmakers]   # rhythm-maker tools
~$ pip install abjad[tonality]  # tonal analysis tools

Development installation

To perform development on Abjad, run the test suite, or build Abjad's documentation locally, clone Abjad from the Github repository and install it in edit mode with its development extras:

~$ git clone https://github.com/Abjad/abjad.git
~$ cd abjad
abjad$ sudo pip install -e .[book,test]  # NOTE: no spaces in the string after "install"

Installing Abjad in development mode will install the following Python package dependencies (along with their own dependencies):

• pytest, for running Abjad's test suite
• Sphinx, for building Abjad's documentation
• PyPDF2, for performing preprocessing on LaTeX source with Abjad's ajv book tool

Some of Sphinx's dependencies provide optional optimized Python extensions, which must be compiled before they can be used. If your machine does not have a C compiler available, you may see error message while the pip install -e ".[development]" command runs. These warnings are harmless and will not prevent the dependencies from being installed.

To install C compilation tools on Debian and Ubuntu:

~$ sudo apt-get install build-essential

To install C compilation tools on OSX, we recommend simply installing XCode from the Apple App Store. Alternatively, you can install via Homebrew although this may take a significant amount of time.

Additionally, a few non-Python tools need to be installed in order to develop Abjad or build its documentation: TeXLive, ImageMagick, and Graphviz (which was explained above).

Install TeXLive

Building the LaTeX documentation, running the test suite, and using Abjad's ajv book document preprocessing tools require TeXLive. Abjad makes use of both pdftex for producing PDFs, and the pdfcrop tool distributed with TeXLive.

To install TeXLive on Debian and Ubuntu:

~$ sudo apt-get install texlive-full

On OSX, we recommend installing via the MacTeX distribution.

Install ImageMagick

Building Abjad's documentation requires ImageMagick, a collection of raster image processing tools.

To install ImageMagick on Debian and Ubuntu:

~$ sudo apt-get install imagemagick

To install ImageMagick on OSX, we recommend installing via Homebrew:

~$ brew install imagemagick

Once you have install ImageMagick, test if ImageMagick is callable from your command-line by running the following command:

~$ convert --version
Version: ImageMagick 6.9.1-6 Q16 x86_64 2015-06-22 http://www.imagemagick.org
Copyright: Copyright (C) 1999-2015 ImageMagick Studio LLC
License: http://www.imagemagick.org/script/license.php
Features: Cipher DPC Modules
Delegates (built-in): bzlib freetype jng jpeg ltdl lzma png tiff xml zlib

Abjad and IPython

Abjad can be used with IPython to embed notation, graphs and audio into an IPython notebook. To work with Abjad in IPython, install Abjad with both its development and ipython extra dependencies:

~$ sudo pip install abjad[ipython]  # NOTE: no spaces in the string after "install"

Capturing MIDI files into an IPython notebook requires the timidity package.

To install timidity on Debian or Ubuntu:

~$ apt-get install timidity

To install timidity on OSX via Homebrew:

~$ brew install timidity

Once all dependencies have been installed, create a new IPython notebook and run the following "magic" command in a cell to load Abjad's IPython extension:

%load_ext abjadext.ipython

Once loaded, notation and MIDI files can be embedded in your notebook whenever you use show(...) and play(...) on valid Abjad objects.

Virtual environments

We strongly recommend installing Abjad into a virtual environment, especially if you intend to hack on Abjad's own source code. Virtual environments allow you to isolate Python packages from your systems global collection of packages. They also allow you to install Python packages without sudo. The virtualenv package provides tools for creating Python virtual environments, and the virtualenvwrapper package provides additional tools which make working with virtual environments incredibly easy.

Let's install virtualenvwrapper:

~$ sudo pip install virtualenvwrapper
...

Note:

On OSX 10.11 (El Capitan) it may be necessary to install virtualenvwrapper via alternate instructions:

~$ pip install virtualenvwrapper --ignore-installed six

See here for details.

Next, set an environment variable in your shell naming the directory you want the virtual environment files to be stored in, then create that directory if it doesn't already exist:

~$ export WORKON_HOME=~/.virtualenvs
~$ mkdir -p $WORKON_HOME

Note:

The location your virtual environment files are stored in could be anywhere. Because you are unlikely to need to access them directly, we suggest the .-prepended path .virtualenvs.

With the virtual environment directory created, "source" virtualenvwrapper's script. This script teaches your shell about how to create, activate and delete virtual environments:

~$ source `which virtualenvwrapper.sh`

Finally, you can create a virtual environment via the mkvirtualenv command. This will both create the fresh environment and "activate" it. Once activated, you can install Python packages within that environment, safe in the knowledge that they won't interfere with Python packages installed anywhere else on your system:

~$ mkvirtualenv abjad
...
~(abjad)$ pip install abjad  # "(abjad)" indicates the name of the virtualenv
...

You can also deactivate the current virtual environment via the deactivate command, or switch to a different environment via the workon <virtualenv name> command:

~(abjad)$ deactivate
~$ workon my-new-score
~(my-new-score)$

To make the virtual environment configuration sticky from terminal session to terminal session, add the following lines to your ~/.profile, ~/.bash_profile or similar shell configuration file:

export WORKON_HOME=$HOME/.virtualenvs
source `which virtualenvwrapper.sh`

Development installation within a virtualenv

To recap, a complete development installation of Abjad within a virtual environment requires the following steps:

• Create and activate a new virtual environment
• Clone Abjad somewhere and cd into the root of the cloned repository
• Install Abjad and its development / IPython dependencies

~$ mkvirtualenv abjad
...
~(abjad)$ git clone https://github.com/Abjad/abjad.git
~(abjad)$ cd abjad
abjad(abjad)$ pip install -e .[development,ipython]  # NOTE: no spaces between "." and "[development,ipython]"
...

Configuring Abjad

Abjad creates a ~/.abjad directory the first time it runs. In the ~/.abjad directory you will find an abjad.cfg file. This is the Abjad configuration file. You can use the Abjad configuration file to tell Abjad about your preferred PDF file viewer, MIDI player, LilyPond language and so on.

Your configuration file will look something like this the first time you open it:

# Abjad configuration file created by Abjad on 31 January 2014 00:08:17.
# File is interpreted by ConfigObj and should follow ini syntax.

# Set to the directory where all Abjad-generated files
# (such as PDFs and LilyPond files) should be saved.
# Defaults to $HOME.abjad/output/
abjad_output_directory = /Users/username/.abjad/output

# Comma-separated list of LilyPond files that
# Abjad will "\include" in all generated *.ly files
lilypond_includes = ,

# Language to use in all generated LilyPond files.
lilypond_language = english

# Lilypond executable path. Set to override dynamic lookup.
lilypond_path = lilypond

# MIDI player to open MIDI files.
# When unset your OS should know how to open MIDI files.
midi_player =

# PDF viewer to open PDF files.
# When unset your OS should know how to open PDFs.
pdf_viewer =

# Text editor to edit text files.
# When unset your OS should know how to open text files.
text_editor =

Follow the basics of ini syntax when editing the Abjad configuration file. Background information is available at http://en.wikipedia.org/wiki/INI_file. Under MacOS you might want to set you midi_player to iTunes. Under Linux you might want to set your pdf_viewer to evince and your midi_player to tiMIDIty, and so on.