midilib 0.8.4

data/ChangeLog

@@ -0,0 +1,87 @@
+2005-03-21  Jim Menard  <jimm@io.com>
+
+	* lib/midilib/event.rb (Realtime::initialize): set @is_realtime
+	to true, not false.
+	(SystemCommon::initialize): moved @is_system = true to here
+	(SystemExclusive::initialize): ...from here.
+
+2005-03-20  Jim Menard  <jimm@io.com>
+
+	* lib/midilib/sequence.rb (Sequence::note_to_delta): created.
+	(Sequence::note_to_length): created.
+	(Sequence::length_to_delta): created.
+
+	* examples/from_scratch.rb: created.
+
+2004-07-16  Jim Menard  <jimm@io.com>
+
+	* Version 0.8.3 released.
+
+2004-07-10  Jim Menard  <jimm@io.com>
+
+	* lib/midilib/event.rb (NoteEvent::note_to_s): created.
+	(Event::number_to_s): created.
+	(Event): added @print_note_names and @print_decimal_numbers
+	attributes.
+	(to_s all classes): use @print_note_names and @print_decimal_numbers
+
+2004-06-30  Jim Menard  <jimm@io.com>
+
+	* Version 0.8.2 released.
+
+	* lib/midilib/event.rb (MetaEvent): changed @type to @meta_type to
+	avoid warnings like "Object#type is deprecated; use Object#class".
+
+	* lib/midilib/track.rb (Track::name): use Event.meta_type (renamed
+	from Event.type).
+	(Track::name=): use Event.meta_type (renamed from Event.type).
+
+	* test/event_equality.rb (MIDI::MetaEvent): use meta_type instead
+	of type.
+
+	* examples/transpose.rb: fixed $LOAD_PATH. Added 'b' to file open
+	modes for Windows.
+
+	* examples/strings.rb: fixed $LOAD_PATH. Fixed arguments passed to
+	read block. Fixed code that looks for meta events. Added 'b' to
+	file open modes for Windows.
+
+	* examples/seq2text.rb: fixed $LOAD_PATH. Fixed arguments passed
+	to read block. Added 'b' to file open modes for Windows.
+
+	* examples/reader2text.rb: fixed $LOAD_PATH. Fixed TextTranslator
+	superclass. Fixed arguments passed to read block. Added 'b' to
+	file open modes for Windows.
+
+	* lib/midilib/io/seqwriter.rb (SeqWriter::initialize): added block
+	rdoc comment.
+	(SeqWriter::write_to): added track to @update_block args.
+
+	* lib/midilib/io/seqreader.rb (SeqReader::initialize): added block
+	rdoc comment.
+
+2004-06-27  Jim Menard  <jimm@io.com>
+
+	* Version 0.8.1 released.
+
+	* test/test_event.rb: created.
+
+	* lib/midilib/track.rb: more documentation.
+	(Track::sort): sorts by events' time_from_start and modifies
+	@events (which wasn't happening before; I forgot to assign the
+	sorted results back to @events).
+	(Track::recalc_delta_from_times): fixed.
+	(Track::quantize): call recalc_delta_from_times.
+
+	* test/test_track.rb (TrackTester::test_sort): created.
+	(TrackTester::test_recalc_delta_from_times): created.
+
+	* lib/midilib/sequence.rb: more documentation.
+
+	* lib/midilib/consts.rb: hid some comments from RDoc.
+
+	* lib/midilib/event.rb: more documentation.
+	(Event::realtime): fix quantize_to so it changes the event's
+	time_from_start instead of delta_time.
+
+	* test/*.rb: removed redundant copyright and license notices.

data/Credits

@@ -0,0 +1,8 @@
+midilib is developed by Jim Menard, jimm@io.com. Additional bug fixes and
+suggestions have come from:
+
+Mike Hall <m3ha11@rcn.com>
+
+    Found errors in example scripts' $LOAD_PATH and a bug in sequence reading
+    block callback arguments. Found a bug in meta events that caused
+    "Object#type is deprecated" error messages.

data/README

@@ -0,0 +1,361 @@
+= midilib
+
+midilib is a pure Ruby MIDI library useful for reading and writing standard
+MIDI files and manipulating MIDI event data. Classes include MIDI::Sequence,
+MIDI::Track, MIDI::Event, and MIDI::IO::MIDIFile and its subclasses
+MIDI::IO::SeqReader and MIDI::IO::SeqWriter.
+
+The Web site of midilib is (http://midilib.rubyforge.org). The RubyForge
+project page is http://rubyforge.org/projects/midilib, where the latest
+version of midilib may be downloaded. midilib is also available as a RubyGem.
+
+
+=== Recent Changes
+
+==== Changes for 0.8.4:
+
+* Realtime status bytes now set @is_realtime to true and return true when
+  realtime? is called.
+
+* All system common events now set @is_system to true and return true when
+  system? is called, not just system exclusive events.
+
+* Added examples/from_scratch.rb, which shows how to create a sequence
+  manually.
+
+* New MIDI::Sequence methods that turn note length names like "32nd", "dotted
+  quarter", and "16th triplet" into delta times. See the docs below and
+  MIDI::Sequence::length_to_delta, MIDI::Sequence::note_to_length, and
+  MIDI::Sequence::note_to_delta.
+
+
+==== Changes for 0.8.3:
+
+* Added MIDI::NoteEvent.note_to_s, which returns note name as a string like
+  "C4" or "F#6".
+
+* Added new boolean attributes to MIDI::Event: @print_decimal_numbers and
+  @print_note_names. These are used by all Event to_s methods. See
+  examples/seq2text.rb for an example.
+
+==== Changes for 0.8.2:
+
+* Changed MIDI::MetaEvent.type to MIDI::MetaEvent.event_type to avoid
+  runtime complaints about Object#type calls.
+* Added 'b' binary flag to file open modes for Windows.
+* Fixed $LOAD_PATH in example files.
+* Fixed read and write block arguments.
+* Fixed other example script bugs.
+
+==== Changes for 0.8.1:
+
+* Fixed track sorting.
+* Fixed track's recalc_delta_from_times method.
+* Fixed event quantization.
+* More tests and documentation.
+
+
+== Dependencies
+
+midilib does not require any other packages. The test suite in the tests
+directory requires the testing framework TestUnit, which comes with Ruby 1.8
+and later and can also be found in the Ruby Application Archive
+(http://raa.ruby-lang.org).
+
+To rebuild the gem or RDocs or run the tests easily, you can use the Rakefile
+which requires Rake (http://rake.rubyforge.org).
+
+
+== Installation
+
+=== RubyGems Installation
+
+To install midilib as a gem, type
+
+    % gem install midilib
+
+You may need root privileges to install the gem.
+
+=== Manual Installation
+
+After downloading and expanding the archive, you can install midilib with the
+command
+
+    % ruby install.rb
+(or)
+    % ruby install.rb --install-dir=my_directory
+
+You may need root privileges to install.
+
+
+== Testing
+
+  % rake test
+
+runs all of the tests in the test directory.
+
+
+== Overview
+
+MIDI file IO only understands MIDI file format 1, where a sequence is made up
+of multiple tracks. It doesn't yet understand format 0 (a single track
+containing all events) or format 2 (a collection of format 0 files in one
+file).
+
+=== MIDI::Sequence
+
+A sequence contains a collection of tracks and global information like the
+sequence's pulses per quarter note (ppqn) and time signature.
+
+The first track in a sequence is special; it holds meta-events like tempo and
+sequence name. Don't put any notes in this track.
+
+MIDI::Sequence also contains some convenience methods that let you set and
+retrieve the sequence's name, the time signature, and to retrieve the first
+tempo event's beats-per-minute value.
+
+Normally instances of MIDI::IO::SeqReader and MIDI::IO::SeqWriter are used
+when a sequence reads itself from or writes itself to a MIDI file. You can
+change that by setting a sequence's reader_class or writer_class attributes.
+Instances of the classes contained in those attributes are created and used
+whenever the sequence reads or writes itself.
+
+=== MIDI::Track
+
+A track contains an array of events.
+
+When you modify the +events+ array, make sure to call recalc_times so each
+event gets its +time_from_start+ recalculated. You don't have to do that
+after every event you add; just remember to do so before using the track in a
+way that expects the list of events to be ordered correctly.
+
+A Track also holds a bit mask that specifies the channels used by the track.
+This bit mask is set when the track is read from the MIDI file by a SeqReader
+but is _not_ kept up to date by any other methods. Specifically, if you add
+events to a track at any other time, the bit mask will not be updated.
+
+=== MIDI::Event
+
+Each event holds not only its delta time but also its time from the start of
+the track. The track is responsible for recalculating its events' start times.
+You can call MIDI::Track#recalc_times to do so.
+
+Events have a number of boolean methods that identify their types, like
+channel?, note?, note_on?, note_off?, meta?, system?, and realtime?.
+
+Subclasses of MIDI::Event implement the various MIDI messages such as note on
+and off, controller values, system exclusive data, and realtime bytes.
+
+MIDI::Realtime events have delta values and start times, just like all the
+other midilib event types do. (MIDI real time status bytes don't have delta
+times, but this way we can record when in a track the realtime byte was
+received and should be sent. This is useful for start/continue/stop events
+that control other devices, for example.) Note that when a MIDI::Realtime
+event is written out to a MIDI file, the delta time is not written.
+
+
+== How To Use
+
+The following examples show you how to use midilib to read, write, and
+manipulate MIDI files and modify track events. See also the files in the
+examples directory, which are described below.
+
+
+=== Reading a MIDI File
+
+To read a MIDI file, create a MIDI::Sequence object and call its #read method,
+passing in an IO object.
+
+The #read method takes an optional block. If present, the block is called once
+after each track has finished being read. Each time, it is passed the total
+number of tracks and the number of the current track that has just been read.
+This is useful for notifying the user of progress, for example by updating a
+GUI progress bar.
+
+ require 'midi/io/seqreader'
+
+ # Create a new, empty sequence.
+ seq = MIDI::Sequence.new()
+
+ # Read the contents of a MIDI file into the sequence.
+ File.open('my_midi_file.mid', 'rb') { | file |
+     seq.read(file) { | num_tracks, i |
+         # Print something when each track is read.
+         puts "read track #{i} of #{num_tracks}"
+     }
+ }
+
+
+=== Writing a MIDI File
+
+To write a MIDI file, call the write method, passing in an IO object.
+
+
+ require 'midi/io/seqwriter'
+
+ # Start with a sequence that has something worth saving.
+ seq = read_or_create_seq_we_care_not_how()
+
+ # Write the sequence to a MIDI file.
+ File.open('my_output_file.mid', 'wb') { | file | seq.write(file) }
+
+
+=== Editing a MIDI File
+
+Combining the last two examples, here is a script that reads a MIDI file,
+transposes some events, and writes the sequence out to a different file. This
+is a useful template for programatically manipulating MIDI data.
+
+
+This code transposes all of the note events (note on, note off, and poly
+pressure) on channel 5 down one octave. It's easy to find events that need to
+be transposed: the method #note? returns true.
+
+==== Transposing One Channel
+
+ require 'midi/io/seqreader'
+ require 'midi/io/seqwriter'
+
+ # Create a new, empty sequence.
+ seq = MIDI::Sequence.new()
+
+ # Read the contents of a MIDI file into the sequence.
+ File.open('my_input_file.mid', 'rb') { | file |
+     seq.read(file) { | num_tracks, i |
+         # Print something when each track is read.
+         puts "read track #{i} of #{num_tracks}"
+     }
+ }
+
+ # Iterate over every event in every track.
+ seq.each { | track |
+     track.each { | event |
+         # If the event is a note event (note on, note off, or poly
+         # pressure) and it is on MIDI channel 5 (channels start at
+         # 0, so we use 4), then transpose the event down one octave.
+         if event.note? && event.channel == 4
+             event.note -= 12
+         end
+     }
+ }
+
+ # Write the sequence to a MIDI file.
+ File.open('my_output_file.mid', 'wb') { | file | seq.write(file) }
+
+
+=== Manipulating tracks
+
+If you modify a track's list of events directly, don't forget to call
+MIDI::Track#recalc_times when you are done.
+
+ track.events[42, 1] = array_of_events
+ track.events << an_event
+ track.merge(array_of_events)
+ track.recalc_times
+
+=== Calculating delta times
+
+A few methods in MIDI::Sequence make it easier to calculate the delta times
+that represent note lengths. MIDI::Sequence#length_to_delta takes a note
+length (a multiple of a quarter note) and returns the delta time given the
+sequence's current ppqn (pulses per quarter note) setting. 1 is a quarter
+note, 1.0/32.0 is a 32nd note (use floating-point numbers to avoid integer
+rounding), 1.5 is a dotted quarter, etc. See the documentation for that method
+for more information.
+
+MIDI::Sequence::note_to_length takes a note name and returns a length value
+(again, as a multiple of a quarter note). Legal note names are those found in
+MIDI::Sequence::NOTE_TO_LENGTH, and may begin with "dotted" and/or end with
+"triplet". For example, "whole", "sixteenth", "32nd", "quarter triplet",
+"dotted 16th", and "dotted 8th triplet" are all legal note names.
+
+Finally, MIDI::Sequence::note_to_delta takes a note name and returns a
+delta time.
+
+
+=== Example Scripts
+
+Here are short descriptions of each of the examples found in the examples
+directory.
+
+* examples/from_scratch.rb shows you how to create a new sequence from scratch
+  and save it to a MIDI file. It creates a file called 'from_scratch.mid'.
+
+* examples/seq2text.rb dumps a MIDI file as text. It reads in a sequence and
+  uses the to_s method of each event.
+
+* examples/reader2text.rb dumps a MIDI file as text. It subclasses
+  MIDI::SeqReader instead of creating a sequence containing tracks and events.
+
+* examples/transpose.rb transposes all note events (note on, note off, poly
+  pressure) on a specified channel by a specified amount.
+
+* There is also one MIDI file, examples/NoFences.mid. It is a little pop ditty
+  I wrote. The instruments in this file use General MIDI patch numbers and
+  drum note assignments. Since I don't normally use GM patches, the sounds
+  used here are at best approximations of the sounds I use.
+
+
+== Resources
+
+The Ruby Web site (http://www.ruby-lang.org/en/index.html) contains an
+introduction to Ruby, the Ruby Application Archive (RAA) at
+http://raa.ruby-lang.org, and pointers to more information.
+
+
+<em>Programming Ruby, The Pragmatic Programmer's Guide<em>, by David Thomas
+and Andrew Hunt, is a well-written and practical introduction to Ruby. Its Web
+page at http://www.rubycentral.com/book also contains a wealth of Ruby
+information. Though the book is available online, I encourage you to purchase
+a copy.
+
+A description of the MIDI file format can be found in a few places such as
+http://www.borg.com/~jglatt/tech/midifile.htm.
+
+The MIDI message reference at http://www.io.com/~jimm/midi_ref.html describes
+the format of MIDI commands.
+
+
+= To Do
+
+:include: TODO
+
+
+= Support
+
+* Visit the forums, bug list, and mailing list pages at
+  http://rubyforge.org/projects/midilib
+
+* Send email to Jim Menard at mailto:jimm@io.com
+
+* Ask on the ruby-talk mailing list
+
+
+= Administrivia
+
+Author:: Jim Menard (mailto:jimm@io.com)
+Copyright:: Copyright (c) 2003-2004 Jim Menard
+License:: Distributed under the same license as Ruby.
+
+
+== Copying
+
+midilib is copyrighted free software by Jim Menard and is released under the
+same license as Ruby. See the Ruby license at
+http://www.ruby-lang.org/en/LICENSE.txt.
+
+midilib may be freely copied in its entirety providing this notice, all
+source code, all documentation, and all other files are included.
+
+midilib is Copyright (c) 2003-2004 by Jim Menard.
+
+The song "No Fences" contained in the MIDI file examples/NoFences.mid is
+Copyright (c) 1992 by Jim Menard (jimm@io.com). It may be freely used for
+non-commercial purposes as long as the author is given credit.
+
+
+== Warranty
+
+This software is provided "as is" and without any express or implied
+warranties, including, without limitation, the implied warranties of
+merchantability and fitness for a particular purpose.