midiator 0.1.0

data/examples/chromatic_scale.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+#
+# A simple example that plays the chromatic scale from C4 to C6 and back
+# again.  Also shows how to use the MIDIator::Notes mixin.
+#
+# == Authors
+#
+# * Ben Bleything <ben@bleything.net>
+#
+# == Copyright
+#
+# Copyright (c) 2008 Ben Bleything
+#
+# This code released under the terms of the MIT license.
+#
+
+require 'midiator'
+
+midi = MIDIator::Interface.new
+midi.autodetect_driver
+
+include MIDIator::Notes
+
+scale = [ C4, Cs4, D4, Eb4, E4, F4, Fs4, G4, Gs4, A4, Bb4, B4,
+          C5, Cs5, D5, Eb5, E5, F5, Fs5, G5, Gs5, A5, Bb5, B5 ]
+
+scale.each do |note|
+	midi.play note
+end
+
+scale.reverse.each do |note|
+	midi.play note
+end

data/examples/metronome.rb

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+#
+# A metronome that can run at any given tempo.
+#
+# == Synopsis
+#
+# $ ./metronome
+# => starts a metronome running at 120bpm
+#
+# $ ./metronome 180
+# => starts a metronome running at 180bpm
+#
+# == Authors
+#
+# * Ben Bleything <ben@bleything.net>
+#
+# == Copyright
+#
+# Copyright (c) 2008 Ben Bleything
+#
+# This code released under the terms of the MIT license.
+#
+
+########################################################################
+### S A N I T Y   C H E C K S
+########################################################################
+
+@tempo = 120.0
+
+if input = ARGV[0]
+	begin
+		@tempo = Float( input )
+	rescue ArgumentError => e
+		$stderr.puts "'#{input}' is not a valid tempo.\n"
+		$stderr.puts "Please specify the tempo in beats per minute " +
+			"(bpm).  Fractional values are allowed!"
+
+		exit 1
+	end
+end
+
+
+########################################################################
+### M I D I A T O R   S E T U P
+########################################################################
+
+require 'midiator'
+include MIDIator::Notes
+
+@midi = MIDIator::Interface.new
+@midi.autodetect_driver
+@midi.program_change 0, 115 # Wood block!
+
+# trap interrupts to properly kill the timer
+Signal.trap( "INT" ) { @timer.thread.exit! }
+
+########################################################################
+### T I M E R   S E T U P
+########################################################################
+
+# 60 / tempo gives us the delay (in seconds) between each beat.  Divide
+# that again by 10 to give us our desired resolution.
+@interval = 60.0 / @tempo
+@timer = MIDIator::Timer.new( @interval / 10 )
+
+def register_next_bang( time )
+	@timer.at( time ) do |yielded_time|
+		register_next_bang yielded_time + @interval
+		@midi.play MiddleC
+	end
+end
+
+puts "Starting metronome running at #{@tempo} bpm."
+register_next_bang Time.now.to_f
+@timer.thread.join

data/lib/midiator.rb

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+#
+# A Ruby library for interacting with system-level MIDI services.
+#
+# == Authors
+#
+# * Ben Bleything <ben@bleything.net>
+#
+# == Copyright
+#
+# Copyright (c) 2008 Ben Bleything
+#
+# This code released under the terms of the MIT license.
+#
+
+require 'string_extensions'
+
+module MIDIator
+	VERSION = "0.1.0"
+end
+
+require 'midiator/driver'
+require 'midiator/driver_registry'
+require 'midiator/exceptions'
+require 'midiator/interface'
+require 'midiator/timer'
+
+##########################################################################
+### S H O R T C U T   M O D U L E S
+##########################################################################
+require 'midiator/drums'
+require 'midiator/notes'

data/lib/midiator/driver.rb

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+#
+# The abstractish superclass of all MIDIator MIDI drivers.
+#
+# == Authors
+#
+# * Ben Bleything <ben@bleything.net>
+#
+# == Copyright
+#
+# Copyright (c) 2008 Ben Bleything
+#
+# This code released under the terms of the MIT license.
+#
+
+require 'midiator'
+require 'midiator/driver_registry'
+
+class MIDIator::Driver
+
+	##########################################################################
+	### M I D I   C O M M A N D   C O N S T A N T S
+	##########################################################################
+
+	# Note on
+	ON  = 0x90
+
+	# Note off
+	OFF = 0x80
+
+	# Program change
+	PC  = 0xc0
+
+	##########################################################################
+	### M A G I C   H O O K S
+	##########################################################################
+
+	### Auto-registers subclasses of MIDIator::Driver with the driver registry.
+	def self::inherited( driver_class )
+		driver_name = driver_class.to_s.underscore
+		MIDIator::DriverRegistry.instance.register( driver_name, driver_class )
+	end
+
+
+	##########################################################################
+	### I N T E R F A C E   A P I
+	##########################################################################
+	# These methods are the same across all drivers and are the interface that
+	# MIDIator::Interface interacts with.
+	##########################################################################
+
+	### Do any pre-open setup necessary.  Often will not be overridden.
+	def initialize
+		open
+	end
+
+
+	### Shortcut to send a note_on message.
+	def note_on( note, channel, velocity )
+		message( ON | channel, note, velocity )
+	end
+
+
+	### Shortcut to send a note_off message.
+	def note_off( note, channel, velocity )
+		message( OFF | channel, note, velocity )
+	end
+
+
+	### Shortcut to send a program_change message.
+	def program_change( channel, program )
+		message( PC | channel, program )
+	end
+
+	##########################################################################
+	### D R I V E R   A P I
+	##########################################################################
+	# subclasses must implement these methods.
+	##########################################################################
+	protected
+	##########################################################################
+
+	### Open the channel to the MIDI service.
+	def open
+		raise NotImplementedError, "You must implement #open in your driver."
+	end
+
+
+	### Close the channel to the MIDI service.
+	def close
+		raise NotImplementedError, "You must implement #close in your driver."
+	end
+
+
+	### Send MIDI message to the MIDI service.
+	def message( *args )
+		raise NotImplementedError, "You must implement #message in your driver."
+	end
+
+end

data/lib/midiator/driver_registry.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+#
+# A hash-like register of all loaded drivers.
+#
+# == Authors
+#
+# * Ben Bleything <ben@bleything.net>
+#
+# == Copyright
+#
+# Copyright (c) 2008 Ben Bleything
+#
+# This code released under the terms of the MIT license.
+#
+
+require 'singleton'
+require 'midiator'
+
+class MIDIator::DriverRegistry
+	include Singleton
+
+	### Stores the given +klass+ in the <tt>@drivers</tt> hash, keyed by +name+.
+	### Typically called via MIDIator::Driver's +inherited+ hook.
+	def register_driver( name, klass )
+		@drivers ||= {}
+
+		raise ArgumentError, "Attempted to register something that is not a MIDIator::Driver" unless
+			klass < MIDIator::Driver
+
+		@drivers.each do |existing_name, existing_klass|
+			raise ArgumentError, "Already registered #{existing_klass.to_s} as '#{existing_name}'." if
+				existing_klass == klass
+		end
+
+		@drivers[ name ] = klass
+	end
+	alias register register_driver
+	alias <<       register_driver
+
+
+	### Returns the number of drivers currently registered.
+	def size
+		return @drivers.size
+	end
+
+
+	### Included to make the registry quack like a hash. Delegates to the
+	### <tt>@drivers</tt> hash.
+	def []( name )
+		return @drivers[ name ]
+	end
+
+end

data/lib/midiator/drivers/alsa.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+#
+# The MIDIator driver to interact with ALSA on Linux.  Taken more or less
+# directly from Practical Ruby Projects.
+#
+# NOTE: as yet completely untested.
+#
+# == Authors
+#
+# * Topher Cyll
+# * Ben Bleything <ben@bleything.net>
+#
+# == Copyright
+#
+# Copyright (c) 2008 Topher Cyll
+#
+# This code released under the terms of the MIT license.
+#
+
+require 'dl/import'
+
+require 'midiator'
+require 'midiator/driver'
+require 'midiator/driver_registry'
+
+class MIDIator::Driver::ALSA < MIDIator::Driver # :nodoc:
+	module C # :nodoc:
+		extend DL::Importable
+		dlload 'libasound.so'
+
+		extern "int snd_rawmidi_open(void*, void*, char*, int)"
+		extern "int snd_rawmidi_close(void*)"
+		extern "int snd_rawmidi_write(void*, void*, int)"
+		extern "int snd_rawmidi_drain(void*)"
+	end
+
+	def open
+		@output = DL::PtrData.new(nil)
+		C.snd_rawmidi_open(nil, @output.ref, "virtual", 0)
+	end
+
+	def close
+		C.snd_rawmidi_close(@output)
+	end
+
+	def message(*args)
+		format = "C" * args.size
+		bytes = args.pack(format).to_ptr
+		C.snd_rawmidi_write(@output, bytes, args.size)
+		C.snd_rawmidi_drain(@output)
+	end
+end

data/lib/midiator/drivers/core_midi.rb

@@ -0,0 +1,82 @@
+#!/usr/bin/env ruby
+#
+# The MIDIator driver to interact with OSX's CoreMIDI.  Taken more or less
+# directly from Practical Ruby Projects.
+#
+# == Authors
+#
+# * Topher Cyll
+# * Ben Bleything <ben@bleything.net>
+#
+# == Copyright
+#
+# Copyright (c) 2008 Topher Cyll
+#
+# This code released under the terms of the MIT license.
+#
+
+require 'dl/import'
+
+require 'midiator'
+require 'midiator/driver'
+require 'midiator/driver_registry'
+
+class MIDIator::Driver::CoreMIDI < MIDIator::Driver # :nodoc:
+	##########################################################################
+	### S Y S T E M   I N T E R F A C E
+	##########################################################################
+	module C # :nodoc:
+		extend DL::Importable
+		dlload '/System/Library/Frameworks/CoreMIDI.framework/Versions/Current/CoreMIDI'
+
+		extern "int MIDIClientCreate( void*, void*, void*, void* )"
+		extern "int MIDIClientDispose( void* )"
+		extern "int MIDIGetNumberOfDestinations()"
+		extern "void* MIDIGetDestination( int )"
+		extern "int MIDIOutputPortCreate( void*, void*, void* )"
+		extern "void* MIDIPacketListInit( void* )"
+		extern "void* MIDIPacketListAdd( void*, int, void*, int, int, int, void* )"
+		extern "int MIDISend( void*, void*, void* )"
+	end
+
+	module CF # :nodoc:
+		extend DL::Importable
+		dlload '/System/Library/Frameworks/CoreFoundation.framework/Versions/Current/CoreFoundation'
+
+		extern "void* CFStringCreateWithCString( void*, char*, int )"
+	end
+
+	##########################################################################
+	### D R I V E R   A P I
+	##########################################################################
+
+	def open
+		client_name = CF.cFStringCreateWithCString( nil, "RubyMIDI", 0 )
+		@client = DL::PtrData.new( nil )
+		C.mIDIClientCreate( client_name, nil, nil, @client.ref )
+
+		port_name = CF.cFStringCreateWithCString( nil, "Output", 0 )
+		@outport = DL::PtrData.new( nil )
+		C.mIDIOutputPortCreate( @client, port_name, @outport.ref )
+
+		number_of_destinations = C.mIDIGetNumberOfDestinations()
+		raise NoMIDIDestinations if number_of_destinations < 1
+		@destination = C.mIDIGetDestination( @midi_destination )
+	end
+
+	def close
+		C.mIDIClientDispose( @client )
+	end
+
+	def message( *args )
+		format = "C" * args.size
+		bytes = args.pack( format ).to_ptr
+		packet_list = DL.malloc( 256 )
+		packet_ptr = C.mIDIPacketListInit( packet_list )
+
+		# Pass in two 32-bit 0s for the 64 bit time
+		packet_ptr = C.mIDIPacketListAdd( packet_list, 256, packet_ptr, 0, 0, args.size, bytes )
+
+		C.mIDISend( @outport, @destination, packet_list )
+	end
+end

data/lib/midiator/drivers/winmm.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+#
+# The MIDIator driver to interact with Windows Multimedia.  Taken more or less
+# directly from Practical Ruby Projects.
+#
+# NOTE: as yet completely untested.
+#
+# == Authors
+#
+# * Topher Cyll
+# * Ben Bleything <ben@bleything.net>
+#
+# == Copyright
+#
+# Copyright (c) 2008 Topher Cyll
+#
+# This code released under the terms of the MIT license.
+#
+
+require 'dl/import'
+
+require 'midiator'
+require 'midiator/driver'
+require 'midiator/driver_registry'
+
+class MIDIator::Driver::WinMM < MIDIator::Driver # :nodoc:
+	module C # :nodoc:
+		extend DL::Importable
+		dlload 'winmm'
+
+		extern "int midiOutOpen(HMIDIOUT*, int, int, int, int)"
+		extern "int midiOutClose(int)"
+		extern "int midiOutShortMsg(int, int)"
+	end
+
+	def open
+		@device = DL.malloc(DL.sizeof('I'))
+		C.midiOutOpen(@device, -1, 0, 0, 0)
+	end
+
+	def close
+		C.midiOutClose(@device.ptr.to_i)
+	end
+
+	def message(one, two=0, three=0)
+		message = one + (two << 8) + (three << 16)
+		C.midiOutShortMsg(@device.ptr.to_i, message)
+	end
+end