ChucK : Language Specification > Overview

version: 1.5.x.x (numchucks)


ChucK is a strongly-typed, strongly-timed, concurrent audio and multimedia programming language. It is compiled into virtual instructions, which is immediately run in the ChucK Virtual Machine. This guide documents the features of the Language, Compiler, and Virtual Machine for a ChucK programmer.

running ChucK

There are many to ChucK:

  • command-line application: chuck (use from a terminal program)
    (see VM options for a guide to command-line options)
  • miniAudicle, an integrate development environment
  • the latest chuck and miniAudicle can be downloaded from here.
  • you can also write and run ChucK code on a browser with the WebChucK IDE

To run ChucK with a program/patch called simply run chuck and then the name of the file:

 %> chuck 

To run ChucK with multiple patches concurrently (or the same one multiple times):

 %> chuck 

There are several flags you can specify to control how ChucK operates, or to find out about the system. For example,the following probes the audio system and prints out all available audio devices and MIDI devices. You may then refer to them (by number usually) from the command line or from your program. (again, see VM Options for a complete list)

 %> chuck --probe 

ChucK can be run in a different terminal as a host/listener that patches may be sent to. The server should invoke the --loop flag to specify that the virtual machine should not halt automatically (when the current programs exit).

 %> chuck --loop 

(See the guide to On-the-fly Programming for more information)

If a ChucK listener is running, we can (from a second terminal) send a program/patch to to the listener by using the + command line option:

 %> chuck + 

Similarly, you can use - and = to remove/replace a patch in the listener, and use ^ to find out the status. Again, see On-the-fly Programming for more information.

To run most of the code or examples in this language specification, you only need to use the basic chuck program.


Comments are sections of code that are ignored by a compiler. These help other programmers (and yourself) interpret your code. Double slashes indicate to the compiler to skip the rest of the line. /* and */ denotes block commenting - the compiler ignores the text in between. (Note: block comments cannot be nested)

    // this is a comment
    int foo; // another comment

       this is a block comment
       still going...

debug print

For the time being, stdout and chout have been temporarily disabled for the present release. In their place we have provided a debug print syntax:

    // prints out value of expression
    <<< expression >>>;

This will print the values and types of any expressions placed within them. This debug print construction may be placed around any non-declaration expression ( non l-value ) and will not affect the execution of the code. Expressions which represent an object will print the value of that object's reference address:

    // assign 5 to a newly declared variable
    5 => int i;
    // prints "5 : (int)"

    // prints "hello! : (string)"
    <<<"hello!">>>; //prints "hello! : (string)"

    // prints "3.5 : (float)"
    <<<1.0 + 2.5 >>>=> float x;

For more formatted data output, a comma-separated list of expressions will print only their respective values (with one space between):

    // prints "the value of x is 3.5" (x from above)
    <<<"the value of x is" , x >>>;

    // prints "4 + 5 is 9"
    <<<"4 + 5 is", 4 + 5>>>;

    // prints "here are 3 random numbers ? ? ?"
    <<<"here are 3 random numbers", 
        Std.rand2(0,9) >>>; 

reserved words

  • (primitive types)
    • int
    • float
    • time
    • dur
    • void
    • same (unimplemented)

  • (control structures)
    • if
    • else
    • while
    • until
    • for
    • repeat
    • break
    • continue
    • return
    • switch (unimplemented)

  • (class keywords)
    • class
    • extends
    • public
    • static
    • pure
    • this
    • super (unimplemented)
    • interface (unimplemented)
    • implements (unimplemented)
    • protected (unimplemented)
    • private (unimplemented)

  • (other chuck keywords)
    • function
    • fun
    • spork
    • new
    • const
    • global

  • (special values)
    • now
    • true
    • false
    • maybe
    • null
    • NULL
    • me
    • pi

  • (special : default durations)
    • samp
    • ms
    • second
    • minute
    • hour
    • day
    • week

  • (special : global ugens)
    • dac
    • adc
    • blackhole