Flabc - Installation, Configuration and Usage
Contents
- 1 Installation
- MacOS X
- Windows
- Linux
- Compiling from Source
- 2 Usage
- Opening Files and Typing abc
- File Encoding
- Previewing and Listening to abc Files
- Setting Format Options and Midi Instruments
- Keyboard Shortcuts
- 3 Configuration
- Where the Configuration is stored
- Look and Feel
- External Helper Programs
- Using abcm2ps instead of abctab2ps
- Printing from gv on MacOS X
- 4 Known Bugs and Limitations
- All Platforms
- MacOS X
- Windows
- Linux
1 Installation
MacOS X
For MacOS X flabc is distributed as an application bundle. To install it simply unpack it by double clicking on the zip archive and move it in some application directory (e.g. /Applications or $HOME/Applications). Then you can open files by dropping them on the application bundle or from the command line with open -a flabc ....
If you want to associate the file extension abc with flabc, do so from the context information menu of an abc file.
The application bundle includes a copy of abctab2ps and abc2midi so that you do not need to install these programs separately. For viewing the postscript output form abctab2ps however, you will need a postscript viewer and set it in the postscript configuration (menu "Options/System Environment", see below).
The default configuration works out of the box with ghostscript from Homebrew. To install ghostscript, do the following:
- install Homebrew
- open Terminal.app and enter the command brew install ghostscript
Windows
For Windows flabc is distributed as an installer built with Inno Setup. Running the installer will install flabc and associate it with the abc file extension. Thus you can open abc files in flabc simply by double clicking on them in the Explorer.
The program includes a copy of abctab2ps and abc2midi so that you do not need to install these programs separately. For viewing the postscript output form abctab2ps however, you will need a postscript viewer that is associated with the ps file extension, e.g. gsview32. Note that you must install two packages: ghostscript and ghostview from http://www.cs.wisc.edu/~ghost/gsview/.
Linux
For Linux flabc is distributed as a RPM or DEB file which does not include abctab2ps or abc2midi so that you need to install them separately.
Due to the lack of universal file type associations on Linux (like the HKEY_CLASSES_ROOT registry branch on Windows or the LaunchServices database on MacOS X) you will need to explicitly set your postscript viewer, midi player and web browser under "Options/System Environment", see below.
Compiling from Source
In order to compile flabc from the sources, you need an ANSI C++ compiler with STL support. Moreover you need at least FLTK 1.3.x from www.fltk.org. For MacOS X you should use the svn version of FLTK because in FLTK 1.3.3 interaction with the clipboard
(copy & paste) leads to crashes on MacOS X.
The provided Makefile assumes that you are using some version of the GNU C compiler gcc.
To install flabc from the source code package, do the following:
- unpack the TGZ-archive eg. with tar xzf
- change to the subdirectory src
- to compile the source code, type make on Linux, make osxapp on MacOS X or make winapp on Windows
- to install flabc into /usr/local type make install as root on Linux
The source package does not include abctab2ps or abc2midi which you will need to install separately.
2 Usage
Opening Files and Typing abc
On Linux you can open an abc file with flabc file.abc. For Windows or MacOS X see the platform specific installation instructions.
Flabc is not a graphical note drawing editor. You will need to type the music as ASCII text in the abc file format. A detailed description of this file format can be found under "Help/Abctab2ps User's Guide".
File Encoding
Whilst abctab2ps requires the abc file to be in latin1 encoding, abcm2ps (at least since 2014) requires it to be in utf8 encoding. flabc solves this problem as follows:
- If the first line starts with %!abcm2ps, the file is stored in utf encoding.
- If the default program is set to abcm2ps in "Options/Behaviour", the file is stored in utf8 encoding, unless the first line starts with %!abctab2ps.
- In all other cases, the file is stored in latin1 encoding.
Previewing and Listening to abc Files
You can preview your music or listen to it with the respective menu items in the "Abc" submenu. If any of these does not work, there is most likely a problem in your configuration of external helper programs or you do not have installed a postscript viewer like ghostview.
When abctab2ps or abc2midi report an error while processing your abc code, a box with the error messages will appear. With the button "Goto next error" you can directly jump to the offending abc code in flabc.
Setting Format Options and Midi Instruments
As it is hard to remember all format options, flabc offers a convenient way for browsing options and setting them. Choose the menu "Abc/List Format Parameters", click on the desired options and press the button "Copy to Clipboard". Then you can paste (e.g. with Ctrl/Apple-V) the options into the editor.
The same works for selecting Midi instruments for abc2midi. If your file contains more than one voice, make sure that you set the instrument for all voices.
Keyboard Shortcuts
Flabc supports the usual CUA shortcuts, i.e. Ctrl/Apple-C for copy, Ctrl/Apple-X for cut, Ctrl/Apple-V for paste and Ctrl/Apple-Z for undo. Moreover you can access the main menu with Alt (Linux, Windows) or Ctrl + Alt (MacOS X) and the underlined letter.
This means that the resulting keyboard shortcut for e.g. "Abc/Preview Tune" is Alt-A-T on Linux and Windows and Ctrl-Alt-A-T on MacOS X. Moreover most popup windows can be closed with Esc.
3 Configuration
Where the Configuration is Stored
To store the configuration you must select the menu item "Options/Save Options". The configuration is stored in files under a directory that will be reported during saving (the actual location depends on the operating system and the user account). If you need to get rid of your configuration you can remove this directory.
Look and Feel
Colors and fonts of the editor can be customized via "Options/Look and Feel". For changing a color, do a single click on the color box; this will popup a color chooser. Moreover you can make the abc markup signs '^' and '~' no dead key characters on MacOS X.
You need to press the "Apply" button for making your settings visible in the current session. In order to make your current settings permanent, select the menu item "Options/Save Options".
External Helper Programs
For a number of operations (e.g. previewing an abc file) flabc relies on external programs which must be properly configured in order to be callable. As the MacOS X and Windows distribution come bundled with abctab2ps and abc2midi there is less to configure than on Linux, but some configuration may still be necessary, depending on your system environment.
The external helper applications can be configured via "Options/System Environment", where all options are documented in detail. You must press the "Apply" button to apply your changes for the current session. In order to make your current settings permanent, select the menu item "Options/Save Options". If you have totally messed up your configuration press the "Reset" button which will restore all default options.
Here are some hints for typical configuration problems:
- On MacOS X the only option that needs to be configured is the postscript viewer. If your postscript viewer is an X11 application (as for instance gv or ghostview), call it with open-xapp, e.g. "open-xapp gv". open-xapp is a script bundled with flabc that automatically launches X11 if it is not yet running and assigns the correct DISPLAY to the called X11 application.
- You can check whether abctab2ps and abc2midi are found with "Help/About flabc".
- On Linux you will also need to set your web browser for viewing the documentation. This can be tricky if your browser supports session management only via arcane command line options. If you are using KDE, konqueror is a good choice. mozilla or firefox should also work.
- When you are using Media Player on Windows as your default application for opening Midi files, you must additionally enable the Midi format in the settings of Media Player (this seems to be disabled by default).
Using abcm2ps instead of abctab2ps
It is possible to use abcm2ps for postscript conversion instead of abctab2ps, provided abcm2ps is installed on your system. On Windows it is recommended to copy the abcm2ps executable into the bin subdirectory of your flabc installation; then it is guaranteed that flabc will find abcm2ps. The "Help/About flabc" dialog will show whether abcm2ps is found.
To use abcm2ps instead of abctab2ps simply check this option under "Options/Behaviour". Independant of the chosen default program you can set the conversion program for individual files by starting them with the magic characters %!abctab2ps or %!abcm2ps. If you do not want this, there is even an option to suppress the recognition of the %! magic; when unchecked, the default program is always used, regardless of the %! directive.
Printing from gv on MacOS X
If you are using gv (eg. from Fink) as postscript viewer on OSX and cannot print from it, set the printer command under "State/Setup Options" to the following command:
ps2pdf '%s' - | lpr -o media=A4
4 Bugs
All Platforms
- Inactive menu items are not yet implemented
- Midi conversion ("Abc/Listen Tune") only works with music but not tablature
- As Midi and Postscript conversions are done with different programs, some abc dialect incompatibilities can occur
- abc2midi does not report the column of an error
MacOS X
- When windows are closed their memory is not freed before the last window or the entire application is closed
- When several windows are open a change in the configuration settings only applies to the current window
- If you compile flabc from the sources with FLTK 1.3.3, there will be crashes when copying to or pasting from the clipboard. To fix this use the SVN version of FLTK.
Windows
- flabc has only been tested on Windows 7.
- regular expression search is not supported on Windows
Linux
- when there is an error invocating the web browser, postscript viewer or midi player, no error is reported
Last changed 2019-12-27