220a/miniAudicle-intro

From CCRMA Wiki

(Difference between revisions)
Jump to: navigation, search
(more stuff to change)
 
(33 intermediate revisions not shown)
Line 1: Line 1:
-
Introduction to running the miniAudicle...
+
This document shows how to open, start, and run/observe ChucK programs in the miniAudicle.
-
* '''start JACK''' (see [[220a/start-jack|starting jack]])
+
= Opening the miniAudicle =
-
there are several ways to run ChucK (e.g., via command line, Audicle, miniAudicle).  for this lab, we will primarily use the miniAudicle ([http://audicle.cs.princeton.edu/mini/ homepage]), a development environment for ChucK that includes the ChucK engine (i.e., it's all you need to starting ChucKin').
+
* '''start JACK'''
* '''start the miniAudicle via the following steps:'''
* '''start the miniAudicle via the following steps:'''
Line 13: Line 13:
(looks something like this):
(looks something like this):
-
[[Image:Terminal-mA.png]]
+
<div style="text-align: center;">[[Image:Terminal-mA.png]]</div>
miniAudicle should then open, and should include the following windows:
miniAudicle should then open, and should include the following windows:
Line 20: Line 20:
The editor serves two primary purposes.  First, it's where we write our ChucK code.  Second, we use the buttons (+, -, =) above to add, remove, or replace code into the ChucK Virtual Machine (where our code is executed, and where audio is generated).  Note how the "Add Shred", "Remove Shred", and "Replace Shred" buttons are grayed out: this indicates that the ChucK Virtual Machine is currently OFF.
The editor serves two primary purposes.  First, it's where we write our ChucK code.  Second, we use the buttons (+, -, =) above to add, remove, or replace code into the ChucK Virtual Machine (where our code is executed, and where audio is generated).  Note how the "Add Shred", "Remove Shred", and "Replace Shred" buttons are grayed out: this indicates that the ChucK Virtual Machine is currently OFF.
-
[[Image:MA-editor.png]]
+
<div style="text-align: center;">[[Image:MA-editor.png]]</div>
== virtual machine window ==
== virtual machine window ==
The virtual machine (VM) window is where we start/stop ChucK.  It also lists ChucK program pieces (called '''shreds''') that are currently running in the VM.  Since we haven't started the VM at this point, the list is empty.
The virtual machine (VM) window is where we start/stop ChucK.  It also lists ChucK program pieces (called '''shreds''') that are currently running in the VM.  Since we haven't started the VM at this point, the list is empty.
-
[[Image:MA-VM.png]]
+
<div style="text-align: center;">[[Image:MA-VM.png]]</div>
== console monitor ==
== console monitor ==
The next window, the console monitor, displays messages from ChucK, as well as from the programs that are currently running.  It logs messages from ChucK and, very importantly, '''displays when ChucK encounters an error in the code''' (which can happen when you try to add a shred).  Basically, when things aren't working as expected, this is one of the first places to check.
The next window, the console monitor, displays messages from ChucK, as well as from the programs that are currently running.  It logs messages from ChucK and, very importantly, '''displays when ChucK encounters an error in the code''' (which can happen when you try to add a shred).  Basically, when things aren't working as expected, this is one of the first places to check.
-
[[Image:MA-Console.png]]
+
<div style="text-align: center;">[[Image:MA-Console.png]]</div>
 +
 
 +
That's it, these are the different part of the miniAudicle.  Now, let's run something!
 +
 
 +
= Starting the miniAudicle =
 +
 
 +
* In order to run ChucK code in the miniAudicle, we must start the virtual machine!  To do so, press the "Start Virtual Machine" button in the Virtual Machine window.  If all goes well, it should look as follows:
 +
 
 +
== virtual machine window (running) ==
 +
If all goes well, note that the clock near the top of the window has started (this is actually displaying ChucK time!), and the "Start Virtual Machine" should now read "Stop Virtual Machine".  Additionally, your console monitor window should have no major error displayed (see below).
 +
 
 +
<div style="text-align: center;">[[Image:MA-VM-running.png]]</div>
 +
 
 +
== console monitor (OK after starting) ==
 +
It should look something like this, which tells you some information about the system (sample rate, buffer size, number of channels).
 +
 
 +
<div style="text-align: center;">[[Image:MA-Console-OK.png]]</div>
 +
 
 +
== editor (ready to ChucK!) ==
 +
If the VM was successfully started, then the editor window button should be enabled, like this:
 +
 
 +
<div style="text-align: center;">[[Image:MA-editor-ready.png]]</div>
 +
 
 +
 
 +
= Hello Sinewave (a first ChucK program) =
 +
 
 +
Let's write some ChucK code.  In this first program, we are going to:
 +
* create a sinewave generator (a '''SinOsc''' called '''foo''')
 +
* connect '''foo''' to the '''dac''' (much like the ''dac~'' object in Pd)
 +
* "advance time" by 1 second (to let the audio generate)
 +
 
 +
To do so, enter the following code into the miniAudicle editor:
 +
 
 +
    SinOsc foo => dac;
 +
    1::second => now;
 +
 
 +
That should look something like this:
 +
 
 +
== editor (containing our Hello Sinewave program) ==
 +
Don't forget the semicolons!  Also note that the numbers "1" and "2" on the left here are not part of the code but indicate the line numbers!
 +
 
 +
<div style="text-align: center;">[[Image:MA-editor-hellosine.png]]</div>
 +
 
 +
* '''now, run the program by hitting "Add Shred" in the editor'''
 +
 
 +
You should hear a 220hz sine tone for 1 second (since we didn't specify a frequency for '''foo''', it defaulted to 220hz).
 +
If you don't hear anything, check your Console Monitor window: you may have an error in the code!  For example...
 +
 
 +
 
 +
== editor + monitor (example of error in code) ==
 +
Let's say we left off the semicolon at the end of the second line, like this:
 +
 
 +
<div style="text-align: center;">[[Image:MA-editor-error.png]]</div>
 +
 
 +
When we try to "Add Shred" in the editor, nothing happens (hopefully).  So the first place to look is usually always the console monitor.  Here we see the console monitor displaying that there was a ''syntax error'' around line 2.  ''syntax error'' is ChucK's way of telling you that your code doesn't conform to the rules of the ChucK grammar (after all, ChucK is a language).  In this case, ChucK can't make sense of the code because the second line is missing a semicolon.  Also be mindful of this: line numbers in error reporting aren't always exact (ChucK may not be sure there was an problem until several lines after the actual error) - so look in the vicinity of the indicated line number when looking for errors!
 +
 
 +
<div style="text-align: center;">[[Image:MA-Console-error.png]]</div>
 +
 
 +
 
 +
== Hello Sinewave (part 2 and 3) ==
 +
* '''next, add to our program''' (if you'd like, save the file - e.g., as hello.ck):
 +
* '''add the shred!'''  what do you hear?
 +
 
 +
 
 +
<div style="text-align: center;">[[Image:MA-editor-hellosine2.png]]</div>
 +
 
 +
* '''next, add two more parts to our program'''
 +
* '''add the shred!'''  how are the pitches of the tones related?
 +
 
 +
 
 +
<div style="text-align: center;">[[Image:MA-editor-hellosine3.png]]</div>
 +
 
 +
 
 +
= Looping the Sine =
 +
So far, we've constructed a program that generates a sinewave, whose frequency is changed over time before reaching the end of the program.  What if we want to keep repeating these changes in frequency?
 +
 
 +
* '''enclose part of the code in a ''while loop'', as shown below.'''  Note exactly what went inside the while loop (between the curly brackets { }): that's the part to be repeated - and what went before and outside the while loop: creating and connecting the SinOsc (we only want that to happen once!).  We also add a line to reset the frequency to 220 at the beginning of every loop iteration.
 +
 
 +
 
 +
<div style="text-align: center;">[[Image:MA-editor-hellosine4.png]]</div>
 +
 
 +
 
 +
* '''add the shred!''' - you should now hear the sequence repeating endlessly.  To stop this nonsense (it will keep going!), press "Remove Shred".  NOTE: if you added more than one, remove shred will only remove the most recent one.  This brings us back to the Virtual Machine window.  When a shred is added and running (like our endless sequence), you should be able to see it in the VM window:
 +
 
 +
 
 +
<div style="text-align: center;">[[Image:MA-VM-hello.png]]</div>
 +
 
 +
 
 +
It's important to know that you can remove shreds directly from this list in the VM window, by hitting the minus (-) next to the shred you want to remove!
 +
 
 +
 
 +
== a little volume control ==
 +
 
 +
* '''we can control the volume of the SinOsc by setting its ''gain'', as shown below'''
 +
 
 +
 
 +
<div style="text-align: center;">[[Image:MA-editor-hellosine5.png]]</div>
 +
 
 +
 
 +
Here we set the gain to .5 (it defaults to 1) before the loop, if we want to a different gain over time, we can set it over time (similar to how we change the frequency over time).
 +
 
 +
 
 +
== changing durations + frequencies ==
 +
* '''let's keep changing stuff! - as shown below, change the durations to something other than 1::second everytime'''
 +
* '''also randomize the frequency by replacing the hardcoded 220, 440, etc. with Sta.rand2( ''MIN'', ''MAX'' )'''
 +
* '''whenever you make a change, rerun the shred either by removing then adding, or by simply hitting "Replace Shred"'''
 +
 
 +
 
 +
<div style="text-align: center;">[[Image:MA-editor-hellosine6.png]]</div>
 +
 
 +
 
 +
The "Replace Shred" is a very useful way to rapidly experiement with new ideas: make use of it!!
 +
 
 +
== more stuff to change ==
 +
Hopefully this example gave you some idea about running ChucK in the miniAudicle.  Feel free to experiment more with this example.  Possible changes:
 +
 
 +
* add to the sequence (more than 4 different frequency each loop iteration)
 +
* randomize the durations
 +
* add/run several shreds (same or different code) at the same time
 +
* add another while loop that does stuff, inside the existing while loop
 +
* change SinOsc to TriOsc (triangle), SqrOsc (square), SawOsc (sawtooth)
 +
* ??? (feel free to post results on wiki to share with others!)
 +
 
 +
To read more about loops and other control structures, check out [http://chuck.cs.princeton.edu/doc/language/ctrl.html this]
 +
in the [http://chuck.cs.princeton.edu/doc/language/ ChucK language specification].

Current revision as of 01:05, 4 October 2007

This document shows how to open, start, and run/observe ChucK programs in the miniAudicle.

Contents

Opening the miniAudicle

  • start JACK
  • start the miniAudicle via the following steps:
    • (make sure JACK is already started at this point)
    • open a terminal window
    • at the prompt type:
   miniAudicle &

(looks something like this):

Image:Terminal-mA.png

miniAudicle should then open, and should include the following windows:

editor

The editor serves two primary purposes. First, it's where we write our ChucK code. Second, we use the buttons (+, -, =) above to add, remove, or replace code into the ChucK Virtual Machine (where our code is executed, and where audio is generated). Note how the "Add Shred", "Remove Shred", and "Replace Shred" buttons are grayed out: this indicates that the ChucK Virtual Machine is currently OFF.

Image:MA-editor.png

virtual machine window

The virtual machine (VM) window is where we start/stop ChucK. It also lists ChucK program pieces (called shreds) that are currently running in the VM. Since we haven't started the VM at this point, the list is empty.

Image:MA-VM.png

console monitor

The next window, the console monitor, displays messages from ChucK, as well as from the programs that are currently running. It logs messages from ChucK and, very importantly, displays when ChucK encounters an error in the code (which can happen when you try to add a shred). Basically, when things aren't working as expected, this is one of the first places to check.

Image:MA-Console.png

That's it, these are the different part of the miniAudicle. Now, let's run something!

Starting the miniAudicle

  • In order to run ChucK code in the miniAudicle, we must start the virtual machine! To do so, press the "Start Virtual Machine" button in the Virtual Machine window. If all goes well, it should look as follows:

virtual machine window (running)

If all goes well, note that the clock near the top of the window has started (this is actually displaying ChucK time!), and the "Start Virtual Machine" should now read "Stop Virtual Machine". Additionally, your console monitor window should have no major error displayed (see below).

Image:MA-VM-running.png

console monitor (OK after starting)

It should look something like this, which tells you some information about the system (sample rate, buffer size, number of channels).

Image:MA-Console-OK.png

editor (ready to ChucK!)

If the VM was successfully started, then the editor window button should be enabled, like this:

Image:MA-editor-ready.png


Hello Sinewave (a first ChucK program)

Let's write some ChucK code. In this first program, we are going to:

  • create a sinewave generator (a SinOsc called foo)
  • connect foo to the dac (much like the dac~ object in Pd)
  • "advance time" by 1 second (to let the audio generate)

To do so, enter the following code into the miniAudicle editor:

   SinOsc foo => dac;
   1::second => now;

That should look something like this:

editor (containing our Hello Sinewave program)

Don't forget the semicolons! Also note that the numbers "1" and "2" on the left here are not part of the code but indicate the line numbers!

Image:MA-editor-hellosine.png
  • now, run the program by hitting "Add Shred" in the editor

You should hear a 220hz sine tone for 1 second (since we didn't specify a frequency for foo, it defaulted to 220hz). If you don't hear anything, check your Console Monitor window: you may have an error in the code! For example...


editor + monitor (example of error in code)

Let's say we left off the semicolon at the end of the second line, like this:

Image:MA-editor-error.png

When we try to "Add Shred" in the editor, nothing happens (hopefully). So the first place to look is usually always the console monitor. Here we see the console monitor displaying that there was a syntax error around line 2. syntax error is ChucK's way of telling you that your code doesn't conform to the rules of the ChucK grammar (after all, ChucK is a language). In this case, ChucK can't make sense of the code because the second line is missing a semicolon. Also be mindful of this: line numbers in error reporting aren't always exact (ChucK may not be sure there was an problem until several lines after the actual error) - so look in the vicinity of the indicated line number when looking for errors!

Image:MA-Console-error.png


Hello Sinewave (part 2 and 3)

  • next, add to our program (if you'd like, save the file - e.g., as hello.ck):
  • add the shred! what do you hear?


Image:MA-editor-hellosine2.png
  • next, add two more parts to our program
  • add the shred! how are the pitches of the tones related?


Image:MA-editor-hellosine3.png


Looping the Sine

So far, we've constructed a program that generates a sinewave, whose frequency is changed over time before reaching the end of the program. What if we want to keep repeating these changes in frequency?

  • enclose part of the code in a while loop, as shown below. Note exactly what went inside the while loop (between the curly brackets { }): that's the part to be repeated - and what went before and outside the while loop: creating and connecting the SinOsc (we only want that to happen once!). We also add a line to reset the frequency to 220 at the beginning of every loop iteration.


Image:MA-editor-hellosine4.png


  • add the shred! - you should now hear the sequence repeating endlessly. To stop this nonsense (it will keep going!), press "Remove Shred". NOTE: if you added more than one, remove shred will only remove the most recent one. This brings us back to the Virtual Machine window. When a shred is added and running (like our endless sequence), you should be able to see it in the VM window:


Image:MA-VM-hello.png


It's important to know that you can remove shreds directly from this list in the VM window, by hitting the minus (-) next to the shred you want to remove!


a little volume control

  • we can control the volume of the SinOsc by setting its gain, as shown below


Image:MA-editor-hellosine5.png


Here we set the gain to .5 (it defaults to 1) before the loop, if we want to a different gain over time, we can set it over time (similar to how we change the frequency over time).


changing durations + frequencies

  • let's keep changing stuff! - as shown below, change the durations to something other than 1::second everytime
  • also randomize the frequency by replacing the hardcoded 220, 440, etc. with Sta.rand2( MIN, MAX )
  • whenever you make a change, rerun the shred either by removing then adding, or by simply hitting "Replace Shred"


Image:MA-editor-hellosine6.png


The "Replace Shred" is a very useful way to rapidly experiement with new ideas: make use of it!!

more stuff to change

Hopefully this example gave you some idea about running ChucK in the miniAudicle. Feel free to experiment more with this example. Possible changes:

  • add to the sequence (more than 4 different frequency each loop iteration)
  • randomize the durations
  • add/run several shreds (same or different code) at the same time
  • add another while loop that does stuff, inside the existing while loop
  • change SinOsc to TriOsc (triangle), SqrOsc (square), SawOsc (sawtooth)
  •  ??? (feel free to post results on wiki to share with others!)

To read more about loops and other control structures, check out this in the ChucK language specification.

Personal tools