clef 0.1.0 → 1.0.0

data/lib/clef/midi/exporter.rb

@@ -8,73 +8,351 @@ module Clef
     class Exporter
       include MIDI
 
+      DEFAULT_VELOCITY = 90
+      DEFAULT_PROGRAM = 1
+
+      attr_reader :score, :channel_map, :ppqn, :instrument_map, :plugins
+
       # @param score [Clef::Core::Score]
       # @param channel_map [ChannelMap]
-      def initialize(score, channel_map: ChannelMap.new)
+      # @param ppqn [Integer]
+      # @param instrument_map [Hash]
+      # @param plugins [Clef::Plugins::Registry]
+      def initialize(score, channel_map: ChannelMap.new, ppqn: 480, instrument_map: {}, plugins: score.plugins || Clef.plugins)
+        raise ArgumentError, "ppqn must be a positive Integer" unless ppqn.is_a?(Integer) && ppqn.positive?
+
         @score = score
         @channel_map = channel_map
+        @ppqn = ppqn
+        @instrument_map = instrument_map
+        @plugins = plugins
+      end
+
+      # @param target [String, #write]
+      # @return [String, #write]
+      def export(target)
+        plugins.run_hook(:on_before_midi, self)
+        sequence = build_sequence
+        write_sequence(sequence, target)
+        target
       end
 
-      # @param path [String]
-      # @return [String]
-      def export(path)
+      private
+
+      def build_sequence
         sequence = Sequence.new
+        sequence.ppqn = ppqn
+        append_tempo_track(sequence)
+        append_staff_tracks(sequence)
+        sequence
+      end
+
+      def append_tempo_track(sequence)
         track = Track.new(sequence)
         sequence.tracks << track
-        track.events << Tempo.new(Tempo.bpm_to_mpq(tempo_bpm))
+        last_tick = write_tempo_events(track)
+        append_track_end(track, score_length, last_tick)
+      end
 
-        append_score(track, sequence.ppqn)
-        File.open(path, "wb") { |file| sequence.write(file) }
-        path
+      def append_staff_tracks(sequence)
+        score.staves.each_with_index do |staff, index|
+          track = Track.new(sequence)
+          sequence.tracks << track
+          channel = channel_for(staff, index)
+          track.events << ProgramChange.new(channel, instrument_for(staff), 0)
+          append_staff(track, staff, channel)
+        end
       end
 
-      private
+      def append_staff(track, staff, channel)
+        note_events = collect_staff_note_events(staff, channel)
+        last_tick = write_delta_events(track, note_events)
+        append_track_end(track, staff_length(staff), last_tick)
+      end
 
-      def append_score(track, ppqn)
-        @score.staves.each_with_index do |staff, index|
-          channel = @channel_map.channel_for(index)
-          track.events << ProgramChange.new(channel, 1, 0)
-          append_staff(track, staff, channel, ppqn)
+      def collect_staff_note_events(staff, channel)
+        starts = measure_starts(staff)
+        staff.measures.flat_map { |measure| measure.voices.keys }.uniq.flat_map do |voice_id|
+          pending_ties = {}
+          playback_state = {velocity: DEFAULT_VELOCITY, slur_depth: 0}
+          events = starts.flat_map do |measure, measure_start|
+            voice = measure.voices[voice_id]
+            next [] unless voice
+
+            collect_voice_events(voice, measure_start, channel,
+              pending_ties: pending_ties,
+              playback_state: playback_state,
+              flush_ties: false)
+          end
+          events + flush_pending_ties(pending_ties, channel)
         end
       end
 
-      def append_staff(track, staff, channel, ppqn)
-        delta = 0
-        staff.measures.each do |measure|
-          voice = measure.voices.values.first
-          delta = append_voice(track, voice, channel, ppqn, delta) if voice
+      def collect_voice_events(voice, start_time, channel, pending_ties: {}, playback_state: {velocity: DEFAULT_VELOCITY}, flush_ties: true)
+        events, = collect_elements(voice.elements, start_time, channel, Rational(1, 1), pending_ties, playback_state,
+          flush_ties: flush_ties)
+        events
+      end
+
+      def collect_elements(elements, start_time, channel, ratio, pending_ties, playback_state, flush_ties:)
+        cursor = start_time
+        events = []
+        elements.each do |element|
+          case element
+          when Clef::Core::Rest
+            cursor += element.length * ratio
+          when Clef::Core::Note
+            events.concat(schedule_note(element, cursor, channel, ratio, pending_ties, playback_state))
+            advance_slur_state(element, playback_state)
+            cursor += element.length * ratio
+          when Clef::Core::Chord
+            events.concat(schedule_chord(element, cursor, channel, ratio, playback_state))
+            cursor += element.length * ratio
+          when Clef::Core::Tuplet
+            nested_events, = collect_elements(element.elements, cursor, channel, ratio * element.ratio,
+              pending_ties, playback_state, flush_ties: false)
+            events.concat(nested_events)
+            cursor += element.length * ratio
+          when Clef::Notation::Dynamic
+            playback_state[:velocity] = velocity_for_dynamic(element)
+          when Clef::Core::Tempo
+            cursor += element.length
+          end
         end
+        events.concat(flush_pending_ties(pending_ties, channel)) if flush_ties
+        [events, cursor]
       end
 
-      def append_voice(track, voice, channel, ppqn, delta)
-        voice.elements.each do |element|
-          delta = append_element(track, element, channel, ppqn, delta)
+      def schedule_note(note, start_time, channel, ratio, pending_ties, playback_state)
+        duration = note.length * ratio
+        midi = note.pitch.to_midi
+        if note.tie_state == :start || note.tie_state == :continue
+          pending = pending_ties[midi] ||= {
+            start_time: start_time,
+            duration: Rational(0, 1),
+            note: note,
+            velocity: playback_state[:velocity]
+          }
+          pending[:duration] += duration
+          return []
+        end
+
+        if note.tie_state == :stop && pending_ties.key?(midi)
+          pending = pending_ties.delete(midi)
+          pending[:duration] += duration
+          return [note_event(pending[:note], pending[:start_time], pending[:duration], channel, pending[:velocity])]
         end
-        delta
+
+        [note_event(note, start_time, effective_note_length(note, duration,
+          slurred: legato_slur_note?(note, playback_state)), channel, playback_state[:velocity])]
       end
 
-      def append_element(track, element, channel, ppqn, delta)
-        ticks = (element.length * ppqn * 4).to_i
-        return delta + ticks if element.is_a?(Clef::Core::Rest)
+      def schedule_chord(chord, start_time, channel, ratio, playback_state)
+        duration = chord.length * ratio
+        chord.pitches.map do |pitch|
+          {start_time: start_time, duration: duration, pitch: pitch.to_midi,
+           velocity: playback_state[:velocity], channel: channel}
+        end
+      end
+
+      def flush_pending_ties(pending_ties, channel)
+        pending_ties.values.map do |pending|
+          note_event(pending[:note], pending[:start_time], pending[:duration], channel, pending[:velocity])
+        end.tap { pending_ties.clear }
+      end
 
-        pitches = element.is_a?(Clef::Core::Chord) ? element.pitches : [element.pitch]
-        write_note_events(track, channel, pitches, ticks, delta)
-        0
+      def note_event(note, start_time, duration, channel, base_velocity)
+        {
+          start_time: start_time,
+          duration: duration,
+          pitch: note.pitch.to_midi,
+          velocity: velocity_for(note, base_velocity),
+          channel: channel
+        }
       end
 
-      def write_note_events(track, channel, pitches, ticks, delta)
-        pitches.each_with_index do |pitch, index|
-          note_delta = index.zero? ? delta : 0
-          track.events << NoteOn.new(channel, pitch.to_midi, 90, note_delta)
+      def write_delta_events(track, note_events)
+        absolute_events = note_events.flat_map do |event|
+          start_tick = ticks_for(event[:start_time])
+          end_tick = ticks_for(event[:start_time] + event[:duration])
+          [
+            [start_tick, 1, NoteOn.new(event[:channel], event[:pitch], event[:velocity], 0)],
+            [end_tick, 0, NoteOff.new(event[:channel], event[:pitch], event[:velocity], 0)]
+          ]
+        end.sort_by { |tick, priority, _event| [tick, priority] }
+
+        previous_tick = 0
+        absolute_events.each do |tick, _priority, event|
+          event.delta_time = tick - previous_tick
+          track.events << event
+          previous_tick = tick
         end
-        pitches.each_with_index do |pitch, index|
-          note_delta = index.zero? ? ticks : 0
-          track.events << NoteOff.new(channel, pitch.to_midi, 90, note_delta)
+        previous_tick
+      end
+
+      def effective_note_length(note, duration, slurred: false)
+        return duration * Rational(1, 2) if note.articulations.include?(:staccato)
+        return duration * Rational(19, 20) if note.articulations.include?(:tenuto)
+        return duration * Rational(101, 100) if slurred
+
+        duration
+      end
+
+      def legato_slur_note?(note, playback_state)
+        (playback_state.fetch(:slur_depth, 0).positive? || note.slur_start) && !note.slur_end
+      end
+
+      def advance_slur_state(note, playback_state)
+        depth = playback_state.fetch(:slur_depth, 0)
+        depth += 1 if note.slur_start
+        depth -= 1 if note.slur_end && depth.positive?
+        playback_state[:slur_depth] = depth
+      end
+
+      def velocity_for(note, base_velocity)
+        return 112 if note.articulations.include?(:accent) || note.articulations.include?(:marcato)
+
+        base_velocity
+      end
+
+      def velocity_for_dynamic(dynamic)
+        {
+          pp: 36,
+          p: 48,
+          mp: 64,
+          mf: 80,
+          f: 96,
+          ff: 112,
+          fff: 120,
+          sfz: 120,
+          fp: 96,
+          cresc: 88,
+          dim: 64
+        }.fetch(dynamic.type)
+      end
+
+      def write_tempo_events(track)
+        events = ([[Rational(0, 1), quarter_note_bpm]] + collect_score_tempo_events)
+          .uniq { |time, _bpm| time }
+          .sort_by(&:first)
+        previous_tick = 0
+        events.each do |time, bpm|
+          tick = ticks_for(time)
+          event = Tempo.new(Tempo.bpm_to_mpq(bpm))
+          event.delta_time = tick - previous_tick
+          track.events << event
+          previous_tick = tick
         end
+        previous_tick
       end
 
-      def tempo_bpm
-        @score.tempo&.bpm || 120
+      def append_track_end(track, length, previous_tick)
+        tick = ticks_for(length)
+        track.events << MetaEvent.new(META_TRACK_END, nil, tick - previous_tick)
+      end
+
+      def collect_score_tempo_events
+        score.staves.flat_map do |staff|
+          measure_starts(staff).flat_map do |measure, measure_start|
+            events = measure.voices.values.flat_map { |voice| collect_tempo_events(voice.elements, measure_start, Rational(1, 1)) }
+            events
+          end
+        end
+      end
+
+      def measure_starts(staff)
+        measure_start = Rational(0, 1)
+        staff.measures.map do |measure|
+          [measure, measure_start].tap do
+            measure_start += measure_length_for(measure)
+          end
+        end
+      end
+
+      def collect_tempo_events(elements, start_time, ratio)
+        cursor = start_time
+        elements.flat_map do |element|
+          case element
+          when Clef::Core::Rest, Clef::Core::Note, Clef::Core::Chord
+            cursor += element.length * ratio
+            []
+          when Clef::Core::Tuplet
+            nested = collect_tempo_events(element.elements, cursor, ratio * element.ratio)
+            cursor += element.length * ratio
+            nested
+          when Clef::Core::Tempo
+            [[cursor, tempo_to_quarter_bpm(element)]]
+          else
+            []
+          end
+        end
+      end
+
+      def ticks_for(time)
+        (time * ppqn * 4).round
+      end
+
+      def measure_length_for(measure)
+        return measure.time_signature.measure_length if measure.time_signature
+
+        measure.voices.values.map(&:total_length).max || Rational(0, 1)
+      end
+
+      def staff_length(staff)
+        staff.measures.sum { |measure| measure_length_for(measure) }
+      end
+
+      def score_length
+        score.staves.map { |staff| staff_length(staff) }.max || Rational(0, 1)
+      end
+
+      def quarter_note_bpm
+        tempo = score.tempo
+        return 120 unless tempo
+
+        tempo_to_quarter_bpm(tempo)
+      end
+
+      def tempo_to_quarter_bpm(tempo)
+        (tempo.bpm * (tempo.beat_unit.length / Clef::Core::Duration.quarter.length)).round
+      end
+
+      def channel_for(staff, index)
+        channel_map.channel_for(index, percussion: staff.clef.type == :percussion)
+      end
+
+      def instrument_for(staff)
+        program = instrument_map.fetch(staff.id) do
+          instrument_map.fetch(index_key(staff)) do
+            staff.metadata.fetch(:midi_program) { staff.metadata.fetch(:program, DEFAULT_PROGRAM) }
+          end
+        end
+        validate_program!(program)
+        program
+      end
+
+      def index_key(staff)
+        score.staves.index(staff)
+      end
+
+      def validate_program!(program)
+        return if program.is_a?(Integer) && (0..127).cover?(program)
+
+        raise ArgumentError, "MIDI program must be an Integer between 0 and 127"
+      end
+
+      def write_sequence(sequence, target)
+        return sequence.write(target) if target.respond_to?(:write)
+
+        ensure_parent_directory!(target)
+        File.open(target, "wb") { |file| sequence.write(file) }
+      end
+
+      def ensure_parent_directory!(path)
+        parent = File.dirname(path.to_s)
+        return if parent.nil? || parent == "." || Dir.exist?(parent)
+
+        raise ArgumentError, "output directory does not exist: #{parent}"
       end
     end
   end

data/lib/clef/notation/dynamic.rb

@@ -13,6 +13,11 @@ module Clef
 
         @type = type
       end
+
+      # @return [Rational]
+      def length
+        Rational(0, 1)
+      end
     end
   end
 end

data/lib/clef/notation/lyric.rb

@@ -3,6 +3,9 @@
 module Clef
   module Notation
     class Lyric
+      HYPHEN = "--"
+      EXTENDER = "_"
+
       attr_reader :voice_id, :text, :syllables
 
       # @param voice_id [Symbol]
@@ -15,14 +18,43 @@ module Clef
         @syllables = parse_syllables(text)
       end
 
+      # @return [Integer]
+      def note_slot_count
+        syllables.count { |syllable| self.class.note_syllable?(syllable) }
+      end
+
+      # @param syllable [String]
+      # @return [Boolean]
+      def self.note_syllable?(syllable)
+        syllable != HYPHEN
+      end
+
+      # @param syllable [String]
+      # @return [Boolean]
+      def self.hyphen?(syllable)
+        syllable == HYPHEN
+      end
+
+      # @param syllable [String]
+      # @return [Boolean]
+      def self.extender?(syllable)
+        syllable == EXTENDER
+      end
+
       private
 
       def parse_syllables(input)
         input
           .split(/\s+/)
-          .flat_map { |token| token.split("-") }
+          .flat_map { |token| lyric_token_parts(token) }
           .reject(&:empty?)
       end
+
+      def lyric_token_parts(token)
+        return [token] if [EXTENDER, HYPHEN].include?(token)
+
+        token.split("-")
+      end
     end
   end
 end