---
title: "Engraving"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Engraving}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE, comment = "#>", message = FALSE, warning = FALSE, error = FALSE, tidy = TRUE, out.width = "100%"
)
```

This section covers `lilypond` and `tab` for writing LilyPond files and engraving to sheet music with LilyPond, respectively. Examples of the various pieces of song metadata that can be passed to to these functions are provided.

The examples focus on `tab` because this generates the tablature whereas `lilypond` only creates the LilyPond file that `tab` renders. `tab` is a wrapper around `lilypond`. The two functions have identical arguments, as `tab` merely passes them along to `lilypond` internally, except for one. `tab` has `keep_ly = FALSE` by default, which removes the `.ly` file created by `lilypond` following rendering of the file to pdf or png. To keep the LilyPond file, set this to `TRUE`. All other arguments are the same for both functions so they are really `lilypond` arguments.

Here are the `lilypond` arguments:

```{r args}
library(tabr)
args(lilypond)
```

By now you have seen many calls to `tab` in order to show full examples in early tutorial sections. With sufficient coverage of phrases, tracks and scores, and the progression through them, now it is time to go into detail on all the render time arguments that can be supplied that apply to the entire piece of tablature and any metadata or general song information associated with it.

## Score metadata

These are the most critical components that can be supplied to `lilypond`. These are the three arguments immediately after the input `score` and output `file`. While they have default values, they will almost invariably need to be changed for just about any song. `key` specifies the key signature, e.g. `key ="dm"`. Key changes in the middle of a song are not supported, but you can always edit the LilyPond file by hand to make highly customized changes. `time` gives the time signature, defaulting to common time, or 4/4 time. `tempo` provides the song tempo, defaulting to `tempo = "2 = 60"`. Note that `key` takes the `tabr` consistent key signature notation whereas `time` and `tempo` take literal LilyPond strings. Look up options for these strings if you are not familiar with them in LilyPond.

Throughout this tutorial section, the guitar and bass example from the section on tracks and scores is reused. The chord chart and chord sequence are retained to provide the most complete illustration of a rendered score. For completeness, here is what you have so far.

```{r song}
voice1 <- rp(p("c5 d5 e5 f5 g5", "1 2 4 4 1", "1*5"), 2)

notes <- "c e g c' e' c' g e g b d' g' f a c' f' c e g e c"
strings <- "5 4 3 2 1 2 3 4 4 3 2 1 4 3 2 1 5 4 3 4 5"
voice2 <- rp(p(notes, "8*20 2", strings), 2)

bass <- rp(p("c2e2*4 g1*2 f1*2 c2e2*3", "4*10 2", "32*4 4*4 32*3"), 2)

t1 <- track(voice1, voice = 1)
t2 <- track(voice2, voice = 2)
t3 <- track(bass, tuning = "bass", music_staff = "bass_8")

chords <- chord_set(c(c = "x32o1o", g = "355433", f = "133211"))
chord_seq <- rep(setNames(c(1, 2, 2, 1), names(chords)[c(1:3, 1)]), 3)
chords
chord_seq

song <- trackbind(t1, t2, t3, tabstaff = c(1, 1, 2)) %>% score(chords, chord_seq)
song
```

This time, when rendering the song, use settings for the three arguments discussed above. Given what is written, it doesn't make sense to change them all. For example, this won't fit well as a waltz (time = "3/4"). But for illustration purposes, pretend the song is actually in the key of D minor (F major). This key has one flat, B, so this will force the B note in the G chord to be annotated as an accidental. Change the time to `2/2` just for the sake of changing it, which won't really be any different from `4/4` except you will see a line through the common time symbol. Finally, change the tempo to `4 = 120`, which is also equivalent to the default, but will show up in the output slightly differently as well.

```{r metadata, results="hide", eval=FALSE}
lilypond(song, "ex32.ly", "dm", "2/2", "4 = 120")
tab(song, "ex32.pdf", "dm", "2/2", "4 = 120")
```

<p align="center"><img src="https://github.com/leonawicz/tabr/blob/master/data-raw/vignette-pngs/ex32.png?raw=true" width="100%"></p>

Notice how the key change alone, which added room for a single flat symbol to be squeezed into the start of the treble and bass clef staves, was enough to push everything to the point of wrapping around onto a second entire line compared to the earlier tutorial section where it all fit on one line. This is because it was a really tight fit to in the previous examples and there was not enough room for LilyPond to continue fitting everything on one line with this slight widening created by the key change. LilyPond generates sheet music with a somewhat responsive layout engraver. It won't leave everything on line one jam packaged and push a single measure to the line two. This will return to fitting on one line in a moment when we revert the key change.

### Ouput file and path

The output file specified with `file` ends in pdf in every example. However, you can switch to png output simply by specifying a file name with that extension. `file` can specify just the file named or the path to the file. The path may be relative or absolute. Optionally, the path to the output file can be passed separately to `path`, which otherwise defaults to `NULL`.

## Song information

The next important argument to `lilypond` is `header`. `header` takes a named list of character strings that are used to fill in general song information such as the title and composer. All previous examples were blank above the tabs because none of this information was ever provided. Below an example is given that uses all available arguments. You can use any subset of these. There is no requirement to supply them all. This example just shows what is available. Several of these would likely not be used in most cases.

```{r header, results="hide", eval=FALSE}
header <- list(
  title = "Song title",
  composer = "Words and music by the composer",
  performer = "Song performer",
  album = "Album title",
  subtitle = "Subtitle",
  arranger = "Arranged by tab arranger",
  copyright = "2018 <Record Label>",
  instrument = "guitar and bass",
  tagline = "A tagline",
  meter = "meter tag", opus = "opus tag", piece = "piece tag", poet = "poet tag"
)

tab(song, "ex33.pdf", header = header)
```

<p align="center"><img src="https://github.com/leonawicz/tabr/blob/master/data-raw/vignette-pngs/ex33.png?raw=true" width="100%"></p>

The copyright and tagline are cutoff in the above image, but in your pdf you will see these if you scroll to the bottom of the rendered page.

## Other settings

### MIDI files

You have probably noticed by now that every time a pdf if rendered, an accompanying MIDI file is also generated. This can be turned off with `midi = FALSE`. This specification goes into the LilyPond file itself via `lilypond`. Therefore, no MIDI output will be created even if you create the LilyPond file with `lilypond` but convert that to pdf with LilyPond outside of R.

One thing to note about MIDI files is that `tabr` will unfold any repeats that occur in a song due to calls to `rp`, `pct` or `volta`. This allows the MIDI file to play everything the proper number of times rather than ending prematurely by not being able to read repeat notation.

Also, `tabr` is a package aimed at creating guitar tablature. It is not concerned with MIDI or audio signals and audio data in general. Any MIDI functionality is considered to be an extra feature and does not receive priority development or support. At this time, there is no way to make other alterations to the MIDI file internals. MIDI output can be toggled on or off as mentioned. And without you having to do anything, MIDI output will respect repeat notation in the rendered LilyPond file. MIDI output will also automatically be transposed to match a transposition that is applied to a music staff (under reasonable and simplified conditions).

### String names

The `string_names` argument defaults to `NULL`. This means that standard tuning is never specified alongside the lines of a tab staff at the beginning of the tablature. However, any other tuning will be explicitly noted so the reader is aware of the alternate tuning of any applicable track. This can also be set to `TRUE` to force all tunings to be explicit including standard guitar tuning or `FALSE` to suppress them all (though it is unclear what value there is in the `FALSE` setting).

### Paper settings

There is some nominal level of control over the paper layout via `paper`. Like `header`, this is a named list. The defaults are fine so you probably do not need to alter most of these values. There are six options, all numeric except for `page_numbers`, which is logical.

*    `textheight`
*    `linewidth`
*    `indent`
*    `first_page_number`
*    `page_numbers`
*    `fontsize`

If you pass any values for some of these in a named list to `paper`, any not passed will retain their built in defaults. You do not have to supply them all when using `paper`.

For more detail on these settings and others further above, see the help documentation, `?lilypond`.

```{r cleanup, echo=FALSE}
unlink("*.mid")
```
