\documentstyle[12pt]{article}
\newcommand{\xm}{{\bf XMusic\ }}
\renewcommand{\thesection}{\Roman{section}}
\title{Some Hints On Using \xm}
\author{George Drapeau}
\begin{document}
\maketitle

During the Spring of 1988, I was doing some research in computer music
at the School of Music at USC.  At that time, the music school was
moving toward the creation of a Music Techonology curriculum that
would require every music major to take at least one class involving
computers.  The curriculum also would provide for a series of classes
focusing on electronic and computer music.  Since USC already had in
place a large network of Sun workstations, I decided to develop a
computer music environment around the Unix environment, using the X
Window System as the windowing environment.  I used the Csound music
compiler written by Barry Vercoe at MIT's Media Lab; however, I
believe that the method of composition will be too difficult for many
of the musicians to learn.  To compensate for the relative difficulty
of learning to program Csound, I have written a front end for Csound.
The program, \xm , runs under X and allows the user to graphically
create instruments that later will be written into a Csound file for
compilation.  I have finished the X11 version of the program, having
ported it from the older, X10 prototype version I completed in June of
1988..  The following should help get you started on XMusic.

\section{A Brief Csound Introduction}
Csound is a music compiler in the MUSICx family of languages, and
consists of two parts --- an instrument file, in which instruments are
defined, and the score file, which contains information about which
notes are to be played by which instruments.  The user creates each of
these files; together they form a composition.  Csound then compiles
both of these files and produces a sound file which can be played
through a digital--to--analog converter for listening purposes.

Csound compositions are programs; the language allows for mathematical
statements, flow--of--control statements, variable assignments, etc.  Most of
this aspect of Csound does not appeal to the musician who is not computer
literate, however, and even though the musician may be familiar with the
concepts of electronic music, s/he may not be able to use Csound effectively.
My approach to writing \xm was to design a tool that lets the user build a
signal path, so that by looking at an \xm diagram, the user can easily tell
the origin of a signal and see the signal modifiers in that path.  For more
advanced users, \xm can still be used to create a first draft of a Csound
instrument file, then s/he can edit that file with any text editor, just as
s/he would have done without the existance of \xm. 

\section{Using \xm}
To begin using \xm, you should be running at least Version 11, Release
3 of the X Window System, available from MIT.  Assuming that you are
running under the X environment, all you need to do to run \xm is to
type ``xmusic'', or if you wish to work with an \xm diagram you had
previously saved, type ``xmusic {\it diagramname}''.  X will prompt
you for a window size and position.  Hitting the right button will
bring the default size and place for the \xm windows.

\xm uses three primary windows.  The largest of these is 
the main drawing window, where you place tools and connect them to
form instruments.  I call the drawing window the \xm window.  At the
top of the {\xm} window there is a row of command buttons.  These
buttons represent a few common operations you would perform on tools
and the diagram as a whole.  The next largest window is the Help
window.  It gives you a synopsis of the commands available to you, and
gives you a little help on how to move, connect, select, and
disconnect tools.  The third window, usually to the left of the \xm
window, is the ToolPalette window.  As of now there are seven types of
tools; in the future, I would like to add at least one more tool type,
that tool type being a Multiple, so that tools can have multiple
outputs.  To simplify the creation of instruments, currently a tool
can have only one output.  I think that a Multiple will be a solid
addition to \xm .

Creating an \xm diagram is fairly simple.  To place a tool in the
diagram, move the mouse to the ToolPalette window and click the left
button on the tool you want.  Then move the mouse into the \xm window,
and click left button again where you want to place the tool.  To
connect two tools, point to one tool in the \xm window and click the
left button; the cursor will change shape to let you know you've
selected a tool to connect.  Then click left button on the tool you
wish to connect the first one with.  If the output of the top tool is
unused and there is at least one input on the bottom tool unused, the
tools will be connected okay, otherwise nothing will happen and you'll
get an error message on stdout.

Remember, an \xm diagram is read from top to bottom, so outputs of tools come
out of the bottom and inputs feed into the tops of tools.  This will determine
the placement of your tools, so keep that in mind.

If you wish to sever a connection between two tools, point to one of the tools
and click right button on it, then point to the second tool and also click
right button on it.  If these two tools were not connected, you'll get an
error message on stdout.

To move a tool you've already placed in the diagram, point to it and click
middle button.  Again, the cursor will change shape until you've moved to the
new place for the tool.  Click any button to move the tool.

\section{Tool Types}
There are several types of tools in the ToolPalette window.  Technically, any
tool type can serve any function, but it would be wise to use the tools as
they are described here.  There are:

\begin{enumerate}

\item {\bf SineTools}, which correspond to the `oscil' functions in Csound, plus a
few others;

\item {\bf EnvTools}, which are supposed to be used as envelope generators.  The
Csound functions that are most applicable here are the `linen' functions;

\item {\bf SumTools}, the triangular tools.  SumTool takes up to eight tools
as input; the value of its output is the sum of the inputs' values.  The
default operator for a SumTool is addition, but that can be changed to
subtraction, multiplication, or division;

\item {\bf AmpTools}, which currently correspond to the Csound `gain' set of
functions, and those related to it;

\item {\bf ParamTools}, which allow instruments to have inputs from the score
file of a composition.  As I described earlier, Csound performances are made
up of two files.  \xm only deals directly with the instrument file; however,
instruments get their cues to be played from the score file, and sometimes a
parameter in the score file can determine, for example, the frequency of a
SineTool.  ParamTools are the mechanism that allows the user to specify the
name of the parameter in the score file that will control a tool.  Using
parameters from the score file is described more completely in the Csound
manual.

\item {\bf NoiseTools}, which correspond to the `rand' series of Csound functions;

\item {\bf EQTools}, which allow users to type any equation or text string and
associate that with an instrument.  Usually an EQTool would not have inputs,
but if it did, those inputs would most likely be ParamTools.
\end{enumerate}

\section{The Information Window}
By pressing the command button labeled ``Inspect a Tool'', you can get
information about any tool in the {\xm} window.  When you press the
button, a window appears next to the tool.  This window is called the
Info Window.  The Info Window shows all the relevant information about
a tool, including the tool type (as I've enumerated earlier), the name
of the tool, the control rate of the tool, the Csound function
corresponding to this tool, and all the arguments to that Csound
function.  By clicking a mouse button on one of these fields, you can
change the value of that field.  Another window will appear, asking
you for the new value of that field.  The exception is the Control
Rate field, which simply toggles through the three acceptable values
to Csound.  Try it and see.

\section{Saving an \xm Diagram}
To save the \xm diagram you've created, just press the ``Save
Diagram'' command button.  A message will appear on stdout saying that
you've written an \xm file.  This is not a Csound instrument file, but
rather is a ``picture'' that you can retrieve later, as I described at
the beginning of this document.

Exiting \xm will also save the diagram if any changes have been made
to it.  When you press the ``Quit'' command button, a small window
asks you to confirm your choice to exit the application.  If you
confirm the choice to exit, \xm will save the diagram you have created
in a file called `orch.xm' which you can recall later.  However, if
you have not made any changes to the diagram since the last time you
saved it, or have not added anything to a newly--created \xm session,
then \xm will not save the file.  If there is already a file called
`orch.xm' and you choose to save the diagram, the old `orch.xm' file
will be overwritten.

\section{Creating a Csound Instrument File}
When you are ready to try to compile your instruments, press the
``Write Csound File'' command button to create a Csound file from the
\xm diagram.  \xm will compile your diagram into a text file that can
be fed into the Csound instrument compiler.  There may be some syntax
errors --- \xm does not check your diagram for correctness --- but
simple diagrams that have no unusual structures should compile just
fine.  Again, try it and see what happens.

\section{Conclusion}
I no longer attend USC, and so am not in a position to be doing much
work in computer music (I have a real job now), so the changes to
XMusic will likely be slow in coming.  However, I would be interested
in hearing suggestions you might have about the program.

When I was at USC, I was working with a Synclavier for a while, but it
became frustrating because everytime you wanted to get some new
synthesis capability, you had to buy this expensive software from New
England Digital.  I began to think that it was almost worth it just to
write a synthesizer in software on a Sun and buy a digital to analog
converter for it.  That was when I found Csound, which solved a lot of
the problem, but the language became a barrier.  This is how {\xm}
came to be.

I hope this document was helpful in giving you an idea of what {\xm}
is all about.  If you have questions about it, I'd love to answer
them.  You can always send me electronic mail to
\begin{description}
\item[{\bf drapeau\@jessica.stanford.edu}]

or
\item[{\bf \{sun,usc,uunet\}!jessica.stanford.edu!drapeau}.]
\end{description}

Thank you for taking the time to look this over.  If you have any comments,
let me know.  I'd be glad to hear them.
\end{document}