|
Manual
Programmers may wish to read the Javadocs
for the musical agent if modifying the source code.
1. Requirements
The Musical Agent application requires the Java
2 V1.3 runtime environment be installed on the computer. The
agent uses multicast IP to communicate with other musical agents
and so the computer must also be setup to allow for this. The author
has tested the application on a Win 98, Win NT and Linux environment.
All the recent versions of these operating systems come configured
with multicast support straight out of the box. The network must
be also properly configured to route multicast datagrams. If the
agent is to participate in a group performance with other musical
agents over the Internet, there must be routers between the computers
that properly route multicast datagrams. Since there are some old
routers still in use that are not IPv6 compliant, this creates multicast
islands where multicast datagrams cannot be transmitted from one
island to another. A MIDI device is required if the user wishes
to hear the performance. However, the agent can still contribute
to a performance if a MIDI device is not available.
2. Downloading an Agent
The agent can be downloaded from here.
3. Running the Agent
Assuming that the Java runtime environment directory is within
the search path, typing the below command on the prompt will start
the agent.
java -jar MusicClient.jar
On a Windows system, double clicking on the MusicClient.jar file
will automatically execute the application.
4. Configuring your Agent
The ‘character.ini’ file is used to configure the agent as required.
Below is a table of configurable parameters and some examples.
|
Parameter
|
Description
|
Example
|
|
breath
|
Specifies how long this agent can hold its breath.
|
6
|
|
id
|
A unique identifier that distinguishes this agent from others.
This must be one word.
|
ruki
|
|
agentis
|
If the agent is specified as a spy, you can listen to the
whole performance. This parameter may be ‘spy’ or ‘nospy’.
|
spy
|
|
multicastip
|
Specify the multicast IP address to use.
|
239.1.2.3
|
|
port
|
Specify the port number to use.
|
1234
|
|
ttl
|
Specify how far the datagrams should travel. ttl = 0 Restricted
to host tt1 =1 Restricted to same subnet tt1 < 32 Restricted
to same department ttl < 128 Restricted to same continent
ttl < 255 Unrestricted.
|
1
|
|
script
|
Specifies the music script file to be performed. All script
files must be in the ‘scripts’ directory.
|
paragraph7.bsh
|
| splash |
Specifies whether the splash screen should be displayed during
start up. This parameter can either be 'yes' or 'no'.
|
no |
|
/
|
This is a comment and will be ignored.
|
/ this is a comment
|
5. Using the Agent
Once the splash screen has been displayed, the
above window will appear. On the status area will be displayed all
the agents participating in the performance. Once all agents are
registered as part of the performance, that is they all appear on
the status area distinguishable by their MemberID, the nominated
leader can press click the ‘start singing’ button. This will switch
all agents from pinging to singing mode. If your agent is configured
as a spy (see configuring your agent) you will hear the performance.
Sending Chat Messages
To send a text message to all agents, write the message in the textbox
and then press the 'enter' key. Your message will appear all agents'
chat area.
Recording a Performance
This feature is only available if there is a MIDI device on the
host computer. Pressing the 'record MIDI' button will begin capturing
all MIDI events. Pressing on the button again, which will have been
renamed to 'stop', will stop recording. To save the recording to
a MIDI file, press the 'Save MIDI' button and enter a filename.
6. Writing Music Scripts
All script files must be placed in the ‘scripts’
directory. To specify a script to be performed by the agent, see
‘configuring your agent’. All script files must end with
‘.bsh’. The script files are written in Java syntax with the exception
of some rules.
- It is not required to declare variables
- Variables are perl-like. They change their type automatically
depending on the object they are storing. (x=5 makes x an integer
while x=5.5 make x a float)
- No need to write a class with a main function. Any code within
the script file will be executed.
To make maximum use of the script language, refer
to the BeanShell document at http://www.beanshell.org/docs.html.
Below is the set of instructions available to the user that can
be used within the script files.
|
Function
|
Description
|
|
cmd.Inform()
|
Informs all other musical agents the status of this agent.
(that is its note, duration, instrument, breath and volume)
|
|
cmd.WaitForLeader()
|
Put the agents in pinging mode until one agent from the
performance is instructed to start singing.
|
|
cmd.Print(String str)
|
Prints the string out to the console.
|
|
cmd.Sleep(int duration)
|
This is a blocking function that stops all processing for
the duration specified.
|
|
cmd.PlayNote(int note, int duration, int velocity, int instrument)
|
Plays a note on the MIDI device. If all 16 channels are
already allocated to an instrument and a new instrument is
specified, that note will be played on the 16th
channel.
|
|
int cmd.Breath()
|
Returns an integer, the breath parameter specified in the
character.ini file.
|
|
int cmd.Random(int min, int max)
|
Returns a random integer that is between the range min and
max (both inclusive).
|
|
int [] cmd.GenerateRandomNums(int min, int max, int num)
|
Returns an array of random integers, all between the range
min and max (both inclusive). All numbers in the array will
be unique unless the range is not sufficient enough to generate
unique numbers.
|
|
boolean cmd.NumIn(int [] nums, int val)
|
Checks whether the number val is in the array of integers
nums. Returns true if it is otherwise false.
|
|
int cmd.LoudestNote(int ignoteNote)
|
This function returns an integer that is the pitch of the
note being sung by an agent. The user can specify a note or
notes to ignore. If all the notes being sung at the moment
by the agents are in the ignore list, 0 will be returned.
|
|
int cmd.LoudestNote(int [] ignoreNotes)
|
|
int cmd.SoftestNote(int ignoreNote)
|
|
int cmd.SoftestNote(int [] ignoreNotes)
|
|
int cmd.RandomNote(int ignoreNote)
|
|
int cmd.RandomNote(int [] ignoreNote)
|
|
int cmd.CurrentNote()
|
This will return an integer, the pitch of the note being
sung by the agent.
|
|
Object [][] cmd.ReadIntoArray(String filename)
|
Loads in a text file from the filename specified and returns
a 2-dimensional array of Objects. This function will interpret
the data as either a Double or a String. The file format of
the text file is as follows: 2,3 "french fries",
5, 5.95 "pizza", 2, 1.95
|
The below functions all deal with the following
MemberList class structure.
public
class
MemberList
{
public
String ID;
public
int
NoteSung;
public
int
LineAt;
public
int
Breath;
public
short
Volume;
public
short
Duration;
public
short
Instrument;
}
|
int cmd.MembersNum()
|
Returns the number of members this agent has.
|
|
MemberList cmd.ReadInfo(int index)
|
Returns a member’s information (see MemberList structure
above) at the index specified. Information of the members
are stored in an array. Use the cmd.MembersNum() function
to first work out the number of members in the array.
|
Example music script
The sample music script demonstrates some of the
above functions. Included in the script directory can be found more
sample music script files.
velocity=127;
note=20;
instrument1=cmd.Random(30,60);
instrument2=cmd.Random(100,127);
cmd.WaitForLeader();
duration=cmd.Random(1000,2000);
increase=true;
while(true)
{
cmd.Inform();
cmd.PlayNote(note,duration,velocity,instrument1);
cmd.Sleep(duration/2);
cmd.PlayNote(note,duration,velocity,instrument2);
cmd.Sleep(duration/2);
if(increase)
note=(cmd.LoudestNote(0)
+ 1) % 127;
else
note=(cmd.SoftestNote(0)
- 1) % 127;
velocity=cmd.Random(120,127);
if(note>=60)
increase=false;
if(note<=15)
break;
}
|
