Gitara is a Ruby DSL for generating Lilypond guitar tablatures

Usage

To install,

gem install gitara

You need lilypond in order to generate pdfs and midis.

Gitara is tested on Ruby 3.3.3 and Lilypond 2.22. Patches are welcome.

To run,

gitara export PATH [OPTIONS]...

This will generate a lilypond .ly file and then call lilypond to export the .ly file to pdf and midi. Please see gitara help export for the available options.

Basic syntax

Gitara is a Ruby DSL. A typical Gitara file will have the following structure:

Gitara.define do
  score do
    stanza "Verse 1" do
      line do
        bar do
          notes "c d e f g a b c"
        end
      end
    end
  end
end

You can find examples at https://github.com/gsmendoza/gitara/tree/master/examples.

Bars

Bars are the smallest expressions in Gitara. That is, a gitara file must have at least one bar. The notes inside a bar follow Lilypond syntax.

Gitara.define do
  bar do
    notes "c d e f g a b c"
  end
end

With Gitara, it's easier to write notes using absolute note names instead of relative note names. This is because we'll be reusing bars and other Gitara expressions (see Reusing expressions below).

Notes with single quotes and backslashes

In Lilypond syntax, single quotes refer to octaves while backslashes refer to string numbers. So, the c note in the second string is written as

c'\2

Since a Gitara file is a Ruby program, you have to be careful with backslashes when writing notes like the one above. Ruby provides AFAIK two ways to preserve the backslash in the note above:

notes %q|c'\2|

or

notes "c'\\2"

Gitara provides a third option: it will automatically convert slashes to backslashes. This way, you can write the note above as

notes "c'/2"

Prettier and easier to search and replace.

Multiple voices

Each line of notes in a bar is a voice:

Gitara.define do
  bar do
    notes "c d e f g a b c"
    notes "c' d' e' f' g' a' b' c'"
  end
end

The tab above will play "c d e f g a b c" and "c' d' e' f' g' a' b' c'" simultaneously, not sequentially.

Partial bars

To indicate that a bar is a partial measure, call partial <duration>:

bar do
  partial 8
  notes "<g/3>8"
  notes "r8"
end

As shown by the example, the durations of the notes within the bar must also have one-eighth durations in order for the tab to render properly.

Grouping bars together

Lines

You can group bars in a line:

line :LineOne do
  bar :BayangMagiliw
  bar :PerlasNgSilanganan
  bar :AlabNgPuso
  bar :SaDibdibMoyBuhay
end

Lines are manually breaked in Gitara. You can disable a line break by setting manual_break to false:

line :LineOne, :manual_break => false do
end

Stanzas

Lines can be grouped in stanzas. The names of a stanza will be displayed at the top of the stanza's first bar.

Score

Finally, stanzas can be grouped in a score. Scores are important in grouping the tab in a single unit because...

Only the last expression under Gitara.define will be generated

When writing a tab, oftentimes you want to generate only a part of the tab for testing purposes. Gitara makes this easy by processing only for the last expression under Gitara.define. For example, in the following tab, only the second bar (notes "g a b c") will be generated.

Gitara.define do
  bar do
    notes "c d e f"
  end

  bar do
    notes "g a b c"
  end
end

If you want Gitara to generate both bars, you must group them inside a score.

Gitara.define do
  score do
    bar do
      notes "c d e f"
    end

    bar do
      notes "g a b c"
    end
  end
end

If you want to test a particular bar inside the score, you can copy it after the score:

Gitara.define do
  score do
    bar do
      notes "c d e f"
    end

    bar do
      notes "g a b c"
    end
  end

  bar do
    notes "c d e f"
  end
end

Or, as you'll see below, you can give the bar a name so that you can call it later.

Reusing expressions

Bars, lines, and other Gitara expressions can be reused. For example, if you want a repeat a bar, you can name the bar and call the name afterwards:

Gitara.define do
  score do
    bar :Intro do
      notes "c d e f g a b c"
      notes "c' d' e' f' g' a' b' c'"
    end

    bar :Intro
  end
end

This will generate a tab with two Intro bars. It's important to group the two bars above inside a score, because otherwise Gitara will only generate the second bar.

You can reuse a Gitara expression as long as it is defined before the call. The definition can even be deeper than the level of the call:

Gitara.define do
  score do
    bar :testing do
      notes "c d e f"
    end

    bar do
      notes "g a b c"
    end
  end

  bar :testing
end

In the example above, Gitara will only generate the last :testing bar.

Finally, you can call multiple expressions in a single line:

bar :BayangMagiliw, :PerlasNgSilanganan, :AlabNgPuso, :SaDibdibMoyBuhay

Repeats and alternative endings

You can also group expressions under repeats and provide alternative endings:

Gitara.define do
  line do
    repeat 4 do
      bar do
        notes "c4 d e f"
      end
    end

    alternative do
      bar do
        notes "d2 e"
      end

      bar do
        notes "f2 g"
      end
    end
  end
end

Properties

A gitara file can have the following properties:

Gitara.define do
  title "Wise Up"
  composer "Aimee Mann"
  arranger "Arranged by George Mendoza"
  instrument "Guitar (capo on second fret)"
  key 'c \major'
  midi_instrument "acoustic guitar (nylon)"
  string_tunings "#guitar-tuning"
  tempo "4 = 75"
  time "4/4"
  transposition "d"
end

• arranger - tab's arranger
• composer - song's composer
• instrument - description of the instrument used on the tab
• key
• midi_instrument - the type of instrument played in the midi export of the tab. By default, "acoustic guitar (nylon)".
• string_tunings
• tempo
• time - default is 4/4
• title - title of the song
• transposition - adjusts the pitch of the instrument. The default transposition is "c". If you set it to "d", then you have to play the tab two frets higher on the guitar (capo on second fret).

Chord labels

You can add chord labels to bars:

Gitara.define do
  chords :FC,   'f2 c2'

  bar :BeganIt do
    notes "/skip 4 <a/3 c'/2 >8 <g/3>8 /skip 4 <g/3 c'/2 >8 <g/3>8"
    notes "<f/4>4 <f/4>4 <c/5>4 <e/4>4"
    chords :FC
  end
end

f2 and c2 are lilypond chord names.

If the bar is a partial measure, the duration of the chords within the bar must match the bar's duration:

chords :G8, 'g8'

bar do
  partial 8
  notes "<g/3>8"
  notes "r8"
  chords :G8
end

Workflow

I'm no Lilypond expert (heh). When writing a tab, I use TuxGuitar to transcribe a set of notes (usually just one bar). I then export the TuxGuitar tab to lilypond so that I can get the lilypond notes. I then place these lilypond notes inside my Gitara tab. This workflow allows me to use TuxGuitar's GUI for transcribing notes while allowing me to use Gitara's features for naming expressions and reusing them.