===============================
Jackbeat - JACK Audio Sequencer
===============================

Introduction
============

Jackbeat is an audio sequencer running on Linux and Mac OS X, for musicians 
and sound artists:

* Drummachine interface with accurate VU meters for easy editing
* Realtime operation : while playing, the sequence can be edited and
  resized, the bpm rate modified, and new samples loaded,
* Easy to use and yet powerful : just JACK it into jack-rack and you
  can apply LADSPA effect plugins on a per track basis, perform 
  mastering with jackeq , etc...
* Loads and saves .jab files, Jackbeat's xml+tar file format.
* Unique Masking feature: allows to insert silences into a 
  track in an interactive manner

Requirements
============

* JACK, the Jack Audio Connection Kit (http://jackaudio.org) : a running server
  as well as the API header files. Mac OS X users should see 
  http://www.jackosx.com

* GTK+-2.0 (gtk.org)

* libsndfile (www.mega-nerd.com/libsndfile)

* libxml2 (http://xmlsoft.org)

* libsamplerate (http://www.mega-nerd.com/SRC)

Optional dependencies
=====================

* Phat Audio Toolkit: install this library (http://phat.berlios.de) if you
  want cute fan sliders instead of spin buttons for volume control. 
  You'll also need to run (see Installation) : 
  ./configure --with-phat

Installation
============

Jackbeat uses autoconf and automake, so you should just need to type :

./configure
make 
make install

Usage
=====

Before launching Jackbeat you should start the JACK server, for example
with qjackctl (http://qjackctl.sourceforge.net/), or by invoking jackd
on the command line. If you don't know what JACK is, I recommend that you
take a look at: http://jackaudio.org

Jackbeat is pretty simple to use. You can load samples by pressing the
track buttons (on the left-side of the window), then by toggling some
of the buttons on the drummachine and clicking Play you shall hear some 
music. Well... hopefully ;)

Some hints:

File Menu
---------

Export waveform:
  mix and export the current sequence as a WAV file.
  Supported parameters:

  Framerate:
    The resulting WAV file's framerate. Beware that the current resampling
    quality (see Options menu) is used for exporting too, so that it
    sounds exactly as in Jackbeat. You may want to increase quality
    before exporting though.

  Sustain:
    This determines how to handle samples that continue playing passed the
    end of the sequence:

    - loop: mix at the beginning. This is optimal for playing the exported
      WAV file as a loop in some external software.
    - truncate: don't play at all. This will sound like the initial sequence
      playback, before it has looped at least once.
    - keep: continue playing samples until they terminate. Beware that the
      exported file may thus be (much) longer than the sequence.

Edit Menu
---------

Clear:
  empties the current sequence

Double: 
  Increase the beats number by a factor of 2, and duplicates the beats data.
  This feature allows you to increase your workspace size, while keeping the 
  output unchanged.

Transpose volumes:
  Interactively increase/decrease all tracks volumes by a given percentage

Options menu
------------

Auto-connect: 
  wether you wish Jackbeat to automatically connect its outputs to some 
  playback hardware or not.

Transport control:
  If set to "Respond and query" (the default), clicking on "Play" will both 
  enable (or disable) the current sequence and tell Jack to start (or stop) 
  playback.
  If set to "Respond", clicling on Play only enables the sequence. It's up to 
  you to start Jack Playback (check the jack_transport or qjackctl tools).

Resampling quality:
  This setting is used when the sample framerate (ex: 44100Hz) differs from 
  JACK's framerate (ex: 48000Hz) on one or more track(s). Because resampling
  happens in realtime, choosing a high quality can consume much resources.

About track masking
===================

Tracks masks allow you to insert silences into a track in a highly interactive 
manner. 
  
Use Shift-Click to toggle the mask for a given beat. The corresponding track will
then get muted during the duration of that beat. 

About fine tuning pitch and volume:
  Each track has individual pitch and volume controls. In order to fine tune both
  of these you can use the Alt-Click combination when you click on the spin buttons.

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

Global shortcuts:

- <space> : Start/stop playback
- (and the usual File menu stuff)

Pattern editing shortcuts:

- <up>/<down>/<right>/<left> : move
- <return> : toggle beat
- <shift><return> : toggle mask

Feedback
========

Please give me some feedback. Tell me if Jackbeat inspires you. 

I invite you to use the public forum at:
http://www.samalyse.com/jackbeat/phorum

It does not require any subscription, login or any other dumb questions about 
the color of your underwear. 

Bugs reports are greatly welcome. If you start Jackbeat from a console, it will
dump a lot of debugging informations, which you can copy and paste into the 
Jackbeat forum along with a small note, in case of krash/problem. It shouldn't
take you more than a minute.

You may also send me links to your musical productions so that I can include 
them on the home page.

Contact
=======

Home page : http://www.samalyse.com/jackbeat

Olivier Guilyardi <olivier {at} samalyse {dot} com>