ArtWonk Tutorial #1: Getting Started

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.

Additional tutorials may be found on our web site:

http://algoart.com/tutorials.htm

Part 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), right click on the Workspace background to get the module menu. Select Clock from 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. Drag the Rand Int output to the MIDI Voice Note input. Finally, type 1 in the MIDI Note Play input, replacing the 0. At this point you should hear random notes. It ain't much but it's a start!
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. 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.
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.
Click on the Playback button (speaker icon) to hear your MIDI file. It should play back exactly as it was recorded.
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 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 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 "Tutorial1a.awp," which is this tutorial up to this point, and checking it against your own patch.

Part 2

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 "PBName.awm" from Macros/Examples.
2. Use the hand icon "mover" that shows up in the upper left corner of the new Panel graphics to move them where you want, especially if they are showing 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 PBName 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, and adjust the little green Prog knob in the Panel. You should hear different instruments as you adjust the knob, and you should see their MIDI Prog number and instrument names.
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.
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 or a hardware synthesizer), you can change the names in the text file in the ArtWonk/Names directory. Be sure to start by reading the readme.txt file.
Notice that the instrument names in the Panel label are one off from the number in the PBName macro Prog output. This is because MIDI program numbers are 1 based, but ArtWonk is 0 based in most array type numbering. Now go into the Macro to change the Prog number label to be 0 based so it reads the same as the macro output.
1. Click on the "@" button of the PBName macro to enter it. The Workspace will change to display the inside of the macro. Notice that the Module Tree also opens up to show the modules in the macro.
2. Notice that the Workspace Readout module (G) that displays the Panel Prog number label is connected to the Workspace Add module directly below it, which is adding 1 to the Knob module output. Connect the Knob module output directly to the Readout module input, replacing the Add connection. Try moving the Prog Knob in the Panel, and it should now be 0 based.
3. You don't need the Add module any more, so delete it. Notice that the Tree is redrawn, and that all the priorities (the A, B, C, etc. on the upper right of each module, and in the input connections) have been adjusted.
4. In fact, you aren't using any of the Bank change modules so delete the entire group of them. To do this, click on the Workspace background to the upper left of the first module in the Bank column of modules, and drag the mouse cursor toward the lower right, enclosing the entire column of modules. The module names will turn red as they are selected, so make sure you get all the modules in the Bank column selected. Then release the mouse button and right click on any of the red labeled selected modules and click on the "Delete Selected" menu item. The selected modules and their Panel graphics are deleted.
5. The white "Banks" label above the now deleted column of modules was not deleted. To delete this, right click on it to get the Workspace doc properties dialog. Notice the text box shows the label text, "Banks." In the upper right of the dialog you will see a vertical up/down button labeled with "+" and "-." Click on the "-" to delete the label. Click OK to keep the change and dismiss the property dialog.
Now you've eliminated the unneeded modules from the macro, but you still have the now unneeded Bank output. So delete that, so the macro will have only the one Prog output.
1. First, notice the Self module in the upper left corner of the Workspace, labeled the same as the Macro module one level up, "PBName" and has the priority label of "A."
  
  This has two inputs labeled "Prog" and "Bank." When you are inside a macro, the Self module is the inverse of the Macro module one level up: all the Macro inputs become Self outputs, and all the Macro outputs become Self inputs. In this case, there are no Macro inputs, so there are no Self outputs; and there are two Macro outputs, so there are two inputs to the Self. So you need to delete the 2nd macro output (which is here the 2nd Self input) for the unneeded Bank.
2. Click on the "A" button on the PBName Self module. This will pop up the Properties dialog for the macro.
3. On the first tab you will see the macro name, "PBName," and the module tool tip, "Select & display program change and bank number." Change the name to "Program," , and change the tool tip to "Select & display program change."
4. Now select the "Outputs" tab of the dialog. Remember, macro outputs are self inputs, so you will see the macro outputs as inputs from the Self view. Click on the Fewer button to remove the unneeded output. Click OK to accept the changes and dismiss the dialog.
5. You've eliminated the Bank output (Self input), but the self Prog input connection that you want to keep has been broken! This is because whenever you change the number of inputs or outputs to a Macro module, it erases all connections to it. This insures ArtWonk will not have connections to non existing inputs or outputs.
6. Re establish the Macro output by dragging the Knob module output to the Self module Prog input, then click on the "#" button to close the Macro.
7. If you like, you can now save the modified Macro, to add it to your macro library. To do this, click on the Macro Properties button, then click on the Save button in the lower left corner of the properties dialog.
8. If you don't see the Save button it's because you've entered the Macro from its Self module, which is the same property dialog but without the Save. In this case, Cancel, go up to the parent level by clicking on the "#" button of the Self module, and try again.

Part 3

Now create a 2nd voice. Since this is just a simple random note pumper, we will stay with the random theme but make it a bit less random, a bit more harmonic.
First change the two octave chromatic scale the Rand Int module is producing to a 1 octave C major scale. There are any number of ways to do this, including a FitScale module to do it directly. For this tutorial we will create the scale on a Switch module, then run the Random Int into the switch:
1. Get a Switch module from the module popup: Switch/Switch.
2. You need 8 inputs, not the default 3. So click on the Switch Properties button go to the Input tab, and click the More button 5 times to get a total of 8 inputs. You should have one Select input followed by 8 Sel inputs, Sel0 to Sel7.
3. Set the 8 Sel input default values to the intervals of the C Major scale (you could just as well do this at the module inputs): 0, 2, 4, 5, 7, 9, 11, 12. Click on the OK button to accept the changes and dismiss the properties dialog.
4. Drag the output of the Rand Int module to the Select input of the Switch module. You should see the switch output randomly selecting the C major scale intervals.
5. Drag the Switch output to the MIDI Voice Note input, replacing the Random Int connection. Click on the toolbar Play button to hear it.
6. Type 1 into the Lgto (legato) input of the MIDI Voice module. This causes notes to play for the full clock cycle, and to only play a new note when the input changes.
Make a 2nd musical line. This will be just random C Maj triad intervals. You can see how this might easily be done with the Switch module, but this is a tutorial, so you get to do it the hard way, with a Function module.
1. Right click on the Workspace, and from the module pop up menu, select Function/NewFunction to create a Func module. Click on the property button to open the property dialog.
2. The task here is to create a random triad generator. One way to do this is to create a small array of the values we want, the intervals 0, 4, 7 and 12, and then select the array elements 0-3 randomly. So the function will have two parts, a setup part that creates the array values, and a run part that returns the random intervals from the array.
3. First, create the array. Function modules have both private arrays and public arrays that other function modules (and sequencers and array modules) can access. For this, you can use the module's private array because it's easier and there is no need to share it.
  1. Click the Fn Reset tab. Any functions placed in this text box will be run when and only when a Reset flag is sent. By default (changable in the System module Properties) when you click on the toolbar Play button, the Reset flag will be tripped, which in turn causes the Func module to run the script in its Fn Reset text box..
  2. Click once inside the text box to place the text cursor in it. Then click on the Fn Prototypes tab. This is where you get the a quick view help, and where you can get the proper spelling and required parameters for functions.
  3. Open the Local Array branch by clicking once on the + node box, or double clicking on "Local Array." The function you need is "Store." Click on the line that starts with Store, and you will be put back into the Fn Load edit box, with the Store function prototype entered at the cursor.
  4. Highlight the function that was inserted at the cursor, right click, and copy it to the clipboard. Then paste it into the text box three more times, once per line:
    
    Store(Index, Val)
    Store(Index, Val)
    Store(Index, Val)
    Store(Index, Val)
  5. Now replace "Index" with the actual index value, 0-3; and replace Val with the actual values you are going to want returned, 0, 4, 7, 12.
    
    Store(0, 0)
    Store(1, 4)
    Store(2, 7)
    Store(3, 12)
  6. Click on the Test button to make sure the function is OK. If there is an error you will get a message. No message means it's good.
4. Now click on the Function tab, to write the main function. You will see the default function there already, which simply sends Input 1 to Output 1. Replace that text with the following:
  
  Out(1, Fetch(Ran*3))
  
  This will create a random number between 0-3 to act as an index to the 4 element array that was set up in the Fn Load section. Click on the Test button to error check the function.
5. Now click on the Inputs tab. This function should only run when it is needed, not at every loop cycle. It will work if it is run every loop cycle, but doing this is very wasteful of CPU cycles. In a program this small it won't be noticeable, but you might as well do it correctly from the start. So click on the checkbox in the lower left of the dialog, that says, "Run on In1 Strobe." Notice that the input label and tool tip has changed.
6. Click on the General tab. Give the function a meaningful name, like "RanNotes" or whatever you like. Give it a meaningful tool tip, like "Produce random triad intervals"
7. Finally, give the module a different color icon by selecting one from the list. Some modules, like Macro modules, have specific colored icons for specific functionality. Some, such as Function and Global Variable modules have user assigned colors. The idea is that you can use icon colors to group functions in a manner that is meaningful to you within the context of your patch. For now, just pick any color you like.
8. Function modules can be saved into a library just as Macro modules can. So if you like you can save it now. Just click on the Save button in the lower left corner of the dialog. If you Save you will automatically exit the properties dialog. Otherwise, click the OK button to accept the changes you've made and dismiss the dialog.
At this point you should have a newly created function module that sends out a random triad interval when strobbed. Connect the Clock Strb output to the Strb input of your function module. You should see the random interval values of 0, 4, 7, 12 on each clock tick. If you are not seeing this, click on the Reset button in the Workspace Toolbar, just to the left of the round transport buttons. This forces a Reset and causes the Fn Reset script to execute. Still no luck? Open the function module again and check your work. Or if you'd rather just move on, you can load the existing function, called "RanTriadT." Load the function with the module popup menu.
Now create another MIDI Voice module. Set it up as follows:
1. Set the Chan input to 1.
2. Set Lgto to 1 for legato play.
3. Drag the function module output to the Note input.
4. Drag the Program macro output to the Prog input.
5. Drag the System module Play output to the Play input.
6. Drag the Clock module Strb output to the Clock input. This is optional because when Lgto is set, the clock is ignored. But you might as well set it up now so you can experiment with how it sounds with legato on and off.
Click on toolbar Play to hear the module.
1. Hmm. There is something wrong, a slight out-of-sync glitch. Something is being calculated out of order, and is then coming in 1 tick late. With ArtWonk you need to pay attention to the order in which modules are calculated. In particular you want the MIDI Output modules to be the last modules in the calculation chain.
2. Change the calculation order of modules, called the module priority, with the Module Tree. Notice the modules are lined up in the Tree in order, first A then B then C, etc. So all you need to do is move the MIDI module to the end of the list and things should be OK. Do this by clicking on the name of the module in the Tree you want to move, which will be the MIDI modules. Then right click on the name of the module in the Tree you want to insert it to.
  
  When you right click on a target below the module you are moving, the module will be placed after the the target; when you right click on a target above the module you are moving, the module will be inserted before the target. Now move the two MIDI modules to the end of the priority list. It does not matter which one is last and 2nd last. After the MIDI modules have been moved down, play the sound; it should now be glitch free.
Now that you have both voices running you can put in a couple widgets to adjust the timing and transpose.
1. Create a Slider module from the module popup Widget sub menu. Shift-click on the widget to drag it into position. This will be the Clock Duration control.
2. Set the slider range from 3 (32nd note) to 48 (half note). To do this, right click on the slider widget graphic in the Panel, or click on the properties button on the Slider module in the Workspace. In the properties dialog, set both Output Value and Display Value to a Range of 45 and an offset of 3. Click OK to dismiss the dialog. Your slider should now have a range of 3 to 48. Drag the Slider module output to the Clock Dur input. Click on Play and noodle with the slider to hear the duration changes.
3. Create one more slider for transposition. Set the slider range to 48 and the offset to 24 to give a 4 octave transpose range of 24 to 72. You might want to change color of the slider, or set the label to "Tr" for transpose (and perhaps set the other slider's label to "Du" for duration). Drag the new Slider module's output to the Transp input of both MIDI Voice modules, replacing the default transpose of 48.
Change the Pan settings of the Midi Voice modules for left/right sound. Type 32 into one and 96 into the other. Click on Play and noodle around. When you get to something you like, go to the next and final stage of this tutorial, which is to record it as a MIDI file.
Set the System Module RcEnd (Recording End) input to 48, which will set any notes that had been left on when the recording ends to half notes instead of the default quarter notes. Usually when you record you should click on the toolbar Record button first, then the Play button to start the recording. To end the recording, you should click on the Play button to pop out both Play and Record.
If you like, you can load the patch file, "tutorial1c.awp" which is the finished tutorial patch up to this point.
You might try changing the MIDI Voice Lgto inputs back to 0 so the modules are controlled by the Clock input. Best way to do this is to use an OnOff Button module, in the Widget sub menu.

[End of Tutorial #1]