# The &kguitar; Handbook

## Introduction

&kguitar; is basically a guitar tabulature editor for K Desktop Environment. It's much more than just a tab editor. It's features are:

- Free GPLed program;

- K Desktop Environment GUI;

- Powerful and convenient tabulature editing, including many effects and classical note score editing for classic instrument players;

- Full and very customizable MIDI to tabulature import and export;

- Support of extra data formats, such as ASCII tabulatures, MusicXML or popular programs' format, such as Guitar Pro's or TablEdit;

- Chord fingering construction tools - chord finder & chord analyzer;

- Many additional facilities to ease tabbing work, including rhythm and lead construction tools;

- Highly customizable to suit a lot of possible instruments (not only 6-string guitars, and even not only guitars), including drum tracks, lyrics and other MIDI events.

You may always report bugs to &kguitar; developers, using either SourceForge.net bug tracking services, complaining in one of &kguitar; maillists on SourceForge, or just directly mailing one of the developers.

### What &kguitar; is

As any sufficiently complex thing, &kguitar; is not for everyone. It wasn't designed to meet up everyone's tastes - there are already few examples of "one-size-fits-all" in commercial software world - and, in fact, the result is really ugly.

&kguitar; is still in development, and every developing process should have it's ultimate mission. &kguitar;'s mission statement is the following.

&kguitar; is a MIDI-enabled music editor that makes it possible to write down a whole multi-track song to get an approximate (may be pretty close) play in terms of MIDI. Basically, &kguitar; tries to help the following process, familiar to most of modern musicians:

- Music pieces are composed by a composer. This process involves creative construction of melodies / harmonies / rhythms, and writing it down quickly and correctly.

- Pre-composed music pieces are sometimes transcribed by ear or some other means by a transcriber. This process involves continuous writing down guesses, re-playing what you've just guessed and comparing with original sound.

- Basic harmonies and rhythms need to be arranged (or re-arranged), giving them a complex, full and interesting texture, unique sounding that will please an ear of final listener. Approximate arrangements are done in MIDI. This usually involves lots of song structure, texture and layering editing and an ability to hear every change instantly helps a big deal to estimate a final result.

- Approximate MIDI rendering of the song is helpful for rehearsals of live-performing artists. &kguitar; may be help rehearsing without gathering all the band: one musician may jam live against a full backup rendering without his track.

After that, &kguitar;'s role diminishes. There are several more steps in sound production, where &kguitar; can't really help directly, but all these steps can use songs done in &kguitar; as a source:

- Approximate arrangement in MIDI is played and recorded (or re-recorded) as live audio tracks by a performing musicians. &kguitar; can't help here directly, but it is able to export nicely rendered MIDI version of a song.

- Recored audio is mixed down and mastered by various sound engineers. Later, these songs / music may be played live by a live band, this process also involes lots of sound engineering and audio processing / mixing magic. &kguitar; can't help you here.

- Written down form of music is going through a professional typesetting system to publish note scores / orchestral scores / various other sheet music. &kguitar; can help you here a bit: it involves approximate printing (your mileage may vary a lot - it may be okay for your personal needs, but these printouts are certainly no match for a high-quality hand-tuned music engravements). Also, &kguitar; is going to be able to export data into some popular professional music engravement system formats, such as MusiXTeX or LilyPond.

So, basically, you can think of &kguitar; as of RAD IDE (Rapid Application Development suite for Intergrated Development Environment), but for music, not for computer programs. It allows you to quickly plan, write down tunes and make acceptable prototypes, that can be greatly improved later in sound production process.

### What &kguitar; isn't

Let me illustrate a few cases when using &kguitar; is suboptimal. It's by no means an excessive list, but it should give you some ideas when solving your tasks with some other tools would yield you better results.

- &kguitar; is not a music typesetting system, and, particularly, isn't a guitar tabulature typesetting system. Sure, &kguitar; is able to produce print-outs, able to save tunes in various typesetting system formats, but &kguitar; shouldn't be viewed as a standalone professional music typesttting system. Professional typesetting is complex and tedious manual task, which involves lots of manual hinting to reach best looks, placement of various helper symbols on the tabulature, etc, etc. This is why professional scores are done in specialized systems, such as NoteEdit. In guitar tabulature world, there GnomeTab that produces heavily annonated printed tabulatures.

- &kguitar; is not a MIDI sequencer. &kguitar; is able to convert its tabulatures into form of MIDI events stream, but generally, you don't have much direct access to modify it. You can't manually fiddle some of SysEx control events for your great MIDI sampler, you can't directly and independently of tabulature change settings of most controllers, you even can't directly use "pitch wheel". Most importantly, MIDI event stream consists of various MIDI events which can have very irregular timing - it isn't the case for &kguitar;. &kguitar; is closer to infamous tracker software in terms of representation of score data: there are fixed pattern array where various notes can be placed in, deviations from this time grid are possible, but should be done with tabulature effects. If you require a full-blown MIDI sequencer for your work, try using RoseGarden or MusE.

- &kguitar; is not a hard disc audio recording system. &kguitar; does not support audio tracks, editing, mixing, looping, mastering, pitch-shifting, applying any effects to audio in real-time or destructively and probably would never be. Audio recording, editing and mastering is a whole another land, where you should use some audio-processing tools, such as Jack audio server, EcaSound multitrack audio processing tool, already mentioned RoseGarden and MusE with their audio-related capabilities. Also, due to the fact that &kguitar; does not process audio, it doesn't bundle any fancy feature like guitar tuners or stuff like that. You can have decent guitar tuners for free as separate applications, there is no need to include them in &kguitar;.

## Using &kguitar;

&kguitar; is a pretty complex software, but if you'll ever used any musical notation editors, it won't be hard for you to learn &kguitar;.

### What is a tabulature?

If you're a professional guitarist who uses tabulatures in everyday's work, then you may skip this section and head straight to tabulature editing. However, if you've never used tabulatures before, you should read this section.

Tabulatures are pretty ancient form of writing down musical patterns. The name "tabulature" originates from ancient latin "tabula", a word that means "a board for writing down things" (that's why the right form of this word is tabulature, not tablature, as most of modern sources think).

Basically, tabulature is a form of music notation for a specific instrument which tells the performer not what to play generally, but how to play it just right. That's the biggest difference between standard note scores and tabulatures. In all other aspects, they're more or less compatible and comparable.

In particular, when tabulature is written down for guitar or similar fretted instruments (we'll refer to all them as "guitar" and we'll refer to a human being that plays these instruments as "guitarists" below), tabulature contains data on what fret should be touched with one hand and what strings should be picked with the other.

### Basic tabulature editing

Tabulature editor is a central part of &kguitar; application and everything else seems to revolve around it.

A screenshot of song view Screenshot

Song view consists of several parts: top part with the tabulature editor itself, and the bottom part with a track manager and editor. Track manager allows you to create multi-track songs and its track editing functions would be explained in detail later and this section will concentrate on features of tabulature editor.

In &kguitar; tabulature editor, the most basic unit of a song is a single column. Column is a group of notes (or rests) that begin at the same time (well, almost, there's an exception to this rule if tabulature effects are used) and have same duration (there're also some exceptions). Such notes (and corresponding fret numbers for them) are vertically aligned and form a single column of tabulature.

Your cursor is shown as an inverted square in tabulature editor. You can move it inside tabulature column (using Up Arrow and Down Arrow keys) and put fret number in the column with digit keys 0-9. To put a two-digit fret number (for example, 12), just press 1 and then press 2 - &kguitar; will detect this and you'll get that 12 eventually. Use Delete to delete entered fret numbers and make rest instead of it in this place on selected string.

One of the very convenient features of &kguitar; is easy transposing. For example, if you think that playing a note on 2nd string is not convenient and 3rd string will be a better choice, just use this function to automatically "pull" fret number from 2nd string to the 3rd and it will get updated accordingly to maintain the original note pitch. Use key combos Ctrl Up Arrow and Ctrl Down Arrow to shift fret numbers like that while moving cursor up or down a string.

### Note durations

When transcribing a piece of music, it's essential to be able to specify durations of notes, i.e. intervals of time they sound.

In &kguitar; every column has a duration (that's one of the major advantages of &kguitar; over ASCII tabulatures, which provide no rhythmic information), which are notated in normal musical form relative to current tempo, i.e. 1/1, 1/2, 1/4, etc. You can see current column's duration as a shape of downward stem and change either using toolbar's duration buttons or with keys - and = (+) to halve or double current duration accordingly.

You can also use so-called "dotted" note durations (when note durations have extra one half of original duration added, thus, for example, for 1/2, making 1/2+1/4=3/4) and triplets (when note durations are 2/3 from original, thus it's possible to fit three triplet columns where there were only two original ones). Use key . to toggle dot status of a note and use t to toggle triplet status. Triplets would be automatically shown in groups of 3 when you'll enter sufficient number of them.

Though such column-oriented approach was critiqued a lot because of it's mythical inflexibility, we advocate for such approache because of it's natural simplicity in most of frequent situations. Later in this documentation, we'll demonstrate how it can be used to transcribe even the most complex musical figures.

### Bars, beats, time and key signature

Most often, music fits some sort of rhythmic mode. Thus, for convenience, similar musical phrases that are marked by beats are separated with bars in musical score. Bars are supported in &kguitar; automatically. Just fit enough note durations to fill one bar and &kguitar; will automatically goes to the next. If you're automatical barring will screw (if you'll delete some column in the middle of the song, for example), use rearrange bars function, available via Shift a Track Arrange Bars

Quantity of beats per bar and value of one beat is called a time signature. &kguitar; lets you set time signature using Shift t Track Time Signature . In the dialog, you'll be presented with an option either to set time signature for current bar only or to set it from current bar to the end of song. If you want to reset the time signature for the whole song, remember to go to the very first bar and use this command with "to the end" checkbox enabled.

Another essential property of a bar is a key signature that determines number of signs of alteration (sharps or flats) that act in this bar. &kguitar; lets you set key signature using Shift k Track Key Signature . This is a very simple dialog where you can select one of key signatures from 7 sharps to 7 flats.

### Tabulature Effects

Tabulature can contain various guitar-specific (and not only guitar) effects. All these things have special symbols assigned to them. You can add effects via either pressing a hotkey or clicking on a toolbar item.

Supported effects so far:

- h - Natural harmonic

- r - Artifical Harmonic

- p - Legato (hammer on/pull off)

### Using Clipboard

You can use all familiar clipboard operations in &kguitar;-edited tabulature.

### Chord Constructor

TODO

### Rhythm Constructor

TODO

### Melody Editor

Melody editor is a tool that helps entering tabulature with mouse. It somewhat loosely resembles Cakewalk's tab staff fretboard or TablEdit's fretboard, but much more useful and flexible. Melody editor lets you easily and quickly enter harmonized solos, fills and etc, by just clicking every note on the fretboard in order of playing.

#### Basic usage

Editor looks like fretboard photo from the same point of view as you read tabulature from. By default, you can click any place on that fretboard and some sort of action will be executes, depending on what button you have pressed:

- Left mouse button - set note on clicked fret and string.

- Middle mouse button - set 022-type power chord on clicked fret and string.

- Right mouse button - set note on clicked fret and string, and on release of mouse button, track cursor advances to the next column - ideal for entering mono-voiced soloes.

#### Setting actions

TODO

#### Customizing Melody Editor

Fully customizable, now supports several inlay types. Work in progress, so more to come. TODO

### Advanced Transcribing

Column-based approach to tabulature transcribing may seem inflexible for most complex pieces of music, but it's not true. Let's demonstrate a few examples of some intonational complexity based of note durations.

The main principle one should stick to while using column-based approach is simple: the tabulature is about how music should be played, not what generally should sound. This rigidly fixes tabulature on particular instrument, but, nowadays, converting from one type of tabulature to another is automated task you can delegate to your computer, rather that comprehending it yourself.

#### Example 1: Mixed duration notes

We need to transcribe two notes that start at the same time, but first one sounds for 1/4 or a beat and second one lasts for 1/2. This is how it looks in classic note staff (screenshot of a Rosegarden sequencer's note editor):

Mixed duration notes on a classic note staff

It seems to be impossible to do that it in column-based tabulature, as all notes stacked in a column seem to have same duration.

Remembering the main principle mentioned above, let's think about how such a figure would be played, for example, on a guitar. Naturally, strings are all the same and we can assume here that they sound infinitely long if not interrupted. How can a guitarist interrupt string sound? There are three possibilities:

- He can fret some sort of other note on the same string, thus ending the tone of previous one;

- He can mute the string with his finger or palm with audible muting click (so called "dead note");

- He can just mute the string with his finger or palm silently;

You can implement it all three ways in KGuitar tabulatures. Let's see how to do that. In all cases, we'll use note "let ring" tool to transcribe long notes. Let ring is a property of every single fret number in a tab. Use the "let ring" tool to toggle that property: either the fret will let ring or not.

##### Ending sound with some other note

Ending sound with some other note

This is how it will look like. Fifth string "2" fret number has a let ring option, so it will ring for as long as bar lasts or anything will interrupt it. Note that horizontal line that normally represent a string became an arrow that represents how long the note sounds - note starts on the digit and ends on the arrowhead, i.e. 1/4 (full length of bar). Fourth string "2" sounds only 1/8 as it's superseeded by "5", picked on a same string.

In complex cases, "2" on fourth string can have let ring options turned on too to achieve even more sophisticated timings.

##### Ending sound with audible muting (dead note)

Ending sound with audible muting (dead note)

This one is just like the first one, but with real note ("5") replaced to dead note ("X"). Dead note means that guitarist will mute the string in some sort of way (for example, with a direct pick strike) that it will produce a loud audible click and stop sounding. Transcribing technique used is just the same.

##### Muting string silently

It was mentioned above that "let ring" options is toggleable for every fret number in the track. That's more than it. You can turn "let ring" on for empty space (i.e. nothing played) to produce some sort of anti-"let ring". Such empty space with anti-"let ring" will stop previously ringing string.

Muting string silently

This technique is demonstrated on the this tabulature. Both 2 notes from the beginning have a "let ring" on them. However, in second column on the fourth string there is empty space with anti-"let ring" that signals guitarist to mute the string without making any more noises. Fifth string continues to ring to the end of bar. Arrows show for how long each note will sound.

### Track Editing

TODO

The Squiggle Tool Squiggle is used to draw squiggly lines all over the &kguitar; main window. It's not a bug, it's a feature!

## Supported Formats

&kguitar; supports multiple tabulature storage formats and various options for importing/exporting. Don't seek a separate import/export menu items, all such operations are done from normal File Open and File Save menus - just select the file format you want. If conversion requires special options, you'll be presented with a separate conversion dialog. This is exactly the same dialog as the one that appears in &kguitar; settings menu (Settings Configure KGuitar). If you don't want this dialog to appear every time and just want to accept default values (which are saved, by the way), you can uncheck the Show this dialog in conversion process. Then, if you'll ever need to change it, it will be accessible in Settings Configure KGuitar dialog.

### KG format

KG is a native &kguitar; format that saves absolutely anything you can have in the song. Nothing much to tell about. It's a best format if you just want to use &kguitar; and nothing else.

### MID format

MID (MIDI file) format is currently supported for export only. MIDI file is a file that basically contains MIDI events, i.e. directions for a synthesizer on which notes to play, how long they should sound, what effects and instruments should be used, etc.

Exporting to MIDI is an excelllent opportunity if you want to show the tabulature you've created in its sounding form to anyone. Also every computer now with a sound card has a MIDI synthesizer (or at least there's a couple of software MIDI synths available), so good chances are that most of the people would be able to listen to your transcribed song. However, keep in mind that MIDI doesn't contain tabulature information at all, i.e. no instrument tuning information are stored, no fret numbers, nothing like that. Effects and various guitar techniques are only approximated via special controllers to sound similar to natural performance.

&kguitar; is able only to export MIDI files for now, but MIDI import with automatic tabulature generation is planned to be added.

### MusicXML format

This is a relatively new format, specified by Recordare and encouraged to be used in all music-related programs. This format is based on widely acclaimed XML and seems to be a new standard for music scores interchange.

MusicXML is recommended if you want to share your tabulature with the rest of the world. Most of the guitar-specific tabulature information is preserved in MusicXML. &kguitar; is able to both import and export MusicXML.

### ASCII TAB format

ASCII TAB is the most widely used tabulature format in the Internet, there are numerous archives that host tabulatures in this format. It consists of a plain text file in which the tabulature is depicted using staves (with minus characters), numbers (digit characters) and effects (with various letters). Among them there could be occasional texts, playing directions, etc. There's no single standard for ASCII tabs, so sometimes it may be a hell amount of work to comprehend a screwed tabulature. Lots of information is often missing from ASCII tabs, most often - the rhythm and note durations information, that makes plainly impossible to play that tabulature if you've never heard the song before (and even if you did, it isn't always very clear how to do it).

&kguitar; now supports only exporting of ASCII tabs. However, if you're going to distribute your created tabulature, we recommend you not to do it in ASCII TAB legacy format. Due to lots of unsaved information, a load of your hard work will be just lost without any traces. Use MusicXML for tabulature distribution, if at all possible.

### Guitar Pro 4 format

Guitar Pro is a popular commercial guitar tabulature editor for Windows and, sadly, it's proprietary format is widely used on the Internet tabulature sharing resources, such as MySongBook. There was a pity to ignore such a huge source of tabulatures and &kguitar; has an import support for Guitar Pro format.

Guitar Pro has at least 3 major formats: GTP (version 2), GP3 (version 3) and GP4 (version 4). &kguitar; officially supports only GP4 (version 4) format. All older formats can be easily converted to GP4 with Guitar Pro itself, and. currently, we have no plans to support older format revisions in &kguitar;.

As Guitar Pro is a closed format and it's specs are available only through trial-and-error determining process, bugs and glitches in Guitar Pro import code are imminent. If you'll encounter a file that latest version of Guitar Pro loads correctly and &kguitar; does not - you're welcome to contact &kguitar; development team and report it.

## Command Reference

### The main &kguitar; window

#### The File Menu

Ctrl n File New

- Creates a new document

Ctrl s File Save

- Saves the document

Ctrl q File Quit

- Quits &kguitar;

## Questions and Answers

&reporting.bugs; &updating.documentation;

My Mouse doesn't work. How do I quit &kguitar;?

You silly goose! Check out the Commands Section for the answer.

Why can't I twiddle my documents?

You can only twiddle your documents if you have the foobar.lib installed.

## Credits and License

KGuitar team includes developers:

- Mikhail Yakshin AKA GreyCat greycat@users.sourceforge.net

- Alexander Brand AKA alinx alinx@users.sourceforge.net

- Leon Vinken lvinken@users.sourceforge.net

- Matt Malone Marlboro@users.sourceforge.net

Documentation copyright 2002 Mikhail Yakshin greycat@users.sourceforge.net

Translation is done by:

- Wilane Ousmane wilane@users.sourceforge.net

- Harri Haataja realblades@users.sourceforge.net

- Stephan Borchert sborchert@users.sourceforge.net

- Richard G. Roberto robertor@users.sourceforge.net

- Riccardo "FeAC" Vitelli feac@users.sourceforge.net

&underFDL; &underGPL;

## Installation

### How to obtain &kguitar;

Latest version of &kguitar;, as well as the latest development news and information can always be obtained from &kguitar;'s homepage. Or look for kguitar or similar package in your favorite distribution.

### Requirements

In order to successfully use &kguitar;, you need KDE 3.x. TSE3 (Trax Sequencer Engine 3) library is very recommended for all MIDI-related capabilities of &kguitar;. There are no special hardware requirements, though having MIDI synthesizer (either full-blown external keyboard or an internal one, integrated on your sound-card) is a big plus that will let you use all MIDI features.

TSE3 library can be found at TSE3 home page.

### Compilation and Installation

In order to compile and install &kguitar; on your system, type the following in the base directory of the &kguitar; distribution:

    % ./configure
    % make
    % make install

Since &kguitar; uses autoconf and automake you should have not trouble compiling it. Should you run into problems please report them to &kguitar; team.

### Configuration

Advanced printing and track displaying features, such as note scores in classical notation, require special Feta fonts to be installed. If you had &kguitar; from some sort of pre-built package, chances are you've already got this font in your system, but if you're building from source, you'll need following instructions.

&kguitar; uses 2 Feta fonts: Lilypond's Feta font and Feta nummer font. Type1 versions of them are available in Lilypond packages.

Prepare at least files "feta20.pfa" and "feta-nummer10.pfa" from Lilypond distribution. This assumes that these files are available in the current directory:

    % cp *.pfa /usr/X11R6/lib/X11/fonts/local
    % cd /usr/X11R6/lib/X11/fonts/local
    % ls -x *.pfa | make-font-dir.py > fonts.scale
    % mkfontdir

These steps copy the font files and create two files "fonts.dir" and "fonts.scale" with lines, describing these fonts.

Note: make-font-dir can be found in lilypond-1.6.5.tar.gz.

Next, you'll have to update your configuration files:

- Add a line "/usr/X11R6/lib/X11/fonts/local" to the catalogue section in /etc/X11/fs/config

- Add a line "<dir>/usr/X11R6/lib/X11/fonts/local</dir>" to the font directory list in /etc/fonts/fonts.conf

After the first step, the Feta fonts become available to X11 applications and can be viewed in "xfontsel". After the second step, the font will also be found by KDE/Qt applications, such as KCharSelect or KWord.

&documentation.index;