alltom / ruck

A port of ChucK's strong timing to Ruby!

ruck lets you easily create a virtual clock against
which precise timing of execution can be guaranteed. The
virtual clock can be kept roughly in sync with real time
if you want it to, but you don't have to. For example, in
ChucK, even if your scripts take too long to generate
samples in real time, the audio stream isn't compromised
because it's timed against the virtual clock.

ruck provides an easily extended scheduler for non-preemptive
shreds (threads) implemented using continuations.
Cooperatively scheduled threads usually don't require
synchronization since execution is never interrupted.

A few example shredulers (schedulers) are provided:

UGenShreduler:

  This shreduler calculates an audio unit generator graph's
  output in virtual time. The graph can be modified by
  shreds all the while.

  The graph is written in Ruby for flexibility, so it's
  too slow (on my computer) for real time, so there is no
  real-time playback. You can use WavOut, though.
  (See examples/ugen/ex01.rb)

  Check out the library of built-in unit generators in ugen/
  and make your own.

  Unit Generator Usage
  ====================

  Play a sine wave (examples/ugen/ex02.rb):

    s = SinOsc.new(:freq => 440)
    w = WavOut.new(:filename => "ex02.wav")
    s >> w >> blackhole
    play 3.seconds

  Attach lambdas to unit generator attributes
  (examples/ugen/ex03.rb):

    wav = WavOut.new(:filename => "ex03.wav")
    sin2 = SinOsc.new(:freq => 3)
    sin = SinOsc.new(:freq => L{ sin2.last * 220 + 660 },
                     :gain => L{ 0.5 + sin2.last * 0.5 })
    [sin >> wav, sin2] >> blackhole
    play 3.seconds

RealTimeShreduler

  This shreduler attempts to keep virtual time in line with
  real time.
  (See examples/ugen/ex10.rb)

MIDIShreduler

  This shreduler uses MIDIator and midilib to support live
  MIDI playback and saving MIDI to disk. An example runner
  is provided in midi_runner.rb which you invoke like this:
  
    $ ruck_midi MIDI_FILENAME NUM_TRACKS LIVE SCRIPT_FILENAME [...]
  
  where LIVE is "no" to only save the MIDI output, or "yes"
  to also play in real-time.

GLAppShreduler

  You don't want to know. (But the scripts are included so
  you can find them if you're really curious.)

USAGE
=====

This project has tons of examples because even though the library
is tiny, there's a lot to test, and a lot of ways to use it.

For examples of how to implement your own Shreduler, see the bottom
of lib/ruck/shreduling.rb and all the scripts in bin/.

For example of how to use the provided Shredulers, check the
examples/ directory. Those scripts contain no boilerplate includes
because they are written to be invoked on the command line by
one of the bin/ scripts. For example:

  $ ruck_ugen examples/ugen/ex01.rb