Hello, 

guitarix,

guitarix is a simple guitar mono amplifier to be used in a 'jackified'
environment (Jack Audio Connection Kit). Guitarix provides one jack
input port and two jack output ports. It is designed to produce a nice
trash/metal/rock/blues guitar sounds. Controls for bass, treble, gain,
compressor, preamp, balance, distortion, freeverb, crybaby(wah) and
echo are available. To modify the sound 'pressure', you can use the 
feedback and feedforward sliders.

guitarix includes an experimental tuner and a JACK midi output port
with 3 channels. They will be fed by a mix from a pitch tracker and a
beat detector. You can pitch the octave (2 up or down), choose the
midi channel, the program, the velocity and the sensitiviy, which
translates into how fast the note will read after the beat detector
emits a signal. Values for the beat detector can be set for all
channels.


======================= Build procedure

---- build environment

As of version 0.04.5-1, guitarix uses 'waf' for the build environment.
The simplest and fastest way to build guitarix is given below:

cd guitarix_source_directory
./waf configure
./waf build
sudo ./waf install

By default, this will install guitarix and related files in
/usr/local/...

The installation prefix can be provided at configure time, e.g.:

./waf configure --prefix=/usr
./waf builf
sudo ./waf install


---- dependencies 

To compile and run properly, guitarix needs the following extra
packages (runtime binaries / libraries and developement packages, aka
package-dev):

gtk+-2.0 >= 2.12.0 
sndfile  >= 1.0.17
jack (jackd, libjack, and dev) >= 0.109.1
boost library >= 1.38, in particular 'boost_program_options'


---- debian
To build a debian package, run "dpkg-buildpackage -rfakeroot -b"



==================== Start up options

---- From the Command line

Guitarix provides a few user options at startup. They can be set in
two ways.  From the command line, guitarix can be invoked with the
usual -h or --help option. The following help message is displayed:

$ guitarix --help

 guitarix usage
 all parameters are optional. Examples:
        guitarix
        guitarix -r black -i system:capture_3
        guitarix -c -o system:playback_1 system:playback_2

  -h [ --help ]         Print this help
  -v [ --version ]      Print version string and exit

 GTK configuration options:
  -c [ --clear ]        Use 'default' GTK style
  -r [ --rcset ] arg    Style to use: 'black', 'pix', 'sunburst' or 'default'

 JACK configuration options:
  -i [ --jack-input ] arg  Guitarix jack input
  -o [ --jack-output ] arg Guitarix jack outputs
 

The options should be self explanatory but for the sake of clarity, a
few extra words are worth mentioning here.

JACK options: 
------------- 
By default, guitarix will not auto-connect to any jack system ports,
unless the latter are explicitely provided by the user from the
command line. If guitarix is started as follows:

$ guitarix

The user will have to manually connect the guitarix jack ports to e.g.
system ports from patchage or qjackctl's connection window.


If system port names are given, as shown in the following example:

$ guitarix -i system:capture_1 -o system:playback_1 system:playback_2

guitarix will autoconnect to these system ports


GTK options:
------------
guitarix comes with 2 GTK styles: 'black' and 'pix' The user can
choose one at startup by invoking the -r (or --rc-style) option:

$ guitarix -r black

The user can also decide not to use the shipped GTK styles and instead
use the default GTK style used by e.g. gnome:

$ guitarix -c

It is of course possible to use combinations of different options (GTK
and JACK options)


---- From SHELL variables 

Guitarix offers the possibility to make some of these options more
"permanent" thanks to SHELL variables. The variables are

GUITARIX2JACK_INPUTS
GUITARIX2JACK_OUTPUTS1
GUITARIX2JACK_OUTPUTS2
GUITARIX_RC_STYLE

Those can be defined in e.g. $HOME/.bashrc.  An typical setup would be:

export GUITARIX2JACK_INPUTS=system:capture_1  
export GUITARIX2JACK_OUTPUTS1=system:playback_1
export GUITARIX2JACK_OUTPUTS2=system:playback_2
export GUITARIX_RC_STYLE=black

For (t)csh shells, the following could be placed in $HOME/.cshrc

setenv GUITARIX2JACK_INPUTS  system:capture_1  
setenv GUITARIX2JACK_OUTPUTS1  system:playback_1
setenv GUITARIX2JACK_OUTPUTS2  system:playback_2
setenv GUITARIX_RC_STYLE  black




==================== Keyboard shortcuts

Guitarix benefits from keyboard shortcuts for most of its operations.
At the moment (svn@200), the following keyboard shortcuts are available:

* Engine menu:
--------------
- Audio engine play	: Space
- Audio engine stop	: Space
- Effects bypass        : B  (see note (i))
- Effects back          : B or Space
- MIDI out ON/OFF	: Shift+M
- Quit guitarix		: Ctrl+Q

(i) Note that if jconv is running (launched from guitarix), it will still 
    be active, the wet/dry slider can also be used. 
    It implies that guitarix can be regarded as a GUI for jconv.


* Presets menu (as of version 0.04.7):
---------------
When guitarix is launched, it will browse the $HOME/.guitarix/guitarixprerc 
file and store the found presets in its menu. The preset handling is quite
versatile and let you do a few useful things:

- Load a preset         : 1, 2, 3, ... (note (ii))  
- Save a preset         : Ctrl+1, Ctrl+2, etc (note (ii))
- Create a new preset   : Ctrl+P (insert a valid name, 
                                  spaces will be replaced by '-')
- Recall main setting   : S      (see note (iii))
- Save as main setting	: Ctrl+S (see note (iv))

Submenu "More Preset Action" :
- Cycle to next preset  : Page Down  (very useful)
- Cycle to prev pres    : Page Up    (very useful)
- Save active preset    : Alt+S
- Rename active preset  : Alt+R
- Delete active preset  : Delete
- Delete ALL presets    : Ctrl+Shift+D (gives a warning)

Notes:

(ii)  If you have more than 9 presets, shortcuts are disabled

(iii) The main setting is a different context than a preset. If you quit
      guitarix while you are in a preset context, the main setting will not
      be saved automatically as guitarix knows only one setting at a time
      (the current active one). You can always recall the main setting and
      save whatever changes you bring to it with Ctrl+S. 

(iv)  Saving the main setting can be done from any context. Ctrl+S will save 
      the current state into the main setting and bring you back to the main
      setting context. Therefore, when you were in a preset context and save
      it as the main setting, you leave the preset context.  
      If you want instead to save the active preset, use Alt+S so you stay
      in this context.


* Options menu:
--------------
- Oscilloscope ON/OFF	: Shift+O
- Tuner ON/OFF 		: Shift+T	
- Meterbridge ON/OFF	: Alt+M
- Jack capture settings	: Alt+J

- Skin change cycle-through : Shift+S

* About menu:
-------------
- About display		: Ctrl+A


- Record / Stop record	: R


==================== Jack start when jack not running

Guitarix will pop up a jack start dialog window if it finds that jackd
is not running.

The user can choose to activate jack or exit guitarix.  Note that the
supported methods for starting jack are (by preference order):

1- qjackctl --start
2- use of $HOME/.jackdrc

Guitarix does not support jackdbus or any other jack start method
other than mentioned above.




=========== Extra information
---- LADSPA
Guitarix also comes as a suite of LADSPA plugins. Should the user wish
to use guitarix or some of its effects in a LADSPA host (e.g. ardour),
the guitarix plugins are available. They are installed by default in

$PREFIX/lib/ladspa

PREFIX being one of /usr or /usr/local



---- RECOMMENDS:

=> jack_capture:
For capture, guitarix uses the program 'jack_capture' from Kjetil
S. Matheussen. If you dont have it installed, look here:

			http://old.notam02.no/arkiv/src/?M=D

You don't need jack_capture to run guitarix. However, the capture
button ('record') won't work without this external
application. Pushing the record button will in this case create a
pop-up warning. Guitarix only looks in $PATH to locate jack_capture.

Recordings will always go to $HOME/guitarix_sessionX.<type>. A small
preference interface is provided by guitarix as to the jack_capture
parameters (file type, bit depth, jack ports to capture from, etc)

If jack_capture is to record into ogg, you also need vorbis-tools for
encode to ogg:

			http://vorbistools.sourceforge.net/


=> jconv
guitarix can also use the convolution engine developed by Fons
Adriaensen, called jconv, available at

                        http://www.kokkinizita.net/linuxaudio/index.html 

jconv can be configured from guitarix. However, due to design
restrictions, jconv can only be configured when not running.  Despite
this restriction, it is possible to save guitarix presets with
particular jconv settings. The user can recall these presets from the
main load preset menu item.

Note: when trying to load an impulse response wav file (IR), guitarix
will check for spaces in the filename and remove them if present.  You
can also resample the file to the one used by jack. Finally, as for
jack_capture, guitarix will run even if jconv is not installed.


===========================================
THANKS:

I (Hermann Meyer) use faust to build the prototype and will say thanks
to the following contributors:

contributors 	: Julius Smith <http://ccrma.stanford.edu/realsimple/faust/>
		: Albert Graef <http://www.musikwissenschaft.uni-mainz.de/~ag/ag.html>
		: Yann Orlary <http://faust.grame.fr/>


The waf build environment and various code cleanups are provided by James Warden.


enjoy :)

If you run prob's with build or run guitarix, please inform us.

     brummer-@web.de
     warjamy@yahoo.com
