-@c -*-texinfo-*-
+@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond-program.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
-@node Conversion tools
-@chapter Converting to LilyPond format.
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+@c \version "2.12.0"
+
+@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.
+
+These are separate programs from @command{lilypond} itself, and are
+run on the command line; see @ref{Command-line usage} for more
+information. If you have MacOS 10.3 or 10.4 and you have trouble
+running some of these scripts, e.g. @code{convert-ly}, see @ref{Setup
+for MacOS X}.
+
+
+@knownissues
+We unfortunately do not have the resources to maintain these
+programs; please consider them @qq{as-is}. Patches are appreciated, but
+bug reports will almost certainly not be resolved.
@menu
-* midi2ly::
-* etf2ly::
-* abc2ly::
-* pmx2ly::
-* musedata2ly::
-* mup2ly::
+* Invoking midi2ly:: Importing MIDI.
+* Invoking musicxml2ly:: Importing MusicXML.
+* Invoking abc2ly:: Importing ABC.
+* Invoking etf2ly:: Importing Finale.
+* Generating LilyPond files:: GUIs, transcribers, and algorithmic composition programs.
@end menu
-@node midi2ly
-@section midi2ly
-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.
+@node Invoking midi2ly
+@section Invoking @command{midi2ly}
+
+@cindex MIDI
+
+@command{midi2ly} translates a Type@tie{}1 MIDI file to a LilyPond source
+file.
-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. Correcting the quantization mistakes of the human player takes a
-lot of time.
+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 converter for a
+direct format.
-Hackers who know about signal processing are invited to write a more
-robust midi2ly.
+@command{midi2ly} converts tracks into @rinternals{Staff} and
+channels into @rinternals{Voice} contexts. Relative mode is used
+for pitches, durations are only written when necessary.
-@subsection Invoking midi2ly
+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}
+midi2ly [@var{option}]@dots{} @var{midi-file}
@end example
-@unnumberedsubsec Options
+Note that by @q{command-line}, we mean the command line of the
+operating system. See @ref{Converting from other formats}, for
+more information about this.
+
+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=@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,
- 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
+@item -a, --absolute-pitches
+Print absolute pitches.
+@item -d, --duration-quant=@var{DUR}
+Quantize note durations on @var{DUR}.
-Report bugs to @email{bug-gnu-music@@gnu.org}.
+@item -e, --explicit-durations
+Print explicit durations.
+@item -h,--help
+Show summary of usage.
-Written by @email{Jan Nieuwenhuizen, janneke@@gnu.org}.
+@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
+@code{:1}.
+@item -o, --output=@var{file}
+Write output to @var{file}.
-@node etf2ly
-@section etf2ly
+@item -s, --start-quant=@var{DUR}
+Quantize note starts on @var{DUR}.
+@item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN}
+Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
-ETF (Enigma Transport Format) is a format used by Coda Music
-Technology's Finale product. This program will convert part of an ETF
-file to a ready-to-use LilyPond file.
+@item -v, --verbose
+Be verbose.
-@subsection Invoking etf2ly
-Usage:
+@item -V, --version
+Print version number.
-@example
- etf2ly [@var{OPTION}]@dots{} @var{ETF-FILE}
-@end example
+@item -w, --warranty
+Show warranty and copyright.
-Convert ETF to LilyPond.
-
-@unnumberedsubsec Options
-@table @code
-@item -h,--help
-this help
-@item -o,--output=FILE
-set output filename to FILE
-@item -v,--version
-version information
+@item -x, --text-lyrics
+Treat every text as a lyric.
@end table
-@refbugs
+@knownissues
-Known: articulation scripts are buggy. Empty measures confuse etf2ly.
-Report bugs to @email{bug-gnu-music@@gnu.org}.
+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.
-Written by @email{Han-Wen Nienhuys,hanwen@@cs.uu.nl}.
+@node Invoking musicxml2ly
+@section Invoking @code{musicxml2ly}
-Report bugs to @email{bug-gnu-music@@gnu.org}.
+@cindex MusicXML
-@node abc2ly
-@section abc2ly
+@uref{http://@/www.@/musicxml@/.org/,MusicXML} is an XML dialect
+for representing music notation.
-ABC is a fairly simple ASCII based format. It is described at
-@uref{http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt}.
+@command{musicxml2ly} extracts the notes, articulations, score structure,
+lyrics, etc. from part-wise MusicXML files, and writes them to a .ly
+file. It is invoked from the command-line.
-@subsection Invoking abc2ly
+It is invoked from the command-line as follows,
@example
- abc2ly [@var{OPTION}]@dots{} @var{ABC-FILE}
+musicxml2ly [@var{option}]@dots{} @var{xml-file}
@end example
-Convert ABC to LilyPond.
+Note that by @q{command-line}, we mean the command line of the
+operating system. See @ref{Converting from other formats}, for
+more information about this.
-There is a rudimentary facility for adding lilypond code to the ABC
-source file. If you say:
+If the given filename is @file{-}, @command{musicxml2ly} reads input
+from the command line.
-@example
- %%LY voices \property Voice.noAutoBeaming=##t
-@end example
+The following options are supported by @command{musicxml2ly}:
-This will cause the text following the keyword ``voices'' to be inserted
-into the current voice of the lilypond output file.
+@table @code
+@item -a, --absolute
+convert pitches in absolute mode.
-Similarly:
+@item -h,--help
+print usage and option summary.
-@example
- %%LY slyrics more words
-@end example
+@item -l, --language=LANG
+use a different language file 'LANG.ly' and corresponding pitch names,
+e.g. 'deutsch' for deutsch.ly and German note names.
-will cause the text following the ``slyrics'' keyword to be inserted
-into the current line of lyrics.
+@item --lxml
+use the lxml.etree Python package for XML-parsing; uses less memory and cpu time.
-@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
+@item --nd --no-articulation-directions
+do not convert directions (@code{^}, @code{_} or @code{-}) for
+articulations, dynamics, etc.
-@refbugs
+@item --no-beaming
+do not convert beaming information, use LilyPond's automatic
+beaming instead.
-The ABC standard is not very "standard". For extended features
-(eg. polyphonic music) different conventions exist.
+@item -o,--output=@var{file}
+set output filename to @var{file}. If @var{file} is @file{-}, the output
+will be printed on stdout. If not given, @var{xml-file}@file{.ly} will
+be used.
-Multiple tunes in one file cannot be converted.
+@item -r,--relative
+convert pitches in relative mode (default).
-ABC synchronizes words and notes at the beginning of a line; abc2ly does
-not.
+@item -v,--verbose
+be verbose.
-abc2ly ignores the ABC beaming.
+@item --version
+print version information.
-Written by @email{Han-Wen Nienhuys,hanwen@@cs.uu.nl}.
+@item -z,--compressed
+input file is a zip-compressed MusicXML file.
+@end table
-Report bugs to @email{bug-gnu-music@@gnu.org}.
+@node Invoking abc2ly
+@section Invoking @code{abc2ly}
-@node pmx2ly
-@section pmx2ly
+@cindex ABC
-PMX is a Musixtex preprocessor written by Don Simons, see
-@uref{http://icking-music-archive.sunsite.dk/Misc/Music/musixtex/software/pmx/}.
+ABC is a fairly simple ASCII based format. It is described at the ABC site:
-Report bugs to @email{bug-gnu-music@@gnu.org}.
+@quotation
+@uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/learn@/.html}.
+@end quotation
-@subsection Invoking pmx2ly
+@command{abc2ly} translates from ABC to LilyPond. It is invoked as follows:
@example
- pmx2ly [@var{OPTION}]@dots{} @var{PMX-FILE}
+abc2ly [@var{option}]@dots{} @var{abc-file}
@end example
-Convert PMX to LilyPond.
-
-@unnumberedsubsec Options
+The following options are supported by @command{abc2ly}:
@table @code
-@item -h,--help
+@item -b,--beams=None
+preserve ABC's notion of beams
+@item -h,--help
this help
-@item -o,--output=FILE
-set output filename to FILE
-@item -v,--version
-version information
+@item -o,--output=@var{file}
+set output filename to @var{file}.
+@item -s,--strict
+be strict about success
+@item --version
+print version information.
@end table
-Report bugs to @email{bug-gnu-music@@gnu.org}.
-
-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:
-@node musedata2ly
-@section musedata2ly
+@example
+%%LY voices \set autoBeaming = ##f
+@end example
-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
+This will cause the text following the keyword @q{voices} to be inserted
+into the current voice of the LilyPond output file.
-@subsection Invoking musedata2ly
+Similarly,
@example
- musedata2ly [@var{OPTION}]@dots{} @var{MUSEDATA-FILE}
+%%LY slyrics more words
@end example
-Convert Musedata to LilyPond.
+will cause the text following the @q{slyrics} keyword to be inserted
+into the current line of lyrics.
-@unnumberedsubsec Options
-@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
+@knownissues
+
+The ABC standard is not very @q{standard}. For extended features
+(e.g., polyphonic music) different conventions exist.
+
+Multiple tunes in one file cannot be converted.
-Report bugs to @email{bug-gnu-music@@gnu.org}.
+ABC synchronizes words and notes at the beginning of a line;
+@command{abc2ly} does not.
-Written by @email{Han-Wen Nienhuys,hanwen@@cs.uu.nl}.
+@command{abc2ly} ignores the ABC beaming.
-@node mup2ly
-@section mup2ly
+@node Invoking etf2ly
+@section Invoking @command{etf2ly}
-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.
+@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.
-@subsection Invoking mup2ly
+It is invoked from the command-line as follows.
@example
- mup2ly [@var{OPTION}]@dots{} @var{MUP-FILE}
+etf2ly [@var{option}]@dots{} @var{etf-file}
@end example
-Convert Mup to LilyPond.
+Note that by @q{command-line}, we mean the command line of the
+operating system. See @ref{Converting from other formats}, for
+more information about this.
-@unnumberedsubsec Options
+The following options are supported by @command{etf2ly}:
@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=FILE
-write output to @var{FILE}
-@item -v,--version
+@item -h,--help
+this help
+@item -o,--output=@var{FILE}
+set output filename to @var{FILE}
+@item --version
version information
-@item -w,--warranty
-print warranty and copyright. Mup2ly comes with absolutlely @strong{NO WARRANTY}.
@end table
-@refbugs
-
-Currently, only plain notes (pitches, durations), voices and staffs are
-converted.
-
-Written by @email{Jan Nieuwenhuizen,janneke@@gnu.org}, based on pmx2ly.
-
-Report bugs to @email{bug-gnu-music@@gnu.org}.
-
-
+@knownissues
+
+The list of articulation scripts is incomplete. Empty measures
+confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
+
+
+@node Generating LilyPond files
+@section Generating LilyPond files
+
+@cindex External programs, generating LilyPond files
+
+LilyPond itself does not come with support for any other formats, but
+there are some external tools that also generate LilyPond files.
+
+These tools include
+
+@itemize
+@item
+@uref{http://@/www@/.denemo@/.org/,Denemo}, a graphical score editor.
+@item
+@uref{http://www@/.volny@/.cz/smilauer/rumor/rumor@/.html,Rumor}, a realtime
+monophonic MIDI to LilyPond converter.
+@item
+@uref{http://nicolas@/.sceaux@/.free@/.fr/lilypond/lyqi@/.html,lyqi}, an
+Emacs major mode.
+@item
+@uref{http://@/www@/.nongnu@/.org/@/xml2ly/,xml2ly}, which imports
+@uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
+@item
+@uref{http://@/noteedit@/.berlios@/.de,NoteEdit}
+which imports @uref{http://@/www@/.musicxml@/.com/xml@/.html,MusicXML}
+@item
+@uref{http://@/www@/.rosegardenmusic@/.com,Rosegarden},
+which imports MIDI
+@item
+@uref{http://@/common-lisp@/.net/project/fomus/,FOMUS},
+a LISP library to generate music notation
+@item
+@uref{http://vsr.informatik.tu-chemnitz.de/staff/jan/nted/nted.xhtml},
+has experimental export for LilyPond.
+@item
+@uref{http://www.tuxguitar.com.ar/}, can export to LilyPond.
+@item
+@uref{http://musescore.org} can also export to LilyPond.
+@end itemize
projects / lilypond.git / blobdiff