[lilypond.git] / Documentation / user / converters.itely

@c -*- coding: latin-1; mode: texinfo; -*-

@node Converting from other formats
@chapter Converting from other formats

Music can be entered also by importing it from other formats.  This
chapter documents the tools included in the distribution to do so.
There are other tools that produce LilyPond input, for example GUI
sequencers and XML converters.  Refer to the
@uref{http://@/lilypond@/.org,website} for more details.



@menu
* Invoking convert-ly::         Older LilyPond versions.
* Invoking midi2ly::            Importing MIDI.
* Invoking etf2ly::             Importing Finale.
* Invoking abc2ly::             Importing ABC.          
* Invoking mup2ly::             Importing MUP. 
* Other formats::               
@end menu


@node Invoking convert-ly
@section Invoking @command{convert-ly}

The LilyPond input syntax is routinely changed to simplify it or improve
it in different ways.  As a side effect of this, the LilyPond interpreter
often is no longer compatible with older input files.  To remedy this,
the program @command{convert-ly} can be used to deal with most of the
syntax changes between LilyPond versions.

It uses @code{\version} statements in the input files to detect the old
version number.  In most cases, to upgrade your input file it is sufficient
to run

@example
covert-ly -e myfile.ly
@end example

If there are no changes to myfile.ly and file called myfile.ly.NEW
is created, then myfile.ly is already updated.

To upgrade LilyPond fragments in texinfo files, use

@example
convert-ly --from=... --to=... --no-version *.itely
@end example

In general, the program is invoked as follows:

@example
convert-ly [@var{option}]@dots{} @var{file}@dots{}
@end example


The following options can be given:

@table @code
@item -e,--edit
Do an inline edit of the input file.  Overrides @code{--output}.

@item -f,--from=@var{from-patchlevel}
Set the version to convert from.  If this is not set, @command{convert-ly}
will guess this, on the basis of @code{\version} strings in the file.

@item -o,--output=@var{file}
Set the output file to write.  

@item -n,--no-version
Normally, @command{convert-ly} adds a @code{\version} indicator 
to the output. Specifying this option suppresses this.  

@item -s, --show-rules
Show all known conversions and exit.

@item --to=@var{to-patchlevel}
Set the goal version of the conversion.  It defaults to the latest
available version.

@item -h, --help
Print usage help.
@end table

@command{convert-ly} always converts up to the last syntax change handled by
it.  This means that the @code{\version} number left in the file is
usually lower than the version of @command{convert-ly} itself.

@refbugs

Not all language changes are handled.  Only one output option can be
specified.

@ignore
Copy and paste from CVS, last updated
Dec 22, 2004

http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
@end ignore
@verbatim

There are a few things that the convert-ly cannot handle. Here's a list of limitations
that the community has complained about.

This bug report structure has been chosen because convert-ly has a structure that doesn't
allow to smoothly implement all needed changes. Thus this is just a wishlist, placed
here for reference.

1.6->2.0:
 Doesn't always convert figured bass correctly, specifically things like {< >}. Mats' comment on working around this:
   To be able to run convert-ly
   on it, I first replaced all occurencies of '{<' to some dummy like '{#'
   and similarly I replaced '>}' with '&}'. After the conversion, I could
   then change back from '{ #' to '{ <' and from '& }' to '> }'.
 Doesn't convert all text markup correctly. Only very simple cases are fixed.
2.0->2.2:
 Doesn't handle \partcombine
 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
2.2->2.4:
 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly converted.
@end verbatim


@node Invoking midi2ly
@section Invoking @command{midi2ly}

@cindex MIDI

@command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
file.

MIDI (Music Instrument Digital Interface) is a standard for digital
instruments: it specifies cabling, a serial protocol and a file
format.  The MIDI file format is a de facto standard format for
exporting music from other programs, so this capability may come in
useful when importing files from a program that has a convertor for a
direct format.

@command{midi2ly} converts tracks into @internalsref{Staff} and
channels into @internalsref{Voice} contexts.  Relative mode is used
for pitches, durations are only written when necessary.

It is possible to record a MIDI file using a digital keyboard, and
then convert it to @file{.ly}.  However, human players are not
rhythmically exact enough to make a MIDI to LY conversion trivial.
When invoked with quantizing (@code{-s} and @code{-d} options)
@command{midi2ly} tries to compensate for these timing errors, but is not
very good at this.  It is therefore not recommended to use @command{midi2ly}
for human-generated midi files.


It is invoked from the command-line as follows,
@example
midi2ly [@var{option}]@dots{} @var{midi-file}
@end example


The following options are supported by @command{midi2ly}.

@table @code
@item -a, --absolute-pitches
Print absolute pitches.

@item -d, --duration-quant=@var{DUR}
Quantize note durations on @var{DUR}.

@item -e, --explicit-durations
Print explicit durations.

@item -h,--help
Show summary of usage.

@item -k, --key=@var{acc}[:@var{minor}]
Set default key.  @math{@var{acc} > 0} sets number of sharps;
@math{@var{acc} < 0} sets number of flats.  A minor key is indicated by
":1".

@item -o, --output=@var{file}
Write output to @var{file}.

@item -s, --start-quant=@var{DUR}
Quantize note starts on DUR.

@item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.

@item -V, --verbose
Be verbose.

@item -v, --version
Print version number.

@item -w, --warranty
Show warranty and copyright.

@item -x, --text-lyrics
Treat every text as a lyric.
@end table


@refbugs

Overlapping notes in an arpeggio will not be correctly rendered.  The
first note will be read and the others will be ignored.  Set them all
to a single duration and add phrase markings or pedal indicators.


@node Invoking etf2ly
@section Invoking @command{etf2ly}

@cindex ETF
@cindex enigma
@cindex Finale
@cindex Coda Technology

ETF (Enigma Transport Format) is a format used by Coda Music
Technology's Finale product.  @command{etf2ly} will convert part of an ETF
file to a ready-to-use LilyPond file.

It is invoked from the command-line as follows.

@example
etf2ly [@var{option}]@dots{} @var{etf-file}
@end example

The following options are supported by @command{etf2ly}:

@table @code
@item -h,--help
this help
@item -o,--output=FILE
set output filename to FILE
@item -v,--version
version information
@end table


@refbugs

The list of articulation scripts is incomplete.  Empty measures
confuse @command{etf2ly}.  Sequences of grace notes are ended improperly.


@node Invoking abc2ly
@section Invoking @code{abc2ly}

@cindex ABC

ABC is a fairly simple ASCII based format.  It is described at the ABC site:

@quotation
@uref{http://@/www@/.gre@/.ac@/.uk/@/~c.walshaw/@/abc2mtex/@/abc@/.txt}.
@end quotation

@command{abc2ly} translates from ABC to LilyPond.  It is invoked as follows:

@example
abc2ly [@var{option}]@dots{} @var{abc-file}
@end example

The following options are supported by @command{abc2ly}:

@table @code
@item -h,--help
this help
@item -o,--output=@var{file}
set output filename to @var{file}.
@item -v,--version
print version information.
@end table

There is a rudimentary facility for adding LilyPond code to the ABC
source file.  If you say:

@example
%%LY voices \set autoBeaming = ##f
@end example

This will cause the text following the keyword ``voices'' to be inserted 
into the current voice of the LilyPond output file.

Similarly,

@example
%%LY slyrics more words
@end example

will cause the text following the ``slyrics'' keyword to be inserted
into the current line of lyrics.


@refbugs

The ABC standard is not very ``standard''.  For extended features
(e.g., polyphonic music) different conventions exist. 

Multiple tunes in one file cannot be converted.

ABC synchronizes words and notes at the beginning of a line;
@command{abc2ly} does not.

@command{abc2ly} ignores the ABC beaming.


@node Invoking mup2ly
@section Invoking @command{mup2ly}

Mup (Music Publisher) is a shareware music notation program by Arkkra
Enterprises.  @command{mup2ly} will convert part of a Mup file to LilyPond
format.  It is invoked from the command-line as follows:

@cindex Music Publisher
@cindex Mup
@cindex Arkkra

@example
mup2ly [@var{option}]@dots{} @var{mup-file}
@end example

The following options are supported by @command{mup2ly}:

@table @code
@item -d,--debug
show what constructs are not converted, but skipped.
@item -D, --define=@var{name}[=@code{exp}]
define macro @var{name} with opt expansion @code{exp}
@item -E,--pre-process
only run the pre-processor
@item -h,--help
print help
@item -o,--output=@var{file}
write output to @var{file}
@item -v,--version
version information
@item -w,--warranty
print warranty and copyright. 
@end table


@refbugs

Only plain notes (pitches, durations), voices, and staves are
converted.


@node Other formats
@section Other formats

LilyPond itself does not come with support for other formats, but
there are some external tools that also generate LilyPond files.

These tools include

@itemize @bullet
@item
@uref{http://@/denemo@/.sourceforge@/.net/,Denemo}.
@item
@uref{http://@/www@/.nongnu@/.org/@/xml2ly/, xml2ly}, that imports
@uref{http://@/www@/.musicxml@/.com/,MusicXML}
@item
@uref{http://@/rnvs@/.informatik@/.tu@/-chemnitz@/.de/@/~jan/@/noteedit/@/noteedit@/.html,NoteEdit}
which imports MusicXML
@item
@uref{http://@/www@/.all@/-day@/-breakfast@/.com/@/rosegarden/,Rosegarden},
which imports MIDI
@end itemize