ramekin 0.1.9 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 765b62c41161f9939eccd6a53a5e0d4b32dc3cd3ec83584231d8dd4172655d5e
-  data.tar.gz: 1a0c1b59f0c9cc746fbb97f19c11d66c14d5dd535d5618c6542c16c8c69fce63
+  metadata.gz: 399438b57abf19c6d68cbc4db7fbb96586985bf801f0f94cea4cd1365d2839e9
+  data.tar.gz: 5abb75a51346fa517c749f3dd78d469459d02bef30bb3478060f2ed9527a0792
 SHA512:
-  metadata.gz: 8a1986e575b290efe80774910bb1fa2c52f1be4f16d9aa9e3888711de7f29252c03fd46fab7a7a454314e7fbd9abbd9408c2229c93d3307fda0059987b94972a
-  data.tar.gz: c312388efff73d5953984dd7803e3b6313de634549ef9538606def060cdd191c04ef295876cfb8d61d443693f40057206584bec82bba239ad97b6aa37b4f2a08
+  metadata.gz: e9306550e91db609450792179302dce6752cb6fa9cb5fe97f95f1ac926bf28bc8548719c5e0d55e7909c0e4c8817149675f7caff6a86c0d4b37bbeaaf634840b
+  data.tar.gz: 38abeba0943b587b1559e9fe0a1fe5fe0875f349a1b7fa5883b1e7da57e1e52898a0bd0ef2b7fee02b418a8f739aae118baae74627cbfce6d773d6d4fba5a4a9

data/README.md

@@ -108,7 +108,7 @@ A list of some ramekin preprocessor features (see `spec/rmk` for some examples!)
 * `#adsr:A,D,S,RR` syntax for ADSR. Also usable on an `#instrument` declaration, with the same syntax. A, D, and R are flipped so that higher numbers are longer times.
 * `v+X` and `v-X` are volumes relative to the last `vXXX` command. Useful for separating expression from mixing.
 * `yLX` and `yRX` commands for panning left and right. `yC` to set back to center. Way easier for me to remember.
-* `#bend` followed by a note with any length, including ties, will bend for that note's duration. Continue the note with a non-collapsing tie `^^`. Octave changes, `l` commands, and other note modifiers are allowed here. This will compile to a correct `$DD` command.
+* The implementation of `&` is more robust, and it compiles to a proper `$dd` command. It can also much more flexibly chain multiple bends together, using a non-breaking tie `^^X` to establish where the boundaries of the bend should be, and handles quite a few idiosyncracies of `$dd` automatically behind the scenes. You should be able to use `&` and `^^` for all pitch bending needs. See "Pitch Expression" below for details.
 ```elisp
 ; bends to c two octaves up for two 16th notes, then continues for a quarter note
 b8 #bend >>c16^16 ^^4
@@ -335,12 +335,22 @@ Volume can be set with `vXXX`, where `XXX` is a number between 0 and 255. This c
 Pitch expression can be accomplished in two ways:
 
 * `pA,B,C`, where A,B, and C are numbers, can be used to set vibrato - a slight pitch wiggle that starts sometime after a note is started. `A` specifies the delay - how long to wait before wiggling the pitch, `B` specifies the speed - how fast to wiggle the pitch, and `C` specifies the amplitude - how much to wiggle the pitch. Turn off vibrato with `p0,0`.
-* Manual pitch bends are fairly straightforward in ramekin, using `#bend` and `^^`:
+* Manual pitch bends are fairly straightforward in ramekin, using `&` and `^^`:
 
 ```elisp
-; b plays for an 8th note, then bends up to c for an eighth note,
-; then continues on c for a quarter note.
-b8 #bend >c8 ^^ c4
+; bend b8 and then hold on c for the rest of the bar
+b8 & >c4.^2
+
+; multiple bends can be safely strung together
+b8 & >c8 & d2
+
+; to hold on a note and then do further bends, use a non-breaking tie ^^.
+; this will hold steady on c, and then bend for an eighth note to the e.
+b8 & c8^4 ^^8 & e8
+
+; to bend at the very end, use a zero-length note.
+; this falls to g and then stops.
+c4 & <g0
 ```
 
 #### Panning Expression

data/lib/ramekin/bends.rb

@@ -0,0 +1,192 @@
+module Ramekin
+  class Bend < NoteEvent
+    attr_reader :notes
+    def initialize(*notes)
+      @notes = notes
+    end
+
+    def ticks
+      @notes.map(&:ticks).sum
+    end
+
+    # special handling for this in legato.rb
+    # since this doesn't play nice with LegatoLastNote
+    def end_legato!
+      @end_legato = true
+    end
+
+    def inspect
+      "#bend(#{@notes.map(&:inspect).join('&')})"
+    end
+
+    def start
+      @notes.first.start
+    end
+
+    def fin
+      @notes.last.fin
+    end
+
+    def rest?
+      false
+    end
+
+    def tie?
+      false
+    end
+
+    def ending_octave
+      @notes.first.octave
+    end
+
+    # in the event of a tie-free bend exactly at a note out where we *also*
+    # have to trigger legato mid-way, we need to use separate splitting logic
+    # to make sure we toggle legato at least 2 ticks from the note end.
+    #
+    # this is complicated by the fact that $dd is sensitive to ties.
+    #
+    # this means there is a possibility we will have to make the bend 2 ticks
+    # shorter than what was actually specified - not a huge difference in sound,
+    # but it has to be handled carefully.
+    def render_massive_special_case(oct, div)
+      from = @notes[0]
+      to = @notes[1]
+      total_duration = (from.ticks + to.ticks) / div
+      bend_duration = from.ticks / div
+
+      leftover = total_duration - bend_duration
+
+      # ensure there is some leftover so we can toggle legato
+      # before the end
+      if leftover < 2
+        adjust = 2 - leftover
+        bend_duration -= adjust
+        leftover += adjust
+        if bend_duration <= 0
+          return error! 'bend duration too small to insert legato-off toggle', el: self
+        end
+      end
+
+      return '' unless check_duration!(from)
+
+      out = StringIO.new
+
+      out << from.octave_amk(oct)
+      out << from.note_name
+      out << "=#{bend_duration}"
+      out << dd(bend_duration, to)
+      out << "$f4$01^=#{leftover}"
+
+      out.string
+    end
+
+    def massive_special_case?(divisor)
+      # special case only matters if this is the last note in a legato chain
+      return false unless @end_legato
+
+      # if there's more than one note to bend, the normal handling will
+      # toggle in between them
+      return false unless @notes.size == 2
+
+      # if the bend is being split up anyways (with a leftover of at least 2
+      # ticks) then normal handling will toggle in between the split
+      return false unless (@notes[1].ticks+@notes[0].ticks) / divisor <= 0x62
+      true
+    end
+
+    def check_duration!(note)
+      ticks = note.ticks
+      return true if ticks > 0 && ticks <= 96
+
+      error! 'bend length too short (must be at least one tick)', el: note if ticks <= 0
+      error! 'bend duration too long (max 96 ticks or a half note)', el: note if ticks > 96
+
+      false
+    end
+
+    def to_amk(octave, divisor)
+      if massive_special_case?(divisor)
+        return render_massive_special_case(octave, divisor)
+      end
+
+      out = StringIO.new
+
+      (0...@notes.length-1).each do |i|
+        note = @notes[i]
+        to_note = @notes[i+1]
+
+        if i == 0
+          ticks = note.ticks + to_note.ticks
+          out << note.octave_amk(octave)
+          out << note.note_name
+        else
+          ticks = to_note.ticks
+          out << '^'
+        end
+
+        ticks /= divisor
+        next unless check_duration!(note)
+
+        # $dd doesn't work properly if the note
+        # beforehand is more than a half note, so we have to
+        # split it up
+        clamped_ticks = [0x60, ticks].min
+        leftover_ticks = [0, ticks-0x60].max
+
+        # always use tick count notation here because
+        # amk can insert ties in some cases which will break $dd
+        out << "=#{clamped_ticks}"
+        out << dd(note.ticks, to_note)
+        out << '$f4$01' if @end_legato && i == 0
+        out << "^=#{leftover_ticks}" if leftover_ticks > 0
+      end
+
+      out.string
+    end
+
+    def dd(dur, note)
+      hex = note.note_hex
+
+      unless 0x80 <= hex && hex <= 0xC5
+        error! 'note out of range (o1c - o6a)', el: note
+        return ''
+      end
+
+      sprintf '$dd$00$%02x$%02x', dur, note.note_hex
+    end
+  end
+
+  class Bends < Processor
+    def flush!
+      yield @last_note if @last_note
+      @last_note = nil
+    end
+
+    def call(&b)
+      each do |el|
+        if NoteEvent === el && !el.rest?
+          flush!(&b)
+          @last_note = el
+          el.meta[:bends] = []
+        elsif Token === el && el.type == :amp
+          next error! 'bend must be followed by a note' unless NoteEvent === peek
+          next error! 'cannot bend to a rest' if peek.rest?
+          next error! 'bend must come after a note' if @last_note.nil?
+
+          to_note = next!
+
+          if Bend === @last_note
+            @last_note.notes << to_note
+          else
+            @last_note = Bend.new(@last_note, to_note)
+          end
+        else
+          flush!(&b)
+          yield el
+        end
+      end
+
+      flush!(&b)
+    end
+  end
+end

data/lib/ramekin/cli.rb

@@ -97,7 +97,14 @@ module Ramekin
       exit 1
     end
 
+    def warn_unless_setup!
+      unless AMKSetup.setup_ok?
+        $stderr.puts "WARNING: ramekin is not set up. Have you run `ramekin setup`?"
+      end
+    end
+
     def compile(*argv)
+      warn_unless_setup!
       @force = false
       @play = false
 
@@ -178,6 +185,7 @@ module Ramekin
 
       inner_chain = Processor.compose(
         NoteAggregator,
+        Bends,
         RestAggregator,
         Legato,
         Inspector,
@@ -258,6 +266,8 @@ module Ramekin
     end
 
     def package(*argv)
+      warn_unless_setup!
+
       @mode = nil
       @update = false
       @search = nil

data/lib/ramekin/legato.rb

@@ -22,6 +22,10 @@ module Ramekin
       @note.fin
     end
 
+    def tie?
+      @note.tie?
+    end
+
     def rest?
       @note.rest?
     end
@@ -78,14 +82,24 @@ module Ramekin
       last = buffer.pop
       error! "legato marks must follow a note", el: last unless NoteEvent === last
       buffer.each(&b)
-      yield LegatoLastNote.new(last)
+
+      # ending legato on a bend is complicated - let Bend handle it
+      case last
+      when Bend then last.end_legato!; yield last
+      else yield LegatoLastNote.new(last)
+      end
       buffer.clear
     ensure
       non_notes.reverse_each(&b)
     end
 
+    def tieable?(t)
+      return true if NoteEvent === t && t.tie?
+      return true if Token === t && TIEABLE_EVENTS.include?(t.type)
+      false
+    end
+
     TIEABLE_EVENTS = %i(
-      amp
       y
       rely
       v
@@ -97,13 +111,16 @@ module Ramekin
       transpose
       adsr
       bpm
+      native_tie
     )
     def call(&b)
       return enum_for(:process) unless block_given?
 
       each do |el|
         if @in_legato
-          if NoteEvent === el
+          if tieable?(el)
+            buffer << el
+          elsif NoteEvent === el
             if @seen_legato
               @seen_legato = false
               buffer << el
@@ -113,13 +130,8 @@ module Ramekin
               flush_legato!(&b)
               buffer!(el, &b)
             end
-          elsif Token === el && el.type == :amp
-            @seen_legato = true
-            buffer << el
           elsif Token === el && el.type == :legato_tie
             @seen_legato = true
-          elsif Token === el && TIEABLE_EVENTS.include?(el.type)
-            buffer << el
           else
             @in_legato = false
             @seen_legato = false
@@ -127,11 +139,11 @@ module Ramekin
             yield el
           end
         else
-          if NoteEvent === el
+          if tieable?(el)
+            buffer << el
+          elsif NoteEvent === el
             flush!(&b)
             buffer!(el, &b)
-          elsif Token === el && TIEABLE_EVENTS.include?(el.type)
-            buffer << el
           elsif Token === el && el.type == :legato_tie
             @seen_legato = true
             @in_legato = true

data/lib/ramekin/note_aggregator.rb

@@ -13,6 +13,10 @@ module Ramekin
       @extensions = extensions
     end
 
+    def meta
+      @note.meta
+    end
+
     def start
       @note.start
     end
@@ -58,6 +62,8 @@ module Ramekin
     end
 
     def length_amk(div)
+      return '=0' if ticks == 0
+
       if ticks % div != 0
         divisible = div == 2 ? 'even' : "divisible by #{div}"
         error!("too fast! tick count must be #{divisible} at this tempo", el: self)
@@ -69,6 +75,21 @@ module Ramekin
       KNOWN_LENGTHS.fetch(t) { "=#{t}" }
     end
 
+    NOTES = { 'c' => 0, 'd' => 2, 'e' => 4, 'f' => 5, 'g' => 7, 'a' => 9, 'b' => 11 }
+    def note_hex
+      @note_hex ||= begin
+        out = 0x80
+        out += 12 * (octave - 1)
+        @note.value =~ /(\w)([+-])?/
+        out += NOTES.fetch($1) # trust the tokenizer
+
+        out += 1 if $2 == '+'
+        out -= 1 if $2 == '-'
+
+        out
+      end
+    end
+
     def octave_amk(current_octave=nil)
       return '' if rest? || tie?
 
@@ -109,7 +130,8 @@ module Ramekin
 
         case ext
         when /\A=(\d+)\z/ then $1.to_i
-        when '0' then 192 * 2
+        # special case for a 0-length note, useful for bends
+        when '0' then 0
         when /\A(\d+)\z/ then 192 / $1.to_i
         when /\A(\d+)[.]\z/ then 192 * 3 / ($1.to_i * 2)
         else
@@ -134,6 +156,14 @@ module Ramekin
       error! "empty CombinedRestEvent" if rests.empty?
     end
 
+    def tie?
+      false
+    end
+
+    def meta
+      @rests.first.meta
+    end
+
     def start
       @rests.first.start
     end

data/lib/ramekin/renderer.rb

@@ -34,6 +34,12 @@ module Ramekin
     def render(&b)
       return render_string unless block_given?
 
+      if ENV['RAMEKIN_DEBUG'] == '1'
+        old_b = b
+        @so_far = StringIO.new
+        b = lambda { |chunk| @so_far << chunk; old_b.call(chunk) }
+      end
+
       render_preamble(&b)
 
       @track.channels.compact.each { |c| render_channel(c, &b) }
@@ -115,6 +121,16 @@ module Ramekin
         @current = el = next!
 
         case el
+        when Bend
+          old_tick = @tick
+          @tick += el.ticks
+          if (old_tick-1) / 192 != (@tick-1) / 192
+            yield "\n"
+          end
+
+          yield el.to_amk(@octave, @track.meta.divisor)
+
+          @octave = el.ending_octave
         when NoteEvent
           old_tick = @tick
           @tick += el.ticks
@@ -124,7 +140,7 @@ module Ramekin
           divisor = @track.meta.divisor
 
           yield el.to_amk(@octave, @track.meta.divisor)
-          @octave = el.octave unless el.rest?
+          @octave = el.octave unless el.tie? || el.rest?
         when MacroDefinition
           # pass
         when LegatoStart, LegatoLastNote
@@ -161,7 +177,7 @@ module Ramekin
         else
           @octave = nil
           unless @instrument_index.key?(token.value)
-            error! "undeclared instrument @#{token.value}"
+            return error! "undeclared instrument @#{token.value}"
           end
 
           yield "@#{@instrument_index[token.value]}"
@@ -208,6 +224,12 @@ module Ramekin
         when 'C' then 10
         end
 
+        if pan > 20
+          return error! 'invalid pan (max yL10)'
+        elsif pan < 0
+          return error! 'invalid pan (max yR10)'
+        end
+
         yield "y#{pan}"
 
       when :p
@@ -241,9 +263,6 @@ module Ramekin
       # triplets are handled in NoteAggregator
       when :lbrace, :rbrace
         # pass
-      when :rbrace
-        yield '}'
-
       else
         error! "unexpected token type: #{token.type}"
       end
@@ -256,10 +275,10 @@ module Ramekin
       if time.nil?
         "v#{vol}"
       else
-        time = time.to_i
+        time = time.to_i / @track.meta.divisor
         time = 255 if time > 255
         time = 0 if time < 0
-        sprintf("$E8$%02x$%02x", time, vol)
+        sprintf("$e8$%02x$%02x", time, vol)
       end
     end
 
@@ -267,23 +286,6 @@ module Ramekin
       case token.value
       when 'SPC'
         # pass
-      when 'bend'
-        note = next!
-
-        error! '#bend must be followed by a note' unless NoteEvent === note
-        error! 'cannot #bend to a rest' if note.rest?
-
-        ticks = sprintf("%02x", note.ticks)
-        yield "$dd$#{ticks}$#{ticks}#{note.octave_amk}#{note.note.value}"
-
-        case peek
-        when NoteEvent
-          peek.extensions.concat(note.extensions)
-        else
-          yield "^=#{note.ticks}"
-        end
-
-        @octave = note.octave
       when 'legato'
         yield '$f4$01'
       when 'echo/toggle'

data/lib/ramekin.rb

@@ -11,6 +11,7 @@ require_relative 'ramekin/tokenizer'
 require_relative 'ramekin/processor'
 require_relative 'ramekin/macros'
 require_relative 'ramekin/note_aggregator'
+require_relative 'ramekin/bends'
 require_relative 'ramekin/legato'
 require_relative 'ramekin/loop_allocator'
 require_relative 'ramekin/meta'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ramekin
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.2.1
 platform: ruby
 authors:
 - jneen
 bindir: gembin
 cert_chain: []
-date: 2025-03-06 00:00:00.000000000 Z
+date: 2025-03-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: strscan
@@ -77,6 +77,7 @@ files:
 - lib/ramekin/amk_runner.rb
 - lib/ramekin/amk_runner/sample_groups.rb
 - lib/ramekin/amk_setup.rb
+- lib/ramekin/bends.rb
 - lib/ramekin/channel_separator.rb
 - lib/ramekin/cli.rb
 - lib/ramekin/config.rb