-@c -*-texinfo-*-
+@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
@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.
+sequencers and XML converters. Refer to the
+@uref{http://@/lilypond@/.org,website} for more details.
+
+These are separate programs from lilypond itself, and are run
+on the command-line. By @q{command-line}, we mean the command
+line in the operating system. Windows users
+might be more familiar with the terms @q{DOS shell} or
+@q{command shell}; OSX users might be more familiar with the
+terms @q{terminal} or @q{console}. OSX users should also
+consult @ref{Notes for the MacOS X app}.
+
+Describing how to use
+this part of an operating system is outside the scope of this
+manual; please consult other documentation on this topic if
+you are unfamiliar with the command-line.
@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 musicxml2ly::
+* Invoking abc2ly:: Importing ABC.
+* Generating LilyPond files::
@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
+@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.
-@file{midi2ly} will convert tracks into @internalsref{Staff} and
+@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.
-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.
+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.
-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:
+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:
+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 -a, --absolute-pitches
- Print absolute pitches.
+Print absolute pitches.
+
@item -d, --duration-quant=@var{DUR}
- Quantize note durations on @var{DUR}.
+Quantize note durations on @var{DUR}.
+
@item -e, --explicit-durations
- Print explicit durations.
+Print explicit durations.
+
@item -h,--help
- Show summary of usage.
+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".
+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}.
+Write output to @var{file}.
+
@item -s, --start-quant=@var{DUR}
- Quantize note starts on 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}.
+Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}.
+
@item -V, --verbose
- Be verbose.
+Be verbose.
+
@item -v, --version
- Print version number.
+Print version number.
+
@item -w, --warranty
- Show warranty and copyright.
+Show warranty and copyright.
+
@item -x, --text-lyrics
- Treat every text as a lyric.
+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:
+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{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. Sequences of grace notes are ended improperly sometimes.
+The list of articulation scripts is incomplete. Empty measures
+confuse @command{etf2ly}. Sequences of grace notes are ended improperly.
+@node Invoking musicxml2ly
+@section Invoking @code{musicxml2ly}
-@node Invoking abc2ly
-@section Invoking abc2ly
+@uref{http://@/www.@/recordarde@/.com/xml@/.html,MusicXML} is an XML dialect
+for representing music notation.
-@cindex ABC
+@command{musicxml2ly} extracts the notes from part-wise MusicXML
+files, and writes it to a .ly file. It is invoked from the command-line.
-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
+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 abc2ly:
+The following options are supported by @command{musicxml2ly}:
@table @code
-@item -h,--help
-this help
-@item -o,--output=@var{file}
-set output filename to @var{file}.
-@item -v,--version
+@item -h,--help
+print usage and option summary.
+@item -o,--output=@var{file}
+set output filename to @var{file}. (default: print to stdout)
+@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 abc2ly
+@section Invoking @code{abc2ly}
-@node Invoking pmx2ly
-@section Invoking pmx2ly
+@cindex ABC
-PMX is a MusiXTeX preprocessor written by Don Simons. More information
-on PMX is available from the following site:
+ABC is a fairly simple ASCII based format. It is described at the ABC site:
@quotation
-@uref{http://icking-music-archive.org/Misc/Music/musixtex/software/pmx/}.
+@uref{http://@/www@/.gre@/.ac@/.uk/@/~c.walshaw/@/abc2mtex/@/abc@/.txt}.
@end quotation
-@cindex PMX
-@cindex MusiXTeX
-@cindex Simons, Don
-pmx2ly converts from PMX to LilyPond input. The program is invoked as
-follows:
+@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
-The following options are supported by pmx2ly:
+The following options are supported by @command{abc2ly}:
@table @code
-@item -h,--help
+@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 -v,--version
+print version information.
@end table
-@refbugs
-
-This script was updated last in September 2000, and then successfully
-converted the @file{barsant.pmx} example from the PMX
-distribution. pmx2ly cannot parse more recent PMX files.
-
-
-@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:
+There is a rudimentary facility for adding LilyPond code to the ABC
+source file. If you say:
@example
- musedata2ly [@var{option}]@dots{} @var{musedata-files}
+%%LY voices \set autoBeaming = ##f
@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:
+This will cause the text following the keyword @q{voices} to be inserted
+into the current voice of the LilyPond output file.
-@cindex Music Publisher
-@cindex Mup
-@cindex Arkkra
+Similarly,
@example
- mup2ly [@var{option}]@dots{} @var{mup-file}
+%%LY slyrics more words
@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
+will cause the text following the @q{slyrics} keyword to be inserted
+into the current line of lyrics.
@refbugs
-Only plain notes (pitches, durations), voices, and staves are
-converted.
+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.
+ABC synchronizes words and notes at the beginning of a line;
+@command{abc2ly} does not.
+
+@command{abc2ly} ignores the ABC beaming.
+
+
+
+@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 @bullet
+@item
+@uref{http://@/denemo@/.sourceforge@/.net/,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
+@end itemize
projects / lilypond.git / blobdiff