miniAudicle

version: 0.1.3.7 (alpha)
For the most up-to-date version of this document,
please visit http://audicle.cs.princeton.edu/mini/mac/doc/

Contents

Introduction

The miniAudicle is a graphical integrated development environment for the ChucK digital audio synthesis environment. miniAudicle allows ChucK programmers to develop programs and utilize on-the-fly programming features outside of the sometimes cumbersome command-line interface. Its features include:

Planned features include:

System Requirements

Currently miniAudicle supports PowerPC G3, G4, G5, or Intel processors and Mac OS X 10.3.9 or greater.

Installation

1. To install, first download the miniAudicle disk image at http://audicle.cs.princeton.edu/mini/.

2. Mount the disk image by double-clicking it. Open the disk image and simply drag the miniAudicle application to your /Applications folder or your desired location.

3. If you like, make a shortcut (to the newly installed miniAudicle) in your System Dock.

4. To run miniAudicle, simply double-click the miniAudicle application in Finder, or open it from the Dock.

Tutorial

If you are new to ChucK programming, the following tutorial should set you well on your way to producing righteous ChucK programs. If you are already familiar with ChucK, you could probably skip ahead to the next section, or open up the miniAudicle and start hacking.

When the miniAudicle is first started, you will see a large blank window and a small window titled "Virtual Machine". To get started, click on the button "Start Virtual Machine" in the small window. If you have used ChucK on the command line before, this is analogous to running chuck --loop. A window will appear called the "Console Monitor"; this window displays any textual information emitted by the virtual machine as it operates.

Once the virtual machine is started, you are ready to start ChucKing! For starters, type or copy/paste the following simple ChucK program into the blank editing window: 

  SinOsc s => dac;
  .2 => s.gain;
  <<< "Hello, worlD!" >>>;
  3::second => now;
Once this code has been entered, click on the "Add Shred" button at the top of the window. You should hear a sine wave sounding for three seconds. In the Virtual Machine monitor, you should see a row appear in the "shred table". On the console monitor, the text 
  [chuck](VM): sporking incoming shred: 1 (Untitled)...
  "Hello, worlD!" : (string)
should print. If all these things occurred, then you have successfully run a ChucK program!

The "Add Shred" button attempts to run whatever code is in the current window on the virtual machine. If you haven't started the virtual machine yet, this button will be greyed out and disabled, because there is no virtual machine to add it to. You can add code in a particular window as many times as you like. Each time you click on "Add Shred" a new "shred" is created to execute that code. Thus, for the code above, if you click on "Add Shred" 10 times in rapid succession, you will hear the sound of 10 simulataneous sine waves mixed together for about three seconds.

Now, in the program you entered in above, try changing the word "second" to "day". The new program should look something like this: 

  SinOsc s => dac;
  .2 => s.gain;
  <<< "Hello, worlD!" >>>;
  3::day => now;
Go ahead and run the program. You might have noticed that this program is similar to the previous one, except that it will run for three days instead of three seconds. Now, for most purposes, three days is far too long! If that is the case, it is easy to prematurely terminate the running shred. Simply click on the "Remove Shred" button.

Try running this program 5 times in succession. You will hear several sine waves now. If you click on "Remove Shred", only the shred which was most recently added will be removed. How do you get rid of all those other shreds? Notice the "shreds" table in the Virtual Machine monitor. Each entry in the table has a "shred id", a "name", and a button next to it with a "-" sign in it. The name is the name of the file, which in this case is "Untitled". The shred id is a unique id assigned to each shred by the virtual machine. Clicking on the button serves to remove the shred corresponding to that entry in the shred table. In this way, you can stop execution of any shred you like in the virtual machine.

Now, suppose you wanted to quickly remove all of the shreds that are currently running. This is easily accomplished by clicking on the "Remove All" button at the top of each code window.

Suppose that you really like this sine wave program, and you would like to keep it for later use. Like most text editors, miniAudicle supports saving, opening, and creating new ChucK source files, and keeping multiple ChucK source files open at the same time.

Now you are well on your way to writing masterful ChucK programs. Please read on for further information on how to use miniAudicle. For more information about the ChucK programming language and on-the-fly programming please visit the ChucK website, particularly the documentation and example code sections.

Interface Reference

On-the-fly programming commands

miniAudicle supports the Add, Replace, Remove, Removeall, and Removelast on-the-fly programming commands. These can be invoked by clicking on the appropriate button in the toolbar of each document window. These commands are also available in the ChucK menu. The Add, Replace, and Remove commands can be invoked by the key combinations Command +, Command =, and Command -, respectively. Removeall can be triggered by Command Delete.

The Add, Replace, and Remove commands refer to the active document window, i.e. the topmost document window, when invoked from the ChucK menu or by a key combination. Note that on the fly programming commands are disabled whenever the virtual machine is not running.

The behavior of these commands are as follows:

Add Shred
Adds the active document to the virtual machine.
Replace Shred
Simultaneously removes the most recently added shred corresponding to the active document and adds the active document to the virtual machine
Remove Shred
Removes the most recent shred corresponding to the active document
Remove Last Shred
Removes the most recently added shred, irrespective of the active document
Remove All Shreds
Removes all shreds on the virtual machine

Virtual Machine Monitor

The Virtual Machine monitor provides a real-time overview of the status of the virtual machine. It displays the length of time the VM has been active, the number of shreds that are currently running, and a list of information for each running shred.

To start the virtual machine, click on the "Start Virtual Machine" button. Clicking this button again will stop the virtual machine. The virtual machine can be stopped and started as many times as desired. Each time the virtual machine is stopped, all running shreds are removed.

When the Virtual Machine is started, miniAudicle also opens up the default port to accept on-the-fly programming commands from other sources, such as the chuck command line program, the ChucK Shell, or other programs.

The shred table lists all shreds running on the virtual machine as they are added. To remove a shred from the virtual machine, click on the "-" button at the right of each shred entry.

The Virtual Machine Monitor can be opened and closed by selecting "Virtual Machine Monitor" from the "Window" menu, or pressing the key combination Command 1.

Console Monitor

The console monitor prints virtual machine text output and ChucK log information. This is the same text which is printed to stdout and stderr when chuck is run from the commmand line. Currently the Console Monitor does not support stdin textual input.

The Console Monitor can be opened and closed via the "Console Monitor" menu item in the "Window" menu, or using the Command 2 key combination.

ChucK Menu

In addition to on-the-fly programming commands, the ChucK menu has the Start Virtual Machine menu item and Log Level menu item. The Start Virtual Machine menu item is semantically the same as clicking on the Start Virtual Machine button of the Virtual Machine Monitor. Additionally, the Virtual Machine can be started and stopped using the Command . key combination.

The Log Level menu item allows users to adjust the verbosity of ChucK's logging system. The verbosity is measured on a scale from 0 to 10, with 0 corresponding to no logging and 10 corresponding to logging of everything. The current log level is checked in the Log Level menu.

The log is printed to the Console Monitor.

miniAudicle User Interface Elements

miniAudicle User Interface Elements (MAUI Elements) are objects instantiated within a ChucK program which create graphic user interface controls in the miniAudicle. Through these user interface controls it is possible to receive input from the user, and also send output back to the user. In this way, parameters in ChucK code can be controlled in real time using graphical controls.

Currently, miniAudicle supports sliders, buttons, and light emitting diodes (LED's).

To start using MAUI Elements, try running the following ChucK code: 

  SinOsc sine => dac;

  MAUI_Slider slider;
  slider.range( 200, 2000 );
  slider.name( "frequency" );
  slider.display();

  while( 1 )
  {
      slider.value() => sine.freq;
      slider => now;
  }
Running this code will do two things. First, you will hear a sine wave sounding at 200Hz. Second, a small window will appear with the text "frequency" in it, the number "200", and a graphical slider. Try moving the slider around. You will notice that the frequency of the sine wave changes as you move the slider, and that the slider window displays the current value of the slider.

Now, lets take apart the code above. The line MAUI_Slider slider; declares and initializes the slider. The line slider.range( 200, 2000 ); sets the inclusive minimum and maximum values of the slider to [200, 2000]. The line slider.name( "frequency" ); sets the display name of the slider to "frequency". The line slider.value() => sine.freq; assigns the current value of the slider to the freqency of the sine oscillator. Lastly, the somewhat cryptic line slider => now; tells virtual machine to block execution on this shred until the value of the slider is changed.

ChucK code which employs MAUI Elements will typically not work on ChucK virtual machines outside of the miniAudicle. However, when the miniAudicle is released for Windows and Linux, code employing MAUI Elements will work correctly on all three platforms.

For more information about how to use the MAUI Elements API to build graphical user interfaces in ChucK, please visit the MAUI API Reference.

Support, Contact, Mailing Lists

Have any questions about ChucK or miniAudicle not answered here? First, see if you can figure it out on the ChucK or miniAudicle website.

Second, consider subscribing to the chuck/chuck-users email list and posting your questions there.

Thirdly, bug reports, features requests, and unsolved questions regarding miniAudicle can be directed to or , or to the chuck-users or chuck-dev mailing list.

Credits
miniAudicle Team

Spencer Salazar, Ge Wang

ChucK Team

Ge Wang, Perry Cook, Ananya Misra, Philip Davidson, Ari Lazier, Spencer Salazar, Mark Daly, Adam Tindale, Ajay Kapur

Libraries

miniAudicle incorporates portions of IDEKit (Copyright (c) Glenn Andreas), licensed under section 6 of the LGPL v2 (OS X only), wxWidgets, licensed under the wxWidgets license (Win32/Linux only); RtAudio; STK; and libsndfile (Copyright (c) Erik de Castro Lopo, http://www.mega-nerd.comlibsndfile/), licensed under section 6 of the LGPL v2.