Skip to content

Latest commit

 

History

History
207 lines (139 loc) · 8.06 KB

README.markdown

File metadata and controls

207 lines (139 loc) · 8.06 KB
Raw

Ripple - DRY for Lilypond

Ripple is a small program that helps you generate scores and parts without repeating yourself, performing complex includes or writing scheme macros.

Here are some of Ripple's features:

  • Create scores and parts from files organized in a consistent, easy-to-understand directory hierarchy.
  • Improved Lilypond syntax for writing music, with support for macros (very useful for notating recurring rhythms), better accidentals, prefixed beams and slurs, and shorthand notation for stuff like divisi, appogiaturas, etc.
  • Automatically create MIDI versions of your scores.
  • Proof mode for faster editing - get your PDF regenerated every time you save your source.
  • Compilation mode for mixing different musical works together in a single score or part.

For comprehensive examples of the improved syntax checkout out my music scores project (mainly works by Bach).

A Ripple project:

Ripple expects your files to be organized a certain way for it to function correctly. Here is a simple example:

my_music
  bach
    BWV1027-1
      _work.yml
      gamba.rpl
      cembalo.rpl

The music is contained in .ly or .rpl files (the latter are assumed to be in Ripple syntax and are converted to normal Lilypond syntax). The _work.yml file is a YAML file that contains the attributes of the work:

title: Sonata for Viola da Gamba and Harpsichord G-dur BWV1027
composer: Johann Sebastian Bach
parts:
  gamba:
    title: Viola da gamba
score:
  order: gamba, cembalo

To process the files into parts and scores, simply cd into the directory and run ripple.

cd my_music
ripple

Lyrics are entered in a separate file with the same part name and using the .lyrics or .lyr extension (the latter using enhanced syntax). Basso continuo figures are also entered in a separate file with the same part name and a .figures or .fig extension (the latter also using the improved Ripple syntax).

Ripple will generate Lilypond files and put them into my_music/_ly, and then run Lilypond to produce PDF files that will be put in my_music/_pdf.

Multi-movement works

Ripple also supports multi-movement works. Consider the following file hierarchy:

my_music
  BWV1029
    _work.yml
    01-allegro
      gamba.rpl
      cembalo.rpl
    02-adagio
      gamba.rpl
      cembalo.rpl
    03-vivace
      gamba.rpl
      cembalo.rpl

Ripple will generate gamba and cembalo parts containing all three movements, as well as a score containing the three movements. The directory names are converted into movement titles, e.g. "1. Allegro", "2. Adagio" and "3. Vivace".

Configuration files

Each work should have its own _work.yml file. This file can be used to configure the different parts and their order in the score. Here is a sample file:

title: Missa Brevis G-dur BWV 236
composer: Johann Sebastian Bach
editor: Sharon Rosner
copyright: © IBS 2009 - all rights reserved
score:
  hide_empty_staves: true
  order:
    - oboe1
    - oboe2
    - violino1
    - violino2
    - viola
    - soprano
    - alto
    - tenore
    - basso
    - continuo

Each movement can also have its own _movement.yml file containing overrides for the specific movement. You can for example specify colla parte without copying the music:

parts:
  oboe1:
    source: soprano
  oboe2:
    source: alto
  violino1:
    source: soprano
  violino2: 
    source: alto
  viola:
    source: tenore

This configuration file specifies that the oboe1 and violino1 parts take their music from the soprano part, oboe2 and violino2 from the alto part, and the viola from the tenore part.

In addition, default settings can be stored in a _ripple.yml file, which can be used for setting for example the editor's name or the copyright notice.

Ripple also currently includes the following default settings for several voice types and instruments:

  1. Clef - the clef is automatically inserted by Ripple unless it is set to none.
  2. AutoBeam:false/true (default is true) - this setting is can be used in order to insert a \autoBeamOff macro in vocal parts.

Overriding default settings

The settings used by Ripple to process the source files are merged from the different settings files (ripple/lib/defaults.yml, _ripple.yml, _work.yml, _movement.yml) and can further be overriden by specifying an --opt switch:

ripple BWV17 --opt "editor:Someone else but me"

Auto-regeneration mode

Ripple can be put into auto-regeneration mode, in which it watches the source directory and process the specified files each time a file is saved in that directory. To use ripple in auto-regenration mode, add auto:true to your _ripple.yml file, or specify the --auto switch:

ripple BWV17 --auto

Proof mode

Proof mode is similar to auto-regeneration mode, except that each time a file is changed or added, it is compiled into PDF (as a single movement and part) and opened in the background. This mode is very useful when entering parts. To use ripple in proof mode, add proof:true to your _ripple.yml file, or specify the --proof or -P switch:

ripple BWV17 -P

Compilation mode

Compilation mode allows you to compile different pieces/movements into a single score or part. The compilation settings are defined in a YAML file. Here's a simple example:

title: My First Ripple Compilation
subtitle: Just Testing
movements:
  - work: bach/BWV1041
    movement: 01-allegro
  - work: bach/BWV1066
    movement: "09-bourree-II"
    score_breaks: 2
    parts:
      ira:
        source: fagotto
        breaks: 1
parts:
  ira:
    source: continuo
    clef: bass
    hide_figures: true

In order to process the compilation, use the -c switch:

ripple -c compilations/test

When no parts are specified, Ripple will process all parts specified in the compilation file. As the example above shows, you can also control page breaks for individual parts and for the score. For more examples of usage look at my own compilations.

Ad-hoc compilations

Ripple also lets you perform ad-hoc compilations without preparing a compilation file by using the -C switch:

ripple -C bach/BWV156 bach/BWV044 bach/BWV017

If no parts are specified, only the score will be prepared. You can also compile specific movements by specifying them using the format work#movement. Ripple will also understand movement numbers instead of complete movement references:

ripple -C bach/BWV156#1 bach/BWV044#2

You can also specify a title for the compilation by including the -t switch:

ripple -C -t "My own title" bach/BWV156#1 bach/BWV044#2

More ripple tips

Process multiple works

ripple bach/BWV017 bach/BWV166

Create a MIDI version of your score:

ripple bach/BWV017 -M

Open the rendered PDF file once it is ready:

ripple bach/BWV017 -o

This also works for MIDI files:

ripple bach/BWV017 -M -o

If you find yourself always using the -o switch, you can add the following setting to your _ripple.yml file instead:

open_target: true

Process only the score:

ripple bach/BWV017 -s

Process only the parts:

ripple bach/BWV017 --no-score

Process a specific part:

ripple bach/BWV017 -p continuo
ripple bach/BWV017 -p violino1,violino2

Process a specific movement:

ripple bach/BWV017 -m 01-coro