-----------------------------
Introduction
-----------------------------
 
Aleatoric is a tool for musical composers and programmers collaborate to create aleatoric musical scores and software ensembles of performers to perform them.  Performances result in a rendered sound file.  As in real-world aleatoric music, composers define musical events and provide performance directions, and performers interpret the directions, perform the score and thus realize the composition.

The most important design goals of Aleaotoric are:
 * To provide musical composers with a simple, natural and intuitive language to define musical events and performance instructions
 * To provide programmers with an intuitive, simple, powerful and extendable framework for creating software performers to realize the score
 * To allow each to collaborate with the other using a separate language they are comfortable with, needing only to understand and agree upon the meaning of the score's performance instructions, which can be named and described using any words or sentences the composer chooses. (This borrows an idea from Behavior Driver Software testing, see cucumber at http://github.com/aslakhellesoy/cucumber/tree/master as an example if you are interested.) 

Composers use Aleatoric's musical score language, called Composer.  Composer is a simple and clear language for specifying musical notes, organizing notes into phrases or measures, specifying software ensembles of performers, and adding written instructions for those performers to follow.  There are also instructions to render the performance into a sound file.
 
Programmers write the code that performs the score and generates a sound file in the Ruby programming language, using the framework provided by Aleatoric.

When score and performance code are complete, Aleatoric combines them to create the final sound file performance.

-----------------------------
A Simple Example
-----------------------------
 
Here is a simple example of a Composer score:
 
  player "Player 1"
	  phrase "Intro Phrase"
	    note "1"
	      instrument  1 
	      start       0.0 
	      duration    0.5
	      amplitude   1000
	      pitch       7.01
	    note "2"
	      instrument  1
	      start       1.0 
	      duration    1.0
	      amplitude   1100
	      pitch       7.02

  instruction "How to play it"
    description "Play these notes repeatedly and unsteadily, at whatever tempo you desire."
		players "Player 1"
  
  repeat until "It's time to stop"
		play
			players "Player 1"
 
  render "my_composition.wav"
    phrases   "Intro Phrase"
    format    csound
    orchestra  "my_csound_orchestra.orc"
 
This score defines two notes as part of a phrase "Intro Phrase." The resulting performance renders them to an audio file.  

This example also shows the core performance features of Composer.  "Player 1" is assigned "Intro Phrase" and is in the list of players under play, so this player plays this phrase.  The instruction command describes how "Player 1" should play, and the repeat until command tells the player when to stop.  These two commands will control the performance using separate code written by the programmer who is collaborating with the musical composer.

Note also the consistent and simple syntax of the language.  Indentation is optional, but should be used to show structure.  For example, we see that each 'note' is part of the 'phrase,' and each line indented under each note defines an attribute of the note.  

In this example, rendering is done using the cross-platform electronic music composition software CSound.  At this time, Aleatoric supports rendering to either MIDI or CSound, and runs on Windows and Mac.
 
-----------------------------
Documentation and Examples
-----------------------------
 
For a complete overview of the Composer language, for both musical composers and programmers, see the language documentation and examples here: http://wiki.github.com/marksweiss/aleatoric/

For programmers implementing ensembles to perform scores, there is the documented Aleatoric Ensemble API.  There is also a non-trivial reference project, a realization of Terry Riley's "In C," which includes:
 * a score
http://github.com/marksweiss/aleatoric/blob/master/compositions/Terry_Riley-In_C/in_c.altc
 * an example software ensemble that performs it
http://github.com/marksweiss/aleatoric/blob/master/compositions/Terry_Riley-In_C/In_C_midi_user_instruction.rb
 * two example performances
http://github.com/marksweiss/aleatoric/blob/master/compositions/Terry_Riley-In_C/In_C__perf_1.mid http://github.com/marksweiss/aleatoric/blob/master/compositions/Terry_Riley-In_C/In_C__perf_2.mid  

Also, documentation generated from the Aleatoric API code is here (in progress):
http://github.com/marksweiss/aleatoric/tree/master/doc