X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fconverters.itely;h=f8b6f6c82f8b5ea8fcd28910eb5520cd41efca2b;hb=31568c504806f35aac420a394c9eab07abd9faa7;hp=71f53b947d449becea93c0fe9627b753a58e9be4;hpb=a96faf44452c408fb5cce3a9ac5b6f5b3f509d48;p=lilypond.git diff --git a/Documentation/user/converters.itely b/Documentation/user/converters.itely index 71f53b947d..f8b6f6c82f 100644 --- a/Documentation/user/converters.itely +++ b/Documentation/user/converters.itely @@ -1,295 +1,295 @@ -@c -*-texinfo-*- +@c -*- coding: utf-8; 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. -@node Conversion tools -@chapter Converting to LilyPond format. @menu -* midi2ly:: -* etf2ly:: -* abc2ly:: -* pmx2ly:: -* musedata2ly:: -* mup2ly:: +* Invoking midi2ly:: Importing MIDI. +* Invoking etf2ly:: Importing Finale. +* Invoking musicxml2ly:: +* Invoking abc2ly:: Importing ABC. +* Invoking mup2ly:: Importing MUP. +* Generating LilyPond files:: @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 convertor for a +direct format. -Hackers who know about signal processing are invited to write a more -robust midi2ly. +@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. -@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 -@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 +The following options are supported by @command{midi2ly}. +@table @code +@item -a, --absolute-pitches +Print absolute pitches. -Report bugs to @email{bug-gnu-music@@gnu.org}. +@item -d, --duration-quant=@var{DUR} +Quantize note durations on @var{DUR}. +@item -e, --explicit-durations +Print explicit durations. -Written by @email{Jan Nieuwenhuizen, janneke@@gnu.org}. +@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". -@node etf2ly -@section etf2ly +@item -o, --output=@var{file} +Write output to @var{file}. +@item -s, --start-quant=@var{DUR} +Quantize note starts on DUR. -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 -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN} +Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}. -@subsection Invoking etf2ly -Usage: +@item -V, --verbose +Be verbose. -@example - etf2ly [@var{OPTION}]@dots{} @var{ETF-FILE} -@end example +@item -v, --version +Print version number. -Convert ETF to LilyPond. +@item -w, --warranty +Show warranty and copyright. -@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 -Known: articulation scripts are buggy. Empty measures confuse etf2ly. +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}. -Report bugs to @email{bug-gnu-music@@gnu.org}. +@node Invoking etf2ly +@section Invoking @command{etf2ly} -@node abc2ly -@section abc2ly +@cindex ETF +@cindex enigma +@cindex Finale +@cindex Coda Technology -ABC is a fairly simple ASCII based format. It is described at -@uref{http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt}. +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 abc2ly +It is invoked from the command-line as follows. @example - abc2ly [@var{OPTION}]@dots{} @var{ABC-FILE} +etf2ly [@var{option}]@dots{} @var{etf-file} @end example -Convert ABC to LilyPond. - -There is a rudimentary facility for adding lilypond code to the ABC -source file. If you say: - -@example - %%LY voices \property Voice.noAutoBeaming=##t -@end example +The following options are supported by @command{etf2ly}: -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. - -@unnumberedsubsec Options @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 ABC standard is not very "standard". For extended features -(eg. polyphonic music) different conventions exist. +The list of articulation scripts is incomplete. Empty measures +confuse @command{etf2ly}. Sequences of grace notes are ended improperly. -Multiple tunes in one file cannot be converted. +@node Invoking musicxml2ly +@section Invoking @code{musicxml2ly} + +@uref{http://@/www.@/recordarde@/.com/xml/,MusicXML} is an XML dialect +for representing music notation. -ABC synchronizes words and notes at the beginning of a line; abc2ly does -not. +@command{musicxml2ly} extracts the notes from part-wise MusicXML +files, and writes it to a .ly file. -abc2ly ignores the ABC beaming. -Written by @email{Han-Wen Nienhuys,hanwen@@cs.uu.nl}. -@c How about Laura? /MB +The following options are supported by @command{musicxml2ly}: + + +@table @code +@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 -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@/.gre@/.ac@/.uk/@/~c.walshaw/@/abc2mtex/@/abc@/.txt}. +@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 -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 -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 ``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 ``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 +@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. -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 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. +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: -@subsection Invoking mup2ly +@cindex Music Publisher +@cindex Mup +@cindex Arkkra @example - mup2ly [@var{OPTION}]@dots{} @var{MUP-FILE} +mup2ly [@var{option}]@dots{} @var{mup-file} @end example -Convert Mup to LilyPond. - -@unnumberedsubsec Options +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}] -define macro @var{NAME} with opt expansion @code{EXP} -@item -E,--pre-process +@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 +@item -h,--help print help -@item -o,--output=FILE -write output to @var{FILE} -@item -v,--version +@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 absolutely @strong{NO WARRANTY}. +@item -w,--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}. - +@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 +@end itemize