.\" to print this man page on lgp: ltroff -2 CW -man pianoroll.c
.TH PIANOROLL 1carl CARL
.SH NAME
pianoroll \- CARL score analysis program
.SH SYNOPSIS
.B pianoroll
[
.B -g
] [
.B -m
] [
.B -M
] [
.B -x
] [
.B -y
] [
.B -d
] [
.B -b
] [
.B -e
] [
.B -s
] [
.B -h
]
< input.sc > output
.SH DESCRIPTION
flags: (default)
.TP
.B -g
y axis grain size (.1)
.TP
.B -m
minimum value on x axis (0)
.TP
.B -M
maximum value on x axis (1000)
.TP
.B -x
P field to display on x axis (6)
.TP
.B -y
P field to display on y axis (2)
.TP
.B -d
P field to determine duration (4)
.TP
.B -b
display score starting at time (0)
.TP
.B -e
display score until time (infinity)
.TP
.B -s
also show sum of x values
.TP
.B -h
displays this summary
.PP
.B pianoroll 
reads a standard 
.I cmusic
score file, and creates a 
graphic display of the score on its standard
output in pseudo-pianoroll notation.  The graphic format utilizes standard
teletype characters.
By default, it displays time (P2 and P4) along the y axis (as does a piano roll)
and frequency (or whatever is in P6) 
along the x axis.  Duration of a note (P4) is displayed by the 
vertical length of the line.
.SH The Flags
The
.I g
flag sets the ``grain'' size (0.1), which is the y axis quantization.  This 
ordinarily means 
how much time passes for each line of the pianoroll drawn.
The
.I m
and
.I M
flags determine the minimum (0) and maximum (1000)
values respectively that will be
displayed on the x axis.
The
.I x
and
.I y
flags set which P fields (P6 and P2 respectively) 
to sample for the x and y axies.
The
.I d
flag specifies the P field used to determine the duration of the note.
.I b
and 
.I e
determine the begin and end points of the score to be displayed.
The
.I s
flag is used to display the sum of the values of the P field being shown
in the x axis.  This is useful e.g., to view amplitude flucuations
through time.  See below.
.SH The Display
.KS
Here is an example display.  It is a bit illegible because it demonstrates
several features of the display for pathological cases.
.sp
.nf
.ft 2
       [0.000_________i______________I______________i_____1000.000]
  0.000:    c    c  c   c  c                                     
  0.100:    |    |  |   |  |                                 n    
  0.200: c c21c  |r | r | x| x                               |   >
  0.300: | ||||   |   |   |  |                               |   |
  0.400: | |7||   |   |   |  |                                   |
  0.500:<| ||||   |   |   |  |                                  x 
  0.600:|| |*||  n  c   n  c                                    | 
  0.700:|| ||||  |  |   |  |                                    | 
  0.800: | ||||  |  |   |  |                                      
.ft P
.KE
.fi
.PP
The beginning of a note is represented 
by the first character of its name, at the appropriate location in the x axis.
Thus, at time 0, a chord using an instrument whose first character is 'c'
is played.  At time .1, the chord is continued, and voice 'n' enters near
1000Hz.  At time .2, several things happen.  Instruments 'r', 'c', and 'x'
enter.  The numerals '2' and '1' indicate that more than one instrument were
active within the character position for that time/frequency quantum.  What
is represented is the number of collisions.  If the number exceeds '9', e.g.,
at time .6, a '*' (meaning ``many'') is printed.  At time .2 and .5, the
freqency of the notes being played went off scale, and this is represented by
\'<' and \'>'.  
Note that the duration of the off-scale event(s) 
is still recorded.  If it is desired to disambiguate the '*'s and \'<'s, 
use a smaller grain size  and/or an expanded x axis range.
.SH Score Format
The score must have the value to be displayed in the y axis (P2) sorted in
monotonically increasing order.  All statements besides those beginning
with the three characters ``not'' are ignored.  (``note'' is also accepted.)
.PP
P fields may contain constant arithmetic expressions
governed by the same rules applied to 
.I cmusic
expressions.  However, 
.B pianoroll
has no knowlege of variables, strings, macros, or P field substitution.  These
must all be evaluated prior to handing the score to pianoroll.
The most convenient way of doing this is to run the score through 
.I cmusic
with the statement
.RS 5i
set barefile = filename;
.RE 
at the top.  A copy of the score with all expressions, macros and variables
expanded and substituted will be produced in the named file.
(
.I cmusic
still produces all the sample data this way.  If you just want the barefile,
try running with a reduced sampling rate, do-nothing instruments, and the
like.)
.SH Alternate Techniques
.B pianoroll
will allow any P fields to be substituted for P2, P4 and P6.
This can be useful for viewing non-standard scores, or for plotting
any parameters against each other.
.PP
One very useful approach is to show amplitude vs. time.  If amplitude is
represented by P5, you would use flag -x5.  Since amplitudes are typically
between 0 and 1, you would rescale the maximum x range with -M1.  What
one is usually after here is to see the sum of the amplitudes to detect
where it might be overflowing.  The -s flag turns on a feature that adds
the display of the sum of the P fields active during that quantum.
Plus signs, '+' are used to show the sum.
.PP
.KS
Here is a score, showing amplitude through time.
.sp
.nf
.ft 2
       [0.000_________i______________I______________i________1.000]
  0.000: 1cc   c       +                                          
  0.100: 311   1       +                                          
  0.200: 733   3                       +                          
  0.300: |||   |                       +                          
  0.400: |||   |                       +                          
  0.500: |||   |                       +                          
  0.600: 1cc   c       +                                          
  0.700: |||   |       +                                          
  0.800: |||   |       +                                          
  0.900: 1cc   c       +                                          
  1.000: |||   |       +                                          
.ft P
.KE
.sp
.fi
As we can see, most amplitudes in this example are below 0.1.  The maximum
sum is about .45 at time 0.3, where there are 16 voices active.
.PP
More exotic possibilities are obtainable this way.  For instance, how
about a plot of frequency vs. amplitude?  
.SH AUTHOR
Gareth Loy
.SH SEE ALSO
cmusic(1carl)
.SH DIAGNOSTICS
Notes out of monotonic order are reported and skipped.
Requesting display of a P field that does not appear is reported and
skipped.  If a P field cannot be numerically evaluated, it is skipped.
.SH BUGS
Remembering that when instruments collide in a quantum, the NUMBER of
instruments in that quantum is recorded rather than the first character
of a name; it becomes clear that it is not a good idea to name your
instruments beginning with numbers.
.PP
A limit of 128 P fields can be handled.  
.PP
Where two values collide in a quantum, if -s is turned on,  the colliding
values are kept track of as one.   The amplitude calculated is still
correct, but it may not reamin correct.
If one of the colliding notes ends sooner than the other, its amplitude
is not subtracted until all notes occupying that quantum have ended. 
Thus, false peaks may appear in very dense sections.  However, expanding
the x axis, and/or decreasing the grain size until the collision is
avoided will reveal the correct amplitude.
