X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fconverters.itely;h=28553b86b97aef86e78a2dc8bfb8e49275b758d9;hb=d4e1cf3b24ad546d05a490ad1b07be45ea230e44;hp=1bfe2a1e0f2222d92259f8b34d52e570af42a1a8;hpb=4cb2a5267e16d233b13089ab37a467c3d19da235;p=lilypond.git diff --git a/Documentation/user/converters.itely b/Documentation/user/converters.itely index 1bfe2a1e0f..28553b86b9 100644 --- a/Documentation/user/converters.itely +++ b/Documentation/user/converters.itely @@ -1,41 +1,52 @@ -@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 -* Older LilyPond versions:: -* Importing MIDI:: -* Importing Finale :: Upgrading from older -* Importing ABC:: -* Importing PMX:: -* Importing Musedata :: -* 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 Older LilyPond versions -@section Older LilyPond versions +@node Invoking convert-ly +@section Invoking convert-ly + +The syntax is regularly changed to simplify it or improve it in +different ways. A side effect of this, is that LilyPond often is not +compatible with older files. To remedy this, the program convert-ly +can be used to deal with most of the syntax changes. + +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, enter the following on the +command line. -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{options}] @var{files} + 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}. @item -f,--from=@var{from-patchlevel} @@ -52,80 +63,90 @@ The following options can be given: 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 - +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 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 Importing MIDI -@section Importing MIDI +@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. +Midi2ly translates a Type 1 MIDI 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 importing files from a program that has convertor for a +direct 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. +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. +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) 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: +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 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}], +@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 -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, + 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 -@node Importing Finale -@section Importing Finale +@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 @cindex ETF @cindex enigma @@ -136,12 +157,12 @@ 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: +It is invoked from the command-line as follows. @example etf2ly [@var{option}]@dots{} @var{etf-file} @end example -The following options are supported by etf2ly. +The following options are supported by etf2ly: @table @code @item -h,--help this help @@ -154,18 +175,20 @@ version information @refbugs -The list of articulation scripts is incomplete. Empty measures confuse -etf2ly. +The list of articulation scripts is incomplete. Empty measures +confuse etf2ly. Sequences of grace notes are ended improperly. -@node Importing ABC -@section Importing ABC +@node Invoking abc2ly +@section Invoking 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 +abc2ly translates from ABC to LilyPond. It is invoked as follows: @example abc2ly [@var{option}]@dots{} @var{abc-file} @@ -182,17 +205,17 @@ set output filename to @var{file}. 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 @@ -205,7 +228,7 @@ into the current line of lyrics. @refbugs The ABC standard is not very ``standard''. For extended features -(eg. polyphonic music) different conventions exist. +(e.g. polyphonic music) different conventions exist. Multiple tunes in one file cannot be converted. @@ -214,86 +237,19 @@ not. abc2ly ignores the ABC beaming. -@node Importing PMX -@section Importing PMX - -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 Importing Musedata -@section Importing Musedata +@node Invoking mup2ly +@section Invoking mup2ly -@cindex Musedata -@cindex CCARH - -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: - -@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 Importing MUP -@section Importing MUP - -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. Mup2ly will convert part of a Mup file to LilyPond +format. It is invoked as follows: @cindex Music Publisher -@cindex MUP +@cindex Mup @cindex Arkkra +It is invoked from the command-line as follows. @example mup2ly [@var{option}]@dots{} @var{mup-file} @end example @@ -303,7 +259,7 @@ 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}] +@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 @@ -320,8 +276,25 @@ print warranty and copyright. @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 also external tools that generate LilyPond files. + +These tools include +http://denemo.sourceforge.net/ +@itemize @bullet +@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