diff --git a/README.md b/README.md
index 05e6e4b..a032983 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,12 @@
-# Audible Planets
+# Audible Planets (v1.1)
An expressive, quasi-Ptolemaic semi-modular synthesizer.
-
+
-
+
-
-
-
-
-
## Demos
@@ -34,7 +29,7 @@ Four bodies revolve with uniform circular motion, each around one of the others
### Gratitude
-I'll speak later about some of the sources of inspiration for this project, but don't want to go any further without acknowledging that none of this would have been possible for someone like me—a humanist with an idea, not a software engineer—without the wealth of open-source tools, instruction, and advice provided freely by the community of professionals and enthusiasts. I'm especially grateful for the existence of the [JUCE](https://github.com/juce-framework/JUCE) framework and for the many helpful extensions to it provided by [Gin](https://github.com/FigBug/Gin) (which did a LOT of heavy lifting) and the visualization tools in [Melatonin Blur](https://github.com/sudara/melatonin_blur). Early prototypes were built in [VCV RACK](https://vcvrack.com/), which was a relatively easy way to get started with audio programming and boasts a vibrant community. As a novice who needs a lot spelled out, I got quite a lot out of [Will Pirkle](https://www.willpirkle.com/)'s teacherly books. Finally, mostly by lurking and poring over old posts, but sometimes by posing ill-formed questions and follow-ups of my own, I learned a lot on the Discord server for [The Audio Programmer](https://www.theaudioprogrammer.com/), mostly that other people who do this kind of thing regularly know a lot more than I am ever likely to.
+I'll speak later about some of the sources of inspiration for this project, but don't want to go any further without acknowledging that none of this would have been possible for someone like me—a humanist with an idea, not a software engineer—without the wealth of open-source tools, instruction, and advice provided freely by the community of professionals and enthusiasts. I'm especially grateful for the existence of the [JUCE](https://github.com/juce-framework/JUCE) framework and for the many helpful extensions to it provided by [Gin](https://github.com/FigBug/Gin) (which did a LOT of heavy lifting). Early prototypes were built in [VCV RACK](https://vcvrack.com/), which was a relatively easy way to get started with audio programming and boasts a vibrant community. As a novice who needs a lot spelled out, I got quite a lot out of [Will Pirkle](https://www.willpirkle.com/)'s teacherly books. Finally, mostly by lurking and poring over old posts, but sometimes by posing ill-formed questions and follow-ups of my own, I learned a lot on the Discord server for [The Audio Programmer](https://www.theaudioprogrammer.com/), mostly that other people who do this kind of thing regularly know a lot more than I am ever likely to.
# Operation
@@ -42,7 +37,7 @@ Enough of that. How to use this thing?
## Installation
-The plugin is available in VST3, LV2 (both Windows, Mac OS, Linux), and AU (Mac OS only) formats, [here](https://github.com/gregrecco67/AudiblePlanets/releases). Since there is no installer, you will have to place the plugin file in the right place yourself. On Windows, place the VST3 file in /Program Files/Common Files/VST3. On Mac OS, place the VST3 file in ~/Library/Audio/Plug-Ins/VST3 and/or the AU file in ~/Library/Audio/Plug-Ins/Components. (You will need the AU component if you plan to run the synth in Logic or GarageBand.) On Linux, place the VST3 file wherever your DAW looks for it, which should include ~/.vst3 as a default. More info on default VST3 file locations [here](https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Locations+Format/Plugin+Locations.html) and LV2 locations [here](https://lv2plug.in/pages/filesystem-hierarchy-standard.html).
+The plugin is available in VST3, LV2 (both for Windows, Mac OS, Linux), and AU (for Mac OS only) formats, [here](https://github.com/gregrecco67/AudiblePlanets/releases). Since there is no installer, you will have to place the plugin file in the right place yourself. On Windows, place the VST3 file in /Program Files/Common Files/VST3. On Mac OS, place the VST3 file in ~/Library/Audio/Plug-Ins/VST3 and/or the AU file in ~/Library/Audio/Plug-Ins/Components. (You will need the AU component if you plan to run the synth in Logic or GarageBand.) On Linux, place the VST3 file wherever your DAW looks for it, which should include ~/.vst3 as a default. More info on default VST3 file locations [here](https://steinbergmedia.github.io/vst3_dev_portal/pages/Technical+Documentation/Locations+Format/Plugin+Locations.html) and LV2 locations [here](https://lv2plug.in/pages/filesystem-hierarchy-standard.html). On a Mac, you will need to take the additional step of authorizing the plugin to run, either from the Privacy & Security settings panel, or by typing `xattr -dr com.apple.quarantine ` in a Terminal window.
Or, you can build it from source:
```
@@ -69,42 +64,32 @@ A few example presets are located [here](https://github.com/gregrecco67/Audible-
## Pages
-The synth has five pages: "Main," "Effects," "Randomization," "MSEG," and "Macros/Aux." The Main page contains the main controls for sound generation. The Effects page contains the built-in effects arranged in one or two chains. The Randomization page contains controls for randomizing the main parameters and modulation settings in a variety of groups, as well as a slightly different interface for the envelopes and oscillators. The MSEG page contains controls for four multi-segment envelope generators, which can act as modulation sources. The Macros/Aux page contains macros, controls that can be used to modulate several parameters at once, and an auxiliary oscillator distinct from the main orbital model.
+The synth has two pages: "Main" and "Effects." The Main page contains the main controls for sound generation and modulation. The Effects page contains the built-in effects arranged in one or two chains.
### Main Page
-Mostly standard envelope, oscillator, and LFO controls take up the majority of screen real-estate here. I'll describe some controls that are less often seen. Envelopes can be made to repeat, either freely ("Free") or in subdivisions or multiples of the beat ("Sync"). With the "Tones" knob set to minimum and the "Saw" switch set to "Off," the motion of the body is uniform and circular. In this mode, adjusting the relative starting points of the various oscillations (with the "Phase" control) can change the sound a lot. When "Tones" is turned up, the motion of the body is no longer uniform and circular, but is modulated with extra whole-number multiples of the main frequency up to 5. The "Saw" switch turns the motion into a diagonal sawtooth wave. Both enrich the spectrum of the oscillator, but have different effects on the final sound depending on the level of the "Demodulate" control, which effectively determines the amount of phase modulation. The "Sidechain" switch changes the motion of the first oscillator to a semicircular projection of whatever audio is piped in. In addition to these ways to enrich the individual "spectrum" of each oscillator, there is a general "Blend" control in the "Timbre" section, which takes the interpretation of the bodies' positions as phases, not of a pure sine wave, but of a mix of sine, saw, and square waves. The presence of "Detune," "Spread," and "Pan" controls for each oscillator indicates that the orbital algorithm described in the overview above is computed for multiple voices over two channels, and slight variations in position and frequency between the latter can bring movement, width, and depth to the sounds produced. Finally, the LFOs have delay and fade-in controls, which affect the per-voice (or "poly") modulation source. (More on that distinction when we discuss modulation.)
+The four revolving bodies are controlled by the four panes of the OSC section. Their relative speeds can be adjusted with the "Coarse" and "Fine" controls, or an absolute frequency can be set with the "Fixed" control. With the "Tones" knob set to minimum and the "Saw" switch set to "Off," the motion of the body is uniform and circular. In this mode, adjusting the relative starting points of the various oscillations (with the "Phase" control) can change the sound a lot. When "Tones" is turned up, the motion of the body is no longer uniform and circular, but is modulated with extra whole-number multiples of the main frequency. The "Saw" switch turns the motion into a diagonal sawtooth wave. Both enrich the spectrum of the oscillator, but have different effects on the final sound depending on the level of the "Demodulate" control, which effectively determines the amount of phase modulation. The "Sidechain" switch (in "Global" )changes the motion of the first oscillator to a semicircular projection of whatever audio is piped in. In addition to these ways to enrich the individual "spectrum" of each oscillator, there is a general "Blend" control in the "Timbre" section, which takes the interpretation of the bodies' positions as phases, not of a pure sine wave, but of a mix of sine, saw, and square waves. The presence of "Detune," "Spread," and "Pan" controls for each oscillator indicates that the orbital algorithm described in the overview above is computed for multiple voices over two channels, and slight variations in position and frequency between the latter can bring movement, width, and depth to the sounds produced. Each body's radius can be modulated by one of the four envelopes.
In the Timbre section, in addition the "Blend" control, there's one that modifies the position of the equant, the point from which the motions of bodies are observed. The function of the "Demodulate" knob has already been described, but I will add that in many cases, turning it up tends to mellow the sound, removing the sideband frequencies produced by the orbital algorithm, making it function more like a rudimentary additive synth. Furthermore, since the size of all the orbits is variable, the audible planet or planets may pass very close to the equant, or even through it, resulting in sharp corners and/or discontinuities. This could (and can) be avoided by making the outer orbits smaller, but that also reduces their contribution to the overall sound. The "Squash" control flattens the outer orbits along perpendiculars to their orbits about the equant, as seen below.
-This brings them farther from the center without diminishing their effect as much as reducing their radii would, since the modulated portion of the signal depends only on the angle about the center (or equant, if displaced). That said, if you begin with a configuration where epicycles are sufficiently small, increasing the "Squash" factor will introduce new harmonics, sharpening the sound. Finally, the "Algorithm" control switches between different arrangements of the oscillators, with the "terminal" body or bodies being indicated by parentheses. In many cases, the first algorithm 1-2-3-(4) is the harshest, and the last the least harsh, but the effects vary depending on the relative sizes of the orbits, so it's worth trying out different algorithm settings as you're trying to dial in a sound.
+This brings them farther from the center without diminishing their effect as much as reducing their radii would, since the modulated portion of the signal depends only on the angle about the center (or equant, if displaced). That said, if you begin with a configuration where epicycles are sufficiently small, increasing the "Squash" factor will introduce new harmonics, sharpening the sound. Finally, the "Algorithm" control switches between different arrangements of the oscillators, with different "terminal" bodies. In many cases, the first algorithm (1-2-3-4) is the harshest, and the last the least harsh, but the effects vary depending on the relative sizes of the orbits, so it's worth trying out different algorithm settings as you're trying to dial in a sound.
-The global parameters include controls for monosynth and legato modes, glissando and portamento at an adjustable rate, velocity sensitivity, pitchwheel range, and overall volume. There's also a dedicated per-voice filter, with cutoff, resonance, and key tracking controls, and a variety of common filter types.
+The controls in the "Global" section include controls for monosynth and legato modes, glissando and portamento at an adjustable rate, velocity sensitivity, pitchwheel range, and overall volume. There's also a dedicated per-voice filter, with cutoff, resonance, and key tracking controls, and a variety of common filter types.
-The partially open circles found in various panel headers, as the section in the top right indicates, are sources of modulation. The single-line versions are "mono" and the double-line versions "poly," which is to say the latter are different for each key press (or subsequent pressure, tilt, or slide, on MPE-capable MIDI controllers). To use any of them, click and drag from the source to the destination. Alternatively, if you want to assign the same source to several parameters, you can click on it: it will turn white, and while the synth is in this mode, you can assign modulation from that source just by dragging on the knob for the parameter you want to modulate. Press 'ESC' or 'L' to exit this "learning" mode. Almost any knob can have its setting modulated, and that goes for the effects controls on the FX page and the MSEG controls as well. When a parameter is modulated, a small orange circle appears in the upper-right corner of the control. Clicking and dragging it (or using a mouse scroll wheel while hovering) will increase or decrease the modulation amount, in a positive or negative direction, or both. (More spacious sets of modulation controls reside on the "Rand" and "MSEG" pages.) Right-clicking the small circle will give the option to remove any or all of the modulation sources attached to it, or to switch to editing the value of a different source. Small white dots on the periphery of the control indicate the modulated value or values of the parameter for whichever voices are active. Many controls accept text input, and all can be adjusted finely by dragging while holding down the control key.
-
-The orbit visualization can be slowed down or sped up with the Orbit "Speed" control and you can zoom in or out with the "Scale" control or by hovering over the orbits and scrolling the mouse wheel.
-
-### Effects Page
+The partially open circles found in the LFO, envelope, and MSEG panel headers, as well as in the "Mod Sources" section, are sources of modulation. The single-line versions are "mono" and the double-line versions "poly," which is to say the latter are different for each key press (or subsequent pressure, tilt, or slide, on MPE-capable MIDI controllers). To use any of them, click and drag from the source to the destination, or just click on it to activate "Learning" mode: it will turn white, and while the synth is in this mode, you can assign modulation from that source just by dragging on the knob for the parameter you want to modulate. Press 'ESC' or 'L' to exit this mode. Almost any knob can have its setting modulated, and that goes for the effects controls on the FX page. When a parameter is modulated, a small orange circle appears in the upper-right corner of the control. Clicking and dragging it (or using a mouse scroll wheel while hovering) will increase or decrease the modulation amount, in a positive or negative direction, or both, and a right click will allow you to select which mod source to edit or delete. More spacious sets of modulation controls are available in the "Mod Matrix" section. Right-clicking the small circle will give the option to remove any or all of the modulation sources attached to it, or to switch to editing the value of a different source. Small white dots on the periphery of the control indicate the modulated value or values of the parameter for whichever voices are active. Many controls accept text input, and all can be adjusted finely by dragging while holding down the control key.
-The effects (FX) page contains slots for up to eight built-in effects, arranged in one (when "FX Chain Routing" is set to "A -> B") or two chains ("A || B"), each with its own gain control, applied before the signal enters the chain. Ordering the effects chains differently can open up a lot of possibilities. Since the effects parameters can be modulation destinations, there's a mod sources panel on this page, too. Also, since there's room for it, there's a modulation matrix panel, showing the currently active modulations, and offering controls to bypass, adjust, or delete them. In combination, the effects on this page can add a lot of boost, especially when modulated with sources that can constructively interfere. A built-in limiter is accordingly always on and meant to keep the levels below 0 dB, but be careful nonetheless.
+The partially open circles found in the LFO, envelope, and MSEG panel headers, as well as in the "Mod Sources" section, are sources of modulation. The single-line versions are "mono" and the double-line versions "poly," which is to say the latter are different for each key press (or subsequent pressure, tilt, or slide, on MPE-capable MIDI controllers). To use any of them, click and drag from the source to the destination, or just click on it to activate "Learning" mode: it will turn white, and while the synth is in this mode, you can assign modulation from that source just by dragging on the knob for the parameter you want to modulate. Press 'ESC' or 'L' to exit this mode. Almost any knob can have its setting modulated, and that goes for the effects controls on the FX page. When a parameter is modulated, a small orange circle appears in the upper-right corner of the control. Clicking and dragging it (or using a mouse scroll wheel while hovering) will increase or decrease the modulation amount, in a positive or negative direction, or both, and a right click will allow you to select which mod source to edit or delete. (More spacious sets of modulation controls are available in the "Mod Matrix" section.) Right-clicking the small circle will give the option to remove any or all of the modulation sources attached to it, or to switch to editing the value of a different source. Small white dots on the periphery of the control indicate the modulated value or values of the parameter for whichever voices are active. Many controls accept text input, and all can be adjusted finely by dragging while holding down the control key.
-### Randomization Page
+In addition to the main "orbital" model, two additional sound sources for the sake of layering are available: an auxiliary oscillator and a rudimentary sampler. Finally, a "Macros" section allows modulation of several parameters at once by one knob, which can be assigned to respond to a MIDI CC message. Just click "Learn" beneath the knob, and then activate the control you want to assign to it on your MIDI controller. A CC number will appear below the knob to indicate the assignment was successful. Click on the "Clear" button below it to remove the assignment.
-Sound design can at times be a game of "almost, but not quite." At other times, good results can come from unexpected synergies and, frankly, from a more kitchen-sink approach. The randomization page is meant to facilitate both: gentle nudges and total crapshoots. The large modulation matrix panel offers the most fine-grained interface for adjustment, while the buttons in the columns to its right change several or even many settings at once. Generally, things in the left column add modulation or randomization and things in the right remove it. The sliders for "Number of Mods" and "Randomization Chance/Amount" control the "how many" and "how much" of these randomization buttons. The "Inharmonic" checkbox allows modulations and randomizations to be applied to the oscillator "Fine" controls and the global "Pitch" control, which quickly produce inharmonic or atonal results. The "Reset Inharmonic" button below it removes any such mods without deleting any others. Other buttons with arrows in their names refer to groups of parameters: "LFO" and "ENV" are self-explanatory, "Keys" includes velocity, MIDI note number, the pitchbend and mod wheels, and "MPE" pressure and timbre. (The latter, as well as per-note pitchbend, can be activated using the "MPE" option in the top-left menu). The parameters of whatever effects are currently active can be modulated with "Randomize FX Mods" and the order and selection of effects can be randomized with "Randomize FX Choice." The bottom row of buttons doesn't add any new modulations, but increases or decreases those that are already active. Since it's annoying to have to switch pages while one is adjusting parameters, a second set of mostly complete envelope and oscillator controls are on this page. That said, if you click once anywhere within the plugin screen, you can change tabs with the "1," "2," "3," and "4" keys on your keyboard.
-
-### MSEG Page
-
-The MSEG page exposes controls for producing arbitrary control signals, single or repeating, with many of the same parameters as the LFOs on the main page. Double-click to create points, which you can click and drag to their desired locations, or turn on "Draw" and select a draw mode from the drop-down menu. All control points will snap to grid lines they are near. Scroll with the mouse wheel to adjust the number of horizontal divisions in the grid, and scroll with a modifier key held down (e.g., control, shift, alt) to adjust the vertical grid.
-
-### Macros/Aux Page
+### Effects Page
-This page exposes controls for four sources of modulation that can be assigned to any number of parameters to modulate them all at once, and two additional sounds sources for the sake of layering: an auxiliary oscillator and a rudimentary sampler. Click on "Add" in the upper left of any one of the macro sections to assign modulation destinations. Each macro knob can be assigned to respond to a MIDI CC message. Just click "Learn" beneath the knob, and then activate the control you want to assign to it on your MIDI controller. A CC number will appear below the knob to indicate the assignment was successful. Click on the "Clear" button below it to remove the assignment. The auxiliary oscillator has a variety of waveforms, and can be placed in the signal chain either before or after the effects chains. Like the main oscillators, it can be controlled by any of the envelopes, and most of its controls can be modulated. The sampler can load .wav, .aif, .mp3, .flac, and .ogg files and play back audio within them up to 10 seconds in length. Select files with the "Load" button, or just by dragging and dropping them onto the plugin.
+The effects (FX) page contains slots for up to eight built-in effects, arranged in one or two chains ("A -> B" or "A || B"), each with its own gain control, applied before the signal enters the chain. Ordering the effects chains differently can open up a lot of possibilities. Since the effects parameters can be modulation destinations, there's a mod sources panel on this page, too. Also, since there's room for it, there's a modulation matrix panel, showing the currently active modulations, and offering controls to bypass, adjust, or delete them. In combination, the effects on this page can add a lot of boost, especially when modulated with sources that can constructively interfere. A built-in limiter is accordingly always on and meant to keep the levels below 0 dB, but be careful nonetheless.
# Motivation / Inspiration