ArtWonk Tutorial: Advanced ArtWonking

Tutorial #2: Advanced ArtWonking

In this tutorial you will create a Macro that can be used in other patches as a 16 step sequencer, with a row of knobs for the pitch and a row for the rhythm. Although this is a fairly extensive tutorial, it is broken up into smaller parts you can work through individually. Each part includes a patch of the finished tutorial for reference. Probably the best way to run the tutorial is to load the reference patch for each part first to see what it should look like, then do a New, and proceed to create the patch yourself from the tutorial.

Part 1: Creating a single stage

We start by creating a single sequencer stage of two knobs and a LED, which later will be duplicated for each of the 16 stages. The reference patch for this part of the tutorial, in the Patches/Examples directory, is: Tutorial2a.awp

Create a Knob widget to be used for the first, pitch row. This will have a range of 4 octaves, 0-48. Start with New, then create a Knob widget.
1. The knob graphic appears in the upper left corner of the Panel. Shift-click and drag to about an inch down and to the right.
2. Right click on the knob to get the property dialog (you could just as well click on the Knob module in the Workspace, either one pops up the property dialog for that knob).
3. Click on the Small size option; check "Hide Info Label" and "Center Value Label." Tool tips are unnecessary here, and can be annoying in a matrix of knobs, so delete the text in the Tool Tip box. Click the OK button to see the knob.
4. You should have a small knob with the value in the center, and no info label. Try changing the knob value by clicking on it, and moving the mouse up and down.
5. The knob pointer is obscuring the center value label, so we need to fix that. Right click on the knob again to get its property box. In the text box labeled "Pointer Length" type in "0.4" to shorten the pointer. Click the OK button and try it out.
6. Set the knob range to be 4 octaves, 0-48. Open properties, and enter 48 into both the Output Value Range and the Display Value Range, replacing the default value of 127. Click OK and test the knob.
Create a 2nd knob to be used for the rhythm row. Although there is total freedom in setting up rhythm durations and you can create complex polyrhythms with ease, in this tutorial we will restrict the rhythm steps to note, dot note and triplet values, within a range of a 16th to a double whole note.
1. Instead of creating the knob and then setting its properties, it is easier to copy and past the existing knob. Right click on the Knob module in the Workspace, select Copy, then click on the Workspace background and select Paste. An identical Knob module will appear where you clicked on the Workspace. Move it to directly underneath the 1st Knob module.
2. In the Panel, the new knob was created over the 1st knob, and a hand icon handle appears. Click and drag on the hand icon to separate the knobs. Position the new knob directly under the 1st knob. You may prefer to click on the background to dismiss the hand icon mover, and then use Shift-click-drag directly on the knob to position it.
3. If you have not already done so, click on the Panel background to dismiss the hand icon mover. Right click on the knob to get its properties box. Change the knob color to yellow. Change the two Range values from 48 to 15 (this give 16 rhythm steps from 16th to double whole, including dots and triplets).
Create a LED widget for the blinky light that will indicate the active sequencer row.
1. Create the LED widget, place the module under the 2nd Knob module, and move the LED to above the 1st Knob. Exact placement is unimportant until we have its parameters set.
2. Right click on the LED to adjust parameters. Set Height to 8, Width to 14.
3. Check Label Above on the right, and On if = [0] on the bottom. This will turn on the LED. Later, when we create the other stages, we will need to adjust the label number and the On if = number, but for now keep the default settings of 1 and 0 respectively.
4. Adjust the position of the LED widget so it is centered just above the 1st Knob widget.
Create a Function module and a Readout label. The Function module will map the 0-15 rhythm knob output values to the actual note duration range needed of from 6 for a 16th note to 192 for a double whole note; and the readout will display the mapped duration value.
1. Create the Function module and place it under the LED module. We will return to this later.
2. Create the Readout widget, place the module under the Function module. In the Panel, place the label below the yellow rhythm knob. Exact placement is unimportant until its parameters are set.
3. Right click on the Readout widget to access its properties, and make the following settings:
  1. Set the Font to "Small Fonts," Font size 7.
  2. Set Justify to Center.
  3. Set the Text Color to white.
  4. Un-check 3D Border; check No Border.
  5. Check Transparent.
  6. Type "0000" into the Text box, then click the Resize to Font button.
4. Click OK to update the widget and dismiss the Property dialog. Adjust the label to just below the yellow knob.
Set up the Function module to do the rhythm duration mapping by clicking on the blue label button on the top right of the module to access its Property dialog.
1. In the General tab, in the Name box, type "Knob2Dur," and in the Tool Tip box, type "Map Rhythm knob 0-15 range to real duration values."
2. Click on the Inputs tab, and type "Knob" in the label box. The input will receive the raw knob value of 0-15.
3. Click on the Outputs tab, and type "Dur" in the label box. The output will have the result of the knob mapping, which will be the note duration.
4. Click on the Fn Load tab. Here we will set the duration map values by storing them into the 0 to 15th elements of the Function module's Private Array. Copy the below text and paste it into the function script text box:
  
  Store(0, 6) ; 16th
  Store(1, 9) ; d 16th
  Store(2, 8) ; t 8th
  Store(3, 12) ; 8th
  Store(4, 18) ; d 8th
  Store(5, 16) ; t 4th
  Store(6, 24) ; 4th
  Store(7, 36) ; d 4th
  Store(8, 32) ; t Half
  Store(9, 48) ; Half
  Store(10, 72) ; d Half
  Store(11, 64) ; t Whole
  Store(12, 96) ; Whole
  Store(13, 144) ; d Whole
  Store(14, 128) ; t Double
  Store(15, 192) ; Double
5. Click on the Function tab. The actual mapping function goes here. Replace the existing default function, which is:
  
  Out(1, In1)
  with:
  Out(1,Fetch(In1))
  
  Thus, a knob value of 0-15 at input 1 will be mapped to the array value stored in the private array at elements 0-15, which we have set up to be the duration values, and the result of the array Fetch will be sent to output 1.
6. Click on the OK button to accept the changes and dismiss the dialog.
7. At this point, the function appears not to be working because there has not yet been a Load event, which normally occurs only when a patch is loaded. Force a Load event now by clicking on the Workspace toolbar Force Load button, the lightening bold icon left of the round transport buttons. You should now see an output of 6 in response to the input of 0.
8. Connect the 2nd (yellow) knob module's output to the Knob input of the newly created Knob2Dur function module. Adjust the knob through its range and you should see the duration values in the Knob2Dur's Dur output.
9. Connect the Knob2Dur's Dur output to the Readout module's input. Try adjusting the knob again and you should see the label under the yellow knob display the duration value, while the label in the center of the knob shows the 0-15 knob range.
10. This concludes making the stage modules & widgets. If you have not done so already, it would be a good idea to either save the patch so far, or to quick save it. This patch is available in the Examples directory, as Tutorial2a.awp.

Part 2: Creating the stage macro

One great use of macros is to help organize a larger patch, and make it easier to understand what it going on in order to debug or modify it later when you have forgotten why you did this particular thing that particular way. The reference patch for this part of the tutorial is a macro, not a patch, which you can load by right clicking on the Workspace background and selecting Macros/Examples/SeqStageT.

Make a Macro of the stage modules & widgets. Start by loading the stage modules & widgets patch you created earlier, or the one created for the tutorial in the Examples directory, Tutorial2a.awp.
1. First, set up the default values for the macro-to-be. In this case, all you need to do is set the two knob values to their defaults. Set the blue note pitch knob to 24; set the yellow note duration knob to 6, which gives a duration value of 24, a quarter note.
2. Click on the toolbar Macro-ize button, the orange ball icon toward the left. You will get a confirm message - click OK. Your modules disappear from the Workspace, and in their place you see a Macro module with 1 input and 1 output.
3. Click on the "@" button on the top line of the Macro module to enter it. You will see the original modules again. In the upper left of the Workspace, instead of the large System module, you will see a Self module, which is the inside out version of the Macro module. Notice the Module Tree on the left shows the new macro with the original modules indented under it.
4. Click ont the "#" button on the top of the Self module to exit the macro. You should now see the System module and the Macro module in the Workspace.
Set the Macro Properties.

Click on the macro properties button, the blue label "B" at the top right of the module. A property dialog should pop up.
1. In the General tab, in the Name text box, enter "SeqStage" - this will be the macro name as well as the macro file name when you later save it. In the Module Tip text box, enter: "Single stage components for a multi stage sequencer."
2. In the Inputs tab, in the Label text box, enter: "Stage" - this will be the input to the macro that tells it when its stage is selected, so the stage LED can know when to turn on.
3. In the Outputs tab, first click on the More button to make a 2nd output. In the Label text box of the 1st output, enter: "Note" - this will be the note pitch value of the stage. In the 2nd output, enter: "Dur" - this will be the note duration value of the stage.
4. Click on the OK button to accept the changes and dismiss the Property dialog.

Connect the inside of the Macro to its inputs and outputs.
1. Click on the "@" button to enter the macro again. Notice that the inputs and outputs are reversed from the Macro module.
  1. Connect the 1st Knob module output to the Self module Note input.
  2. Connect the 2nd Knob module output to the Self module Dur input.
  3. Connect the Self module Stage output to the LED module input.
2. Click on the "#" button to exit the Macro. Test it by moving each knob and seeing the assigned outputs of the macro change properly. Type 1 in the Stage input and the LED should go out. Type 0 in the Stage input and it should go back on. After testing, return the knobs to their default values.
Save the Macro in the macro library.
1. First be sure the macro is set to the default setting you want
2. Click on the Property button to access the module properties.
3. Click on the Save button, located at the bottom left of the properties dialog. You will get a file save dialog showing the Macro directory. The save file name is already set to the macro name. Click on Save and the macro will be saved and the dialogs close. The macro is now part of the macro library, ready for use.

Part 3: Putting it together

Now that we have a complete single stage, we can put 16 of them together, along with a few control modules, to make a complete 16-step pitch & rhythm sequencer.

This sequencer will use a Free Run Clock to step it. The reason for the FRClock is so we can use the Dur stage knob values to feed back into the Dur input of the clock, so each time the clock ticks, it causes another stage to be selected, which in turn feeds back into the clock and tells it how long the duration of the new stage should be.

The reference patch for this part of the tutorial, in the Patches/Examples directory, is: Tutorial2b.awp, and the macro created is in the Macro directory as Step16T.awm.

Create the clock and support modules first, before creating the stages. Starting with a New ArtWonk, place them along the left edge of the Workspace.
1. These will be:
  1. A Clock/FRClock module for the timing.
  2. An Clock/Incr module to step the stages.
  3. 2 Switch/Switch modules to select the knob for the current stage.
2. In each of the Switch modules, pop up the Properties dialog, and in the Inputs tab, click the More button until you have a total of 16 Sel inputs, numbered 0-15.
Create 4 SeqStage macros that you made in the previous section:
1. Left click on the Workspace background to get the module menu. Select the SeqStage macro (or Examples/SeqStageT if you are using the prebuilt one). The SeqStage macro will appear in the Workspace, and the knob widgets will appear in the Panel. Click on the Panel background to loose the hand mover icon.
2. You can repeat the above 3 more times for a total of 4 SeqStage macros, but it is probably easier to just Copy the one you created, then Paste it 3 times. Either way, be sure you move each set of widgets with the hand icon mover before going on to the next, otherwise you will have a tedious job of moving and lining up each stacked widget. Put the widgets and the modules in a horizontal row of 4.
3. Set the correct LED widget labels and On if = number for each of the 4 LEDS. For each LED widget, right click for its Property box, then set both text boxes to the 0 based stage number, 0 for the first, 1 for the 2nd, 2 for the 3rd, 3 for the 4th.
Connect the modules for a 4 stage sequencer. We will add the other 12 stages later, after testing the 1st 4 stages.
1. Connect the FRClock Strb output to the Incr Strb input.
2. Set (type in) the Incr Limit input to 3. This will cause it to count from 0 to 3, which will select the 4 stages. Later we will change this to 15, to select all 16 stages.
3. Connect the Incr Out to the Select input of both Switch modules, and to the Stage input of all 4 SeqStage macros.
4. At this point the LEDs should be flashing each in turn as the sequencer steps 0-3. If they are not showing the stage steps, you should go back and check your work. It is important to set the correct LED On if = number, as this is what causes the LED to be on if and only if it is the selected stage.
5. Connect each of the 4 SeqStage Note outputs to the 1st Switch Sel0 to Sel3 inputs.
6. Connect each of the 4 SeqStage Dur outputs to the 2nd Switch Sel0 to Sel3 inputs.
7. Connect the Out of the 2nd Switch (the one that has the SeqStage Dur inputs) to the FRClock Dur input. This will feed back the values from the yellow duration knobs to control the clock stepping durations.
8. Try adjusting the yellow knobs, to see that the sequence steps rhythm is changed by their settings. Adjust the blue note knobs to see that the 1st Switch module shows the value set as it is selected.
Create and connect up the remaining stages.
1. By far the easiest way to create the remaining stages is to use Copy/Paste. First, set all the knobs to their default settings. This probably should be 24 for the blue note knobs, and 6 (24) for the yellow rhythm knobs, but feel free to set them however you prefer.
2. Select the 4 already existing SeqStage macro modules. Be sure only the SeqStage macros are highlighted, not any of the other modules. Then Copy all 4 macro modules by right clicking on one and clicking on Copy Selected from the popup menu.
3. Right click anywhere on the Workspace background to Paste. The Pasted modules will appear exactly on top of the original modules, and they will be highlighted so you can move them as a group. Do so by click-drag on the top line of any one module, and all 4 will move. Place them under the 1st group of 4. Then move the widgets which were also copied directly on top of the originals. Use the hand icon mover handle, to move them to the right, carefully lining them up so you have an evenly spaced group of 8 stages.
4. Now you can repeat the above 2 steps a 2nd and 3rd time, for a total of 16 stages.
5. Note that each of the stages is numbered 0-3, and of course the LED On if = setting will also be 0-3. So you need to right click on each of the 12 new LEDs and set the correct LED widget labels and On if = number for each, so you end up with labels and LED On values of 0-15.
6. Connect the Note and Dur outputs of the new SeqStage modules to the corresponding inputs of the Switch modules.
7. Change the Incr module Limit input from 3 to 15. This will cause it to now count from 0 to 15, which will step through all 16 stages.
8. Experiment with the knob settings to see that the stages are sequencing properly, and that the rhythm knob settings are giving the desired effect.
9. If you have not done so already, it would be a good idea to either save the patch so far, or to quick save it. This patch is available in the Examples directory, as Tutorial2b.awp.
Convert the patch to a macro.
1. First, set the knob values to the defaults you want, then click on the toolbar Macro-ize button.
2. Click on the macro Properties button. Be sure you are entering the macro Properties from the Macro side, where the System module is, not from inside the macro.
3. In the General tab, in the Name text box, enter the name you want, such as "Step16" (the name of the prebuilt tutorial macro is "Step16T").
4. In the Module Tip box, enter the tool tip for the module, something like "16 Stage Clock-Sequencer with pitch and rhythm knobs."
5. In the Inputs tab, click the More button 2 times for a total of 3 inputs. Enter the following into the input slot labels and tool tips:
  1. 1st input label: Limit --tool tip: Max Sequencer row
  2. 2nd input label: %On --tool tip: Percent clock is On
  3. 3rd input label: Hold --tool tip: NZ to stop sequencer from stepping
6. In the Outputs tab, click on the More button once for a total of 3 outputs. Enter the following into the output slot labels and tool tips:
  1. 1st output label: Clock --tool tip: Sequencer step clock
  2. 2nd output label: Step --tool tip: Sequencer step address
  3. 3rd output label: Note --tool tip: Note Pitch value
7. Click OK to accept the changes and dismiss the Property dialog.
Update the macro defaults.

Click on the "@" button to enter the macro.
In the Self module, which is now labeled with the macro name, "Step16," notice that the inputs and outputs are reversed from the Macro module level. Make the following connections to complete the macro:
1. Connect the FRClock Strb output to the Step16 Clock input.
2. Connect the Incr Out to the Step16 Step input.
3. Connect the 1st Switch (with the Pitch values) Out to the Step16 Note input.
4. Connect the Step16 Limit output to the Incr Limit input.
5. Connect the Step16 %On output to the FRClock %On input.
6. Connect the Step16 Hold output to the FRClock Hold input.
Click on the "#" button to exit the macro. Set the macro defaults:
1. Set the Step16 macro Limit input to 15.
2. Set the Step16 macro %On input to 50.
3. Leave the Step16 macro Hold input at 0.
Make sure the knob settings are what you want for default values.

Save the macro.
1. Click on the Properties button to get the dialog box.
2. Click on the Properties Save button to save the macro. The default file name is already set, so you only need to click the File Save dialog's Save button to save the macro and exit the dialogs.
3. You now have a completed 16 stage sequencer macro in the macro library, ready for use in any patch.

[End of Tutorial #2]