stretto 0.6.1

data/lib/stretto/music_elements/controller_change.rb

@@ -0,0 +1,49 @@
+require File.join(File.dirname(__FILE__), 'music_element')
+
+module Stretto
+  module MusicElements
+
+    # Represents a MIDI controller event.
+    #
+    # MIDI specification defines about 100 controller events, that are used by the
+    # instruments or synthesizer to perform a range of effects and control settings.
+    #
+    # JFugue defines the most common ones (See {Variables::CONTROLLER_VARIABLES}),
+    # and provides a shortcut for mixed (coarse and fine values) controllers.
+    #
+    # The syntax for a controller change is X_controller_=_value_, where controller is the
+    # number of the controller event, and value is the value that is going to be set.
+    class ControllerChange < MusicElement
+
+      attr_reader :controller, :value
+
+      def initialize(string_or_options, pattern = nil)
+        token = case string_or_options
+          when String then Stretto::Parser.parse_controller_change!(string_or_options)
+          else string_or_options
+        end
+        super(token[:text_value], pattern)
+        @original_controller = token[:controller]
+        @original_value      = token[:value]
+      end
+
+      def controller
+        @controller || @original_controller.to_i(@pattern)
+      end
+
+      def value
+        @value || @original_value.to_i(@pattern)
+      end
+
+      private
+
+        # @private
+        def substitute_variables!
+          @controller = @original_controller.to_i(@pattern)
+          @value      = @original_value.to_i(@pattern)
+        end
+
+    end
+
+  end
+end

data/lib/stretto/music_elements/harmonic_chord.rb

@@ -0,0 +1,56 @@
+require File.join(File.dirname(__FILE__), 'music_element')
+require File.join(File.dirname(__FILE__), 'chord')
+
+module Stretto
+  module MusicElements
+
+    # Represents a non-regular chord (see {Chord})
+    #
+    # A harmonic chord can be specied by joining notes, or even chords, together with
+    # the <tt>+</tt> symbol. For example, the chord <tt>C+E+G</tt> is the same as the chord
+    # +Cmaj+, and the chord <tt>C+D+E</tt> is an irregular chord (not included in the
+    # standard named chords) which will have the notes +C+, +D+ and +E+. Note that as
+    # the notes are specified by their note notation, the default octave is 5, instead of
+    # 3 as the normal chords.
+    class HarmonicChord < Chord
+
+      def initialize(string_or_options, pattern = nil)
+        token = case string_or_options
+          when String then Stretto::Parser.parse_harmonic_chord!(string_or_options)
+          else string_or_options
+        end
+        super(token, pattern)
+        @notes = normalize_notes(@notes)
+      end
+
+      # @return (see Chord#elements)
+      def elements
+        notes
+      end
+
+      # @return (see Chord#elements)
+      def duration
+        @notes.map(&:duration).max
+      end
+
+      # @private
+      def substitute_variables!
+        @duration        = @notes.map(&:duration).max
+        @notes.each{ |note| note.pattern = @pattern }
+      end
+
+      # Builds the +@notes+ instance variable, flattening the notes
+      # and the notes in a chord into a single array of elements
+      def normalize_notes(base_notes)
+        base_notes.inject([]) do |notes, element|
+          element.pattern = @pattern
+          case element
+            when Note   then notes << element
+            when Chord  then notes + element.notes
+          end
+        end.uniq
+      end
+
+    end
+  end
+end

data/lib/stretto/music_elements/harmony.rb

@@ -0,0 +1,37 @@
+require File.join(File.dirname(__FILE__), 'music_element')
+
+module Stretto
+  module MusicElements
+
+    # Represents a group of notes, chords and rests of different lengths
+    # that should play together.
+    #
+    # It is similar to a HarmonicChord (see {HarmonicChord} with the difference
+    # that it can also include rests and melodies (see {Melody})
+    class Harmony < MusicElement
+
+      attr_accessor :elements
+
+      def initialize(string_or_options, pattern = nil)
+        token = case string_or_options
+          when String then Stretto::Parser.parse_harmony!(string_or_options)
+          else string_or_options
+        end
+        super(token[:text_value], pattern)
+        @elements = token[:music_elements]
+      end
+
+      # @return (see HarmonicChord#duration)
+      def duration
+        @elements.map(&:duration).max
+      end
+
+      # @return (see HarmonicChord#pattern=)
+      def pattern=(pattern)
+        @elements.each { |element| element.pattern = pattern }
+      end
+
+    end
+
+  end
+end

data/lib/stretto/music_elements/instrument.rb

@@ -0,0 +1,57 @@
+require File.join(File.dirname(__FILE__), 'music_element')
+
+module Stretto
+  module MusicElements
+
+    # Represent an instrument change by the MIDI specification.
+    #
+    # The sound played depends on the soundbank installed by
+    # the synthesizer, the MIDI standard defines 128 standard instruments
+    # (see {Variables::INSTRUMENT_VARIABLES}) that are reflected by
+    # JFugue with predefined variables.
+    class Instrument < MusicElement
+
+      MAX_INSTRUMENT_VALUE = 127
+
+      # Returns an instrument with value 0 (piano)
+      def self.default_instrument(pattern = nil)
+        params = {
+          :text_value => '',
+          :value => Value.new(Value::NumericValue.new(0))
+        }
+        new(params, pattern)
+      end
+
+      def initialize(string_or_options, pattern = nil)
+        token = case string_or_options
+          when String then Stretto::Parser.parse_instrument!(string_or_options)
+          else string_or_options
+        end
+        super(token[:text_value], pattern )
+        @original_value = token[:value]
+      end
+
+      # Sets and validates value (0...127)
+      def value=(value)
+        if value < 0 or value > MAX_INSTRUMENT_VALUE
+          raise Exceptions::ValueOutOfBoundsException.new("Instrument value should be in range 0..#{MAX_INSTRUMENT_VALUE}")
+        end
+        @value = value
+      end
+
+      # @return [Number] Returns or calculates the value for the
+      #   instrument
+      def value
+        @value || @original_value.to_i(@pattern)
+      end
+
+      private
+      
+        def substitute_variables!
+          self.value = value
+        end
+
+    end
+
+  end
+end

data/lib/stretto/music_elements/key_signature.rb

@@ -0,0 +1,110 @@
+require File.join(File.dirname(__FILE__), 'music_element')
+
+module Stretto
+  module MusicElements
+
+    # A key signature indicates the channel to play in the indicated key or scale.
+    #
+    # This increases or decreases note values for certain notes, according to music theory
+    # (see http://en.wikipedia.org/wiki/Key_signature). The key signature is specified by the
+    # letter +K+, followed by a key (for example +C+, +D#+ or +Eb+) and the scale (+maj+ or
+    # +min+)
+    #
+    # Note that notes and chords specified with a pitch value will not be affected. That is,
+    # given the following pattern "KGmaj F [65]", the first note will raise its pitch to
+    # 66 (due to the sharp accidental in the F notes), while the second note will keep its
+    # given value of 65
+    class KeySignature < MusicElement
+
+      attr_reader :key, :scale
+
+      def initialize(string_or_options, pattern = nil)
+        token = case string_or_options
+          when String then Stretto::Parser.parse_key_signature!(string_or_options)
+          else string_or_options
+        end
+        super(token[:text_value], pattern)
+        @key = normalize_keysig(token[:key])
+        @scale = SCALES[token[:scale].downcase]
+      end
+
+      # @return [Number] +1, 0 or -1, if the note key has a flat, none or sharp accidental
+      #   respectively for the given +note_key+
+      def modifier_for(note_key)
+        MODIFIERS[@scale][@key][note_key]
+      end
+
+      private
+
+        MODIFIERS = {
+          :major => {
+            'C'   => {},
+            'G'   => { 'F' => +1 },
+            'D'   => { 'F' => +1, 'C' => +1 },
+            'A'   => { 'F' => +1, 'C' => +1, 'G' => +1 },
+            'E'   => { 'F' => +1, 'C' => +1, 'G' => +1, 'D' => +1 },
+            'B'   => { 'F' => +1, 'C' => +1, 'G' => +1, 'D' => +1, 'A' => +1 },
+            'F#'  => { 'F' => +1, 'C' => +1, 'G' => +1, 'D' => +1, 'A' => +1, 'E' => +1},
+            'C#'  => { 'F' => +1, 'C' => +1, 'G' => +1, 'D' => +1, 'A' => +1, 'E' => +1, 'B' => +1 },
+
+            'F'   => { 'B' => -1 },
+            'Bb'  => { 'B' => -1, 'E' => -1 },
+            'Eb'  => { 'B' => -1, 'E' => -1, 'A' => -1 },
+            'Ab'  => { 'B' => -1, 'E' => -1, 'A' => -1, 'D' => -1 },
+            'Db'  => { 'B' => -1, 'E' => -1, 'A' => -1, 'D' => -1, 'G' => -1 },
+            'Gb'  => { 'B' => -1, 'E' => -1, 'A' => -1, 'D' => -1, 'G' => -1, 'C' => -1 },
+            'Cb'  => { 'B' => -1, 'E' => -1, 'A' => -1, 'D' => -1, 'G' => -1, 'C' => -1, 'F' => -1},
+          },
+          :minor => {
+            'A'   => {},
+            'E'   => { 'F' => +1 },
+            'B'   => { 'F' => +1, 'C' => +1 },
+            'F#'  => { 'F' => +1, 'C' => +1, 'G' => +1 },
+            'C#'  => { 'F' => +1, 'C' => +1, 'G' => +1, 'D' => +1 },
+            'G#'  => { 'F' => +1, 'C' => +1, 'G' => +1, 'D' => +1, 'A' => +1 },
+            'D#'  => { 'F' => +1, 'C' => +1, 'G' => +1, 'D' => +1, 'A' => +1, 'E' => +1},
+            'A#'  => { 'F' => +1, 'C' => +1, 'G' => +1, 'D' => +1, 'A' => +1, 'E' => +1, 'B' => +1 },
+            'D'   => { 'B' => -1 },
+            'G'   => { 'B' => -1, 'E' => -1 },
+            'C'   => { 'B' => -1, 'E' => -1, 'A' => -1 },
+            'F'   => { 'B' => -1, 'E' => -1, 'A' => -1, 'D' => -1 },
+            'Bb'  => { 'B' => -1, 'E' => -1, 'A' => -1, 'D' => -1, 'G' => -1 },
+            'Eb'  => { 'B' => -1, 'E' => -1, 'A' => -1, 'D' => -1, 'G' => -1, 'C' => -1 },
+            'Ab'  => { 'B' => -1, 'E' => -1, 'A' => -1, 'D' => -1, 'G' => -1, 'C' => -1, 'F' => -1},
+          }
+        }
+
+        # ALIASES IN MAJOR SCALE
+        MODIFIERS[:major]['Fb'] = MODIFIERS[:major]['E' ]
+        MODIFIERS[:major]['Cb'] = MODIFIERS[:major]['B' ]
+        MODIFIERS[:major]['Gb'] = MODIFIERS[:major]['F#']
+        MODIFIERS[:major]['Db'] = MODIFIERS[:major]['C#']
+        MODIFIERS[:major]['B#'] = MODIFIERS[:major]['C' ]
+
+        # EQUIVALENCES FROM MAJOR SCALE TO MINOR SCALE
+        MODIFIERS[:major]['G#'] = MODIFIERS[:major]['Ab'] = MODIFIERS[:minor]['F' ]
+        MODIFIERS[:major]['D#'] = MODIFIERS[:major]['Eb'] = MODIFIERS[:minor]['C' ]
+        MODIFIERS[:major]['A#'] = MODIFIERS[:major]['Bb'] = MODIFIERS[:minor]['G' ]
+        MODIFIERS[:major]['E#'] = MODIFIERS[:major]['F' ] = MODIFIERS[:minor]['D' ]
+
+        # ALIASES IN MINOR SCALE
+        MODIFIERS[:minor]['B#'] = MODIFIERS[:minor]['C' ]
+        MODIFIERS[:minor]['E#'] = MODIFIERS[:minor]['F' ]
+        MODIFIERS[:minor]['A#'] = MODIFIERS[:minor]['Bb']
+        MODIFIERS[:minor]['D#'] = MODIFIERS[:minor]['Eb']
+        MODIFIERS[:minor]['G#'] = MODIFIERS[:minor]['Ab']
+
+        # EQUIVALENCES FROM MINOR SCALE TO MAJOR SCALE
+        MODIFIERS[:minor]['Db'] = MODIFIERS[:minor]['C#'] = MODIFIERS[:major]['E' ]
+        MODIFIERS[:minor]['Gb'] = MODIFIERS[:minor]['F#'] = MODIFIERS[:major]['A' ]
+        MODIFIERS[:minor]['Cb'] = MODIFIERS[:minor]['B' ] = MODIFIERS[:major]['D' ]
+        MODIFIERS[:minor]['Fb'] = MODIFIERS[:minor]['E' ] = MODIFIERS[:major]['G' ] 
+
+        SCALES = { 'maj' => :major, 'min' => :minor }
+
+        def normalize_keysig(string)
+          string.downcase.sub(/\w/){ |initial| initial.upcase }
+        end
+    end
+  end
+end

data/lib/stretto/music_elements/layer.rb

@@ -0,0 +1,22 @@
+module Stretto
+
+  # Wrapper for a layer: set of elements inside a voice
+  #
+  # Layers are not part of the MIDI specification, but are
+  # a resource to separate multiple notes that should be played
+  # together in a voice.
+  #
+  # This is most useful in the voice 9 (see {Voice}), which is
+  # the percussion layer. Different parts of the percussion track
+  # can be separated in different layers, and they all play together
+  # in the same track.
+  class Layer < Array
+
+    # @return [Array(MusicElement)] Its elements as an array
+    def elements
+      to_a
+    end
+
+  end
+  
+end

data/lib/stretto/music_elements/layer_change.rb

@@ -0,0 +1,39 @@
+require File.join(File.dirname(__FILE__), 'music_element')
+
+module Stretto
+  module MusicElements
+
+    class LayerChange < MusicElement
+
+      MAX_LAYERS = 15
+
+      attr_reader :index
+
+      def initialize(string_or_options, pattern = nil)
+        token = case string_or_options
+          when String then Stretto::Parser.parse_layer_change!(string_or_options)
+          else string_or_options
+        end
+        super(token[:text_value], pattern)
+        @original_value = token[:value]
+      end
+
+      def index
+        @index || @original_value.to_i(@pattern)
+      end
+
+      def index=(index)
+        if index < 0 or index > MAX_LAYERS
+          raise Exceptions::ValueOutOfBoundsException.new("Layer value should be in range 0..#{MAX_LAYERS}")
+        end
+        @index = index
+      end
+
+      def substitute_variables!
+        self.index = index
+      end
+
+    end
+
+  end
+end

data/lib/stretto/music_elements/measure.rb

@@ -0,0 +1,38 @@
+require File.join(File.dirname(__FILE__), 'music_element')
+
+module Stretto
+  module MusicElements
+
+    # Does not have effect in the playback, it represents a measure
+    # for readability of the music texts
+    class Measure < MusicElement
+
+      def initialize(string_or_options, pattern = nil)
+        token = case string_or_options
+          when String then Stretto::Parser.parse_measure!(string_or_options)
+          else string_or_options
+        end
+        super(token[:text_value], pattern)
+      end
+      
+      # @private
+      # TODO: Make tests for other elements inside ties, move this to MusicElement
+      def tied_elements
+        next_element = self.next
+        if next_element
+          next_element.tied_elements
+        else
+          []
+        end
+      end
+
+      # @private
+      # TODO: Make tests for other elements inside ties, move this to MusicElement
+      def tied_duration
+        tied_elements.inject(0){|sum, element| sum + element.duration}
+      end
+
+    end
+
+  end
+end

data/lib/stretto/music_elements/melody.rb

@@ -0,0 +1,72 @@
+require File.join(File.dirname(__FILE__), 'music_element')
+
+module Stretto
+  module MusicElements
+
+    # A set of elements that should play sequentially. The elements are separated
+    # by underscores, for example <tt>C_D_E</tt>
+    #
+    # A melody alone would be the equivalent to play the elements of it separately,
+    # but it is useful to indicate explicitely a melody when used in harmonies
+    # (see {Harmony}). For example, a harmony (C_D+E_Fmaj) will play at the same time
+    # +C+ + +E+ for one quarter of a whole note, then +D+ and +Fmaj+ will play together. 
+    class Melody < MusicElement
+
+      attr_reader :elements
+
+      def initialize(array_or_hash, pattern = nil)
+        options = _handle_initial_argument(array_or_hash)
+        _verify_is_pattern(pattern)
+        @elements = options[:elements]
+        super(options[:original_string], pattern)
+      end
+
+      # Returns the sum of the duration of its elements
+      def duration
+        @elements.map(&:duration).sum
+      end
+
+      # Adds an element to the melody, additionally setting its pattern
+      # (see {MusicElement::pattern=)
+      def <<(element)
+        @elements << element
+        element.pattern = @pattern if @pattern
+      end
+
+      private
+
+        # @private
+        # Builds the set of elements based on what the constructor is (a token,
+        # an array of elements or a single MusicElement (in which case, a melody
+        # with just one element is created.)
+        def _handle_initial_argument(array_hash_or_music_element)
+          arg = array_hash_or_music_element
+          case arg
+            when Array
+              unless arg.present? and arg.all? { |element| element.kind_of?(MusicElement) }
+                raise ArgumentError.new("First argument should be either a MusicElement or an array of at least one MusicElement")
+              end
+              { :elements   => arg,
+                :original_string => arg.map(&:original_string).join('_')
+              }
+            when Hash
+              arg
+            when MusicElement
+              { :elements   => [arg],
+                :original_string => arg.original_string
+              }
+            else raise ArgumentError.new("First argument should be either a MusicElement or an array of MusicElements")
+          end
+        end
+
+        # @private
+        # Verifies that the second parameter in initializer is a {Pattern}
+        def _verify_is_pattern(pattern)
+          if pattern and !pattern.kind_of?(Pattern)
+            raise ArgumentError.new("Second argument should be a Pattern object or nil")
+          end
+        end
+
+    end
+  end
+end