cyclotone 0.1.0 → 1.0.0

data/lib/cyclotone/backends/osc_backend.rb

@@ -5,14 +5,36 @@ require "socket"
 module Cyclotone
   module Backends
     class OSCBackend
-      attr_reader :host, :port
+      Double = Struct.new(:value, keyword_init: true)
+      Blob = Struct.new(:bytes, keyword_init: true)
 
-      def initialize(host: "127.0.0.1", port: 57_120, socket: nil, socket_factory: nil, retries: 1)
+      attr_reader :host, :port, :address
+
+      class << self
+        def double(value)
+          Double.new(value: value.to_f)
+        end
+
+        def blob(bytes)
+          Blob.new(bytes: bytes.to_s.b)
+        end
+      end
+
+      def initialize(
+        host: "127.0.0.1",
+        port: 57_120,
+        address: "/dirt/play",
+        socket: nil,
+        socket_factory: nil,
+        retries: 1
+      )
         @host = host
         @port = port
+        @address = address
         @socket_factory = socket_factory || proc { UDPSocket.new }
         @retries = retries.to_i
         @socket = socket || build_socket
+        @closed = false
       rescue StandardError => error
         raise ConnectionError, error.message
       end
@@ -28,10 +50,16 @@ module Cyclotone
       end
 
       def build_message(event, at:, cps: nil)
-        encode_message("/dirt/play", payload_for(event, at: at, cps: cps))
+        encode_message(address, payload_for(event, at: at, cps: cps))
+      end
+
+      def build_bundle(events, at:, cps: nil, timetag: at)
+        messages = Array(events).map { |event| build_message(event, at: at, cps: cps) }
+        encode_bundle(messages, timetag: timetag)
       end
 
-      def send_event(event, at: Time.now.to_f, cps: nil)
+      def send_event(event, at: Time.now.to_f, cps: nil, **_options)
+        reopen_if_closed!
         with_retry do
           @socket.send(build_message(event, at: at, cps: cps), 0, host, port)
         end
@@ -39,6 +67,20 @@ module Cyclotone
         raise ConnectionError, error.message
       end
 
+      def flush
+        self
+      end
+
+      def panic
+        self
+      end
+
+      def close
+        close_socket
+        @closed = true
+        self
+      end
+
       private
 
       def with_retry
@@ -56,8 +98,17 @@ module Cyclotone
       end
 
       def reconnect!
-        @socket.close if @socket.respond_to?(:close)
+        close_socket
         @socket = build_socket
+        @closed = false
+      end
+
+      def reopen_if_closed!
+        reconnect! if @closed
+      end
+
+      def close_socket
+        @socket.close if @socket.respond_to?(:close)
       end
 
       def build_socket
@@ -65,7 +116,7 @@ module Cyclotone
       end
 
       def flatten_hash(hash)
-        hash.each_with_object([]) do |(key, value), payload|
+        hash.sort_by { |key, _| Support::Deterministic.canonical_key(key) }.each_with_object([]) do |(key, value), payload|
           payload << key.to_s
           payload << value
         end
@@ -81,36 +132,73 @@ module Cyclotone
         return nil unless event.offset
         return event.offset.to_f if cps.nil? || event.duration.nil?
 
-        at.to_f + (event.duration.to_f / cps.to_f)
+        at.to_f + (event.duration.to_f / cps)
       end
 
       def encode_message(address, arguments)
-        type_tags = arguments.map do |argument|
-          case argument
-          when Integer then "i"
-          when Float then "f"
-          else "s"
-          end
-        end.join
+        type_tags = arguments.map { |argument| osc_type_tag(argument) }.join
+
+        padded(address) + padded(",#{type_tags}") + arguments.filter_map { |argument| encode_argument(argument) }.join
+      end
 
-        padded(address) + padded(",#{type_tags}") + arguments.map { |argument| encode_argument(argument) }.join
+      def osc_type_tag(argument)
+        case argument
+        when Double then "d"
+        when Blob then "b"
+        when Integer then "i"
+        when Float then "f"
+        when TrueClass then "T"
+        when FalseClass then "F"
+        when NilClass then "N"
+        when Symbol then "S"
+        else "s"
+        end
       end
 
       def encode_argument(argument)
         case argument
+        when Double
+          [argument.value].pack("G")
+        when Blob
+          encode_blob(argument.bytes)
         when Integer
           [argument].pack("N")
         when Float
           [argument].pack("g")
+        when TrueClass, FalseClass, NilClass
+          nil
         else
           padded(argument.to_s)
         end
       end
 
+      def encode_blob(bytes)
+        data = bytes.to_s.b
+        [data.bytesize].pack("N") + pad_bytes(data)
+      end
+
+      def encode_bundle(messages, timetag:)
+        body = messages.map { |message| [message.bytesize].pack("N") + message }.join
+        padded("#bundle") + encode_timetag(timetag) + body
+      end
+
+      def encode_timetag(value)
+        return [0, 1].pack("NN") if value.nil? || value == :immediate
+
+        seconds = value.to_f + 2_208_988_800
+        whole = seconds.floor
+        fraction = ((seconds - whole) * (2**32)).round
+        [whole, fraction].pack("NN")
+      end
+
       def padded(string)
-        bytes = "#{string}\0"
+        bytes = "#{string}\0".b
+        pad_bytes(bytes)
+      end
+
+      def pad_bytes(bytes)
         padding = (4 - (bytes.bytesize % 4)) % 4
-        bytes + ("\0" * padding)
+        bytes + ("\0".b * padding)
       end
     end
   end

data/lib/cyclotone/controls.rb

@@ -6,11 +6,11 @@ module Cyclotone
       s: { type: :string, aliases: [:sound] },
       n: { type: :integer },
       speed: { type: :float, default: 1.0 },
-      begin: { type: :float, aliases: [:sample_begin] },
-      end: { type: :float, aliases: [:sample_end] },
-      pan: { type: :float, default: 0.5 },
-      gain: { type: :float, default: 1.0 },
-      amp: { type: :float, default: 1.0 },
+      begin: { type: :float, aliases: [:sample_begin], range: 0..1 },
+      end: { type: :float, aliases: [:sample_end], range: 0..1 },
+      pan: { type: :float, default: 0.5, range: 0..1 },
+      gain: { type: :float, default: 1.0, minimum: 0 },
+      amp: { type: :float, default: 1.0, minimum: 0 },
       cut: { type: :integer },
       unit: { type: :string },
       accelerate: { type: :float },
@@ -55,10 +55,10 @@ module Cyclotone
       ring: { type: :float },
       ringf: { type: :float },
       ringdf: { type: :float },
-      note: { type: :integer },
-      velocity: { type: :integer, default: 100 },
+      note: { type: :numeric_or_array },
+      velocity: { type: :integer, default: 100, range: 0..127 },
       sustain: { type: :float, default: 1.0 },
-      channel: { type: :integer, default: 0 },
+      channel: { type: :integer, default: 0, range: 0..15 },
       cc: { type: :hash }
     }.freeze
 
@@ -95,29 +95,77 @@ module Cyclotone
     end
 
     def coerce_pattern(pattern_or_value)
-      return pattern_or_value if pattern_or_value.is_a?(Pattern)
-      return Pattern.mn(pattern_or_value) if pattern_or_value.is_a?(String)
-
-      Pattern.pure(pattern_or_value)
+      Pattern.ensure_pattern(pattern_or_value, strings: :mini_notation)
     end
 
     def wrap_value(control_name, value)
       if value.is_a?(Hash)
         if control_name == :s && (value.key?(:s) || value.key?(:n))
-          value.merge(s: value[:s] || value[:value])
+          sample = value.key?(:s) ? value[:s] : value[:value]
+          value.merge(s: validate_value(control_name, sample))
         elsif control_name == :note && value.key?(:note)
-          value
+          value.merge(note: validate_value(control_name, value[:note]))
         else
-          value.merge(control_name => value[control_name] || value[:value] || value)
+          raw_value = if value.key?(control_name)
+                        value[control_name]
+                      elsif value.key?(:value)
+                        value[:value]
+                      else
+                        value
+                      end
+          value.merge(control_name => validate_value(control_name, raw_value))
         end
       else
-        { control_name => value }
+        { control_name => validate_value(control_name, value) }
       end
     end
 
     def canonical(name)
       ALIASES.fetch(name.to_sym) { raise InvalidControlError, "unknown control #{name}" }
     end
+
+    def validate_value(control_name, value)
+      definition = CONTROL_DEFS.fetch(control_name)
+      validate_type(control_name, value, definition.fetch(:type))
+      validate_range(control_name, value, definition)
+      value
+    end
+
+    def validate_type(control_name, value, type)
+      case type
+      when :integer, :float
+        raise InvalidControlError, "#{control_name} must be numeric" unless value.is_a?(Numeric)
+      when :numeric_or_array
+        values = value.is_a?(Array) ? value : [value]
+        raise InvalidControlError, "#{control_name} must be numeric" unless values.all?(Numeric)
+      when :hash
+        validate_cc(value) if control_name == :cc
+      end
+    end
+
+    def validate_range(control_name, value, definition)
+      values = value.is_a?(Array) ? value : [value]
+
+      if definition[:range]
+        range = definition[:range]
+        raise InvalidControlError, "#{control_name} must be within #{range}" unless values.all? { |entry| range.cover?(entry) }
+      end
+
+      return unless definition.key?(:minimum)
+
+      minimum = definition.fetch(:minimum)
+      raise InvalidControlError, "#{control_name} must be >= #{minimum}" unless values.all? { |entry| entry >= minimum }
+    end
+
+    def validate_cc(value)
+      raise InvalidControlError, "cc must be a Hash" unless value.is_a?(Hash)
+
+      value.each do |controller, amount|
+        raise InvalidControlError, "cc controllers must be within 0..127" unless controller.is_a?(Numeric) && controller.between?(0, 127)
+
+        raise InvalidControlError, "cc values must be within 0..127" unless amount.is_a?(Numeric) && amount.between?(0, 127)
+      end
+    end
   end
 end
 

data/lib/cyclotone/dsl.rb

@@ -8,9 +8,9 @@ module Cyclotone
       end
     end
 
-    %i[sine cosine tri saw isaw square rand irand perlin range smooth].each do |name|
-      define_method(name) do |*args|
-        Oscillators.public_send(name, *args)
+    %i[sine cosine tri saw isaw square rand irand perlin range bipolar noise sample_and_hold brownian smooth].each do |name|
+      define_method(name) do |*args, **kwargs|
+        Oscillators.public_send(name, *args, **kwargs)
       end
     end
 
@@ -126,8 +126,8 @@ module Cyclotone
       stream.stop
     end
 
-    def chord(name, root: 0)
-      Harmony.chord(name, root: root)
+    def chord(name, root: 0, **options)
+      Harmony.chord(name, root: root, **options)
     end
 
     def scale(name, pattern, root: 0)

data/lib/cyclotone/errors.rb

@@ -4,11 +4,12 @@ module Cyclotone
   class Error < StandardError; end
 
   class ParseError < Error
-    attr_reader :line, :column
+    attr_reader :line, :column, :source
 
-    def initialize(message, line: nil, column: nil)
+    def initialize(message, line: nil, column: nil, source: nil)
       @line = line
       @column = column
+      @source = source
 
       super(format_message(message))
     end
@@ -17,11 +18,15 @@ module Cyclotone
 
     def format_message(message)
       return message unless line && column
+      return "#{message} at line #{line}, column #{column}" unless source
 
-      "#{message} at line #{line}, column #{column}"
+      source_line = source.lines.fetch(line - 1, "").chomp
+      caret = "#{" " * [column - 1, 0].max}^"
+      "#{message} at line #{line}, column #{column}\n#{source_line}\n#{caret}"
     end
   end
 
   class ConnectionError < Error; end
   class InvalidControlError < Error; end
+  class InvalidRationalError < Error; end
 end

data/lib/cyclotone/event.rb

@@ -2,12 +2,17 @@
 
 module Cyclotone
   class Event
+    UNSET = Object.new.freeze
+
     attr_reader :whole, :part, :value
 
     def initialize(whole:, part:, value:)
+      raise ArgumentError, "part must be a TimeSpan" unless part.is_a?(TimeSpan)
+      raise ArgumentError, "whole must be nil or a TimeSpan" unless whole.nil? || whole.is_a?(TimeSpan)
+
       @whole = whole
       @part = part
-      @value = value
+      @value = deep_freeze(value)
       freeze
     end
 
@@ -45,8 +50,23 @@ module Cyclotone
       self.class.new(whole: whole, part: part, value: new_value)
     end
 
-    def with_span(new_whole: whole, new_part: part)
-      self.class.new(whole: new_whole, part: new_part, value: value)
+    def with_span(new_whole: UNSET, new_part: UNSET, whole: UNSET, part: UNSET)
+      next_whole = if whole.equal?(UNSET)
+                     new_whole.equal?(UNSET) ? self.whole : new_whole
+                   else
+                     whole
+                   end
+      next_part = if part.equal?(UNSET)
+                    new_part.equal?(UNSET) ? self.part : new_part
+                  else
+                    part
+                  end
+
+      self.class.new(whole: next_whole, part: next_part, value: value)
+    end
+
+    def to_h
+      { whole: whole, part: part, value: value }
     end
 
     def ==(other)
@@ -61,5 +81,20 @@ module Cyclotone
     def hash
       [self.class, whole, part, value].hash
     end
+
+    private
+
+    def deep_freeze(object)
+      case object
+      when Hash
+        object.each_with_object({}) do |(key, entry), frozen_hash|
+          frozen_hash[deep_freeze(key)] = deep_freeze(entry)
+        end.freeze
+      when Array
+        object.map { |entry| deep_freeze(entry) }.freeze
+      else
+        object.freeze
+      end
+    end
   end
 end

data/lib/cyclotone/harmony.rb

@@ -46,7 +46,7 @@ module Cyclotone
     module_function
 
     def scale(name, pattern, root: 0)
-      intervals = SCALES.fetch(name.to_sym)
+      intervals = SCALES.fetch(name.to_sym) { raise ArgumentError, "unknown scale #{name}" }
       root_note = note_number(root)
 
       Pattern.ensure_pattern(pattern).fmap do |value|
@@ -54,11 +54,15 @@ module Cyclotone
       end
     end
 
-    def chord(name, root: 0)
+    def chord(name, root: 0, inversion: 0, voicing: nil, drop2: false, octave_spread: 0)
       root_note = note_number(root)
-      notes = CHORDS.fetch(name.to_sym) { raise ArgumentError, "unknown chord #{name}" }.map do |interval|
+      intervals = voicing || CHORDS.fetch(name.to_sym) { raise ArgumentError, "unknown chord #{name}" }
+      notes = Array(intervals).map do |interval|
         root_note + interval
       end
+      notes = invert_notes(notes, inversion.to_i)
+      notes = spread_octaves(notes, octave_spread.to_i)
+      notes = drop_second_voice(notes) if drop2
 
       Pattern.pure(notes)
     end
@@ -67,6 +71,7 @@ module Cyclotone
       Pattern.ensure_pattern(pattern).flat_map_events do |event|
         notes = extract_notes(event.value)
         next [event] if notes.empty?
+        next [] if event.part.duration.zero?
 
         ordered = order_notes(notes, mode)
         segment_length = event.part.duration / ordered.length
@@ -77,7 +82,7 @@ module Cyclotone
             event.part.start + (segment_length * (index + 1))
           )
 
-          Event.new(whole: part, part: part, value: note)
+          Event.new(whole: part, part: part, value: arpeggiated_value(event.value, note))
         end
       end
     end
@@ -87,20 +92,28 @@ module Cyclotone
 
       normalized = value.to_s.strip.downcase
       match = normalized.match(/\A([a-g](?:s|b)?)(-?\d+)\z/)
-      return normalized.to_i if match.nil?
+      return normalized.to_i if match.nil? && normalized.match?(/\A-?\d+\z/)
+      raise ArgumentError, "invalid note #{value.inspect}" if match.nil?
 
       NOTE_OFFSETS.fetch(match[1]) + ((match[2].to_i + 1) * 12)
     end
 
     def apply_scale(intervals, root_note, value)
       if value.is_a?(Hash) && value.key?(:note)
-        value.merge(note: map_degree(intervals, root_note, value[:note]))
+        value.merge(note: map_value(intervals, root_note, value[:note]))
       else
-        map_degree(intervals, root_note, value)
+        map_value(intervals, root_note, value)
       end
     end
     private_class_method :apply_scale
 
+    def map_value(intervals, root_note, value)
+      return value.map { |entry| map_degree(intervals, root_note, entry) } if value.is_a?(Array)
+
+      map_degree(intervals, root_note, value)
+    end
+    private_class_method :map_value
+
     def map_degree(intervals, root_note, value)
       degree = note_number(value)
       octave, index = degree.divmod(intervals.length)
@@ -131,6 +144,44 @@ module Cyclotone
       end
     end
     private_class_method :order_notes
+
+    def arpeggiated_value(value, note)
+      return value.merge(note: note) if value.is_a?(Hash) && value.key?(:note)
+
+      note
+    end
+    private_class_method :arpeggiated_value
+
+    def invert_notes(notes, inversion)
+      normalized = notes.dup
+
+      inversion.times do
+        normalized << (normalized.shift + 12)
+      end
+
+      (-inversion).times do
+        normalized.unshift(normalized.pop - 12)
+      end
+
+      normalized
+    end
+    private_class_method :invert_notes
+
+    def spread_octaves(notes, spread)
+      return notes if spread <= 0
+
+      notes.each_with_index.map { |note, index| note + (12 * spread * index) }
+    end
+    private_class_method :spread_octaves
+
+    def drop_second_voice(notes)
+      return notes if notes.length < 2
+
+      dropped = notes.dup
+      dropped[-2] -= 12
+      dropped.sort
+    end
+    private_class_method :drop_second_voice
   end
 end
 
@@ -139,7 +190,10 @@ module Cyclotone
     def up(semitones)
       fmap do |value|
         if value.is_a?(Hash) && value.key?(:note)
-          value.merge(note: value[:note] + semitones.to_i)
+          notes = value[:note].is_a?(Array) ? value[:note].map { |note| note + semitones.to_i } : value[:note] + semitones.to_i
+          value.merge(note: notes)
+        elsif value.is_a?(Array)
+          value.map { |note| note + semitones.to_i }
         else
           value + semitones.to_i
         end