\begindata{text,538490844}
\textdsversion{12}
\template{help}
\define{global
}


\chapter{Play: Play music on the RT keyboard

}
\section{What play is

}\leftindent{
Play is a module that provides an interface for playing notes on the RT 
keyboard.  The highest level interface  (play_notes) has the same music 
encoding as is used in Advanced Basic for the IBM PC.

}
\section{Starting play

}\leftindent{
You may utilize play either via C code or a Ness script.  For help with C 
coding, see /usr/andrew/doc/atk/music/play.doc.  

}\leftindent{
}
\section{ProcTable Entries}


\leftindent{The following proctable routines are defined by the play module. 
 Only the first is really needed.  For an example, see 
andrew/atk/ness/demos/happybday.d.


\indent{Note:  The names are given as they would be called from Ness, with 
underlines.  The actual entries in the proctable have hyphens instead.}


\bold{play_notes}(code string) 

  

Plays the notes encoded in the string.  The encoding is the same as that for 
Advanced Basic on the IBM PC, and is sketched below.  Example: Happy Birthday 
is played in Ness with:

	play_notes("L8 CC L4 DCF    E P4")

	play_notes("L8 CC L4 DCG   F P4")

	play_notes("L8 CC L4 >C <A  FED P4")

	play_notes("L8 A#A# L4 AF G  F.") 



\bold{play_tone}(freq, duration)  


Plays a tone of the given frequency for the given duration.  'freq' is a 
double float value;  use 0.0 for a rest.  'Duration' is an integer and is 
interpreted as the number of 128'ths of a second.



\bold{play_volume}(vol)  


Sets the volume to 'vol'   (0<= vol <= 9).  Default is 3 for the softest 
audible volume;  which is still pretty loud.



\bold{play_retard}(slow)  


Sets the global retardation  (-30<=slow<=40).   Note lengths are mutliplied by 
(1+slow/50).  Default is 0.



\bold{play_tuning}(letter)  


Chooses one of the available tunings:  EqualTemper, MeanTone, JustIntonation, 
Pythagorean. The 'letter' must be a string constant giving the first letter of 
the tuning name.  The default is "E", but MeanTone is the more usually used.  

}

\section{Codes for play_notes}


\leftindent{In the code string, spaces, newlines, tabs, and other undefined 
characters are ignored.  The letter \italic{x} in each description below is to 
be replaced by an integer.  (In Advanced Basic, the x value can be of the form 
"=variable;", but such codes are ignored in this implementation.)


O\italic{x}		Choose octave.  (Code is upper-case Oh)

		Each octave starts at C and ascends to B

		Middle C is the first note in O3.

		(0 <= \italic{x} <= 6)    Default 4.


<		Change to next lower octave.	

>		Change to next higher octave.


C, C#, D, D#, E, F, F#, G, G#, A, A#, B

		Play the named note in the current octave

		with the current volume and duration.

		C# may be written as C+ or D-

		and similarly for E#, F#, G#, and A# .


L\italic{x}		The length of subsequent notes is 1/\italic{x}

		(1 <= \italic{x} <= 64)    Default 4.

		L1 is whole note;  L2 half note;  L4  quarter note;

		L8 eighth note; L16, L32, L64  etc.

		Non-traditional durations like L7 are accepted.


P\italic{x}		(Pause) rest for length \italic{x}, where \italic{x} is as for 
L\italic{x.}


. 		Dotted note.  When placed immediately after a 

		note, dot multiples its duration by 3/2.

		(multiple dots repeat the multiplication)


T\italic{x}		Tempo.  Sets the number of quarter notes in a

		minute.   (32 <= \italic{x} <= 255)    Default 120.


N\italic{x}		Note.  Plays the \italic{x}'th note on piano  (0 <= \italic{x} <= 
84) 

		n=0 is rest.  Notes 1-12 are in octave 0,

		13-24 in octave 1, ...,  73-84 in octave 6.

		Middle C is note 37.


V\italic{x}		Set relative Volume for subsequent notes.

		(0 <= \italic{x} <= 9)  Default 3.


Mc		Ignored.   (where c is one character)

Xvariable;	Ignored.  

}
\leftindent{
}
\section{Program Author}

\leftindent{
Wilfred J. Hansen.  The design of the codes is taken from Advanced Basic.}


\section{Related tools}  


Select (highlight) one of the italicized names and choose "Show Help on 
Selected Word" from the pop-up menu to see the help file for:


\leftindent{\italic{nes}}s

\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,662,0,0}
Copyright 1992 Carnegie Mellon University and IBM.  All rights reserved.

\smaller{\smaller{$Disclaimer: 

Permission to use, copy, modify, and distribute this software and its 

documentation for any purpose is hereby granted without fee, 

provided that the above copyright notice appear in all copies and that 

both that copyright notice, this permission notice, and the following 

disclaimer appear in supporting documentation, and that the names of 

IBM, Carnegie Mellon University, and other copyright holders, not be 

used in advertising or publicity pertaining to distribution of the software 

without specific, written prior permission.



IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS 

DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT 

SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER 

BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY 

DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 

WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 

ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 

OF THIS SOFTWARE.

 $

}}\enddata{text,538490844}