cyclotone 0.1.0 → 1.0.0

data/lib/cyclotone/backends/midi_file_backend.rb

@@ -10,16 +10,40 @@ module Cyclotone
       DEFAULT_BPM = 120
       DEFAULT_PPQN = 480
       DEFAULT_TRACK_NAME = "Cyclotone"
+      TEMPO_EVENT_PRIORITY = -30
+      TIME_SIGNATURE_EVENT_PRIORITY = -20
+      TRACK_NAME_EVENT_PRIORITY = -10
+      END_OF_TRACK_PRIORITY = 99
 
-      attr_reader :path, :channel, :ppqn, :bpm
+      attr_reader :path, :channel, :ppqn, :bpm, :track_mode
 
-      def initialize(path:, bpm: DEFAULT_BPM, ppqn: DEFAULT_PPQN, channel: 0, track_name: DEFAULT_TRACK_NAME)
+      def self.bpm_from_cps(cps, beats_per_cycle: 4)
+        cps.to_f * 60.0 * beats_per_cycle.to_f
+      end
+
+      def initialize(
+        path:,
+        bpm: DEFAULT_BPM,
+        ppqn: DEFAULT_PPQN,
+        channel: 0,
+        track_name: DEFAULT_TRACK_NAME,
+        time_signature: [4, 4],
+        track_mode: :single,
+        unsupported_controls: :ignore,
+        fractional_notes: :floor
+      )
         @path = path
-        @bpm = bpm.to_f
-        @ppqn = ppqn.to_i
+        @bpm = normalize_bpm(bpm)
+        @ppqn = normalize_positive_integer(ppqn, "ppqn")
         @channel = channel.to_i
         @track_name = track_name.to_s
+        @time_signature = normalize_time_signature(time_signature)
+        @track_mode = track_mode.to_sym
+        @unsupported_controls = normalize_unsupported_control_policy(unsupported_controls)
+        @fractional_notes = normalize_fractional_note_policy(fractional_notes)
         @messages = []
+        @tempo_changes = []
+        @time_signature_changes = []
         @origin_time = nil
       end
 
@@ -28,18 +52,35 @@ module Cyclotone
         self
       end
 
+      def end_capture
+        self
+      end
+
       def clear
         @messages.clear
+        @tempo_changes.clear
+        @time_signature_changes.clear
         @origin_time = nil
         self
       end
 
-      def send_event(event, at: Time.now.to_f, **_options)
+      def tempo_change(at:, bpm:)
+        @tempo_changes << { at: at.to_f, bpm: normalize_bpm(bpm) }
+        self
+      end
+
+      def time_signature_change(at:, numerator:, denominator:)
+        signature = normalize_time_signature([numerator, denominator])
+        @time_signature_changes << { at: at.to_f, signature: signature }
+        self
+      end
+
+      def send_event(event, at: Time.now.to_f, cps: nil, slot_id: nil, **_options)
         capture_time = at.to_f
         @origin_time ||= capture_time
 
-        messages_for(event).each do |message|
-          @messages << normalize_message(message, capture_time)
+        messages_for(event, cps: cps).each do |message|
+          @messages << normalize_message(message, capture_time, slot_id)
         end
 
         self
@@ -55,30 +96,55 @@ module Cyclotone
         raise ConnectionError, error.message
       end
 
+      def flush
+        clear
+      end
+
+      def close
+        self
+      end
+
+      def panic
+        self
+      end
+
       def midi_file_data
-        header_chunk + track_chunk(track_data)
+        tracks = track_payloads
+        header_chunk(tracks.length) + tracks.map { |data| track_chunk(data) }.join
       end
 
       private
 
-      def normalize_message(message, capture_time)
+      def normalize_message(message, capture_time, slot_id)
         timestamp = capture_time + message.fetch(:delay, 0).to_f
-        message.reject { |key, _| key == :delay }.merge(at: timestamp)
+        message.except(:delay).merge(at: timestamp, track: track_key(slot_id))
       end
 
-      def header_chunk
-        "MThd".b << [6, 0, 1, ppqn].pack("Nnnn")
+      def header_chunk(track_count)
+        format = track_count > 1 ? 1 : 0
+        "MThd".b << [6, format, track_count, ppqn].pack("Nnnn")
       end
 
       def track_chunk(data)
         "MTrk".b << [data.bytesize].pack("N") << data
       end
 
-      def track_data
+      def track_payloads
+        return [track_data(@messages, @track_name)] unless track_mode == :slot
+
+        grouped = @messages.group_by { |message| message[:track] }
+        return [track_data([], @track_name)] if grouped.empty?
+
+        grouped.sort_by { |track, _| track.to_s }.map do |track, messages|
+          track_data(messages, "#{@track_name}:#{track}")
+        end
+      end
+
+      def track_data(messages, track_name)
         previous_tick = 0
         body = +"".b
 
-        track_events.each do |track_event|
+        track_events(messages, track_name).each do |track_event|
           delta = track_event[:tick] - previous_tick
           body << encode_variable_length(delta)
           body << track_event[:data]
@@ -88,19 +154,42 @@ module Cyclotone
         body
       end
 
-      def track_events
+      def track_events(messages, track_name)
         events = [
-          { tick: 0, priority: 0, data: tempo_event },
-          { tick: 0, priority: 1, data: track_name_event }
+          { tick: 0, priority: TEMPO_EVENT_PRIORITY, data: tempo_event(bpm) },
+          { tick: 0, priority: TIME_SIGNATURE_EVENT_PRIORITY, data: time_signature_event(@time_signature) },
+          { tick: 0, priority: TRACK_NAME_EVENT_PRIORITY, data: track_name_event(track_name) }
         ]
 
-        events.concat(@messages.map { |message| channel_track_event(message) })
+        events.concat(tempo_change_events)
+        events.concat(time_signature_change_events)
+        events.concat(messages.map { |message| channel_track_event(message) })
 
         end_tick = events.map { |event| event[:tick] }.max || 0
-        events << { tick: end_tick, priority: 99, data: end_of_track_event }
+        events << { tick: end_tick, priority: END_OF_TRACK_PRIORITY, data: end_of_track_event }
         events.sort_by { |event| [event[:tick], event[:priority]] }
       end
 
+      def tempo_change_events
+        @tempo_changes.map do |change|
+          {
+            tick: seconds_to_ticks(change[:at] - origin_time),
+            priority: TEMPO_EVENT_PRIORITY,
+            data: tempo_event(change[:bpm])
+          }
+        end
+      end
+
+      def time_signature_change_events
+        @time_signature_changes.map do |change|
+          {
+            tick: seconds_to_ticks(change[:at] - origin_time),
+            priority: TIME_SIGNATURE_EVENT_PRIORITY,
+            data: time_signature_event(change[:signature])
+          }
+        end
+      end
+
       def channel_track_event(message)
         tick = seconds_to_ticks(message[:at].to_f - origin_time)
 
@@ -124,10 +213,34 @@ module Cyclotone
       end
 
       def seconds_to_ticks(seconds)
-        beats = [seconds.to_f, 0.0].max * bpm / 60.0
+        elapsed = [seconds.to_f, 0.0].max
+        current_bpm = bpm
+        previous_elapsed = 0.0
+        beats = 0.0
+
+        sorted_tempo_changes.each do |change|
+          change_elapsed = change[:at] - origin_time
+
+          if change_elapsed <= previous_elapsed
+            current_bpm = change[:bpm]
+            next
+          end
+
+          break if change_elapsed >= elapsed
+
+          beats += (change_elapsed - previous_elapsed) * current_bpm / 60.0
+          previous_elapsed = change_elapsed
+          current_bpm = change[:bpm]
+        end
+
+        beats += (elapsed - previous_elapsed) * current_bpm / 60.0
         (beats * ppqn).round
       end
 
+      def sorted_tempo_changes
+        @tempo_changes.sort_by { |change| change[:at] }
+      end
+
       def channel_event_data(message)
         channel = message[:channel].to_i.clamp(0, 15)
 
@@ -143,8 +256,8 @@ module Cyclotone
         end
       end
 
-      def tempo_event
-        microseconds = (60_000_000 / bpm).round.clamp(1, 0xFF_FF_FF)
+      def tempo_event(bpm_value)
+        microseconds = (60_000_000 / bpm_value).round.clamp(1, 0xFF_FF_FF)
         "\xFF\x51\x03".b << [
           (microseconds >> 16) & 0xFF,
           (microseconds >> 8) & 0xFF,
@@ -152,15 +265,60 @@ module Cyclotone
         ].pack("C3")
       end
 
-      def track_name_event
-        name = @track_name.dup.force_encoding(Encoding::ASCII_8BIT)
+      def track_name_event(name_value)
+        name = name_value.to_s.dup.force_encoding(Encoding::ASCII_8BIT)
         "\xFF\x03".b << encode_variable_length(name.bytesize) << name
       end
 
+      def track_key(slot_id)
+        return :default unless track_mode == :slot
+
+        slot_id || :default
+      end
+
+      def time_signature_event(signature)
+        numerator, denominator = signature
+        exponent = denominator.bit_length - 1
+        "\xFF\x58\x04".b << [numerator, exponent, 24, 8].pack("C4")
+      end
+
       def end_of_track_event
         "\xFF\x2F\x00".b
       end
 
+      def normalize_bpm(value)
+        normalized = Float(value)
+        return normalized if normalized.positive? && normalized.finite?
+
+        raise ArgumentError, "bpm must be positive"
+      rescue TypeError
+        raise ArgumentError, "bpm must be numeric"
+      end
+
+      def normalize_positive_integer(value, name)
+        normalized = Integer(value)
+        return normalized if normalized.positive?
+
+        raise ArgumentError, "#{name} must be positive"
+      rescue TypeError
+        raise ArgumentError, "#{name} must be an integer"
+      end
+
+      def normalize_time_signature(signature)
+        values = Array(signature)
+        raise ArgumentError, "time_signature must contain numerator and denominator" unless values.length == 2
+
+        numerator = normalize_positive_integer(values[0], "time_signature numerator")
+        denominator = normalize_positive_integer(values[1], "time_signature denominator")
+        return [numerator, denominator] if power_of_two?(denominator)
+
+        raise ArgumentError, "time_signature denominator must be a power of two"
+      end
+
+      def power_of_two?(value)
+        value.nobits?(value - 1)
+      end
+
       def encode_variable_length(value)
         number = value.to_i
         bytes = [number & 0x7F]

data/lib/cyclotone/backends/midi_message_support.rb

@@ -3,68 +3,139 @@
 module Cyclotone
   module Backends
     module MIDIMessageSupport
-      def messages_for(event)
+      SUPPORTED_NOTE_CONTROLS = %i[
+        note channel velocity gain velocity_scale release_velocity release_velocity_scale sustain sustain_cycles fractional_notes
+      ].freeze
+      SUPPORTED_CC_CONTROLS = %i[
+        cc channel cc_scale controller_scale
+      ].freeze
+      UNSUPPORTED_CONTROL_POLICIES = %i[ignore error].freeze
+      FRACTIONAL_NOTE_POLICIES = %i[floor round error].freeze
+
+      def messages_for(event, cps: nil)
         values = event.value.is_a?(Hash) ? event.value : { note: event.value }
-        return control_change_messages(values) if values.key?(:cc)
+        if values.key?(:cc)
+          validate_unsupported_controls!(values, SUPPORTED_CC_CONTROLS)
+          return control_change_messages(values)
+        end
+
+        notes = Array(values[:note])
+        return [] if notes.empty? || notes.all?(&:nil?)
 
-        note = values[:note]
-        return [] if note.nil?
+        validate_unsupported_controls!(values, SUPPORTED_NOTE_CONTROLS)
 
         active_channel = normalize_channel(values[:channel] || channel)
-        sustain = [extract_sustain(values, event), 0.0].max
+        sustain = [extract_sustain(values, event, cps), 0.0].max
+        velocity_scale = values[:velocity_scale]
+        attack_velocity = normalize_velocity(values[:velocity] || values[:gain] || 1.0, scale: velocity_scale)
+        release_velocity = normalize_velocity(
+          values.fetch(:release_velocity, 0),
+          scale: values.fetch(:release_velocity_scale, velocity_scale)
+        )
 
-        [
-          {
-            type: :note_on,
-            channel: active_channel,
-            note: normalize_data_byte(note),
-            velocity: normalize_velocity(values[:velocity] || values[:gain] || 1.0)
-          },
-          {
-            type: :note_off,
-            channel: active_channel,
-            note: normalize_data_byte(note),
-            velocity: 0,
-            delay: sustain
-          }
-        ]
+        notes.compact.flat_map do |note|
+          normalized_note = normalize_note(note, policy: values.fetch(:fractional_notes, fractional_note_policy))
+
+          [
+            {
+              type: :note_on,
+              channel: active_channel,
+              note: normalized_note,
+              velocity: attack_velocity
+            },
+            {
+              type: :note_off,
+              channel: active_channel,
+              note: normalized_note,
+              velocity: release_velocity,
+              delay: sustain
+            }
+          ]
+        end
       end
 
       private
 
+      def normalize_unsupported_control_policy(value)
+        policy = value.to_sym
+        return policy if UNSUPPORTED_CONTROL_POLICIES.include?(policy)
+
+        raise ArgumentError, "unsupported_controls must be one of #{UNSUPPORTED_CONTROL_POLICIES.join(", ")}"
+      end
+
+      def normalize_fractional_note_policy(value)
+        policy = value.to_sym
+        return policy if FRACTIONAL_NOTE_POLICIES.include?(policy)
+
+        raise ArgumentError, "fractional_notes must be one of #{FRACTIONAL_NOTE_POLICIES.join(", ")}"
+      end
+
+      def unsupported_control_policy
+        @unsupported_controls || :ignore
+      end
+
+      def fractional_note_policy
+        @fractional_notes || :floor
+      end
+
+      def validate_unsupported_controls!(values, supported_controls)
+        return unless unsupported_control_policy == :error
+
+        unsupported = values.keys - supported_controls
+        return if unsupported.empty?
+
+        names = unsupported.map(&:inspect).join(", ")
+        raise InvalidControlError, "unsupported MIDI controls: #{names}"
+      end
+
       def control_change_messages(values)
         cc_values = values[:cc].is_a?(Hash) ? values[:cc] : {}
         active_channel = normalize_channel(values[:channel] || channel)
+        scale = values[:cc_scale] || values[:controller_scale]
 
-        cc_values.map do |controller, amount|
+        cc_values.sort_by { |controller, _| controller.to_i }.map do |controller, amount|
           {
             type: :cc,
             channel: active_channel,
             controller: normalize_data_byte(controller),
-            value: normalize_controller_value(amount)
+            value: normalize_controller_value(amount, scale: scale)
           }
         end
       end
 
-      def extract_sustain(values, event)
+      def extract_sustain(values, event, cps)
+        if values.key?(:sustain_cycles)
+          return values[:sustain_cycles].to_f / cps if cps.to_f.positive?
+
+          return values[:sustain_cycles].to_f
+        end
+
         sustain = values[:sustain]
         sustain = event.duration if sustain.nil?
         sustain ||= 1
         sustain.to_f
       end
 
-      def normalize_velocity(value)
-        normalize_7bit_value(value)
+      def normalize_velocity(value, scale: nil)
+        normalize_7bit_value(value, scale: scale)
       end
 
-      def normalize_controller_value(value)
-        normalize_7bit_value(value)
+      def normalize_controller_value(value, scale: nil)
+        normalize_7bit_value(value, scale: scale)
       end
 
-      def normalize_7bit_value(value)
+      def normalize_7bit_value(value, scale: nil)
+        return normalize_data_byte(value) if scale == :midi
+        return normalize_unit_7bit_value(value) if scale == :unit
+
         numeric = value.to_f
         return numeric.round.clamp(0, 127) if numeric > 1.0
 
+        normalize_unit_7bit_value(numeric)
+      end
+
+      def normalize_unit_7bit_value(value)
+        numeric = value.to_f
         (numeric * 127).round.clamp(0, 127)
       end
 
@@ -72,6 +143,18 @@ module Cyclotone
         value.to_i.clamp(0, 15)
       end
 
+      def normalize_note(value, policy:)
+        numeric = Float(value)
+        raise InvalidControlError, "MIDI notes must be finite" unless numeric.finite?
+
+        raise InvalidControlError, "fractional MIDI note #{value.inspect} is not allowed" if numeric != numeric.floor && policy == :error
+
+        normalized = policy == :round ? numeric.round : numeric.floor
+        normalize_data_byte(normalized)
+      rescue ArgumentError, TypeError => error
+        raise InvalidControlError, "invalid MIDI note #{value.inspect}: #{error.message}"
+      end
+
       def normalize_data_byte(value)
         value.to_i.clamp(0, 127)
       end

data/lib/cyclotone/backends/null_backend.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Cyclotone
+  module Backends
+    class NullBackend
+      attr_reader :events
+
+      def initialize
+        @events = []
+      end
+
+      def send_event(event, at:, **options)
+        @events << { event: event, at: at, options: options }
+        self
+      end
+
+      def flush
+        @events.clear
+        self
+      end
+
+      def close
+        self
+      end
+
+      def panic
+        self
+      end
+    end
+
+    DryRunBackend = NullBackend
+  end
+end