ruck 0.1.0

data/.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+pkg

data/README

@@ -0,0 +1,85 @@
+A port of ChucK's strong timing to Ruby!
+
+Use Ruck's "shreds" to coordinate interleaved execution
+of threads (continuations) with precise virtual timing.
+Actual run-time is abstracted and shreds declare how much
+virtual time they took to execute. Scheduling of shreds
+is done by a ...
+
+  SHREDULER
+
+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 ex01.rb)
+
+  Check out the library of built-in unit generators in ugen/
+  and make your own.
+
+  Unit Generator Usage
+  ====================
+
+  Play a sine wave (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 (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 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:
+  
+    $ ruby midilib_runner.rb 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.
+
+USAGE
+=====
+
+ugen_runner.rb is an (example) program that lets you run scripts
+as you do with ChucK, with a shreduler that pulls samples from
+the unit generator graph (through the blackhole):
+
+  $ ruby ugen_runner.rb examples/ex01.rb
+
+It uses a UGenShreduler with a hard-coded sample rate. You can use it
+as an example for how to embed your own shreduler. It boils down
+to this:
+
+  require "ruck"
+  
+  @shreduler = Ruck::Shreduler.new # replace with your subclass
+  
+  # repeat this part as necessary to seed @shreduler with shreds
+  @shreduler.spork("main") do
+    ...
+  end
+  
+  # this returns when no shreds remain
+  @shreduler.run

data/Rakefile

@@ -0,0 +1,25 @@
+
+begin
+  require "jeweler"
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "ruck"
+    gemspec.email = "tom@alltom.com"
+    gemspec.homepage = "http://github.com/alltom/ruck"
+    gemspec.authors = ["Tom Lieber"]
+    gemspec.summary = "strong timing for Ruby: cooperative threads on a virtual clock"
+    gemspec.description = <<-EOF
+      Ruck uses continuations and a simple scheduler to ensure "shreds"
+      (threads in Ruck) are woken at precisely the right time according
+      to its virtual clock. Schedulers can map virtual time to samples
+      in a WAV file, real time, time in a MIDI file, or anything else
+      by overriding "sim_to" in the Shreduler class.
+      
+      A small library of useful unit generators and plenty of examples
+      are provided. See the README or the web page for details.
+    EOF
+    gemspec.has_rdoc = false
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jewler not available. Install it with: sudo gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/bin/ruck_glapp

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+# requires glapp gem
+# sudo gem install alltom-glapp
+# see http://alltom.com/pages/glapp for more details
+
+require "ruck"
+
+require "rubygems"
+require "glapp"
+
+class GLAppShreduler < Ruck::Shreduler
+  def initialize
+    @shreds_waiting_for_next_frame = []
+    super
+  end
+  
+  def actual_now
+    Time.now - @start_time
+  end
+  
+  def enqueue_for_next_frame(shred)
+    @shreds_waiting_for_next_frame << shred
+    @shreds.delete(shred)
+  end
+  
+  def next_frame_has_arrived
+    @shreds += @shreds_waiting_for_next_frame
+    
+    @shreds_waiting_for_next_frame.each do |shred|
+      shred.now = now
+    end
+    
+    @shreds_waiting_for_next_frame = []
+  end
+  
+  def catch_up
+    @start_time ||= Time.now
+    
+    while shreds.length > 0 && next_shred.now < actual_now
+      run_one
+    end
+  end
+end
+
+module ShredLocal
+  def wait_for_frame
+    SHREDULER.enqueue_for_next_frame(SHREDULER.current_shred)
+    SHREDULER.current_shred.yield(0)
+  end
+  
+  def wait(seconds)
+    SHREDULER.current_shred.yield(seconds)
+  end
+end
+
+class MySketch
+  def setup
+    ARGV.each do |filename|
+      SHREDULER.spork(filename) do
+        require filename
+      end
+    end
+  end
+  
+  def draw
+    SHREDULER.catch_up
+    SHREDULER.next_frame_has_arrived
+  end
+end
+
+include GLApp
+include ShredLocal
+SHREDULER = GLAppShreduler.new
+
+MySketch.new.show 800, 600, "My Sketch"

data/bin/ruck_midi

@@ -0,0 +1,143 @@
+#!/usr/bin/env ruby
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require "ruck"
+
+require "rubygems"
+require "midilib"
+require "midiator"
+
+# configuration
+if ARGV.length < 4
+  puts "ruby midilib_runner.rb MIDI_FILENAME NUM_TRACKS LIVE SCRIPT_FILENAME [...]"
+  exit 1
+end
+
+MIDI_FILENAME = ARGV[0]
+NUM_TRACKS = ARGV[1].to_i
+ALSO_LIVE = ["yes", "true", "1", "yeah"].include? ARGV[2].downcase
+FILENAMES = ARGV[3..-1]
+
+class MIDIShreduler < Ruck::Shreduler
+  def run
+    @start_time = Time.now
+    super
+  end
+  
+  def sim_to(new_now)
+    d = new_now - @now
+    TRACK_DELTAS.each_with_index do |delta, i|
+      TRACK_DELTAS[i] = delta + d
+    end
+    
+    # sync with wall clock
+    if ALSO_LIVE
+      actual_now = Time.now
+      simulated_now = @start_time + (new_now.to_f / SEQUENCE.ppqn / SEQUENCE.bpm * 60.0)
+      if simulated_now > actual_now
+        sleep(simulated_now - actual_now)
+      end
+    end
+    
+    @now = new_now
+  end
+end
+
+# state
+SHREDULER = MIDIShreduler.new
+SEQUENCE = MIDI::Sequence.new
+TRACKS = (1..NUM_TRACKS).map { MIDI::Track.new(SEQUENCE) }
+TRACK_DELTAS = TRACKS.map { 0 }
+if ALSO_LIVE
+  MIDI_PLAYER = MIDIator::Interface.new
+end
+
+# midi initialization stuff
+TRACKS.each do |track|
+  SEQUENCE.tracks << track
+  #track.events << MIDI::Tempo.new(MIDI::Tempo.bpm_to_mpq(120))
+end
+if ALSO_LIVE
+  MIDI_PLAYER.use :dls_synth
+  MIDI_PLAYER.instruct_user!
+end
+
+# set up some useful time helpers
+module MIDITime
+  def pulse
+    self
+  end
+  alias_method :pulses, :pulse
+  
+  def quarter_note
+    self * SEQUENCE.ppqn
+  end
+  alias_method :quarter_notes, :quarter_note
+  alias_method :beat, :quarter_note
+  alias_method :beats, :quarter_note
+end
+
+class Fixnum
+  include MIDITime
+end
+
+class Float
+  include MIDITime
+end
+
+# stuff accessible in a shred
+module ShredLocal
+
+  def now
+    SHREDULER.now
+  end
+
+  def spork(name = "unnamed", &shred)
+    SHREDULER.spork(name, &shred)
+  end
+
+  def wait(pulses)
+    SHREDULER.current_shred.yield(pulses)
+  end
+
+  def finish
+    shred = SHREDULER.current_shred
+    SHREDULER.remove_shred shred
+    shred.finish
+  end
+  
+  def note_on(note, velocity = 127, channel = 0, track = 0)
+    TRACKS[track].events << MIDI::NoteOnEvent.new(channel, note, velocity, TRACK_DELTAS[track].to_i)
+    TRACK_DELTAS[track] = 0
+    if ALSO_LIVE
+      MIDI_PLAYER.driver.note_on(note, channel, velocity)
+    end
+  end
+  
+  def note_off(note, channel = 0, track = 0)
+    TRACKS[track].events << MIDI::NoteOffEvent.new(channel, note, 0, TRACK_DELTAS[track].to_i)
+    TRACK_DELTAS[track] = 0
+    if ALSO_LIVE
+      MIDI_PLAYER.driver.note_on(note, channel, 0)
+    end
+  end
+
+end
+
+FILENAMES.each do |filename|
+  unless File.readable?(filename)
+    LOG.fatal "Cannot read file #{filename}"
+    exit
+  end
+end
+
+FILENAMES.each do |filename|
+  SHREDULER.spork(filename) do
+    include ShredLocal
+    require filename
+  end
+end
+
+SHREDULER.run
+
+File.open(MIDI_FILENAME, "wb") { |file| SEQUENCE.write(file) }

data/bin/ruck_ugen

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require "ruck"
+
+# stuff accessible in a shred
+module ShredLocal
+
+  def blackhole
+    BLACKHOLE
+  end
+  
+  def now
+    SHREDULER.now
+  end
+
+  def spork(name = "unnamed", &shred)
+    SHREDULER.spork(name, &shred)
+  end
+
+  def play(samples)
+    SHREDULER.current_shred.yield(samples)
+  end
+
+  def finish
+    shred = SHREDULER.current_shred
+    SHREDULER.remove_shred shred
+    shred.finish
+  end
+
+end
+
+
+SAMPLE_RATE = 22050
+SHREDULER = Ruck::UGenShreduler.new
+BLACKHOLE = Ruck::InChannel.new
+
+filenames = ARGV
+filenames.each do |filename|
+  unless File.readable?(filename)
+    LOG.fatal "Cannot read file #{filename}"
+    exit
+  end
+end
+
+filenames.each do |filename|
+  SHREDULER.spork(filename) do
+    include ShredLocal
+    include Ruck::Generators
+    require filename
+  end
+end
+SHREDULER.run

data/examples/glapp/ex01.rb

@@ -0,0 +1,13 @@
+
+clear
+
+loop do
+  wait 2
+  
+  glTranslate(0, 0, -5)
+  glutSolidCube(2)
+  
+  wait 0.1
+  
+  clear
+end

data/examples/midi/ex01.rb

@@ -0,0 +1,24 @@
+
+def maybe
+  rand >= 0.5
+end
+
+TRACKS[0].events << MIDI::Controller.new(10, 32, 1) # channel, controller, value
+TRACKS[0].events << MIDI::ProgramChange.new(10, 26) # channel, program
+MIDI_PLAYER.control_change 32, 10, 1 # number, channel, value
+MIDI_PLAYER.program_change 10, 26 # channel, program
+
+def play(note, dur = 1.quarter_note)
+  return if maybe
+  note_on note, 100, 10
+  wait dur
+  note_off note, 10
+end
+
+10.times do
+  spork { play(rand(30) + 40, rand * 3.quarter_notes + 3.quarter_notes) }
+  wait 0.5.quarter_note
+end
+
+wait 2.quarter_notes; note_off 0 # end padding
+

data/examples/ugen/ex01.rb

@@ -0,0 +1,24 @@
+def beep(wav, chan)
+  (s = SawOsc.new(:freq => 440, :gain => 0.25)) >> wav.in(chan)
+  10.times do
+    play 0.1.seconds
+    s.freq *= 1.2
+  end
+  s << wav
+end
+
+wav = WavOut.new(:filename => "ex01.wav", :num_channels => 2)
+SinOsc.new(:freq => 440, :gain => 0.25) >> wav
+SinOsc.new(:freq => 880, :gain => 0.25) >> wav
+
+wav >> blackhole
+
+chan = 0
+
+10.times do
+  play 0.7.seconds
+  chan = (chan + 1) % 2
+  spork("beep") { beep(wav, chan) }
+end
+
+play 2.seconds