It is assumed that the you are already familiar with EasyAbc and the Abc music notation. This guide introduces the new features in version 1.3.6.
EasyAbc is an open source program created by Nils Liberg. His last release was version 1.3.5 in the middle of 2012. Nils had stopped further development and as a result further support has been taken over by other Python programmers and myself. Later versions of the program can be be found on sourceforge.net.
EasyAbc acts as a graphical user interface to a suite of command driven programs such as abcm2ps and abcMIDI. Minor improvements to these programs have introduced small incompatibilities with EasyAbc making it necessary to update EasyAbc. Furthermore minor bugs were discovered as the program was used by a larger population. Newer versions of this program addressed these issues and also made further changes that would extend its capabilities as well as make it easier to support.
We wanted to make the operation of EasyAbc more transparent so that the user would be able to identify and isolate problems. For example, in some cases problems was caused by a bug in an external program such as abc2midi rather than EasyAbc.
When new features were introduced, it was desirable that the normal use of the program remained the same. However, there were a few changes such as the operation of the Abc Settings menu and the reporting of errors that are different in later versions.
Errors and warning messages are no longer appearing in pop up windows. Instead there is a short note in the status bar indicating whether the program ran normally or not. If the output does not look right, the user can check for warning and error messages and determine what is happening by going to the Internals menu item.
The Abc Setting menu item has changed significantly. It is no longer a dialog box which can cascade into other dialog boxes and lock up the program until user clicks OK or Cancel. The Abc Settings has been replaced with a tabbed book with separate pages which control how the external programs abcmp2s and abc2midi operate.
Another tool called 'Search directories' was added. A progress bar has been introduced when certain batch operations are started. The user can see a the progress and can abort this process.
The next few sections describe these changes in detail.
The Internals menu allows one to follow the operations of EasyAbc when a certain function is called. There are three submenu items. EasyAbc relies on 3rd party programs to convert the selected tune to another form where it can be displayed or played. If the tune is not displayed or played correctly, it may be useful to check the messages returned by the external program. In another instance, when you are processing a whole collection of tunes, a log of all the error messages will reduce the time for verifying the output files.
Two of the important programs that perform these conversions are abcm2ps and abc2midi. Abcm2ps converts the selected tune to a svg (scaleable vector graphics) file called temp0.svg which is put in your cache folder. EasyAbc reads this file and displays the file in the musical score pane. Abc2midi converts the selected tune to a midi file called temp.mid and calls another program to play this midi file. Both of these programs send acknowledgements when they are executed and report any problems with the input file.
There are three sub-menu items in the Internals menu. Messages shows the communications between EasyAbc and the external program. Input processed tune shows the tune that it is sent to the external program. The processed tune will likely contain additional commands that tell the program how to convert it. For example if the tune is sent to abc2midi, there may be commands indicating which musical instruments to be assigned to the voices. Show settings status shows all the state variables in EasyAbc which are loaded when the program is started and may be modified by the user in the Abc Settings.
If you click Internals/Messages a window labeled Messages will appear on your screen. It may contain the following text.
AbcToSvg /home/seymour/abc/abcm2ps - -O temp.svg -v -A abcm2ps-8.5.2 (January 28, 2015) File stdin stdin:29:15: warning: Line underfull (395pt of 778pt) Output written on temp001.svg (86970 bytes)
abcm2ps merely returns the message:
stdin:29:15: warning: Line underfull (395pt of 778pt) Output written on temp001.svg (86970 bytes)
In this case the warning message is not very significant and implies that the formating of the music may not be perfect.
If now, you play the selected tune, the following text would be appended to the Messages box.
AbcToMidi /home/seymour/easyabc_source_code_1.3.6.1/bin/abc2midi - -o /home/seymour/.EasyABC/cache/temp.midi -BF writing MIDI file /home/seymour/.EasyABC/cache/temp.midi
The function AbcToMidi gets the selected tune and adds inserts %%MIDI commands that will instruct abc2midi how to create the midi file. The executable abc2midi is run creating a midi file called temp.midi in the cache folder. The parameter -BF turns on the Barfly stress model.
In this case, abc2midi did not return any warnings or error messages and the status bar is clear.
This window shows the actual data that was submitted to the external program. Furthermore the line are numbered so you can relate the warnings or error messages in the Message box with the input tune. The input tune will contain some extra lines that were not in your transcription. For example if you just selected and new tune and a new music score was displayed, the following lines may be inserted at the beginning.
1 %%leftmargin 0.5cm 2 %%rightmargin 0.5cm 3 %%botmargin 0cm 4 %%topmargin 0cmThese are additional parameters passed to abcm2ps so it produces a svg file suitable for rendering on the Musical Score. If you now played the tune, the processed input tune window will now contain something similar to the following.
1 X: 1 2 %%MIDI program 1 0 3 %%MIDI program 2 0 4 %%MIDI program 3 0 ... 16 %%MIDI program 15 0 17 %%MIDI program 16 0 18 %%MIDI control 7 96 19 %%MIDI control 10 64 20 %%MIDI program 0 etc.All the command beginning with %%MIDI tell abc2midi to add specific information to the output midi file. In order that the midi player on the Mac handles the midi file correctly, it was necessary to assign instruments to all the 16 midi channels independently on whether they are used.
The actual messages inserted in the processed tune will also depend upon the Abc Settings. This will be discussed in another section.
There is no option to save the contents of these windows to a file, but you can do the following. You could grab the contents of the processed window using ctrl-A and ctrl-C key combinations and then paste them into an abc text file using the ctrl-V combination.
The Abc Settings is an advanced feature and in most situations it can be ignored by the novice user. Furthermore, the misuse of these settings can leave EasyAbc and all its earlier versions in a nonoperable state. If this ever happens, the 'Cold restart' button in the Settings menu item if restore EasyAbc to its initial settings. On the other hand the Abc Settings opens the door to many of the options available in the external programs like abc2midi and abcm2ps. In order to allow room for expansion the Abc Settings has been changed from a dialog box to a tabbed notebook. It is no longer necessary to click on 'OK' in order for a change to become active. For many of the controls in the Abc Settings, some helpful information may popup when the mouse pointer is hoverving over one of the buttons or entry boxes.
The main advance is that the Abc Settings has grown considerably that it is now organized in a tabbed notebook. Presently, there are 5 tabs.
These settings are vital to the proper operation of EasyAbc. On both Windows and the Mac, EasyAbc comes with the helper programs which are placed in a bin folder. When EasyAbc is started for the first time, it establishes links to these programs and normally the user does not need to modify the links to these executables. For other operating systems such as Linux, the user is expected to establish these links and in the File Settings page. Each time EasyAbc is restarted, it check that these links are still valid and reports any problems. Unlike version 1.3.5 the default settings are no longer hidden.
Note all versions of EasyAbc share the same settings file settings1.3.dat which implies that if you have recently upgraded to a newer version of EasyAbc, you may wish or need to change the links to the abcm2ps and abc2midi to the latest version which comes with the latest version of EasyAbc. If you are running Windows and staying withen the 1.3.6 series, this may not be necessary.
There are several ways of changing the settings. You can click on the cold start button on the Settings menue, which will restore all the settings to their default value. If you wish to change only a select number of path settings, you can do this with the restore settings button at the bottom. Alternatively, you can enter the path names directly in the entry box or use the browse button to find the executable and set the appropriate path.
Here are a few minor comments. On Windows and Linux you use ghostscript for converting a PostScript file to a PDF file. On the Mac, the program is called ps2pdf. Nwc2xml is applicable if you use NoteWorthy composer to create music files which is a commercial product. On Windows and the Mac it is not necessary to specify a Midiplayer unless the default one is unsatisfactory.
The button called 'Restore settings' can also be used for restoring the default path to particular executables. Just erase the existing path and then click the 'Restore settings' button.
The settings under Abcm2ps control are somewhat experimental as the default settings are definitely sufficient. If the EasyAbc defaults box is checked then the music score should be displayed in the in a familiar manner. If your tune has its own abcm2ps layout commands embedded, you may wish to check the box 'No page settings'. If neither the 'No page settings' and 'EasyAbc defaults' are checked additional page settings will appear below. You can see the default or suggested values of these page settings by hovering the mouse pointer over the particular box. All the values must be in centimeter units. Do not include the units cm, in, pt or whatever when you enter the values in the box.
All of these settings are turned into abcm2ps commands which are added in the processed abc file with a preceding %% sign. You can view these added commands by looking at the Internals/processed file output.
If you check 'Include bar numbers', then the bars will be numbered in the displayed score. This may be useful for interpreting warning messages returned by abc2midi when you play a particular tune. Note abc2midi counts the bars from zero. If you check, 'Add X reference number', the reference number of the Abc tune will appear with the title in the musical score. If your tune has lyrics and the box 'Suppress Lyrics' is checked, the lyrics will not appear in your score. Abcm2ps attempts to layout the lines of music based on the particular bars in a text line. If you check, 'Ignore line ends', abcm2ps will disregard how you layed them out and just place as many bars that it can fit on system.
Normally, you would not need to use the buttons marked 'Change abcm2ps path' and 'Restore abcm2ps path'. They were introduced to please a particular user who likes to try out different versions of abcm2ps. The developer of abcm2ps, Jef Moine, comes out with new versions of the program fairly frequently which contain new features and repair old bugs. Those two buttons affect the settings that appear in the 'File Settings' tab and are placed here mainly as a convenience. Abcm2ps has many optional run time parameters which are listed when you run abcm2ps in a command window. For example here are the first few lines.
/home/seymour/abc$ abcm2ps
abcm2ps-8.5.2 (January 28, 2015)
ABC to Postscript translator.
Usage: abcm2ps [options] file [file_options] ..
where:
file input ABC file, or '-'
options and file_options:
.output file options:
-E produce EPSF output, one tune per file
-g produce SVG output, one tune per file
-v produce SVG output, one page per file
-X produce SVG output in one XHTML file
-z produce SVG output from embedded ABC
-O fff set outfile name to fff
-O = make outfile name from infile/title
-i indicate where are the errors
-k kk size of the PS output buffer in Kibytes
If you wish to include these run time parameters when abcm2ps is run you would put them in the text entry box marked 'Extra Parameters'. You can verify that these parameters are passed using the 'Internals/Messages' in the top menu of EasyAbc. This is an advanced feature and it is assumed that you know what you are doing.
In some situations, you may also need to pass a format file to abcm2ps. For example, in displaying Turkish makam files which use special symbols for particular microtones, abcm2ps requires an additional format file called commaA-E.fmt which comes with the music collection. You would place the name of the format file in the appropriate entry box and be sure EasyAbc knows where to find it.
The MIDI file corresponding to a plain abc file (without %%MIDI indications) will play the tune on the 'Acoustic Piano' which is the default instrument. Most abc files available on the internet do not specify any MIDI instruments or tempo, so it is desirable to give the user some control on how the music is played without having to modify the original file.
When you play a specific tune, EasyAbc inserts numerous %%MIDI commands prior to converting the tune into a MIDI file. The sequence begins with 16 %%MIDI program commands specifying the instruments to all 16 midi channels whether they are used or not. This was necessary to fix a problem with one of the MIDI players. The next set of %%MIDI commands support the bass/gchord accompaniment associated with the guitar chords. All of these MIDI commands are placed at the beginning of the tune, so if the abc notated tune as %%MIDI commands appearing in the body of the tune (after the first K: declaration), they will override these settings.
The Abc2midi settings page allows you to change the assignment of musical instruments to the melody, chord and bass accompaniment. You can transpose the output to another key without changing the tune using the transposition slider. This is useful if you play a musical instrument such as a Bb clarinet which automatically transposes the music down by a tone. You can modify the tuning away from A 440 Hz up to semitone in either direction. (Some old musical instruments like the accordion are not tuned to this standard.)
Older versions of EasyAbc alway applied the Phil Taylor's Barfly stress model to the tune when it contains a rhythm designator (eg R: jig) recognized by the program. The newer version allows you to switch the Barfly stress model on or off (assuming the tune has a proper rhythm designator).
This controls the assignments of the 16 Midi channels to the different instruments. Note that channel 10 is usually assigned to percussion instruments independent of what you do.
The user may find that the above instrument assignments does not always work as expected. Note that this applies to the MIDI channel and not the voice number in the abc file. This can be a source of confusion. The user does not commonly or need to specify the channel assigned to a voice. In this case abc2midi does the channel assignment automatically and unfortunately, the channel numbers may not match the voice numbers. For example if a voice has guitar chords, two additional channels are automatically assigned to handle the chords. Furthermore, the program (MIDI instrument) assignments in the Abc2midi page has priority over the voice assignments. If the given abc tune already has %%MIDI indications, they will also have priority. The issue is rather complicated and I have not figured out a transparent solution. For a multivoiced tune, it may help if the user also specifies the channel number with each initial V: declaration.
I have add little experience with Music XML files which is now a music notation standard shared by a lot of music notation software. The options listed on that page can be considered experimental. For your information, the free program musescore allows your to read/display/play and create Music XML files.