Tutorial #1: Getting Started
This is a startup tutorial that will introduce you to the basic elements of
MusicWonk. 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:
- Start with the Tiny Tutorial from the Introduction. Here it is again:
- 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.
- 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.
- 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.
- Right click on the Workspace to get the module pop up menu and select
Knob from the Widget
- 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.
- 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.
- 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.
- Rather than just getting program numbers, it would be better to see the
patch names as you change them.
- Pop up the module menu, and select the macro called "PBName.awm"
- 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.
- 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.
- 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 MusicWonk/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 MusicWonk 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.
- 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.
- 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.
- 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.
- 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.
- 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
- 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.
- 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.
- Click on the "A" button on the PBName Self module.
This will pop up the Properties dialog for the macro.
- 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."
- 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.
- 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 MusicWonk will not have connections
to non existing inputs or outputs.
- 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.
- 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
- 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.
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
- 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:
- Get a Switch module from the
module popup: Switch/Switch.
- 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
- 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.
- 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.
- Drag the Switch output to the MIDI Voice Note
input, replacing the Random Int connection. Click on the toolbar
Play button to hear it.
- 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
- 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.
- 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.
- 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.
- 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..
- 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.
- 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
- 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:
- 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.
- 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.
- 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:
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.
- 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.
- 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"
- 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.
- 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:
- Set the Chan input to 1.
- Set Lgto to 1 for legato play.
- Drag the function module output to the Note input.
- Drag the Program macro output to the Prog
- Drag the System module Play output to the
- 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.
- 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
MusicWonk 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.
- 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.
- 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
- 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.
- 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
- 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]
MusicWonk is Copyright © 2003-2010 by John Dunn and Algorithmic
Arts. All Rights Reserved.