midi-message 0.3.2 → 0.4.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ad978e231aef5931892a5fb96573c4e709f3ad64
+  data.tar.gz: 53cc976f50cb5c4d5ba619f3d3d4b1aaa10a71d9
+SHA512:
+  metadata.gz: 6a51573df46bbee8bc764be4d139b52c7366c192c0402846bb3cae67efa4e5cbfa87b4ad1982765fc80f2d6d3e088c857f6ee5a9b0bc6d0f68a2e2ca08f3a931
+  data.tar.gz: c7264a018b5b523aeaa7391ab2f387aab0a2a9b66f583692bdd05a12eb7968c9ebc0ef120de61cfe82ab42e6f8c3301522fe957f6fc9ca9b5969d387ff8f1c5c

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright 2010-2011 Ari Russo
+Copyright 2011-2014 Ari Russo
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -10,4 +10,4 @@ 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.
+limitations under the License.

data/README.md

@@ -0,0 +1,120 @@
+# MIDI Message
+
+![midi](http://img208.imageshack.us/img208/5623/mks80small.jpg)
+
+Ruby MIDI message objects
+
+## Features
+
+* Flexible API to accommodate various sources and destinations of MIDI data
+* Simple approach to System Exclusive data and devices
+* [YAML dictionary of MIDI constants](https://github.com/arirusso/midi-message/blob/master/lib/midi.yml)
+	
+## Install
+
+`gem install midi-message`
+
+Or if you're using Bundler, add this to your Gemfile
+
+`gem "midi-message"`
+
+## Usage
+
+```ruby
+require "midi-message"
+  
+include MIDIMessage
+```
+  
+#### Basic Messages
+
+There are a few ways to create a new MIDI message.  Here are some examples
+ 
+```ruby   
+NoteOn.new(0, 64, 64)
+  
+NoteOn["E4"].new(0, 100)
+  
+with(:channel => 0, :velocity => 100) { note_on("E4") }
+```
+
+Those expressions all evaluate to the same object
+
+```ruby
+#<MIDIMessage::NoteOn:0x9c1c240
+   @channel=0,
+   @data=[64, 64],
+   @name="E4",
+   @note=64,
+   @status=[9, 0],
+   @velocity=64,
+   @verbose_name="Note On: E4">
+```
+
+#### SysEx Messages
+
+As with any kind of message, you can begin with raw data
+  
+```ruby
+SystemExclusive.new(0xF0, 0x41, 0x10, 0x42, 0x12, 0x40, 0x00, 0x7F, 0x00, 0x41, 0xF7)
+```
+  
+Or in a more object oriented way
+
+```ruby  
+synth = SystemExclusive::Node.new(0x41, :model_id => 0x42, :device_id => 0x10)
+    
+SystemExclusive::Command.new([0x40, 0x7F, 0x00], 0x00, :node => synth)
+```
+
+A Node represents a device that you're sending a message to (eg. your Yamaha DX7 is a Node).  Sysex messages can either be a Command or Request
+  
+You can use the Node to instantiate a message
+
+```ruby  
+synth.command([0x40, 0x7F, 0x00], 0x00)
+```
+  
+One way or another, you will wind up with a pair of objects like this
+
+```ruby
+#<MIDIMessage::SystemExclusive::Command:0x9c1e57c
+   @address=[64, 0, 127],
+   @checksum=[65],
+   @data=[0],
+   @node=
+    #<MIDIMessage::SystemExclusive::Node:0x9c1e5a4
+     @device_id=16,
+     @manufacturer_id=65,
+     @model_id=66>>
+```
+     
+#### Parsing
+
+The parse method will take any valid message data and return the object representation
+
+```ruby
+MIDIMessage.parse(0x90, 0x40, 0x40)
+  
+  #<MIDIMessage::NoteOn:0x9c1c240 ..>
+  
+MIDIMessage.parse(0xF0, 0x41, 0x10, 0x42, 0x12, 0x40, 0x00, 0x7F, 0x00, 0x41, 0xF7)
+  
+  #<MIDIMessage::SystemExclusive::Command:0x9c1e57c ..>
+```
+
+Check out [nibbler](http://github.com/arirusso/nibbler) for more advanced parsing
+
+## Documentation
+
+* [rdoc](http://rubydoc.info/github/arirusso/midi-message)
+
+## Author
+
+* [Ari Russo](http://github.com/arirusso) <ari.russo at gmail.com>
+
+## License
+
+Apache 2.0, See the file LICENSE
+
+Copyright (c) 2011-2014 Ari Russo

data/lib/midi-message/channel_message.rb

@@ -1,29 +1,27 @@
-#!/usr/bin/env ruby
-#
 module MIDIMessage
 
-  # common behavior amongst Channel Message types
+  # Common behavior amongst Channel Message types
   module ChannelMessage
 
-    attr_reader :data,
-                :name
-                
-    def self.new(*a, &block)
-      RawChannelMessage.new(*a, &block)
+    attr_reader :data, :name
+
+    # Shortcut to RawChannelMessage.new
+    # aka build a ChannelMessage from raw nibbles and bytes
+    # eg ChannelMessage.new(0x9, 0x0, 0x40, 0x40)
+    # @param [*Array<Fixnum>] data The status nibbles and data bytes
+    # @return [RawChannelMessage] The resulting RawChannelMessage object
+    def self.new(*data, &block)
+      Message.new(*data, &block)
     end
-                  
-    def initialize(*a)
-      options = a.last.kind_of?(Hash) ? a.pop : {}
-      @const = options[:const]        
-      unless @const.nil?
-        key = self.class.map_constants_to
-        ind = self.class.properties.index(key)
-        ind ||= 0
-        a.insert(ind, @const.value)               
-      end
-      initialize_channel_message(self.class.type_for_status, *a)
+
+    # @param [*Array<Fixnum>] data The status nibbles and data bytes
+    def initialize(*data)
+      data = data.dup
+      options = data.last.kind_of?(Hash) ? data.pop : {}      
+      processed_data = options[:const].nil? ? data : data_with_const(data, options[:const])
+      initialize_channel_message(self.class.type_for_status, *processed_data)
     end
-    
+
     def initialize_properties
       props = [
         { :name => :status, :index => 1 },
@@ -44,15 +42,22 @@ module MIDIMessage
         end
       end
     end
-    
+
     protected
-    
+
     def self.included(base)
+      base.include(ShortMessage)
       base.extend(ClassMethods)
     end
 
     private
-    
+
+    def data_with_const(data, const)
+      key = self.class.constant_property
+      ind = self.class.properties.index(key) || 0
+      data.insert(ind, const.value)               
+    end
+
     def initialize_channel_message(status_nibble_1, status_nibble_2, data_byte_1, data_byte_2 = 0)
       @status = [status_nibble_1, status_nibble_2]
       @data = [data_byte_1]
@@ -60,120 +65,58 @@ module MIDIMessage
       initialize_properties
       initialize_short_message(status_nibble_1, status_nibble_2)
     end
-    
+
+    # For defining Channel Message class types
     module ClassMethods
-      
-      attr_reader :properties
-            
+
+      # Get the status nibble for this particular message type
+      # @return [Fixnum] The status nibble
       def type_for_status
-        @display_name.nil? ? nil : Status[@display_name] 
+        Status[display_name] 
       end
 
-      def schema(*args)
-        @properties = args
+      def properties
+        const_get("DATA") if const_defined?("DATA")
       end
-      alias_method :layout, :schema
 
+      # Does the schema of this Channel Message carry a second data byte?
+      # eg. NoteMessage does, and ProgramChange doesn"t
+      # @return [Boolean] Is there a second data byte on this message type?
       def second_data_byte?
-        @properties.nil? || (@properties.length-1) > 1
+        properties.nil? || (properties.length-1) > 1
       end
 
     end
-        
-  end
-
-  # use this if you want to instantiate a raw channel message
-  #
-  # example = ChannelMessage.new(0x9, 0x0, 0x40, 0x57) # creates a raw note-on message
-  #
-  class RawChannelMessage
-
-    include ShortMessage
-    include ChannelMessage
-
-    use_display_name 'Channel Message'
-    
-    def initialize(*a)
-      initialize_channel_message(*a)
-    end        
-    
-    def to_type
-      status = (@status[0] << 4) + (@status[1])
-      MIDIMessage.parse(status, *@data)
-    end
-
-  end
-
-  #
-  # MIDI Channel Aftertouch message
-  #
-  class ChannelAftertouch
-
-    include ShortMessage
-    include ChannelMessage
 
-    schema :channel, :value
-    use_display_name 'Channel Aftertouch'
-
-  end
-  ChannelPressure = ChannelAftertouch
-
-  #
-  # MIDI Control Change message
-  #
-  class ControlChange
-
-    include ShortMessage
-    include ChannelMessage
-
-    schema :channel, :index, :value
-    use_display_name 'Control Change'
-    use_constants 'Control Change', :for => :index
-   
-  end  
-  Controller = ControlChange #shortcut
-
-  #
-  # MIDI Pitch Bend message
-  #
-  class PitchBend
-
-    include ShortMessage
-    include ChannelMessage
-
-    schema :channel, :low, :high
-    use_display_name 'Pitch Bend'
-
-  end
-
-  #
-  # MIDI Polyphonic (note specific) Aftertouch message
-  #
-  class PolyphonicAftertouch
-
-    include ShortMessage
-    include ChannelMessage
+    # Use this if you want to instantiate a raw channel message
+    #
+    # For example ChannelMessage::Message.new(0x9, 0x0, 0x40, 0x57)
+    # creates a raw note-on message
+    class Message
+
+      include ChannelMessage
+
+      DISPLAY_NAME = "Channel Message"
+
+      # Build a Channel Mssage from raw nibbles and bytes
+      # eg ChannelMessage.new(0x9, 0x0, 0x40, 0x40)
+      # @param [*Array<Fixnum>] data The status nibbles and data bytes
+      # @return [RawChannelMessage] The resulting RawChannelMessage object
+      def initialize(*data)
+        initialize_channel_message(*data)
+      end        
+
+      # Convert this RawChannelMessage to one of the more specific ChannelMessage types
+      # eg. RawChannelMessage.new(0x9, 0x0, 0x40, 0x40).to_type would result in
+      # NoteMessage.new(0x0, 0x40, 0x40)
+      # @return [ChannelMessage] The resulting specific ChannelMessage object
+      def to_type
+        status = (@status[0] << 4) + (@status[1])
+        MIDIMessage.parse(status, *@data)
+      end
 
-    schema :channel, :note, :value
-    use_display_name 'Polyphonic Aftertouch'
-    use_constants 'Note', :for => :note
+    end
 
   end
-  PolyAftertouch = PolyphonicAftertouch
-  PolyPressure = PolyphonicAftertouch
-  PolyphonicPressure = PolyphonicAftertouch
 
-  #
-  # MIDI Program Change message
-  #
-  class ProgramChange
-
-    include ShortMessage
-    include ChannelMessage
-
-    schema :channel, :program
-    use_display_name 'Program Change'
-
-  end
-  
 end

data/lib/midi-message/constant.rb

@@ -1,6 +1,3 @@
-#!/usr/bin/env ruby
-#
-
 module MIDIMessage
 
   # MIDI Constants

data/lib/midi-message/message.rb

@@ -0,0 +1,204 @@
+module MIDIMessage
+
+  #
+  # MIDI Channel Aftertouch message
+  #
+  class ChannelAftertouch
+
+    include ChannelMessage
+
+    DATA = [:channel, :value]
+    DISPLAY_NAME = "Channel Aftertouch"
+    
+  end
+  ChannelPressure = ChannelAftertouch
+
+  #
+  # MIDI Control Change message
+  #
+  class ControlChange
+
+    include ChannelMessage
+
+    DATA = [:channel, :index, :value]
+    DISPLAY_NAME = "Control Change"
+    CONSTANT = { "Control Change" => :index }
+   
+  end  
+  Controller = ControlChange #shortcut
+
+  #
+  # MIDI Pitch Bend message
+  #
+  class PitchBend
+
+    include ChannelMessage
+
+    DATA = [:channel, :low, :high]
+    DISPLAY_NAME = "Pitch Bend"
+
+  end
+
+  #
+  # MIDI Polyphonic (note specific) Aftertouch message
+  #
+  class PolyphonicAftertouch
+
+    include ChannelMessage
+
+    DATA = [:channel, :note, :value]
+    DISPLAY_NAME = "Polyphonic Aftertouch"
+    CONSTANT = { "Note" => :note }
+
+  end
+  PolyAftertouch = PolyphonicAftertouch
+  PolyPressure = PolyphonicAftertouch
+  PolyphonicPressure = PolyphonicAftertouch
+
+  #
+  # MIDI Program Change message
+  #
+  class ProgramChange
+
+    include ChannelMessage
+
+    DATA = [:channel, :program]
+    DISPLAY_NAME = "Program Change"
+
+  end
+
+  #
+  # MIDI Note-Off message
+  #
+  class NoteOff
+
+    include NoteMessage
+
+    DATA = [:channel, :note, :velocity]
+    DISPLAY_NAME = "Note Off"
+    CONSTANT = { "Note" => :note }
+
+  end
+
+  #
+  # MIDI Note-On message
+  #
+  class NoteOn
+    
+    include NoteMessage   
+
+    DATA = [:channel, :note, :velocity]
+    DISPLAY_NAME = "Note On"
+    CONSTANT = { "Note" => :note }
+    
+    # returns the NoteOff equivalent of this object
+    def to_note_off
+      NoteOff.new(channel, note, velocity)
+    end
+
+  end
+
+  #
+  # MIDI System-Common message
+  #
+  class SystemCommon
+
+    include SystemMessage
+
+    DISPLAY_NAME = "System Common"
+    
+    attr_reader :data
+    
+    def initialize(*a)
+      options = a.last.kind_of?(Hash) ? a.pop : {}
+      @const = options[:const]
+      id = @const.nil? ? a.shift : @const.value
+      id = strip_redundant_nibble(id)
+      initialize_short_message(0xF, id)
+      @data = [a[0], a[1]]
+    end
+    
+  end  
+  
+  #
+  # MIDI System-Realtime message
+  #
+  class SystemRealtime
+
+    include SystemMessage
+
+    DISPLAY_NAME = "System Realtime"
+    
+    def initialize(*a)
+      options = a.last.kind_of?(Hash) ? a.pop : {} 
+      @const = options[:const]
+      id = @const.nil? ? a[0] : @const.value
+      id = strip_redundant_nibble(id)
+      initialize_short_message(0xF, id)
+    end
+
+    def id
+      @status[1]
+    end
+
+  end
+
+  module SystemExclusive
+
+    # A SysEx command message
+    # A command message is identified by having a status byte equal to 0x12
+    class Command
+
+      include SystemExclusive::InstanceMethods
+
+      attr_accessor :data
+      alias_method :value, :data
+
+      TypeByte = 0x12
+      
+      def initialize(address, data, options = {})
+        # store as a byte if it's a single byte
+        @data = (data.kind_of?(Array) && data.length.eql?(1)) ? data[0] : data
+        initialize_sysex(address, options)
+      end
+      
+    end
+    
+    # A SysEx request message
+    # A request message is identified by having a status byte equal to 0x11
+    class Request
+
+      include SystemExclusive::InstanceMethods
+      
+      attr_reader :size
+      alias_method :value, :size
+
+      TypeByte = 0x11
+      
+      def initialize(address, size, options = {})
+        self.size = (size.kind_of?(Array) && size.length.eql?(1)) ? size[0] : size
+        initialize_sysex(address, options)
+      end
+      
+      def size=(val)
+        # accepts a Numeric or Array but
+        # must always store value as an array of three bytes
+        size = []
+        if val.kind_of?(Array) && val.size <= 3
+          size = val
+        elsif val.kind_of?(Numeric) && (((val + 1) / 247) <= 2)
+          size = []
+          div, mod = *val.divmod(247)
+          size << mod unless mod.zero?
+          div.times { size << 247 }
+        end
+        (3 - size.size).times { size.unshift 0 }
+        @size = size
+      end
+      
+    end
+
+  end
+  
+end
+

data/lib/midi-message/note_message.rb

@@ -1,70 +1,40 @@
-#!/usr/bin/env ruby
-#
 module MIDIMessage
 
-  #
   # Common Note Message Behavior
-  #
   module NoteMessage
 
-    # the octave number of the note
+    def self.included(base)
+      base.include(ChannelMessage)
+    end
+
+    # The octave number of the note
+    # @return [Fixnum]
     def octave
-      (note / 12) -1
+      (note / 12) - 1
     end
     alias_method :oct, :octave
     
-    # set the octave number of the note
-    def octave=(val)
-      self.note = ((val + 1) * 12) + abs_note
+    # Set the octave number of the note
+    # @param [Fixnum] value
+    # @return [NoteMessage] self
+    def octave=(value)
+      self.note = ((value + 1) * 12) + abs_note
       self
     end
     alias_method :oct=, :octave=
     
-    # how many half-steps is this note above the closest C
+    # How many half-steps is this note above the closest C
+    # @return [Fixnum]
     def abs_note
       note - ((note / 12) * 12)
     end
     
-    # the name of the note without its octave e.g. F#
+    # The name of the note without its octave e.g. F#
+    # @return [String]
     def note_name
       name.split(/-?\d\z/).first
     end
         
   end
-
-  #
-  # MIDI Note-Off message
-  #
-  class NoteOff
-
-    include NoteMessage
-    include ShortMessage
-    include ChannelMessage
-
-    schema :channel, :note, :velocity
-    use_display_name 'Note Off'
-    use_constants 'Note', :for => :note
-
-  end
-
-  #
-  # MIDI Note-On message
-  #
-  class NoteOn
-    
-    include NoteMessage
-    include ShortMessage
-    include ChannelMessage    
-
-    schema :channel, :note, :velocity
-    use_display_name 'Note On'
-    use_constants 'Note', :for => :note
-    
-    # returns the NoteOff equivalent of this object
-    def to_note_off
-      NoteOff.new(channel, note, velocity)
-    end
-
-  end
   
 end