Tutorial #1: Getting Started

This is a startup tutorial that will introduce you to the basic elements of ArtWonk. It will create a simple 2 voice random note player that can be adjusted with widgets in the user interface panel, and can be played and recorded with the tool bar transport buttons.


Part 1

  1. Start with the Tiny Tutorial from the Introduction. Here it is again:
    1. After you have set the MIDI Output driver (you don't need an Input driver yet), and you are ready to proceede with the tutorial, select File/New to get a fresh start.  Now right click on the light blue Workspace background to get the module menu. Select Clock from the top of the Clock sub menu. Pop up the module menu again and select Rand Int (not Random) from the Pattern menu.
    2. Click and drag the Strb output of the Clock to the Strb input of the Rand Int module. You should see the output of the Rand Int changing, showing values from 0 to 24, the default setting.
    3. Pop up the module menu, and select MIDI Voice from the MIDI Out menu. Drag the Clock Strb output to the MIDI Voice Clock input. You should hear a steady one note beat. Drag the Rand Int output to the MIDI Voice Note input.  At this point you should hear random notes. You can turn it off by typing 0 into the Play input at the top of the MIDI Voice module.
  2. Make the sound respond to the toolbar Play button by connecting the System Module Play output to the MIDI Voice Play input. Sound should stop if it was playing. Now click on the Play button on either toolbar. When Play is in, you should get sound, when it is out, you should get silence.
  3. Although the sound isn't much yet, you do have enough to create a MIDI file. So give this a try. Simply click on the toolbar (either one) Record button. It will turn red. Then click on Play and let it run for a few bars. Then click on Play again to stop.
  4. Click on the Playback button (speaker icon) to hear your MIDI file. It should play back exactly as it was recorded.
  5. It would be nice to be able to change instruments. You can do this with the Prog input to the MIDI Voice.
    1. Right click on the Workspace to get the module pop up menu and select Knob from the Widget submenu.
    2. Notice that you get not only the Knob module but also a knob graphic in the upper left corner of the dark blue Panel. Move the knob to the center of the panel by holding down the shift key and dragging it with the mouse.
    3. Plug the Knob module output into the Midi Voice Prog input. Now click on the Play button to get sound and try different knob settings. Default Knob movement is up/down for large changes and left/right for small changes. You should hear different instruments playing.
    4. At this point, if you are not getting the results you expected, you might try loading the patch file in the Tutorials folder, "Tutorial1a," which is this tutorial up to this point, and checking it against your own patch.
    5. If you want to do a temporary save of your current patch, click on the Quick save icon, the red floppy 4th from the left of the lower toolbar.  This saves the patch as "Quick#" with the "#" as 0-9, automatically rotating. 

Part 2

  1. Rather than just getting program numbers, it would be better to see the patch names as you change them.
    1. Pop up the module menu, and select the macro called "ProgList" from Macros/MIDI Control/Parts."
    2. Use the hand icon "mover" that shows up in the upper left corner of the Panel graphic to move it where you want, especially if it landed on top of the knob you created earlier. Click on the Panel background to dismiss the hand icon. If you should want to move the graphics as a group again, just click on the Panel background and drag the rubber band box that will show up to enclose the items you want to move as a group, then move the box, and again click on the background when you are finished moving to dismiss the temp group box.
    3. Back in the Workspace, connect the Prog output of the newly created ProgList macro to the Prog input of the Midi Voice module, replacing the Knob connection previously made. Click Play in the toolbar to play the patch, selecting the instrument names from the list box widget, or by clicking on the Inc/Dec widget to change one at a time. You should hear different instruments as you go, and you should see the highlighted MIDI Prog number and instrument name selected.
    4. You don't need the knob you created earlier, so delete it. To do this, right click on the Knob module in the Workspace (not on the Knob graphic in the Panel), and select Delete from the pop up menu. Both the module and the graphic are deleted.
  2. The program names you see in the Prog label are the default General Midi names. If your synth is not GM (just about all sound cards are, so this applies mostly for those who are using a soft synth/sampler or a hardware synthesizer), you can change the names in the text file in the ArtWonk Names folder. Be sure to start by reading the readme.txt file.
  3. The tutorial up to this point can be found in the Tutorials folder as "Tutorial1b."

Part 3

  1. Now create a 2nd voice. Since this is just a simple random note pumper, we will stay with the random theme, but try to bump up the interest a little. First thing, swap out the RandInt module with a RandWalk module.  This will keep the random but give it more of a pattern. 

  2. Pop up the Workspace module menu, and select RandWalk from the Pattern group.  Connect the Clock module Out to the RandWalk Strb (strobe) input.  Connect the RandWalk Out to the MIDIVoice Note Input. Delete the RandInt module.
  3. In almost every patch MIDI output control is needed, so there are several Macros that simplify setting up MIDI out.  Start by going to the Help menu and browsing Macro Help for MIDI Control macros. 

  4. Use the MIDI2 macro for this patch, which gives 2 MIDI output channels and basic Panel controls.  Right click on the Workspace, and in the pop-up module menu, select Macros/MIDI Control/2-Voice/MIDI2.  How would you know where to find that?  Simple, the Macros menu is set up the same as the Macros Help.  So by browsing Help you get an idea of what you need and where to find it.

  5. As before, the Macro graphic shows up in the upper left corner of the Panel with the 3-hand mover icon attached.  So move the graphic somewhere toward the center of the Panel, but not on top of anything else, then click on the background to dismiss the mover icon.
  6. MIDI2 replaces the MIDIVoice module and the ProgList macro, so delete them by right clicking on the top of each Workspace module (not the Panel graphic), and selecting "Delete."
  7. Now connect the Clock Out to the MIDI2 L.Clock input. Connect the RandInt output to the MIDI2 L.Note input, and the System module Play output to the MIDI2 Play input.  At this point you should be back where you started: Click the toolbar Play button and you get random notes.  If you do not, go back and check your connections. 
  8. The tutorial up to this point can be found in the Tutorials folder as "Tutorial1c."
  9. Before moving to the next part, take a moment to look inside the MIDI2 macro. Macros are simply containers for more modules.  To get inside, click on the "@" symbol on the top right.  You will see the two MIDIVoice modules along with the other support modules.  Click on the "#" symbole on the MIDI2 container module in the upper left of the Workspace to return to the main Workspace.  You could also click on the "Start" line in the white module tree to the left of the Workspace.


Part 4

  1. Before setting up the 2nd voice, give the totally random chromatic scale some manners.  There are any number of ways to do this, but the simplest and most comprehensive is to use the FitScale module. So right click on the Workspace and select Process/FitScale. This module coerces its input note to the nearest note of the scale selected by the Scale input.  There are over 80 different scales to choose from, but for now we will pick #1, Major (Ionian). So type "1" in the Scale input. (A fast way to input constants is to double click on the input and a table will pop up.  Most constants are given note durations, but a number is a number.  Click on the number you want, in this case "True=1."  You can change this table to suit your own needs by editing Constants.txt in the ArtWonk Settings folder.)
  2. Now connect the RandWalk output to the FitScale In input, and connect the FitScale Out output to the MIDI2 macro L.Note input.  Click the Toolbar Play button to hear the results.
  3. The random notes should now be slightly less random, being confined to the C Major scale (the key is set by the yellow Transpose knob in the MIDI2 Panel graphic).
  4. Finally, we can add a 2nd voice. There is no limit to the ways you can play one voice off another in ArtWonk just as in music at large.  For this tutorial we will go with the DitherBack macro, which sort of wanders back and forth.  Read about it in Macros Help/Misc Macros.   Get it from - you guessed it - the Workspace pop-up module menu: Macros/Misc. Macros/DitherBack.
  5. Now connect the Clock output to the DitherBack Clock input, the FitScale Out to the DitherBack Note input, and the DitherBack Note output to the MIDI2 R.Note input.  Finally, connect the Clock output to the MIDI2 R.Clock input.
  6. Although it's not likely to matter in this simple patch, MIDI Out modules should always be the last in the processing chain since that is the last thing each calculation cycle does, send the MIDI messages out to the sound device.  To move MIDI2 to the end of the chain, left click on its name in the white module tree to select it for moving, then right click on the last module in the tree, DitherBack.  You should see the tree rearrange itself so MIDI2 is at the end of the chain. If you are getting little 64th note glitches in your sound, chances are the modules are in the wrong calculation order, and usually it's because MIDI out is not at the end of the chain.
  7. Click the toolbar Play button to audition your patch.  Try speeding up the clock a bit (more about that later) by typing 12 into the Clock Dur input (or you can double click the input text box and select 8th=12 from the constants list).  Try turning on Legato by clicking on the little blue "L" button in the upper left of the MIDI2 Panel graphic (it will turn yellow to show Legato is on).  Legato in the ArtWonk context sends MIDI Off messages only at the very end of a MIDI note.  This causes the note to be on for its entire duration, and it also causes double or multiple notes to play as a single long note.  The results are often surprising.
  8. The tutorial up to this point can be found in the Tutorials folder as "Tutorial1d."

Part 5

  1. For a finishing touch we will add a scale picker and some clock control.  The scales that are built into the FitScale module are available in the ListBox widget.  Right click on the Workspace to get the module menu, select Widgets/ListBox.  The Panel graphic will appear in the upper left as always.  Shift-click-drag to place it where you want.
  2. Left click on the ListBox graphic to open its properties box.  You can also open the widget properties by clicking on the Properties button on the top right of the module.  Use the sliders to adjust the size, and select the "FitScale" option button on the right, 2nd from the bottom.  You should see the list box fill up with scale names.  Click "OK."
  3. Connect the ListBox Index output to the FitScale Scale input.  Also connect the ListBox Index to its own Index input.  This will cause it to remember its setting when you save the patch.  Click on the Toolbar Play button and try out some different scales.
  4. Now for the clock control.  A word here about rhythm might be in order.  ArtWonk has many different ways to set up rhythms, simple and complex, loose and tight.  And it eats rhythm boxes for lunch, once you become familiar with the tools (hint: see the Ary Clock sequencer macros). But this tutorial patch as well as many of the Example patches and most of the clock control macros use a single value totally robotic rhythm - why is that?  Mainly it's because ArtWonk specializes in data driven compositions, such as DNA music, that works well with monorhythms, where the clock (or clocks) hold steady and the rhythm is perceived from other cues, mostly pitch changes. So if you want more traditional rhythms you certainly can have them with ArtWonk, but if you are willing to give its monorhythms a try you might be surprised with the rich creative material you find there.
  5. So, as with the MIDI Control, brows Help/Macros/Clock Control to get an idea of what's available. You are free to experiment with any of them of course, but for now use the ClkDur%ON macro.  You know the drill: right click on the Workspace, select Macro/Clock Controls/ClkDur%ON.  Move it wherever you like and dismiss the mover by clicking on the Panel background.
  6. Connect the Dur and %On outputs of the ClkDur%ON macro to the Dur and %On inputs of the Clock module.  While you're at it, connect the System module Stop output to the Clock Hold input, so when the Toolbar Play button is out (Play=0 and Stop=1), the clock and all activity driven by it will freeze.
  7. As a last step, move the MIDI2 module to the end of the calculation cycle.  Left click on its name in the white module tree to the left of the workspace, then right click on the last module in the tree, the ClkDur%ON. You will see the chain rearrange itself so MIDI2 is now at the end.  Strictly speaking, Panel widgets are asynchronous with the calculation chain and you don't really need to put them ahead of MIDI.  But its still a good idea to keep the MIDI modules at the end, like signaling a turn even when there's no traffic.
  8. Take some time to explore what you've built.  Most of the control widgets and all of the module labels give tool tip help messages when you hold your cursor over them for a moment.  Also, it is easy to trace what modules are plugged into what by clicking on the labels.  If there is a connection, the connected modules' label will highlight, turning what seems at first to be an impossible jumble into a readable signal flow.
  9. This concludes the "Getting Started" tutorial. This last part can be found in the Tutorials folder as "Tutorial1e."
[End of Tutorial #1, Getting Started]


ArtWonk is Copyright 2003-2014 by John Dunn and Algorithmic Arts. All Rights Reserved.