X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fconverters.itely;h=8b394782003af7efc84671e9e10fdf1c2249b8d1;hb=c3cc35878c0d01c43cfb19d00cee956ef9fef2e8;hp=945f4f15d224e0b5de57e75d921c915f9b288034;hpb=56803f159f4a7bcf205835b781531c7db9c10958;p=lilypond.git diff --git a/Documentation/user/converters.itely b/Documentation/user/converters.itely index 945f4f15d2..8b39478200 100644 --- a/Documentation/user/converters.itely +++ b/Documentation/user/converters.itely @@ -1,272 +1,283 @@ -@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 +@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 lilypond itself, and are run +on the command-line; see @ref{Command-line usage} for more information. + + +@refbugs +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 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. +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 [OPTION]... MIDI-FLIE +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 +@samp{: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 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 [OPTION]... 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 -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}. +@uref{http://@/www.@/recordarde@/.com/xml@/.html,MusicXML} is an XML dialect +for representing music notation. -@node abc2ly -@section abc2ly +@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 -@uref{http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt}. +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. -@subsection Invoking abc2ly +The following options are supported by @command{musicxml2ly}: -@example - abc2ly [OPTION]... ABC-FILE -@end example - -Convert ABC 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 -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 -@refbugs -The ABC standard is not very "standard". For extended features -(eg. polyphonic music) different conventions exist. +@node Invoking abc2ly +@section Invoking @code{abc2ly} +@cindex ABC -Written by @email{Han-Wen Nienhuys,hanwen@@cs.uu.nl}. +ABC is a fairly simple ASCII based format. It is described at the ABC site: +@quotation +@uref{http://@/www@/.walshaw@/.plus@/.com/@/abc/@/abc2mtex/@/abc@/.txt}. +@end quotation -Report bugs to @email{bug-gnu-music@@gnu.org}. - -@node pmx2ly -@section pmx2ly - -PMX is a Musixtex preprocessor written by Don Simons, see -@uref{http://icking-music-archive.sunsite.dk/Misc/Music/musixtex/software/pmx/}. - -Report bugs to @email{bug-gnu-music@@gnu.org}. - -@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}. +There is a rudimentary facility for adding LilyPond code to the ABC +source file. If you say: -Written by @email{Han-Wen Nienhuys,hanwen@@cs.uu.nl}. - - -@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 [OPTION]... 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 +@refbugs + +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 [OPTION]... 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=FILE +set output filename to FILE +@item -v,--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}. - - +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 @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