diff --git a/.gitignore b/.gitignore index 04b6ea6..04b7d0c 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,6 @@ site .DS_Store **/.DS_Store help/.DS_Store +.DS_Store +docs/.DS_Store +docs/img/.DS_Store diff --git a/docs/img/index/ipad_overview/patch_browser/new_patch_browser.png b/docs/img/index/ipad_overview/patch_browser/new_patch_browser.png index 4210a98..b7b52fd 100644 Binary files a/docs/img/index/ipad_overview/patch_browser/new_patch_browser.png and b/docs/img/index/ipad_overview/patch_browser/new_patch_browser.png differ diff --git a/docs/index.md b/docs/index.md index 16ce78d..ebf7b7b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -185,6 +185,8 @@ width="50"/> ### 3. module browser user interface +Click on the blank background of the `canvas` and press `add` to add a module. + `module browser` screen from which you can add modules and submodules from either the default library or your own user library. @@ -174,7 +174,7 @@ exposable | ✅ **description** -The `text` node has no inputs or outputs. `text` nodes are used for labeling and commenting inside your patches. Click or tap on the node and open the `inspector panel` (pictured below). You can then type in the text field and text will appear inside the node. +The `text` node is used for commenting patches and labeling modules. Click or tap on the node and open the `inspector panel` (pictured below). You can then type in the text field and text will appear inside the node. The `text` node can also be exposed to the front panel of a module for labeling. text inspector panel @@ -271,9 +271,10 @@ The `zero cross` node counts the time between two zero-crossings and outputs tha The `math` nodes are some of the most powerful and versatile nodes. -- The `expr` node alone has 40 operators and functions which can be combined in many ways. -- `sum` and `product` are elegant ways to visually emphasize how signals are combining and can be expanded to have as many inputs as necessary. -- The `random` node has a `seed` input that ensures multiple copies of the same module can produce different random results with different `seed` values. +- The `expr` node has 40 available operators and functions for creating math expressions. +- The `sum` node adds two or more signals together. +- The `product` node multiplies two or more signals together. +- The `random` node outputs random values between 0 and 1.
@@ -361,7 +362,7 @@ The `expr` node is the most versatile node. It does math and basic programming o Double clicking on any input will create an `expr` node. -You enter equations into the `inspector panel`, pictured below. You do not need to add an `=` sign after your expression. +You enter equations into the `inspector panel`, pictured below. You do not need to add an `=` sign after your expression. expr node inspector panel -Variables are case-sensitive, meaning `x` is not the same as `X`. Spaces and underscores are not allowed. For long variables, you can use camel case. For example: `thisIsALongVariable`. +Syntax errors are reported underneath the input text area in the `inspector panel`. -Variables can contain numbers, but they must start with a letter. `input1` will generate an input but `1input` will not. Variables cannot contain symbols. +Variables are case-sensitive, meaning `x` is not the same as `X`. Spaces and underscores are not allowed. For long variables, you can use camel case. For example: `thisIsALongVariable`. You can also use underscores for variable names. For example: `_variable_Name`. + +Variables can contain numbers, but they must start with a letter or underscore. `input1` or `_input1` will generate an input but `1input` will not. Variables cannot contain symbols other than underscore. Certain variable names are reserved, like `mod`, `e`, and `pi`. If you need to use them as variables you can capitalize the first letter, like this: `Mod`, `E`, `Pi`. @@ -385,7 +388,7 @@ You can call a variable multiple times within an expression, like `x * x * x`. Spaces between variables and operators and within functions are optional. `x*y` is the same as `x * y` and `clamp(x,0,1)` is the same as `clamp(x, 0, 1)`. -Functions can be nested within one another, like `max(0, min(x, 1))`. +Functions can be nested, like `max(0, min(x, 1))`. Divide-by-zero functions return a `0`. In other rare cases it is possible to create an expression that outputs a `nan` value, or "Not a number." The node producing the `nan` will immediately self-disconnect from your signal chain to prevent damage to speakers. A `nan` will be displayed in the `value` node, as pictured below. @@ -515,11 +518,11 @@ If the `Seed` remains the same, every time the patch is reopened, the same strin The `meter` nodes are vital for displaying information about signals. -- The `meter` node is responsive and versatile. -- The `waveform` node is a simple way to see how signals change over time. -- The `value` node can help with debugging as well as displaying information on UIs. -- The `light` and `rgb light` nodes are great for adding visual feedback to modules. -- The `scope` node is like the `waveform` node, but suited for examining audio rate signals. +- The `meter` node displays a green to red bar meter between 0 and 1 for each poly channel. +- The `waveform` node displays a graph of a waveform. Best for low frequency signals. +- The `value` node displays numbers, useful for number displays on UIs as well as debugging. +- The `light` and `rgb light` nodes are great for adding light indicators to modules. +- The `scope` node behaves like an oscilloscope, well-suited for analyzing audio rate signals. - With the `shader` and `canvas` nodes you can use your own code to create your own beautiful custom meters, visualizers, and UI elements using GLSL and Lua.
@@ -554,7 +557,7 @@ In the `inspector panel` the `meter` node can be resized by altering the height alt="meter inspector" width="200"/> -If both `W` and `H` values are `0`, then the node defaults to its standard size. The node can be resized however you want, but it cannot be rotated. +If both `W` and `H` values are `0`, then the node defaults to its standard size and will automatically resize to fit UI elements. The node can be resized however you want, but it cannot be rotated. meter sizes -Changing precision can be useful for UI displays. For example, a sequencer's `current step` display should be a whole number, not a decimal. +Changing precision can be useful for UI displays. For example, a sequencer's `current step` display makes more sense as a whole number, not a decimal. value precision -Each input works with a `mod` signal. When the signal is `0`, the light is off. When the signal is `1`, the light is fully on. +Each input is clamped to a value between 0 and 1. light node -Colors can be mixed by sending different values to each input. +Any color can be created by sending different values between 0 and 1 to each input. For example, if you send a value of 1 to red and a value of .5 to green, the color of the rgb light will be orange. light node -The `s` variable is a measure of the persistence of the line drawn where `0` means only the current position of the cursor is shown and `1` means the cursor will draw a line that persists infinitely. `s` values between `0` and `1` will cause the line to fade quickly or gradually over time. +The `p` variable refers to the persistence of the line drawn where `0` means only the current position of the cursor is shown and `1` means the cursor will draw a line that persists infinitely. `p` is akin to feedback where values between `0` and `1` will cause the line to fade quickly or gradually over time. -There can be a large difference between what an `s` value of `0.9`, `0.99`, and `0.999` look like, so experiment with what works best for your use. +There can be a large difference between what an `p` value of `0.9`, `0.99`, and `0.999` look like, so experiment with what works best for your use. In the `scope` node's `inspector panel` there are options to change both the `Size` and resolution (`Image Size`) of the scope. @@ -753,7 +756,7 @@ width="200"/> The default size is `W = 200` and `H = 200` with an image size of `W = 512` and `H = 512`. -For a crisp, clean-looking line, the `Image Size` should be at least double the `Size` parameter. For a more digital-looking, stair-stepped size, the `Image Size` should be the same or smaller than the `Size.` +For a crisp, clean look, make `Image Size` at least double that of `Size`. For low-resolution, stair-stepped looks, make `Image Size` smaller than the `Size.` scope sizes -Below the code block are all of the available Lua functions which you can drag and drop into your code. +Below the code block are a list of Lua functions for various things, available vector graphic elements, transformations, Audulus theme colors, etc. You can drag and drop these into your code. canvas functions -Unlike other nodes, the `canvas` node does not run at audio rate, making it unsuitable to be within any audio or time-critical control paths. As the name implies, it is intended to be space to draw things. +*Note: unlike other nodes, the `canvas` node runs at a rate determined by graphics settings, not audio. Although it is possible to make ports and pass data to use with audio, the different time base can make it unsuitable for time-critical control paths. As a meter node, its intended purpose is to draw visual things.*
@@ -863,7 +866,7 @@ The `midi` nodes send and receive MIDI signals in and out of Audulus. - The `keyboard` allows you to play Audulus synths with an external MIDI controller or feed in MIDI notes from a DAW. - The `note send` node sends MIDI notes out of Audulus to hardware or DAWs. -- The `cc send` node sends MIDI CC messages from Audulus to hardware or or DAWs. +- The `cc send` node sends MIDI CC messages from Audulus to hardware or DAWs. - The `trigger` node can both act like a button within Audulus and can also receive on/off MIDI messages.
@@ -902,7 +905,7 @@ There are also two controls on the `keyboard` node. The first cycles through `Le `Legato` means only one note (the last played) will be outputted. `Poly 2` means 2 notes can be played at once, `Poly 4` means 4, and so on. -Higher poly counts multiply CPU usage, so only set it to the count you need. +Poly settings relate directly to the poly nodes in Audulus. Higher poly counts multiply CPU usage, so only set it to the count you need. You also might need a `poly mix` node at some point further down in your signal path to mix the poly signal into a 1-channel signal. The `Omni/(1-16)` control specifies which incoming MIDI channel is referenced. On `Omni`, any messages from any of the channels will come through. You can also set the keyboard node to listen to a specific channel `1-16`. @@ -996,9 +999,9 @@ The `trigger` node outputs a gate when its button is pressed. The button can be The `level` nodes are tools helpful for manipulating the level of a signal. -- You can create custom lines with the `spline` node and trace over them to output a continuous series of custom values. -- The `mapper` node allows you to shape the response curve of a knob or signal moving through it. -- The `env follow` node traces the loudness envelope of an incoming signal and outputs it as a `mod` signal. +- The `spline` node transforms a `mod` signal to follow the line you draw. +- The `mapper` node can change the range and curve of a signal. Similar to the spline node with a simpler set of points.[^5] +- The `env follow` node follows the amplitude (loudness) of an incoming signal and outputs it as a `mod` envelope signal.
@@ -1032,7 +1035,7 @@ exposable | ✅ The `spline` node allows you to draw a line using two or more breakpoints and then trace over that line using a `mod` input. -Breakpoints are added by double clicking or tapping on the blank field inside the node. Once created, they can be dragged around anywhere inside of the field. +Breakpoints are added by double clicking or tapping on the blank field inside the node. Once created, they can be dragged around anywhere inside the field. spline draw @@ -1208,9 +1211,9 @@ exposable | ❌ **description** -The `biquad` node allows you to create all different types of biquadratic filters. Refer to [this guide](https://webaudio.github.io/Audio-EQ-Cookbook/audio-eq-cookbook.html) for more information. +The `biquad` node allows you to create all different types of biquadratic filters. The filters included in the module library are based on [this classic set](https://webaudio.github.io/Audio-EQ-Cookbook/audio-eq-cookbook.html). -You need to calculate the coefficient inputs separately from the node using `expr` nodes. +Calculate the coefficients for biquad node inputs using `expr` nodes.
@@ -1238,7 +1241,7 @@ exposable | ❌ **description** -The `low pass` node is a simple non-resonant `6dB/oct` low-pass filter. The `alpha` input is the smoothing factor where `1 = no filtering` and `0 = maximum filtering`. +The `low pass` node is a simple non-resonant 1-pole `6dB/oct` low-pass filter. The `alpha` input is the smoothing factor where `1 = no filtering` and `0 = maximum filtering`.
@@ -1266,7 +1269,7 @@ exposable | ❌ **description** -The `high pass` node is a simple non-resonant `6dB/oct` high-pass filter. The `alpha` input is the smoothing factor where `1 = maximum filtering` and `0 = no filtering`. +The `high pass` node is a simple non-resonant 1-pole `6dB/oct` high-pass filter. The `alpha` input is the smoothing factor where `1 = maximum filtering` and `0 = no filtering`.
@@ -1379,7 +1382,7 @@ In the `inspector panel` you can choose from different multiples of the base sam alt="resample inspector" width="200"/> -For example, given a base sample rate of `44.1kHz`, `4x` sample rate would be `176.4kHz`. +For example, given a base sample rate of `44.1 kHz`, `4x` sample rate would be `176.4 kHz`. To properly use the `resample` node, you have to have two `resample` nodes in your patch, one to mark where you want to begin supersampling and one to mark where you want to downsample back to the original sample rate, as well as a pre-downsampling low-pass filter with a cutoff set to half the base sample rate. @@ -1432,6 +1435,8 @@ Reading and writing to the `memory` node can happen at different index values at You can also import audio to the memory node. On Mac, you do this by dragging an `.AIFF` or `.WAV` file from a Finder window into the space marked `Drop audio file here`. There is also a check box labeled `Save Data` that, when checked, will save the contents of the `memory` node in between patch loads. +You can also set the memory node buffer size with the Samples pulldown in the `inspector panel`. This can reduce the file size for patches when you do not need the maximum buffer size. + memory inspector @@ -1448,7 +1453,7 @@ width="200"/> The `synth` nodes are low-level building blocks specific to audio synthesis. - The `osc` node outputs one of 4 classic anti-aliased waveforms. -- The `phasor` node outputs an un-aliased phasor signal from `0 to 2π` useful for creating custom oscillators +- The `phasor` node outputs an un-aliased phasor signal from `0 to 2π` useful for creating custom oscillators, clocks, etc. - The `sample & hold` node can sample an input signal, store it, and hold that value at its output. - The `adsr` node generates an envelope according to an incoming `gate` signal. @@ -1491,7 +1496,7 @@ The `osc` node is intended as an audio-rate oscillator. This means it is anti-al The `Hz` input controls the speed of the oscillator from `0` to `sampleRate/2 Hz`. -The `amp` input uses a `mod` signal to control the amplitude of the wave. For example: An amplitude value of `1` will set the output of the `osc` node to range between `-1 and 1`, whereas a value of `0.5` will oscillate between `-0.5 and 0.5`. +The `amp` input controls the amplitude of the waveform. For example: An amplitude value of `1` will set the output of the `osc` node to range between `-1 and 1`, whereas a value of `0.5` will oscillate between `-0.5 and 0.5`. osc hz amp -Exposed elements within a `module` node will appear automatically on the UI. You can move them around by clicking or tapping the `lock icon` to enter `Edit Modules` mode. +Exposed elements within a `module` node will appear automatically on the UI. On ipadOS you can move them around by clicking or tapping the `lock icon` to enter `Edit Module` mode. On macOS select `Edit Module` with cmd-E or via View menu > Edit Module. module move ui -You can either define an explicit size for the `module` node, or let the UI elements determine the size. In the example below, the first `module` has a dimension of `0x0` and the size of the module is determined by where the `input` and `output` nodes are placed. In the second example, the module has a fixed size of `200x200` and the output can be placed wherever without shrinking the size of the module. In the third example, you can see how with a fixed size, you can even put UI elements outside of modules, which can be useful for both creative and practical purposes. +By default, a `module` resizes to fit all exposed UI elements. You can define an explicit size for a `module` by setting W/H to something other than 0. In the example below, the first `module` has a dimension of `0x0` and the size of the module is determined by where the `input` and `output` nodes are placed. In the second example, the module has a fixed size of `200x200` and the output can be placed wherever without shrinking the size of the module. In the third example, you can see how with a fixed size, you can even put UI elements outside of modules, which can be useful for both creative and practical purposes. module size io -There are six `Style` options for the `knob` node that change its shape: `Standard`, `Mini`, `Large`, `Drive`, `Mix`, and `Bipolar`. The three color options are blue, green, and red. +There are six `Style` options for the `knob` node that change its shape: `Standard`, `Mini`, `Large`, `Drive`, `Mix`, and `Bipolar`. The three color options are azure, green, and red. knob styles -In the `inspector panel` you can change the color of the slider to blue, green, or red, and assign `MIDI CC` and `Channel`. +In the `inspector panel` you can change the color of the slider to azure, green, or red, and assign `MIDI CC` and `Channel`. slider inspector **description** -The `poly` nodes help create and manage polyphonic signals. +The `poly` nodes create and manage multi-channel "polyphonic" signals. Poly channels can be composed of audio or control signal types. -- The `combine` and `split` nodes allow you to merge several mono signals together and then take them back apart. -- The `poly mix` node takes a poly signal and mixes it down to a mono signal. +- The `combine` and `split` nodes allow you to merge several mono signals into one cable or separate a poly signal into its repsective channels. +- The `poly mix` node mixes a multi-channel poly signal down to a 1-channel signal. - The `channel index` node outputs a poly signal of integers indexed from `0`. -- The `channel count` node outputs the current number of polyphony at its input. +- The `channel count` node outputs the current number of poly channels at its input.
@@ -2053,7 +2058,7 @@ exposable | ❌ **description** -The `combine` node takes from `2` up to `256` mono signals and combines them into one polyphonic signal. +The `combine` node takes from `2` up to `256` mono signals and combines them into one multi-channel "polyphonic" signal. In the `inspector panel` you can set the number of channels. @@ -2093,7 +2098,7 @@ exposable | ❌ **description** -The `split` node takes a poly signal and splits it into `1` to `256` mono signals. +The `split` node takes a multi-channel poly signal and splits it into `1` to `256` mono signals. In the `inspector panel` you can set the number of channels. @@ -2133,18 +2138,7 @@ exposable | ❌ **description** -The `split` node takes a poly signal and splits it into `1` to `256` mono signals. - -In the `inspector panel` you can set the number of `Channels`. - - - - - +The `poly mix` node sums all channels of a poly signal.
@@ -2167,7 +2161,7 @@ exposable | ❌ **description** -The `channel index` node creates a signal with `1` to `256` channels where each channel is an integer index number that is indexed from `0`. +The `channel index` node creates a poly signal with `1` to `256` channel index integers from 0 to n-1 channels. Used in combination with the `channel count` and math `expr` nodes, this node is good for performing iterative math operations across poly signals. In the `inspector panel` you can set the number of `Channels`. @@ -2217,8 +2211,9 @@ width="400"/> The `switch` nodes route signals and turn them on or off. -- The `mux` node sends one of several inputs to one output while the `demux` node sends one input to several outputs. -- The `spigot` node allows you to turn off a section of a patch to prevent it from wasting CPU time when not needed. +- The `mux` node sends one of several inputs to one output. +- The `demux` node sends one input to one of several outputs. +- The `spigot` node allows you to turn off a section of a patch to prevent it from using CPU resources when not needed.
@@ -2352,7 +2347,7 @@ Nodes that are not processing show `inactive` next to their name when in `timing alt="spigot off on" width="800"/> -Beware that if you have any kind of `meter` or other type of terminal output node connected to a node or series of nodes that you want to turn off using a spigot node, the node will not turn off. +Beware that if you have any kind of `meter` or other type of terminal output node connected to a node or series of nodes that you want to turn off using a spigot node, the node will continuously wake up `spigot` node and not turn off.