X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fconverters.itely;h=451e59f9ce3e5387ea4aefe3845ce11a083d4e3f;hb=6e4061ccca25474d5bc9958f15385bc0c9c28894;hp=9522f50cd652a15c7111ee0d99c2b3e6fbe53f61;hpb=2a0f240bdfac5cec93adc010d3c5eff4986746e5;p=lilypond.git diff --git a/Documentation/user/converters.itely b/Documentation/user/converters.itely index 9522f50cd6..451e59f9ce 100644 --- a/Documentation/user/converters.itely +++ b/Documentation/user/converters.itely @@ -1,297 +1,319 @@ -@c -*-texinfo-*- +@c -*- coding: utf-8; mode: texinfo; -*- -@node Conversion tools -@chapter Converting to LilyPond format. +@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 -* midi2ly:: -* etf2ly:: -* abc2ly:: -* pmx2ly:: -* musedata2ly:: -* mup2ly:: -@end menu +These are separate programs from lilypond itself, and are run +on the command-line. By ``command-line'', we mean the command +line in the operating system. Windows users +might be more familiar with the terms ``DOS shell'' or +``command shell''; OSX users might be more familiar with the +terms ``terminal'' or ``console''. OSX users should also +consult @ref{Notes for the MacOS X app}. -@node midi2ly -@section midi2ly +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. -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. -It is possible to record a MIDI file using a digital keyboard, and then -convert it to @file{.ly}. However, human players can 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. +@menu +* Invoking midi2ly:: Importing MIDI. +* Invoking etf2ly:: Importing Finale. +* Invoking musicxml2ly:: +* Invoking abc2ly:: Importing ABC. +* Invoking mup2ly:: Importing MUP. +* Generating LilyPond files:: +@end menu -Hackers who know about signal processing are invited to write a more -robust midi2ly. -@subsection Invoking midi2ly -@example - midi2ly [OPTION]... MIDI-FLIE -@end example +@node Invoking midi2ly +@section Invoking @command{midi2ly} -@unnumberedsubsec Options +@cindex MIDI -@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 +@command{midi2ly} translates a Type@tie{}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 a convertor for a +direct format. -Report bugs to @email{bug-gnu-music@@gnu.org}. +@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. +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. -Written by @email{Jan Nieuwenhuizen, janneke@@gnu.org}. +It is invoked from the command-line as follows, +@example +midi2ly [@var{option}]@dots{} @var{midi-file} +@end example -@node etf2ly -@section etf2ly +Note that by ``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}. -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. +@table @code +@item -a, --absolute-pitches +Print absolute pitches. -@subsection Invoking etf2ly -Usage: +@item -d, --duration-quant=@var{DUR} +Quantize note durations on @var{DUR}. -@example - etf2ly [OPTION]... ETF-FILE -@end example +@item -e, --explicit-durations +Print explicit durations. -Convert ETF to LilyPond. +@item -h,--help +Show summary of usage. -@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 -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}. -@refbugs +@item -s, --start-quant=@var{DUR} +Quantize note starts on DUR. -Known: articulation scripts are buggy. Empty measures confuse etf2ly. -Report bugs to @email{bug-gnu-music@@gnu.org}. +@item -t, --allow-tuplet=@var{DUR}*@var{NUM}/@var{DEN} +Allow tuplet durations @var{DUR}*@var{NUM}/@var{DEN}. -Written by @email{Han-Wen Nienhuys,hanwen@@cs.uu.nl}. +@item -V, --verbose +Be verbose. +@item -v, --version +Print version number. -Report bugs to @email{bug-gnu-music@@gnu.org}. +@item -w, --warranty +Show warranty and copyright. -@node abc2ly -@section abc2ly +@item -x, --text-lyrics +Treat every text as a lyric. +@end table -ABC is a fairly simple ASCII based format. It is described at -@uref{http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt}. -@subsection Invoking abc2ly +@refbugs -@example - abc2ly [OPTION]... ABC-FILE -@end example +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. -Convert ABC to LilyPond. -There is a rudimentary facility for adding lilypond code to the ABC -source file. If you say: +@node Invoking etf2ly +@section Invoking @command{etf2ly} -@example - %%LY voices \property Voice.noAutoBeaming=##t -@end example +@cindex ETF +@cindex enigma +@cindex Finale +@cindex Coda Technology -This will cause the text following the keyword ``voices'' to be inserted -into the current voice of the lilypond output file. +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. -Similarly: +It is invoked from the command-line as follows. @example - %%LY slyrics more words +etf2ly [@var{option}]@dots{} @var{etf-file} @end example -will cause the text following the ``slyrics'' keyword to be inserted -into the current line of lyrics. +Note that by ``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}: -@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@/.html,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. It is invoked from the command-line. -abc2ly ignores the ABC beaming. +Note that by ``command-line'', we mean the command line of the +operating system. See @ref{Converting from other formats} for +more information about this. -Written by @email{Han-Wen Nienhuys,hanwen@@cs.uu.nl}. +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 [OPTION]... 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 [OPTION]... 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 [OPTION]... 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 absolutlely @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