Introduction.
-------------

Here is a little piece of program that I wrote to practice bass with
my computer running Linux. It can play bass and drums and guitar
and in fact whatever intrument you want as long as you use tablature
to describe it. It lacks a lot of features, but it may prove usefull
to someone (as it is to me), so that's why I release it to the
public. I hope you will send me comments or gripes or whatever
if you try it. I've developped it under Linux using a Gravis Ultrasound
card, but since it doesn't deal directly whith the MIDI drivers
(it writes a MIDI file which is later played by a sequencer (in my case
the ``mp'' program which comes in the ``adagio'' package)), you
may be able to make it work on another plateform, as long as you have
a C compiler to compile it.

The program is available by Mosaic, at the URL :
if you don't have access to mosaic, I can send it to you 'shar'ed
or 'tar'ed my mail, or maybe I can put it in a FTP site somewhere.

This program is Copyrighted by Stefane Fermigier (fermigie@ens.fr),
and is provided without warranty of any type. You can distribute it
and even modify it freely as long as you don't drop the copyright notice.
Some parts are Copyrighted by other persons though, so check the code.
If you add features or correct bugs, I would be glad if you could send me
the patches.

Thanks for your attention,

Stefane Fermigier, fermigie@dmi.ens.fr. 
(WWW page : http://acacia.ens.fr:8080/home/fermigie/index.html)

---------------------------------------------------------------------------

Installation.
-------------

Fetch it with mosaic at the URL : 
http://acacia.ens.fr:8080/home/fermigie/tabulator.en.html.

Make it. 

Copy tabul to $HOME/bin and copy tabul.rc to either you songs
directory or $HOME/.tabul.rc

Manual.
-------

OK, I don't have much time nor inclination to write a full manual.
Check the examples and try to understand by yourself. However, here 
are a few tips to get you started. I presume that you are familiar with
ASCII tablature as practiced in The Bottom Line mailing list (see
http://syy.oulu.fi:80/tbl/), or the newsgroups rec.music.makers.*,
alt.guitar.tablature etc.

So the tabulator is a program for transforming ASCII tablature into a
midi file, which can later be played by a sequencer. The syntax is

> tabul [-v] [-d<debug_level>] [-t<tempo>] input_file [output_file]

``input_file'' and ``output_file'' must be actual files, and not pipes, because
we need to do some fseek. If no ``output_file'' is provided, the output
file is  ``input_file.mid''. It is a format 0 midifile with only one
track on it.

The option -t<tempo> permits to set the tempo to a floating point value,
overriding the tempo set in the config part of the file. 

The other options are pretty useless. The verbose (-v) option gives
nothing, and the debug option is for those (me) who know the intrinsics
of the program.

The program begins by reading a file named ``tabul.rc'', which contains
a lot of configuration commands. Then it reads the beginning of 
``input_file'', which contains other configuraion commands, until it
reaches the command ``begin_song''. After that, it reads tablature
informations and try to produce some music.

------------------------------------------------------------------------- 

Configuration commands:
----------------------

Used in the preamble:

tablength n : set the length of the ASCII ``tab'' character to be n 
	(default 8).

division n : number of MIDI tick per quarter note (default 96).

tempo n : default tempo.

duration s n : set the duration symbol ``s'' to be n MIDI ticks.
	example : duration q 96  --> a quarter note is 96 MIDI ticks.
	By default, ``w'' is whole note, ``h'' is half, ``q'' is quarter, ``e'' is 
	eigth, ``s'' is sixtenth and ``t'' is 32th. Doted and capitalized note are 
	doted notes. Triplets are note like ``q3'', ``e3'' or ``s3''.

signature s n : the time signature ``s'' is n MIDI ticks long.
	example : signature 4/4 384

patch ch n : Midi channel ch is set to (general MIDI) patch n.
	ex patch 2 34 : channel 2 is electric bass.

perc s ch n vel : Symbol ``s'' refere to percussion channel ch, note n,
	velocity vel (ch is usually channel 10).
	ex : perc bassdrum 10 36 100 --> bassdrum is note 36 of channel 10.

tab s ch vel n : symbol ``s'' refere to a string of an fretted instrument,
	located on channel ch, with default velocity vel and open string pitch n.
	ex : tab bE 2 100 28 --> ``bE'' is the E string of the instrument on
	channel 2 (tuned like a bass guitar).

chord s n1 n2 n3 ... : symbol ``s'' is a chord. If s is something like
	Xblahblah (i.e. the letter X plus an extension), then n1, n2... are 
	pitches in semitones relative to the root of the chord:
	ex : chord X7 0 4 7 10 --> a X7 chord is the root, the major third,
	the fifth and the minor 7th.
	You can also define explicite voicings like
	ex : chord AbM 45 49 52 --> here the pitches are absolute MIDI pitches.
	One more thing : chord are always played by instrument number 1 (MIDI
	channel 1).

; [comments] : comment.

def_signature sig : set the default signature to ``sig''.

-------------------------------------------------------------------------

Songs commands:
--------------

Now after the preamble (i.e. after ``begin_song'')

The song is organized in measures. I give examples and explain:

Suppose you use the tabul.rc file supplied with the distribution.
Then

time q q q q
bE|  0 0 0 0

means play quarter note E on the open E bass string.
Note that the 0 must be just below the q. 

Now two measures:

t   q q q q   q q q q 
bA|   1 5 1 |   1 5 1
bE| 3       | 3

Means play G major arpeggios in quarter notes for 2 measures.
(``t'' is a synonymous to ``time'').

The time count is reset to what it has to be each time we cross a
measure boundary (a ``|''), so we can write funnier things like

time q+e e q q+h   h  q q
bE|  0     0 0   |    0 0

which means a doted quarter E (q+e), an eight note rest, a quarter note
E and then a doted half note which extends to the next measure. At the
begining of the next measure, there is a half note rest which is not
a real rest, because the last note from the preceding measure is still
ringing, then two quarter notes. If you do foolish things like:

time q q q q q q q q   q q q q
bE|  0 0 0 0 0 0 0 0 | 1 1 1 1

you get something really ugly because the four last notes of the first
measure are ringing at the same time than the notes of the second measure.
(There is no check that you put the good number of notes in a measure,
wich let you write something like

time t   t   t   t
bE|  0 | 0 | 0 | 0

which means a 32th note at the beginning of each measure and then rest.)

--------------------------------------------------------------------------

Drums.
------

t   q q e e q 
sd|   x     x
bd| x   x x

gives you a simple rock and roll drum pattern 

When the program reaches an empty line, all the patterns between the line
and the above empty line (or the beginning of the song) are played. 
so:

t   q q e e q 
sd|   x     x
bd| x   x x
time q q q q
bE|  0 0 0 0

means that you will ear the drum pattern and the bass line at the same
time, whereas

t   q q e e q 
sd|   x     x
bd| x   x x

time q q q q
bE|  0 0 0 0

will give you the drum pattern _then_ the bass line. But if you replace
the empty line between the two paragraphs by a semi-colon (a comment),
you will ear then both at the same time.

When you have in the same paragraph several lines with different lenght
in measures, the longest one determines the lenght of the paragraph:

t   q q q q   q q q q 
bA|   1 5 1 |   1 5 1
bE| 3       | 3
;
t   q q e e q 
sd|   x     x
bd| x   x x

will give you first one measure of bass and drum, then one measure
of drums alone. You can add a ``|'' after at the end of a line, if no
note ever appears after the |, no new measure is created, like in

t   q q e e q 
sd|   x     x |
bd| x   x x   |

-----------------------------------------------------------------------------

Chords.
-------

The support for chords is not very clever. There are two ways of using
them:

chords | Am7 | C7m | Dm |

means play these chords, one per measure, during three measures.
(Remember to put a ``|'' at the end of the line, otherwise the
last chord is not read --- this is a bug).

or

t   q   q   q   q
sc| Am7 C7m Dm  Am7

means that the chord must change every quarter note. ``sc'' is the
acronym for ``short chord'', which is a pretty dumb name (write me
if you have a better idea).
 
Note that the chord velocity is fixed to 50 in the program. Search the
variable 'chord_velocity' in commands.c if you want to change it.

-----------------------------------------------------------------------------

A musical example.
------------------

---- cut here ----
; grove performance, ex 2.

tempo 80

beginsong 

t  q q q q 
hc|x x x x

repeat 25

; measure 1 
t    s s s s  s s s s  s s s s  s s s s 
hc | x x x x    x x x  x x x x    x x x 
sd |          x                 x
bd | x   x             x     x      x
;
t    e e  e e  e s s+e e
bA |      1 1  3 3     5
bE | 3 3           1
;
t    h   h
sc | Gm7 C7 |

; measure 2
t    s s s s  s s s s  s s s s  s s s s 
hc | x x x x    x x x  x x x x    x x x 
sd |          x                 x
bd | x   x             x     x      x
;
t    e e  e e  e s s+e s s
bA |      1 1  3 3     
bE | 3 3           0   1 2
;
t    h   h
sc | Gm7 C7 |

end

---- cut here ----

Other things.
-------------

You can also try to change the tempo in the middle of one song, using

tempo | 120 | 140 | 160 | ; don't forget the last ``|'' (this is a bug)

which means that the tempo is set to 120 bpm at the begining of the first
measure, at 140 bpm at the second one, and so on. If there is no change
later, the tempo stays at 160. 

You can also change the signature of a measure from the default one 
using ``sig'':

sig | 4/4 | 3/4 | 2/4 | ; don't forget the last ``|''
t   q q q q   q q q   q q 
bd| x x x x | x x x | x x

remember that the ``sig'' command must happen _before_ any note is 
played (here, it could be after the ``t'' line, but not the ``bd'' line).

Alas, there is no way to change the default signature after the preamble.
after these lines, if you don't specify ``sig'', the signature is ``4/4''
(or whatever you put in the preamble) again.

