midi-events 0.5.0

data/LICENSE.midi-message

@@ -0,0 +1,13 @@
+Copyright 2011-2015 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.md

@@ -0,0 +1,170 @@
+# MIDI Events
+
+**Ruby MIDI Events Objects**
+
+This library is part of a suite of Ruby libraries for MIDI:
+
+| Function | Library |
+| --- | --- |
+| MIDI Events representation | [MIDI Events](https://github.com/javier-sy/midi-events) |
+| MIDI Data parsing | [MIDI Parser](https://github.com/javier-sy/midi-parser) |
+| MIDI communication with Instruments and Control Surfaces | [MIDI Communications](https://github.com/javier-sy/midi-communications) |
+| Low level MIDI interface to MacOS | [MIDI Communications MacOS Layer](https://github.com/javier-sy/midi-communications-macos) |
+| Low level MIDI interface to Linux | **TO DO** (by now [MIDI Communications](https://github.com/javier-sy/midi-communications) uses [alsa-rawmidi](http://github.com/arirusso/alsa-rawmidi)) | 
+| Low level MIDI interface to JRuby | **TO DO** (by now [MIDI Communications](https://github.com/javier-sy/midi-communications) uses [midi-jruby](http://github.com/arirusso/midi-jruby))| 
+| Low level MIDI interface to Windows | **TO DO** (by now [MIDI Communications](https://github.com/javier-sy/midi-communications) uses [midi-winm](http://github.com/arirusso/midi-winmm)) | 
+
+This library is based on [Ari Russo's](http://github.com/arirusso) library [MIDI Message](https://github.com/arirusso/midi-message).
+
+## 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/javier-sy/midi-events/blob/master/lib/midi.yml)
+
+## Install
+
+`gem install midi-events`
+
+Or if you're using Bundler, add this to your Gemfile
+
+`gem "midi-events"`
+
+## Usage
+
+```ruby
+require "midi-events"
+```
+
+#### Basic Messages
+
+There are a few ways to create a new MIDI event. Here are some examples:
+
+```ruby
+MIDIEvents::NoteOn.new(0, 64, 64)
+
+MIDIEvents::NoteOn["E4"].new(0, 100)
+
+MIDIEvents.with(:channel => 0, :velocity => 100) { note_on("E4") }
+```
+
+Those expressions all evaluate to the same object:
+
+```ruby
+#<MIDIEvents::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
+MIDIEvents::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
+#<MIDIEvents::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>>
+```
+
+## Documentation
+
+* (**TO DO**) [rdoc](http://rubydoc.info/github/javier-sy/midi-events)
+
+## Differences between [MIDI Events](https://github.com/javier-sy/midi-events) library and [MIDI Message](https://github.com/arirusso/midi-message) library
+
+[MIDI Events](https://github.com/javier-sy/midi-events) is mostly a clone of [MIDI Message](https://github.com/arirusso/midi-message) with some modifications:
+* Renamed gem to midi-events instead of midi-message
+* Renamed module to MIDIEvents instead of MIDIMessage
+* Removed parsing features (in favour of the more complete parser [MIDI Parser](https://github.com/javier-sy/midi-parser))
+* TODO: update tests to use rspec instead of rake
+* TODO: migrate to (or confirm it's working ok on) Ruby 3.0 and Ruby 3.1
+
+## Then, why does exist this library if it is mostly a clone of another library?
+
+The author has been developing since 2016 a Ruby project called 
+[Musa DSL](https://github.com/javier-sy/musa-dsl) that needs a way 
+of representing MIDI Events and a way of communicating with 
+MIDI Instruments and MIDI Control Surfaces.
+
+[Ari Russo](https://github.com/arirusso) has done a great job creating 
+several interdependent Ruby libraries that allow 
+MIDI Events representation ([MIDI Message](https://github.com/arirusso/midi-message) 
+and [Nibbler](https://github.com/arirusso/nibbler)) 
+and communication with MIDI Instruments and MIDI Control Surfaces 
+([unimidi](https://github.com/arirusso/unimidi), 
+[ffi-coremidi](https://github.com/arirusso/ffi-coremidi) and others) 
+that, **with some modifications**, I've been using in MusaDSL.
+
+After thinking about the best approach to publish MusaDSL 
+I've decided to publish my own renamed version of the modified dependencies because:
+
+* Some differences on the approach of the modifications vs the original library doesn't allow to merge the modifications on the original libraries.
+* Then the renaming of the libraries is needed to avoid confusing existent users of the original libraries.
+* Due to some of the interdependencies of Ari Russo libraries, 
+  the modification and renaming on some of the low level libraries (ffi-coremidi, etc.)
+  forces to modify and rename unimidi library.
+* The original libraries have features
+  (very detailed logging and processing history information, not locking behaviour when waiting input midi messages)
+  that are not needed in MusaDSL and, in fact,
+  can degrade the performance on some use case scenarios in MusaDSL.
+
+All in all I have decided to publish a suite of libraries optimized for MusaDSL use case that also can be used by other people in their projects.
+
+| Function | Library | Based on Ari Russo's| Difference |
+| --- | --- | --- | --- |
+| MIDI Events representation | [MIDI Events](https://github.com/javier-sy/midi-events) | [MIDI Message](https://github.com/arirusso/midi-message) | removed parsing, small improvements |
+| MIDI Data parsing | [MIDI Parser](https://github.com/javier-sy/midi-parser) | [Nibbler](https://github.com/arirusso/nibbler) | removed process history information, minor optimizations |
+| MIDI communication with Instruments and Control Surfaces | [MIDI Communications](https://github.com/javier-sy/midi-communications) | [unimidi](https://github.com/arirusso/unimidi) | use of [MIDI Communications MacOS Layer](https://github.com/javier-sy/midi-communications-macos)
+| Low level MIDI interface to MacOS | [MIDI Communications MacOS Layer](https://github.com/javier-sy/midi-communications-macos) | [ffi-coremidi](https://github.com/arirusso/ffi-coremidi) | removed process history information, locking behaviour when waiting midi events, improved midi devices name detection, minor optimizations |
+| Low level MIDI interface to Linux | **TO DO** | | |
+| Low level MIDI interface to JRuby | **TO DO** | | |
+| Low level MIDI interface to Windows | **TO DO** | | |
+
+## Author
+
+* [Javier Sánchez Yeste](https://github.com/javier-sy)
+
+## Acknowledgements
+
+Thanks to [Ari Russo](http://github.com/arirusso) for his ruby library [MIDI Message](https://github.com/arirusso/midi-message) licensed as Apache License 2.0.
+
+## License
+
+[MIDI Events](https://github.com/javier-sy/midi-events) Copyright (c) 2021 [Javier Sánchez Yeste](https://yeste.studio), licensed under LGPL 3.0 License
+
+[MIDI Message](https://github.com/arirusso/midi-message) Copyright (c) 2011-2015 [Ari Russo](http://arirusso.com), licensed under Apache License 2.0 (see the file LICENSE.midi-message)
+
+

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rake'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+task default: [:test]

data/examples/constants.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+#
+# How to use constants
+#
+
+$:.unshift(File.join("..", "lib"))
+
+require "midi-events"
+
+# some messages for a sequencer
+
+pp MIDIEvents::SystemRealtime["Start"].new
+pp MIDIEvents::NoteOn["E4"].new(0, 100)
+pp MIDIEvents::SystemRealtime["Stop"].new
+
+# this should output something like:
+
+#
+# #<MIDIMessage::SystemRealtime:0x89fda3c
+#  @name="Start",
+#  @status=[15, 250],
+#  @verbose_name="System Realtime: Start">
+#
+# #<MIDIMessage::NoteOn:0x9363cac
+#  @channel=0,
+#  @data=[64, 100],
+#  @name="C3",
+#  @note=64,
+#  @status=[9, 0],
+#  @velocity=100,
+#  @verbose_name="Note On: C3">
+#
+# #<MIDIMessage::SystemRealtime:0x89fc600
+#  @name="Stop",
+#  @status=[15, 252],
+#  @verbose_name="System Realtime: Stop">
+#

data/examples/context.rb

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+#
+# Use a block loaded with velocity and channel
+#
+
+$:.unshift(File.join("..", "lib"))
+
+require "midi-events"
+
+MIDIEvents.with(:channel => 0, :velocity => 100) do
+
+  note_on("E4")
+  note_off("E4")
+
+  note_on("C4")
+  note_off("C4")
+
+  control_change("Portamento", 64)
+
+  note_on("E4")
+  pp note_off("E4")
+
+  pp program_change(20)
+
+end

data/examples/melody.rb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+#
+# Construct a melody
+#
+
+$:.unshift(File.join("..", "lib"))
+
+require "midi-events"
+
+channel = 0
+notes = [36, 40, 43] # C E G
+octaves = 2
+velocity = 100
+
+melody = []
+
+(0..((octaves-1)*12)).step(12) do |oct|
+
+  notes.each { |note| melody << MIDIEvents::NoteOn.new(channel, note + oct, velocity) }
+
+end
+
+pp melody
+
+# this should output something like:
+
+# (will add when I have the constants yaml more filled out)

data/examples/short_messages.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+#
+# Walk through of different ways to instantiate short (non-sysex) MIDI Messages
+#
+
+$:.unshift(File.join("..", "lib"))
+
+require "midi-events"
+
+# Here are examples of different ways to construct messages, going from low to high-level
+
+pp MIDIEvents.parse(0x90, 0x40, 0x40)
+
+channel_msg = MIDIEvents::ChannelMessage.new(0x9, 0x0, 0x40, 0x40)
+
+pp channel_msg
+
+# this will return a NoteOn object with the properties of channel_msg
+pp channel_msg.to_type
+
+pp MIDIEvents::ChannelMessage.new(MIDIEvents::Constant::Status["Note On"], 0x0, 0x40, 0x40)
+
+pp MIDIEvents::ChannelMessage.new(MIDIEvents::Constant::Status["Note On"], 0x0, 0x40, 0x40).to_type
+
+pp MIDIEvents::NoteOn.new(0, 64, 64) # or NoteOn.new(0x0, 0x64, 0x64)
+
+# some message properties are mutable
+
+pp msg = MIDIEvents::NoteOn["E4"].new(0, 100)
+
+msg.note += 5
+
+pp msg

data/examples/sysex.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+#
+# Walk through of different ways to instantiate System Exclusive (SysEx) messages
+#
+
+$:.unshift(File.join("..", "lib"))
+
+require "midi-events"
+
+# you can create a message by parsing bytes
+
+pp MIDIEvents.parse(0xF0, 0x41, 0x10, 0x42, 0x12, 0x40, 0x00, 0x7F, 0x00, 0x41, 0xF7)
+
+# or create a Node (destination) object and then send messages to that.
+# a Node represents a device that you"re sending a message to
+# (eg. your Yamaha DX7 is a Node).
+
+node = MIDIEvents::SystemExclusive::Node.new(0x41, model_id: 0x42, device_id: 0x10)
+
+# The following will create a command object for address "407F00" with value "00"
+# associated with our node
+#
+# A command is a sysex message where the status (byte index 4) is 0x12
+#
+# A Request type message (SystemExclusive::Request) has a status byte
+# equal to 0x11
+
+pp MIDIEvents::SystemExclusive::Command.new([0x40, 0x7F, 0x00], 0x00, node: node)
+
+# it is actually optional to pass a node to your message-- one case where not
+# doing so is useful is when want to have a generic message prototype used with
+# multiple nodes
+
+prototype = MIDIEvents::SystemExclusive::Command.new([0x40, 0x7F, 0x00], 0x00)
+
+pp node.new_message_from(prototype) # this will create a new message using the prototype"s data and the node"s information
+
+# you can also generate a totally new message from the Node
+
+pp node.command([0x40, 0x7F, 0x00], 0x00)
+
+# each of the print statements in this example should output a message something like:
+
+#
+# #<MIDIMessage::SystemExclusive::Command:0x9c1e57c
+# @address=[64, 0, 127],
+# @checksum=[65],
+# @data=[0],
+# @node=
+#  #<MIDIMessage::SystemExclusive::Node:0x9c1e5a4
+#   @device_id=16,
+#   @manufacturer=65,
+#   @model_id=66>>
+#
+
+# read more about SysEx messages in general here: http://www.2writers.com/eddie/TutSysEx.htm

data/lib/midi-events/channel_message.rb

@@ -0,0 +1,152 @@
+module MIDIEvents
+  # Common behavior amongst Channel Message types
+  module ChannelMessage
+    include MIDIEvents # this enables ..kind_of?(MIDIEvents)
+
+    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 [*Fixnum] data The status nibbles and data bytes
+    # @return [RawChannelMessage] The resulting RawChannelMessage object
+    def self.new(*data, &block)
+      Message.new(*data, &block)
+    end
+
+    # @param [*Fixnum] data The status nibbles and data bytes
+    def initialize(*data)
+      data = data.dup
+      options = data.last.is_a?(Hash) ? data.pop : {}
+      add_constant_value(options[:const], data) unless options[:const].nil?
+      initialize_channel_message(self.class.type_for_status, *data)
+    end
+
+    private
+
+    def self.included(base)
+      base.send(:include, ::MIDIEvents::Message)
+      base.send(:extend, ClassMethods)
+    end
+
+    # Add the given constant to message data
+    def add_constant_value(constant, data)
+      index = Constant::Loader.get_index(self)
+      data.insert(index, constant.value)
+    end
+
+    # Assign the message data
+    def assign_data(status_nibble_1, status_nibble_2, data_byte_1, data_byte_2 = 0)
+      @status = [status_nibble_1, status_nibble_2]
+      @data = [data_byte_1]
+      @data[1] = data_byte_2 if self.class.second_data_byte?
+    end
+
+    # Initialize the message: assign data, decorate with accessors
+    def initialize_channel_message(status_nibble_1, status_nibble_2, data_byte_1, data_byte_2 = 0)
+      assign_data(status_nibble_1, status_nibble_2, data_byte_1, data_byte_2)
+      Accessors.initialize(self) unless self.class.properties.nil?
+      initialize_message(status_nibble_1, status_nibble_2)
+    end
+
+    class Accessors
+      SCHEMA = [
+        { name: :status, index: 1 }, # second status nibble
+        { name: :data, index: 0 }, # first data byte
+        { name: :data, index: 1 } # second data byte
+      ].freeze
+
+      # @param [Class] klass
+      # @return [Class]
+      def self.decorate(klass)
+        decorator = new(klass)
+        decorator.decorate
+      end
+
+      # Initialize a message object with it's properties
+      # @param [MIDIEvents] message
+      # @return [Boolean]
+      def self.initialize(message)
+        message.class.properties.each_with_index do |property, i|
+          data_mapping = SCHEMA[i]
+          container = message.send(data_mapping[:name])
+          index = data_mapping[:index]
+          message.send(:instance_variable_set, "@#{property.to_s}", container[index])
+        end
+        true
+      end
+
+      # @param [Class] klass
+      def initialize(klass)
+        @klass = klass
+      end
+
+      # @return [Class]
+      def decorate
+        @klass.properties.each_with_index do |property, i|
+          data_mapping = SCHEMA[i]
+          define_getter(property)
+          define_setter(property, data_mapping)
+        end
+        @klass
+      end
+
+      private
+
+      # @param [Symbol, String] property
+      # @return [Boolean]
+      def define_getter(property)
+        @klass.send(:attr_reader, property)
+        true
+      end
+
+      # @param [Symbol, String] property
+      # @param [Hash] mapping
+      # @return [Boolean]
+      def define_setter(property, mapping)
+        index = mapping[:index]
+        @klass.send(:define_method, "#{property.to_s}=") do |value|
+          send(:instance_variable_set, "@#{property.to_s}", value)
+          send(mapping[:name])[index] = value
+          send(:update)
+          return self
+        end
+        true
+      end
+
+    end
+
+    # For defining Channel Message class types
+    module ClassMethods
+      def properties
+        const_get('DATA') if const_defined?('DATA')
+      end
+
+      # 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
+      end
+
+    end
+
+    # 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'.freeze
+
+      # Build a Channel Message from raw nibbles and bytes
+      # eg ChannelMessage.new(0x9, 0x0, 0x40, 0x40)
+      # @param [*Fixnum] data The status nibbles and data bytes
+      # @return [RawChannelMessage] The resulting RawChannelMessage object
+      def initialize(*data)
+        initialize_channel_message(*data)
+      end
+    end
+  end
+end