Andante
=======

0.1.1 - Initial version (still a prototype) - Not documented yet!
http://gsd.ime.usp.br/andante

README - compilation and execution instructions
------

The system is currently in a prototype stage, so it is difficult to
compile and run it. We will strive to release a better version as soon
as possible.

Feel free to contact us through the URL above.

* Required software

  - Java 2 SDK, Standard Edition v1.4 (J2SDK)
    http://java.sun.com
  - Aglets 2.0.2
    http://aglets.sourceforge.net
  - Apache Ant 1.5.4
    http://ant.apache.org/

  The system was tested on Linux (2.4.21) and Mac OS X. The following
  are instructions for compiling and execute the system on these
  environments.

* Compilation

  Open a terminal and uncompress and extract the tar file by entering
  the following command:

    $ tar zxvf andante-0.1.1.tgz

  Change to the directory named 'andante-0.1.1':

    $ cd andante-0.1.1

  Compile:

    $ ant

  The compiled classes will be in the directory 'andante-0.1.1/build'.

* Execution

  First of all, run the CORBA Name Server (included in the J2SDK):

    $ tnameserv -ORBInitialPort 1050

  (The Name Server will be listening on the port 1050.)

  From now we will assume that the sources were extracted to the
  directory '/home/user/andante-0.1.1' and the Aglets package is
  installed in '/home/user/aglets'.

  In order to run the Aglet-based parts of the system, we need to use
  the shell script 'asd' located at '/home/user/andante-0.1.1/classes'. 
  Edit this file and change the part that looks like the following:

    # Set this to your installation directory
    AGLET_HOME=/home/user/aglets
    JDK_HOME=/usr/local/j2sdk

  to match your own directories (AGLET_HOME should be where you
  installed the Aglets and JDK_HOME where your J2SDK is).

  For Mac OS X users, the JDK_HOME variable should be something like

    /System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home

  Alternatively, you may use the system environment variables (and leave
  the variables in the script unset).

  To run any Andante application or infra-structure element, you need
  to change to the directory '/home/user/andante-0.1.1/build'.

  Now you may run one or more Stages, each one uses one port. So
  you may run more than one Stage in the same machine, provided you
  choose distinct ports. To run one Stage, open another terminal and
  type the following:

    $ ./asd andante.Main -daemon -port 4444 \
      -ORBInitialPort 1050 -ORBInitialHost villa
  
  Please note that the parameters 'ORBInitialPort' and 'ORBInitialHost'
  refer to the Name Server: the value '1050' is its port and 'villa'
  is the name of the machine in which it is running. You should change
  this values accordingly.

  After running one or more Stages, we need to run an application that
  creates/manages Musical Agents. One way is to use the Tahiti interface
  included in the Aglet package. For this we need to create a symbolic
  link from the directory where the Tahiti looks for the Java classes
  to the directory where the Andante classes are:

    $ ln -s /home/user/andante-0.1.1/build/andante \
      /home/user/aglets/public/andante

  (This is done only once.)

  You may now run the Tahiti interface, but the class andante.Main 
  already does that. Just run one of the stages without the '-daemon'
  option:  

    $ ./asd andante.Main -port 4445 \
      -ORBInitialPort 1050 -ORBInitialHost villa

  Use the Tahiti to create and dispatch Musical Agents to a Stage.
  To create, click on "Create" and fill only the field "name" with, for
  example, "andante.apps.noiseweaver.NoiseAgent". To dispatch, select
  the agent, click on "Dispatch", and fill the "Destination URL", for
  example, with "atp://villa:4444".

  Finally, you may run an Andante application, the NoiseWeaver:

    $ java andante.apps.noiseweaver.NoiseWeaver

  An initial window will show the running stages. You may select one stage
  and click on "Manage". A new window will allow you to control the agents
  hosted on this stage. The list on the the "Agents" pane shows the agents.
  By selecting one agent, the pane on the right side of the window will
  allow you to see and change the agent's properties (change a property and
  click on "Set"). The pane will also allow you to make the agent start or
  stop playing (click on the "Start" button).

* Running the demonstration Applet

  The classes andante.test.SocketAdapter and andante.test.SAApplet are a
  simple example of how an Applet can communicate with an Andante agent.
  
  The SocketAdapter first finds an Andante agent in a CORBA name server.
  It then opens a socket on a port specified on the command line. The
  messages (strings) received through the socket are translated to CORBA
  messages and sent to the Andante agent. This version of the SocketAdapter
  only translates the following messages of the Andante agent interface:

   - start;
   - stop;
   - setProperty property value.

  The SAApplet opens a socket to a running SocketAdapter and then allows
  the user to send messages (strings) to it.

  To run this example, you need also to run the Andante infrastructure, and
  to create and dispatch an agent. Here are some quick steps, but you may
  follow the instructions above (section 'Execution') if you encounter
  problems.

   - Open a terminal and run the name server on port 1050:

     $ tnameserv -ORBInitialPort 1050

   - Open another terminal in the same machine, enter the directory 'build'
     of the Andante directory, and run a stage on port 4444:

     $ ./asd andante.Main -port 4445 -ORBInitialPort 1050

     This will also open the Tahiti GUI.

   - Use the Tahiti GUI to create an "andante.apps.noiseweaver.NoiseAgent" and
     dispatch it to "atp://localhost:4444".

   - Open another terminal and run the SocketAdapter on port 5000:

     $ java andante.test.SocketAdapter 5000 -ORBInitialPort 1050

     (The port must be the first parameter.)
     
     The SocketAdapter should find the agent created on the previous step.

   - Run the SAApplet using another terminal:

     $ appletviewer saapplet.html

     or open 'saapplet.html' using a web browser.

  With these steps, the messages sent by the applet are resent to a NoiseAgent.
  The 'setProperty' message may be sent to change the NoiseAgent properties.
  The supported properties (of this specific agent) are:

    PROPERTY             VALUES                            DEFAULT

    PitchGenerator       Pink, Brown, White, Constant      Pink
    IntensityGenerator   Pink, Brown, White, Constant      Pink
    IntensityMax         0 to 127                          110
    IntensityMin         0 to 127                          80
    DurationGenerator    Pink, Brown, White, Constant      Pink
    DurationMax          positive integer                  5
    DurationMin          positive integer                  1
    Channel              0 to 15                           1
    Instrument           0 to 127                          1
    Scale                Diatonic, Chromatic, Pentatonic,  Diatonic
                         HarmonicMinor
    ScaleStart           0 to 127                          60
    ScaleLength          positive integer                  14

  For example, to change the IntensityMin property to 50, fill the "Message"
  field with 

   setProperty IntensityMin 50

  and click on "Send".