Mer's 'Net Tab Converter Users' Guide

Project Home Page | Project Summary Page

Overview

Mer's 'Net Tab Converter is a tool that renders text-formatted guitar and bass tablature (as is found all over the internet) as standard sheet music.

Internet guitar tablature often looks something like this:

+--5--------|--5-----5--|--3--------|--3--------|--3--------|--3-----3--+
+------3----|--3---3----|----0---0--|----0---0--|----0---0--|----0------+
+----4---4--|----4------|------5----|--5---5----|------5----|--5---5----+
+--0--------|--------0--|--0--------|-----------|--0--------|--------0--+
+-----------|-----------|-----------|-----------|-----------|-----------+
+-----------|-----------|-----------|-----------|-----------|-----------+

It describes the fingerings to use to play the music on a guitar, or any instrument with the same number of strings and the same tuning.  There is rarely any representation of rhythm or key signature or any of the other more complex issues of musical notation, but if you already know what the music should sound like, and how the rhythm and phrasing works, then it functions as a useful tool for learning to play the music on a guitar.

However, if you want to learn to play the music on  an instrument other than guitar, you would have to figure out each note one at a time by looking at a guitar and figuring out which notes the tab indicates to play.  For example, with the tablature above, the first chord is 5th fret on the high E string and the open D string.  The open D string is easy: it's a D.  The 5th fret on the high E string takes more calculation: each fret is one half step up, so the 5th fret is 5 half steps above the open E string, which is an A.  If you want to manually transpose the guitar tablature to music that is understandable for any other instrument, you must continue this process for every single note represented by the tab, which is a very time consuming process.

Mer's 'Net Tab Converter does all of this for you by automating the process of calculating half steps up from the open string for you and showing the results in a familiar format very much like regular sheet music, with dots on a staff, like this:
 
The staff above is a treble clef staff though it is not notated that way because the program does not yet support inserting clef images in the staff (but it will in a future version).  As with the original tablature, you need prior knowledge of the rhythm and what the music sounds like to make use of this style of notation.

Guitar tablature can be found at many web sites throughout the internet, in particular http://www.olga.net is an excellent resource.  To use Mer's 'Net Tab Converter, just find any tablature on the internet (or write it yourself - whatever you want) and save it to your local hard drive or a disk.  Run Mer's 'Net Tab Converter and select the tab file that you saved (and other options explained below) and it will create an HTML file containing sheet music like the example above.  You must use a web browser (like the one you are using now) to view the output sheet music files.

The Main Dialog

Source Tablature
Everything in this section describes information about the input to the program.

Lyrics and Instructions
Often the tablature will have a few lines before and/or after the actual tablature containing lyrics and/or instructions (such as first ending, second ending, repeat 2x, and things like that).  If you want this text to line up with the notes in the sheet music, you must select the number of lines of text before and after the lines of tablature.  "Lines above" is the number of lines preceding the tab text and "Lines below" is the number of lines following the text.  This is just used for beautifying the sheet music that is produced.  Often, your best clue to the rhythm is the way in which the lyrics line up with the numbers in the tablature.  Consider the following example from the Beatle's "Here Comes the Sun"

D     Dsus2 D              Dsus2   D   G    Gmaj7 G6  Gmaj7 E7
 Here comes the sun    doo doo doo doo       Here comes the sun
|--2--0-----2-------|----2------0--2------|----2--0-----2---------|
|---------------3---|-------3----------0--|-----------------3-----|
|-------------------|---------------------|-----------------------|
|-------------------|---------------------|-----------------------|
|-------------------|---------------------|-----------------------|
|-------------------|---------------------|-----------------------|

If you want the lyrics to line up with the generated sheet music, then you must select at least 1 line above.  If you also want the chord markings to line up with the music, then select 2 lines above.

Strings
The first drop-down list is for the number of strings represented in the tablature.  Most tab is for 6-string guitar, but some is for bass which only has 4 strings.  If you want to convert bass tab, select 4 for the number of strings.  The following 6 boxes indicate the note values of the open strings from highest to lowest in units of half steps from middle C.  Positive numbers represent half steps above middle C and negative numbers represent half steps below middle C.  0 is middle C.  There are note letter labels underneath the number boxes to confirm that you have counted the half steps correctly.  Most tab uses the standard guitar tuning of E B G D A E, but some tab uses alternate guitar tunings such as drop-D, open-D, or other slide-guitar or custom tunings.  The tuning style is usually explained in the text preceding the tablature but there is no way for Mer's 'Net Tab Converter to determine the tuning style for itself, which is why you must enter it in these boxes.

Output Sheet Music
This section describes the format of the sheet music to create.

Prompt for each destination file
If this box is checked, each time you open a file to convert to sheet music, the program will ask you where you want to save the output file (using a standard Save As... dialog box).  If the box is unchecked, then all output files will be saved to the file name using the format specified in the text box that follows the check box.  You can use a "%s" in the format to indicate the original file name.  This is better explained through examples:

If you have specified for format "%s SHEET MUSIC.html" and you select the input file called "C:\My Documents\Tab\Beatles - Here Comes the Sun.txt" then the output file name will be "C:\My Documents\Tab\Beatles - Here Comes the Sun SHEET MUSIC.html"

If you specify the format "C:\My Documents\Sheet Music\%s.html" and you select the input file called "C:\My Documents\Tab\Beatles - Here Comes the Sun.txt" then the output file name will be "C:\My Documents\Sheet Music\Beatles - Here Comes the Sun.html"

If you specify a format without a %s, like "C:\temp.html" then for any input file you select, the converted sheet music output file will be saved to the file "C:\temp.html"

Output Config File
This lets you select the output configuration file used by Mer's 'Net Tab Converter to format the output of the HTML sheet music files that it creates.  The format of this configuration file is explained below.  It is suggested not to change the contents of the configuration file nor the selection of the configuration file unless you have a very good understanding of the HTML language.

Auto-transpose by ___ half steps
The number here specifies the number of half steps to shift all of the notes.  Most of the time this should be zero.  This is useful for creating sheet music that is natively understandable for non-C instruments such as Bb trumpets.  For a Bb trumpet you would specify 2 in this box to shift all of the music up 2 half steps from Bb to C (since a C on the trumpet is a Bb on a guitar, so you want the Bb on guitar to be represented as a C in the trumpet music, which means all notes should be transposed up 2 half steps).  This is also useful if you want to transpose the music to another key just for the fun of it.

Clef
This specifies the clef to use when displaying the output music.  In the current version an image is not displayed to indicate what clef was used, so it is advisable to print the generated sheet music and draw the clef on yourself while you remember what range the music was in.  For all intents and purposes, all this really chooses at this point is the notes represented by the 5 staff lines drawn in the sheet music.  Selecting a different clef simply shifts the position of the dots.

Key
This allows you to select a key signature for the output sheet music.  This is currently not supported.

Accidentals Use
This allows you to specify whether you prefer in-between notes such as G# to be displayed as a G# or as Ab.  Currently, only sharps are supported.

Include Original Tab Text
If this box is checked, then the original text of the tablature is included in the output sheet music.  Each set of tab lines is shown above the converted sheet music that it became.  If unchecked, the output sheet music does not include any of the original tablature text.

Automatically Open Output File When Done
If this box is checked, then each file created by Mer's 'Net Tab Converter will be automatically opened in your default web browser.

Convert Tab File
This button will prompt you to open the tablature file that you want to convert.  Then if "prompt for each output file" is checked it will also ask you where to save the output file.  Then it will open a dialog box with a progress meter on it to indicate progress in converting the data. When done, it will optionally open the output file.

Menus
The menus describe some default input and output formats.  Selecting items from the Input Schemes or Output Schemes menus will only change settings in the main dialog to defaults for those schemes.  Beyond that it should be self explanatory.

Tablature File Specifications

This section describes the valid input and text strings and constructs recognized by Mer's 'Net Tab Converter when it parses an input tab file to generate sheet music.

All tab files consist of interspersed blocks of comment text and tablature staffs.  All comment text is preserved and shown in its original form in the HTML sheet music output file.  All complete tablature staffs are converted to graphical sheet music and optionally displayed with the original text or only in the converted graphical format (see the "Include Original Tab Text" option on the main dialog).

Everything that is not determined to be part of a complete tablature staff is considered comment text.

Each tablature staff consists of:

• zero to X lines of text (lyrics and instructions) where X is specified by "lines above" in the main dialog, followed by
• exactly Y string lines, where Y is specified by the number of strings selected in the main dialog, followed by
• zero to Z lines of text (lyrics and instructions) where X is specified by "lines below" in the main dialog.

Each string line must contain at least 5 hyphens (-) and otherwise may contain any kind of text and numbers.  If there are 5 or more hyphens on a line, but the line contains any tabs, or if it contains spaces that are not immediately surrounded by hyphens or numbers, then that line is thrown out and treated as comment text.  Consider the following two examples of a valid string line vs. an invalid string line.

Valid string line:
+------- 15 ------|--------- - - - - -------+

Invalid string line:
+--- some text ----15----|---------+

The excessive text in the invalid line is what makes it invalid and causes it to be treated as comment text.

If one or more string lines are detected in a row, but not enough to equal the number of strings specified in the main dialog before encountering a line of comment text, then the whole block of text is thrown out and considered comment text because the tablature staff is incomplete.  For example, many tab files contain a block of text at the top describing wrote the music and who transcribed it into guitar tab.  Such a block of text might look like this:

#----------------------------------PLEASE NOTE---------------------------------#
#This file is the author's own work and represents their interpretation of the #
#song. You may only use this file for private study, scholarship, or research. #
#------------------------------------------------------------------------------#

The first and last line of the block may temporarily be detected as possible string lines, but the text in between causes the potential tablature staffs to be incomplete and treated as comment text.

More Specifics on Advanced Tab File Syntax

The specifics of the text-formatted guitar tablature formats used on the internet vary tremendously by author and by song.  Tablature is a limited form of musical representation compared to all the things that can be represented in modern sheet music, so text-formatted tablature authors tend to use a variety of techniques to represent rhythm, bar lines, repeat signs, and other more complex things about how a piece of music should be played beyond just what notes to play and in what order to play them.

These more complex items vary in the way they are represented, but share some things in common. Mer's 'Net Tab Converter does its best to interpret these complex items in general purpose ways so that the graphical sheet music that it produces is as useful as possible.  Below I describe the rules for how the program detects and interprets the more complex items and textual constructs that are often used in internet-located, text-formatted guitar and bass tablature.

The examples used below are intended to be simplified examples of specific and limited uses of these complex items in order to better exemplify the methods and rules used to analyze these things.  The type of things that you find in practice when using Mer's 'Net Tab Converter on the wide variety of tab that is found on the internet is going to stretch these rules in odd ways in attempts to represent a number of musical expressions as limitless as music itself.  The computer does its best to figure out what the tab author means, but no computer will ever be as successful at understanding music as the Human Mind.

Primarily, the tab file parser detects the numbers along the string lines and calculates their note values based on the number of half steps above the note value of the open string on which the number was found, as described in the overview at the beginning of the Users' Guide.  Additionally, the tab parser finds the following items:

• Indentation levels: The number of text columns that each detected item (numbers and other things in this list) is indented on its line, and renders the graphical note's dot (or other item for non-number items) at the same indentation/text column position as the original item.  This is critical because the only representation of rhythm is the spacing of the numbers and the alignment of the lyric and instruction text with those numbers, as well as the vertical alignment of the other text and items found on a text-formatted tablature staff.
   
• Bar lines: If there is any text character that appears at the same column position on all of the string lines in the tablature staff, then that is considered to be a bar line.  Bar lines are often represented using the | or + characters, as in the examples above, but they may also be represented with any character such as *, l, b, #, @, or anything.  There are only three types of characters which can not count as part of a bar line: spaces, hyphens (-), and numbers (0-9).
  
  Here are some examples of valid bar lines:

  |-------------+------------*------------A
  |-------------+------------*------------A
  |-------------+------------*------------A
  |-------------+------------*------------A
  |-------------+------------*------------A
  |-------------+------------*------------A

  Here are some examples of invalid bar lines.  Invalid bar lines are simply ignored, or treated as decorating text (see below) but will not cause the entire tablature staff to be thrown out as comment text.  The first bar is discounted because the | is missing from at least one line.  The second one is discounted because the characters used are not the same on every line

  |-------------+
  |-------------*
  |-------------+
  --------------*
  |-------------+
  |-------------*
  

• Repeat Signs: If a bar line is detected in the tablature staff (as described above), and that bar line is followed or preceded by the same character on each of the middle two lines of the tablature staff, then that bar line is considered to be a repeat sign as well as a bar line.
  
  Following is an example of a 6-string tablature staff with matching repeat signs on both ends.  Note that the * and + used could also be anything (other than a number, hyphen, or space) as long as it is the same character on both lines.

  |----------------------------|
  |----------------------------|
  |*--------------------------+|
  |*--------------------------+|
  |----------------------------|
  |----------------------------|

  Following are some examples of invalid repeat signs.  The characters used to denote these invalid repeat signs will simply be ignored and will not cause the tablature staff to be treated as comment text.
  
  The first invalid repeat sign is invalid because the *s are separated from the bar line by an extra column.
  
  The second repeat sign is invalid because there is only one character.
  
  The third repeat sign is invalid because the *s appear on lines other than the two middle lines.
  
  The fourth repeat sign is invalid because the two characters are different.

  |-------------|------------|------------|
  |-------------|-----------*|------------|
  |-*-----------|$-----------|-----------%|
  |-*-----------|------------|-----------@|
  |-------------|-----------*|------------|
  |-------------|------------|------------|

• Decorating text: If a number is immediately surrounded by any text on either side that is not a hyphen or space, then that text will be displayed next to the sheet music dot for that note.  Often tablature authors will use decorating text to indicate special methods of playing the note.  Specifically on guitar, some common indications are h for a hammer-on, or p for a pull-off, or / or \ to indicate to slide up to or away from the note when playing it.  Sometimes a number will be placed in parentheses to indicate that it is optional, or possibly a grace note, or played only by the second guitar part, or perhaps something else.  Understanding what the decorating text means involves reading the comment text in the tab file as well as having a prior knowledge of the way the music is supposed to sound.
  
  Here is an example of some decorating text.  In this case, it is probably saying the play the 5th fret on the 3rd string (which is a C) then to hammer-on and pull-off of the 7th fret (which is a D) and then back on the 5th fret (C) and then to slide up to the 9th fret (which is an E).  In this case, the dot for the D would be displayed on the sheet music staff surrounded by the h and p, and the E would be displayed on the sheet music staff preceded by a /, just as it is written in the tablature.

  |---------------|
  |---------------|
  |---5-h7p-5--/9-|
  |---------------|
  |---------------|
  |---------------|

  Decorating text takes precedence over bar lines and repeat signs.  In the following example: the first E Major chord is displayed with ( and ) around each dot for each note; the second E Major chord is displayed with a | following each dot for each note; the third E Major chord is displayed with a bar line following it; and the last E Major chord has more complex behavior.  While it is obvious to a human being that the end of this tab staff indicates to play an E Major and then repeat, the tab parser will treat each of the "*| " strings as decorating text for the G# (1st fret/3rd string) and the E (2nd fret/4th string) and ignore the rest of the bar line as incomplete.

  |--(0)-------0|----------0-|----------0-|
  |--(0)-------0|----------0-|----------0-|
  |--(1)-------1|----------1-|----------1*|
  |--(2)-------2|----------2-|----------2*|
  |--(2)-------2|----------2-|----------2-|
  |--(0)-------0|----------0-|----------0-|

  Decorating text may not be separated from the number that it decorates, or it will be ignored.  For example, the following notation might indicate to strum the E Major chord slowly, but since there is at least one column separating the / and \ characters from the numbers, the tab parser will ignore them.

  |----\-0---|
  |----/-0---|
  |----\-1---|
  |----/-2---|
  |----\-2---|
  |----/-0---|

  Any ignored text is simply ignored. It is not displayed anywhere in the graphical sheet music and it does not cause the tablature staff to be treated as comment text.
   
• HTML Tags: In many cases, tablature files used as input for Mer's 'Net Tab Converter are saved to the user's hard drive directly from web sites on the internet.  For this reason, the files are likely to contain HTML tags describing hyperlinks, images, text formatting rules, and a wide variety of other things.  For the most part, the tab parser treats these HTML tags as comment text, as it would any other text that it encounters outside of a tablature staff.  However, there are some special features and some special problems surrounding HTML tags in tab files.
  
  The generated output file may contain the original files HTML header block as defined using the <HEAD> and </HEAD> tags and as specified in the output configuration file NetTabConverter.ini, which will affect the base path to images and links as well as a few other things
  
  The output file will also contain the same <BODY> tag attributes as in the original file, which may define the background color or background image, the title of the web page, and several other things.  Like with the <HEAD> portion of the HTML code, the <BODY> code may be controlled through the output configuration file as well.
  
  There may be some occasional bad uses of HTML in tab files, for instance the <PRE> tag.  For text-formatted tablature to be readable by the human eye, it must be displayed using a mono-spaced font (a font in which all letters, spaces, etc are the same exact width, as opposed to a variable-width font in which an l or a space is much narrower than an M or a W).  The <PRE> tag in HTML code tells the web browser to display the text using a mono-spaced font until it reaches a </PRE> tag.  In some cases, the tablature may be made web-browser friendly by inserting a <PRE> tag at the beginning and end of each line of the tablature.  This kind of bad usage is likely to cause the output sheet music to interpret the lined up <, P, R, E, and > characters as bar lines.  For this reason it is advisable to always select the Text format when saving tab files from the internet.
  
  Future versions of Mer's 'Net Tab Converter will provide better options for handling HTML code in the input files, such as the option to ignore all tags, or just certain types of tags.

The Output Configuration File

This file contains information about the images and HTML tags to use when creating the output HTML file.  Specifics are detailed in the file itself.  It is not a good idea to edit this file unless you have a good understanding of how the HTML language works as well as how Mer's 'Net Tab Converter formats the sheet music tables that it generates.

Current Problems and Limitations

This version of Mer's 'Net Tab Converter is a pre-release version.  I want to stress that it is not a finished piece of software (and might never be since I have a habit of coming up with new feature ideas faster than I can debug the existing features).  Following is a list of the known bugs, limitations, and features that haven't yet been implemented.

• Some features on the main dialog are not yet supported, including the "Key" and "Accidentals Use" selections.
• Selecting an output clef other than treble has not been tested, so I can't guarantee that the notes will line up correctly for those clefs.  If it turns out that the notes are off by a few half steps, this can be temporarily corrected by setting the auto-transposition to adjust for it.
• The output files do not contain any images or other indication of the selected clef, so it is advisable to print the generated files and draw the clef on them while you remember what you selected for the clef in the main dialog.
• Sometimes two notes want to overlap on the staff, such as when a G and the A above it are in the same chord.  In this case, some half-dots may appear in the graphical sheet music, since the bottom half of the top note will be overwritten by the top half of the note immediately below it.  This is a bug that will be fixed in a future version. 

Please report any additional problems, restrictions, bugs, crashes, errors, or feature ideas through the project website at http://nettabconverter.sourceforge.net/ or by email to rengirion@users.sourceforge.net.