====== Mozaic: MutatoR ====== {{tag>Mozaic midi_scripting}}

MutatoR is a script hosted on PatchStorage that allows to apply independant note mutations and humanization to all 16 midi channels with 64 user-defined configurations organized in 4 banks.

MutatorR can issue pattern based or random note drops, velocity changes, transpositions with scales and destination channel routings independenly for each channel to transform the melodic and rhyhtmic qualities of the input material.

Interactively switching between configurations makes it possible to arrange, transform and decompose the piece played by the midi sequencers & generator in a live jam fashion.

The script is based on the concepts of the [[https://patchstorage.com/midi-matrix-switch/|Midi Matrix Switch]], [[https://patchstorage.com/copycat/|CopyCat]] and [[https://patchstorage.com/toggle-channels-on-bar-divisions/|ToggleChannels]]. ===== Basic Setup ===== Like its predecessors it needs a special project setup: * All midi generators need to send on different midi output channels and need to be routed into the MutatoR script * All sound generator reacting to the midi generators need to read their midi input from the MutatoR script and also need to apply an input channel filter to select the correct generator * The more midi generators there are, the more variety can be created * For sonic variety, you can add alternative sound generators receiving on separate midi channels (See [[midi_routing_for_multi_input_processing|Midi routing for multi-channel-midi processing plugins]] for more information about this topic) {{mutator_routing.png}} Basically all generated midi input is fed into MutatoR on up to 16 separate midi channels and all sound generators listen to the output of the script, but each only to a different one of the channels. Depending on the active configuration MutatoR will route channels through (like ch 2), change the output channel (ch 1) or mute channels (ch 3 and 11) - just like [[https://patchstorage.com/midi-matrix-switch/|Midi Matrix Switch]]. The diagram also visualizes MutatoRs note modifaction capabilities such as volume changes (ch 5), transpositions (ch 7), random note drops (ch 8) or pattern gating (ch 10) - like an extended version of [[https://patchstorage.com/copycat/|CopyCat]]. ===== The Views ===== There are three main views * The **[[#CHANNEL View]]** shows the applied modifications on the pad labels of each channel with different colors for each for the channel modes (Thru, Apply or Mute) * The **[[#CONFIG View]]** shows one of four configration banks in batches of 16 pads labeled with user-defined names. The banks have different colors: lavender, violet, magenta and yellow. The current active config is highlighted in light blue. * The **[[#EDITOR View]]** consists of 10 pages with knobs per channel focusing on one mutation aspect per page. and two secondary views ([[#SWAP/COPY View|SWAP/COPY]], [[#HELP View|HELP]]) ===== CHANNEL View ===== This view shows the applied modifications summarized on the pad labels of each channel. {{mutator_channel_view.png}} ==== Main Labels ==== The main top label first describes the mode "CHANNELs", followed by the currently active config id (Config-31). If a name was set for the config, the label above the knobs either shows the config-id (C31) followed by the configured name. ==== Pad Labels ==== The pads of the CHANNEL View use top separated layout to distinguish this view more clearly from the [[#CONFIG view]]. Each pad shows infos about the channel number, the channel mode and optional channels output routing and below the headers division line the modifications configured. \\ === Channel Header === The channel mode is shown in the heading and in the colorization of the pad: ^ Mode ^ Color ^Info ^ | Thru | Unlit | Note data passes unmodified | | Apply | Green | Modifications are applied | | Muted | Red | All notes of this channel are suppressed | A '**» //number//**' after the mode indicates that the channel is configured to redirect to the stated output channel. \\ === Channel Mutation Summary === The lower part of each pads label describes the modifications applied: ^ Line ^ Info ^ Format ^ | Top | note drop probability \\ drop pattern info | **Drop** //percent// \\ //drop pattern id// //**/**// //beat division//    //drop probability// **|** //sneak in probability// | | Middle | note velocity modifications | **Vel** //absolute offset// **|** //random humanization// | | Bottom | note transpositions | **Transp** //absolute offset// \\ **Tra** //absolute offset// **|** //random percentage// | ==== Bar Display ==== If the hosts timeline is running, one of the pads will flash in sync with the quarter beat. The flashing pad advances each bar, running from from the top left pad to bottom right pad. This visualization makes in easy change channel mode in sync with the regular patterns fed into MutatoR, even if these are muted. The feature can be turned off or adapted to different musical phrase length, for more information see the [[#Bar Display Documentation|Bar Display]] section of the HELP View. ==== Interactions ==== === Pads === * Tap a channel pad to toggle between mute/apply mode * Double-tap a pad to toggle between apply/thru mode * Hold a pad and press SHIFT to toggle between apply/thru mode === Knobs === * Turn the CHAN/Conf to the right (or double-tap) to toggle to [[#CONFIG View]] * Turn the HELP knob to the right (or double-tap) to toggle to [[#HELP View]] * Double-tap the unlabeled top left knob to change to previous config * Double-tap the unlabeled top right knob to change to next config === Shift Button === * Tap SHIFT to enter the [[#EDITOR View]] for the active config * Double-tap SHIFT to change to [[#CONFIG View]] * Hold SHIFT and then tap a pad to enter channel [[#SWAP/COPY View|SWAP/COPY]] mode and sets the origin. \\ ===== CONFIG View ===== The config view allows to select the active configuration by pressing the corresponding pad. {{mutator_config_banks.gif}} There are four banks of 16 configs each. Each bank uses different pad colors (lavender, violet, magenta and yellow). The currently active configuration is highlighted with light-blue color (Config 1). Changing the bank only changes the display, it does not active a different config. ==== Main Labels ==== The main label starts by stating "CONFIGSs" mode at the same position where the channel view states "CHANNELs". The label above the knobs is empty. ==== Pad Labels ==== Config names * If the upper part of a config pad is empty, the config setup contains defaul values - all channels are in Apply mode without any channel re-routing or modifications * A default name of '<< >>' name is shown, if the configuration differs from the default a '<< >>' name is shown, but no name was setup in the [[#EDITOR View]] * Otherwise, the configured name is shown To differentiate this view more clearly from the [[#CONFIG View]], the separator line and config id is located at the bottom of the pad. \\ === Bar Display === If the hosts timeline is running, one of the pads will flash in sync with the quarter beat. The flashing pad advances each bar, running from from the top left pad to bottom right pad. This visualization makes in easy to switch configs in sync with the regular patterns fed into MutatoR, even if these are muted. The feature can be turned off or adapted to different musical phrase length, for more information see the [[#Bar Display Documentation|Bar Display]] section of the HELP View. ==== Interactions ==== === Pads === * Tap a channel pad to activate the config. Config changes takes place immediately, all new incoming notes will be modified according to the new settings. No active notes are muted or changed. === Knobs === * Turn the BANK knob to display the four config banks 1-16, 17-32, 33-48 and 49-64 * Double-tap the BANK knob to switch to the next bank * Turn the chan/CONF to the left (or double-tap) to toggle to [[#CHANNEL View]] * Turn the HELP knob to the right (or double-tap) to toggle to [[#HELP View]] === Shift Button === * Tap SHIFT to enter the [[#EDITOR View]] for the active config * Double-tap SHIFT to change to [[#CHANNEL View]] * Hold SHIFT and then tap a pad to enter config [[#SWAP/COPY View|SWAP/COPY]] mode and sets the origin. Config changes takes place immediately, all new incoming notes will be modified according to the new settings. No active notes are muted or changed. \\ ===== EDITOR View ===== The EDITOR Víew is split into 10 sub pages all in 22 knobs layout, grouped into 4 categories: ^ Category ^ Page ^ Info ^ | [[#Channel Mode]] | 1 | Channel mode, output channel assignment and config name | | [[#Note Drop]] | 2-4 | Random note drops, pattern based note drops and sneak-in probability | | [[#Note Velocity]] | 5-6 | Random change and absolute offset | | [[#Note Transpose]] | 7-10 | Static offset, random change probability and ranges | * Turn the EDIT knob to change between the ten editor sub pages * Double-tap the EDIT knob to change to next sub page ==== Channel Mode ==== The page allows to change the channel modes and channel re-routing and to setup the config name shown on the [[#CONFIG View]] pads. {{mutator_modes.png?direct}} \\ === Channel Knobs === The channel knobs determine the mode of a channel. Each of the channels can either be ^ Channel Mode ^ Knob Position ^ Info ^ | routed thru unmodified | fully left | Allows to compare modifications vs original | | routed to original channel | position differs | Plays original sound with note modifications applied | | routed to different channel | all except original | Plays notes with different sounds and note modifications applied | | muted | fully right | Silences the channel | * Double-tap of a channel knob changes between 'mute' and the last dialed channel. * A doube-tap of a channel in thru mode changes to the original channel. \\ === Extra Knobs === The NAME knob in the upper row selects the base name from the list of No Name Break, Breakdown, Bridge, Buildup, Chorus, Drop, Fill, Hook, Intro, Middle 8, Motif, Outro, Part, Pre-Chorus, Refrain, Solo, Variation, Verse The two lower knobs change the subsection from (A-G) and number (1-8), they appear if the name is changed away from 'No Name'. \\ A 'No Name' config with settings that differ from the default will use a '<< >>' label on its [[#CONFIG View]] pad. \\ === Summary Label === Channel Mode and output redirections are shown in the header of the [[#CHANNEL View]] pad label and determine the color of the respective Pad. ^ Mode ^ Chan ^ Color ^ Format ^ | Thru | any | - | //input ch// **Thru** | | Apply | same | green | //input ch// **Apply** | | Apply | other | green | //input ch// **Apply >>** // output ch// | | Mute | same | red | //input ch// **Mute** | | Mute | other | red | //input ch// **Mute >>** // output ch// | ==== Note Drop ==== The note drop settings span over three sub pages. {{mutator_note_drop.gif}} ^ Sub Page ^ Info ^ | Drop Probability | Configures the percentage of random note drops | | Drop Pattern | Specify 4 or 8 element pattern based note drops with variable beat divisions speed | | Sneak-In Probability | Configures the percentage of note re-enabling during the dropped elements of the pattern | === How Note Drop and Patterns works === The Note Drop feature only applies to the note-on midi event - it is either passed or dropped (muted). This causes the note to be completely suppressed until its corresponding note-off midi event, which is then likewise suppressed to avoid confusing the sound generator. The default settings for all configs is to let all notes pass. Tweaking just the knobs on the 'Drop Probability' page will randomly select notes to be dropped. To allow more control over the timing of note drops, the MutatoR script offers a pattern based note drop feature. A pattern drop definition consists of either four or eight elements, each either 1 (pass) or 0 (drop) and a beat division ranging froom 1/1 to 1/16 specifiying the speed the pattern is stepped through . ^ Knob Label ^ Pattern ^ Info ^ | p5 | 1111 | Pass all notes | | 0x99 /16 | 1001 | Pass notes on the every first and forth 1/16, dropping notes on every second and thrird 1/16 | | 0x04 /1 | 0000 0100 | Only pass notes of bar 6 | The pattern feature will not mute or shorten already sounding sustained notes and therefor not allow pattern gating like [[https://patchstorage.com/mute-maschine/|Mute Maschine]]. \\ === The Two Drop Probabilities === The two probabilites of the note drop pages serve different purposes: * The 'Drop Probability' only applies to notes issued during the 1 (pass) elements of the pattern. \\ It specifies the chance (0-99%) of the note-on beeing dropped. * The second 'Sneak-In Probability' re-enables notes dropped during the 0 (drop) elements of the pattern. \\ The value specifies the change (0-100%) of re-enabling the note. \\ This allows for various use cases: ^ Mutation \\ Goal ^ Note \\ Drop ^ Pattern \\ & Div ^ Sneak \\ In ^ Info \\ . ^ | Play every on-beat of a drum, but other hits only occasionaly | 0% | 1000/16 | 5% | Every forth 1/16 is played with a 100% chance, all other steps have 5% chance of playing | | Drop 25% of notes of the 3rd quarter of a bar | 0% | 1101/4 | 75% | The 1 elements will not drop any notes, the 0 elements will drop 25% as 75% of the notes are re-enabled | |      "      same as above      " | 25% | 0010/4 | 100% | The 1 element on 3rd quarter will drop 25% and the 0 elements passes all (100%) notes | \\ === Pattern Editor === The Drop-Pattern page allows to choose any 8-step pattern and to specify the speed the pad is stepped through. {{mutator_pat_edit.gif}} The channel knobs have three editoring modes, stepped though using a double-tap. \\ The knob label uses underlining as a visual indicator, which part of the pattern definition is edited. ^ Double-Tap # ^ Info ^ | none | Turning a channel knob for the first changes between off (fully left) and 15 four-element pattern | | 1 | Turning the channel knob changes the betwen four-element patterns (fully left) or adjusts the last 4 elements of a eight element patterns | | 2 | Turning the channel knob changes the step divisions from 1/1 (step per bar) to 1/16 | | 3+ | The channel knob steps through the above 3 editing modes | The channel knobs displayed the pattern as hexadecimal value due to label length reasons, but the corresponding 0+1 elements are shown in the pattern visualizer on the right hand side. The four element pattern still show a 2 byte hex with a dublicated value. Channel knobs and pattern visualizer knobs work in paralell. Both can be used alternatively and mixed for pattern and step definition. \\ === Pattern Visualizer === The Pattern visualizer starting with the 🟩 knob offers an alternative way of pattern editing. A 🟢 highlights the currently visualized channel. When it hosts timeline is running, there is an additional marker showing the active element - this helps a lot in finding the right pattern and step division speed. {{mutator_pat_vis.gif}} Upper row * The leftmost knob changes edited channel, double-tap or full left hides the visualizer * The middle knob changes the first 4 steps * The right knob changes changes the last 4 steps, fully turned to the left only 4 steps are used Lower row * The leftmost knob shows the decimal pattern id, nothing to edit * The middle knob changes the step division from 1/1 (one step each full bar) to 1/16 \\ The pattern-element knobs apply a custom gray-code like sequence, which makes it easier (than the hex order) to select musicaly relevant patterns : 1111, 1110, 1100, 1000, 1010, 1011, 1001, 1101, 0010, 0100, 0101, 1100, 0111, 0011, 0001, 0000 === Summary Label === Note Drop mutations of a channel are listed in the top line of the mutation summary on [[#CHANNEL View]] pad label. Pure drop mutations are shown as **Drop** //percent// , mutations with patterns use the //drop pattern id// //**/**// //beat division// //drop probability// **|** //sneak in probability// format. \\ ==== Note Velocity ==== The two velocity sub pages of the [[#EDITOR View]] allow to specify a static velocity offset and a random velocity humanization percentage: {{mutator_velocity.gif?direct}} ^ Modification ^ Range ^ Info ^ | Velocity Offset | -64 to +64 | Offsets original note velocity | | Velocity Humanization | 0 to 99% | Adds a bi-polar random value to note velocity, the percentage controls the range | The result of both velocity mutations is clipped between 1 and 127, so that notes can only be 'very quiet' but not dropped. \\ === Summary Label === Velocity mutations of a channel is listed as Vel //offset// **|** //random%// in the center line of the mutation summary on [[#CHANNEL View]] pad label. The example shown in the above animated screenshot will sumarize as\\ Vel 64|0% on pad 2, Vel -64|31% on pad 6, Vel -64|67% on pad 7 and Vel -62|0 on pad 11 \\ === Remark === Be aware that some synth only use fixed velocities for their sounds, sometimes this depends on the sound preset used. In such cases, changing the note-on velocity won't change the volume of the produced sound. ==== Note Transpose ==== The four tranposition sub pages of the [[#EDITOR View]] allow to apply a fixed or random note offset and to apply scale quantizations. {{mutator_transpose.gif?direct}} ^ Modification ^ Range ^ Info ^ | Transpose Offset | -24 to +24 | Offsets original note by semi tones | | Transpose Random Probability | 0 to 100% | Set the chance for random tranpositions | | Transpose Random Down | 0 to -12 | Set the random downwards semi tone transpostion range | | Transpose Random Up | 0 to +12 | Set the random upwards semi tone transpostion range | \\ === Extra Knobs === The two rightmost knobs far right in the top row control scale quantization. * The first knob allows to select between 'No Scale' (turned left) and 24 predefined scales * Thesecond knob allows to select the scales root note. The knob is only visible, if a scale was selected. Only channels with a non-zero transpose offset or non-zero random probability will apply scale quantization. \\ === Summary Label === Transpose mutations of a channel is listed in the bottom line of the mutation summary on [[#CHANNEL View]] pad label. Pure offset mutations are shown as Transp //offset// , mutations including random transpositions use the Tra //offset// **|** //random%// format. The example shown in the above animated screenshot will sumarize as Tra 0|39% on pad 1, Transp 7 on pad 2, Transp 12 on pad 4 and Tra 0|55% on pad 6 \\ === Remarks === Even when interactively tweaking the transpostions and scale quantization, MutatoR takes care to send the correct corresponding note-off for each note mutation applied. If you don't want to apply scale quantization without tranposition, dial in an a non-zero random tranpose probability with an up and down range of zero semi-tones. \\ ===== SWAP/COPY View ===== The SWAP/COPY view allows to rearrange and duplicate channel or config settings. {{mutator_swap_copy.gif}} \\ === Entering the View === To enter this view from either [[#CONFIG VIEW]] or [[#CHANNEL View]], hold the SHIFT button and press the source pad to be swapped or copied. The top labels change to indicate the new view, a swap/copy knob appears and the source pad will start to flash and show a label to cancel the SWAP/COPY View. After initiating the SWAP/COPY View, release the source pad and SHIFT button. ^ View ^ Operation ^ Info ^ | CONFIG View | Swap | Swap settings from the select config with another of the 64 configs | | CONFIG View | Copy | Copy settings from the selected config to another of the 64 configs | | CHANNEL View | Swap | Swap setttings of both channels for all 64 configs to allow re-configuration \\ of the midi channels send by the generators | | CHANNEL View | Copy | Copy the selected settings to a different channel on any of the configs | \\ === Swap/Copy Mode Change === There are different flash pattern for swap or copy mode. The mode is toggled by turning or double tapping the swap/copy knob, or by tapping the SHIFT button. \\ === Cancel === Tap the flashing source pad to cancel the operation and to leave the view. \\ === Bank or Config Change === If acting on configs the Bank knob can be used to select destinations on a different bank as the source. If acting on channels and with the COPY operation selected, the Config knob can be used to change to a different config for destination selection. Whe the source pad is not visible, all pads are flashing with a slow tempo to visualize SWAP/COPY mode. \\ === Execute === Tap a different pad to select the destination for the operation. After tapping a destination pad, the operation is executed and SWAP/COPY View is left. Swapping channels allows to reconfigure the output channels of MutatoRs input midi generators without loosing the current settings. ==== Interactions ==== === Pads === * The source pad was selected upon entering the SWAP/Copy View * Tap the source pad again to cancel the operation * Tap a different pad to select the destination and to carry out the operation === Knobs === * In [[#CONFIG View]] the Bank knob allows to select a destination config on a different bank. Double-tap to change to next bank * In [[#CHANNEL View]] the Config knob allows to select a destination channel in a different config. Double-tap to change back to the source config. * Turn the swap/copy knob (or double-tap) to toggle between swap and copy operation === Shift Button === * Tap SHIFT to toggle between swap and copy operation \\ ===== HELP View ===== The help view displays the embedded short description, allows to import settings from older script versions and to configure the bar display. {{mutator_help.png}} ==== Importing ==== The importing feature allows to import the settings of all configs stored in another script instance running an older script version. Loading and installing a more recent MutatoR version (with bug-fixs or new features) normally will apply the default settings to all 64 configs - all configurations made in the older version are lost and one would have to dial in all knob positions for all 16 channels on all 10 views for a maximum of 64 configurations (16 x 10 x 64) resultig in a maximum of 10240 knobs turns. With the Importing of MutatoR you only needs to turn a single knob - the IMPORT knob. But you need to do some preparations: * **Before** loading a new script version, save the to-be-preseved configuration to a new preset name (either in the host or in Mozaic) * Update the script to the new version by loading the script - this will come up with the scripts default settings * Load a second Mozaic instance on any of your HOSTs tracks, no need to setup any routing * Back in your main Moazic instance running the new MutatoR version, enter HELP View and turn the IMPORT knob of the script * Change back to the other Mozaic instance and load the saved configuration, you have ten seconds after turning the IMPORT knob to do this. * The new MutatoR version picks up the configuration and changes back to the CONFIG View and you are ready to go * Remove the temporary second Mozaic instance from you project If you took to long to re-load the preset in the second Mozaic instance, the importing will fail after 10 seconds and the Import knob will turn back to the left. ==== Bar Display Documentation ==== If the hosts timeline is running, [[#CHANNEL View]] and [[#CONFIG View]] will flash one of the pads in sync with the hosts quarter beat. The number of flashes is specified by the hosts time signature, for a time signature of 4/4 this results in 4 flashes per pad. Per default all 16 pads are used, stepped one per full bar starting with the top left pad on hostbar 1:1. In hostbar 16.1 flashing will reach the bottom right pad and wrap back to the top-left pad to signal a new batch of 16 bars. The various midi generators (sequencers, drum pattern etc) fed into MutatoR often use internal loops with length of power of 2. The bar display makes it easy to to classify the current bar within a 2, 4, 8 or 16 bar grid, offering a visual aid to better sync config or channel mode changes in relation to the patterns fed into MutatoR even if their output is muted. Since not all music is performed in 4/4 and phrase length might not be in powers of 2, the number of bars before wrapping back to the first pad can be configured between 2 and 16 bars (or deactivated) with the barDisp knob in the HELP View. If configured to wrap after 8 or less bars, only the lower pad row will be used to visualize the current bar. With a 3/4 time signature and bar display configured to wrap back at 9 bars, its possible to sync to patterns with a phrase length of 3 bars. ==== Interactions ==== === Knobs === * Turn the IMPORT knob to start [[#Importing]] * Turn the BarDisp knob to configure the [[#Bar Display Documentation|Bar Display]]. The left knob position turns off the pad flashing, turn right for a wrap value of 2 to 16 bars. * Turn the HELP knob to the left (or double-tap) to toggle back to the view from where you entered the HELP View. === Shift Button === * Tap SHIFT to change to the last active view, either [[#CHANNEL VIEW]] or [[#CONFIG VIEW]]. * Double-tap SHIFT to change to the other main view. If you entered the HELP view from [[#CONFIG VIEW]], a double-tap on SHIFT will change to the [[#CHANNEL View]] \\ ===== Automation ===== MutatoR supports AU parameter automation: ^ Parameter ^ Info ^ | user 0 | Selects the current configuration from config 1 to config 64 | | user 1 | Selects the visible view (config bank view, channel view and the 10 editor views) | | pad 0-15 | Allows to trigger a pad to mute/unmute channels or activate a config | | knob 0-21 | Allows to change knob setting | This should allow to remote control the MutatoR script from external controllers.