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 third public release. This release comes with few
   added  functionalities but lots of improvements. Again, we are
   still  far  from  a usable drum machine. Until we release this
   full  featured  beat box you are all waiting for, try this one
   and  let  us know what you like and what we should work harder
   on.
     _________________________________________________________

Copyright

   Copyright 2002-2003 Yannick Gingras <ygingras@ygingras.net>

   Copyright 2002-2003 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.  At this time we know that OBB
   had  been successfully installed on Linux an IRIX. 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. All the
   libraries  and  all  the  packages  OBB  uses  are portable on
   Windows,  Mac  and several kinds of UNIX systems. Since we did
   not  install  OBB  on those systems, this README will focus on
   installing OBB on a Linux system.
     _________________________________________________________

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
     * SDL_mixer
     * Pygame
     _________________________________________________________

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

   cSound  is the sound synthesizer engine behind OBB. One of the
   goals  of  OBB  is to run using different synthesizer engines,
   left  to the preference of the user. 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 and plenty of
   information  on all csound versions on http://www.csounds.com.
   The    last    time    we   tried   the   branch   hosted   on
   http://www.cs.bath.ac.uk/pub/dream,  it  proved  to  be  quite
   unstable,  but  the  binaries  work  fine.  We  recommend  the
   unofficial   port  hosted  on  ftp://mustec.bgsu.edu/pub/linux
   altough it's not supported anymore. 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
     _________________________________________________________

SDL_mixer

   SDL_mixer provides a portable way to access the sound hardware
   from  several  operating  systems.  It is really popular among
   game developers so the chances are high that your distribution
   provides  a package for it. You can see if it is installed the
   same way you did for Qt :
     rpm -qa | grep SDL_mixer

   the result on my system is

     libSDL_mixer1.2-devel-1.2.4-5mdk
     libSDL_mixer1.2-1.2.4-5mdk

   As with Qt, you need a package with "devel" in it's name.

   If  you can't find a binary package for your distribution, you
   can      download     the     source     distribution     from
   http://www.libsdl.org/projects/SDL_mixer/
     _________________________________________________________

Pygame

   We  use Pygame in OBB much the same way we use PyQt, to access
   the functionality of a C library in Python. Pygame is a really
   small binding, you can download it from http://pygame.org/

   Pygame is installed with the setup.py script :

     python setup.py build
     python setup.py install

   Pygame may warn you that it did not find some dependencies. As
   long  as  it  found the mixer, OBB will play sounds. The other
   dependencies  are  not  needed by OBB but you may be forced to
   install numeric 22.0 if you don't have this version installed.
   You may want to install all pygame's dependincies while you're
   at  it  in  case  you  install a game using Pygame in the near
   future.
     _________________________________________________________

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

   The  green  buttons  with  the weird shape at the right of the
   four  holder bars are the hit buttons. The diamond shaped ones
   on  the  left of the tool bar 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.

   The button with the speaker on it preview the sample loaded on
   it's holder bar. You can change this sample by clicking on the
   button with a folder on it.

   The  sliders  next  to  the  preview  buttons  are the balance
   sliders  you  can  adjust on witch stereo channel you want the
   sample  to play by double clicking on it you'll wet it on it's
   default value.

   You  can  change  the tempo with the amber spinbox. It support
   mouse wheel, it's the fastest way to change it quick.

   You  can change the master output volume by draging the handle
   on the slider next to the tempo spinbox.

   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  slider won't change it's value unless you release the
       mouse while it's over it.
