MidiZyx2abc

(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

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:

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:

• make beautiful prints using free abc software (e.g. based on abcm2ps or LilyPond) of work-in-progress residing in your customary sequencer or notation system,
• make even more beautiful prints of that work, using your friend's expensive notation software that can somehow read abc, typically via MusicXML *),
• send your music by email as abc text, to persons not known to own the software you are using,
• post your music as abc text to discussion forums etc.,
• use your notation system as an “editor” for ad-hoc abc postings to discussion forums etc.,
• move your music files, possibly endowed with many ornaments, from an older notation system to a newer one *),
• mail your music to a publisher of sheet music, typically (to be) transformed to MusicXML,
• perform major operations, such as adding global score dynamics, on existing primitive abc files, after using an abc-to-MIDI conversion software,
• use it on existing MIDI files without any MIDI sequencing software, alternatively to other existing midi2abc implementations, either as a makeshift for one of the above purposes ...
• ... or to serve any of several gaming platforms that accept abc text for personal jingles,
• etc.

*) 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.

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

• allow the input of lyrics or other text events,
• allow the input of metre signature changes, if required,
• and export these correctly to standard MIDI files.

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.

• Prefixes and super-prefixes
• Defining voices and tunes
• Header and footer
• Interrupting notes, rests, staves, lines
• Rests
• Transposition
• Keys and accidentals
• Tempo
• Percussion
• Cue notes, cf. also dedicated chapter
• Formatting the code
• Direct code manipulation, cf. also dedicated chapter
• External text file, cf. also dedicated chapter
• Abc2xml conversion, cf. dedicated chapter
• Plugin, cf. also dedicated chapter
• Settings

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.

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

• any notes, rests, or accidentals, except for grace notes, explicit overlay passages, and “direct code manipulation” as described above,
• any bar lines or repeat signs by other means than /&B,
• any fields of administrative types such as L:, M:, K:, V:, T:, w:,

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:

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:

• Any syllable consisting of a single underscore or hyphen (in other words equal to “_” or “-”) will be treated as a melisma.
• Trailing hyphens will be passed to abc unchanged (i.e. without added escape mark), since this probably reflects the author's intentions.
• As a compromise, backslashes will also go unescaped, so you can use them for character escapes (but not for any other purpose).

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 abc “cue=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 you are a Windows user, download abc2xml.exe and put it into the same directory as MidiZyx2abc.jar;
• Alternatively, or if you use a different operating system, make sure to have Python installed with the checkbox "Add to PATH" selected. (If you forgot to select that box, best is reinstall Python using the "repair" option.) Download and unpack the abc2xml Python script package) and put the resulting two files abc2xml.py and pyparsing.py into the same directory as MidiZyx2abc.jar.

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.

Appendix 2: Some common transposing instruments

with their MidiZyx2abc transposition marks.

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:

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