
   pyTrommler version 0.9 - A Cross Platform Drum Machine
   Copyright (C) 2006 Robert Muth <robert at muth dot org>

    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; version 2 of June 1991.

    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 in form of the file COPYING;
    if not, write to the

    Free Software Foundation, Inc. <http://www.fsf.org>
    59 Temple Place, Suite 330,
    Boston, MA 02111-1307  USA

    $Id: README,v 1.10 2004/05/07 22:18:50 muth Exp $

Short Description
=================

pyTrommler is a cross platform drum machine using Python + GTK + SDL

o Graphical user interface based on GTK
o Use of 16 bit 44100kHz wav samples (mono or stereo)
o Realtime audio output using SDL
o Alternatively, audio output to file
o Variable number of beats per pattern
o Volume adjustment of drum samples
o Stereo panning of drum samples
o Environment variable "TROMMLER_DRUM_DIR" for drum sample directory

Updates
=======

If you want receive email about future pyTrommler version please sign up at
Trommler's Freshmeat page at:

http://freshmeat.net/projects/pytrommler/

While you are at it, please write a comment or rank pyTrommler.

Installing and Running pyTrommler
=================================

Just unpack the archive after install the prerequsite packages
and run pytrommler.py
There is a demo song rumba.sng in the Test directory.


TODO(muth): This does not work yet:
You can specify a song on the command line to be loaded by pyTrommler.
The option -nosound will keep pyTrommler from using your soundcard.
TODO(muth): mention TROMMLER_DRUM_DIR

Getting Started
===============

The pyTrommler interface comes up with 32 empty tracks.  Each track
has the following items (from left to right): track number, volume
control, panning, mute/unmute, track name, 4 measures with 4 beats
each (adjustable).

First off you will need to load drum samples. (if you load a song and
the path are set correcty, this step may be skipped).  Click on the
track number and the pop-up menu will give you a choice of loading,
clearing or swapping a sample. After loading a sample you can name the
track as you wish, because this is not done automatically.  Set the
volume and make sure the track is not muted.  You can now depress the
rectangles in the measures where you want the beat to be.

The bottom of the interface contains the play options (Nothing,
Pattern, Range, Song).  Depress Pattern and the riff you just created
will be looped continuously.  If you don't hear anything check
speakers, volume settings and sound drivers of your box.

Taking It Further
=================

The concept of pyTrommler is to build songs, which in turn are build
up of patterns.  An example of a song might be: 1. intro, 2. riff, 3.
changeover, 4. riff, 5. outro. In this example there are only four
different patterns.  The top of the interface houses the options for
patterns (from left to right): pattern number, pattern name, number of
units (or measures if you prefer), beats per unit (measure), rotating
the riff, copying another pattern into the current one.

To build a song first build the four different patterns.
Select pattern 0, build the intro and name the pattern.
Now use the arrow buttons to switch to pattern 1, build the riff and name the pattern.
Do the same for the changeover and outro.

Now that you have all the different patterns ready you can put the
song together.  Just below the tracks are the song options (from left
to right): song name, number of measures, beats per minute, set first
measure of song range, set last measure of song range. Our song name
is 'example' and we have five measures in our song, so we use the
arrow buttons to make that choice.  You will see that the five
measures appear just below the song options.  You can now link the
patterns with the measures by entering the number of the pattern in
the text box. In our case this would be 000 -> 0, 001 -> 1, 002 -> 2,
003 -> 1, 004 -> 3.  To hear the song depress the radio button Song in
the play options. Lastly we will save our masterpiece.

The special drum name "@ACCENT" will superimpose its volume
on other drums played simultaneously with "@ACCENT".


Samples
=======

pyTrommler uses standard 44.1kHz 16 bit signed samples as input (mono or stereo)
and will produce stereo output.

A few samples are provided in the "Test" subdirectory.
You should use the environment variable "TROMMLER_DRUM_DIR"
to point to this directoy. Use an absolute path and
avoid a trailing "/"!

The following sites provide a good collection of drum samples.

http://spec.ch.man.ac.uk/~ashley/drums.html
http://hem2.passagen.se/lej97/kalava/drumkits.html
http://volftp.tin.it/soundwave/free.html
http://tilt.largo.fl.us/samples/samples.html
http://www.hyperreal.org/music/machines/

Song Description File Format
============================

I have not had time to document the format.
It is an ascii text file and fairly self explanatory.

A test song is  provided in the "Songs" subdirectory.

Glossary
========

Song:
    A sequence of measures. The length of a song is
    its number of measures.

Measure:
    Part of a song. A pattern is assigned to a measure.

Pattern:
    Main object in Trommler describes which drum is played
    at what time.

Drum:
    Percussion instrument that can be played in a pattern.

Range:
    A continuous sequence of measures in a song.

Unit:
   Each pattern is subdivided into units. A unit roughly correspods
   to the numerator of fraction indicating the kind of rhythm use.
   Eg. a Waltz has 3 units, most other songs probably 4.
   The speed of a song/pattern is controlled via the units.

Beat:
  Each unit is subdivided in to Beats.












