Open Beat Box : A Virtual Drum Machine
           ______________________________________________

   Table of Contents
   Introduction
   Copyright
   Licence
   Portability
   Installation
   Dependencies
   Running OBB
   Known Bugs

Introduction

   Open Beat Box (OBB) is a virtual drum machine. It is a program
   to  make  songs  with  music  sample  in  loops instead of the
   traditional method with scores and instruments.

   This  is  our  fist public release. Don't expect much from it,
   it's a proof of concept release. This release doesn't do a lot
   of things but it serves its purpose, it clearly shows that the
   technology  we  use is up to the task. We are in a early stage
   of  development but we are far enough to receive you feedback.
   Don't  hesitate  to comment this release, good or bad, we need
   your comments.
     _________________________________________________________

Copyright

   Copyright 2002 Yannick Gingras <ygingras@ygingras.net>

   Copyright 2002 Vincent Barbin <vbarbin@openbeatbox.org>
     _________________________________________________________

Licence

   This  program is free software; you can redistribute it and/or
   modify it under the terms of the GNU General Public License as
   published by the Free Software Foundation; either version 2 of
   the License, or (at your option) any later version.

   This  program  is  distributed  in  the  hope  that it will be
   useful,  but  WITHOUT  ANY  WARRANTY; without even the implied
   warranty  of  MERCHANTABILITY  or  FITNESS  FOR  A  PARTICULAR
   PURPOSE. See the GNU General Public License for more details.

   You  should  have  received  a  copy of the GNU General Public
   License  along  with  this  program; if not, write to the Free
   Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
   MA 02111-1307 USA
     _________________________________________________________

Portability

   A  major  goal  of  OBB  is  portability. This release is only
   tested  on  a Linux Standard Base 1.2 compliant system though.
   We  want  to include more platforms in our future releases but
   we  don't  have  a  lot of systems to do our tests. If you are
   interested in helping us to improve our portability by testing
   source  snapshots  on  specific  systems,  please contact us :
   http://openbeatbox.org/contact  .  We would be more than happy
   to have a longer list of tested systems for the next release.

   As far as we know, all our code should be portable. You should
   be able to see the OBB GUI on any platform that support Python
   and  Qt.  The  sound part is not ready yet for Windows but you
   should  ear OBB on any system that support the UNIX like sound
   architecture. This should include *BSD and Mac OS X.
     _________________________________________________________

Installation

   Due  to the early stage of our development, you will typically
   not install OBB. You will be able to run it from the place you
   extracted  the  archive but we don't want to scatter all those
   pre-alpha files across your filesystem. We prefer to have them
   enclosed right here is this directory.

   You need to install a few dependencies before you can run OBB,
   let's get started !
     _________________________________________________________

Dependencies

   OBB did not reinvented the wheel nor the raster operations. We
   use  several  packages  and some of them may not be present on
   your system. To run OBB you will need :

     * Qt
     * Python
     * PyQt
     * cSound
     _________________________________________________________

Qt

   This  is  the  graphical  user interface (GUI) toolkit we use.
   Chances  are  high  that it's already installed on your system
   but you will need to install the development package too. On a
   RPM based system check if it's installed with the command
     rpm -qa | grep qt

   the result on my system is

     libqt3-3.0.5-7mdk
     libqt3-devel-3.0.5-7mdk

   the  name and version may differ slightly but if you don't see
   the two packages and one with "devel" in it's name you have to
   install it.

   Most  distributions  comes  with  Qt  but if yours don't, just
   download it from Trolltech's web site
   (http://www.trolltech.com).    Qt's   distribution   is   well
   documented  and  not really hard to install. Be warned that it
   will take really long to build.
     _________________________________________________________

Python

   This  is the programming language OBB is written in. It's easy
   too see if it is installed, just type :
     python -V

   you should see something like this :
     Python 2.2.1

   which is good news, or like this :
     bash: python: command not found

   which means you are in trouble. In the later case, you have to
   install  Python. Grab the latest version from the Python's web
   site  (http://python.org),  build it and install it. Python is
   easier  and  faster  to  build  than  Qt so you should have no
   problem here.
     _________________________________________________________

PyQt

   The  things  are getting interesting here. Qt is a really nice
   toolkit  and  Python is a really nice language. Unfortunately,
   Qt  is  written  in C++ so we can't use it directly in Python.
   PyQt is a binding to use Qt in Python. You probably don't have
   it  installed  since  really  few distributions provide it. To
   check if you have it, type :
     python -c "import qt"

   You  will  either  have no result and you will get back to the
   command  prompt,  which  means  that  PyQt  is installed, or a
   message like :
     Traceback (most recent call last):
       File "<string>", line 1, in ?
     ImportError: No module named qt

   In  the  latter  case,  you  have to install PyQt. You have to
   download   the   latest  version  from  the  PyQt's  web  site
   (http://www.riverbankcomputing.co.uk/pyqt/index.php).

   There  are  a  few  tricks  that  will  help  you  with PyQt's
   installation.  The  first step is to install Sip that you will
   find  on  the  PyQt's  web site. If the installation complains
   about QTDIR, it's because it is looking for the place where Qt
   is  installed. On most systems this should be /usr/lib/qt3/ so
   just type :
     export QTDIR=/usr/lib/qt3

   Once  Sip  is  installed, you might what to proceed with PyQt.
   Before you build PyQt, have a look at the file README.Linux in
   the  PyQt's  distribution. You will need to modify a few files
   on  some  Linux  distribution. Building PyQt cat take a lot of
   time  but  if  you have enough RAM(I'd say 128M), you can pass
   the -c option to the build.py script :
     python build.py -c

   This  will merge all the PyQt's code in a single big file. The
   build  process  is at least 5 times faster with the -c option.
   You have to be root to build PyQt, not just to install it.
     _________________________________________________________

cSound

   The  last  but  not the least, cSound is the sound synthesizer
   engine behind OBB. The cSound port for Linux is sometimes hard
   to   install.   There  is  almost  no  documentation  for  the
   installation so we will guide you. You will find the different
   branches of the Linux port of cSound at
   http://www.bright.net/~dlphilp/linux_csound.html  .  The  last
   time we tries the branch hosted on
   http://www.cs.bath.ac.uk/pub/dream  ,  it  proved  to be quite
   unstable  so  we  recommend  the  unofficial  port  hosted  on
   ftp://mustec.bgsu.edu/pub/linux  .  If you ever try the branch
   on   www.cs.bath.ac.uk,   be  warned  that  the  archive  will
   uncompress  the  files  in  the  current  directory instead of
   creating  a  new  one. the unofficial cSound can be built with
   the regular
     ./configure; make; make install

   The  branch  on  www.cs.bath.ac.uk will require you to use the
   Makefile for Linux :
   make -f Makefile.lnx; make -f Makefile.lnx install
     _________________________________________________________

Running OBB

   Good,  now  the hard work is done and you can enjoy OBB. There
   is  a  script called obb in the directory where you found this
   README. Just run it :
     sh obb

   or:
     ./obb

   There  is  not much functionalities in this release but follow
   the  online  help  to  get started. The green buttons with the
   weird  shape  at the right of the four holder bars are the hit
   buttons.  The  diamond shaped ones at the left are the command
   buttons.  You  can  click  play  now.  The red flashing lights
   indicate which hit buttons are being queried for a sound.

   Each  holder bar has a different sound but all the hit buttons
   on  the  same  holder bar plays the same sound. Click on a hit
   button  to  activate  it. It should be brighter. Next time the
   red light passes to this hit it will record it's state and the
   next loop will play the sound at this position. You alway work
   a  step  (a full cycle of the red light) in advance of what it
   being played.

   That's  about it for now. We have to implement the rest of the
   functionalities.  How  did you like it ? We'd like to ear from
   your impressions.

   Please contact us : http://openbeatbox.org/contact .

   Thank you for trying OBB !
     _________________________________________________________

Known Bugs

   We  prefer  to  have  only a few features but to be mostly bug
   free. There are a few bugs that we did not fixed at the moment
   for  various  reasons.  Most  likely  we  left them there even
   though  we  know  they exists because they are part of modules
   that will be completely rewritten in future versions.

   We know the existence of the following bugs :

     * The stop button do not empty the sound buffer. The current
       cycle is played until the end.
     * When quitting when the song is playing a temporary file is
       left on the filesystem.
     * The  hit  button next to the scrolling text may glitch and
       print some text under itself.
     * The  sound  tend  to get out of sync with the GUI when the
       last hit of the cycle is on for any sounds.
