MidiZyx2abc

Homepage in German: http://www.midicond.de/Freeware/,
Homepage in English: http://www.midicond.de/Freeware/index_en.html.

(Shortcuts for lookup purposes: Features, Parameters.)

MidiZyx2abc converts standard MIDI files (usual name ending .mid, also .kar) to abc music notation code, in the tradition of other “midi2abc” converters. One of the design goals is the careful treatment of accidentals. Additionally, it allows you to use your conventional MIDI sequencer or notation software to add those features of abc for which there is no canonical equivalent in MIDI files, e.g. dynamics, repeat signs, clefs, slurs, and various ornaments. For this purpose, MidiZyx2abc abuses ordinary MIDI text events.

MidiZyx2abc is gratis only for private use. Any public distribution is prohibited, even if without charge, unless licensed explicitly. The file must not be altered. You are very welcome to spread the above address of the homepage for MidiZyx2abc.

The abc notation language was designed by Chris Walshaw for mnemonic ease and brevity. On his homepage http://abcnotation.com/, you will find the definition of the language standard and an impressive list of software and other resources.

“MIDI file to abc” – or to any other format of traditional notation – is an unfulfillable promise, given the restrictions of the MIDI file format. If a little step towards abc has been taken, metaphorically zyx, chances are much better.

On the homepage you will find, besides news and the latest version to download, an email address for your comment. You are strongly encouraged to use it, preferably in German, English, or French. Please describe how you are hoping to work with MidiZyx2abc and benefit from your suggestions being implemented, if any. Every well-founded mail will count as a vote, even if it contains no new information. Reports of genuine bugs in the latest version are welcome, particularly when illustrated by a very small MIDI file (two bars, two tracks).

You can also post your comments and questions to the abc users' group https://groups.io/g/abcusers/. It is very active, so that you are likely to get a handful of responses very quickly.

If you appreciate any free piece of software such as MidiZyx2abc, please recommend it in social media, reputable blogs, forums and software lists, e.g. as run by leading computer magazines.

Enjoy and be successful!

Alexander Scheutzow, Mannheim, Germany


Standalone

When invoked without a set of parameters that would be sufficient for tacit action, MidiZyx2abc will open a window with the traditional menu bar. There you can load a MIDI file, read and edit the abc code produced, and copy it to other applications, or process it by self-made “plugins”. Since there is no shortage of dedicated abc editors and renderers, MidiZyx2abc is not going to compete with them.

Alternatively to the traditional “Open” menu item, you can drag and drop a symbol for a MIDI file to the space above the editor area (– not to the editor area itself, alas, for technical reasons beyond my influence).

The “Save as ...” menu item writes the text as it currently appears in the editable window to a file you choose. If this target file already exists, you will be asked whether the new text shall be appended to it or replace its entire current content. MidiZyx2abc will inspect neither the file nor the added text for any notion of consistency.

Appending to existing content is done mechanically. If however the output file is newly created or emptied, MidiZyx2abc can add a BOM, i.e. an invisible three-byte prefix that is required by some software products to correctly identify the UTF-8 format, whereas some others may not be able to cope with it. Also, an abc file header can be added, as conforming to the current abc standard but not always desired. You have the choice in the two checkboxes labeled “add the BOM” and “add the abc file header”.

There are more options that you can make use of in the area between the menu bar and the text window; most of them have equivalent call parameters described below. Choices that affect the output will take effect at the next “Open” or “Reload” action. Rarely used options are accessible via the “Options” menu. If any of these choices have actually been passed as parameters to the process that opened the window, the selections will be preset accordingly. Changes you make in the window are considered temporary and will be forgotten when the window is closed. Some settings are actually pertinent to specific MIDI files and are therefore best decreed inside them, see below.)

Persons who do not edit their MIDI files yet may also welcome the opportunity to command an upbeat (alias anacrusis) here: Since there is no direct way for a MIDI file to tell us about any upbeat at its beginning, well-behaved files always start with a complete bar, filled up with “rests” as required. MidiZyx2abc will cut any leading rests unless told otherwise, so you will normally not be bothered with this problem. But some files do not follow that rule, they start directly with the upbeat. (Either they were not meant for notation at all, or the programmes that created them blundered, such as some products in the vicinity of abc.) If you want to (pre-)view such a file without doing any MIDI editing, open it in MidiZyx2abc tentatively. Enter into the number field your guess for the length of the upbeat in 16ths, e.g. 4 for a quarter note, and click on “Reload”. The number refers to the beginning of the file, so you may have to increase it if a leading rest does exist, but is too short. – Preferably, add the required “rests” to the MIDI file in your sequencer software, or a “/&B|” text event at the end of the upbeat.

If “Always to clipboard” is selected when you leave the MidiZyx2abc window without closing it, the entire current content of the editor field is automatically copied to the clipboard, saving you the select-all-and-copy action, as available in the “Edit” menu. (If you work with another abc GUI tool, you may frequently switch there to paste the text. Users of plugins do not have that desire.) The checkbox will be preselected if you passed the parameter -clipboard. Beware of accidentally overriding the clipboard.

In some Linux and related systems, clipboard contents produced by a MidiZyx2abc session are no longer available after closing it. This is a known long-standing bug of Java implementations. You may be more lucky when using the Ctrl-C or Ctrl-X keyboard functions (– which proves that the problem would be solvable; indeed I know a workaround, too risky to offer to the public). Try it out before relying on it.

In the “Cases” menu, all “case names” mentioned in the current MIDI file are listed.

For the “Plugins” menu and the text field labeled “At the next plugin call add:”, see the chapter “Plugins” below.


Use with other abc tools

Alternatively, the software can be used in batch/command mode, syntax e.g.

java -jar MidiZyx2abc.jar MyMidi.mid -o Output.abc
or
java -jar MidiZyx2abc.jar MyMidi.mid -stdout

In some contexts MidiZyx2abc, or a batch file calling it, can replace the widespread tool midi2abc.

You can specify more than one MIDI file, each by a separate parameter, to be processed into the same abc file. Additional optional command parameters influence the output. Here is the complete list:


-odeclares the next parameter to denote the output file. If it already exists, its previous contents will be deleted. Only one output file is allowed per call. (This behaviour has been designed for compatibility to midi2abc)
-oappendsame as -o, except that if the output file exists, the new result (– which may replace some of the expected code by error messages –) will be appended to the previous content. Only one output file is allowed per call altogether.
-stdoutcauses the resulting abc code to be written not to a file, but to standard output, i.e. the current command line window.
-unicodeproduces Unicode in the window, or the UTF-8 format in output files. Otherwise only basic ASCII will be used, with escape sequences following the current abc standard. (Note that some software products such as abc2xml actually require Unicode and do not support escape sequences, others vice versa!)
-bomif an output file is created or replaced (rather than appended to), begin it with a UTF-8 “BOM”. Corresponds to the “add the BOM” checkbox. Typically used in conjunction with -unicode.
-tuneonlyif an output file is created or replaced (rather than appended to), omit the file header defined in the standard. Corresponds to the opposite of the header checkbox.
-channels
causes each track to be mapped not necessarily to a single abc voice (as normally), but to as many voices as MIDI channels are encountered there, distributed accordingly. This usually reflects the internal organization of the current MIDI file, therefore any Channels: or /&x setting inside it will take precedence.
-case
assumes the next parameter to be a list of one or more named cases, separated by commas.
-quantize
causes the quantization specified by the next parameter, unless a corresponding setting is encountered inside the file. The default is “1/32t”.
-beamlyrics
makes MidiZyx2abc disregard the traditional convention that notes carrying lyrics must not be beamed.
-alltempo
produces Q: directives for all tempo events, unless/until overridden by a /&T directive (see below).
-bartempo
produces Q: directives for all tempo events that coincide with bar lines, unless/until overridden by a /&T directive. -alltempo and -bartempo are mutually exclusive.
-tempotop
translate non-initial MIDI tempo change events only into the first voice of any score, to prevent some software from printing them on each staff. (By default, they will be copied into each voice. Note that Q: fields created explicitly will not be affected – be careful.)
-autosplit
switches the /&autosplit flag on, unless overridden by an Autosplit: setting inside the file.
-x or -xdeclares the next parameter, which must be a decimal positive integer, to denote the X: number of the first tune produced; default is 1. However, any /&HX:... statement encountered in the file takes precedence. If more than one tune is to be written to the output context, the X: number will be counted up whenever necessary to ensure uniqueness.
-declare
causes MidiZyx2abc to “declare” all voices at the beginning, i.e. position all their voice header lines directly after the tune header, roughly as if /&VI had been encountered at the very beginning.
-ndeclares the next parameter, which must be a decimal positive integer, to denote the number of characters that no line of the resulting abc code should exceed (unless necessary to complete a single bar); default is 100.
-chunkSep
declares the next parameter, which must be a decimal positive integer, to denote the maximal number of bars to be written in any “chunk” of the resulting abc code, after which all voices will be interrupted, as if a /&VI command had been found there. (Any explicit /&V... will of course remain in force additionally.) Specifying a fairly small number of bars often facilitates human reading. Any resulting such score chunk will be separated from its predecessor by a comment line stating the current bar number, making for even better readability. The eventual rendering as sheet music should remain unaffected, of course.
-chunkCp
Same as -chunkSep, but producing no separating comment lines, thus more compact and less readable code.
-soundk
causes MidiZyx2abc to use the keyword sound= instead of the synonymous traditional transpose= at any /&t_in_... command in the whole tune. Recommended whenever supported by the target software; may become the default in future versions.
-magicdecrees that the next parameter shall be the “magic word” to be looked for instead of the default word MidiZyx2abcSettings. For safety, avoid using special characters, diacritics, and non-Latin letters.
-plugdeclares the next parameter to denote the full path of the directory where plugin batch files are to be looked for.
-clipboardtakes effect only if the GUI window is opened: preselects the clipboard checkbox.
-metaltakes effect only if the GUI window is opened: Sets its "look and feel" to the Java-owned "Metal" style rather than the one purportedly adapted to your desktop – either may have shortcomings.
Any othersare assumed to denote MIDI files to be read and processed in given order into the single abc output. For the GUI window, only the first-named such file will be prepared; any others are ignored. Any of the above option parameters will be applied to all the input files named in the current call, regardless of their order. If you want different sets of options for different MIDI files, issue separate calls.

All parameters are case-sensitive. Misspelled or invalid parameters do not lead to direct failure (as opposed to errors inside the MIDI file); they will be registered in a list and have no other effect. If a GUI window is displayed, that list appears in a warning box which can also be viewed via the Help menu. In a context without a window, the list is added at the end of the output file as comment lines.

The parameters taking the next parameter for their value, such as -case, -quantize, and -magic, allow for an alternative syntax: directly to the keyword you can append a colon “:” and the string that would otherwise form the next parameter, as in -quantize:1/16t

Example: To use MidiZyx2abc with the Windows software “ABCexplorer.exe”, create a text file “MidiZyx2abc.bat” consisting of a single line like

java -jar D:\MyBestTools\MidiZyx2abc.jar %1 %2 %3 %4 -tuneonly -unicode

and enter the full path of that “MidiZyx2abc.bat” to the ABCexplorer's menu item dialogue “Options → External tools → Path of the tool for MIDI import”.



Some use cases

To edit a large score, you may find that nothing surpasses a full-fledged mouse-driven notation system you are well acquainted with. If you have such a system that can export MIDI files but neither abc nor MusicXML, you belong to the primary target group of MidiZyx2abc.

MidiZyx2abc is meant to minimize editing work and error-prone proofreading for the following tasks:

*) Some notation software products can read abc themselves, others via converters to MusicXML or LilyPond. Of course they can also import MIDI files directly, but then they lack the benefits of “MidiZyx” annotations – and often perform worse than MidiZyx2abc even without annotations. On the other hand, abc does not administer typical MIDI data such as the attack velocity of each note.


Example: If you used the software Notator SL™ on your old Atari ST™ to create sheet music, and want to convert the corresponding files to Sibelius™ or Finale™ etc., you may proceed as follows:
  1. in the Notator SL™ software, for each clef, decoration, dynamics sign, annotation, etc., add the corresponding “MidiZyx” text event (- consider using “global dynamics” to save a lot of work -),
  2. also add commands for transposition, interrupting, settings such as “MidiZyx2abcSettings Charset:AtariST Lyrics:invert”, etc., if relevant,
  3. export the songs to MIDI files,
  4. read them into a computer that has Java (possibly via another computer that supports both floppy disks and USB sticks),
  5. run them through MidiZyx2abc,
  6. convert the results to MusicXML, e.g. by Wim Vree's freeware tool abc2xml,
  7. read the resulting MusicXML file into your new notation software.
  8. Check the result for errors, repeat the procedure if necessary.
Not trivial, but generally less error-prone and tedious than reproducing all those decorations by hand in the target system.

Good results can be achieved quickly with music for ensembles of melody instruments and/or singing voices. Parts for keyboard instruments, harp, guitar, or percussion may require some additional preparation for best output.


Requirements

If you want to make full use of MidiZyx2abc, your MIDI sequencer or notation software should

Such sequencers are available as freeware, and so is software to render abc code as sheet music, or process it otherwise.

Being a Java application, a single file MidiZyx2abc.jar will run on almost any modern platform, such as Windows, MacOS, Linux.


Matters of abc version

Generally, MidiZyx2abc strives to know as little as possible about abc, hoping to be usable for present and future versions and dialects.

If MidiZyx2abc does not encounter any directive for a header line of type abc-version in a tune, it inserts I:linebreak $ to suppress breaks of the staff system at the end of each source line. Otherwise it assumes that the user takes provisions to that purpose.

Lyrics are treated to comply to both abc-2.1 and the older standards.

It goes without saying that a new version of MidiZyx2abc will be issued as soon as possible whenever its core functionality is affected by a new version of the abc standard. This is not as improbable as it should be. Before updating any software, check the homepages for warnings of possible incompatibilities.


Usage

Normally, each MIDI track is mapped to a voice in abc. MidiZyx2abc can also be made to split the music by both track and MIDI channel, which however has drawbacks (cf. Hints).

In the following the notion “text event” is used to comprise lyrics syllables, free printable text, and MIDI events of type “cue” or “marker”. If they start with a special prefix as listed below, MidiZyx2abc will process them. Otherwise those of lyrics type will be forwarded as “genuine lyrics”.

If you now suspect you have to learn yet another notation language, you are mistaken. You must learn as much of the abc language as you plan to use (see the appendix below for a start), plus a couple of simple prefixes. By now, MidiZyx2abc is endowed with very powerful and sophisticated features, but you can safely ignore those you do not want to use.

Users who prefer experimenting to theory may jump to the appendix and read this chapter later.

The following list is subdivided by topics:

The last column, titled “VP”, tells you whether the meaning of the text event depends on the voice (V) or position (P) at which it is found, or both – this is important information for you. The entry T denotes the MIDI track of an event from which the notion of voice is deduced.


PrefixMeaningExampleVP
//The bread-and-butter function. If a text event starts with that token, the remainder of the text will be “blindly” written to the abc code immediately before the name of any note starting at this position. Also called “preinsertion code”. This covers dynamics, ornaments and a lot more. (If there is no such note or rest, the effective metric position may be postponed; if in such a case you insist on the exact position, use /&i or /&v. To precede a bar line, use /&b. Avoid anything of nonzero note length or other effects that MidiZyx2abc manages actively. Also note that the event may interact with “global dynamics” or “sempre mode”.//!crescendo(!VP
/\The same as //, except that if a note starts at this position, the remainder of the text will be inserted directly after its representation, notably before any bar line following it, but also before any tied continuation. The example marks the end of a slur. Usage at other positions is not recommended./\)VP
/?A super-prefix to specify named cases. See the chapter “Named cases” below./?vl,-scr./&i?
/#A super-prefix to specify a single channel number (1 to 16), see below. The special value /#q indicates that the event applies to the cue voice (see “Cue notes” below)./#2//.T
/&All other special tokens begin with this sequence, distinguished by the letter following it. This will be a capital letter if the information is used for all voices equally, and a small letter if the track or voice in which it is found is relevant.?
Defining voices and tunes
/&xIf the statement continues with a “-” sign (/&x-), this track will be mapped to a single voice. If it stands alone or continues with a “+” sign (/&x or /&x+), the track will be split to as many voices as different MIDI channel specifications are encountered for its notes. Notes and sound “program” statements are distributed according to their channel information. All other events are normally applied to each such voice; see below for exceptions. This setting overrides any -channels parameter or Channels: setting; in default of all of these, “-” applies./&x+T
/#A super-prefix to specify a channel number (1 to 16) by one or two decimal digits following it. If the track gives rise to more than one voice, the event will be ignored in all voices specializing on a different MIDI channel. Otherwise, or if the channels match, the event is considered as if the super-prefix were absent. It may result in a genuine lyrics syllable or another MidiZyx2abc prefixed event. (In case of ambiguity, the two-digit number will win; if necessary use a leading zero digit, e.g. with lyrics: /#011.~We.) – A special value /#q will be discussed below./#9/&L16
/#12//.
TP
/&g lyr followed by “-”: ignore the lyrics for this particular voice, from this particular position until revoked by /&g lyr+. The idea is that if a track gives rise to more than one voice, of different channels but evantually sharing a staff, some of these may not need a copy of all syllables. (The same effect can be achieved by prefixing each such syllable with some /#.)/#2/&g lyr-VP
/&n%Exclude this whole voice from the resulting abc code. (Of course, MidiZyx2abc events in that track which affect other voices will still be respected.)/?NoCembalo/&n%V
/&NProduce an entire set of abc tunes, for example to have several instrument parts in one tune each. Additional text must consist of one or more segments in brackets “[ ]”. A normal such segment gives rise to one abc tune, it contains a valid completion of an I:score statement using the effective voice IDs (– i.e., if you defined cue notes and want to see them, you must include their voice IDs explicitely, together with their pertinent parentheses). You are free to use additional (nested) brackets to go into the new I:score ... statement.
Special values for possible segments are:
[[]]the score that would be produced if no /&N were present at all, i.e. without cues.
[|]complete score including all cues (– mainly for export via MusicXML).
[]( – spaces are ignored –) produces an extra one-staff tune for each original voice not mentioned explicitly in any /&N command currently in force. If a cue voice is defined for it, it will be attached properly, see below). An empty /&N is equivalent to /&N[], i.e. each genuine voice separately.
MidiZyx2abc will create these tunes in the given order into the current output context; X: numbers are counted upwards. Except for the [[]] case, any directive equivalent to /&HI:score ... encountered elsewhere in the file will be suppressed. If two or more /&N statements are encountered, their texts will be concatenated “blindly” in order of appearance, to allow for lengthy declarations and sophisticated management of named cases. (Consider using “external text files” in such cases.) For example, /&N[{(r rQ)|lh}][] will produce one tune with I:score {(r rQ)|lh}, imagined as a piano part with cue notes in the right hand, and one more tune for each other voice, imagined as a melody instrument part. See “Instrumentation variants” below for a comprehensive example.

Best make sure that the instrument name appears on each part sheet, typically via named cases.

FAQ: Why is there no equivalent parameter to operate this function flexibly from outside the file? Answer: Designing such partial scores requires intimate knowledge of the file. Use “named cases” to distinguish between your varying requirements from outside.
/&N[{(r rQ)|lh}][]-
/&g trackID declares the remainder of the text (after a possible space character) to be the name of this track, for internal reference only. The name must be unique in the whole file and not contain any space characters. Currently only used in error messages. Not to be confused with the voice ID, which is taken from voice header settings, if any, but may be tacitly adjusted to guarantee uniqueness. In contrast, although trackIDs are optional, nonunique settings will produce fatal errors immediately./&g trackID ChoirT
Header and footer
MidiZyx2abc will ensure that the order of the header and footer lines conforms to the abc standard. Apart from that, lines of equal type will be sorted by their metric positions (which are otherwise irrelevant), and in case these are equal, in the order found in the MIDI file. Wherever the order matters to you, best use distinct metric positions or external text files.
/&HThe remainder of the text is to form a tune header line./&HT:Serenade-
/&LDetermines the L: field of the tune header; see below./&L:1/4-
/&hThe remainder of the text is to form a voice header line, i.e. a line to be positioned above the abc code for the current voice. If it starts with “V:”, MidiZyx2abc will not offer such a line by itself, but use that voice name for its I:score directive (unless you provide that as well)./&hV:TubaV
/&FThe remainder of the text is to form a line at the end of the abc code, quasi in the footer. Any two-character sequence “\n” in it will be transformed to a new-line directive, i.e. resulting in one more line./&F%The End-
/&WSame as /&F, except that every line (including the ones derived from \n sequences) will be prefixed “W:”, so that they are treated as words of additional verses./&Wetc.-
/&g midihdThe remainder of the text must be a name for a MIDI sound program, see Appendix 3, case-insensitive. MidiZyx2abc will transform this to a voice header line, as if it were /&h%%MIDI program followed by the corresponding zero-based program number. Normally, you need not bother: If you do not provide such a directive and the MIDI track has a sound program event at its beginning, MidiZyx2abc will translate it to a voice header line. In contrast, sound changes in the midst of a voice are not currently administered by MidiZyx2abc, due to lack of standardization; you are free to add inline or “addline” fields at your own risk./&g midihd violinV
Interrupting
/&BThe remainder of the textshall be put into every voice in lieu of a bar line, e.g. a repeat sign. (Of course, the substitution will precede anything else that may refer to the same prosition.) The internal administration will assume a new bar starting here (– with the full length of the current metre, until further notice –), for example consider all added accidentals cancelled. If the idea is to have a repeat sign in the midst of a bar, do not forget to mark the next regular bar line by /&B|. Another typical makeshift usage is an ordinary /&B| at the end of an upbeat (anacrusis) whose bar has not been filled up with rests by the MIDI software. Note that this may lead to incorrect splitting in truncated bars; adjust it with suitable events. Whenever else you want to change the metric positions of bar lines, best change the MIDI metre signatures./&B:||:P
/&bLegal only at positions where a bar line would be due anyway. The remainder of the text shall be put into the current voice in lieu of that bar line. (Other than /&B, this command never influences the internal administration of bars.) If a /&B directive occurs at the same position, its value is ignored for this voice, in other words overridden. Experts may use such an item to create an overlay for the preceding bar, at their own risk./&b!<)!|VP
/&vThe remainder of the text shall be put into an implicit, MidiZyx2abc-generated bar overlay otherwise filled with x rests, so that it ideally appears at the specified position (rounded to the closest 64th to avoid triplet marks) even if this is non-interrupting, such as in the midst of a note or rest. Like the other types of insertion code, this one must not contain anything of non-zero effective note length. Typically used for mid-note dynamics. For all such events within a bar of a voice, a single overlay passage will be used, inserted immediately before the next bar line or any /&B text there. The exact consequences, e.g. when matching opening with closing events, may depend on the target software./&v!pp!VP
/&iForce any note or rest that starts before this position and ends after it to be optically interrupted here without change of meaning, e.g. to prevent illegible dotting. Notes will be tied, the new part can have its own lyrics syllable. If any text follows the /&i, it is treated as “preinsertion code” exactly as if prefixed //, also with respect to global dynamics and “sempre” mode./&i!p!VP
/&ISame as /&i, but applying to all voices, and never interrupting the global dynamics or “sempre” mechanisms. Rather, the resulting insertion will precede all other preinsertions of equal metric position. This command, in contrast to /&G split, cannot be overridden for individual voices, so use it only if you mean it./&I[1P
/&autosplitSets the autosplit mode for the current voice, valid for items starting here until the next such command. If the flag is set on, it allows MidiZyx2abc more liberty to boldly split notes (by ties), rests, and beams automatically, for good readability within the current time signature; see the chapter “Splitting, Autosplit” below. /&autosplit+ switches the mode on, /&autosplit- off, /&autosplit0 (zero) back to the default value (as determined by the setting Autosplit: or the parameter -autosplit). You can insert a blank after the keyword./&autosplit +VP
// A preinserted space character prevents beaming from the previous note, by mere abc syntax. Alternatively, you can try a post-insertion on the previous note.// VP
/&g splitfollowed by one or more positive integer numbers, separated by space characters. Defines distances between split points, in the unit of a sixteenth note (semiquaver), the first one starting at each bar line. At each such split point, notes and rests will be interrupted (as if a /&i had been found there) if they start after the previous split point or end before the following one. If the text ends on an asterisk (*), the last number will be iterated until the end of the bar. This setting renders ineffective the splitting aspect of any autosplit mode setting, even if found later on. To return to the current autosplit specification, issue /&g split-./&g split 12 8*VP
/&g unbeamExactly the same syntax as /&g split. Prevents any note that starts on such a position from being beamed to its predecessor, as if //  had been found there, but without hampering with “global dynamics” and “sempre mode”. This setting renders ineffective the unbeaming aspect of any autosplit mode setting, even if found later on. To return to the current autosplit specification with respect to beaming, issue /&g unbeam-./&g unbeam 8*VP
/&G split has exactly the same effect as if a /&g split of equal text had been found in each voice in which actually no /&g split is found at that exact position./&G split 6 8 6P
/&G unbeam has exactly the same effect as if a /&g unbeam of equal text had been found in each voice in which actually no /&g unbeam is found at that exact position./&G unbeam 6*P
/&addline (Must be followed by a space character!) Force the line of the abc code to be ended (including any matching lyrics lines), insert the remaining text, then resume in a new line. Use \n in the text to demand additional line breaks. Chiefly used to insert in mid-voice proprietary fields of old software that does not recognize the inline syntax:
/&addline %%MIDI program 42\n%%;MIDI channel 8.
/&addline %%font 2VP
/&SIf found before the very first note of the file: start here (with rests), rather than there. Otherwise ignored. No further text is allowed./&SP
Rests
/&rThe remainder of the text is the text for a rest. By the 2011 standard, this must be either z (normal, as assumed by default) or x (invisible). The command is valid for the current voice, starting at the next interrupt, until the next such command. (If you want it to work right here but it doesn't, additionally issue an /&i interrupt.)/&rxVP
/&nMOffers a workaround to effect multi-bar rests, which however are not being administered explicitly. See below under “Direct code manipulation” ./&nM|Z ... /&n}VP
Transposition
For “transposing instruments”, the following commands make MidiZyx2abc write out the notes to reflect the sheet music. This method is still recommended for various reasons. As an alternative, the new abc standard offers coding “at sounding pitch” via /&hV:... instrument=...;abc@c, but MidiZyx2abc will take no further notice of this and treat those voices as if they were non-transposing, e.g. when correcting accidentals or in the “cue notes” mechanism described below.
/&t_in_Use this command at the beginning of the voice for a transposing instrument such as the trumpet, and at any other position where the transposition must change (e.g. the clarinet switching between A and Bb). The prefix must be followed by a note name, i.e. the note letter followed by # or b if applicable, and any number of + or - signs representing one octave shift each. Without those signs, transposition goes downwards by 0 to 11 semitones. Remember that + means a higher instrument, so the notation will be lower to compensate for that. (See Appendix 2 below for a list of examples.) MidiZyx2abc will also add a directive to ensure playback at original pitches. If the parameter -soundk is active, the syntax sound=... will be used, e.g. sound=c_B for a trumpet voice. Otherwise, the legacy transpose= will be inserted. (In future versions, the former behaviour may be declared the default; then another parameter will be offered to revert to the old standard. This is always independent of any declaration of abc-version in the file!) MidiZyx2abc will not transpose any abc code entered by the user directly, such as grace notes, overlay, or chord symbols./&t_in_Bb--VP
/&tn_in_The same as /&t_in_, except that neither transpose= nor sound= is issued. Meant for users who need to control those parameters themselves./&tn_in_Bb--VP
/&t_biasFollowed by a number called "bias", indicating the degree of bias towards sharp key signatures. When performing a transposition other than by full octaves, MidiZyx2abc will choose a key signature of less than (6 - bias) flats and less than (6 + bias) sharps if possible. Otherwise the same type of accidental is preferred; signatures without accidentals go to sharps. The same applies to the assumed key as set by an /&A command, see below. Of course, the default bias is 0. You can adjust the bias anywhere in the voice, it will be applied at the next change of key signature, assumed key, or transposition. This is the only way to influence the choice of enharmonic variant; the enharmonic spelling used for the /&t_in_ command makes no difference./&t_bias-1VP
/&oThe abc code for the voice shall be produced in another octave until the next event of this kind. The prefix must be followed directly by a + or - sign, followed by a single decimal digit, together specifying which octave to notate compared to the one of the MIDI source. The remainder of the text is blindly inserted to the music code line, preceding any insertion code of equal time position. Normally that text will declare the reason, e.g. a compensating “octave=” directive or an “unorthodox” clef. Warning: code entered by the user, e.g. grace notes, will remain unchanged, beware of “over-compensation”!  Obviously, /&o+0 reverts to normal notation./&o+2[K:octave=-2]VP
Keys and accidentals
/&cWrite the whole voice without any signature accidentals (“as if the main key were C major”), independent of transposition, without changing the orthographic or sounding result. Typically used with traditional parts for French horn./&cV
/&KChange the key signature. (Use this command in lieu of the corresponding MIDI event, if your MIDI software cannot produce it.) The remainder of the text must be a capital letter for the note name, followed as the case may be by # or b, then by m if it is a minor key; any other syntax is currently illegal. Note that keys always apply to all voices with respect to the sounding result, which means that for transposing instruments (/&t...), the key signature will appear different in the code./&KF#mP
/&AThe remainder of the text names the key to be assumed internally when deciding about enharmonic alternatives, e.g. whether to write ^G (G sharp) or _A (A flat). This command remains valid until either a real key signature change occurs or you issue another /&A, /&AX, or /&K command, usually to return to the original key. The syntax is equal to the /&K command. Whenever you are unhappy with the software's orthography, try this tag first, which is a better idea than flagging individual notes. Make sure never to lose track of those commands./&ABbP
/&AXThe same as /&A, but interpreted rigidly, without respect for the chromatic context. Each note that is not flagged otherwise by /&f, is guaranteed to have a distance of -3 to +8 on the helix of fifths to the fundamental note of the major key. For example, /&AXC or /&AXAm will use the notes E-flat, B-flat, F, ... C-sharp, G-sharp, but never D-sharp or A-flat etc./&AXF#P
/&fSome properties (“flags”) for individual notes. Although MidiZyx2abc makes more effort to guess the correct accidentals than many other MIDI file importers, the result may be wrong or differ from your taste. If an appropriate /&A or /&AX does not do the trick, you can use this tag. The remainder of the text is a sequence of token-digit pairs, which you may (but need not) separate by spaces. The digit, 1 to 9, tells us which note you are talking about, in case there are more than one in that voice at that position, numbered bottom (1) to top. If it is 1 and no ambiguity arises, you are allowed to drop it. The token preceding the digit can be:

TokenMeaning
^prefer sharp (or natural) to flat
^^prefer double-sharp (or sharp) to natural or flat
=prefer natural to double-sharp or double-flat
_prefer flat (or natural) to sharp
__prefer double-flat (or flat) to natural or sharp
(of course, a single note should not have more than one of the above flags.) –

A different topic with the same syntax is
!force the display of the accidental (including natural) even if it is not strictly necessary
%suppress the display of the accidental (including natural) if MidiZyx2abc might otherwise add it for mere “courtesy”.

The example /&f ^1 _2 !2 assumes a chord of at least two notes, say some Eb and a higher F#. The directive then means that the lower note should be spelled D#, the top one Gb, and the flat sign for the Gb be displayed in any case. An alternative syntax option would be /&f^_2!2 – not recommended though.

Note that all such flagging refers to the note in the abc code, after any transposition due to /&t.... It may need reworking if you change that transposition; this is one of the reasons to prefer /&A.
/&f^1_2!2VP
Tempo
/&QIssue right here an inline tempo directive [Q:...] with the current tempo from the MIDI file. You can optionally append the desired unit, e.g. 3/16, which will also be applied to subsequent /&Q commands until one is encountered that specifies another unit, independently of anything done by /&T commands. (If you want to set the actual tempo value as well, use something like /&I[Q:1/4=86].) If this directive is found at the very start, it will operate on the Q: header line./&Q3/8P
/&TUntil the next such command, react to MIDI tempo change events (occuring after the beginning of the piece) depending on the remainder of the text:
  • If it is “+”, issue an inline tempo directive [Q:...] (of suitable unit, not user-defined) for every such event. (When used at the beginning of the piece, the command is equivalent to a parameter -alltempo)
  • If it is “|”, issue such a tempo directive only for those events that coincide with bar lines. (When used at the beginning of the piece, the command is equivalent to a parameter -bartempo.) If you are lucky, all the main tempo instructions will be conserved without cluttering the score with the effects of MIDI ritardandi etc.
  • If it is “-”, do not react to those events at all. In other words, restore the default behaviour.
At the position of a /&Q command, the current /&T status has no effect.
/&T+P
Special decoration shorthands
/&DThe remainder of the text shall normally be put into each voice individually right before the next note occuring there, unless some other /&D, /&C, nonempty // or /&i... has been issued in between. Exceptions are described below. Typically used for global dynamics. Bar lines are not affected./&D!ff!P
/&CThe remainder of the text is considered the closing mark of the previous /&D event. In each voice, either both or none will appear, depending on whether there are any notes in between or not. The closure will precede any trailing rests. To be used for the closing mark of a global crescendo or decrescendo or similar./&C!<)!P
/&g usegdynIf directly followed by -, tells MidiZyx2abc to ignore any global dynamics (/&D) in this voice and forget any pending one, starting with this position until further notice. With +, it reactivates the default mode. Useful for solo voices, shared staves, passagewise exceptions, etc./&g usegdyn-VP
/&g gdynoverlayIf directly followed by +, tells MidiZyx2abc to make any global dynamics (/&D and /&C) effective immediately even if this voice is in the midst of a note, using bar overlay as in /&v. With -, it reactivates the default mode: simple code insertion, which takes effect at the end of the note./&g gdynoverlay+VP
/&g prefixgdyndirectly followed by +, -, or 0. In the first two cases, any ordinary preinsertion (“prefix”) code found in this particular voice after the current position will not invalidate any pending /&D text there, but be written before or following it, respectively. This behaviour will continue until further notice; /&g prefixgdyn0 returns the voice to the default behaviour, i.e. invalidating./&g prefixgdyn-VP
/&sThe remainder of the text is to be preinserted to any note starting here or later in this voice until (excluding) the next occurence of /&s. Typical case: staccato “sempre”. A naked /&s can be used at the end of this passage. By default, any // or /&i... of nonempty text will also end this mode; this behaviour can be changed as described below. (The position of the command need not coincide with any note and never causes any interrupt. Tied note continuations are of course unaffected.)/&s.VP
/&g prefixsempre
                
directly followed by +, -, or 0. In the first two cases, any ordinary preinsertion (“prefix”) found in this particular voice after the current position will not invalidate any current /&s text there, but be written before or following it, respectively. This behaviour will continue until further notice; /&g prefixsempre0 returns the voice to the default behaviour, in which any preinsertion code ends the sempre mode./&g prefixsempre-VP
These “special decoration shorthands” and similar functions can save a lot of work, but are not always easy to grasp in their interactions. Beginners are often happy with the default settings, whereas users with a sense of systematics typically prefer the settings /&g prefixgdyn- and /&g prefixsempre- throughout all voices. Also keep in mind that global dynamics do not cause any interrupts; use /&i, /&g gdynoverlay, or /&g usegdyn passagewise if desired.
Percussion
MidiZyx2abc identifies a track as a percussion track by the fact that all its notes have MIDI channel 10. Such a track is subject to a special percussion administration. If it has no %%MIDI header statement, %%MIDI channel 10 will be provided (future standardization pending). More importantly, if the following percussion map mechanism is installed, it will apply there, to allow for correct visual representation. Otherwise ordinary notes will be produced. See the chapter “Percussion Maps” below for further explanations and examples.
/&G percmapfollowed by a list of items separated by semicola. Each item must start with an abc note name (leading space characters will be ignored). Whenever a pitch is encountered in the MIDI file that would produce this note or an enharmonic equivalent (– not distinguishing between _D and ^C etc. –), the item is pertinent. A special value is *, it refers to all pitches that are not mapped otherwise.

After the note name comes either a space character or a channel number in brackets, 1 through 16, called “pseudo-channel”, which – only for the purposes of the “splitting by channel” mechanism! – causes all percussion notes of that pitch to be treated as if their MIDI channel number were the one given (although it is actually always 10). Each pseudo-channel occuring in a percussion track always gives rise to a separate voice, whether or not splitting is in force otherwise. The said space character, without brackets, is simply a shorthand for [1].

The remainder of the item text is what you actually want to appear in the code, replacing the note name, including any accidental, excluding the note length. Typically it will be another such note name, or at least end with one, but anything is allowed that suits your target software and contains no semicolon. Each /&G percmap statement applies to all percussion tracks of the whole tune. You can issue more than one such statement in a tune, but trying to map the same pitch twice is an error. As an exception, if the text for “*” ends with “=” or another “*”, MidiZyx2abc will put the original pitch for it, in a special predictable orthography: Black-key notes will be spelled with a single sharp; for white-key notes, either no accidental (in the * case) or a natural sign (in the = case) is used – all regardless of the key.
/&G percmap _B,, C-
Cue notes
/&qCreates copies of notes and other events from another voice as cue notes here. If the full ID of the voice to copy from follows immediately, this will be done until the position of the next /&q event. Otherwise the cue ends there. Transposition (of /&t... type only!) is adjusted in such a way that the function can also serve for “play in absence of” notes. After the ID (if any), you can add a space character followed by options: A signed number indicates an additional transposition in semitones for the subsequent cue notes (typically 12 or -12). Another option can be a single letter, either “n” for “copy note events only” or “y” for “only note or genuine lyrics events”. If a letter “p” is encountered, the whole remainder of the text will be inserted as a MidiZyx2abc “just-before” event into the cue passage, exactly as if it occured in a separate event super-prefixed /#q//. Example: For an entry of the voice Trp1, I want a cue from Hrn1, transposed up by an octave, but only the bare notes, then from Trp2 in original pitch with all decorations: /&qHrn1 n12 p"^Horn" ... /&qTrp2 p"^Trp. 2" ... /&q p"^Trp. 1" – the last event, containing no ID, ends the cue. Actually, all cue events for a voice will be collected in an additional abc voice called cue voice, whose ID is normally derived from ID of the former by appending the letter Q. Outside the actual cue passages, it is filled with invisible rests. The idea, of course, is that the couple shares a staff. For more details, see the chapter “Cue Notes” below./&qSopr yp"^Sopr."VP
/#qSuper-prefix to inject arbitrary MidiZyx2abc events to the cue voice. For details, see the chapter “Cue Notes” below./#q//"_Trp. 1"VP
/&g qFirstCauses MidiZyx2abc to set the cue voice before the main one whenever it has to make up an I:score line containing these, e.g. I:score (TrpQ Trp) – by default it will be the other way round. Depending on the software used for printing, this may influence the stem direction and the position of the rests./&g qFirstV
/&g qForDeclares this whole track a dummy track only carrying cue statements to form an additional cue voice for a different voice. The ID of that voice, the target voice, must follow after a blank. You can, after another blank, enter a number, which tells MidiZyx2abc where to put the new cue voice in a default score statement: the target voice is given a value 10, its own cue voice gets 15 by default, or 5 when /&g qFirst applies in the target voice. Smaller numbers result in earlier appearance. For example, a value of 20 will put the voice after the two voices at the target, normally adequate for cues using the lower part of the staff. A target voice can thus adopt many cue voices, but each dummy track can only have one target voice – whose /&t_in_... transposition, if any, will be inherited automatically. For more details, see the chapter “Cue Notes” below./&g qFor oboe 8V
Formatting the code
/&LThe remainder of the text represents the denominator of the basic unit as to appear in the L: field of the tune header, and to be used in the internal administration. Allowed values are 1, 2, 4, 8, 16, 32, or 64. A prefix :1/ is optional./&L:1/16
/&L16
-
/&lInsert an inline L: field, and act accordingly. The remainder of the text has the same meaning as in /&L./&l:1/16VP
/&o...octave=See above; typically used in the figure /&on[K:octave=-n] to relieve the abc code of excessive commas or apostrophes without changing its meaning. Make sure to use “octave=” consistently; MidiZyx2abc will never produce it by itself./&o-1[K:octave=+1]VP
/&EIn each voice, force the end of the current code line, usually to mark the end of a musical period. Any text following will be added to the code as a line-end comment./&ECue JoanP
/&VIWrite out the code up to here for all the voices before continuing with the first voice. If any text follows in the command, typically a comment about a new passage starting, it will be added to the code in a separate line. Often used in conjunction with /&B|$ or /&I$ (in the spelling of abc 2.1) which has the analogous effect in the rendered sheet music. Use \n in the text to demand additional line breaks. The output will resume afterwards with inline [V:...] directives. The example produces three comment lines./&VI%\n% Trio\n%
                  
P
/&VLSame as /&VI, except that resumed voiced will start with V:... on a separate line./&VLP
/&VCSame as /&VL, except that before each V:... line a separate empty comment line will be inserted./&VCI:sepP
Direct code manipulation
This delicate mechanism is meant as a last resort for otherwise unsupported features, such as quintuplets. Apart from explicit “overlays”, this is the only place where MidiZyx2abc commands may, and indeed must, contain abc items of nonzero effective note length. Mnemonics for /&n can be “not” or “nullify”. For more details, and an extended example involving lyrics, see the dedicated chapter below.
/&n[Suppresses all notes and rests in the passage of the voice from here until – but excluding (!) – the position of the next command of /&n type. (More precisely, note names, individual accidentals, tie markings, rest letters, and the corresponding length specifications will simply be omitted from the output, but not from the internal administration!) Instead of the first note or rest in the passage, the remainder of the text will be blindly added to the abc code. All other item types, e.g. decorations and genuine lyrics, will still be written mechanically as if nothing had happened – possibly attaining tweaked metric positions. Any overlapping notes and rests will be considered as split in two, as if /&i had been issued simultaneously, so that pending ties may result. It is your responsibility that before any important events, notably bar lines, suppression is interrupted and note lengths add up correctly. If you want to continue suppression there, issue another /&n[ command. Alternatively, use /&n: at slightly increased risk. Mind transposition and accidentals; always control the result./&n[(5cdefg ... /&n}VP
/&n}(with a closing brace, not bracket!) ends the current suppressed passage without starting a new one. Anything of the current position, including any bar line, will not be suppressed either. No added text is allowed./&n}VP
/&n:Has the same effect as /&n[, but additionally suppresses all bar lines in the passage, including any at its start, not affecting any at its end. Also additionally suppresses any text coming from /&b, /&B, and /&I commands found in the same range (– if you need such a text, copy it into this command at the appropriate place). Again, the internal administration, e.g. of accidentals, works as if all the notes and bar lines were present. Strong poison, ensure strict control. (A popular but abusive application is to omit a passage from all voices, with compensation either completely lacking or reduced to, say, a repeat sign – strictly at your own risk!)/&n:| A8 | B4 ... /&n}VP
/&nMHas the same effect as /&n:, but MidiZyx2abc will suffix the text with the number of bars in the passage, counted from its own administration for your convenience. Only allowed if both limits coincide with bar lines. The main application is to endow a multi-bar rest with the required length, for which your text must end with a capital Z. It is your responsibility to avoid overrunning any relevant event such as change of time signature, accelerated /&B command, repeat sign, and, of course, music./&nM|Z ... /&n}VP
/&n]This variant, closed by a bracket rather than a brace, still works but is deprecated. Its effect is the same as that of a /&n} at the next following interrupting event. The idea is to position the command at “the last note to be suppressed”, but the exact end of the passage is not always obvious to the user, and may change when seemingly unconnected changes are effected elsewhere, e.g. by /&I.DeprecatedVP
/&dThis variant still works but is deprecated as well. It acts like simultaneous /&n[, with the remainder of the text, and /&n] (bracket). The idea is to “suppress a single note”, but the same caveat applies as for /&n].DeprecatedVP
External text files
/&g section followed by a space character. Only valid inside an external text file (see next entry) at the beginning of a line, without any super-prefix. Starts a new section, whose name is the rest of the line. The previous section ends here. Arbitrary characters are allowed in the name, except for ']'. Space characters make a difference. If the file does not begin with a /&g section line, an additional section of empty name is defined to consist of the part before the first such line, or, if no such line is found at all, of the whole text. Within a file, each section name must be unique./&g section FluteVP
/&g includeThe remainder of the text may start immediately with a section name in brackets, optionally followed by a space character. If instead it starts with a space character, the empty section name is assumed. The remainder of the text must denote a file that contains text in UTF-8 format. If the specified string is not a complete (“absolute”) path, it will be considered relative to the directory of the file containing the statement. The file specification can be omitted; if this occurs inside a text file, the same file is assumed, otherwise the name and path of the current MIDI file is used with an added suffix “.txt” (without removing any existing suffix, thus possibly ending “.MID.txt” ). If the denoted file or section does not exist, a fatal error is diagnosed. Each line of the specified section will be treated as if a MIDI text event of exactly that content had been found in the same track at the same position as the original /&g include event. Arbitrary line lengths are allowed. The only constraint is that any MidiZyx2abcSettings tag inside the file will have no effect. Super-prefixes are respected, at the /&g include event and at each line inside the section. See the chapter “External text files” below. /&g include hd.txtVP
Plugin
/&G pluginpara ...<...Decrees default parameters for a particular plugin in the GUI window. See the chapter “Plugins” below. -
Settings – at last comes a command designed especially for people who are unhappy with the above prefixes:
If the magic word MidiZyx2abcSettings (or its replacement via a -magic parameter) is found inside any lyrics or text event of the file, no matter where, no matter how the text starts, the part of the text following it will be interpreted as a series of general options, separated by blanks (spaces). Each option starts with its keyword, directly followed by its value. Not all keywords must be present, and the order is up to you. Avoid ambiguity among the various tokens.

You can use more than one MidiZyx2abcSettings event, but any single keyword inside them is only allowed once per MIDI file, except for Case: (see the chapter “Named cases” below). Any such event will be ignored for all other purposes, even if it happens to have a relevant prefix.

Keywords are

Version:followed by n.mm, for example 1.00, the MidiZyx2abc version whose syntax is being used in the file (future versions will try to respect this, but no guarantee is implied)
Charset:followed by the standardized name of the charset or codepage used inside that MIDI file for texts and lyrics, for example UTF-8 or KOI8-R (cf. encyclopedia articles on “Character encoding”); the name AtariST is supported additionally. Users of UTF-16 or some exotic encoding methods must ensure that the keywords, the charset name, and the blank characters of this event are encoded in ASCII.
LyrCharset:followed by a name exactly like Charset:. Sets the codepage of the genuine lyrics, restricts the realm of Charset: to text and formal lyrics prefixed for MidiZyx2abc. Useful in files that originated in a different software or system from the one used to prepare them for MidiZyx2abc.
Before:followed by your choice of token instead of the above //
After:followed by your choice of token instead of the above /\
Other:followed by your choice to replace the above /& for all the tokens starting with it.
Channel:followed by your choice to replace the above /# for all the tokens starting with it (including the special value q with a different meaning). (Do not confuse this one with the keyword Channels:!)
Incase:followed by your choice to replace the above /? for all the tokens starting with it.
Case:followed by lists of case names; see the chapter “Named cases”.
Quantize: acts as if the corresponding -quantize:... parameter were present, and overrides any such parameter (!). See the chapter “Quantization” below.
Autosplit: followed by + or -, sets or unsets, respectively, the default value for the /&autosplit flag; overrides any -autosplit parameter.
Channels: followed by + or -, sets or unsets, respectively, the default value for the /&x flag to split tracks by channels; overrides any -channels parameter. (Do not confuse this one with the keyword Channel:!)
Lyrics:only allowed in the combination Lyrics:invert; tells MidiZyx2abc, if it encounters more than one genuine lyrics event for a note, to count them in inverse order, i.e. last verse first (to compensate for a peculiarity of some notation software).

Example:
.\MidiZyx2abcSettings Version:2.01 Charset:KOI8-U Before:./ After:.Aft Other:.+ Lyrics:invert Quantize:1/16t

Replacing the magic word by means of a -magic: parameter is rarely required, e.g. to switch between settings (– better use “named cases”); switched-off magic words will simply be ignored, if appearing in non-lyrics text events without meaningful prefixes. Choose a string, not too short, of basic characters (up to ASCII code 127); make sure it does not occur anywhere inside any other text event of the file.

Whatever you enter after those prefixes, as text to be inserted into the abc code, is entirely your responsibility. If it affects bars, accidentals, key signatures, or metric positions without compensation, MidiZyx2abc's internal administration is bound to be derailed. The correct way to apply such changes is to change the corresponding events in the MIDI file, or to use dedicated MidiZyx2abc commands.

For example, do not directly enter abc code producing

unless you have full control of the consequences.

Situations can arise where various settings conflict at a particular position. Ideally, the result will be either an error message or safely predictable from this documentation. However, sometimes a “straightforward” pragmatic solution is applied tacitly – best avoid relying on that.

As exceptions, MidiZyx2abc will notice and react to the presence or absence of the following header lines stemming from inserted text events:

X:If present, the line will be moved to the start, otherwise created. The specified number takes precedence over any -X parameter, but may be counted upwards to ensure uniqueness within the current output context.
T:If absent, it will be created to represent the file name sans suffix
Q:If absent, and no /&Q is found at the very beginning either, a header line will be created to represent the initial tempo in the file. All other MIDI tempo events are ignored by default; cf. /&Q and /&T directives.
M:, K:, or L:Ignored tacitly (as an exception), since MidiZyx2abc has its own ideas about these data, drawn from the MIDI file and from your commands /&K, /&L, and /&l mentioned above.
V:If absent in a particular voice (/&hV:...), it will be created with a unique ID.
%%abc-versionIf absent, it will be inserted as 2.1, together with a line I:linebreak $ (see above).
%%MIDIIf absent in a particular voice, and not represented by /&g midihd either, but possibly suitable “program” MIDI events are encountered there, one voice header line in the syntax %%MIDI program 53 will be provided, representing the first such event. All others are ignored. Voices dedicated to drums will obtain %%MIDI channel 10. Note that this reflects unofficial (and indeed somewhat unfortunate) de-facto standards.

Genuine Lyrics

When MidiZyx2abc encounters lyrics that are not MidiZyx2abc commands, it will prepare them to look in abc renderers as they would in notation software importing the MIDI file directly. Exceptions:

If such a syllable is found at a position where the voice has no note, and no /&i or /&I directive has been issued there either, MidiZyx2abc may tacitly move it to a lyricless note nearby, assuming it misplaced by a mouse-driven notation system.

That “poetic license” does not extend to text events prefixed for MidiZyx2abc! The logical position of such an event is taken literally, so check it carefully: it might not correspond to the point on the canvas where your notation system displays the text.

Whenever several genuine lyrics events are found at one position in a voice, they are put into distinct lines of lyrics, as normally used for repeats, variants, or additional verses. The order in which they are found in the MIDI file is mapped to the lines top-down. If your software consistently exports its lyrics lines in the opposite order, use the directive MidiZyx2abcSettings Lyrics:invert described above.

Remember that MIDI lyrics do not come with channel numbers; if you have a track with lyrics using more than one channel, and insist on splitting it by channels, control the result carefully!

MidiZyx2abc makes an effort to read “Karaoke” lyrics in a variant of the MIDI file format that is sometimes characterized by the file name suffix .kar – for example as created by the programme abc2midi. Since the format is not well standardized, success cannot be guaranteed.

Version notice: due to differing interpretations of the various abc lyrics standards, software may differ on the meaning of bar line symbols | at the beginning of w: lines, resulting in incorrect matching of lyrics syllables. If you need a radical workaround right now, you can avoid that situation by inserting /&E code line breaks.


Quantization

In order to make sense for notation, MIDI files must be quantized, which means that the position and length of each note must exactly correspond to the expected notation. If your music was entered by live playing, you should use the “quantize” function of your sequencer software selectively and carefully. For possible treatments of trills, grace notes, arpeggio chords etc. see the relevant chapter.

But since MidiZyx2abc is often used on less well-prepared files, it offers a primitive all-over quantization function. Users can command the rigorosity of the quantization by a keyword inside the MidiZyx2abcSettings event or by an external (“command line”) parameter. If both are used, the former overrides the latter. The parameter is also offered via a combobox in the standalone window. See above for details.

In the parameter following the -quantize keyword, or immediately after the colon of -quantize: or Quantize:, one of the following values must be specified: “1/64t”, “1/64n”, “1/32t”, “1/32n”, “1/16t”, “1/16n”, “1/8t”, “1/8n”.

Roughly speaking, this represents the smallest note value to be displayed. More precisely, in the specifications ending with “n”, the positions of all events of the file, including MidiZyx2abc text events, are rigorously rounded to the nearest multiple of the specified note value; no triplets at all will be produced or respected! With the “t” postfix, triplet positions are allowed, so that for example -quantize:1/16t also admits effective 1/24 notes – rounghly speaking, again.

The “1/” can be omitted. The default corresponds to -quantize:1/32t.

MidiZyx2abc may lengthen some notes slightly to avoid very short rests. If you actually want to see the latter at a particular position, issue a simple /&i event there.


Percussion Maps

In percussion contexts, some target software has its own fixed interpretation of abc notes. For example, when abcm2ps encounters a voice with clef=perc, it expects its notes as if for treble clef, using sharps for x-shapes and flats for circled x-es. To meet such a demand in MidiZyx2abc, you have to provide a /&G percmap mapping for each distinct note that occurs in the percussion voices of your MIDI file. The following example illustrates an idiomatic use of * in that context, to check for completeness without risking fatal error messages:

/&G percmap _E, ^e; _D, _e; E, ^f; _E,, _g; B,,, =D; * "^TODO!"*

Remember that in a section, the first note is only taken as a representation of its MIDI number, thus “_E, =e;” and “^D, =e;” would be completely equivalent, and “_E, =e; ^D, ^f;” would provoke a fatal error message. In contrast, the second part is taken literally. If a natural sign is specified, it will be added at each occurence, which may be useful to prevent some software from falsely assuming a propagation of accidentals.

This mapping is global for the whole file. If you insist on a distinction by voices or passages, transpose them to distinct areas, e.g. by /&o.


Voices

With respect to stem directions, rests, etc., percussion voices behave like normal voices. A typical drumset staff will have two or more voices sharing it. The easiest way to deal with this is to create one track per voice. If however your percussion voices consist of distinct instruments, as in most cases, the pseudo-channel mechanism is an alternative. For example, if you have a single percussion track, but want to have one voice for the cymbals and another one for bass and snare drums, you can declare something like

/&G percmap _E, ^e; _D, _e; B,,,[2]F; D,,[2]c

(– this example refers to the legacy system of abcm2ps). Note that the occurence of notes of non-uniform pseudo-channel numbers will always cause a percussion track to be split, no matter whether splitting by channels is commanded elsewhere or not. The channel super-prefix is available exactly as if the channels were real ones, and, like in those other cases, should be used at least for voice declarations such as /#2/&hV:lowperc to achieve complete score setups.


Mapping in the target software

There is abc software that allows for commands in the abc code to perform a percussion mapping by itself. Usually this mapping expects a predictable orthography, so that some /&G percmap is still advisable.

If you are targeting exclusively such software, and you have a separate track for each desired voice, the best idea is to issue a single statement /&G percmap * * (or /&G percmap * =) in that MIDI file, plus the required target mapping statements.

In contrast, if you need separation by pseudo-channels, you must specify the voice distribution via an otherwise trivial /&G percmap. You can save some typing by using * for the pseudo-channel with the largest number of mappings:

/&G percmap ^F,[1]^F,; C,,[2]C,,; D,,[2]D,,; *[3]*

All types of percussion map make good candidates for the “external text file” mechanism.


Cue Notes

MidiZyx2abc can create so-called “cue notes” – notes with small noteheads copied from other voices, which normally only serve as an orientation, rather than being played by the player reading them. They are typically considered helpful in single instrument parts, but not in full scores. This mechanism can save much work and reduce the probability of errors, since the actual copying is done by MidiZyx2abc. The processing abc software should understand staff sharing (I:score ... (...) ...) and the “de-facto standard” voice parameter V: ... cue=on as supported by the newest versions of abcm2ps and abc2xml.

Some programmes fail the second requirement but have a similar function which you can trigger by injecting a proprietary directive, e.g. /#q/&h%%voicescale 0.7 for older versions of abcm2ps. Note also that the correct treatment of rests may require special settings in the importing software, see “Plugins” below for examples.

For syntax details, see the section “Cue notes” in the above table. Remember that if a voice contains directives for one or more cue passages, possibly from various source voices, MidiZyx2abc will create one new voice which contains all those passages. The ID of this cue voice is, by default, the ID of the main voice plus the suffix Q.

MidiZyx2abc has a built-in algorithm to supply missing voice IDs. Also, it ensures uniqueness of each voice ID by adding a suffix if necessary. If you want to use the cue mechanism safely, you are advised to create your own voice headers /&hV:... for all real voices involved, specifying distinct IDs, none of which ends with capital Q. Setting the ID of the cue voice explicitly via /#q/&hV:... is also possible, but advisable only for the dummy tracks described in the next paragraph.

The cue notes will only be displayed if demanded either by an explicit score header like /&HI:score ..., or by the /&N mechanism. When in this mechanism single part sheets are created collectively, typically by a directive like /&N[], each will come with an I:score line like I:score (Trp TrpQ) at its beginning, if cues are defined for it. (If you specified /&g qFirst in the “Trp” voice, you will obtain I:score (TrpQ Trp) instead.) In your explicit part lists you can proceed analogously, using round parentheses, if you want to see the cues. If you need them for further processing, you may enjoy the /&N[|] directive.

You can inject arbitrary further MidiZyx2abc events into the cue voice, inside or outside an actual cue passage, by attaching the /#q super-prefix. This can be preceded, but not followed, by a /# channel number super-prefix (and, of course, named-case super-prefixes). For example, /&qBass 24p"_Dbl.Bass" has the same effect as if the following three separate events occured at the same position: /&qBass 24, /#q//"_Dbl.Bass", and /#q/&i.

If a voice contains no /&q passages at all, no directly associated cue voice will be created, thus any /#q injections there are ignored. The voice can still function as a target voice of the mechanism described in the next paragraph.

Copying is performed with limited sophistication, designed for standard situations only. Events occurring exactly at the position of the closing /&q statement will not be copied; instead, all pending notes and rests will be ended. Any other missing closure or opening, e.g. of slurs, sempre, suppression, or global dynamics modes, must be provided by the user via suitable /#q statements. Some obvious types of MidiZyx2abc event are exempt from copying altogether, including those that concern the whole voice, such as /&h.

A “mid-cue” /&q statement that specifies the same source voice as the preceding (unclosed) one causes no event to be lost. If the transposition stays the same as well, overlapping notes will not be truncated either, as an exception. Such statements are typically used to change the type filter: if you want to prevent particular non-note events from being copied, you can redeclare short passages with the “notes only” variant (/&q... n), combined with /#q injections if necessary. For example, you may want to change some /&f flags due to transposition issues.


Several cue voices for one part

Sometimes we want more than one cue voice for a real voice, either to allow for both upper and lower cues, or to cue from several voices simultaneously. This case is not common enough to justify a complication of the ordinary cue syntax, therefore a trick is required: Create one empty MIDI track per additionally desired cue voice, only enter one special directive /&g qFor ... to it with the voice ID you want cued, and cue instructions of types /&q and /#q. The latter should include a pro-forma header statement setting the ID for the new cue voice, e.g. /#q/&hV:oboePianoLh, and, if necessary, a translation of “cue=on” for your target software. Whenever you write a score statement yourself, do not forget to mention the cue voices you want, e.g. I:score (oboeQ oboe oboePianoLh).

A dummy track does not give rise to a non-cue voice. Do not add notes or other irrelevant items to it.


Reuse of cue voices

As we have seen, every cue voice refers to a single main voice which determines the transposition. This taken into account, you are free to reuse it on a staff with a different voice, by an explicit score directive. For example, assume you have a dummy track whose cue voice you named “lowWindCuesInBb”, referring to the trumpet voice. Provided that your clarinet voice never switches to the A instrument, /&HI:score (trumpetQ trumpet lowWindCuesInBb) (clarinet lowWindCuesInBb) may produce a reasonable result. (Writing all cues in C or in the transposition of their origin is a bad but tradition-honoured makeshift.)

Using many non-overlapping cue voices in varying combinations makes sense in some, rather rare, circumstances.


Caution with MusicXML

The current MusicXML standard is clear enough about “cue” properties, which it expects attached to individual items. The tool abc2xml produces these accurately from the abccue=on” mode.

However, some products that claim to import MusicXML files still ignore these attributes altogether, others produce clearly wrong item sizes in some circumstances – careful checking is advisable. Users should press for correct implementation, particularly if they paid money. (Generally, programming MusicXML import can be tedious due to the target software's different internal organization of cues. Perhaps MusicXML, which now has the same owner as Finale™, will one day offer a more compatible alternative.)


Named cases


Names for cases

A MIDI file can be prepared so that MidiZyx2abc can produce various abc texts from it, representing possible variants among which the user can choose “on the fly”. For each item of choice, you invent a name, such as “ScoreForJane” or “withRepeats”, which must not contain any space characters, commas, semicola, or full stops (periods). Beware also of characters that may be disallowed in call parameters or mismatched with your MIDI file text events; best avoid diacritics, non-Latin characters, quotation marks, apostrophes, backslashes etc. Case names are of course case-sensitive.


Setting the case(s)

There are two ways of telling MidiZyx2abc which named cases to consider active. “From outside” you can use the call parameter -case, followed by another single parameter containing the list of names to become active simultaneously, separated by commas (without space characters). Alternatively, use the colon syntax described above; example: -case:score,withPiano,forJohn

The other method is to set them inside the file, using the Case: keyword within the MidiZyx2abcSettings event (see above). Again, names are separated by commas (without space characters). Named cases always apply to the complete file, no matter at what position MidiZyx2abcSettings is found. Note that this may be overridden by the call parameter, see below.

In either method, you can specify more than one list, separated by semicola. Each of these lists results in a separate tune (or more than one, if /&N features become active as well) from the same MIDI file, consecutively into the same output. Case-driven score specifications can help you to avoid unwanted doubles. Example: MidiZyx2abcSettings Case:soli;tutti,noCembalo (or a parameter -case:soli;tutti,noCembalo) produces two scores from the same MIDI file, one with soli and another one with both tutti and noCembalo activated.

You may specify case names that do not actually exist in the current MIDI file and thus have no consequence for it. This will pass without any error message, as it is sometimes required when batch processing many MIDI files at once. The drawback is that correct spelling is your own responsibility.

If both methods are used in conjunction, the Case: values from MidiZyx2abcSettings are ignored. This works even with an empty -case: parameter.

In the GUI window, the text entry field marked “Activate cases:” corresponds to the -case value parameter. If you have loaded a MIDI file, you will find all case names mentioned in it as menu items of the menu “Cases”. Selecting one of these will add that name to the list in the entry field, deselecting will remove it. A completely empty text field is interpreted as the absence of any case setting, so that any MidiZyx2abcSettings Case: setting becomes effective if found. In the very rare case that your file specifies a nonempty such list which you want to override with an empty one, enter somthing unused into the text field.

Some case lists are too long to fit into a single MidiZyx2abcSettings event. Therefore a syntax Case:;n:list is offered, where n stands for an arbitrary word (which contains neither space characters nor colons), used only for its alphabetical position. The remaining parts of all such statements in the file will be considered concatenated mechanically, in ASCII-alphabetical order of their n prefix. If a statement without such a name exists, it will come first of all. An unrealistic example: The following three text events
MidiZyx2abcSettings Case:;220:te,
MidiZyx2abcSettings Case:flu
MidiZyx2abcSettings Case:;23:John
will have the same effect as a single
MidiZyx2abcSettings Case:flute,John
regardless of their places in the file. Duplicate n will result in an error message. Note that no similar syntax for -case parameters is currently avaliable –.


Making directives depend on named cases

Those MidiZyx2abc directives that you want to be in force only in certain such cases, you must mark with the “super-prefix” /?, followed by a list of case names, separated by commas, always ending with a full stop “.” (even if it only consists of a single name!). Each name can be prefixed with a minus sign. The event will be valid if any of the names without minus sign is active, or if any of the minus-prefixed names is not active. In this case the event will simply be considered as if the part from /? until the full-stop were not there. The remaining part can be a lyrics syllable or a MidiZyx2abc directive of any kind, or even have another /? prefix. The only types of text event that cannot be case conditioned are /g section lines and MidiZyx2abcSettings. (If you insist on switching the latter, you can use the parameter -magic:.)

Example: A text event /?-export,xml.//"Cm" will actually produce a “Cm” chord symbol if either the named case “xml” is activated or the named case “export” is not.

If you want an event to be valid only if several conditions are all met in conjunction (“AND” logic), use several /? super-prefixes. For example, /?clar,trumpet./?-concertScore./&t_in_Bb will only amount to /&t_in_Bb if either “clar” or “trumpet” is active, and “concertScore” is not.

Sometimes a treatment “if ..., else ...” is desired. To cover this, you need two separate /? statements specifying complementary conditions. For example, one lyrics event could be /?female.she's, and another one at the same position /?-female.he's. The syntax is designed for slimness, not for particular comfort in very complicated cases.

Within a text event, all /? parts must precede any /# super-prefix.

Note that MidiZyx2abc has no way of checking whether a case name is mistyped. If you are in doubt, you can check the “Cases” menu for near-doubles.

Extensive usage of named cases can easily cause confusion. It is a good idea to use telling names and explain them with their intended usage in comment lines, e.g. in the header via /&H%... or in external text files.


External text files

Anywhere in a MIDI file, you can create a /&g include event to inject further MidiZyx instructions from a separate ordinary text file, for ease of reading, editing and possible reuse. See the syntax table above. (Obviously, MidiZyx2abcSettings events cannot be externalized that way.)

Auxiliary files generally pose the problem that they tend to be forgotten when the main file is moved or copied. Use them only if you are sufficiently organized. Use file and directory names that help you remember. For inter-system mobility, MidiZyx2abc tries to translate the spelling of paths; the rest is your responsibility.

This said, external text files can be very helpful with large scores, particularly for collecting “global” stuff such as tune header lines, percussion maps, and score directives (/&N). You may create text files dedicated to single MIDI files, and others to be reused. As an example of the latter, consider a file named “Instruments.txt” containing the following lines:

/&g section French Horn 1
/&hV:hr1 name="Hr. 1" clef=treble
/&g midihd French Horn
/&t_in_F
/&g section French Horn 2

...

Then at the beginning of the pertinent voice in the MIDI file, you only need a single text event like

/&g include[French Horn 1] ..\My Text Files\Instruments.txt

– provided you can use (and remember) the voice ID exactly as given in the text file.

Such text files may contain /&g include lines in turn – be careful! Remember that conflicting statements will usually cause fatal error messages rather than controlled overriding. Make sure to keep track of case names etc.

If the MIDI file contains a MidiZyx2abcSettings statement, its settings of super-prefixes and prefixes apply to external text files as well, as opposed to any Charset: setting.

As with MIDI text events, any text lines that do not start with a recognized prefix will be ignored. This effect can be used to add empty lines and comment lines, highly recommended. It can also be used to disable some lines temporarily by adding a suitable character at the beginning, which is easy to remove for reenabling (– slang expression: “commenting out”). Often a named-case prefix is the better choice, or inserting another /&g section line with an unused name.

All characters count, including leading and trailing space characters, except for a UTF-8 BOM (—unnecessary but tolerated). Beware of typos.

The command starts with a lower-case /&g to indicate that the track in which it is found is taken into account. The file it points to can well contain other types of MidiZyx2abc text, such as tune header lines. Be careful to avoid unwanted multiplicities. Also, be aware that for a file that contains some /&g section, omitting the section name only refers to the part before the first such line; you can symbolize that by the spelling /&g include[] ..., or better, by issuing a nonempty section name right at the beginning. If you want to include more than one section, you must issue one separate statement for each.


Omitting file specifications

One possible method of organizing is to omit all file specifications in the MIDI file, using statements like

/&g include[2nd movement]

This works if all sections to be directly included are collected in a single dedicated file, which is to be placed following the recipe described above. For example, if your MIDI file is MySong.mid, the text file must be MySong.mid.txt in the same directory as the MIDI file. If you need globally reusable sections as well, e.g. for your favourite percussion map, you can use /&g include statements inside that MySong.mid.txt, so that your MIDI file need not contain any explicit path or file name.

You can also use the syntax without file specification within a text file, to refer to different sections of the same file. Thus you can reuse some sections in several other sections.


MusicXML conversion

Since subsequent conversion to MusicXML is a main use case and Wim Vree's abc2xml is the main tool for it, MidiZyx2abc offers a special shortcut that allows you to use abc2xml without touching a command line. All you need to do is the following:

If these conditions are met at the beginning of a MidiZyx2abc session, an additional menu item "Save MusicXML ..." will be offered. Similarly to the ordinary "Save as ...", it will take the current contents of the text area as-is, convert them using abc2xml, then save the result to a (Music)XML file you choose. You can open this XML file with a pertinent music notation software.

Note that the abc2xml option "-r" will be used, as required for the cue mechanism to work correctly. Users who want different abc2xml options, or their MusicXML files to be opened immediately in their notation software, will use the plugin feature.

Note that abc2xml only converts the first tune it finds. Read about other restrictions and peculiarities on the homepage.

If you have tinkered with the code and produced what normally would be considered syntax errors, abc2xml will nevertheless try to make sense of it and may issue some strange-looking "warnings".

The Python module, when first called, will create a subdirectory named "__pycache__" to speed up future calls.

The internal functionality of abc2xml may change; please notify both programmers if you find any incompatibilies.


Plugins


Why?

The results from MidiZyx2abc are often meant to be processed by other software immediately. In batch mode, this is straightforward. For the GUI window, the clipboard and saving functions can do everything we want, but are sometimes considered too tedious, particularly while experimenting. Therefore you can arrange for self-written batch files (= scripts) that can be called directly from the MidiZyx2abc menu, whereupon the current content of the text area is communicated via a temporary file whose path is passed as a parameter.

This chapter is for users who know how to write and operate batch files or scripts or have such experts at hand to whom they entrust their system. AI tools like ChatGPT can be of valuable assistance but must never be trusted blindly.


How do plugins work?

The mechanism can be called “poor man's plugin” because when activated, it simply writes the current content of the text area to a newly created temporary abc file in your OS's “Temp directory”, and then issues a system call to the plugin, passing the path of that file as the first parameter. The second parameter will be the full path of the MIDI file last loaded (if any, otherwise a dummy). Other parameters may follow; see below. MidiZyx2abc will inform you if the starting has gone wrong, but has no control over the further process, whether your batch files crash, run forever, or work incorrectly. At the end of its own window session, it will try to delete its own left-over temporary files; however, this will fail for files that are locked by other software. Best take care of that yourself, and declutter regularly.

Since the text is freely editable, it is your responsibility whether or not it is valid abc code and has anything to do with the MIDI file mentioned in the second parameter. The window can even be abused as a mere GUI interface, with hand-typed abc code or even arbitrary text.


The plugin directory

When MidiZyx2abc is opened as a GUI window, it registers plugin files from one single directory. This directory can be specified by the parameter -plug, otherwise the so-called user directory (depending on your operating system) is considered, but if no suitable candidate is found there, the directory where MidiZyx2abc.jar resides is assumed. You can specify a directory that does not (yet) exist or contain any plugins.


Plugin files

Only those files count that are deemed executable (i.e. either scripts or real programme files) by your system, and whose names start with MidiZyxPlugin, followed by zero or more of the letters B or A, followed by an underscore _. These letters indicate: B – the temporary file shall have a BOM; A – the temporary file shall contain a file header (%abc etc.; otherwise the text will simply start with the X: line). Note that these choices are imperative and override the current selection status of the two corresponding check boxes – these apply only to the “Save as...” menu item. Most plugins have none of these requirements, so that their file names simply start with MidiZyxPlugin_. Files violating any of these rules will be overlooked tacitly.

The names of the files that passed this test are listed in the “Plugins” menu, with the prefix MidiZyxPlugin omitted for brevity, and the option part moved to the end, then sorted alphabetically. Clicking one of these will run the corresponding job without further questions. Be careful!

If you add, rename, or delete a plugin while the window is open, you must click the menu item “Recollect” or restart MidiZyx2abc for this to be noticed. Changing the contents of a script file does not require such an activity.


Menu item separators

You are strongly advised to keep only those plugins in your plugin directory that you need for the current project and whose mechanism you remember exactly. This will probably be a small number, so that alphabetical listing should be enough of an organization. If you need a different ordering, tweak the file names. However, in some cases a menu item separator (a horizontal line in the drop-down menu) comes handy. You can produce it by creating another file whose name starts with MidiZyxPluginS_, in the plugin directory. The rest of the file name will only be considered in its alphabetical relation to the genuine plugin names, to determine the position of the separator. The contents of the file and its authorization status are ignored; best make it of zero size, at least non-executable.


Parameters on the spot

Sometimes we want to experiment with settings for the target software. This can be done by editing the batch file, but we may prefer to design it so that it accepts those settings as additional parameters. In the window, there is an entry field for such parameters, to be separated by blank characters as if on the command line, thus starting with parameter three. (Parameters with inside quotes may be rejected by Java.) Again, be very careful!

It is a common pitfall to prepare the entryfield for one plugin, then click for another one that expects different kinds of paramters. The field is not meant for permanent usage. When I am satisfied with my experiments for a project, say for Beeth9.mid, I create a dedicated batch file Beeth9.bat for it with all options hard-coded, and leave the entryfield empty.


Parameters from the MIDI file

Parameters for specific plugins can also be preset by commands inside the MIDI file (– typically via an external text file). The syntax is:

/&G pluginpara plugin_name<parameters

where plugin_name stands for the name, to be spelled exactly as found in the menu item. Then, if you click that menu item while the entry field is completely empty (not even contain a space character!), the text of the parameters part will be copied there and used immediately.

Qualification by named cases works as usually, but if for some plugin name, conflicting settings are active within the window, an error message will result.

In contrast, it is not diagnosed as an error if currently no plugin of the specified name is available. You can recognize a typo by the fact that when you call the intended plugin, the expected copying into the entry field does not take place.


Examples for Windows™ users

You are free to use any scripting language available on your system. The following examples use the ancient DOS-Windows language for the only reason that it is the one most widely known. Not only the paths, but also the behaviour may well be different for different environments and software versions.

I want to try the result of my work in a notation software via MusicXML as created by Wim Vree's Python script abc2xml.py. In the directory where MidiZyx2abc.jar resides, I create a batch file named “MidiZyxPlugin_To Finale .bat“ from the following skeleton:

set myPython="C:\Tools\Python2.7\python.exe"
set myAbc2xml="C:\MusicTools\abc2xml\abc2xml.py"
set myXmlImporter="%programfiles%\Finale NotePad 2012\Finale NotePad.exe"
REM --------
REM abc2xml will write its XML output into the *current* dir; switch to the temporary one:
%~d1
cd "%~p1"
start /W "" %myPython% %myAbc2xml% %1 %3 %4 -o. -r
REM  -r is required when using cue voices
erase %1
set targetXml="%~dpn1.xml"
if not exist %targetXml% exit
%myXmlImporter% %targetXml%

Next time I start MidiZyx2abc or click the menu item “Recollect”, I find an entry “To Finale .bat” in the “Plugins” menu. When I click it after opening a MIDI file, it does what I expect in a couple of seconds.

But what about the part %3 %4? Normally, these will be empty parameters, doing neither harm nor good. If however I enter -p "1.2,300,200,10,12,10,10" into the entry field labeled “At the next plugin call add:”, abc2xml.py will recognize this as the two (!) parameters for its page formatting option. I can try out various value combinations and check their effect quickly – provided, of course, that I remember the exact syntax and meaning. The quotes are necessary because in these special circumstances, non-quoted commas may have the role of parameter separators.

We also want a plugin “To abcm2ps to PDF .bat” so that no other GUI wrapper is needed. Using the popular Ghostscript tool in batch mode is something of a challenge. Here is a blueprint skeleton – be sure to know exactly what you're doing!

REM Up to three abcm2ps options can be set manually, e.g. -s0.575
set myAbcm2ps=C:\MusicTools\abcm2ps-8.1.5\abcm2ps.exe
set myGhostscript="%programfiles%\gs\gs9.14\bin\gswin32c.exe"
set myPDFreader="%programfiles%\Foxit Software\Foxit Reader\Foxit Reader.exe"
REM --------
REM abcm2ps will write Out.ps into the *current* dir; switch to the temporary one:
%~d1
cd "%~p1"
start /W "" %myAbcm2ps% -j0 -N3 %3 %4 %5  --combinevoices -1 "%~nx1"
REM  --combinevoices -1 is required when using cue voices
erase %1
if not exist Out.ps exit
REM --------
REM Ghostscript; takes its parameters from a file
set targetPdf="%~n1.pdf"
echo -q -P- -dPARANOIDSAFER -dNOPAUSE -dBATCH -sDEVICE#pdfwrite >MidiZyxTempParam.txt
echo -sOutputFile#%targetPdf% >>MidiZyxTempParam.txt
echo -dCompatibilityLevel#1.4 >>MidiZyxTempParam.txt
echo -c .setpdfwrite -fOut.ps >>MidiZyxTempParam.txt
%myGhostscript% @MidiZyxTempParam.txt
erase MidiZyxTempParam.txt
erase Out.ps
if not exist %targetPdf% exit
REM --------
%myPDFreader% %targetPdf%

In both examples, some tricky tasks of cleanup and error treatment have been omitted. Experts should consider using non-file process communication whenever available.


Splitting, Autosplit

The positions where to split a note or rest inside a bar, or to interrupt possible beaming, depend on the metre, the rhythmic situation, and very much on the author's taste. Therefore MidiZyx2abc offers several mechanisms to identify such places without having to issue individual /&i or //  commands (- which of course will always be obeyed).

The commands /&g split and /&g unbeam will often reflect the user's current interpretation of the current metre. For example, in a 7/4 metre that the composer considers subdivided after 3 beats, /&G unbeam 12 will probably be desired, twelve sixteenths amounting to those three beats. It is also conceivable to switch between /&g split 12 and /&g split- passagewise. If in a 4/2 metre you want split points after each beat, /&g split 8 8 8 will produce them, or /&g split 8* for short. Now assume an 11/8 metre of which the first three beats form a unit: /&g split 6 4 4 4 may be what you want, which is equivalent to /&g split 6 4*. (The asterisk is only allowed at the end.)

Note that a /&g split statement will survive any change of metre or autosplit mode. It can only be revoked for that voice by another /&g split, possibly /&g split-. The same applies to /&g unbeam, which forms an entirely independent mechanism.

Wherever either /&g split or /&g unbeam is absent or revoked, the “autosplit mode”, if switched on, can provide defaults. This is meant for users who value comfort over exact control; MidiZyx2abc reserves the right to change the exact behaviour of that mode in future versions.

Note that repositioning bar lines via /&B statements will trick out the metre and thus the splitting mechanism. Use MIDI metre events instead whenever possible.

Example: For an ordinary piece in 4/4 time, just two commands, /&G split 8 and /&G unbeam 8 at the beginning of one arbitrary track, often suffice to produce a behaviour similar to most music software. (/&G split 8 is often omitted, or overridden in mid-tune; a matter of taste.)

When all that intentional splitting is done, single fragments of notes or rests may still have note lengths that are not directly printable, such as 5/4. MidiZyx2abc will split these where it deems fit. If you prefer a split at a different place, or an additional split, mark it with /&i.

In some situations, inserting /&i can also adjust the distribution of triplet marks, even if nothing is being split visibly.


Direct code manipulation

This feature is mainly recommended for tuplets that are not triplets. Possible other usages include the bridging of various ornaments spelled out in the MIDI file, such as trills and grace notes – better replace them in the source by their main notes and decoration text events.

Here is a more extensive example. Assume you want to produce a quintuplet for a vocal part. For added difficulty, you want the first and last note tied to notes outside the quintuplet, so that the resulting code looks like:

A8- | (5:4:5 A2 B2 !>!c2 d2 e2- | e8 |]
w: I_ guess I'm in love!_

This cannot be produced directly from a MIDI file. The solution is to replace the quintuplet in the original MIDI file by five notes of arbitrary lengths that only sum up correctly, just to carry the lyrics. (If any global split points interfere, choose the lengths to reflect the final situation in that respect.) If MidiZyx2abc were used now, the output, consistent but not yet what you want, could be something like

A8- | A2 B2 c2 d e- | e8 |]
w: I_ guess I'm in love!_

Do not add the desired accent via a //!>! event, since after the following tweaking it would no longer be at its correct position – other than the lyrics. Also, make sure that no such interference comes from outside. Now, on the first note of the second bar, add a single text event with abc code for all the notes, ties, rests, and decorations etc.:

/&n[ (5:4:5 A2 B2 !>!c2 d2 e2-

and at the start of the third bar (– the position where to return to ordinary notes –) add another text event

/&n}

– the desired result will be achieved, with all ties miraculously in place. Note that the suppressed passage actually resides inside a single bar, which is crucial.

For passages without lyrics, things are easier: the number of notes is irrelevant, just their overall length matters.


Miscellaneous hints

abc is the perfect language for typing little snippets like those after the MidiZyx2abc prefixes. However, there is no easy way to edit a large abc score in a text editor (and certainly not in the MidiZyx2abc window). Therefore you will probably prefer to apply any changes, even minor ones, on the original “MidiZyx” file, and re-export it then. Only after you have decided to forget the old version completely, apply your further changes in the target notation software.

If you have tracks for keyboards, guitars, harps, etc. containing polyphonic passages, you best split them up into several tracks and reassemble them in the target score by inserting something like /&HI:score { (Right1 Right2) | (Left1 Left2 Left3) }. Alternatively, differentiate by MIDI channel, as many notation software products do. Make unwanted rests disappear using the /&rx command.

For a large project, start with clearly preparing the set of voices you need, tracks to be split by channel, voices that later must share a staff (with x or with z rests?), transposition, octave, etc. Also correct the quantization if necessary. Then carefully make those settings that have far reaching impacts, such as global dynamics, splitting and unbeaming modes, special bar lines (/&B), assumed keys (/&A), L: settings, etc. Details that only affect short passages come last, since their necessity and effect often depends on those larger settings. For example, any grace notes, explicit overlay, or “direct code manipulation” may well become wrong if the wider context is changed afterwards.


Instrumentation variants

Named cases can be used for many variants, including a non-transposing “concert score” (– qualify the t..._in_... events by a case prefix). Another typical usage is to cater for an alternate instrumentation: let clefs, transposition, subtitle line etc. depend on named cases. Arbitrary instrument part sets can be produced in a single run, by combining named cases with /&N directives and semicolon-separated case lists.

Example: Suppose you have a piece for violin, viola, and piano. You want a score, parts, additional parts for clarinet in Bb from the violin and viola voices, and a part for alto saxophone from the viola voice. One of several ways to achieve this is to use named cases “TwoClars” (the two clarinet parts), and “SaxOnly” (alto sax part). Insert the following texts at arbitrary places in the MIDI file:

/?TwoClars./&N[violin][viola]
/?SaxOnly./&N[viola]
/?-TwoClars./?-SaxOnly./&N[[]][][{rh | lh}]

(To produce a single-staff sheet for both clarinetists, replace the first line by /?TwoClars./&N[(violin viola)].)

At the beginning of the violin track, add the following text event:
/?TwoClars./&t_in_Bb

At the beginning of the viola track, add the following text events:
/?TwoClars./&t_in_Bb
/?SaxOnly./&t_in_Eb
/?TwoClars,SaxOnly.//[K:clef=treble]
– assuming that the voice header specifies clef=alto. If your viola part contains clef changes, qualify them accordingly.

Now you can set the case lists, e.g.
MidiZyx2abcSettings Case:;TwoClars;SaxOnly
to obtain the complete set in one go. Note the semicola, particularly the first semicolon ending an empty case list, which activates the third of the above commands, with the minus signs, to produce the score and the three parts in C. Make sure to cover all cases, and that your target software understands your code. If you feel uncomfortable with multiple conditions, use an extra case name such as “Normal”.

If your violin part has cue notes defined via /&q, you may for example replace [violin] with [(violin violinQ)].

Don't forget to have the instrument name printed on each part sheet, managed via those named cases.




Appendix 1: Some of the most useful abc elements

... each with its appropriate MidiZyx2abc prefix. Most present-day abc software supports most of these, and many MidiZyx2abc magicians need not know much more about abc than this. If your software requires a different dialect, e.g. + instead of !, the difference is usually easy to take into account.


Header
/&HT:My First Symphonytitle of the piece
/&HC:John van Beethovencomposer, arranger
/&hV:Clar name="Clarinet"voice header
/&HI:score [{Vl1|Vl2}|Vcl]score layout, using the voice identifiers found at the beginning of the V: fields
/&H% use -s0.53comment, also handy as a notepad for further processing
Global delimiters (those starting with /&B will always force a new bar in MidiZyx2abc)
/&B|:start of a repeated section
/&B:|end of a repeated section
/&B:|:start and end of a repeated section
/&B||double bar line
/&B|1start of first variant in a repeated section at a bar line
/&I[1start of first variant in a repeated section, not at a bar line (rare)
/&B:|2start of second variant after a repeated section (seems to end at the next double bar line)
/&B|(MidiZyx2abc syntax: force a new bar without announcing a change of metre, in case of irregularities)
/&B|$ or /&I$force a line break in the score (but not in the code, cf. /&E)
Annotations
//"^mute"annotation above the staff
//"_sempre accel."annotation below the staff
Ornaments and other decorations
//.staccato
//!>!accent
//!fermata!fermata
//!D.C.!da capo
//!trill!short trill; for more decorations consult the standard document or the manual of your abc software
//!pp! etc.dynamics for this voice only
//{/c}slashed grace note(s), with note names in abc syntax
//{cB}grace note(s), with note names in abc syntax
//"D#maj7"chord symbol
//  (a space character)do not beam from the previous note
Extended decorations taking one event to start and another one to end
//( ... /\)slur (note the exceptional backslash in the closing mark!)
//!<(! ... //!<)!crescendo for this voice only
//!>(! ... //!>)!decrescendo for this voice only
//!trill(! ... //!trill)!extended trill (might not be supported by your software)
/&s. ... /&sspecial MidiZyx2abc syntax: staccato on all notes in between; see above for exact regulations
/&s!>! ... /&sthe same with accents (etc.)
Global dynamics (special MidiZyx2abc functionality, see above)
/&D!pp! etc.dynamics for all voices
/&D!<(! ... /&C!<)!crescendo (start and end) for all voices
/&D!>(! ... /&C!>)!decrescendo (start and end) for all voices


Appendix 2: Some common transposing instruments

with their MidiZyx2abc transposition marks.


Conventionally transposing instruments
/&t_in_FCor anglais
/&t_in_BbClarinet in Bb
/&t_in_AClarinet in A
/&t_in_Eb+Clarinet in Eb
/&t_in_Bb-Bass clarinet
/&t_in_EbAlto saxophone
/&t_in_Bb-Tenor saxophone
/&t_in_Eb-Baritone saxophone
/&t_in_FFrench horn in F, usual notation
/&t_in_Bb-French horn in Bb basso (in classical music)
/&t_in_C-French horn in C basso (in classical music)
/&t_in_EbFrench horn in Eb (all other classical transpositions similarly)
/&t_in_BbTrumpet in Bb
/&t_in_F+Trumpet in F (in classical music)
/&t_in_D+Trumpet in D (in Baroque or classical music)
/&t_in_Bb-Tenor/baritone horn
Octave transposition (in a way of thinking)
/&t_in_C+Soprano recorder
/&t_in_C+Piccolo flute
/&t_in_C+Celesta
/&t_in_C-Guitar (when an ordinary treble clef is used)
/&t_in_C-Double bass, bass guitar


Appendix 3: standard MIDI sound program names

In the first column of the following table you find a zero-based sound number, as used in %%MIDI program. The second column lists the sound name, in the spelling recognized by /&g midihd ..., for that number and for the seven next numbers, separated by commas:

0Grand Piano, Bright Piano, Electric Grand, Honky-tonk Piano, Electric Piano, Electric Piano 2, Harpsichord, Clavinet
8Celesta, Glockenspiel, Music Box, Vibraphone, Marimba, Xylophone, Tubular Bells, Dulcimer
16Draw Organ, Perc. Organ, Rock Organ, Church Organ, Reed Organ, Accordion, Harmonica, Tango Accordion
24Nylon Guitar, Steel Guitar, Jazz Guitar, Clean Guitar, Muted Guitar, Overdrive Guitar, Distortion Guitar, Guitar Harmonics
32Acoustic Bass, Fingered Bass, Picked Bass, Fretless Bass, Slap Bass, Slap Bass 2, Syn. Bass, Syn. Bass 2
40Violin, Viola, Cello, Contrabass, Tremolo Strings, Pizzicato Strings, Harp, Timpani
48Strings, Slow Strings, Syn. Strings, Syn. Strings 2, Choir Aahs, Voice Oohs, Syn. Voice, Orchestra Hit
56Trumpet, Trombone, Tuba, Muted Trumpet, French Horn, Brass, Syn. Brass, Syn. Brass 2
64Soprano Sax, Alto Sax, Tenor Sax, Baritone Sax, Oboe, English Horn, Bassoon, Clarinet
72Piccolo, Flute, Recorder, Pan Flute, Blown Bottle, Shakuhachi, Whistle, Ocarina
80Square Wave, Saw Wave, Syn. Calliope, Chiffer Lead, Charang, Solo Voice, 5th Saw Wave, Bass & Lead
88Fantasia, Warm Pad, Polysynth, Space Voice, Bowed Glass, Metal Pad, Halo Pad, Sweep Pad
96Ice Rain, Soundtrack, Crystal, Atmosphere, Brightness, Goblin, Echo Drops, Star Theme
104Sitar, Banjo, Shamisen, Koto, Kalimba, Bag Pipe, Fiddle, Shanai
112Tinkle Bell, Agogo, Steel Drums, Woodblock, Taiko, Melo Tom, Synth Drum, Reverse Cymbals
120Guitar Fret Noise, Breath Noise, Seashore, Bird Tweet, Telephone, Helicopter, Applause, Gun Shot

Additionally, some common names such as double bass, organ, and piano are supported. Note that the text of /&g midihd is case-insensitive.