MIDI Modules

-- MusicWeaver Release 1.3 August 1999 --


OVERVIEW

With the presently available set of MIDI modules, there are a number of different sorts of things one can do. There is the module, of course, that connects to your hardware MIDI interface (if you have one); there is one that drives the internal Synth, and one to play Midifiles, Aside from these, the others either modify the MIDI events in some way, or control the path on which they flow. (It is assumed that you have enough knowledge of MIDI to follw these descriptions: if not, there are many sources of information on the subject -- check your local bookstore or the net...)

I should reiterate that the MusicWeaver is not a Sequencer or the like. (In fact in the freely distributable package there is no way of recording MIDI, although this is available to registered users. See Copyright and Distribution) It is much more slanted to the manipulation of MIDI streams in real-time -- either taking input directly from a keyboard or just from a previously recorded file. You can do things like transpose notes, change or add instruments and channels, filter out certain events or note ranges. You can send Controller and PitchBend messages; you can direct selected events to separate processing paths; and so on. The number of modules grows with each release, and so does your range of capabilities.

There is a single MidiConn module, that can be attached to any of the MIDI I/O ports offered by your hardware . This is a 'Multiconnector' module, that both accepts events from MIDI IN, and drives MIDI OUT. 'WvrSynth' is a Filter that will drive the BeOS internal Synth from a MIDI stream. The 'MidiPlay' Source module generates a real-time MIDI stream from a Midifile read from disc. There is also a 'Program' Source module that will send user-determined Program-Change events to a MIDI stream, and others that similarly send other specific MIDI events.

There are simple Filter modules, such as 'Transpose' and 'MIdiChannel', that modify some or all of the events that are passed through them. Transpose, naturally, only operates on 'Note-On' and 'Note-Off' events, shifting them up or down by the interval desired; MidiChannel operates on all except System events that pass through it, setting them to the specified channel.

Other modules are used in various combinations to divert specific events that satisfy certain criteria into different paths. For example you could have all notes within a certain range flow along one path, notes outside that along another (keyboard-split deluxe...). Or you could split off certain channels for separate processing, and so on. See 'Marking and Splitting Events' for details on how this is achieved.

There is a different type of (Universal) path-switching module that will change the path of an entire stream in response to 'director' messages. Refer to 'Path Switching' in the documentation on Universal Modules for details of the mechanism.

Notice, by the way, that in this release all element control panels are 'first click' -- they do not need to be selected before accessing any of their controls. This is in general much more convenient for live performance, as you are likely to have a number of controls in different windows that you want to manipulate quickly. (It is a little harder to bring a window to the front -- you need to click on the title bar or border -- but good prearrangement of the windows minimizes this. Also remember that you can always bring a hidden or minimized panel to the front by selecting 'Panel' from the element's menu.)

-----------------------------------------



Marking and Splitting Events

Some preliminary explanation of the concepts involved is advisable. Central is the fact that any MIDI event flowing along a MusicWeaver path may be 'marked'. There is one particular (Multiconnector) module, Splitter, that responds to these marks and directs the event onto one (or both, or neither) of its two output paths. 'Marker' modules (for example 'KeyRange') can set these marks according to the values of the particular properties they monitor. (These marks are exclusive to the MusicWeaver -- they are not part of the MIDI protocol, and therefore not available outside the system.)

The Splitter's panel allows you to select which marks (there are eight possible) will affect the path taken by the event, and what the effect of each will be. Unmarked events, or those with no marks that match any selected in the Splitter, are passed straight through on the 'Through' path. You may choose to have an event with a particular mark redirected, duplicated to both paths, or blocked completely. You may also use a mark to inhibit all the above effects that would otherwise result from other marks . (If more than one mark is set, there is a precedence order. [Note: a Splitter never clears any marks. This is done, if needed, by a separate 'ClearMarks' element.]

As you can see, it takes a pairing of a Marker with a Splitter to change the path of an event. If you want to divert events onto a path according to several different criteria, you can link different markers in a chain leading to a single splitter.

By default, a Marker module sets 'mark 1'. This can be changed through a menu in each marker's panel. (The other details of the panel of course depend on the marker's function.) Also by default, a Splitter diverts events with mark 1 and duplicates them if they have mark 2. (There is no default for either the 'Stop' or 'Pass' actions.) You can rearrange this as you desire via the checkboxes in the Splitter's panel.

Each Marker element can only set one of the marks, but successive Markers applied to the same event can be configured to set either the same or different marks. Each event may have as many of the marks as are useful. Several marks can be set first, before the events pass through a network of splitters to achieve all the desired separations.

There is another way of redirecting events, in this case entire event streams. Please refer to the section on the Path Switching in the Universal Modules documentation for details.



Event Timing

MIDI events within the MusicWeaver are each tagged with a time value. When an event is generated -- by MidiConn or MidiPlay for example -- this is initially just the "current time" (to the millisecond), but it can be modified -- currently only by the 'MidiDelay' module.

However (and note this...) none of the MusicWeaver output modules -- MidiConn or WvrSynth -- pay any attention to the time value: they always output events at the moment they arrive. To reorder events according to their time value (and re-emit them at the specified time) you must use a 'TimeSort' element. This accepts a stream of arbitrarily ordered MIDI events, sorts them, and re-emits them at the appropriate time, (It only works, of course, on "future time" events: if for some reason an event has been assigned a time earlier than "now", it is simply re-emitted immediately.)

The ability to delay events is mostly useful for things like "echoes". It takes at least two elements -- a MidiDelay followed by a TimeSort -- to achieve this, but you can feed several MidiDelays into a simgle TimeSort ( via a Join element or some other merging filter), and its output will be suitably sorted. (Unlike most other elements, the output of a TimeSort can be connected back to its input to create a continuous loop [see Cautions]; however the only way to stop such a loop playing is to break the loop somehow, perhaps with a Marker/Splitter combination or a Switcher. )



MODULES

MidiConn

MidiConn is a Multiconnector module: each element provides connections to both the 'MIDI In' and 'Midi Out' functions of its associated port; hence it has both 'source' and 'filter' connectors. (see 'Multiconnector Modules') (This module replaces the separate ones for each port that earlier releases provided.)

Before you can use it, each element must be associated with a particular MIDI port available on your machine. [You have to do this even if you only have a single port -- the module isn't smart enough to recognize this case, I'm afraid...] Open up the element's control panel ('Diagram Operations'), and select the port from the popup menu there. You can have as many elements as you wish associated with a single port: incoming MIDI will be duplicated, and outgoing will be merged.

The element has two output pips. By default, the first one that you drag a link from will be 'MIDI IN'; the other will then be a pass-through from the input that is driving MIDI OUT, if you want it. (If you happen to make these connections in the wrong order, bring up the Connector-selection menu by pressing the right mouse-button on (the tile of) that connector, and change the selection. You only have to do this to one of them: the other will be swapped automatically.)

About the simplest thing you can do with these elements is build a "MIDI Through" connection. To pass MIDI In to MIDI Out. just connect the output of the element directly back to its own input. To link MIDI 1 In to MIDI 2 Out (if your machine has multiple ports), or vice versa, set up two MidiConn elements, attach one to each port, and cross connect between the two elements.

As this is a Multiconnector element, you can't have more than one path directly connected to MIDI OUT. Of course it is perfectly legal to have several converging paths, but to do this you will have to precede the input connector with a 'JoinPaths' (or some relevant Filter).

Please refer to the README for the notice about interface problems with audio cards under BeOS 4.0 Intel. (Fixed in 4.5)


WvrSynth

This is a Filter that makes a connection between a MusicWeaver MIDI stream and the BeOS internal synth. It has no control panel-- it just passes on the events that arrive.

Note that the first instance of WvrSynth placed will take quite a while to load (all those instruments...). Further instances can access the already-loaded data, and so are fast. There is a similar (but shorter) delay when unloading the last copy.

You can obviously connect MIDI In from a MidiConn element to a WvrSynth -- either directly or through some fancy processing chain -- and play it live from your MIDI keyboard. You will find, though, that the synth is not exactly 'real-time': there is a slight unavoidable latency between striking a key and hearing the sound. This is not the fault of the MusicWeaver: it is because the synth has to build the sound in a buffer before it can play it -- just the nature of the beast, I'm afraid.


MidiPlay

(This is a major revision to an earlier, cruder module of the same name.)
MidiPlay is a Source module that will read standard Midifiles and play them out onto a MusicWeaver path (from where you can send the music direct to an output port or WvrSynth, or manipulate the stream a bit first...) . You can specify as many files as you like to be played in sequence. It has a control panel with five buttons:

'Queue...' opens a standard File Panel where you can select a Midifile, or group of files, to be played. All the files you select will be queued to be played in turn. Play does not actually begin until you click 'PLAY'. You can re-open the File Panel to select more files at any time, even while previous ones are playing. The file that is currently loaded is always shown in the box at the top.

'PLAY' starts the music playing (from the current point if it has been stopped). When the piece reaches its end, the next file in the queue will begin automatically. If there are no more in the queue, play will stop, but the last piece will be rewound to the beginning, ready for another go round.

'STOP' while music is playing halts the performance immediately, but does not try to silence things, so any notes playing at that moment will continue doing so.. Pressing 'PLAY' will resume from that point. Clicking 'STOP' a second time after play has stopped will send "All Notes Off', thus preventing ugly unstoppable tonality (but will not reset other things like controllers and program settings); you can still resume playing without much loss if you wish.

'Rewind' returns to the beginning of the file. It is only active when the music has been paused.

'Next' will skip the current piece in memory and start the next in the queue. If there are none left, it will pop up the same file requester panel as ''Queue...' so you can select more files. The only difference is that playing begins automatically when you exit the requester.

MidiPlay now processes any System Exclusive sequences that may appear in a midifile. This may improve the sound of some files if your synth is equipped to handle that sequence.


MidiChannel

This Filter sets the MIDI channel of all events (except System Messages of course) that pass through it. It has a control panel with Radio buttons from which you can select the desired channel


Transpose

This Filter can shift all Note-On and Note-Off events that pass through it by up to three octaves up or down. The control panel has Radio Buttons to shift by octaves (+ or - 2) and a slider to shift in semitones by up to one octave in either direction.

Note that it affects all notes, whatever their channel. If you want different effects on different channels, use separate paths.


VelAdjust

(AN enhancement to an earlier version.)
This is a Filter that lets you adjust velocity characteristics of Note-On events.

The top slider in the control panel sets a threshold value that will first be subtracted from the original velocity; if the velocity was less than this, the result will be zero. Default is 0 (no cutoff).

The middle slider is a multiplier for velocity values; it is scaled in per cent, from '0' (all variation is removed) to '200' (values are doubled). Default is 100%.

The bottom slider is an offset that will be added to all velocities, ranging from 0 to 126 (so Note minimums range from '1' -- softest -- to '127' -- loudest possible). Default is 0.

The threshold is subtracted first (with reset to zero if necessary), and then scaling is applied before the offset. The resultant value is adjusted to be within the range 1--127 if necessary. ('0' is not permitted, as it represents Note-Off.)

A VelAdjust element is a good way of adding "highlights" to notes above a certain volume. If you want to completely suppress soft notes, or divert loud ones to some other processing, use a VelMarker and suitable splitting.

NoteOff

This is a Filter that may find occasional use in conjunction with a delay, for instance to generate notes of a fixed length. It simply turns all arriving Note On events into Note-Offs (zero-velocity Note-Ons). All other events (including Note-Offs) are completly discarded. It has no control panel.


OneNote

This is another Filter with rather restricted uses. It sets the note value of all Note-On and Note-Off events to a selected value, according to the slider in its control panel (default 60 = 'Middle C'). The velocity value is not affected, and all other events are passed unchanged. It will probably be mainly useful in percussion tracks, where you may wish to reduce varying incoming events to a single sound.


NoteOffType

The MIDI Standard specifies two distinct kinds of 'Note Off' events. There is a special message type ('0') defined, but many keyboards generate and recognize a 'Note On' (type '1') with a zero velocity value for the purpose instead. It is possible that one or the other may not be recognized at all, so this module is provided to make the conversion if needed.

MusicWeaver modules have tended to use the 'zero-note-on' convention, so the default action of this module is to convert to 'true note off'. It has a control panel with a pop-up menu where you can select the inverse conversion if appropriate. [At one time the BeOS Intel MIDI drivers were converting incoming zero-note-ons to true note-offs, so if your equipment gets confused, you may need this!]


Program

This is a Source module that sends Program Change events to a MusicWeaver MIDI stream. The transmitted event is always on channel 1. To send to a different channel, link it to a following MIdiChannel element.

The major portion of the panel is a scrolling list of General MIDI Program Change values by name (and number). You can select any entry by clicking on it. (The names only represent the "Standard Bank" of General Midi instruments. If your synth supports it, you can of course select other banks -- by sending the appropriate control messages -- but you'll need to refer to your manual for the exact meaning of each Program Number.)

If you ever have to reselect the currently selected entry (you might have two preset Program elements that you wish to switch between, for example), use 'ReSend' -- clicking on the currently selected item will have no effect. (You don't need to press 'ReSend' when picking a new item from the list.)

When you load a Diagram file containing a Program element, the value is set as it was when the file was saved, and the appropriate event is transmitted. This happens after loading is complete, so all other parameters (such as channels) will have been properly set already. (In previous releases there were problems because the event could get emitted too early; this no longer happens.) You can't ever automatically send a Program event to a WvrSynth element at load time, though. Because the synth takes so long to set up, the event always gets transmitted long before the synth is ready. You just have to click 'ReSend' when loading is complete.


Controller

This is a Source module that will send setting events for a desired MIDI Controller. Select the Controller number that you wish to affect from the scrolling list in its control panel, and the value you wish to set with the slider below. (Controller names provided in the list are best guesses according to such "standards" as exist, but your own synth is unlikely to conform, and may not even have most of them. Check your manual.)

Below the slider to the left is a popup menu that determines how events are sent. By default ('When Set') a single event is sent when the slider is moved to a new value and released. If 'Single' is selected, no event is sent automatically when the slider is changed: the 'SEND' button to the right must be used. (This button is always active in any case.) In the third 'Continuous' mode, events are sent continually while the slider is being moved (though not if the mouse button is depressed but stationary). Changing the controller number never sends an event by itself.

The three buttons on the right ('0', '64', and '127') will send their respective values to the current controller directly. They do not affect the slider value.

As usual, this module only generates events on MIDI channel 1. To affect other channels follow it with a MIdiChannel element. As with the Program element, when it is in a configuration file that is loaded, it sends the appropriate Control Change after loading is complete.


SetRPN

In addition to the regular set of MIDI 'Controllers', your synth may accept 'Registered Parameter Numbers' ('RPNs'). These are actually supplied by a suitable sequence of Controller events, but they would be tedious to generate from standard MusicWeaver Controller elements. A separate module is therefore provided for RPNs.

The control panel for a SetRPN element has identical form to a Controller element -- except that it doesn't need a scrolling list. Use it exactly as described in that section. (The default mode here, however, is 'Single', so normally nothing gets sent until the 'SEND'button is activated. ) Note, though, that where a Controller element would send one event, SetRPN will send five! This means that you will not want to use 'Continuous' mode too extensively...


PitchBend

This is a Source module that generates Pitch Bend events as the slider in its control panel is moved. The slider knob returns to zero automatically (and instantaneously) when it is released.

This is a somewhat preliminary version, and will likely gain options (such as non return to zero) in a future release.

One trick that may be useful: if you resize the window, the slider resizes too. This means that you can make a very 'thick' slider track that is easy to grab in a hurry!

Splitter

The Splitter is a 'Multiconnector' Module with two outputs: 'Through', and 'Diverted'. It is used to determine which of the two paths arriving events will be sent out on. (see Marking and Splitting Events) The determination is made on the basis of 'marks' that may be set on the event. Its panel has checkboxes that can be used to control its behaviour.

There are eight possible marks that may be attached to an event, and four possible actions a Splitter may take if it is set to respond to it. If the box in the 'Dupe:' column of the panel is checked for that mark, the event will be sent to both output paths; if the box in the 'Split:' column is checked, the event will go out only on the 'Diverted' path; if the mark is in the 'Stop' column, the event will be removed from the stream at that point. If there is no match between any mark and checkbox, or there is a match with a selection in the 'Pass' column, the event continues on along the 'Through' path. The initial default is that mark 1 causes a Split, and mark 2 causes a Dupe; other marks are initially ignored.

You can set as many of the marks on a single event as you like, and you can check any desired set of marks in the splitter (although you can only choose a single column for each). If an event is marked (with multiple marks) for more than one action, Dupe takes precedence over Split, Stop takes precedence over both, and Pass overrides them all.

[Note that a Splitter does not clear any marks. Use the 'ClearMarks'' element for this.]


ClearMarks

The function of this module is simply to clear marks that may have been previously set on an event. (See Marking and Splitting Events) You can select those you wish cleared in its control panel. By default, all marks will be cleared.


ChanMarker

This Marker (Filter) can set a mark on all events on a particular channel or set of channels. (see Marking and Splitting Events) Checkboxes in the panel control the selection. Like all marker modules, the mark applied is determined from a drop-down menu in its panel.

You would use this element, together with a suitably set-up following Splitter to divert a channel for special processing, or simply to mute it. You can 'solo' a channel by having it diverted by the Splitter, and ignoring everything on the latter's 'Through' output.


KeyMarker

This Marker can mark selected notes of the scale. Any subset of the twelve notes of the octave may be marked; this setting then applies to all octaves.


KeyRange

This module can mark a range of notes for splitting. You can select either to mark events that are within the range (inclusive of the set limits), or those that are strictly outside it.

The 'Low Limit' slider in its control panel sets the lowest note that will be in the range; "High Limit' determines the highest. Both limits are inclusive. If you set 'High' less than 'Low', all notes are in range!)

A drop down menu next to the usual Mark selection at the top of the panel determines whether notes within or outside the selected range are marked (default is within). The ranges are MIDI note numbers, of course, with '60' being Middle-C.


MsgMarker

This module can mark individual types of MIDI Events ("Messages"). These types are 'Note-On', 'Note-Off', 'Program Change', 'Controller', 'Poly Afterouch', 'Channel Aftertouch', 'Pitch Bend', and 'System'. (Some of these are abbreviated for space in the panel, and the order there is numerically correct.)

Note-On events with velocity zero are considered by this module to be Note-Off events (a usual convention). So you needn't be concerned which convention is actually generated by your keyboard or other source.


VelMarker

(An improvement to the previous version of the module.)
This module will mark all Note-On events that exceed a threshold velocity. A slider in its control panel sets this threshold. When a Note-Off to match a marked Note-On arrives (same note and channel), it is tagged with the same mark, so that it will be diverted by subsequent switching in the same way that the original Note-On was.

Proper operation of this element does presume that On and Off events are properly ordered. If you have merged MIDI streams as input, or there is any other reason to doubt this, it is safest to precede it with a DeGlitch element.


ControlMarker

This module lets you mark all events targetted at a selected MIDI Controller number -- for example 'Sustain Pedal' events (Controller 64). The controller to be tagged is set by the slider in the control panel. (It's best to determine that number from your synth manual, but you can check the list in a Controller element's panel as a guide.)

As with other marker modules, the specific mark to be applied is determined by a drop-down menu.


ValueRange & IndexRange

These two modules can be discussed together. They let you mark rather less specific attributes of MIDI events than most of the other modules. Because the meaning of these attributes is a function of the type of event, you will generally want to pre-restrict the events you pass to these elements to be only those of interest.

A quick word on the structure of MIDI events. A single event is represented as one to three bytes. The first specifies the type of event (and the channel, if appropriate). The second -- except for single-byte 'system' events -- is an 'index' as to the exact target of the event... the note to be played, the controller to be addressed, or the program-number to be set. etc. The third, where present, always represents a 'value' -- note velocity, control setting, and so on. (Pitch Bend is an exception -- the second and third bytes are combined into a value of higher precision.) If you're not already familiar with these technicalities, please read up on it in one of the many books on the subject.

A ValueRange element will mark all three-byte events (except Pitch Bend) according to their third, 'value', byte. IndexRange does the same for the second byte of two- and three-byte events (again ignoring Pitch Bend). (The first byte can of course be handled by a suitable combination of MsgMarker and ChanMarker elements.)

As with other range markers, the specific mark is selected from a drop-down menu, as is whether marks should be set within or outside the selected range. Range is inclusive of the set slider positions (Low should be less than or equal to High!).


TimeSort

This element re-orders incoming events according to their time-value [see Event Timing]. It is a multiconnector element, with one input (the original stream) and two outputs (a 'Through' output for the original, and a 'Sorted' copy).. Events are sent out the 'Sorted' connector at their specified time (or immediately if this moment has already passed). It has no control panel.

Used by itself, it will have no effect, as all events by default have "now" as their time value. One or more MidiDelay elements must precede it to usefully alter this. If you are messing with event timing to produce multiple echoes for example, you may also need a following DeGlitch element to prevent ugly note cut-offs.


MidiDelay

This adds a specified time interval (in milliseconds) to the time value of an event [see Event Timing]. This has no effect on its own (as output modules ignore the time value); the event should (eventually) be passed to a TimeSort element to transmit it at the desired time.

The slider in the element's panel represents delay in milliseconds, up to one second. If you need a longer delay, you can concatenate MidiDelay elements to reach the desired value (within reason).


DeGlitch

This is a special-purpose module that needs a bit of explaining. It should be used when you have merging streams of MIDI note events that might interfere with each other.

Normally a MIDI stream (from a keyboard or whatever) is nicely ordered, with each note being turned on by a Note-On event, and off by a Note-Off. If the same note (on the same channel) sounds twice, the sequence is always On-Off-On-Off, because a key must be released before it can be struck again. However, if you have more than one stream that can possibly activate the same note, this order can be lost -- a problem often known as "ReTriggering". The particular difficulty is that if there is a second Note-On that arrives just before the Note-Off that corresponds to the first Note-On, that second note gets abruptly cut off at that point (and its Note-Off is ignored) -- undoubtedly not what was intended.

For example, if you try to use a MidiDelay/TimeSort pair to create an 'echo' (on a single channel) you are likely to get such ugly cut-offs on any sustained notes. One solution is to route the echo to a separate channel, but this wastes a channel if you actually want the same voice. A better solution is to put a DeGlitch element in the merged stream.

What this element does is to keep track of the number of Note-Ons and Note-Offs. It inserts an extra Note-Off before every "unmatched" Note-On, and "swallows" each corresponding Note-Off that actually arrives, only passing on the final one that "balances" the complete sequence. The result is a proper On-Off-On-Off....On-Off sequence that sounds as intended.

Each channel is tracked separately, so you can feed a complete MIDI sequence through it if you like. It only pays attention to Note events, not others -- such as the sustain pedal -- that might also suffer from Retriggering. These, though, don't usually need delaying and can be diverted to pass around the delay section of the diagram.

There is currently no control over this module's behaviour. Although it keeps track of both "kinds" of Note-Off events (true status-0 events, and Note-Ons with zero velocity), it only inserts the latter, assuming that most Synthesizers respond to this. If Ons and Offs arriving at the module are in fact not balanced, the element will lose track -- rather defeating its purpose. There is no 'reset' button, so the only way of recovering at the moment is to elide the element and insert a new copy.


Switcher

The Switcher is somewhat different from other MusicWeaver modules. It should be considered more a part of the Weaver itself -- like 'JoinPaths' -- because it is totally agnostic as to the type of data flowing through it, but it will be dealt with here for convenience.

A Switcher is intended to direct all the data in an incoming path onto a selection from two output paths. It may be sent to one or other path, to both, or to neither. 'Director' messages sent to its 'Control' input are used to determine this. (It can also be set directly from the control panel.)

You'll notice that a Switcher element is unique (at the moment) in having three output pips. Two of these are the possible output connections ('Through' and 'Diverted'); the third is simply a pass-through of the 'Control' input if this should be wanted. There are two inputs: the incoming data (labelled 'Through', to match the undiverted output connector), and 'Control', where director messages will arrive.

'Director' messages are distinct from all other data flowing around a diagram, though they can use the same paths if it's convenient (usually probably not...). They are generated only by modules specifically designed to do so [see following sections] and are recognized only by the Switcher. Other elements simply ignore them.

The director format is parallel in many ways to the marks that can be set on MIDI events, though there are sixteen possible tags rather than eight. Any subset of these tags may be set in a message (depending on the source), and a Switcher will respond to them (or not) according to the checkboxes set in its panel. The arrangement of the checkboxes is similar to the Splitter, too, but of course the effect is on an entire data stream, rather than individual MIDI events.

At the top of the Switcher's control panel is an Indicator/Selector that shows the current state; clicking on this will bring up a menu allowing you to set the state manually. The possible states are Pass, Divert, Dupe, and Stop. In Pass, all data just goes straight on out the 'Through' output. With Divert, the data only appears on the 'Diverted' output; Dupe sends it to both, and Stop blocks it altogether.

The rest of the panel is taken up with the array of checkboxes that determine its response to director messages. A marked checkbox in a column will cause a matching mark in an incoming director message to set the switcher to the corresponding state (which will be reflected in the indicator above). You can check as many boxes as you wish in a column, but only one in each row. (If a message should have more than one tag set, and these happen to match conflicting checkbox settings, columns to the right take priority.)

Be careful that you connect to the intended inputs and outputs. The default (first connected) input and output are for data ('Through'). Use the popup menu on the connector after the link is made to ensure you are connected as you think.

TriggerSwitch

A TriggerSwitch element is the most basic source of director messages [see the Switcher above]. It will generate such a message each time anything arrives at its input. ( "Anything" actually means a data packet, but in the MusicWeaver context this is essentially equivalent to a MIDI event.) The mode of use is to filter off the desired trigger events from the event stream (using marker and splitter elements) and pass only these to the TriggerSwitch input.

A director message needs at least one of its tags set to have any effect on a Switcher. The TriggerSwitch control panel has a set of checkboxes to select the ones you want. It also has a button to trigger a message directly if you wish.

The element has only one input ('Trigger'). The outputs are 'Switch Out', where the director messages appear, and a pass-through of 'Trigger'.


UseIndex

This is another -- more specialized -- way of generating director messages [see the Switcher in the Universal Modules docs]. Its intended purpose is to turn Program Change events into director messages, but it was written rather more generally than this so that future modules can make use of it in other ways. (The message it generates is actually in a different format from TriggerSwitch messages, but you don't need to be concerned with that until other modules than the Switcher make use of it.) There is no control panel.

The element will generate a director message that effectively has a tag set to match the 'index' byte of each arriving MIDI event. [see IndexRange]. To respond only to Program Change events, the stream should be filtered to pass only these to the element, as most MIDI events have an 'index' value. It will generate a suitable message for all 128 possible index numbers, but the Switcher can only respond to the first sixteen of these, so you are similarly limited in the Program Change numbers that will be useful.


Copyright and Distribution of the MusicWeaver

This documentation, the Weaver program, and all associated modules, are Copyright 1997-9 by Peter J. Goodeve. All rights are reserved.

The MusicWeaver is ShareWare. If you use it for more than evaluation purposes, you should send $20 US (15 pounds UK is also suitable -- or even 20 Euro!) to:

	Peter Goodeve
	3012 Deakin Street #D
	Berkeley, California 94705, USA

(You may send cash, but if you do, make sure it is not obvious to those with felonious intent!)

If you register, you will be eligible to receive a modiule that will record and write Midifiles -- this will not be distributed otherwise. The most convenient way to receive this will be via e-mail, but if you would prefer it mailed to you on floppy disc , please indicate this (and the platform you are running on) in your registration. Registered users will also be kept informed of updates to the rest of the suite.

You are permitted to distribute the Weaver program, the current modules, and documentation in the form of the supplied ZIP archive without charge for non-commercial purposes, provided that the whole package is kept intact. For commercial use or distribution (other than charging a reasonable media and copying fee) please contact the author.

Please note that future releases of the MusicWeaver may be fully commercial, and distribution will be restricted. However, the firm intention is for the main Weaver program to remain freely distributable.. Only the modules themselves will be charged for. Developers interested in writing their own modules for MIDI or any other purpose, please contact the author.



Author:

				Pete Goodeve
				Berkeley, California

		e-mail:	pete@jwgibbs.cchem.Berkeley.EDU
				pete.goodeve@computer.org
========================