micromidi 0.0.7

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2011 Ari Russo
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.rdoc

@@ -0,0 +1,103 @@
+= micromidi
+
+A Ruby DSL for MIDI
+
+{pic}[http://images.treetrouble.net/images/midi.png]
+
+== Features
+ 
+* Cross-platform compatible using MRI or JRuby.
+* Simplified MIDI and Sysex message output
+* MIDI Thru, processing and custom input events
+* Optional shorthand for {live coding}[http://en.wikipedia.org/wiki/Live_coding]
+
+== Installation
+
+  gem install micromidi
+  
+== Requirements
+
+Ruby 1.9.2+ or JRuby in 1.9 mode
+
+Requires {midi-eye}[http://github.com/arirusso/midi-eye], {midi-message}[http://github.com/arirusso/midi-message] and {unimidi}[http://github.com/arirusso/unimidi].  These should install automatically with the gem.
+
+== Usage
+
+The following are basic examples that use {unimidi}[http://github.com/arirusso/unimidi] inputs and outputs.  ({see an example here that explains selecting an output...}[http://github.com/arirusso/unimidi/blob/master/examples/select_a_device.rb])
+
+  require "midi"
+  
+  @i = UniMIDI::Input.use(:first)
+  @o = UniMIDI::Output.use(:first)
+
+This example plays some arpeggios
+
+  MIDI.using($o) do
+    
+    5.times do |oct|
+      octave oct
+      %w{C E G B}.each { |n| play n 0.5 }
+    end
+
+  end
+    
+While running, this next example sends all input directly to the output except for notes; notes that are received are only sent to the output if their octave is between 1 and 3.  Output is also printed to the console by passing in <em>$stdout</em>.
+
+  MIDI.using(@i, @o, $stdout) do
+
+    thru_except :note { |msg| only(msg, :octave, (1..3)) }
+
+    join
+
+  end
+
+This is the same example redone using shorthand aliases
+
+  M(@i, @o) do
+
+    te :n { |m| only(m, :oct, (1..3)) }
+
+    j
+
+  end
+  
+Finally, here is an example that maps some MIDI Control Change messages to SysEx
+  
+  MIDI.using(@i, @o) do
+  
+    *@the_map =
+      [0x40, 0x7F, 0x00],
+      [0x41, 0x7F, 0x00],
+      [0x42, 0x7F, 0x00]
+  
+    node :roland, :model_id => 0x42, :device_id => 0x10
+  
+    receive :cc do |message|
+    
+      command @the_map[message.index - 1], message.value
+      
+    end
+  
+  end 
+
+I've written up a few posts explaining each of the concepts used here in greater detail:
+
+* {Output}[http://tx81z.blogspot.com/2011/08/micromidi-midi-messages-and-output.html]
+* {MIDI Thru and Processing}[http://tx81z.blogspot.com/2011/08/micromidi-midi-thru-and-midi-processing.html]
+* {Binding Custom Input Events}[http://tx81z.blogspot.com/2011/08/micromidi-custom-events.html]
+* {Shorthand}[http://tx81z.blogspot.com/2011/08/micromidi-shorthand.html]
+* {Sysex}[http://tx81z.blogspot.com/2011/09/generating-sysex-messages-with.html]
+ 
+== Documentation
+
+* {rdoc}[http://rubydoc.info/github/arirusso/micromidi] 
+
+== Author
+
+* {Ari Russo}[http://github.com/arirusso] <ari.russo at gmail.com>
+
+== License
+
+Apache 2.0, See the file LICENSE
+
+Copyright (c) 2011 Ari Russo

data/TODO

@@ -0,0 +1,8 @@
+Functionality
+* thru issues / strong thru
+* Sysex messages 
+* MIDI files?
+
+Documentation
+* Guide for shorthand aliases
+* More rdoc

data/lib/micromidi/context.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+#
+
+module MicroMIDI
+  
+  class Context
+    
+    include Instructions::Composite
+    
+    attr_reader :state
+            
+    def initialize(ins, outs, &block)
+      
+      @state = State.new(ins, outs)
+      
+      @instructions = {
+        :process => Instructions::Process.new(@state),
+        :input => Instructions::Input.new(@state),      
+        :message => Instructions::Message.new(@state),
+        :output => Instructions::Output.new(@state),
+        :sticky => Instructions::Sticky.new(@state),
+        :sysex => Instructions::SysEx.new(@state)
+      }
+       
+      instance_eval(&block) unless block.nil?
+    end
+    
+    def repeat
+      self.send(@state.last_command[:method], *@state.last_command[:args]) unless @state.last_command.nil?
+    end
+    
+    def method_missing(m, *a, &b)
+      delegated = false
+      outp = nil
+      options = a.last.kind_of?(Hash) ? a.last : {}
+      do_output = options[:output] || true
+      [@instructions[:sysex], @instructions[:message], @instructions[:process]].each do |dsl|
+        if dsl.respond_to?(m)
+          msg = dsl.send(m, *a, &b)
+          outp = @state.auto_output && do_output ? @instructions[:output].output(msg) : msg
+          delegated = true
+        end
+      end
+      unless delegated
+        [@instructions[:input], @instructions[:output], @instructions[:sticky]].each do |dsl| 
+          if dsl.respond_to?(m)
+            outp = dsl.send(m, *a, &b)
+            delegated = true
+          end
+        end
+      end
+      @state.record(m, a, b, outp)
+      delegated ? outp : super
+    end
+        
+  end
+end

data/lib/micromidi/instructions/composite.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+#
+module MicroMIDI
+
+  module Instructions
+    
+    module Composite
+      
+      # play note n, wait <em>duration</em> seconds, then do note off for note n
+      def play(n, duration)
+        msg = case n
+          when Numeric, String then note(n)
+          when MIDIMessage then n 
+        end
+        sleep(duration)
+        off
+        msg
+      end
+      
+      # sends a note off message for every note on every channel
+      def all_off
+        (0..15).each do |channel|
+          (0..127).each do |note_num|
+            note_off(note_num, :channel => channel)
+          end
+        end
+        true
+      end
+      alias_method :quiet!, :all_off
+      
+    end
+
+  end
+
+end

data/lib/micromidi/instructions/input.rb

@@ -0,0 +1,114 @@
+#!/usr/bin/env ruby
+#
+module MicroMIDI
+
+  module Instructions
+    
+    class Input
+
+      include MIDIMessage
+      
+      def initialize(state)
+        @state = state
+      end
+
+      # bind an event that will be called every time a message is received
+      def receive(*a, &block)
+        options = a.last.kind_of?(Hash) ? a.pop : {}
+        match = a.empty? ? nil : { :class => msg_classes(a) }
+        listener(match, options) { |event| yield(event[:message], event[:timestamp]) }
+      end
+      alias_method :gets, :receive
+      alias_method :handle, :receive
+      alias_method :listen, :receive
+      alias_method :listen_for, :receive
+      alias_method :when_receive, :receive
+
+      def receive_unless(*a, &block)
+        options = a.last.kind_of?(Hash) ? a.pop : {}
+        match = { :class => msg_classes(a) }
+        listener(nil, options) { |event| yield(event[:message], event[:timestamp]) unless match.include?(event[:message].class) }
+      end
+      alias_method :handle_unless, :receive_unless
+      alias_method :listen_unless, :receive_unless
+      alias_method :listen_for_unless, :receive_unless
+      alias_method :unless_receive, :receive_unless
+
+      # send input messages thru to the outputs
+      def thru
+        thru_if
+      end
+
+      # send input messages thru to the outputs if it has a specific class
+      def thru_if(*a)
+        a.last.kind_of?(Hash) ? a.last[:thru] = true : a.push({ :thru => true })
+        receive(*a) { |message, timestamp| output(message) }
+      end
+
+      # send input messages thru to the outputs unless of a specific class
+      def thru_unless(*a)
+        a.last.kind_of?(Hash) ? a.last[:thru] = true : a.push({ :thru => true })
+        receive_unless(*a) { |message, timestamp| output(message) }
+      end
+      
+      # like <em>thru_unless</em> except a block can be passed that will be called when
+      # notes specified as the <em>unless</em> arrive
+      def thru_except(*a, &block)
+        thru_unless(*a)
+        receive(*a, &block)        
+      end
+            
+      # wait for input on the last input passed in
+      # can pass the option :from => [an input] to specify which one to wait on
+      def wait_for_input(options = {})
+        listener = options[:from] || @state.listeners.last || @state.thru_listeners.last
+        listener.join
+      end
+      
+      def join
+        loop { wait_for_input }
+      end
+
+      protected
+
+      def listener(match = {}, options = {}, &block)
+        inputs = options[:from] || @state.inputs
+        thru = options[:thru] || false
+        match ||= {}
+        inputs.each do |input|
+          listener = MIDIEye::Listener.new(input)
+          listener.listen_for(match, &block)
+          if thru
+            @state.thru_listeners.each { |l| l.stop }
+            @state.thru_listeners.clear
+            @state.thru_listeners << listener
+          else 
+            @state.listeners << listener
+          end 
+          listener.start(:background => true) unless !options[:start].nil? && !options[:start]
+        end
+      end
+
+      private
+
+      def msg_classes(list)
+        list.map do |type|
+          case type
+          when :aftertouch, :pressure, :aft then [ChannelAftertouch, PolyphonicAftertouch]
+          when :channel_aftertouch, :channel_pressure, :ca, :cp then ChannelAftertouch
+          when :control_change, :cc, :c then ControlChange
+          when :note, :n then [NoteOn, NoteOff]
+          when :note_on, :nn then NoteOn
+          when :note_off, :no, :off then NoteOff
+          when :pitch_bend, :pb then PitchBend
+          when :polyphonic_aftertouch, :poly_aftertouch, :poly_pressure, :polyphonic_pressure, :pa, :pp then PolyphonicAftertouch
+          when :program_change, :pc, :p then ProgramChange
+          end
+        end.flatten.compact
+      end
+
+    end
+
+  end
+
+end

data/lib/micromidi/instructions/message.rb

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+#
+module MicroMIDI
+
+  module Instructions
+    
+    class Message
+
+      include MIDIMessage
+      
+      def initialize(state)
+        @state = state
+      end
+      
+      # create a control change message
+      def control_change(id, value, opts = {})
+        props = @state.message_properties(opts, :channel)
+        id.kind_of?(Numeric) ? ControlChange.new(props[:channel], id, value) : ControlChange[id].new(props[:channel], value)
+      end
+
+      # create a note message
+      def note(id, opts = {})
+        props = @state.message_properties(opts, :channel, :velocity)
+        note = if id.kind_of?(Numeric) 
+          NoteOn.new(props[:channel], id, props[:velocity])
+        elsif id.kind_of?(String) || id.kind_of?(Symbol)
+          note_string = parse_note_name(id)
+          NoteOn[note_string].new(props[:channel], props[:velocity])
+        end
+        @state.last_note = note
+        note
+      end
+
+      # create a note off message
+      def note_off(id, opts = {})
+        props = @state.message_properties(opts, :channel, :velocity)
+        if id.kind_of?(Numeric) 
+          NoteOff.new(props[:channel], id, props[:velocity])
+        elsif id.kind_of?(String) || id.kind_of?(Symbol)
+          note_string = parse_note_name(id)
+          NoteOff[parse_note_name(id)].new(props[:channel], props[:velocity])
+        end
+      end
+
+      # create a MIDI message from a byte string, array of bytes, or list of bytes
+      def parse(message)
+        MIDIMessage.parse(message)
+      end
+
+      # create a program change message
+      def program_change(program, opts = {})
+        props = @state.message_properties(opts, :channel)
+        MIDIMessage::ProgramChange.new(props[:channel], program)
+      end
+
+      # create a note-off message from the last note-on message
+      def off
+        o = @state.last_note.to_note_off unless @state.last_note.nil?
+        @state.last_note = nil
+        o
+      end
+      
+      # create a channel pressure message
+      def channel_aftertouch(value, opts = {})
+        props = @state.message_properties(opts, :channel)
+        MIDIMessage::ChannelAftertouch.new(props[:channel], value)
+      end
+      alias_method :channel_pressure, :channel_aftertouch
+      
+      # create a poly pressure message
+      def polyphonic_aftertouch(note, value, opts = {})
+        props = @state.message_properties(opts, :channel)
+        MIDIMessage::PolyphonicAftertouch.new(props[:channel], note, value)
+      end
+      alias_method :poly_aftertouch, :polyphonic_aftertouch
+      alias_method :polyphonic_pressure, :polyphonic_aftertouch
+      alias_method :poly_pressure, :polyphonic_aftertouch
+      
+      def pitch_bend(low, high, opts = {})
+        props = @state.message_properties(opts, :channel)
+        MIDIMessage::PitchBend.new(props[:channel], low, high)
+      end
+      alias_method :bend, :pitch_bend
+      alias_method :pitchbend, :pitch_bend
+      
+      protected
+      
+      def parse_note_name(name)
+        name = name.to_s #ensure that name is a string
+        string_opts = { :octave => name.scan(/-?\d\z/).first }
+        note = name.split(/-?\d\z/).first
+        string_props = @state.message_properties(string_opts, :octave)
+        "#{note}#{string_props[:octave].to_s}"
+      end
+
+    end
+
+  end
+
+end

data/lib/micromidi/instructions/output.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+#
+module MicroMIDI
+
+  module Instructions
+    
+    class Output
+      
+      def initialize(state)
+        @state = state
+      end
+
+      def output(msg)
+        auto_output(msg) if msg === false || msg === true
+        @state.outputs.each { |o| o.puts(msg) } unless msg.nil?
+        msg
+      end
+      
+      # toggle mode where messages are automatically outputted
+      def auto_output(mode = nil)
+        mode.nil? ? @state.toggle_auto_output : @state.auto_output = mode
+      end
+
+    end
+
+  end
+
+end

data/lib/micromidi/instructions/process.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+#
+module MicroMIDI
+
+  module Instructions
+    
+    class Process
+
+      include MIDIMessage
+      include MIDIMessage::Process
+      
+      def initialize(state)
+        @state = state
+      end
+      
+      def transpose(message, property, factor, options = {})
+        Transpose.process(message, property, factor, options)
+      end
+      
+      def limit(message, property, range, options = {})
+        Limit.process(message, property, range, options)
+      end
+      
+      def filter(message, property, bandwidth, options = {})
+        Filter.process(message, property, bandwidth, options)
+      end
+      
+      def high_pass_filter(message, property, min, options = {})
+        HighPassFilter.process(message, property, min, options)
+      end
+      alias_method :only_above, :high_pass_filter
+      alias_method :except_below, :high_pass_filter
+
+      def low_pass_filter(message, property, max, options = {})
+        LowPassFilter.process(message, property, max, options)
+      end
+      alias_method :only_below, :low_pass_filter
+      alias_method :except_above, :low_pass_filter
+      
+      def band_pass_filter(message, property, bandwidth, options = {})
+        BandPassFilter.process(message, property, bandwidth, options)
+      end
+      alias_method :only_in, :band_pass_filter
+      alias_method :only, :band_pass_filter
+      
+      def notch_filter(message, property, bandwidth, options = {})
+        NotchFilter.process(message, property, bandwidth, options)
+      end
+      alias_method :band_reject_filter, :notch_filter
+      alias_method :except_in, :notch_filter
+      alias_method :except, :notch_filter
+      
+    end
+
+  end
+
+end

data/lib/micromidi/instructions/shorthand.rb

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+#
+
+module MicroMIDI
+  
+  alias l loop
+ 
+  class << self
+    alias_method :m, :message
+  end
+  
+  class Context
+    alias_method :r, :repeat
+  end
+  
+  module Instructions    
+        
+    module Composite
+      alias_method :p, :play
+      alias_method :q!, :all_off
+      alias_method :x, :all_off
+    end
+        
+    class Input
+      alias_method :j, :join
+      alias_method :rc, :receive
+      alias_method :rcu, :receive_unless
+      alias_method :t, :thru
+      alias_method :te, :thru_except
+      alias_method :tu, :thru_unless
+      alias_method :w, :wait_for_input      
+    end
+    
+    class Message
+      alias_method :c, :control_change
+      alias_method :cc, :control_change
+      alias_method :n, :note
+      alias_method :no, :note_off
+      alias_method :o, :off
+      alias_method :pc, :program_change
+    end
+    
+    class Output
+      alias_method :out, :output
+    end
+    
+    class Process
+      alias_method :bp, :band_pass_filter
+      alias_method :bpf, :band_pass_filter
+      alias_method :br, :notch_filter
+      alias_method :f, :filter
+      alias_method :hp, :high_pass_filter
+      alias_method :hpf, :high_pass_filter
+      alias_method :l, :limit
+      alias_method :lp, :low_pass_filter
+      alias_method :lpf, :low_pass_filter
+      alias_method :mbf, :filter
+      alias_method :nf, :notch_filter
+      alias_method :tp, :transpose      
+    end
+        
+    class Sticky
+      alias_method :ch, :channel
+      alias_method :ss, :super_sticky
+      alias_method :v, :velocity
+    end
+    
+    class SysEx
+      alias_method :sc, :sysex_command
+      alias_method :sr, :sysex_request
+      alias_method :sx, :sysex_message
+    end
+
+  end
+end
+
+def M(*a, &block)
+  MIDI.message(*a, &block)  
+end

data/lib/micromidi/instructions/sticky.rb

@@ -0,0 +1,59 @@
+#!/usr/bin/env ruby
+#
+module MicroMIDI
+
+  module Instructions
+    
+    class Sticky
+      
+      def initialize(state)
+        @state = state
+      end
+
+      # sets the sticky channel for the current block
+      def channel(val = nil)
+        val.nil? ? @state.channel : @state.channel = val
+      end
+      
+      # sets the octave for the current block
+      def octave(val = nil)
+        val.nil? ? @state.octave : @state.octave = val
+      end
+      
+      # sets the sysex node for the current block
+      def sysex_node(*args)
+        options = args.last.kind_of?(Hash) ? args.last : {}
+        args.empty? ? @state.sysex_node : @state.sysex_node = MIDIMessage::SystemExclusive::Node.new(args.first, options)
+      end
+      alias_method :node, :sysex_node
+
+      # sets the sticky velocity for the current block
+      def velocity(val = nil)
+        val.nil? ? @state.velocity : @state.velocity = val
+      end
+      
+      #
+      # toggles super_sticky mode, a mode where any explicit values used to create MIDI messages
+      # automatically become sticky -- whereas normally the explicit value would only be used for 
+      # the current message.
+      #
+      # e.g.
+      #
+      # note "C4", :channel => 5
+      #
+      # will have the exact same effect as
+      # 
+      # channel 5
+      # note "C4"
+      #
+      # while in super sticky mode
+      #
+      def super_sticky
+        @state.toggle_super_sticky
+      end
+      
+    end
+
+  end
+
+end

data/lib/micromidi/instructions/sysex.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+#
+module MicroMIDI
+
+  module Instructions
+    
+    class SysEx
+
+      include MIDIMessage
+      
+      def initialize(state)
+        @state = state
+      end
+      
+      # create a sysex command
+      def sysex_command(address, data, options = {})
+        options[:sysex_node] ||= options[:node]
+        props = @state.message_properties(options, :sysex_node)
+        SystemExclusive::Command.new(address, data, :node => props[:sysex_node])
+      end
+      alias_method :command, :sysex_command
+      
+      # create a sysex request
+      def sysex_request(address, size, options = {})
+        options[:sysex_node] ||= options[:node]
+        props = @state.message_properties(options, :sysex_node)
+        SystemExclusive::Request.new(address, size, :node => props[:sysex_node])        
+      end
+      alias_method :request, :sysex_request
+      
+      # create an indeterminate sysex message
+      def sysex_message(data, options = {})
+        options[:sysex_node] ||= options[:node]
+        props = @state.message_properties(options, :sysex_node)
+        SystemExclusive::Message.new(data, :node => props[:sysex_node])
+      end
+      alias_method :sysex, :sysex_message
+
+    end
+
+  end
+
+end