Abjad

Abjad helps composers build up complex pieces of music notation in an iterative and incremental way. Use Abjad to create a symbolic representation 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's documentation is available at http://projectabjad.org.

Abjad depends on Python

This information refers to Abjad 2.14.

You must have Python 2.7.5 installed to run Abjad.

Type the following to check the version of Python installed on your computer:

python --version

You can download different versions of Python at http://www.python.org.

Note that Abjad does not yet support the Python 3.x series of releases.

Abjad depends on LilyPond

You must have LilyPond 2.17 (or greater) installed to run Abjad.

Download LilyPond at http://www.lilypond.org.

Type the following to see if LilyPond is callable from your commandline:

lilypond --version

If LilyPond is not callable from your commandline then you should add the location of the LilyPond executable to your PATH environment variable.

If you are new to working with the commandline you should Google to get a basic introduction to editing your profile and setting environment variables.

Installing the current packaged version of Abjad with pip

There are different ways to install Python packages on your computer.

One of the most direct ways is with pip. Type the following to find out if pip is installed on your computer:

pip --version

If you do not have pip installed we strongly recommend that you get it with Python's easy_install:

sudo easy_install pip

Then type the following to install the current packaged version of Abjad:

sudo pip install abjad --upgrade

Python will install Abjad in the site packages directory on your computer and you will be ready to start using Abjad.

Manually installing Abjad from the Python Package Index

What if you do not have pip or easy_install installed on your computer? Then you can install the current packaged version of Abjad from the Python Package Index. Follow these steps:

1. Download the current packaged version of Abjad from http://pypi.python.org/pypi/Abjad.

2. Unarchive the downloaded file.

   Under MacOS and Windows you can double click the archived file.

   Under Linux execute the following command with x.y replaced by the current release of Abjad:

   tar xzvf Abjad-x.y.tar.gz
   

3. Change to the directory created:

   cd Abjad-x.y
   

4. Then run the following under MacOS or Linux:

   sudo python setup.py install
   

5. Or run this command under Windows after starting up a command shell with administrator privileges:

   setup.py install
   

Python will install Abjad in the site packages directory on your computer and you will be ready to start using Abjad.

Documentation

Current online documentation for Abjad is available at http://projectabjad.org.

PDFs are available in Abjad's docs/pdf directory after you install.

Most users will find the online and PDF versions of the docs complete. If you work with Abjad a lot then you might want to build the docs yourself. Abjad's build system depends on Graphviz. So visit http://graphviz.org and install Graphviz if you decide to build the docs yourself.

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

# 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.