.TH CHED 1 "MIDI"
.SH NAME
ched - edit MIDI file graphically
.SH SYNOPSIS
.B ched
[\fB-B\fP#]
[\fB-b\fP#]
[\fB-d\fP]
[\fB-m\fP#]
[\fB-t\fP#]
file
.SH DESCRIPTION
.I Ched
produces a graphic rendition of a MIDI file that is, in many ways,
similar to a score (or a piano roll on its side) and lets you edit it.
Like a score, there are treble and base staves.
The treble staff is the one usually associated with the G clef; it has
horizontal lines at E4, G4, B4, D5, and F5.
The bass staff is the one usually associated with the f clef; it has
horizontal lines at A3, F3, D3, B2, and G2.
Like a piano roll, the time and pitch dimensions are very regular.
The pitches are displayed vertically and are given a fixed distance
per half-tone, i.e. the spacing is chromatic rather than diatonic.
Event times are displayed horizontally in such a way that all bars take
the same amount of space.
.PP
A row of VU meters at the top show which channels are being displayed
(and are active for playing).
When
.I ched
first reads a file those channels that contain MIDI data are turned ``on''.
All others are turned ``off'' (no play, no display).
Pointing at a VU meter and clicking the left mouse button inverts its
on/off state.
Pointing at a VU meter and clicking the center mouse button toggles
grey versus black display.  The color for display of each channel is
indicated in the bottom of the VU meter icon for that channel.
.SH "Horizontal (Time) Scroll Bar"
A scroll bar at the bottom shows either a tiny version of the entire
score display or the relative volume of each location
in the score with the area being displayed highlighted
(depending on the setting of VMODE, see below).
Since \fIched\fP has no way to know the decay characteristics
of the instrument on which this will be played, it compromises on a slow
exponential decay with a half-life of approximately 25 pixels.
Sweeping out a time range with the left mouse button depressed
defines the time range to be displayed.
Simply clicking the left mouse button in the bottom scroll bar
causes the entire file to be displayed.
Pointing at a location inside the highlighted area
and clicking the middle mouse button allows you to drag the highlighted
area forward and backward in time.
Pointing at a location outside the highlighted area
(but inside the horizontal scroll bar)
and clicking the middle mouse button moves the center of the highlighted
area area to the time selected.
.SH "Vertical (Keys) Scroll Bar"
A scroll bar at the left shows the staff lines with the key range
currently being displayed highlighted.
Sweeping out a key range with the left mouse button depressed
defines the lowest and highest keys to be displayed.
Simply clicking the left mouse button in the left scroll bar
causes the entire key range (0 to 127, C-2 to G8) to be displayed.
.SH "Score Area"
The center area of the screen is used to display the MIDI data in the
piano-roll-like format described above.
In the default case, \fIched\fP makes the notes in the MIDI file
fill the screen both vertically and horizontally, although it will
always include all of the treble and bass staff lines.
The left mouse button is used to select notes for various operations.
By sweeping out an area with the left button, you can define the beginning
and ending times and lowest and highest keys for other operations.
By simply clicking the left mouse button, the selected area will
collapse to nothing.
When there is a selected area it will be shown as an inverted (white on black)
rectangle in the display area.
.PP
The center mouse button pops up a menu with operations that use the
selected area.  These are:
.IP PLAY 0.9i
Play all the notes within the selected area.  Notes that extend
past the selected area on the left and right will be clipped (for playing)
however, only notes that are completely enclosed in the area vertically
will be played.
.IP BBOX
``tighten up'' the selected area so it contains as little
empty space as possible.
Specifically,
move the left edge right until a key-on MIDI event is encountered;
move the right edge left until a key-off MIDI event is encountered;
set the top edge so it is as high as it can be without including any
key higher than the highest note already enclosed in the selected area;
set the bottom edge so it is as low as it can be without including any
key lower than the lowest note already enclosed in the selected area;
.IP CUT
Delete the notes falling within the selected area.
Notes that overlap the left and right borders of the selected area will
be clipped.  Only notes falling entirely with the selected area vertically
will be deleted.  Put the deleted notes in the cut buffer.
Also see \fICLOSE\fP.
.IP PASTE
Insert the data from the cut buffer
(that most recently \fIcut\fP, \fIglom\fPmed or \fIclose\fPd)
at the location of the left edge of the selected area.
The pitches of inserted notes are not altered;
use \fIfilter\fP with ``transpose'' to do that.
Also see \fIOPEN\fP.
.IP GLOM
Select the notes that fall within the selected area (usually for
\fIpasting\fP) and put them in the cut buffer.
.IP FILTER
Request typed input of a command and send the data
from the selected area through that command, replacing the old data
with the output from the command.  The original data from the selected
area is left in the cut buffer (see \fIPASTE\fP).
.IP IPROC
Request typed input of an information command and send the data
from the selected area through that command, display (as text)
the output from the command.
The previous IPROC command is offered as a default (initially ``da'').
Note that the data being edited is unaffected by this command.
.IP INFO
Pop up a little menu describing the selected area in terms of
beginning & ending times (in clocks, beats, and bars)
and lowest and highest notes (in decimal & octal).
The menu will remain and preemp all other activity until you
press the middle button again.
.IP "ZOOM IN"
Enlarge the scale until the selected area fills the entire display area.
Set the selected area so that selection of \fIzoom out\fP will restore the
original scale (or close to it).
.IP "ZOOM OUT"
Shrink the scale until the entire display is contained in the selected area.
Set the selected area so that selection of \fIzoom in\fP will restore the
original scale (or close to it).
.IP WRITE
Pop up a text window to collect the name of a file and then write
the selected area out.
.IP OPEN
Open up a space equal to the width of the selected area
at the location (time) marked by the left edge of the selected area.
.IP CLOSE
Delete all notes falling between the beginning time and ending time of
the selected area, and close up the empty space left.
Notes that overlap the left and right borders of the selected area will
be clipped.  Put the deleted notes (also clipped, if necessary) in the
cut buffer.
Also see \fICUT\fP.
.PP
The right mouse button pops up a menu containing operations that affect
the entire file, ignoring any selected area.
.IP PLAY 0.9i
Play the entire file.
.IP CONTROLS
Replace the VU meter display with a set of sliders and
pushbuttons to set numeric values and select options,
see discussion of the pop-up control panel, below.
.IP FILTER
Request typed input of a command and send the data
from the entire file through that command, replacing the old data
with the output from the command.  The original data from the selected
area is left in the cut buffer
(also see \fIPASTE\fP and \fIFILTER\fP on the middle button).
.IP IPROC
Request typed input of an information command and send the data
from the entire file through that command, display (as text)
the output from the command.
The previous IPROC command is offered as a default (initially ``da'').
Note that the data being edited is unaffected by this command.
.IP READ
Pop up a text window to collect the name of a file and then read in that
file for display and editing.
.IP WRITE
Pop up a text window to collect the name of a file and then write
the whole file out.
.IP QUIT
Exit from \fIched\fP.
.PP
The pop-up control panel contains either 2 or 4 sliders
(depending on the setting of CLOX/BAR) and 2 sets of buttons.
.IP CLOX/BAR 0.9i
This is a little slider that sets the number of MIDI clocks per bar.
If this value is set to 0 then the Timing Clock With Measure End
codes in the data will be used to determine bar boundaries.
If CLOX/BAR is set to 0, the OFFSET & TICKS/BAR sliders disappear.
The default CLOX/BAR value is 480.
.IP OFFSET
This slider represents an offset at which bar lines start.
It is automatically set to the location of the first TCWME
(Timing Clock With Measure End) code found (mod CLOX/BAR, if non-zero)
whenever a new file is read in.
If CLOX/BAR is set to 0, then this slider is not displayed.
.IP TICKS/BAR
This slider selects the number of divisions per bar.
If the selection is other than 0, dotted vertical grid lines will
be drawn in the appropriate places.
.IP TEMPO
This slider sets the rate at which the
data is played with the ``PLAY'' menu options.
.IP GMODE
These pushbuttons determine what is done with the miscellaneous MIDI
``garbage'' (continuous controllers, after-touch, etc.)
when selected data is sent to commands (with IPROC, FILTER, etc.)
The choices are:
NONE, to filter it out completely;
SEL, to send the garbage with the selected area data;
UNSEL, to leave the garbage behind;
and
BOTH, to send it and leave it behind.
.IP VMODE
These two buttons choose
between making the height of each note proportional to its key
velocity and making it fixed at the maximum size that will fit.
This also selects whether the display in the horizontal scroll bar will be
a tiny version of the entire score display or the relative volume
of each location in the score.
.PP
.SH Options
.PP
The \fB-B\fP option specifies the number of MPU clocks per bar.
If this is set to zero (e.g. ``-B0''), bar line placement will be
governed by MPU Timing Clock With Measure End commands.
The default is 480.
.PP
If a number of bars is specified with the \fB-b\fP option,
that many bars (counting from the beginning of the file)
will be made to fill the width of the screen initially.
.PP
The \fB-d\fP option turns on debugging output.
.PP
The \fB-m\fP option lets you specify a blank margin around the score
and scroll bars.  The decimal integer argument is in units of pixels.
.PP
The \fB-t\fP option sets the number of grid ticks per bar
(see description of the TICKS/BAR slider, above).
The default is 0.
.PP
Examples:
.Cs
ched bach
ched -m39 bach
ched -B360 -b10 -t6 bach
.Ce
The first example displays the contents of the file bach in as large a format
as possible.
The second example indents the active area of the display by 39 pixels on
all sides (convenient for making slides photographically).
The third example displays only the first 10 bars (with 360 MPU clocks per bar)
of bach.  It also specifies 6 grid divisions per bar.
.SH BUGS
This editor is about 7/10 finished.
Many other refinements and additions are contemplated, including
convenient movement of data from channel to channel, massive speedups,
avoiding rewriting the screen unnecessarily, etc.
.SH SEE ALSO
chart(1), therm(1),
.SH AUTHOR
Peter Langston, Bell Communications Research
(bellcore!psl)