encode [-r controlfile.rc] [editfile]
command is limited to encoding information one spine at a time.
A typical use of
might be to encode individual musical "parts" or "voices"
in a representation such as
the user might then use the Humdrum
commands to construct a full score from the encoded parts.
The user must have access to an appropriate MIDI controller connected
via a Roland MPU-401 (or compatible) MIDI controller card.
is available only for IBM PC or compatible hardware running under
the DOS operating system.
command implements a full-screen interactive text editor
-- similar to the
When invoked, the screen is divided into three display regions: a
and a larger
displays various pieces of information,
including the name of the file being edited, the current size of the file
(in bytes), the run-control (
.rc) file used to configure the editor,
the number of beats per measure, the output signifier assigned to each beat,
the current metronome rate, and mode.
is used to construct and execute general-purpose
is used to display and edit the encoded Humdrum text.
The editor has four modes of operation: edit mode, input mode, MIDI input mode, and command mode.
Four scrolling commands are available.
Control-F is used to scroll forward in the document by one page.
Control-B is used to scroll backward by one page.
Control-D is used to scroll down by half a page.
Control-U is used to scroll up by half a page.
The page-down and page-up keys can be used instead of CTRL-F
and CTRL-B respectively.
If any of these commands is preceded by a typed
then the action is repeated
5 will cause the display to advance five pages.
Movement to specific line numbers can be achieved using the upper-case `G' command preceded by the desired line number. If no line number is specified, the G command causes the cursor to be moved to the end of the file.
Vertical motions of the cursor relative to the displayed text can be controlled by a variety of means. The up and down cursor-control keys move the cursor up one line or down one line respectively. Alternatively, the lower-case letters `k' and `j' may be used for up and down movements -- as in the vi text editor. If the cursor is at the bottom or top of the screen, cursor movement down or up a line (respectively) will cause the screen to scroll one line as needed. The carriage return or ENTER key will cause the cursor to move to the beginning of the next line. Once again, if any of these commands is preceded by a typed number, then the action is repeated number times.
The upper-case letter `H' positions the cursor at the highest line displayed on the screen, whereas the upper-case letter `L' positions the cursor at the lowest line displayed on the current screen. Alternatively, the `home' and `end' keys can be used to move the cursor to the top and bottom respectively. The upper-case letter `M' positions the cursor in the middle of the current screen. In all of these commands, the cursor is positioned at the horizontal beginning of the appropriate line.
Horizontal motions of the cursor within a line can be carried out using the left (<-) and right (->) arrow keys. Alternatively, the lower-case `h' and `l' keys can be used as aliases for the left and right cursor motions -- as in the vi text editor. The space bar can also be used to move the cursor to the right. The dollar sign ($) causes the cursor to move to the end of the current line. The number zero (0) or the caret (^) causes the cursor to move to the beginning of the current line.
Horizontal cursor movements may also be defined by context. Where multiple data tokens are encoded on a single line, the `w' command causes the cursor to move forward word-by-word, whereas the `b' command causes backward movement word-by-word. A word is defined as any character string separated by spaces (or by new lines). In both the `w' and `b' commands the cursor is placed at the beginning of the appropriate word.
Three forms of simple text deletions are possible in edit mode. The character corresponding to the current cursor position can be deleted by typing the lower-case letter `x'. The character immediately before the current cursor position can be deleted by typing the upper-case letter `X'. The lower-case letter `d' will cause the current line to be deleted; line deletions may also be achieved by typing the `Del' key. Preceding any of these commands by a typed number causes the action to be repeated number times. The most recent deletion can be restored or "undone" by typing the lower-case letter `u'.
Once the input mode is invoked, typed ASCII characters will be added at the current cursor position until the ESCape or TAB key is pressed. Pressing ESCape or TAB will return encode to the edit mode. Tabs are explicitly forbidden as input in order to reduce the possibility of creating text that does not conform to the Humdrum syntax.
MIDI input mode,
data is entered into the current document according to user-defined
(such as caused by playing on a MIDI keyboard)
and ASCII character strings.
Predefined mappings are specified in a
command is invoked, it must have access to a
.rc file containing
The user can identify a specific
.rc file on the command line
option (see OPTIONS).
will seek a default
.rc file (named
encode.rc) residing in the
the current directory, or if absent, in the
The run-time control file is essential to the operation of
and inability to locate a
.rc file will cause
to abort (see discussion in OPTIONS below).
The run-control file contains a series of definitions mapping
MIDI events to output strings.
Three classes of MIDI events can be mapped:
.rc file contains a number of definitions
for each class of event, although some events may not appear at all
By way of example, the run-control instruction:
KEY 60 middle-C
assigns the key-on event for MIDI key #60 to the
MIDI input mode,
each key-on event for key #60 will cause the string
middle-C to be
prepared for insertion into the text window.
Typically, a number of
KEY definitions will appear in
a given run-control file -- often one definition for
each MIDI key (0 to 127).
A second class of MIDI events is key-down velocity (
Key velocities can range between 0 (low key velocity)
and 127 (high key velocity).
VEL mapping specifies a range of values for which a given string
will be output.
By way of example, the following assignment maps key velocity
values between 90 and 127 to a string consisting merely of
the apostrophe (the
**kern signifier for a staccato note):
VEL 90 127 '
Given this mapping, key-down velocities within the specified range will cause the apostrophe character to be prepared for insertion into the text window.
A third class of MIDI events is delta-time (
When determing the "duration" of a performed note,
the durations of individual key-presses are confound by the articulation.
In general, performing musicians are less concerned by the
of individual key-presses, than by the keypress-to-keypress time spans;
the elapsed time between one key-onset and the next
key-onset provides a better estimate of the nominal musical
duration of a note than the actual held duration.
DEL contains the
difference between successive key-onset times
-- expressed in MIDI clock ticks.
DEL may range from 0 upward.
For a tempo of 60 beats per minute,
inter-onset durations of one second correspond to
DEL values of about 100.
The following sample
.rc file illustrates a simple run-control file.
Notice that a series of
DEL ranges have been defined and
For example, inter-onset times lying between 48 and 80 clock ticks
generate the output string `
values between 113 and 160 generate the string `
4' and so on.
Notice that this file restricts the number of possible output "durations"
to just five.
# Sample .rc file KEY 60 c KEY 62 d KEY 64 e KEY 65 f KEY 67 g KEY 69 a KEY 71 b KEY 72 cc DEL 48 80 8 DEL 81 112 8. DEL* 113 160 4 DEL 161 224 4. DEL 225 320 2 VEL 90 127 ' ORDER DEL KEY VEL
The effect of the above run-control file can be illustrated by example.
received two key-on events (key #60 followed by key #62),
where the first key exhibited a velocity value of 94 and the inter-onset time
DEL) was 100.
The first key (#60) would be mapped to the string `
the delta-time would be mapped to the string `
and the key-velocity (
VEL) would be mapped to the apostrophe.
At the moment of the key-onset for key #62, these three
strings would be amalgamated according to the
KEY second, and
VEL third) --
producing the output string:
outputs assembled strings only when the
key-on event occurs.
This means that the text display is always one "note"
behind the performer.
Note that if musical durations are based on key inter-onset times,
it is impossible to output a note prior to the onset of the next note.
The last note in a buffer can be flushed by typing the ESCape key.
(The timing of the last note is based on the
DEL between key-onset
and the moment of pressing ESCape.)
In addition to mapping velocities, inter-onset times,
and key numbers, run-control files can define a number of other
The MIDI channel number attended to by
can be set by the
Any one of 16 channels (1-16) can be selected.
A default channel 1 is assumed if no
RECEIVE instruction is present
in the run-control file.
command has a built-in metronome for assisting real-time encoding.
The metronome sends commands to the MIDI instrument
generating metronome tones.
Two types of tones are generated -- tones marking each beat,
and tones marking the beginning of each measure.
The metronome rate (in beats per minute) is set by the TEMPO command.
The beat is specified in two ways.
The default beat is indicated by the presence of an asterisk following
of the DEL instructions.
In the above example, the signifier `4' is assigned to the default beat.
Apart from the default beat, the beat may also be explicitly assigned
using the BEAT instruction.
This instruction is followed by a single argument identifying the output
intended to coincide with each metronome beat.
BEAT 4. would set the beat in the above example to
the dotted quarter, rather than the quarter.
Note that the specified signifier in the BEAT command must correspond to
one of the existing signifiers defined using a DEL instruction.
The following table lists all of the types of instructions permitted in a run-control file.
# text unexecutable comment BEAT string set beat to DEL whose output signifier is string beat BUFFER n text define (potentially multi-line) text buffer # in (0-9) DEL min max string key inter-onset times between min and max clock ticks cause string to be output KEY n string MIDI key-on #n causes string to be output METER n define number of beats per measure as n METRE n same as METER MM on|off switch metronome on or off; default is on ORDER codeword1 codeword2 ... define order of string outputs, where codewords are selected from: BUFFER, DEL, KEY, SRING, VEL RECEIVE n define the MIDI channel from which data is accepted STRING n text define string constant # in (0-9) TEMPO n set metronome to n beats per minute VEL min max string key-down velocities between min and max cause string to be output
can be repeated multiple times within the
All other instructions (
should appear only once in the
TEMPO instructions cannot appear in
.rc file until after the default beat (
has been defined.
Each command is formulated in the command window and launched by pressing the ENTER key. After execution, encode is returned to edit mode.
Most commands consist of a single character; some commands require one or more parameters.
The `w' command causes the current text to be written to disk. If there is currently no active filename, then an error is displayed indicating that encode is unable to write a file without knowledge of the filename. The command `w filename' will cause the current contents to be written to the file filename. If encode was invoked with a specified filename, then that filename is active throughout the session.
If the user attempts to write to an existing file (that was not specified when encode was invoked), then an error message is issued. Overwriting an existing file can be achieved by appending an exclamation mark following the write instruction -- as in `w! filename.'
The `q' command causes encode to terminate. If the current file has been modified without writing to disk, then a warning will be displayed and the quit instruction ignored. Appending an exclamation mark (`q!') will cause encode to terminate without saving any recent modifications.
Note that the quit and write commands can be combined as a single instruction -- `wq'.
The `r filename' command causes encode to read the file filename into the text, beginning at the line following the current cursor position.
The `v' command causes encode to spawn a vi text editing session -- importing the current encode text. The vi text editor provides text manipulation capabilities, including searching, substitution, and macro-instruction facilities not available in encode. (Refer to the UNIX vi reference document for further information.) When the vi session is closed, the edited text file is returned to the encode session.
The `m' command invokes a Humdrum pipeline that is suitable for
auditioning text data conforming to either the
**MIDI representation formats.
Specifically, `m' causes the current text to be passed to the
midi -c | perform.
**kern data will be translated to
data and sent to the
The user can then interactively proof-listen or audition
the encoded data.
Refer to the
for information regarding the types of
interactive commands available during proof-listening.
command is terminated when the end-of-file is reached,
or if the user presses either the ESCape key or the letter `q'.
In either case, control is returned to
The `b' command is used to read buffer text defined in the
Up to ten numbered buffers (0-9) can be defined.
will cause any text denoted
BUFFER 1 to be output following
the current cursor position.
Use of the upper-case `B' rather than `b' causes the
buffer contents to be inserted prior to the current line rather
than following the current line.
Buffer zero (0) has a special status.
command is invoked, if the current text is empty
(i.e. empty file or no filename specified),
then the contents of
BUFFER 0 are automatically inserted into
This provides a convenient way to import header information
for a newly encoded file.
The `rc filename' command causes encode to use a different run-control file filename. This allows the encode environment to be entirely reconfigured without interrupting the encoding session. This command can prove useful, for example, when the music being encoded changes key.
The set command can be used to define (or redefine) any parameters
permitted in a
For example, the tempo may be changed, the metronome turned-off,
the metronome beat redefined, a string variable assigned,
or a specific key re-mapped, e.g.
set TEMPO 92
set MM off
set BEAT 4.
set STRING 3 !! Variation No. ...
set KEY 60 C4
buffer record, rather than replacing any existing buffer definitions.
Note that run-control keywords, such as
may be spelled using either upper-case or lower-case.
Note that due to the small size of the command window, especially long command lines may wrap around within the window. This wrap-around has no affect on the command operation.
EDIT MODE CTRL-F scroll forward one page CTRL-B scroll backward one page CTRL-D scroll down by half a page CTRL-U scroll up by half a page scroll forward one page scroll backward one page move cursor down one line move cursor up one line j move cursor down one line k move cursor up one line move cursor to the beginning of the next line H move cursor to the top of the display M move cursor to the middle of the display L move cursor to the bottom of the display move cursor to the top of the display move cursor to the bottom of the display -> move cursor one character to the right <- move cursor one character to the left l move cursor one character to the right h move cursor one character to the left move cursor one character to the right x delete character at current cursor position X delete character immediately preceding currrent cursor position d delete current line u undo most recent deletion or insertion command insert text prior to current cursor position (invoke INPUT MODE) i insert text prior to current cursor position (invoke INPUT MODE) a insert text after to current cursor position (invoke INPUT MODE) o insert text beginning with the next line (invoke INPUT MODE) O insert text beginning with the previous line (invoke INPUT MODE) A invoke MIDI INPUT MODE; insert data beginning with the next line I invoke MIDI INPUT MODE; insert data beginning with the previous line <number> repeat ensuing command <number> times INPUT MODE ESC return to EDIT MODE return to EDIT MODE MIDI INPUT MODE ESC complete last MIDI event and return to EDIT MODE COMMAND MODE b n append run-control buffer number n following current cursor position B n insert run-control buffer number n before current cursor position m invoke interactive proof-listening for
set rc-command set or reset a
q quit encode q! quit encode without saving modifications since last write r filename read input file filename at current cursor position rc controlfile use run-control file controlfile rather than current
s n append run-control string number n following current cursor position S n insert run-control string number n before current cursor position v spawn vi text editing session using current text w [filename] write file filename to disk; default filename is current file w! filename overwrite existing file filename wq write current file and quit
Options are specified in the command line.
-h displays a help screen summarizing the command syntax -r file.rc invoke using the run-control file file.rc
option permits the user to identify a specific run-control file
to configure the
If this option is omitted,
will seek a default run-control file named
in the current directory, or in the directory
if not present in the current directory.
If the option is specified,
will search the current directory for the specified run-control file.
If this search fails to locate the file,
If this fails,
will treat the input filename as an absolute file path.
If this fails, encode will issue an error message indicating
that it failed to locate the specified run-control file.
.rcfiles are maintained in the
$HUMDRUM/etcdirectory. Exploration is encouraged. The default file is
vitext editor must be available in order to invoke the `v' edit command.
Note that the
TEMPO instructions cannot appear in
.rc file until after the default beat (
has been defined.
assemble (4), cleave (4), encode.rc (5), humdrum (4), **kern (2), **MIDI (2), midi (4), num (4), perform (4), proof (4), record (4), timebase (4), vi (UNIX)