Abjad (3.0.0)¶
GitHub | PyPI | Documentation | Mailing list | Issue Tracker | Travis-CI
Introduction¶
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.
Quickstart¶
1. Get Abjad and LilyPond¶
Get Abjad via pip:
~$ sudo pip install abjad
Get LilyPond from http://lilypond.org/development.html.
Consult our installation instructions for detailed help on getting Abjad, setting it up, and installing any dependencies like LilyPond:
2. Make notation¶
Start your Python interpreter and import Abjad:
>>> import abjad
Then use Abjad to create and show notation:
>>> duration = abjad.Duration(1, 4)
>>> notes = [abjad.Note(pitch, duration) for pitch in range(8)]
>>> staff = abjad.Staff(notes)
>>> abjad.show(staff)

Note that you can click on any music notation you find in Abjad’s documentation to see its LilyPond source code.
You might notice that the music notation throughout Abjad’s documentation doesn’t quite look like what LilyPond produces out-of-the-box. There are a number of small differences. For example, all of the notes, chords and rests are spaced proportionally. There are no bar numbers. The glissandi are a little bit thicker than normal. Tuplet brackets show the tuplet ratio rather than a single number.
How does this happen? Our notation examples are generated as part of
Abjad’s doc-building process via a custom Sphinx extension housed in
Abjad’s abjad.book
subpackage.
To get the look-and-feel we want for our examples, we include a default
stylesheet
in each generated file.
Not all examples are styled the same. When demonstrating LilyPond
overrides or page layout options we may replace Abjad’s default
documentation stylesheet with another stylesheet or disable documentation
stylesheets entirely. If, while examining the LilyPond source files in
Abjad’s documentation, you encounter \include "..."
statements in those
files, you can find the corresponding stylesheets in Abjad’s documentation
source directory: abjad/docs/source/_stylesheets/
.
Now, let’s split the notes you just made every 5/16 duration, transpose every other split group up by a major-seventh, then slur every split group and finally attach an accent to the first note of each split group:
>>> shards = abjad.mutate(staff[:]).split(
... durations=[abjad.Duration(5, 16)],
... cyclic=True,
... tie_split_notes=False,
... )
>>> for index, shard in enumerate(shards):
... if index % 2:
... abjad.mutate(shard).transpose('M7')
... if 1 < len(shard):
... abjad.attach(abjad.Slur(), shard)
... abjad.attach(abjad.Articulation('accent'), shard[0])
...
>>> abjad.show(staff)

Now let’s create a second staff, copied from the first, invert all of the new staff’s pitches around middle-G and finally group both staves into a staff group:
>>> copied_staff = abjad.mutate(staff).copy()
>>> staff_group = abjad.StaffGroup([staff, copied_staff])
>>> for note in abjad.iterate(copied_staff).leaves(pitched=True):
... note.written_pitch = note.written_pitch.invert(axis='G4')
...
>>> abjad.show(staff_group)

Explore Abjad’s documentation to find even more ways you can create and transform notation with Python, LilyPond and Abjad.
Gallery¶
Many scores have been composed in whole or in part with the assistance of Abjad and LilyPond. Here are excerpts from a few such works.
Traiettorie inargentate (2013)¶
- For cello.
- Composed by Trevor Bača.
- Written for Séverine Ballon.
- Source available from https://github.com/trevorbaca/traiettorie/.
Invisible Cities (iii): Ersilia (2015)¶
- For chamber orchestra.
- Composed by Josiah Wolf Oberholtzer.
- Written for Ensemble Dal Niente.
- Source available from https://github.com/josiah-wolf-oberholtzer/ersilia/.
Visit our score gallery for many more examples:
- Score gallery
- Demarest/Lloyd (2016)
- Al-kitab al-khamr (2015)
- Invisible Cities (iii): Ersilia (2015)
- Ins wasser eingeschrieben (2015)
- Invisible Cities (ii): Armilla (2015)
- Refrain (2014)
- Huitzil (2014)
- Invisible Cities (i): Zaira (2014)
- Krummzeit (2014)
- Plague Water (2014)
- The World All Around (2012-13)
- Traiettorie inargentate (2013)
- Cartography (2013)
- Aurora (2011)
- L’archipel du corps (2011)
- L’imaginaire (2010)
- Lagartija (2010)
- Mon seul désir (2009)
- Lidércfény (2008)
- Sekka (2007)
- Čáry (2006)
- Poème Récursif (2005)
CCRMA Summer Workshop¶
Summers | Palo Alto, CA
Introduction to the production of professionally engraved musical scores using the Python programming language and the Abjad API for Formalized Score Control as part of compositional practice.
The course introduces Abjad’s object-oriented approach to music notation and algorithmic composition through real-world examples and hands-on coding activities. No previous programming experience is required. Python basics will be taught from the ground up during the course with musical examples designed to make sense to composers.
Topics covered include:
- system installation and configuration,
- defining your own functions, classes and modules,
- generating structured tableaux of rhythms, pitch collections and other materials during precomposition,
- managing polyphony with operations on voices, staves and other musical containers,
- working with parametric score layout,
- understanding the document structure of complex scores, and
- controlling the details of musical typography programmatically.
Taught by Jeff Treviño, Trevor Bača, and Josiah Wolf Oberholtzer.
Note
Visit the CCRMA website for the most up-to-date scheduling information about this annual course.
Texts on Abjad¶
A number of papers and dissertations discuss Abjad.
- Bača, Trevor, Josiah Wolf Oberholtzer, Jeffrey Treviño and Vıctor Adán. “Abjad: An Open-Software System For Formalized Score Control.” Proceedings of the First International Conference on Technologies for Music Notation and Representation. 2015.
- Oberholtzer, Josiah Wolf. A Computational Model of Music Composition. Doctoral dissertation, Harvard University, Graduate School of Arts & Sciences. 2015.
- Trevino, Jeffrey Robert. Compositional and analytic applications of automated music notation via object-oriented programming. Doctoral dissertation, University of California, San Diego. 2013.
Features¶
Abjad lets you:
- Create musical notation in an object-oriented way.
- Model compositional thinking computationally.
- Generate and transform complex rhythms through rhythm-makers, meter-rewriting and quantization.
- Construct powerful component selectors for locating musical objects in a score.
- Parse LilyPond and RTM syntax into musical objects.
- Control all of the typographic details of music notation.
- Embed musical notation in IPython notebooks, LaTeX and Sphinx documents.
Explore the high-level overview of Abjad’s concepts or our tutorials and examples to see these features in action:
Extensions¶
Abjad supports a collection of extension packages providing additional documentation, tooling and compositional support.
- Documentation extension: https://github.com/abjad/abjad-ext-book
- Score project commandline tools: https://github.com/abjad/abjad-ext-cli
- IPython integration: https://github.com/abjad/abjad-ext-ipython
- Quantization tools: https://github.com/abjad/abjad-ext-nauert
- Rhythm-maker tools: https://github.com/abjad/abjad-ext-rmakers
- Tonal analysis tools: https://github.com/abjad/abjad-ext-tonality