@c -*-texinfo-*-
-@node Conversion tools
-@chapter Converting to LilyPond format.
+@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
-* midi2ly::
-* etf2ly::
-* abc2ly::
-* pmx2ly::
-* musedata2ly::
-* mup2ly::
+* 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 midi2ly
-@section midi2ly
+
+@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
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 can not rhythmically
-exact enough to make a MIDI to .ly conversion trivial. midi2ly tries to
+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. Correcting the quantization mistakes of the human player takes a
-lot of time.
+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.
-
-@subsection Invoking midi2ly
+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 [OPTION]... MIDI-FLIE
+ midi2ly [@var{option}]@dots{} @var{midi-file}
@end example
-@unnumberedsubsec Options
+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=@file{DIR},
- Add DIR to search path.
-@item -k, --key=ACC[:MINOR],
- Set default key. ACC > 0 sets number of sharps; 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=@file{FILE},
- Set @file{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,
+@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 -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.
+@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
-Report bugs to @email{bug-gnu-music@@gnu.org}.
-
-
-Written by @email{Jan Nieuwenhuizen, janneke@@gnu.org}.
-
-
-@node etf2ly
-@section etf2ly
+@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. This program will convert part of an ETF
+Technology's Finale product. etf2ly will convert part of an ETF
file to a ready-to-use LilyPond file.
-@subsection Invoking etf2ly
-Usage:
-
+It is invoked as follows:
@example
- etf2ly [OPTION]... ETF-FILE
+ etf2ly [@var{option}]@dots{} @var{etf-file}
@end example
-Convert ETF to LilyPond.
-
-@unnumberedsubsec Options
+The following options are supported by etf2ly:
@table @code
@item -h,--help
this help
@refbugs
-Known: articulation scripts are buggy. Empty measures confuse etf2ly.
-Report bugs to @email{bug-gnu-music@@gnu.org}.
-
-Written by @email{Han-Wen Nienhuys,hanwen@@cs.uu.nl}.
+The list of articulation scripts is incomplete. Empty measures confuse
+etf2ly. Sequences of grace notes are ended improperly sometimes.
-Report bugs to @email{bug-gnu-music@@gnu.org}.
+@node Invoking abc2ly
+@section Invoking abc2ly
-@node abc2ly
-@section abc2ly
+@cindex ABC
-ABC is a fairly simple ASCII based format. It is described at
+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}.
-
-@subsection Invoking abc2ly
+@end quotation
+abc2ly translates from ABC to LilyPond. It is invoked as follows:
@example
- abc2ly [OPTION]... ABC-FILE
+ abc2ly [@var{option}]@dots{} @var{abc-file}
@end example
-Convert ABC to LilyPond.
+The following options are supported by abc2ly:
-@unnumberedsubsec Options
@table @code
@item -h,--help
this help
-@item -o,--output=FILE
-set output filename to FILE
+@item -o,--output=@var{file}
+set output filename to @var{file}.
@item -v,--version
-version information
+print version information.
@end table
-@refbugs
-
-The ABC standard is not very "standard". For extended features
-(eg. polyphonic music) different conventions exist.
-
-
-Written by @email{Han-Wen Nienhuys,hanwen@@cs.uu.nl}.
+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
-Report bugs to @email{bug-gnu-music@@gnu.org}.
-
-@node pmx2ly
-@section pmx2ly
-
-PMX is a Musixtex preprocessor written by Don Simons, see
-@uref{http://icking-music-archive.sunsite.dk/Misc/Music/musixtex/software/pmx/}.
-
-Report bugs to @email{bug-gnu-music@@gnu.org}.
+This will cause the text following the keyword ``voices'' to be inserted
+into the current voice of the LilyPond output file.
-@subsection Invoking pmx2ly
+Similarly,
@example
- pmx2ly [OPTION]... PMX-FILE
+ %%LY slyrics more words
@end example
-Convert PMX to LilyPond.
+will cause the text following the ``slyrics'' keyword to be inserted
+into the current line of lyrics.
-@unnumberedsubsec Options
-@table @code
-@item -h,--help
-this help
-@item -o,--output=FILE
-set output filename to FILE
-@item -v,--version
-version information
-@end table
+@refbugs
-Report bugs to @email{bug-gnu-music@@gnu.org}.
+The ABC standard is not very ``standard''. For extended features
+(e.g. polyphonic music) different conventions exist.
-Written by @email{Han-Wen Nienhuys,hanwen@@cs.uu.nl}.
+Multiple tunes in one file cannot be converted.
+ABC synchronizes words and notes at the beginning of a line; abc2ly does
+not.
-@node musedata2ly
-@section musedata2ly
+abc2ly ignores the ABC beaming.
-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
-(@uref{http://www.ccarh.org/publications/books/beyondmidi/online/musedata}).
-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
+@node Invoking musedata2ly
+@section Invoking musedata2ly
-@subsection 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 [OPTION]... MUSEDATA-FILE
+ musedata2ly [@var{option}]@dots{} @var{musedata-files}
@end example
-Convert Musedata to LilyPond.
-
-@unnumberedsubsec Options
+The following options are supported by musedata2ly:
@table @code
@item -h,--help
version information
@item -r,--ref=@var{reffile}
read background information from ref-file
-@var{REFFILE}
+@var{reffile}
@end table
-Report bugs to @email{bug-gnu-music@@gnu.org}.
-
-Written by @email{Han-Wen Nienhuys,hanwen@@cs.uu.nl}.
+@refbugs
+@file{musedata2ly} converts only a small subset of MuseData.
-@node mup2ly
-@section mup2ly
+@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.
+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:
-@subsection Invoking mup2ly
+@cindex Music Publisher
+@cindex Mup
+@cindex Arkkra
@example
- mup2ly [OPTION]... MUP-FILE
+ mup2ly [@var{option}]@dots{} @var{mup-file}
@end example
-Convert Mup to LilyPond.
-
-@unnumberedsubsec Options
+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 -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=FILE
-write output to @var{FILE}
+@item -o,--output=@var{file}
+write output to @var{file}
@item -v,--version
version information
@item -w,--warranty
-print warranty and copyright. Mup2ly comes with absolutlely @strong{NO WARRANTY}.
+print warranty and copyright.
@end table
@refbugs
-Currently, only plain notes (pitches, durations), voices and staffs are
+Only plain notes (pitches, durations), voices, and staves are
converted.
-Written by @email{Jan Nieuwenhuizen,janneke@@gnu.org}, based on pmx2ly.
-
-Report bugs to @email{bug-gnu-music@@gnu.org}.
-
projects / lilypond.git / blobdiff