deftones 0.1.0 → 1.0.0

data/lib/deftones/io/buffers.rb

@@ -5,13 +5,27 @@ module Deftones
     class Buffers
       include Enumerable
 
-      def initialize(buffers = {})
+      class BulkLoadError < Deftones::Error
+        attr_reader :errors
+
+        def initialize(errors)
+          @errors = errors
+          super("Failed to load #{errors.length} buffer(s): #{errors.keys.join(', ')}")
+        end
+      end
+
+      attr_reader :load_errors
+
+      def initialize(buffers = {}, aggregate_errors: false, **keyword_buffers)
         @buffers = {}
+        @load_errors = {}
         @disposed = false
-        merge(buffers)
+        merge(buffers.merge(keyword_buffers), aggregate_errors: aggregate_errors)
       end
 
       def add(name, buffer)
+        raise Deftones::Error, "cannot add buffer to disposed Buffers" if @disposed
+
         @buffers[key_for(name)] = normalize_buffer(buffer)
         self
       end
@@ -50,8 +64,18 @@ module Deftones
         @buffers.dup
       end
 
-      def merge(buffers)
-        buffers.each { |name, buffer| add(name, buffer) }
+      def merge(buffers, aggregate_errors: false)
+        errors = {}
+        buffers.each do |name, buffer|
+          add(name, buffer)
+        rescue StandardError => error
+          raise unless aggregate_errors
+
+          errors[key_for(name)] = error
+        end
+        @load_errors.merge!(errors)
+        raise BulkLoadError, errors if errors.any?
+
         self
       end
 

data/lib/deftones/io/recorder.rb

@@ -67,7 +67,8 @@ module Deftones
         else
           seconds = [duration.to_f, 1.0 / @context.sample_rate].max
           frames = (seconds * @context.sample_rate).ceil
-          block = @node.send(:render_block, frames, 0, {}).fit_channels(@context.channels)
+          start_frame = ((@started_at || 0.0) * @context.sample_rate).floor
+          block = @node.send(:render_block, frames, start_frame, {}).fit_channels(@context.channels)
           Buffer.new(block.interleaved, channels: @context.channels, sample_rate: @context.sample_rate)
         end
       end

data/lib/deftones/music/frequency.rb

@@ -105,14 +105,19 @@ module Deftones
         end
 
         def parse(value)
-          case value
-          when Numeric
-            value.to_f
-          when /\A(\d+(?:\.\d+)?)hz\z/i
-            Regexp.last_match(1).to_f
-          else
-            Note.to_frequency(value)
-          end
+          frequency =
+            case value
+            when Numeric
+              value.to_f
+            when /\A(-?\d+(?:\.\d+)?)hz\z/i
+              Regexp.last_match(1).to_f
+            else
+              Note.to_frequency(value)
+            end
+
+          raise Deftones::InvalidFrequencyError, "Frequency must be positive" unless frequency.positive? && frequency.finite?
+
+          frequency
         end
 
         def to_period(value)

data/lib/deftones/music/midi.rb

@@ -1,11 +1,5 @@
 # frozen_string_literal: true
 
-begin
-  require "unimidi"
-rescue LoadError
-  nil
-end
-
 module Deftones
   module Music
     class Midi
@@ -105,6 +99,7 @@ module Deftones
         end
 
         def available?
+          load_backend!
           !!defined?(UniMIDI)
         end
 
@@ -136,6 +131,17 @@ module Deftones
           open_device(find_output(name), *args, &block)
         end
 
+        def open_output_session(name = nil, *args)
+          session = OutputSession.new(open_output(name, *args))
+          return session unless block_given?
+
+          begin
+            yield session
+          ensure
+            session.close
+          end
+        end
+
         def receive(name = nil, *args)
           open_input(name) do |input|
             input.gets(*args)
@@ -163,16 +169,84 @@ module Deftones
           )
         end
 
+        def sync_transport(message, transport: Deftones.transport)
+          status = message_data(message).first.to_i
+          case status
+          when 0xF8
+            transport.ticks = transport.ticks + (transport.ppq / 24.0)
+            :clock
+          when 0xFA
+            transport.ticks = 0
+            transport.start(0)
+            :start
+          when 0xFB
+            transport.start(transport.seconds)
+            :continue
+          when 0xFC
+            transport.stop
+            :stop
+          else
+            :ignored
+          end
+        end
+
+        def trigger_from_message(message, target:, time: nil, velocity_scale: 127.0)
+          data = message_data(message)
+          status = data.first.to_i
+          command = status & 0xF0
+          return :ignored unless [0x80, 0x90].include?(command)
+
+          note = Note.from_midi(normalize_data_byte(data[1]))
+          velocity = normalize_data_byte(data[2]) / [velocity_scale.to_f, 1.0].max
+          if command == 0x90 && velocity.positive?
+            target.trigger_attack(note, time, velocity)
+            :note_on
+          else
+            trigger_release(target, note, time)
+            :note_off
+          end
+        end
+
         private
 
+        def load_backend!
+          return true if defined?(UniMIDI)
+
+          require "unimidi"
+          true
+        rescue LoadError
+          false
+        end
+
+        def message_data(message)
+          data = message.is_a?(Hash) ? message.fetch(:data, message) : message
+          Array(data).map(&:to_i)
+        end
+
         def find_device(devices, name)
           return devices.first if name.nil?
 
-          devices.find { |device| device.name == name.to_s }
+          matched_by_id = devices.find { |device| matches_device_id?(device, name) }
+          return matched_by_id if matched_by_id
+          return devices[name] if name.is_a?(Integer) && name >= 0 && name < devices.length
+
+          matcher = name.is_a?(Regexp) ? name : Regexp.new(Regexp.escape(name.to_s), Regexp::IGNORECASE)
+          devices.find { |device| device.respond_to?(:name) && device.name.to_s.match?(matcher) }
+        end
+
+        def matches_device_id?(device, selector)
+          return false if selector.is_a?(Regexp)
+
+          candidates = []
+          candidates << device.id if device.respond_to?(:id)
+          candidates << device.device_id if device.respond_to?(:device_id)
+          candidates << device.index if device.respond_to?(:index)
+          candidates << device.device_index if device.respond_to?(:device_index)
+          candidates.compact.any? { |candidate| candidate.to_s == selector.to_s }
         end
 
         def open_device(device, *args, &block)
-          raise ArgumentError, "MIDI support is unavailable" unless available?
+          raise Deftones::MissingMidiBackendError, "MIDI support is unavailable. Install the unimidi gem to enable MIDI I/O." unless available?
           raise ArgumentError, "No matching MIDI device found" unless device
 
           return device.open(*args) unless block
@@ -197,8 +271,57 @@ module Deftones
           base + normalize_channel(channel)
         end
 
+        def trigger_release(target, note, time)
+          target.trigger_release(note, time)
+        rescue ArgumentError
+          target.trigger_release(time)
+        end
+
         def normalize_channel(channel)
-          [[channel.to_i - 1, 0].max, 15].min
+          integer = channel.to_i
+          raise ArgumentError, "MIDI channel must be between 1 and 16" unless (1..16).cover?(integer)
+
+          integer - 1
+        end
+      end
+
+      class OutputSession
+        def initialize(output)
+          @output = output
+          @closed = false
+        end
+
+        def send(message)
+          raise IOError, "MIDI output session is closed" if @closed
+
+          @output.puts(message)
+          self
+        end
+
+        def note_on(note, velocity: 100, channel: 1)
+          send([self.class.parent_status_byte(0x90, channel), Midi.send(:normalize_note, note),
+                Midi.send(:normalize_data_byte, velocity)])
+        end
+
+        def note_off(note, velocity: 0, channel: 1)
+          send([self.class.parent_status_byte(0x80, channel), Midi.send(:normalize_note, note),
+                Midi.send(:normalize_data_byte, velocity)])
+        end
+
+        def close
+          return self if @closed
+
+          @output.close if @output.respond_to?(:close)
+          @closed = true
+          self
+        end
+
+        def closed?
+          @closed
+        end
+
+        def self.parent_status_byte(base, channel)
+          Midi.send(:status_byte, base, channel)
         end
       end
     end

data/lib/deftones/music/note.rb

@@ -32,22 +32,32 @@ module Deftones
         end
 
         def from_frequency(frequency)
-          midi_number = (12 * Math.log2(frequency.to_f / 440.0) + 69).round
+          normalized_frequency = frequency.to_f
+          raise Deftones::InvalidFrequencyError, "Frequency must be positive" unless normalized_frequency.positive? && normalized_frequency.finite?
+
+          midi_number = (12 * Math.log2(normalized_frequency / 440.0) + 69).round
           from_midi(midi_number)
         end
 
         private
 
         def parse_note_name(note_name)
+          validate_accidentals!(note_name)
           match = note_name.to_s.match(/\A([A-Ga-g][#b]?)(-?\d+)\z/)
-          raise ArgumentError, "Invalid note: #{note_name}" unless match
+          raise Deftones::InvalidNoteError, "Invalid note: #{note_name}" unless match
 
           normalized_name = normalize_name(match[1])
-          raise ArgumentError, "Unsupported note name: #{note_name}" unless NOTE_NAMES.include?(normalized_name)
+          raise Deftones::InvalidNoteError, "Unsupported note name: #{note_name}" unless NOTE_NAMES.include?(normalized_name)
 
           [normalized_name, match[2].to_i]
         end
 
+        def validate_accidentals!(note_name)
+          return unless note_name.to_s.match?(/\A[A-Ga-g](?:##|bb)/)
+
+          raise Deftones::InvalidNoteError, "Double accidentals are unsupported: #{note_name}"
+        end
+
         def normalize_name(token)
           canonical = token[0].upcase + token[1..]
           FLAT_MAP.fetch(canonical, canonical.upcase)

data/lib/deftones/music/time.rb

@@ -106,8 +106,10 @@ module Deftones
           else
             return value.to_seconds if value.respond_to?(:to_seconds)
           end
-        rescue KeyError, ArgumentError
-          raise ArgumentError, "Unknown time format: #{value}"
+        rescue KeyError, ArgumentError => error
+          raise error if error.is_a?(Deftones::InvalidTimeError)
+
+          raise Deftones::InvalidTimeError, "Unknown time format: #{value}"
         end
 
         private
@@ -133,7 +135,10 @@ module Deftones
             beats_per_measure = Array(time_signature).first || 4
             ((bars * beats_per_measure) + beats + (sixteenths * 0.25)) * beat_duration(bpm)
           when /\A(\d+(?:\.\d+)?)hz\z/i
-            1.0 / Regexp.last_match(1).to_f
+            frequency = Regexp.last_match(1).to_f
+            raise Deftones::InvalidTimeError, "Hz time values must be positive" unless frequency.positive?
+
+            1.0 / frequency
           when /\A(-?\d+(?:\.\d+)?)i\z/i
             (Regexp.last_match(1).to_f / ppq.to_f) * beat_duration(bpm)
           else
@@ -154,7 +159,19 @@ module Deftones
         end
 
         def tokenize(expression)
-          expression.scan(/\d+:\d+:\d+|\d+(?:\.\d+)?hz|-?\d+(?:\.\d+)?i|\d+n\.?|\d+t|\d+m|[()+\-*\/]|\d+(?:\.\d+)?/)
+          tokens = []
+          offset = 0
+          pattern = /\G\s*(\d+:\d+:\d+|\d+(?:\.\d+)?hz|-?\d+(?:\.\d+)?i|\d+n\.?|\d+t|\d+m|[()+\-*\/]|-?\d+(?:\.\d+)?)/
+
+          while offset < expression.length
+            match = expression.match(pattern, offset)
+            raise Deftones::InvalidTimeError, "Invalid time expression: #{expression}" unless match
+
+            tokens << match[1]
+            offset = match.end(0)
+          end
+
+          normalize_unary_minus(tokens)
         end
 
         def to_rpn(tokens)
@@ -170,6 +187,8 @@ module Deftones
             elsif token == "("
               operators << token
             elsif token == ")"
+              raise Deftones::InvalidTimeError, "Mismatched parentheses" unless operators.include?("(")
+
               output << operators.pop until operators.last == "("
               operators.pop
             else
@@ -177,6 +196,8 @@ module Deftones
             end
           end
 
+          raise Deftones::InvalidTimeError, "Mismatched parentheses" if operators.any? { |operator| ["(", ")"].include?(operator) }
+
           output.concat(operators.reverse)
         end
 
@@ -185,6 +206,8 @@ module Deftones
 
           tokens.each do |token|
             if operator?(token)
+              raise Deftones::InvalidTimeError, "Invalid time expression" if stack.length < 2
+
               right = stack.pop
               left = stack.pop
               stack << left.public_send(token, right)
@@ -193,9 +216,24 @@ module Deftones
             end
           end
 
+          raise Deftones::InvalidTimeError, "Invalid time expression" unless stack.length == 1
+
           stack.first
         end
 
+        def normalize_unary_minus(tokens)
+          normalized = []
+
+          tokens.each_with_index do |token, index|
+            if token == "-" && (index.zero? || operator?(tokens[index - 1]) || tokens[index - 1] == "(")
+              normalized << "0"
+            end
+            normalized << token
+          end
+
+          normalized
+        end
+
         def operator?(token)
           %w[+ - * /].include?(token)
         end

data/lib/deftones/offline_context.rb

@@ -1,46 +1,223 @@
 # frozen_string_literal: true
 
+require "tempfile"
+
 module Deftones
   class OfflineContext < Context
-    attr_reader :channels, :duration, :total_frames
+    RenderResult = Struct.new(:buffer, :metadata, keyword_init: true)
+    class RenderCancelled < Deftones::Error; end
+
+    attr_reader :channels, :current_frame, :duration, :last_render_metadata, :total_frames
 
     def initialize(duration:, channels: 2, sample_rate: DEFAULT_SAMPLE_RATE,
-                   buffer_size: DEFAULT_BUFFER_SIZE)
-      super(sample_rate: sample_rate, buffer_size: buffer_size, channels: channels, autostart: false)
+                   buffer_size: DEFAULT_BUFFER_SIZE, transport: nil, draw: nil)
+      super(sample_rate: sample_rate, buffer_size: buffer_size, channels: channels, autostart: false,
+            transport: transport, draw: draw)
       @duration = duration.to_f
       @total_frames = (@duration * sample_rate).ceil
+      @current_frame = 0
+      @rendering = false
+      @last_render_metadata = nil
     end
 
     def current_time
-      0.0
+      @current_frame.to_f / sample_rate
     end
 
     def state
       "suspended"
     end
 
-    def render
-      Deftones.transport.prepare_render(@duration)
-      Deftones.draw.prepare_render(@duration)
+    def render(seed: nil, metadata: false, progress: nil, cancel: nil)
       samples = Array.new(@total_frames * @channels, 0.0)
-      frames_processed = 0
 
-      while frames_processed < @total_frames
-        chunk_frames = [buffer_size, @total_frames - frames_processed].min
-        interleaved = render_block_frames(chunk_frames, frames_processed).fit_channels(@channels).interleaved
-        start_index = frames_processed * @channels
+      render_each_block(seed: seed, progress: progress, cancel: cancel) do |block, start_frame|
+        interleaved = block.fit_channels(@channels).interleaved
+        start_index = start_frame * @channels
 
         samples[start_index, interleaved.length] = interleaved
-        frames_processed += chunk_frames
       end
 
-      IO::Buffer.new(samples, channels: @channels, sample_rate: sample_rate)
+      buffer = IO::Buffer.new(samples, channels: @channels, sample_rate: sample_rate)
+      @last_render_metadata = metadata_for(buffer)
+      return RenderResult.new(buffer: buffer, metadata: @last_render_metadata) if metadata
+
+      buffer
+    end
+
+    def render_with_metadata(**options)
+      render(**options, metadata: true)
+    end
+
+    def render_each_block(seed: nil, progress: nil, cancel: nil)
+      return enum_for(:render_each_block) unless block_given?
+
+      with_render_state(seed: seed) do
+        frames_processed = 0
+
+        while frames_processed < @total_frames
+          raise RenderCancelled, "render cancelled" if cancel&.call(frames_processed.to_f / @total_frames)
+
+          chunk_frames = [buffer_size, @total_frames - frames_processed].min
+          @current_frame = frames_processed
+          advance_schedulers(frames_processed, chunk_frames)
+          yield render_block_frames(chunk_frames, frames_processed).fit_channels(@channels), frames_processed
+          frames_processed += chunk_frames
+          progress&.call(frames_processed.to_f / @total_frames)
+        end
+
+        @current_frame = @total_frames
+      end
+
+      self
     end
 
-    def render_to_file(path, format: nil)
-      rendered_buffer = render
-      rendered_buffer.save(path, format: format)
+    alias renderEachBlock render_each_block
+    alias renderWithMetadata render_with_metadata
+
+    def render_to_file(path, format: nil, streaming: false, bit_depth: 16, dither: false, dither_rng: nil,
+                       **render_options)
+      if streaming
+        return stream_to_file(path, format: format, bit_depth: bit_depth, dither: dither, dither_rng: dither_rng,
+                                    **render_options)
+      end
+
+      rendered_buffer = render(**render_options)
+      buffer = rendered_buffer.respond_to?(:buffer) ? rendered_buffer.buffer : rendered_buffer
+      buffer.save(path, format: format, bit_depth: bit_depth, dither: dither, dither_rng: dither_rng)
       rendered_buffer
     end
+
+    private
+
+    def with_render_state(seed: nil)
+      previous_frame = @current_frame
+      previous_rendering = @rendering
+      previous_seed = seed ? srand(seed) : nil
+      @rendering = true
+      @current_frame = 0
+      yield
+    ensure
+      srand(previous_seed) if seed
+      @current_frame = previous_frame
+      @rendering = previous_rendering
+    end
+
+    def advance_schedulers(start_frame, chunk_frames)
+      window_start = start_frame.to_f / sample_rate
+      window_end = (start_frame + chunk_frames).to_f / sample_rate
+      transport.prepare_render_window(window_start, window_end)
+      draw.advance_to(window_end)
+      Deftones.transport.prepare_render_window(window_start, window_end) unless Deftones.transport.equal?(transport)
+      Deftones.draw.advance_to(window_end) unless Deftones.draw.equal?(draw)
+    end
+
+    def stream_to_file(path, format: nil, bit_depth:, dither:, dither_rng:, **render_options)
+      resolved_format = format || File.extname(path).delete_prefix(".").downcase.to_sym
+      resolved_format = :wav if resolved_format.nil? || resolved_format == :""
+      resolved_format = :ogg if resolved_format.to_sym == :oga
+      unless IO::Buffer::SAVEABLE_FORMATS.include?(resolved_format.to_sym)
+        raise UnsupportedAudioFormatError, "Unsupported streaming render format: #{resolved_format}"
+      end
+      return stream_compressed_to_file(path, resolved_format.to_sym, bit_depth: bit_depth, dither: dither,
+                                                                dither_rng: dither_rng, **render_options) unless resolved_format.to_sym == :wav
+
+      normalized_bit_depth = validate_wav_bit_depth(bit_depth)
+
+      File.open(path, "wb") do |file|
+        file.write(wav_header(normalized_bit_depth))
+        render_each_block(**render_options) do |block, _start_frame|
+          file.write(pcm_payload(block.fit_channels(@channels).interleaved,
+                                 bit_depth: normalized_bit_depth,
+                                 dither: dither,
+                                 dither_rng: dither_rng))
+        end
+      end
+
+      path
+    end
+
+    def stream_compressed_to_file(path, format, bit_depth:, dither:, dither_rng:, **render_options)
+      Tempfile.create(["deftones-stream-render", ".wav"]) do |tempfile|
+        tempfile.close
+        stream_to_file(tempfile.path, format: :wav, bit_depth: bit_depth, dither: dither, dither_rng: dither_rng,
+                                      **render_options)
+        encode_streamed_wav(tempfile.path, path, format)
+      end
+      path
+    end
+
+    def encode_streamed_wav(input_path, output_path, format)
+      backend = IO::Buffer.send(:encoder_backend_for, format)
+      raise MissingCodecBackendError, IO::Buffer.send(:missing_encoder_message, format) unless backend
+
+      if IO::Buffer.send(:custom_codec_backend?, backend)
+        backend.encode(input_path, output_path, format: format, sample_rate: sample_rate, channels: channels)
+        return
+      end
+
+      command = IO::Buffer.send(:encoder_command, backend, input_path, output_path, format, sample_rate, channels)
+      stdout, stderr, status = IO::Buffer.send(:capture_codec_command, *command)
+      return if status.success?
+
+      IO::Buffer.send(:raise_codec_command_error, "Failed to encode #{format}", command, stdout, stderr, status)
+    end
+
+    def metadata_for(buffer)
+      {
+        duration: duration,
+        frames: total_frames,
+        channels: channels,
+        sample_rate: sample_rate,
+        peak: buffer.peak,
+        rms: buffer.rms,
+        clip_count: buffer.clip_count
+      }
+    end
+
+    def wav_header(bit_depth)
+      bytes_per_sample = bit_depth / 8
+      data_size = @total_frames * @channels * bytes_per_sample
+      byte_rate = sample_rate * @channels * bytes_per_sample
+      block_align = @channels * bytes_per_sample
+
+      "RIFF" \
+        + [36 + data_size].pack("V") \
+        + "WAVEfmt " \
+        + [16, 1, @channels, sample_rate, byte_rate, block_align, bit_depth].pack("VvvVVvv") \
+        + "data" \
+        + [data_size].pack("V")
+    end
+
+    def pcm_payload(samples, bit_depth:, dither:, dither_rng:)
+      quantized = samples.map { |sample| quantize_pcm(sample, bit_depth, dither: dither, dither_rng: dither_rng) }
+
+      case bit_depth
+      when 16 then quantized.pack("s<*")
+      when 24 then quantized.map { |value| [value & 0xFFFFFF].pack("V")[0, 3] }.join
+      when 32 then quantized.pack("l<*")
+      end
+    end
+
+    def quantize_pcm(sample, bit_depth, dither:, dither_rng:)
+      max = (2**(bit_depth - 1)) - 1
+      min = -(2**(bit_depth - 1))
+      value = dither ? dither_sample(sample, bit_depth, dither_rng) : sample.to_f
+      scaled = Deftones::DSP::Helpers.clamp(value, -1.0, 1.0) * max
+      Deftones::DSP::Helpers.clamp(scaled.round, min, max)
+    end
+
+    def dither_sample(sample, bit_depth, rng)
+      random = rng || Random
+      step = 1.0 / ((2**(bit_depth - 1)) - 1)
+      sample.to_f + ((random.rand - random.rand) * step)
+    end
+
+    def validate_wav_bit_depth(bit_depth)
+      normalized = bit_depth.to_i
+      return normalized if IO::Buffer::WAV_BIT_DEPTHS.include?(normalized)
+
+      raise ArgumentError, "Unsupported WAV bit depth: #{bit_depth}"
+    end
   end
 end