_______________________________________________________________________________

README for the cataRT data-driven concatenative sound synthesis system in real time based on unit selection from large databases for Max/MSP/FTM

copyright 2005-2009 Diemo Schwarz, Real-Time Music Interaction Team (IMTR), 
	  	    Ircam--Centre Pompidou

CataRT is essentially based on FTM&Co. by Norbert Schnell et al.,
For more information see http://imtr.ircam.fr

This program is free software; you can use it and/or modify it under the terms of the "Ircam FORUM Libre" free software License.  See files "contrat-forum-2008-v4-LIBRES-FINAL-ENGLISH.pdf" or "contrat-2008-forum-libre.pdf" for further informations on licensing terms.
_______________________________________________________________________________

http://imtr.ircam.fr/index.php/CataRT

DESCRIPTION

The concatenative real-time sound synthesis system cataRT plays grains (also called units) from a large corpus of segmented and descriptor-analysed sounds according to proximity to a target position in the descriptor space. This can be seen as a content-based extension to granular synthesis providing direct access to specific sound characteristics.

cataRT is implemented in MaxMSP using the FTM and Gabor libraries. Segmentation and MPEG-7 descriptors are loaded from text or SDIF files, or analysed on-the-fly.

MANIFESTO

CataRT is offered as free and libre open source software. All I want is some feedback from you. Or in more details:

- CataRT is offered for free, so you can make music and create.

- CataRT is offered as open source software, so you can look into it,
  learn from it, and adapt it to your needs.

- CataRT is offered in the spirit of the GNU General Public License
  (GPL), which means that any modifications you make, or any software
  that uses CataRT in whole or in parts, must be distributed under a
  license in the same spirit also, so the improvements, variations,
  adaptations you make will benefit the community of users.

- CataRT is offered with the wish that you give me some feedback if you
  use it, how you use it, how you would like to use it, why you don't
  use it, and what you use it for in order to learn from it and to
  have arguments for my employer to continue to let me work on CataRT.

QUICK START

0. Preparation:
- Install FTM 2.2.0 or later from http://www.ircam.fr/ftm
- Read the cataRT 7-page article on http://catart.concatenative.net for background information (optional)

1. Setup:
- bang init
- check that "Max Scheduler in Overdrive" and "Scheduler in Audio
  Interrupt" (a.k.a. "takeover") are both on in DSP Status, at least
  for analysis.  For playing, takeover can be off.
- DSP on, augment volume (lower left corner of the main patch)

2. Importing Sounds
- choose segmentation mode and grain size, or use defaults
- click import (soundfile) to choose one or drag one or more sound
  files on either stack of modules (corpus1 or corpus2)
- you can drop any number of files, or whole directories whose contents 
  will be imported (but not recursively)
- if you have opened the corresponding catart.lcd, you can see the file's 
  units coming in during analysis
- after import, reselect the x/y descriptors to refresh the ranges in catart.lcd

3. Playing
- open catart.lcd for your corpus (see also catart.lcd.doc.png)
- move around in lcd, units closest to mouse are played
- drag right/left to increase random-radius
- click to freeze position, click without moving the mouse (maybe twice) 
  to unfreeze (watch the checkbox to the left)
- experiment with different descriptors on x-/y-/colour-axis
- zoom in by changing the min/max underneath the descriptor menu
- try out different trigger modes (except quant and seq that are shaky):
  -- bow triggers closest unit each time you move the mouse
  -- fence plays a unit whenever a different unit becomes the closest
     one (named in homage to clattering a stick along a garden fence)
  -- beat mode triggers units via a metronome (controlled by "grain rate")
  -- chain mode triggers a new unit whenever the previous unit has finished
     playing
  -- quant is a quantized metronome, but non functional for the moment
  -- seq will be the sequencer and external triggering/selection mode
- use the common granular synthesis parameters to the left
  -- xfade and attack/release alternatively control the grain envelope

4. Saving/Loading Corpora
- a whole corpus (list of sound files, descriptors, and unit data) is
  saved by clicking "export" as three text files (.ds.txt, .sf.txt,
  .ud.txt), you can choose any of these or just the base name (keep it
  short, since Max's file dialogs are still stuck with 31 char names).


KNOWN BUGS


MORE INFORMATION

- cataRT page: http://imtr.ircam.fr/index.php/CataRT
- full CataRT doc: http://imtr.ircam.fr/index.php/CataRT_Documentation 
- mailinglist (low volume and spam-free): http://listes.ircam.fr/wws/info/concat
- cataRT extended article: http://recherche.ircam.fr/anasyn/schwarz/publications/dafx2006/catart-dafx2006-long.pdf
- ReleaseNotes.txt: gives more details about changes

- FTM and Gabor page: http://www.ircam.fr/ftm/
- FTM and Gabor wiki: http://ftm.ircam.fr
- SDIF page: http://sdif.sourceforge.net/
- SDIF wiki: http://sdif.wiki.sourceforge.net/


TODO

- so much!

