ChucK : Programming Guide

Standard Libraries

version: 1.4.x.x (numchucks)

ChucK Standard Libraries API

these libraries are provide by default with ChucK - new ones can also be imported with ChucK dynamic linking (soon to be documented...). The existing libraries are organized by namespaces in ChucK. They are as follows.

namespace: Std

Std is a standard library in ChucK, which includes utility functions including absolute values, unit conversions, pitch-frequency conversions. (NOTE: the random number generator functions—which used to be in Std—are now in the Math library below.)

[example]
// infinite time-loop while( true ) { // generate random MIDI note number Math.random2(60,84) => int pitch; // convert pitch to frequency pitch => Std.mtof => float frequency; // print both <<< pitch, frequency >>>; // wait a bit 100::ms => now; }

[function]: int abs ( int value );

  • returns absolute value of integer

[function]: float fabs ( float value );

  • returns absolute value of floating point number

[function]: float sgn ( float value );

  • computes the sign of the input as -1.0 (negative), 0 (zero), or 1.0 (positive)

[function]: int system ( string cmd );

  • pass a command to be executed in the shell

[function]: int atoi ( string value );

  • converts ascii (string) to integer (int)

[function]: float atof ( string value );

  • converts ascii (string) to floating point value (float)

[function]: string getenv ( string key );

  • returns the value of an environment variable, such as of "PATH"

[function]: int setenv ( string key, string value );

  • sets environment variable named 'key' to 'value'

[function]: float mtof ( float value );

  • converts a MIDI note number to frequency (Hz)
  • note the input value is of type 'float' (supports fractional note number)

[function]: float ftom ( float value );

  • converts frequency (Hz) to MIDI note number space

[function]: float powtodb ( float value );

  • converts signal power ratio to decibels (dB)

[function]: float rmstodb ( float value );

  • converts linear amplitude to decibels (dB)

[function]: float dbtopow ( float value );

  • converts decibels (dB) to signal power ratio

[function]: float dbtorms ( float value );

  • converts decibles (dB) to linear amplitude

namespace: Machine

Machine is ChucK runtime interface to the virtual machine. this interface can be used to manage shreds. They are similar to the On-the-fly Programming Commands, except these are invoked from within a ChucK program, and are subject to the timing mechanism.

----------

[function]: int add ( string path );

  • compile and spork a new shred from file at 'path' into the VM now
  • returns the shred ID
  • (see example/machine.ck)

[function]: int spork ( string path );

  • same as add

[function]: int remove ( int id );

  • remove shred from VM by shred ID (returned by add/spork)

[function]: int replace ( int id, string path );

  • replace shred with new shred from file
  • returns shred ID , or 0 on error

[function]: int status ( );

  • display current status of VM
  • (see example/status.ck)

[function]: void crash ( );

  • literally causes the VM to crash. the very last resort; use with care. Thanks.


namespace: Math

Math contains the standard math functions, including all trignometric functions expects angles to be in radians, as well as random number generators.

[example]
// print sine of pi/2 <<<< Math.sin( Math.PI / 2.0 ) >>>;
[example 2]
// infinite time-loop while( true ) { // generate random float (and print) <<< Math.random2f( 100.0, 1000.0 ) >>>; // wait a bit 50::ms => now; }

[function]: float sin ( float x );

  • computes the sine of x

[function]: float cos ( float x );

  • computes the cosine of x

[function]: float tan ( float x );

  • computes the tangent of x

[function]: float asin ( float x );

  • computes the arc sine of x

[function]: float acos ( float x );

  • computes the arc cosine of x

[function]: float atan ( float x );

  • computes the arc tangent of x

[function]: float atan2 ( float y, float x );

  • computes the principal value of the arc tangent of y/x, using the signs of both arguments to determine the quadrant of the return value

[function]: float sinh ( float x );

  • computes the hyperbolic sine of x

[function]: float cosh ( float x );

  • computes the hyperbolic cosine of x

[function]: float tanh ( float x );

  • computes the hyperbolic tangent of x

[function]: float hypot ( float x, float y );

  • computes the euclidean distance of the orthogonal vectors (x,0) and (0,y)

[function]: float pow ( float x, float y );

  • computes x taken to the y-th power

[function]: float sqrt ( float x );

  • computes the nonnegative square root of x (x must be >= 0)

[function]: float exp ( float x );

  • computes e^x, the base-e exponential of x

[function]: float log ( float x );

  • computes the natural logarithm of x

[function]: float log2 ( float x );

  • computes the logarithm of x to base 2

[function]: float log10 ( float x );

  • computes the logarithm of x to base 10

[function]: int random ( );

  • generates random integer between 0 and Math.RANDOM_MAX
  • (NOTE: Math.random*() functions use a different, superior random number generator than the Std.rand*() functions)

[function]: int random2 ( int min, int max );

  • generates random integer in the range [min, max]

[function]: float randomf ( );

  • generates random floating point number in the range [0, 1]
    (NOTE: this is different semantics than Std.randf(), which has the range [-1,1])

[function]: float random2f ( float min, float max );

  • generates random floating point number in the range [min, max]

[function]: void srandom ( int seed );

  • seeds the random number generator

[function]: float floor ( float x );

  • round to largest integral value (returned as float) not greater than x

[function]: float ceil ( float x );

  • round to smallest integral value (returned as float) not less than x

[function]: float round ( float x );

  • round to nearest integral value (returned as float)

[function]: float trunc ( float x );

  • round to largest integral value (returned as float) no greater in magnitude than x

[function]: float fmod ( float x, float y );

  • computes the floating point remainder of x / y

[function]: float remainder ( float x, float y );

  • computes the value r such that r = x - n * y, where n is the integer nearest the exact value of x / y. If there are two integers closest to x / y, n shall be the even one. If r is zero, it is given the same sign as x

[function]: float min ( float x, float y );

  • choose lesser of two values

[function]: float max ( float x, float y );

  • choose greater of two values

[function]: int nextpow2 ( int x );

  • computes the integeral (returned as int) smallest power of 2 greater than the value of x

[function]: float isinf ( float x );

  • tests if x is infinity

[function]: float isnan ( float x );

  • tests if x "is not a number"

[constant]: float PI;

  • constant PI; use as: Math.PI

[constant]: float TWO_PI;

  • constant PI*2; example usage: Math.TWO_PI

[constant]: float e; // same as: E

  • Euler's constant, base of natural logarithm; same as Math.exp(1); use as: Math.e or Math.E

[constant]: complex i; // same as: j, I, or J

  • the imaginary number 'i' as a complex value; use as: Math.i or Math.j or Math.I or Math.J

[constant]: int RANDOM_MAX;

  • max value returned by Math.random()
  • (NOTE: not to be confused with Std.rand*)
Next: Chuck Standard Unit Generators

Return to Programming Guide

chuck | soundlab | cs | music | ccrma