# webern (0.1.0)
Elixir library for creating and working with 12-tone rows
![](https://github.com/mikowitz/webern/blob/master/config/Webern.jpg?raw=true)
<sup>Photo [Public Domain, Wikipedia](https://commons.wikimedia.org/w/index.php?curid=1137036)</sup>
[![Build Status](https://travis-ci.org/mikowitz/webern.svg?branch=master)](https://travis-ci.org/mikowitz/webern)
[![Inline docs](http://inch-ci.org/github/mikowitz/webern.svg)](http://inch-ci.org/github/mikowitz/webern)
[![license](https://img.shields.io/github/license/mashape/apistatus.svg?maxAge=2592000)](LICENSE)
## API
### Creating objects
`Webern.row/1` provides a helper function to generate a new tone row consisting
of pitch classes from the 12-tone semitone chromatic scale
`Webern.matrix/1` accepts a row as an argument and returns a displayable matrix
based on the row.
### Transforming tone rows
`Webern` also provides functions for the standard serial transformations:
* `prime` - the original form of the row
* `retrograde` - the row backwards
* if the prime form begins with pitch class indices [3, 5], the retrograde
form will end with pitch class indices [5, 3]
* `inverse` - the row with the interval between each set of pitch classes
flipped
* if the first two pitch classes in the prime form of the row are [3, 5],
the first two pitch classes of the inverse form will be [3, 1];
the upward step of 2 semitones becomes a downward step of 2 semitones
* `retrograde_inverse` - a compound transformation, acheived by taking first
the inverse of the prime form, and then the retrograde of the resulting
form
* `inverse_retrograde` - another, less common compound form, acheived by
taking first the retrograde of the prime form, and then the inverse of
the resulting form
For more information about twelve tone technique and transformations, see
[Twelve-tone technique](https://en.wikipedia.org/wiki/Twelve-tone_technique)
on Wikipedia
### Output
Both `Webern.Row` and `Webern.Matrix` implement the `String.Chars` protocol:
```elixir
iex> row = Webern.row([0, 2, 1, 3, 4, 6, 5, 7, 8, 10, 9, 11])
iex> to_string(row)
"c d cs ef e fs f g af bf a b"
iex> matrix = Webern.matrix(row)
iex> to_string(matrix)
"c d cs ef e fs f g af bf a b
bf c b cs d e ef f fs af g a
...
cs ef d e f g fs af a b bf c"
```
`Webern.Row.to_list/2` allows for more customized output of a row's contents.
Passing only the row to `to_list/2` will return the pitch classes as integers
```elixir
iex> row = Webern.row([0, 2, 1, 3, 4, 6, 5, 7, 8, 10, 9, 11])
iex> Webern.Row.to_list(row)
[0, 2, 1, 3, 4, 6, 5, 7, 8, 10, 9, 11]
```
Passing the option `to_pitches: true` will convert the pitch classes to their
lilypond formatted pitch class names, with 0 == `c`
```elixir
iex> row = Webern.row([0, 2, 1, 3, 4, 6, 5, 7, 8, 10, 9, 11])
iex> Webern.Row.to_list(row, to_pitches: true)
["c", "d", "cs", "ef", "e", "f", "fs", "f", "g", "af", "bf", "a", "b"]
```
Passing a pitch class name as the option `zero_pitch` works as above, but will
set 0 == `zero_pitch`
```elixir
iex> row = Webern.row([0, 2, 1, 3, 4, 6, 5, 7, 8, 10, 9, 11])
iex> Webern.Row.to_list(row, to_pitches: true, zero_pitch: "fs")
["fs", "af", "g", "a", "bf", "b", "c", "b", "cs", "d", "e", "ef", "f"]
```
`Webern` provides the `Webern.Lilypond` protocol and its `to_lily/1` function.
This function embeds a valid [LilyPond](http://www.lilypond.org) represenation of the row or matrix inside
a full lilypond document string. For a row, this returns a result almost identical
to calling `to_string/1` on the row (the only change being octave markings for
the pitch classes). For a matrix, the document will contain 60 rows, each of the
five row transformations listed above for each chromatic semitone.
While `Webern.Lilypond.to_lily/1` can be called on its own to return the LilyPond
document string, `Webern.to_lily/2` exists, which writes that document to a file
(whose name is passed as the second argument) and compiles it to a PDF document,
provided LilyPond is installed on your system.
```elixir
iex> row = Webern.row([0, 2, 1, 3, 4, 6, 5, 7, 8, 10, 9, 11])
iex> Webern.to_lily(row, "my_row")
:ok #=> this creates `my_row.ly` and `my_row.pdf` in your current working directory
```
## Installation
1. Add webern to your `mix.exs` dependencies
```elixir
defp deps do
[ {:webern, "~> 0.1"} ]
end
```
2. Run `mix do deps.get, compile`
### Dependencies
Most of `Webern`'s functionality requires only an Elixir installation, but if
you wish to use the `Webern.to_lily/2` function provided, make sure LilyPond
is installed on your system using the links and instructions found
[here](http://lilypond.org/download.html).