cyclotone 0.1.0 → 1.0.0

data/lib/cyclotone/oscillators.rb

@@ -4,43 +4,51 @@ module Cyclotone
   module Oscillators
     module_function
 
-    def sine
-      Pattern.continuous { |time| (Math.sin(phase(time)) + 1.0) / 2.0 }
+    def sine(freq: 1, phase: 0, bipolar: false)
+      oscillator(freq: freq, phase_offset: phase, bipolar: bipolar) do |time|
+        (Math.sin(phase(time)) + 1.0) / 2.0
+      end
     end
 
-    def cosine
-      Pattern.continuous { |time| (Math.cos(phase(time)) + 1.0) / 2.0 }
+    def cosine(freq: 1, phase: 0, bipolar: false)
+      oscillator(freq: freq, phase_offset: phase, bipolar: bipolar) do |time|
+        (Math.cos(phase(time)) + 1.0) / 2.0
+      end
     end
 
-    def tri
-      Pattern.continuous do |time|
+    def tri(freq: 1, phase: 0, bipolar: false)
+      oscillator(freq: freq, phase_offset: phase, bipolar: bipolar) do |time|
         position = cycle_position(time)
         position < 0.5 ? position * 2.0 : (1.0 - position) * 2.0
       end
     end
 
-    def saw
-      Pattern.continuous { |time| cycle_position(time) }
+    def saw(freq: 1, phase: 0, bipolar: false)
+      oscillator(freq: freq, phase_offset: phase, bipolar: bipolar) { |time| cycle_position(time) }
     end
 
-    def isaw
-      Pattern.continuous { |time| 1.0 - cycle_position(time) }
+    def isaw(freq: 1, phase: 0, bipolar: false)
+      oscillator(freq: freq, phase_offset: phase, bipolar: bipolar) { |time| 1.0 - cycle_position(time) }
     end
 
-    def square
-      Pattern.continuous { |time| cycle_position(time) < 0.5 ? 0.0 : 1.0 }
+    def square(freq: 1, phase: 0, bipolar: false)
+      oscillator(freq: freq, phase_offset: phase, bipolar: bipolar) { |time| cycle_position(time) < 0.5 ? 0.0 : 1.0 }
     end
 
-    def rand
+    def rand(steps: 128)
+      normalized_steps = positive_integer(steps, "rand steps")
+
       Pattern.continuous do |time|
         cycle = time.floor
-        step = ((cycle_position(time) * 128).floor).to_i
+        step = (cycle_position(time) * normalized_steps).floor.to_i
         Support::Deterministic.float(:rand, cycle, step)
       end
     end
 
     def irand(maximum)
-      rand.fmap { |value| (value * maximum.to_i).floor }
+      normalized_maximum = positive_integer(maximum, "irand maximum")
+
+      rand.fmap { |value| (value * normalized_maximum).floor }
     end
 
     def perlin
@@ -56,18 +64,64 @@ module Cyclotone
       end
     end
 
-    def range(low, high, pattern)
+    def range(low, high, pattern, mode: :raw)
       Pattern.ensure_pattern(pattern).fmap do |value|
-        low.to_f + ((high.to_f - low.to_f) * value.to_f)
+        normalized_value = normalize_range_value(value.to_f, mode)
+        low.to_f + ((high.to_f - low.to_f) * normalized_value)
+      end
+    end
+
+    def bipolar(pattern)
+      Pattern.ensure_pattern(pattern).fmap { |value| (value.to_f * 2.0) - 1.0 }
+    end
+
+    def noise(steps: 128)
+      rand(steps: steps)
+    end
+
+    def sample_and_hold(pattern, steps: 8)
+      normalized_steps = positive_integer(steps, "sample_and_hold steps")
+      source = Pattern.ensure_pattern(pattern)
+
+      Pattern.continuous do |time|
+        sampled_time = Rational((time * normalized_steps).floor, normalized_steps)
+        source.query_point(sampled_time)
+      end
+    end
+
+    def brownian(step: 0.1)
+      normalized_step = step.to_f
+      raise ArgumentError, "brownian step must be positive" unless normalized_step.positive?
+
+      cache = { -1 => 0.5 }
+      highest_cycle = -1
+
+      Pattern.continuous do |time|
+        cycle = time.floor
+
+        while highest_cycle < cycle
+          next_cycle = highest_cycle + 1
+          cache[next_cycle] = brownian_step(cache.fetch(highest_cycle), next_cycle, normalized_step)
+          highest_cycle = next_cycle
+        end
+
+        cache.fetch(cycle, 0.5)
       end
     end
 
-    def smooth(pattern)
+    def smooth(pattern, interpolator: nil, &block)
       source = Pattern.ensure_pattern(pattern)
       return source if source.continuous?
 
+      interpolation = block || interpolator
+      cache = {}
       Pattern.continuous do |time|
-        interpolate(source, Pattern.to_rational(time))
+        rational_time = Pattern.to_rational(time)
+        cache.fetch(rational_time) do
+          cache[rational_time] = interpolate(source, rational_time, interpolation)
+          cache.shift if cache.length > 256
+          cache[rational_time]
+        end
       end
     end
 
@@ -81,7 +135,51 @@ module Cyclotone
     end
     private_class_method :phase
 
-    def interpolate(source, time)
+    def oscillator(freq:, phase_offset:, bipolar:)
+      normalized_freq = Pattern.to_rational(freq)
+      raise ArgumentError, "oscillator frequency must be positive" unless normalized_freq.positive?
+
+      offset = Pattern.to_rational(phase_offset)
+      Pattern.continuous do |time|
+        value = yield((time * normalized_freq) + offset)
+        bipolar ? (value * 2.0) - 1.0 : value
+      end
+    end
+    private_class_method :oscillator
+
+    def normalize_range_value(value, mode)
+      case mode.to_sym
+      when :raw
+        value
+      when :clamp
+        value.clamp(0.0, 1.0)
+      when :wrap
+        value % 1.0
+      when :fold
+        folded = value % 2.0
+        folded > 1.0 ? 2.0 - folded : folded
+      else
+        raise ArgumentError, "unknown range mode #{mode}"
+      end
+    end
+    private_class_method :normalize_range_value
+
+    def positive_integer(value, label)
+      normalized = Integer(value)
+      raise ArgumentError, "#{label} must be positive" unless normalized.positive?
+
+      normalized
+    rescue ArgumentError, TypeError => error
+      raise ArgumentError, "invalid #{label}: #{error.message}"
+    end
+
+    def brownian_step(value, cycle, step)
+      delta = (Support::Deterministic.float(:brownian, cycle) * 2.0) - 1.0
+      (value + (delta * step)).clamp(0.0, 1.0)
+    end
+    private_class_method :brownian_step
+
+    def interpolate(source, time, interpolation)
       anchors = anchors_for(source, time)
       return source.query_point(time) if anchors.empty?
 
@@ -89,8 +187,8 @@ module Cyclotone
       right = anchors.find { |anchor| anchor[:time] >= time } || anchors.last
       return left[:value] if left[:time] == right[:time]
 
-      amount = (time - left[:time]).to_f / (right[:time] - left[:time]).to_f
-      interpolate_value(left[:value], right[:value], amount)
+      amount = (time - left[:time]).to_f / (right[:time] - left[:time])
+      interpolate_value(left[:value], right[:value], amount, interpolation)
     end
     private_class_method :interpolate
 
@@ -105,25 +203,29 @@ module Cyclotone
     end
     private_class_method :anchors_for
 
-    def interpolate_value(left, right, amount)
+    def interpolate_value(left, right, amount, interpolation = nil)
       if left.is_a?(Numeric) && right.is_a?(Numeric)
         left.to_f + ((right.to_f - left.to_f) * amount)
       elsif left.is_a?(Hash) && right.is_a?(Hash)
-        interpolate_hash(left, right, amount)
+        interpolate_hash(left, right, amount, interpolation)
+      elsif interpolation
+        interpolation.call(left, right, amount)
       else
         amount >= 0.5 ? right : left
       end
     end
     private_class_method :interpolate_value
 
-    def interpolate_hash(left, right, amount)
-      (left.keys | right.keys).each_with_object({}) do |key, result|
-        result[key] =
+    def interpolate_hash(left, right, amount, interpolation)
+      (left.keys | right.keys).to_h do |key|
+        value =
           if left.key?(key) && right.key?(key)
-            interpolate_value(left[key], right[key], amount)
+            interpolate_value(left[key], right[key], amount, interpolation)
           else
             amount >= 0.5 ? right.fetch(key, left[key]) : left.fetch(key, right[key])
           end
+
+        [key, value]
       end
     end
     private_class_method :interpolate_hash

data/lib/cyclotone/pattern.rb

@@ -10,6 +10,9 @@ module Cyclotone
     include Transforms::Sample
 
     SAMPLE_EPSILON = Rational(1, 1024)
+    CACHE_LIMIT = 128
+    CACHE_MUTEX = Mutex.new
+    COMPILER_MUTEX = Mutex.new
 
     attr_reader :query
 
@@ -26,12 +29,17 @@ module Cyclotone
     end
 
     def query_span(span)
-      cycle_spans = span.cycle_spans
-      cycle_spans = [span] if cycle_spans.empty? && continuous?
+      span = self.class.coerce_span(span)
+      emitted_cycle_span = false
+      events = []
 
-      cycle_spans.flat_map { |cycle_span| query.call(cycle_span) }.then do |events|
-        self.class.sort_events(events)
+      span.each_cycle_span do |cycle_span|
+        emitted_cycle_span = true
+        events.concat(query.call(cycle_span))
       end
+
+      events.concat(query.call(span)) if !emitted_cycle_span && continuous?
+      self.class.sort_events(events)
     end
 
     def query_cycle(cycle_number)
@@ -39,13 +47,23 @@ module Cyclotone
     end
 
     def query_event_at(time)
-      query_span(TimeSpan.new(time, time + SAMPLE_EPSILON)).find { |event| event.covers_time?(time) }
+      sample_time = self.class.to_rational(time)
+      query_span(TimeSpan.new(sample_time, sample_time + self.class.sample_epsilon)).find do |event|
+        event.covers_time?(sample_time)
+      end
     end
 
     def query_point(time)
       query_event_at(time)&.value
     end
 
+    def query_points(time)
+      sample_time = self.class.to_rational(time)
+      query_span(TimeSpan.new(sample_time, sample_time + self.class.sample_epsilon)).select do |event|
+        event.covers_time?(sample_time)
+      end.map(&:value)
+    end
+
     def fmap(&transform)
       raise ArgumentError, "fmap requires a block" unless transform
 
@@ -94,12 +112,24 @@ module Cyclotone
       other_pattern = self.class.ensure_pattern(other)
 
       Pattern.new do |span|
-        left_events = query_span(span)
+        left_events = query_span(span).sort_by { |event| event.active_span.start }
         right_events = other_pattern.query_span(span)
+        right_events_by_start = right_events.sort_by { |event| event.active_span.start }
+        first_candidate = 0
 
         left_events.flat_map do |left_event|
-          right_events.filter_map do |right_event|
-            overlap = left_event.active_span.intersection(right_event.active_span)
+          left_span = left_event.active_span
+          left_stop = left_span.stop
+
+          while first_candidate < right_events_by_start.length && right_events_by_start[first_candidate].active_span.stop <= left_span.start
+            first_candidate += 1
+          end
+
+          first_candidate.upto(right_events_by_start.length - 1).filter_map do |index|
+            right_event = right_events_by_start.fetch(index)
+            break [] if right_event.active_span.start >= left_stop
+
+            overlap = left_span.intersection(right_event.active_span)
             next unless overlap
 
             part = overlap.intersection(span)
@@ -138,14 +168,24 @@ module Cyclotone
     end
 
     def merge(other)
+      merge_right(other)
+    end
+
+    def merge_left(other)
       combine_left(other) do |left, right|
-        if left.is_a?(Hash) && right.is_a?(Hash)
-          left.merge(right)
-        elsif right.nil?
-          left
-        else
-          right
-        end
+        merge_values(right, left)
+      end
+    end
+
+    def merge_right(other)
+      combine_left(other) do |left, right|
+        merge_values(left, right)
+      end
+    end
+
+    def merge_deep(other)
+      combine_left(other) do |left, right|
+        deep_merge_values(left, right)
       end
     end
 
@@ -180,18 +220,39 @@ module Cyclotone
 
       alias atom pure
 
+      def atom_at(value, at:, duration: 0)
+        onset_offset = to_rational(at)
+        event_duration = to_rational(duration)
+        raise ArgumentError, "atom duration must be non-negative" if event_duration.negative?
+
+        Pattern.new do |span|
+          cycle_start = Rational(span.cycle_number)
+          onset = cycle_start + onset_offset
+          whole = TimeSpan.new(onset, onset + event_duration)
+          trigger_span = TimeSpan.new(onset, onset + sample_epsilon)
+          part = span.intersection(trigger_span)
+
+          part ? [Event.new(whole: whole, part: part, value: value)] : []
+        end
+      end
+
       def silence
         Pattern.new { |_span| [] }
       end
 
-      def continuous(&sampler)
+      def continuous(sample: :midpoint, &sampler)
+        raise ArgumentError, "continuous requires a sampler block" unless sampler
+
         Pattern.new(continuous: true) do |span|
-          [Event.new(whole: nil, part: span, value: sampler.call(span.midpoint))]
+          [Event.new(whole: nil, part: span, value: sampler.call(sample_time(span, sample)))]
         end
       end
 
-      def ensure_pattern(value)
-        value.is_a?(Pattern) ? value : pure(value)
+      def ensure_pattern(value, strings: :literal)
+        return value if value.is_a?(Pattern)
+        return mn(value) if value.is_a?(String) && strings == :mini_notation
+
+        pure(value)
       end
 
       def to_rational(value)
@@ -199,21 +260,28 @@ module Cyclotone
         return Rational(value, 1) if value.is_a?(Integer)
 
         Rational(value.to_s)
+      rescue ArgumentError, TypeError => error
+        raise InvalidRationalError, "invalid rational value #{value.inspect}: #{error.message}"
       end
 
       def timecat(weighted_patterns)
-        normalized = Array(weighted_patterns)
+        normalized = Array(weighted_patterns).map do |weight, pattern|
+          normalized_weight = to_rational(weight)
+          raise ArgumentError, "timecat weights must be positive" unless normalized_weight.positive?
+
+          [normalized_weight, pattern]
+        end
         raise ArgumentError, "timecat requires patterns" if normalized.empty?
 
-        total_weight = normalized.sum { |weight, _pattern| to_rational(weight) }
+        total_weight = normalized.sum { |weight, _pattern| weight }
+        raise ArgumentError, "timecat total weight must be positive" unless total_weight.positive?
 
         Pattern.new do |span|
           cycle_start = Rational(span.cycle_number)
           cursor = cycle_start
 
           normalized.flat_map do |weight, pattern|
-            normalized_weight = to_rational(weight)
-            segment_length = normalized_weight / total_weight
+            segment_length = weight / total_weight
             segment_span = TimeSpan.new(cursor, cursor + segment_length)
             overlap = span.intersection(segment_span)
             cursor += segment_length
@@ -255,11 +323,12 @@ module Cyclotone
         end
       end
 
-      def randcat(patterns)
+      def randcat(patterns, namespace: :randcat)
         normalized = Array(patterns)
+        raise ArgumentError, "randcat requires patterns" if normalized.empty?
 
         Pattern.new do |span|
-          index = Support::Deterministic.int(normalized.length, :randcat, span.cycle_number)
+          index = Support::Deterministic.int(normalized.length, namespace, span.cycle_number)
           ensure_pattern(normalized[index]).query_span(span)
         end
       end
@@ -272,9 +341,13 @@ module Cyclotone
         fastcat([first, second])
       end
 
-      def stack(patterns)
+      def stack(patterns, empty: :error)
         normalized_patterns = Array(patterns).map { |pattern| ensure_pattern(pattern) }
-        raise ArgumentError, "stack requires at least one pattern" if normalized_patterns.empty?
+        if normalized_patterns.empty?
+          return silence if empty == :silence
+
+          raise ArgumentError, "stack requires at least one pattern"
+        end
 
         Pattern.new do |span|
           normalized_patterns.flat_map { |pattern| pattern.query_span(span) }.then do |events|
@@ -283,28 +356,69 @@ module Cyclotone
         end
       end
 
+      def stack_or_silence(patterns)
+        stack(patterns, empty: :silence)
+      end
+
       def overlay(first, second)
         stack([first, second])
       end
 
       def mn(string)
-        compiler.compile(parser.parse(string))
+        source = string.to_s
+        cached_pattern(source) { compiler.compile(parser.parse(source)) }
+      end
+
+      def mn!(string)
+        mn(string)
+      end
+
+      def try_mn(string)
+        mn(string)
+      rescue ParseError, ArgumentError
+        nil
       end
 
       def parser
-        @parser ||= MiniNotation::Parser.new
+        MiniNotation::Parser.new
       end
 
       def compiler
-        @compiler ||= MiniNotation::Compiler.new
+        return @compiler if @compiler
+
+        COMPILER_MUTEX.synchronize do
+          @compiler ||= MiniNotation::Compiler.new
+        end
       end
 
       def sort_events(events)
         events.sort_by do |event|
-          [event.onset || event.part.start, event.offset || event.part.stop, event.value.to_s]
+          [
+            event.onset || event.part.start,
+            event.offset || event.part.stop,
+            Support::Deterministic.canonical_key(event.value)
+          ]
         end
       end
 
+      def coerce_span(value)
+        return value if value.is_a?(TimeSpan)
+        return TimeSpan.new(value.fetch(0), value.fetch(1)) if value.respond_to?(:fetch)
+
+        raise ArgumentError, "expected TimeSpan or [start, stop], got #{value.class}"
+      end
+
+      def sample_epsilon
+        @sample_epsilon ||= SAMPLE_EPSILON
+      end
+
+      def sample_epsilon=(value)
+        normalized = to_rational(value)
+        raise ArgumentError, "sample epsilon must be positive" unless normalized.positive?
+
+        @sample_epsilon = normalized
+      end
+
       def map_span(span, &block)
         return nil unless span
 
@@ -323,6 +437,38 @@ module Cyclotone
         offset = to_rational(amount)
         map_event(event) { |time| time + offset }
       end
+
+      private
+
+      def sample_time(span, sample)
+        case sample
+        when :begin, :start
+          span.start
+        when :end, :stop
+          span.stop
+        when :midpoint, :center
+          span.midpoint
+        else
+          raise ArgumentError, "unknown continuous sample point #{sample.inspect}"
+        end
+      end
+
+      def cached_pattern(source)
+        CACHE_MUTEX.synchronize do
+          @mn_cache ||= {}
+          @mn_cache_order ||= []
+
+          return @mn_cache[source] if @mn_cache.key?(source)
+
+          pattern = yield
+          @mn_cache[source] = pattern
+          @mn_cache_order << source
+
+          @mn_cache.delete(@mn_cache_order.shift) while @mn_cache_order.length > CACHE_LIMIT
+
+          pattern
+        end
+      end
     end
 
     private
@@ -339,23 +485,52 @@ module Cyclotone
     end
 
     def combine_scalar(left, right, operator)
+      return left if right.nil?
+
       if left.is_a?(Hash) && right.is_a?(Hash)
         keys = left.keys | right.keys
-        keys.each_with_object({}) do |key, result|
-          result[key] =
-            if left.key?(key) && right.key?(key) && left[key].respond_to?(operator)
+        keys.to_h do |key|
+          value =
+            if left.key?(key) && right.key?(key) && right[key].nil?
+              left[key]
+            elsif left.key?(key) && right.key?(key) && left[key].respond_to?(operator)
               left[key].public_send(operator, right[key])
             else
               right.fetch(key, left[key])
             end
+
+          [key, value]
         end
-      elsif right.nil?
-        left
       elsif left.respond_to?(operator)
         left.public_send(operator, right)
       else
         left
       end
     end
+
+    def merge_values(left, right)
+      if left.is_a?(Hash) && right.is_a?(Hash)
+        left.merge(right.compact)
+      elsif right.nil?
+        left
+      else
+        right
+      end
+    end
+
+    def deep_merge_values(left, right)
+      return left if right.nil?
+      return right unless left.is_a?(Hash) && right.is_a?(Hash)
+
+      right.each_with_object(left.dup) do |(key, value), merged|
+        next if value.nil?
+
+        merged[key] = if merged[key].is_a?(Hash) && value.is_a?(Hash)
+                        deep_merge_values(merged[key], value)
+                      else
+                        value
+                      end
+      end
+    end
   end
 end