eclab · danielappelt · Jun 23, 2017 · Jun 23, 2017 · Jun 23, 2017 · Jun 23, 2017
diff --git a/README.md b/README.md
@@ -1,140 +1,105 @@
-# edisyn
-Synthesizer Patch Editor (Version 7)
+![Edisyn Splash Banner](https://raw.githubusercontent.com/eclab/edisyn/master/pics/Banner.png)
 
+# Edisyn
+Synthesizer Patch Editor (Version 17)
+
 By Sean Luke (sean@cs.gmu.edu)
 
+I've been asked where my Patreon page is.  So, sure, here's my <a href="https://www.patreon.com/SeanLuke">Patreon page</a>.
 
-## About
-
-Edisyn is a synthesizer patch editor library written in pure Java.  
-
-Edisyn presently supports:
-
-* Waldorf Blofeld and Waldorf Blofeld Keyboard (Single and Multi Modes)
-* Waldorf Microwave II, XT, and XTk (Single and Multi Modes)
-
-Ultimately Edisyn will have some more written for it as well as I get time; and of course the patch
-editors I can write are restricted to the synths I own and can test on!  
-Edisyn has no graphical interface editor system like 
-Ctrlr, but it's designed to make the GUI pretty easy to write (well, for me anyway).
+Related projects:  
 
-At present Edisyn *only runs on OS X* (well, I've only tried it on OS X, that's its target).  If you try running
-it elsewhere, you're on your own.  We have confirmation that it runs fine under Linux.
+* [Flow](https://github.com/eclab/flow), a fully-modular, polyphonic, additive software synthesizer.
+* [Gizmo](https://cs.gmu.edu/~sean/projects/gizmo/), an Arduino-based MIDI Swiss Army knife
 
 
-## Installation
 
-For the time being, to install Edisyn you need to do the following two things.
-
-1. Install the Java JDK.
-2. Put the file `jar/edisyn.7.jar` where you like (it's Edisyn's executable).
-
-
-## Running 
-
-- *On OS X:* Double click on the file `edisyn.7.jar`
-- *On Windows:* I don't know.  Anyone?
-- *On Linux:* In Ubuntu, you'll first need to change the Properties of the jar file (see the "Open With" tab) to your Java VM.  Thereafter you can just double-click on the file.
+## About
 
-Edisyn should launch and either present you with a window asking what MIDI interface you want to use, or tell
-you that there are no available MIDI interfaces, and that you'll need to work offline.
+Edisyn is a synthesizer patch editor library written in pure Java.   It runs on OS X, Linux, and Windows.  
 
+Edisyn is particularly good at exploring the space of patches.  It has to my knowledge the most sophisticated set of general-purpose patch-exploration tools of any patch editor available.
 
-### The Editor Pane
+Edisyn presently supports:
+
+* DSI Prophet '08 
+* E-Mu Morpheus and Ultraproteus (Single, Hyperpreset, and MidiMap modes)
+* Waldorf Blofeld and Waldorf Blofeld Keyboard (Single and Multi Modes)
+* Waldorf Microwave II, XT, and XTk (Single and Multi Modes)
+* Oberheim Matrix 1000
+* PreenFM2
+* Kawai K1, Kawai K1m, and Kawai K1r (Single and Multi Modes)
+* Kawai K4 and Kawai K4r (Single, Multi, Drum, and Effect Modes)
+* Kawai K5 and K5m
+* Yamaha DX7 Family (Single)
+* Yamaha TX81Z (Single and Multi Modes)
+* Korg SG Rack (Single and Multi Modes) and Korg SG Pro X (Single Mode)
+* Korg Microsampler
+* Korg MicroKorg
+* Korg Wavestation SR (Performance, Patch, and Wave Sequence Modes)
 
-The editor pane should be self-explanatory.  There are four tabs which together cover all of the parameters of 
-the synthesizer.  The first tab, *Oscillators and Filters*, also contains an area called *Waldorf Blofeld* (or
-some other synth) which
-lets you set the patch name and category, bank, number, and Device ID.   The bank, number, and ID are mostly
-for saving out to sysex files: whenever you upload or download patch to/from the synth, you'll be prompted
-to revise those if necessary.
+Edisyn has infinite levels of undo, CC and NRPN mapping and learning, offline modes, randomization, merging, nudging, hill-climbing, patch constriction, per-parameter customization, real-time parameter updates, test notes, etc.
 
-### The File Menu
+## Manual
 
-* *New* creates a new editor pane, set to the default (the synth's Init patch setting).  Note that only the frontmost editor pane will receive MIDI.  So if you for
-some reason set up both editor panes with the same interface, then request MIDI from one pane, then quickly
-switch to the other pane, you could in theory get the MIDI sent to the other pane.  So don't do that.
+Edisyn has an [extensive manual](https://github.com/eclab/edisyn/raw/master/docs/manual/Edisyn.pdf) which describes how to run it, and (if you are so inclined) how to make new patch editors.
 
-* *Load...* loads a sysex file into the existing editor pane.  It's called Load instead of Open because it 
-doesn't open a new window.
+## Install and Run Edisyn
 
-* *Close Window* closes, well, you know, it closes, um, the window.
+Edisyn is cross-platform and will run on a variety of platforms (Windows, Linux) but I am personally developing on and for OS X.  I'd appreciate feedback and screenshots of it running on Windows and Linux so I can tweak things.
 
-* *Save* and *Save As...* save to a sysex file.
 
-* *Export Diff to Text...* saves out to a text file a line-by-line description of every parameter which is *different* 
-from the default Init patch setting, plus the current value it's set to.  The patch value is either a string (in the
-case of the Patch name) or a number from 0...127: this may not be that useful to you, but the parameter names might
-be useful if you want to publish your patch on a sebsite and need to know which parameter settings to mention. 
+### Installation and Running on OS X 
 
+First install Edisyn from the [Edisyn.app.zip](https://github.com/eclab/edisyn/raw/master/install/Edisyn.app.zip) file located in the "install" directory.  Sadly, it's a whopping 70MB because it includes the Java VM.  :-(
 
-### The MIDI Menu
 
-Note that you can *send* a patch to the synthesizer and you can *write* a patch to the synthesizer.  The former
-just temporarily updates the synth's current patch memory so you can play it.  The latter actually writes the 
-patch to an address in the synth, replacing whatever is there.
+Sierra has really locked down the ability to run an application that's not from a commercial, paying Apple Developer.  And I'm not one.  So you will have to instruct Sierra to permit Edisyn to run.
 
-* *Request Current Patch* asks the synthesizer to load the current patch memory into the editor.  Note that on
-some machines (like the Waldorf Blofeld) when the patch is loaded, the bank and patch number are invalid and will
-be reset to some defaults, which might be confusing!
+Let's assume you stuck Edisyn in the /Applications directory as usual.  Then:
 
-* *Request Patch...* asks the synthesizer to load a specific patch into the editor.  If the synthesizer complies,
-once the patch is loaded, Edisyn will then send the patch to the synthesizer.
+1. Run the Terminal Program (in /Applications/Utilities/)
+2. Type the following command and hit RETURN: `   sudo spctl --add /Applications/Edisyn.app`
+4. Enter your password and hit RETURN.
+5. Quit the Terminal Program
 
-* *Request Merge* asks the synthesizer to load a specific patch into the editor.  If the synthesizer complies,
-then the patch is *merged* with the existing patch, meaning that some *percentage* of parameters in the existing
-patch are replaced with the old patch.  Then Edisyn will then send the patch to the synthesizer.
+Now you should be able to run Edisyn.  Let me know if this all works.
 
-* *Randomize* randomizes the editor's current patch, then sends it to the synthesizer.
 
-* *Reset* resets the editor's current patch to its initialized state, then sends it to the synthesizer.
+### Installation and Running on Windows
 
-* *Send Patch* sends the current patch to the synthesizer.  This isn't actually used much since other commands
-send the patch automatically.
+I believe that the following should work:
 
-* *Write Patch...* writes the patch to a given location in the synthesizer.
+1. [Download and install Java 11](http://www.oracle.com/technetwork/java/javase/downloads/index.html).  The JRE should work fine.
 
-* *Change MIDI* sets or updates the MIDI interface.
+2. Download Edisyn's jar file, called [edisyn.jar](https://github.com/eclab/edisyn/raw/master/jar/edisyn.jar), presently located in the "jar" directory.
 
-* *Disconnect MIDI* disconnects the MIDI interface.
+3. Double-click on edisyn.jar to launch Edisyn.
 
-* *Send All Sounds Off* sends the All Sounds Off message to all channels.
+#### Important Note for Windows User
 
-* *Send Test Note* sends a 1/2 second test note to the primary channel.
+Java versions earlier than 11 (or so) do not handle high-resolution displays properly, so Edisyn will appear teeny-tiny.  You need to upgrade to 11.
 
+Also Edisyn makes heavy use of Java preferences to store persistence information: what menu option you chose last time, what should be the default synth editor to pop up, and so on.  However there is a longstanding Java/Windows bug which makes Java preferences not work out of the box in Windows for earlier versions of Java.  I think this is fixed as of Java 11 but you should check and let me know.
 
-### The MIDI Interface
 
-Edisyn makes up to three MIDI device connections.  The *Receiving Device* is the MIDI device from which we will accept
-patches.  This is usually your synthesizer.  The *Sending Device* is the MIDI device to which we will send 
-patches and parameter changes.  We'll also need a channel for the Sending Device so we can send test notes.
+### Installation and Running on Linux
 
-Optionally you can route your controller keyboard through Edisyn to play the sounds directly if you wish.  To do this,
-the *Keyboard Device* is the MIDI Device of your controller keyboard.  You'll also specify an incoming keyboard
-channel of course.  This can be set to "Any" for any channel (Omni).
+I'm told that Edisyn works fine if you have installed *Java 8*.  After this:
 
-### Sending and Recieving Parameters
+1. Download [Edisyn's jar file](https://github.com/eclab/edisyn/raw/master/jar/edisyn.jar) located in the "jar" directory.
 
-If you change a widget in the editor, Edisyn will send the appropriate sysex command to the synthesizer to change it on
-the synth as well.  Additionally, if you change a parameter on the synthesizer and it forwards a *sysex* command to Edisyn,
-then Edisyn will update the appropriate widget in the editor.  At present Edisyn does't support CC commands from the
-synthesizer (maybe later).  So (for example) on the Blofeld you'll need to change the machine to *send sysex* -- not CC only -- when changing parameters on the synth.
+2. You'll need to figure out how to make it so that double-clicking on the jar file launches it in java.  In Ubuntu, here's what you do: right-click on the jar file icon and choose "Properties".  Then select the "Open With" tab, and select your Java VM (for example "Open JDK Java 8 Runtime").  The press "Set as Default".  This makes the Java VM the default application to launch jar files.
 
-### Per-Synth Specific Notes and Bugs
+3. Thereafter you should be able to just double-click on the file to launch Edisyn.
 
-Gotchas and important things to know are contained in the <b>About</b> Tab in each synth editor window.  You should read it before using the editor for that synth.
 
-## Caveats
+### Running from the command line (OS X, Windows, Linux)
 
-To work around some bugs in OS X Midi and CoreMIDI4J, Edisyn's architecture at present does not let you
-plug in new devices (or remove them) after Edisyn has been launched.  If you need to do so, restart Edisyn
-(for now). 
+1. Make sure Java is installed.
 
-Randomize isn't very useful right now.  I'm working on it.
+2. Download [Edisyn's jar file](https://github.com/eclab/edisyn/raw/master/jar/edisyn.jar) located in the "jar" directory.
 
-Everything has to be sent via sysex for the moment: I don't have code written to make it easy to send CC or NRPN
-if you wanted to build a patch which did that.
+3. Run Edisyn as:   `java -jar edisyn.jar`
 
-Popping up a new panel is slow.  Profiling suggests that the primary reason for this is that JComboBox construction
-is slow.  So I can't get around it.
 
diff --git a/docs/manual/0.png b/docs/manual/0.png
diff --git a/docs/manual/1.png b/docs/manual/1.png
diff --git a/docs/manual/2.png b/docs/manual/2.png
diff --git a/docs/manual/3.png b/docs/manual/3.png
diff --git a/docs/manual/4.png b/docs/manual/4.png
diff --git a/docs/manual/5.png b/docs/manual/5.png
diff --git a/docs/manual/6.png b/docs/manual/6.png
diff --git a/docs/manual/7.png b/docs/manual/7.png
diff --git a/docs/manual/ConstrictorPanel.png b/docs/manual/ConstrictorPanel.png
diff --git a/docs/manual/Edisyn.pdf b/docs/manual/Edisyn.pdf