@c -*-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 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 -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 option 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.

@file{midi2ly} will convert 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.  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 -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.  @var{acc} > 0 sets number of sharps; @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


@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. Sequences of grace notes are ended improperly sometimes. 


@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 \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; abc2ly does 
not.

abc2ly ignores the ABC beaming.

@node Invoking musedata2ly
@section Invoking musedata2ly

@cindex MuseData
@cindex CCARH

MuseData (see @uref{http://www.musedata.org/}) is an electronic
library of classical music scores, comprising at the time of writing
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

@file{musedata2ly} converts only a small subset of MuseData. 

@node Invoking mup2ly
@section Invoking mup2ly

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

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