Rhythm estimator for Pd
=======================

This is a collection of Pd objects for doing rhythm (quantum)
estimation.

This text corresponds to release 0.1 of rhythm_estimator as of 22
June, 2000.  This release of rhythm_estimator has been tested with Pd
0.30.

Rhythm_estimator is distributed under the GNU General Public License.

Contents
--------

The package consists of the following Pd objects:
* "rhythm_estimator.pd" - Pd patch implementing the algorithm
* "rhythm_estimator_example.pd" - an example usage of rhythm_estimator
* "rhythm_ioi_histogram.pd_linux", "rhythm_quantum.pd_linux" and
  "rhythm_slave_metro.pd_linux" - Pd externs implementing parts of the
  algorithm
* "bang-eater.pd", "drumboy~.pd", "drunk-metro.pd" and "ping~.pd"
  - subpatches used in the rhythm_estimator_example patch

Installation
------------

The pd libraries and the rhythm_estimator subpatches are all installed
in the extras/rhythm_estimator subdirectory in the Pd directory tree.
The installation is carried out with the "configure", "make" and "make
install" commands as usual.  If "configure" doesn't find the Pd
installed on your system, you can select it by hand by giving
"configure" the option "--with-pddir=YOUR_PD_DIRECTORY", for example
"--with-pddir=/home/pd/pd-0.30".  See INSTALL for more precise usage
information.

Operation
---------

The rhythm_estimator patch accepts bangs, which represent sound onset
events, and produces a metrical grid, a "metronome" of the shortest
time pulse present in the onset stream.  The onsets are taken in the
first inlet and the metrical grid is sent in the first outlet.

Rhythm_estimator consists of 3 subobjects, which are implemented in
C.  The subobjects are rhythm_ioi_histogram, rhythm_quantum and
rhythm_slave_metro.

The rhythm_ioi_histogram object generates a histogram from the
inter-onset intervals (IOI's) of the incoming onset stream.  The
histogram is saved in a Pd array, represented with the "table"
object.  Rhythm_ioi_histogram sends a bang on every onset, which
causes the histogram content to change.

The rhythm_quantum object accepts the histogram generated by
rhythm_ioi_histogram and attempts to find the most prominent quantum
(quantization step) period from the IOI's.  Rhythm_quantum accepts
also bangs from rhythm_ioi_histogram, which tell when to recompute the
quantum.

The last object in rhythm_estimator, the rhythm_slave_metro, accepts
the original onset stream and the estimated quantum duration from
rhythm_quantum.  It produces a stream of bangs with an average period
specified by the quantum duration, but which is synchronized to the
incoming onsets.

The algorithm operation is discussed in more detail in the supplied
"cama99.ps" technical paper.  The paper can also be downloaded from
the algorithm home page, with the link as given below.

Parameters
----------

There are numerous parameters for the algorithm, all of which can be
changed with the "set" message to the second inlet of
"rhythm_estimator".  The second inlet accepts also a "print" message,
which then prints all parameter values.  See the
"rhythm_estimator_example" patch and the source code for parameter
details.

The second outlet of "rhythm_estimator" sends out the quantum duration
in milliseconds during the estimation process.

Links
-----

For more information about the rhythm estimator algorithm, see
http://www.cs.tut.fi/sgn/arg/music/jams/.  For more information about
Pd, see http://iem.mhsg.ac.at/pd/.

Jarno Seppänen <jams@cs.tut.fi> and Piotr Majdak <p.majdak@bigfoot.com>
