MIDIPUT

Section: C Library Functions (3)
Index Return to Main Contents

BSD mandoc
TCLM April 7, 1993

NAME

midiput - tclm command to append an event to a track of a Standard MIDI File

SYNOPSIS

mfileId track timing event [arg ... ]

DESCRIPTION

is a tclm command that appends an event to a specified track in a Standard MIDI File. The first argument specifies the Standard MIDI File and should be a value returned by either midiread(3) or midimake(3). The second argument specifies the track in which to put the event, and the third argument is the time in clocks since the previous event in the track. If the timing argument is not a list, then it is interpreted as a fixed length value. If it is a list of more than on value, then it is treated as a variable length value as used in Standard MIDI Files. Timing values specified as fixed length values are converted to variable length values by internally. The next argument to is the event name. The remaining optional arguments are dependent on the event type. The non-meta event names, their descriptions and their arguments are as follows:

channelpressure channel value: This MIDI event changes the pressure parameter for an entire channel. It takes two arguments. The first the the channel number and the second is the pressure value. Both values should be less than 128.
keypressure channel key value: This event changes the pressure for one key. It takes three arguments. The first is the channel number, the second the key value and the last the pressure value. All values should be less than 128.
noteoff channel pitch velocity: This event turns a note off. It takes two arguments with an optional third. The first argument is the channel and the second is the pitch. If a third argument is specified, it is the velocity for the note off. If it is not specified, then a velocity of zero is assumed. If a velocity of zero is used, either through assumption or as specified, then a note on event with a velocity of zero will be substituted. This is to take advantage of the running status, since most MIDI events are note on and note off events. All arguments should have values of 127 or less.
noteon channel pitch velocity: This event turns a note on. It takes three arguments. The first argument is the channel, the second is the pitch and the third is the velocity. All values should be less than 128.
parameter channel param_number setting: This event sets a parameter value. It takes three arguments. The first is the channel, the second is the parameter number and the third is the setting. All values should be 127 or less.
pitchwheel channel setting: This event sets the pitchwheel. It takes two arguments. The first is the channel and the second is the setting. Tclm takes care of converting the pitchwheel setting to the proper MIDI event form (eg two 7 bit values). The channel should be less than 128 and the setting should be less than 0x4000.
program channel setting: This event changes the program for a channel. It takes two arguments. The first argument is the channel, and the second is the setting. Both should be less than 128.
sysex [cont] {byte_list}: This event is used to transfer implementation specific information over MIDI It takes one or two arguments. If the first argument is the string ``cont'' then will generate a sysex message in the continuation form. The second argument is then treated as the data. If there is only one argument, then it is treated as the data. The data should be in a standard tcl list with each element being a byte of the sysex message. The data need not specify the initial 0xf0 or 0xf7 byte as includes the proper value depending on if the ``cont'' string was an argument. It is up to the user to make sure all sysex messages are properly terminated. All data in the sysex message should be less than 128.

All non-meta events except sysex take advantage of the running status feature of Standard MIDI Files. That is, if one event immediately follows an event of the same track on the same channel, then the event type need not be explicitly stated and is assumed to be the same as the previous value.

In addition to the events listed above, can also be used with meta events. Their names, descriptions and parameters are:

metachanprefix {byte_list}: I really don't know what this event does, so I had to guess on the format. It takes one argument, which is a list of bytes.
metacpy copyright: This event is a text event that is used for copyrights. It takes one argument which should be the copyright as a string.
metacue cue: This event is a text event that is used for cue information. It takes one argument which should be the cue as a string.
metaeot: This event marks the end of a track. All tracks must have one. It takes no arguments.
metainstname name: This event is a text event used for instrument information. It takes one arguments which should be the instrument data as a string.
metakey key_name key_type: This event is used to specify a key signature. It takes two arguments. The first should be one of the following strings: ``C flat'' ``G flat'' ``D flat'' ``A flat'' ``E flat'' ``B flat'' ``F'' ``C'' ``G'' ``D'' ``A'' ``E'' ``B'' ``F sharp'' or ``C sharp '' (I hope I got those right - it should 7 flats to 7 sharps). The second argument should be either: ``major'' or ``minor''
metalyric lyric: This event is a text event used for lyrics. It takes one argument which is the lyric in string form.
metamarker marker: This event is a text event used for marker information. It takes one argument which is the marker data as a string.
metaseqname name: This event is a text event used for naming sequences. It takes one argument which is the sequence name as a string.
metaseqnum number: This event is used for numbering sequences. It takes one argument which is the sequence number. converts the number to the proper two byte form.
metaseqspec: I don't know anything about this event, and it is not currently implemented.
metasmpte hour minute second frame fractional_frame: This event is used for supplying SMPTE information. It takes five arguments. The first argument is the hour position, the second is the minute position and the third the second position. The fourth argument is the frame number and the fifth the fractional frame number.
metatempo tempo: This event is used to specify a tempo. It takes one argument. The argument should be an integer. If the number has a `u' character at the end it is treated as if it represents microseconds per quarter-note. If it does not have a `u' character then it is treated as if it represents beats per minute.
metatext text: This event is a generic text event. It take one argument which is a string.
metatime numerator denominator clocks 32nds: This event is used for specifying the time signature. It takes four arguments. The first is the numerator of the time signature and the second is the denominator. The third argument is the number of clocks per metronome beat and the fourth is the number of 32nd notes per quarter note. takes care of converting the denominator to a negative power of two, which is the form specified by Standard MIDI Files.

RETURN VALUES

returns nothing.

BUGS

should be rewritten to handle inserting events in the middle of a track.

AUTHORS

Mike Durian - durian@advtech.uswest.com

This document was created by man2html, using the manual pages.
Time: 00:28:07 GMT, March 30, 2022