TAPESTREA : ChucK Scripting Synthesis

version: 0.1.x.x (tap tap)

home: http://taps.cs.princeton.edu

  
Figure 1 : ChucK operator + taps library

ChucK?!

ChucK is a strongly timed, concurrent, on-the-fly audio programming language developed by Ge Wang, Perry Cook, and others. In taps, for now it is used mainly as a scripting tool, offering finer control over synthesis parameters and how they change over time.

To begin your scripting trajectory, check out the ChucK documentation if you haven't yet. Then come back here (if you can tear yourself away from it)!


Synthesis API

The synthesis API in taps has the following objects:


TapsSynth

A set of functions to access the synthesis face and template library.

  • int load( string name )
    • what: Load a .tap file into the library by name/path.
    • returns: 1 if successful, 0 if failed
    • example: 
      if( !TapsSynth.load( "examples/chirp" ) )
    <<< "failed" >>>;

  • int count( string name )
    • what: Count the number of templates that have the given string as part of their name.
    • returns: Number of such templates currently in the library
    • example: 
      TapsSynth.count( "chirp" ) => int nchirps;

  • int copy( string name, int index, int copies )
    • what: Make copies of a template, identified by name and index, and add these to library.
    • returns: 1 if successful, 0 if failed
    • example: 
      // Make 4 copies of the 1st library template that has the word 
// "chirp" in its name
TapsSynth.copy( "chirp", 0, 4 );

TapsTemp

An object representing a taps template.

  • int readFromFile( string path, int show )
    • what: Reads in a template from a given .tap file, and shows it in the library if "show" is not specified or is non-zero.
    • returns: 1 if successful, 0 if failed
    • example: 
      TapsTemp t1;
t1.readFromFile( "examples/chirp" );

  • int readFromLibrary( string name, int index )
    • what: Read a template from the current library into the script, by name. If "index" is not specified, read the first library template with the same name, otherwise read the template corresponding to the given index.
    • returns: 1 if successful, 0 if failed
    • example: 
      // Read in the 2nd library template whose name is exactly "chirp"
TapsTemp t2;
t2.readFromLibrary( "chirp", 1 );

  • int read( string path )
    • what: Reads a template from a .tap file into the script but not into the library.
    • returns: 1 if successful, 0 if failed
    • example: 
      Template t3;
t3.read( "examples/chirp.tap" );

  • void play( int which )
    • what: Play the template on the specified audio bus. If "which" is not specified, play on the template's default bus, and if that is also not specified, on the default script bus, 7.
    • example: 
      t1.play( 4 );
t2.play();

  • void stop( )
    • what: Stop the template.
    • example: 
      t1.stop();

  • void rewind( )
    • what: Rewind the template to its beginning.
    • example: 
      t1.rewind();

  • int playing( )
    • what: Check whether the template is currently playing.
    • returns: 1 if playing, 0 otherwise
    • example: 
      // wait for t2 to stop
while( t2.playing() )
    0.1::second => now;

  • int close( )
    • what: Delete the template. (Dangerous.)
    • returns: 1
    • example: 
      t3.close();

  • int release( )
    • what: Release a template to signify it's no longer needed. To replace close() and to be implemented.


  • int bus( int which )
    • what: Set the template's default bus, or if "which" is not specified, return its current default bus.
    • returns: latest default bus
    • example: 
      // set t2's bus to 3 and t1's bus to 5
t2.bus( 3 );
5 => t1.bus;
// print both buses
<<< t2.bus(), t1.bus() >>>;

  • float gain( float value )
    • what: Set the template's gain, or if "value" is not specified, return its current gain.
    • returns: latest gain
    • example: 
      // get t1's gain and set t2's gain to the same amount
t1.gain() => t2.gain;
// another way to do it
t2.gain( t1.gain() );

  • float pan( float value )
    • what: Set the template's pan, or if "value" is not specified, return its current pan.
    • returns: latest pan
    • example: 
      // Set t2 to play equally on both speakers
t2.pan(0.5);
// Set t1 to play only on left speaker
0 => t1.pan;

  • float freqWarp( float value )
    • what: Set the template's frequency warp factor, or if "value" is not specified, return its current frequency warp.
    • returns: latest frequency warp
    • example: 
      2 => t1.freqWarp;

  • float timeStretch( float value )
    • what: Set the template's time stretch factor, or if "value" is not specified, return its current time stretch.
    • returns: latest time stretch
    • example: 
      t1.timeStretch( 2 );

  • float periodicity( float value )
    • what: Set the template's periodicity, or if "value" is not specified, return its current periodicity. Only relevant for loops and mixed bags.
    • returns: latest periodicity
    • example: 
      t1.periodicity( 0.5 );

  • float density( float value )
    • what: Set the template's density, or if "value" is not specified, return its current density. Only relevant for loops and mixed bags.
    • returns: latest density
    • example: 
      5.0 => t1.density;

  • float random( float value )
    • what: Set the template's randomness, or if "value" is not specified, return its current randomness. Only relevant for loops.
    • returns: latest randomness
    • example: 
      // set t1's randomness value and print it
2 => t1.random;
<<< t1.random() >>>;

  • int ready( )
    • what: Check that template is ready to use.
    • returns: 1 if ready, 0 if not
    • example: 
      if( !t1.ready() )
    <<< "Something's wrong" >>>;

TapsBus

Ways to modify taps audio buses.

  • float reverb( int which, float value )
    • what: Set given bus's reverb to given value, or if "value" is not specified, return the bus's current reverb.
    • returns: latest reverb for given bus
    • example: 
      // set bus 0's reverb to 0.3
TapsBus.reverb( 0, 0.3 );
// get bus 2's reverb and store it in variable r
TapsBus.reverb( 2 ) => float r;

  • float volume( int which, float value )
    • what: Set given bus's gain to given value, or if "value" is not specified, return current gain.
    • returns: latest gain for given bus
    • example: 
      // set bus 1's volume to bus 3's volume
TapsBus.volume( 3 ) => float v;
TapsBus.volume( 1, v );

  • float pan( int which, float value )
    • what: Set given bus's pan to given value, or if "value" is not specified, return its current pan.
    • returns: latest pan for given bus
    • example: 
      // Set bus 3's pan to bus 1's pan
TapsBus.pan( 1 ) => float p;
TapsBus.pan( 3, p );

TapsUI

Highly experimental API to add user interface elements like sliders, buttons, and flippers, in the synthesis face. This has a hierarchical structure, with different types of TapsUI objects. Some functions are associated with all TapsUI objects, and others are reserved for specific types of UI elements.

All TapsUI objects have these functions:

  • void position( float x, float y, float z )
    • what: Set the display position of the UI element, where the x,y,z coordinates range from -1 to 1 and (0, 0, 0) is the x-y center of the display area

  • float value( float val )
    • what: Set the value of the UI element, or if val is not specified, return its current value
    • returns: latest value

  • string label( string name )
    • what: Set the displayed label of the UI element, or if name is not specified, return its current label
    • returns: latest name/label

TapsUI objects of the following types can be instantiated:

TapsUIButton : A standard button object that can be clicked.

TapsUIFlipper : A flipper or on/off switch.

TapsUISlider : A slider or fader. In addition to the functions above, TapsUISlider objects can be further customized using the following interface:

  • int init( int isHor, int isExp, intisInt, int length, float min, float max )
    • what: Initialize the slider to the given parameters:
      • isHor : if 1, the slider is horizontal; if 0, it's vertical
      • isExp : if 1, the values change exponentially as the slider is moved; if 0, they change linearly
      • isInt : if 1, the slider has integer values; if 0, it has floating point values
      • length : specify one of 3 standard slider lengths, with 0 being the longest, 1 somewhat shorter, and 2 the smallest
      • min : the minimum/lowest acceptable slider value
      • max : the maximum/highest acceptable slider value
    • returns: 1 if successful, 0 if failed

  • int orientation( int hor )
    • what: Set the orientation of the slider, or if hor is not specified, return the current orientation. (Horizontal if hor is 1, vertical if hor is 0.)
    • returns: latest orientation

  • int length( int len )
    • what: Set the slider length, or if len is not specified, return current length. (Smallest if len is 2, medium if len is 1, longest if len is 0.)
    • returns: latest length

Examples : TapsUI is easiest to describe by example, so here are a few scripts that use various TapsUI elements to control synthesis. Both also use the lutinebell template.

taps | soundlab | cs | music