Sunday, July 3, 2011

Diamond, MIDI Arpeggiator in Ruby

Diamond is a MIDI arpeggiator in Ruby.

It features all of the classic functions of a MIDI arpeggiator plus the ability to live code, algorithmically generate and modify patterns, chain and sync instances and more

This is a quick screencast video I did while live coding Diamond. (read more about this here...)
(Sounds starts around 55 seconds in)

Getting started

Ruby 1.9.2 or JRuby in 1.9 mode are required.

It installs with a typical gem installation...
gem install diamond
Here is a very basic example to get started:
require "diamond"
First, select a MIDI output using unimidi. (more...)
@output = UniMIDI::Output.gets
The Arpeggiator has a number of optional parameters (more...). For the sake of keeping this demo simple, here is a straightforward setup:
opts = { 
  :gate => 90, 
  :range => 4, 
  :interval => 7,
  :midi => @output,
  :pattern => Diamond::Pattern["UpDown"],    
  :rate => 8
(read more about what these options mean)

Now create an Arpeggiator object, passing in a tempo value and the options chosen before. In this case the tempo will be 138 BPM
arp =, opts)
Of course, an Arpeggiator needs notes to work with. As you might expect, it's easy to use a MIDI input for that (see example). However, again for the sake of simplicity here's a chord in Ruby
chord = ["C3", "G3", "Bb3", "A4"]
Use Arpeggiator#add and Arpeggiator#remove to change the notes that the arpeggiator sees. (Arpeggiator#<< is the same as add)
arp << "A4"
By default, the arpeggiator will run in a background thread so if you are working in IRB this will allow you to live code, sync it other arpeggiators, or just run another foreground process. (To start in the foreground, just pass :focus => true to Arpeggiator#start)
At that point, the arpeggiator starts playing. All of its options can be controlled on the on the fly.
arp.rate = 16
arp.gate = 20
arp.remove("C5", "A4")
Here are examples showing how to use some of Diamond's other features
Thanks for reading


  1. Hmm, I'm a total MIDI newb, but this did not work for me (Snow Leopard, Ruby 1.9.2)

    When I paste your example code into irb, nothing happens. If I use arp.start(:focus=>true), it hangs. I don't even get CtrlC or CtrlZ - the terminal is dead.

    I tried to dig down, and went with your unimidi example. That one does not hang; it pauses appropriately, but remains mute. Any tips?

  2. Hi

    Yep, it sounds like there's an issue with your MIDI setup. arp.start(:focus => true) is probably not hanging-- given the "stock" setup, it's only supposed to output MIDI and not anything to the screen

    What device are you attempting to output MIDI to? Or are you trying to output to another program? If the latter, I've done a post about how to do that with unimidi in OSX.

    There's another example in Diamond called print_to_screen.rb that you could run to at least confirm that the Ruby/Diamond configuration is set up correctly before figuring out your MIDI issue

  3. print_to_screen.rb is working. The device is, as you said, UniMIDI::Output.first (which prints as #, @id=1, @type=:output, @manufacturer="Apple Inc.", @model="IAC Driver", @name="Apple Inc. IAC Driver", @enabled=false>, @id=1, @name="Apple Inc. IAC Driver", @type=:output>)

  4. OK... so you could use that IAC Driver output-- but you would need to use MIDI Patch Bay and another program to generate sounds (eg GarageBand)

    This post should help guide you through that...

  5. Sorry, took a bit of time, with other things on my mind :) Anyway, I tried again, and got somewhere, just not sure where exactly. I managed to get sound out to GarageBand with output.puts. But the arpeggiator is only working while the code is running - as soon as irb prompt comes back, it pauses, and then whenever i press enter it flushes a note. If I do "sleep 10", it plays for those 10 secs, then pauses again, while irb waits for me. I'm a complete eventmachine noob, but it sounds to me something about backgrounding is failing... Any ideas?

  6. @Amadan

    Hey, well first off, thanks for trying this stuff out

    I'm pretty sure it's this problem:

    It's annoying because it only afflicts certain OSX environments and not others. Anyway, it's an easy fix but of course you lose some of the fun shortcuts in IRB.

  7. ARI!!!!! This is so awesome!

  8. What's happening here?

    1.9.2-p330 :036 > arp =, opts)ArgumentError: wrong number of arguments (2 for 1)
    from /home/gmaglio/.rvm/gems/ruby-1.9.2-p330/gems/diamond-0.5.9/lib/diamond/arpeggiator.rb:28:in `initialize'
    from (irb):36:in `new'
    from (irb):36
    from /home/gmaglio/.rvm/rubies/ruby-1.9.2-p330/bin/irb:12:in `'


  9. Nevermind! Late version of your gem has us using clock to set bpm. Documented under usage on diamond's github



    1. Yup- sorry for the confusion, will update these blogs posts