-@c -*-texinfo-*-
+@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 pmx2ly:: Importing PMX.
-* Invoking musedata2ly:: Importing Musedata.
-* Invoking mup2ly:: Importing MUP.
+* 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 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 if a file called MYFILE.ly.NEW
+is created, then MYFILE.ly is already updated.
+
+To upgrade LilyPond fragments in texinfo files, use
-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`
+convert-ly --from=... --to=... --no-version *.itely
@end example
-The program is invoked as follows:
+In general, the program is invoked as follows:
+
@example
- convert-ly [@var{option}]@dots{} @var{file}@dots{}
+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}.
+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.
+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.
+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.
+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.
+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.
+Set the goal version of the conversion. It defaults to the latest
+available version.
+
@item -h, --help
- Print usage 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 options can be specified.
+Not all language changes are handled. Only one output option can be
+specified.
@node Invoking midi2ly
-@section Invoking midi2ly
+@section Invoking @command{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.
+@command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
+file.
-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.
+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.
-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.
+@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.
-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 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 as follows:
+
+It is invoked from the command-line as follows,
@example
- midi2ly [@var{option}]@dots{} @var{midi-file}
+midi2ly [@var{option}]@dots{} @var{midi-file}
@end example
-The following options are supported by midi2ly:
+
+The following options are supported by @command{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.
+@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 etf2ly
+@section Invoking @command{etf2ly}
@cindex ETF
@cindex enigma
@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
+Technology's Finale product. @command{etf2ly} will convert part of an ETF
file to a ready-to-use LilyPond file.
-It is invoked as follows:
+It is invoked from the command-line as follows.
+
@example
- etf2ly [@var{option}]@dots{} @var{etf-file}
+etf2ly [@var{option}]@dots{} @var{etf-file}
@end example
-The following options are supported by etf2ly.
+The following options are supported by @command{etf2ly}:
+
@table @code
-@item -h,--help
+@item -h,--help
this help
-@item -o,--output=FILE
+@item -o,--output=FILE
set output filename to FILE
-@item -v,--version
+@item -v,--version
version information
@end table
@refbugs
-The list of articulation scripts is incomplete. Empty measures confuse
-etf2ly.
+The list of articulation scripts is incomplete. Empty measures
+confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
@node Invoking abc2ly
-@section Invoking abc2ly
+@section Invoking @code{abc2ly}
@cindex ABC
-ABC is a fairly simple ASCII based format. It is described at
-@uref{http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt}. abc2ly
-translates from ABC to LilyPond. It is invoked as follows:
+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}
+abc2ly [@var{option}]@dots{} @var{abc-file}
@end example
-The following options are supported by abc2ly:
+The following options are supported by @command{abc2ly}:
@table @code
-@item -h,--help
+@item -h,--help
this help
-@item -o,--output=@var{file}
+@item -o,--output=@var{file}
set output filename to @var{file}.
-@item -v,--version
+@item -v,--version
print version information.
@end table
-There is a rudimentary facility for adding lilypond code to the ABC
+There is a rudimentary facility for adding LilyPond code to the ABC
source file. If you say:
@example
- %%LY voices \property Voice.autoBeaming=##f
+%%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.
+into the current voice of the LilyPond output file.
-Similarly:
+Similarly,
@example
- %%LY slyrics more words
+%%LY slyrics more words
@end example
will cause the text following the ``slyrics'' keyword to be inserted
@refbugs
-The ABC standard is not very ``standard''. For extended features
-(eg. polyphonic music) different conventions exist.
+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 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
+ABC synchronizes words and notes at the beginning of a line;
+@command{abc2ly} does not.
-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:
+@command{abc2ly} ignores the ABC beaming.
-@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
+@section Invoking @command{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:
+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 Mup
@cindex Arkkra
@example
- mup2ly [@var{option}]@dots{} @var{mup-file}
+mup2ly [@var{option}]@dots{} @var{mup-file}
@end example
-The following options are supported by mup2ly:
+The following options are supported by @command{mup2ly}:
@table @code
-@item -d,--debug
+@item -d,--debug
show what constructs are not converted, but skipped.
-@item D, --define=@var{name}[=@code{exp}]
+@item -D, --define=@var{name}[=@code{exp}]
define macro @var{name} with opt expansion @code{exp}
-@item -E,--pre-process
+@item -E,--pre-process
only run the pre-processor
-@item -h,--help
+@item -h,--help
print help
-@item -o,--output=@var{file}
+@item -o,--output=@var{file}
write output to @var{file}
-@item -v,--version
+@item -v,--version
version information
-@item -w,--warranty
+@item -w,--warranty
print warranty and copyright.
@end table
@refbugs
-Currently, only plain notes (pitches, durations), voices and staves are
+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
projects / lilypond.git / blobdiff