<html>
<HEAD>
<TITLE>MusicWeaver README</TITLE>
</HEAD>
<BODY bgcolor="#F0FDFF">
<center><H1>
MusicWeaver README
</H1>
<h3>Release 2.4 &mdash;  for  BeOS R5 </h3>
<h3>May 2006</h3>
</center>
<H2>
Update Notes
</H2>
I've had a sudden spurt of code generation, so there are a few new modules
that I guess I shouldn't keep to myself.  However, I <i>am</i> skimping on
the documentation effort this time.  This means in particular that the main
documentation has not been updated at all for the new modules.  They all
have (hopefully adequate) help files, but no expanded docs.  There are brief
details of the new stuff <a href="#release2.4"> below</a>.  This README is
simply the 2.3 version with these bits tacked on.
<P>
<H2>
What is it?
</H2>
The MusicWeaver is a suite of components &mdash; a master program and a batch
of add-ons &mdash; from which you can build configurations for creating, playing,
and in particular "morphing", MIDI streams.  It is intended particularly for
live performance (via connections to external synth and keyboard), but it
can also do endless useful things to prerecorded sequences, and of course
can record the results.
<P>
One of its simpler uses is to do what your MIDI keyboard controller may also do,
but much more conveniently.  A typical controller can be programmed by some
arcane sequence of button presses to send MIDI events to certain channels, or
to send Program Change events and so on.  With the MusicWeaver, you can build
configurations to do this -- and more -- from visually comprehensible on-screen
control panels.  Or of course you can trigger all this from a simple button
on your controller too.
<P>
Beyond this, you can transpose, delay ("echo"), reroute, merge, and so on,
to get rich effects from simpler input.
<P>
<a name="release2.4">
<H2>
Release 2.4
</H2></a>
The following modules are new:

<ul>
<li><b>SysExGen</b> &mdash;
At long last the MusicWeaver can generate arbitrary System Exclusive sequences.
This element accepts text packets defining the desired output (presumably from
a StreamView or ReadFile).  The format is simple: a sequence of numeric byte
values (0..127) enclosed in square brackets.
<li><b>MasterVolume</b> &mdash;
This sends the special System Exclusive "Master Volume" message to set the
output level of <i>all</i> channels of a sound source.
<li><b>ValueAdjust</b> &mdash;
This is much like the old "VelAdjust" element, excepts that it adjusts the
value byte of <i>any</i> MIDI event that has a value.  It is intended, for
example, to modify the response of a "D_Controller" to "GamePort" input.
(I use it to separate up and down joystick motion to different controllers,
for instance.)
<li><b>D_Aftertouch</b> &mdash; (In the "Experimental" folder)
This accepts e.g. "GamePort" element signals to generate Aftertouch ("Channel
Pressure") events. (And of course has a slider to generate them directly.)
<li><b>RanDelay</b> &mdash;
Similar to "MidiDelay", except that the delay applied to each packet is random
within the set maximum.  (Beware that under some circumstances there can be
several events in a single packet: they will all get the same delay.) 
<li><b>ChordSelect</b> &mdash;
This is certainly the most complex module in the suite.  It arose from a
short interchange on usenet.  Someone wanted to do (in Windows, of course (:-))
things that I habitually do with the MusicWeaver, but he also expressed the
desire to have each note of a chord go to a different MIDI channel.  Both I
and someone else initially suggested that it would be tricky, because the
keys of a chord are not hit simultaneously, so there would be nasty glitches.
<P>
However, I then realized that MusicWeaver has both a module that recognizes chords,
and another that can pack closely timed notes into a simultaneous packet, so it
seemed the idea might have possibilities.  Hence I wrote this module.
Turns out the results can sound quite pleasant &mdash; provided you don't
expect magic!
<P>
To recognize specific chords, it needs an immediately preceding "KeyTrack"
element, but if it is just to pick out arbitrary groups of <i>n</i> notes
as 'chords' it can work by itself.  It sends out the note groups it responds to
on a separate path with each note optionally tagged in some way, either by
being on its own channel or having its own combination of MusicWeaver 'marks'.
For further information &mdash; experiment...!
</ul>
These have been updated:
<ul>
<li><b>MidiMon</b> &mdash;
Now shows the MusicWeaver 'marks' attached to an event.
<li><b>Analyze</b> &mdash;
Fixed a typo in the sourcefile that prevented it seeing its Help file.
[And apologies to those who would rather see it spelled with an 's'!]
<li><b>Controller</b> and <b>D_Controller</b> &mdash;
Have a fix to initialization message generation that was important to me
but probably nobody else.

</ul>

<P>
<H2>
Release 2.3
</H2>
For the first time in six years (!) the Weaver main program has itself had
a slight update (now "3.1").  It now has an option to save only the Parameters
(the panel settings of the elements) of a configuration, rather than the complete
diagram.  A diagram can be reset to its saved settings by dropping the file
into that window.
<P>
There are a couple of new (or at least previously undistributed) modules:
<B>MidiLink</B> and <B>SysExMon</B>.  The former is a better way than the
old <B>MidiConn</B> of connecting to external MIDI, as it uses the R5
MidiKit;  you can connect to any producer or consumer of MIDI, including
an external hardware port.  SysExMon lets you peek into the contents of
any System Exclusive message contained in a midifile or arriving from
an external device.
<P>
Other modules have had enhancements or bug fixes of some kind. These are
all noted in <a href="Documentation/Newer_MIDI.html">Newer_MIDI.html</a>.
In particular <B>RePlay</B> now has "Play on Load" and "BLAST OUT" options
that make it useful for setting your hardware to a desired state.
<B>Controller</B> has presettable buttons and allows for a custom Controller
list.
<P>
This distribution also has most of the StreamWeaver modules included, as
they can be useful and don't take up that much space.  I doubt there will be
any separate package in the future.
<P>
Much of the system (including the new Weaver program itself) has now been
compiled for R5 (or later) only.  I assume it is highly unlikely anyone is still
using an earlier OS version!  It should be happy with Zeta etc.  If not,
let me know.  The 3.02 Weaver exposed an incompatibility with BeOS BONE,
and needed a special version for that OS.  3.1 has the fix built in, but
will work with non-BONE also (it simply always loads the MIDI library).
<P>
<h2>
Folder Organization and Installation
</h2>
This suite of files can be unpacked anywhere [which presumably you have
already done as you are reading this!].  You can move the top-level folder
anywhere else, provided you keep its sub-folder hierarchy intact.
No other installation should be required, but it seems to be possible (if you
have an old version of the Weaver around for instance) for the Tracker not to
see the proper icons, or for modules from the supplied demo configurations to
fail to load.  If this is so, you can double-click on the "Update&nbsp;Tracker"
script to correct things.
<P>
Although the suite itself expects things to be where it can find them, you can
save configurations anywhere you prefer without problem.  (Configurations use
complete pathnames internally, but if an element can't be found with the stored
name because the suite has been moved, it will look in the current hierarchy for it.)
<P>
The folder organization looks like this:
<ul type="none">
<b><big>Weaver</big></b>
<br>&mdash; Top-level folder with main program, common modules and demo configurations.
<ul type="none">
<li><b><big>Weaver/MusicWeaver</big></b>
<br>&mdash; All the MusicWeaver modules.
<li><b><big>Weaver/StreamWeaver</big></b>
<br>&mdash; Text and data stream processing modules
<li><b><big>Weaver/Experimental</big></b>
<br>&mdash; Gameport and associated (not that experimental any more&hellip;!).
<li><b><big>Weaver/Documentation</big></b>
<br>&mdash; All the main HTML docs.
<ul type="none">
<li><b><big>Weaver/Documentation/Images</big></b>:
</ul>
<li><b><big>Weaver/Help</big></b>
<br>&mdash; Help files for the modules, mostly in sub-folders:
<ul type="none">
<li><b><big>Weaver/Help/MusicWeaver</big></b>:
<li><b><big>Weaver/Help/StreamWeaver</big></b>:
<li><b><big>Weaver/Help/Test</big></b>:
</ul>
<li><b><big>Weaver/SEQUENCES</big></b>
<br>&mdash; Demo RePlay sequences mentioned in the MWExamples doc.
<li><b><big>Weaver/TEST</big></b>
<br>&mdash; Simple useless modules for playing with.
<li><b><big>Weaver/Tables</big></b>
<br>&mdash; for Controller custom list (sample included), and
example tables for the KeySig module.
</ul>

<CENTER>====================</CENTER>
<BR>
Details on how to use the main Weaver program and all the modules
can be found in the Documentation folder.
These links will take you there:
<P>
<FONT SIZE=+1><B>
<A HREF="Documentation/Weaver.html">Main Weaver Documentation</A>
</B></FONT>
&mdash; The basic concepts
<H3>Module Descriptions:</H3>
<A HREF="Documentation/MIDI.html">MIDI Modules</A>
&mdash; the basic modules of the MusicWeaver suite
<BR>
<A HREF="Documentation/Newer_MIDI.html">Newer Modules</A>
&mdash; Various recently added modules, plus Midi Event Monitoring (MidiMon &amp; StreamView),
and GamePort and associated modules.
<BR>
<A HREF="Documentation/LinkMidi.html">Linkage Modules</A>
&mdash; Connecting to other applications with the R5 MidiKit
<BR>
<A HREF="Documentation/RePlay.html">RePlay</A>
&mdash; MIDI sequence recorder/player
<BR>
<A HREF="Documentation/MidiFile.html">MidiFile</A>
&mdash; Midifile recorder/player
<P>
<B>Other Module Sets:</B>
<BR>
&nbsp;&nbsp;&nbsp;<A HREF="Documentation/Universal.html">Universal Modules</A>
&mdash; useable in all suites
<BR>
&nbsp;&nbsp;&nbsp;<A HREF="Documentation/StreamWeaver_Modules.html">StreamWeaver Modules</A>
&mdash; The text handling etc. modules now included.
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="Documentation/TestModules.html">"Test" Modules</A>
&mdash;&mdash; used in the (Weaver Documentation) Tutorial
<BR>
<P>
<FONT SIZE=+1><B>
<A HREF="Documentation/MWExamples.html">Example MusicWeaver Configurations</A>
</B></FONT>
-- Explore some of the ways to use this package with these demos.
<P>
<FONT SIZE=+1><B>
<A HREF="Documentation/MWindex.html">MusicWeaver Documentation &mdash;
Master Table of Contents</A>
</B></FONT>
<P>
<BR> 

<CENTER>====================</CENTER>
<BR>

<H3>
<A NAME="Author">Author:</A>
</H3>
<pre>
			Pete Goodeve
			3012 Deakin St #D
			Berkeley, California 94705
			USA

		e-mail:	pete@jwgibbs.cchem.Berkeley.EDU
				pete.goodeve@computer.org
</pre>


<BR><BR><I>
The documentation, the Weaver program, and all associated modules,
are Copyright 1997-2006 by Peter J. Goodeve.  All rights are reserved.
For details, see:
<A HREF="Documentation/MIDI.html#Distribution">Copyright and Distribution</A></I>
<P>


</body>
</html>
