In [1]:
%load_ext abjadext.ipython
import abjad
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.
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.
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.
Terminal.app in /Applications/UtilitiesCommand Promptcd: change directorypwd: print the current directoryls: list the contents of the current directoryecho: print somethingcat: print the contents of a failhead/tail: show the first or last few lines of a filemkdir: make a new directoryrm: remove a file or directorywhich: find the location of an executableAlso:
.. and directory separatorsFor example, here are some terminal commands (not counting the ! which is special to the IPython Notebook):
In [2]:
!pwd
In [3]:
!ls -l
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!
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.
LilyPond is Abjad's musical typesetting engine. Abjad generates LilyPond input files (.ly) and then runs LilyPond against those files, creating PDFs.
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.
In [4]:
!lilypond --version
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.
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.
apt, yum) to get the newest Python version.Installing a new version of Python won't erase your old versions, so no harm done.
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.
In [5]:
!python --version
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
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.
Abjad uses git as its source control.
If you're on OSX, there's a good chance your machine already has Git installed. Likewise under *nix.
brew install gitapt-get install git
In [7]:
!git --version
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.
Abjad uses ImageMagick's convert tool to crop images when building its documentation, and when inserting images into IPython notebooks like this one.
brew install imagemagickapt-get install imagemagick
In [8]:
!convert --version
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.
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")
abjad.play(staff)
In [10]:
!timidity --version
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.
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'")
abjad.graph(staff)
In [12]:
!dot -V
TeX:
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.
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.
apt-get install texlive-full
In [13]:
!xetex --version
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.
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 virtualenvwrapperpip 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.Now that all of the dependencies are installed, let's get Abjad.
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]
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.
Now that Abjad is installed, let's verify that it's working as expected.
Start by launching your Python interpreter:
python
Once the interpreter is active, run the following lines, one by one:
from abjad import *
note = Note()
show(note)
After running the last line, a PDF should appear!
If that worked, go ahead and quit Python:
exit()
In [14]:
!ajv --help
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 [ ]: