Abjad is a Python API for Formalized Score Control.
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.
Abjad works on Unix/Linux, OSX, and Windows.
~$ sudo pip install abjad
We strongly encourage you to not install Abjad globally via sudo pip install, but to use a virtual environment instead. If you’re already working in a virtual environment, simply omit the sudo.
Abjad supports Python 2.7 and above. Python 2.7.9 and above provide pip out-of-the-box. For earlier versions of Python 2.7, you may need to install pip yourself. While you can use the old easy_install tool (sudo easy_install pip), we strongly recommend the pip-installation instructions found here: https://pip.pypa.io/en/stable/installing/.
~$ git clone https://github.com/Abjad/abjad.git ~$ cd abjad abjad$ sudo pip install .
Once you have Abjad installed, fire up Python and import it:
~$ python Python 3.5.2 (v3.5.2:4def2a2901a5, Jun 26 2016, 10:47:25) [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__ '2.19'
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.20 Copyright (c) 1996--2015 by Han-Wen Nienhuys <email@example.com> Jan Nieuwenhuizen <firstname.lastname@example.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:
You can add the above line to your ~/.profile to make the change permanent.
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
~$ brew install graphviz
~$ 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 topleveltools.graph() for more details.
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 .[development] # 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.
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.
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
~$ brew install imagemagick
~$ 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
~$ sudo pip install abjad[development,ipython] # NOTE: no spaces in the string after "install"
To install timidity on Debian or Ubuntu:
~$ apt-get install timidity
~$ brew install timidity
Once loaded, notation and MIDI files can be embedded in your notebook whenever you use show(…) and play(…) on valid Abjad objects.
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 ...
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
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]" ...
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 # Default accidental spelling (mixed|sharps|flats). accidental_spelling = mixed # 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.