@c -*-texinfo-*-

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

@menu
* Invoking convert-ly::            Older LilyPond versions.
* Invoking midi2ly::               Importing MIDI.
* Invoking etf2ly::                Importing Finale.
* Invoking abc2ly::                Importing ABC.          
* Invoking pmx2ly::                Importing PMX.
* Invoking musedata2ly::           Importing Musedata.
* Invoking mup2ly::                Importing MUP. 
@end menu


@node Invoking convert-ly
@section Invoking convert-ly

Convert-ly sequentially applies different conversions to upgrade a
Lilypond input file.  It uses @code{\version} statements in the file to
detect the old version number.  For example, to upgrade all lilypond
files in the current directory and its subdirectories, use
@example
        convert-ly -e --to=1.3.150 `find . -name '*.ly' -print`
@end example

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 -a,--assume-old
    If version number cannot be determined, apply all conversions.
@item -e,--edit
    Do an inline edit of the input file. Overrides @code{--output}.
@item -f,--from=@var{from-patchlevel}
    Set the level to convert from. If this is not set, 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, 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



@refbugs

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

@node Invoking midi2ly
@section Invoking midi2ly

@cindex MIDI

Midi2ly translates a MIDI input 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 you want
to import files from a program that has no converter for its native
format.

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.  midi2ly tries to
compensate for these timing errors, but is not very good at this. It is
therefore not recommended to use midi2ly for human-generated midi files.

Hackers who know about signal processing are invited to write a more
robust midi2ly.  midi2ly is written in Python, using a module written in
C to parse the MIDI files.

It is invoked as follows:
@example
        midi2ly [@var{option}]@dots{} @var{midi-file}
@end example

The following options are supported by midi2ly:

@table @code
@item -b, --no-quantify,
    Write exact durations, e.g.: `a4*385/384'.
@item -D, --debug,
    Print lots of debugging stuff.
@item -h, --help,
    Show a summary of usage.
@item -I, --include=@var{dir},
    Add @var{dir} to search path.
@item -k, --key=@var{acc}[:@var{minor}],
    Set default key.  @var{acc} > 0 sets number of sharps; @var{acc} < 0
sets number
    of flats.  A minor key is indicated by ":1".
@item -n, --no-silly,
    Assume no plets or double dots, assume smallest (reciprocal) duration 16.
@item -o, --output=@var{file},
    Set @var{file} as default output.
@item -p, --no-plets,
    Assume no plets.
@item -q, --quiet,
    Be quiet.
@item -s, --smallest=N,
    Assume no shorter (reciprocal) durations than N.
@item -v, --verbose,
    Be verbose.
@item -w, --warranty,
    Show the warranty with which midi2ly comes. (It comes with @strong{NO WARRANTY}!)
@item -x, --no-double-dots,
    Assume no double dotted notes.
@end table


@node Invoking etf2ly
@section Invoking 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. etf2ly will convert part of an ETF
file to a ready-to-use LilyPond file.

It is invoked as follows:
@example
        etf2ly [@var{option}]@dots{} @var{etf-file}
@end example

The following options are supported by 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
etf2ly.


@node Invoking abc2ly
@section Invoking 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
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 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 \property Voice.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
(eg. polyphonic music) different conventions exist. 

Multiple tunes in one file cannot be converted.

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

abc2ly ignores the ABC beaming.

@node Invoking pmx2ly
@section Invoking pmx2ly

PMX is a MusiXTeX preprocessor written by Don Simons. More information
on PMX is available from the following site:

@quotation
@uref{http://icking-music-archive.sunsite.dk/Misc/Music/musixtex/software/pmx/}.
@end quotation

@cindex PMX
@cindex MusiXTeX
@cindex Simons, Don

pmx2ly converts from PMX to LilyPond input. The program is invoked as
follows:

@example
        pmx2ly [@var{option}]@dots{} @var{pmx-file}
@end example

The following options are supported by pmx2ly:

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


@node Invoking musedata2ly
@section Invoking musedata2ly

@cindex Musedata
@cindex CCARH

Musedata (@uref{http://www.musedata.org/}) is an electronic library of
classical music scores, currently comprising about 800 composition
dating from 1700 to 1825.  The music is encoded in so-called Musedata
format.  musedata2ly converts a set of musedata files to one .ly file,
and will include a @code{\header} field if a @file{.ref} file is
supplied. It is invoked as follows:

@example
        musedata2ly [@var{option}]@dots{} @var{musedata-files}
@end example

The following options are supported by musedata2ly:

@table @code
@item   -h,--help
print help
@item  -o,--output=@var{file}
set output filename to @var{file}
@item  -v,--version
version information
@item  -r,--ref=@var{reffile}
 read background information from ref-file
@var{reffile}
@end table

@refbugs

musedata2ly converts only a small subset musedata. 

@node Invoking mup2ly
@section Invoking mup2ly

MUP (Music Publisher) is a shareware music notation program by Arkkra
Enterprises.  It is also the name of the input format.  Mup2ly will
convert part of a Mup file to a ready-to-use LilyPond file. Mup2ly is
invoked 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 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

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