ramekin 0.0.10 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6d502b095f92786dc1c94da24e1144d744f8462f609a1d7623a9c46a541b5f9
-  data.tar.gz: 2de364d731e7760f8dc1111d18aad6b4de5a5b713e5d3ec424af3c80f180ec52
+  metadata.gz: 999d9354b8f31a49551d78893fe986a38f9ff8ca4e2ecc880970bdde628e8ac0
+  data.tar.gz: f3e29e81592be14e9b888de2ca731cbc285fb43763b80e2320486bbf17694434
 SHA512:
-  metadata.gz: 0a1aed7dde26850dd627da1ac9e0b7445d41097128dcae4ba464afc7c0868e7905f8adb2b395bfc93aa3d9ea28e7739cb2e5bb36fdf6de679726d938913de179
-  data.tar.gz: 6402af26f0cbd457a8246121eefcfe976a5331925ed97849520fec05faafbdf47c8124a95bdb398a38115dcb6a6dce2fd7ff0bac6e1678787d433e4e7cfcc247
+  metadata.gz: e4d0bba97851f3d9039710c750fbd1f2cdfb65f84d8279b628901b1e7e23990f5e7319264ba4f3dca4058bc7bc5b99b21078c8d65c0a20da06bb50cb6b740539
+  data.tar.gz: b69597095b27d7a1bfb268729bf44c510bdcf4109a747a677f6a5f9665948a71dcaf4a4c696d976c480373b84762b699cb2aad71749dfc21f64997e231ab9d8d

data/README.md

@@ -1,3 +1,9 @@
+<style>
+img { float: right; }
+</style>
+
+![Ramekin logo](logo.svg "Ramekin logo")
+
 # Ramekin
 
 Ramekin is a pre-processor for AddMusicK syntax that is in very early development.
@@ -53,6 +59,9 @@ ramekin compile -i filename.rmk [flags]
         --play
             play the generated SPC file. will automatically
             set up an SPC player if none is detected.
+        --package my-cool-folder/
+            create a package directory suitable for submission
+            to SMWC, complete with README and packaged samples.
         --wav filename.wav
         --wav filename.wav:N
             (non-windows only)
@@ -93,6 +102,7 @@ A list of some ramekin preprocessor features (see `spec/rmk` for some examples!)
 
 * The metadata section (before any channels) is fairly different, I recommend reading the metadata part of the guide below.
 * Macros ("replacements") are implemented in a much more robust way (*with* tokenization), and can no longer interrupt other tokens. The generated txt will not contain any replacements.
+* Loops can be given arbitrary names using any combination of letters, numbers, underscores, or dashes. `(my-cool-loop)[ ... ]` is valid syntax. These are case sensitive, and are assigned numbers when compiled to AddmusicK syntax.
 * Adopted the transposition syntax `_+N`, `_-N`, and `_0` from General MML. Compiles to `$fa$02$XX`.
 * `#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.
@@ -119,7 +129,7 @@ b8 #bend >>c16^16 ^^4
 
 * In ramekin, there is no difference between instrument `#adsr` syntax and the one in the pattern data. They are both compiled to their respective syntaxes in the txt.
 
-* Tempo can alternately be declared with `#bpm:128`. This will be converted to the nearest `tXX` command. A major TODO is automatic `#halvetempo` etc.
+* Tempo can alternately be declared with `#bpm:128`. This will be converted to the nearest `tXX` command. If the tempo is over `t60` (`#bpm:146`), the tempo and all note and event lengths will be halved automatically. This is similar to `#halvetempo` except that it is done automatically.
 * `p0,0` compiles to `$df`.
 * "Legato tie" represented by `~`, which will use `$f4$01` at appropriate times to cause the note transition to be played legato.
 * If you ever want to see what exactly Ramekin is generating, just use `--txt` and you can inspect the generated AddmusicK syntax manually!
@@ -163,9 +173,6 @@ w150
 
 ; sets the bpm. (todo: mention the reasonable range for this)
 #bpm:130
-
-; echo settings. this syntax is likely to change in the future, because it sucks
-#echo $ef$ff$df$df $f1$02$cf$01
 ```
 
 ### Instrument definitions
@@ -217,16 +224,20 @@ It is generally advised to stick with the default tuning. The `o5` declaration s
 Echo settings can be set up with the `#echo/...` family of directives:
 
 ```elisp
+; select which channels have echo enabled
 #echo/channels:0,1,2,3
 ; or
 #echo/channels:all
 ; or
 #echo/channels:none
 
-#echo/volume:20    ; range from -7f to 80, use negatives for surround
+#echo/volume:20    ; range from -80 to 7f, use negatives for surround
 #echo/volume:20,30 ; set different values for left vs right echo
-#echo/feedback:48  ; range from -7f to 80, use negatives for surround
+#echo/feedback:48  ; range from -80 to 7f, use negatives for surround
 #echo/fir:1        ; 1 or 0 to enable/disable the FIR filter
+
+; later, you can use this to toggle the echo on a channel.
+#echo/toggle
 ```
 
 
@@ -296,7 +307,7 @@ Personally, I tend to use `l16` across the whole track for consistency.
 
 Just as in Addmusick, there are two kinds of loops:
 
-* Regular loops, marked with `[ ]`, which can optionally be tagged with a number, as in `(1)[ ]`. These can not only loop immediately but also be called at arbitrary points.
+* Regular loops, marked with `[ ]`, which can optionally be tagged with a name, as in `(my-cool-loop)[ ]`. These can not only loop immediately but also be called at arbitrary points.
 * Super loops, marked with `[[ ]]`, which can only loop immediately, but can nest either inside or outside of regular loops.
 
 This is best shown with an example:
@@ -306,11 +317,75 @@ This is best shown with an example:
 [ defg ]4    ; plays defg four times (regular loop)
 [[ abcd ]]4  ; plays abcd four times (superloop)
 *            ; calls the last defined regular loop, in this case plays defg
-(01)[ fedc ] ; defines a loop named (01), also plays fedc immediately
-(01)         ; calls the loop (01)
-(01)2        ; calls the loop (01) twice
+*3           ; same thing but 3 times
+(blungus)[ fedc ] ; defines a loop named (blungus), also plays fedc immediately
+(blungus)         ; calls the loop (blungus)
+(blungus)2        ; calls the loop (blungus) twice
 ```
 
 ### Expression and effects
 
-Volume can be set with `vXXX`, where `XXX` is a number between 0 and 255.
+#### Volume Expression
+
+Volume can be set with `vXXX`, where `XXX` is a number between 0 and 255. This command also sets the current "reference volume", which can be referenced with commands `v+XX` and `v-XX`, where XX is a number to be added or subtracted to the reference volume. This way, you can add dynamics to your drums or melody lines, while also easily being able to change the overall volume of the section.
+
+#### Pitch Expression
+
+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 `^^`:
+
+```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
+```
+
+#### Panning Expression
+
+Panning can be specified with the command `yLX` or `yRX`, where X is a number from 1-10. To reset panning to the center, use `yC`:
+
+```elisp
+yR10 ; maximum pan right
+yR2  ; tasteful pan right
+yC   ; pan center
+yL2  ; tasteful pan left
+yl10 ; maximum pan left
+```
+
+## Hex
+
+For those who want to use AddmusicK features that are not currently supported by Ramekin, Ramekin still supports manual entry of hex values with `$XX`. While these can be made slightly easier to use with macros, I would very much appreciate it if you could open an issue here or contact me via SMWC or Discord if you find you are using these heavily.
+
+## Macros
+
+To make your life easier, Ramekin implements a very similar macro ("replacement") system as AddmusicK - allowing you to define all manner of custom shortcuts for maximum efficiency and tweakability. (Note that Ramekin's implementation of macros is far more robust than AddmusicK's, and will not interrupt other tokens - e.g. a macro called `F` will not be applied to something like `$EF`).
+
+A macro looks like this:
+
+```elisp
+"MY_COOL_MACRO=@smwacousticbass o3 v150"
+```
+
+Now whenever you type `MY_COOL_MACRO` in a channel, it will be as if you typed `@smwacousticbass o3 v150`. This can be used to define all sorts of helpers, including some dynamics helpers:
+
+```elisp
+"F=v+0" ; forte
+"M=v-20" ; mezzo
+"P=v-40" ; piano
+```
+
+Or drum instrument helpers:
+
+```elisp
+"K=@smwkick o4"
+"S=@smwsnare o4"
+"H=@smwshaker o4"
+```
+
+Or anything else you might find helpful.
+
+# Thank you for trying out Ramekin!
+
+If you find any bugs, please report them in the issue tracker here on Codeberg. If you have questions, design ideas, or complaints, or just want to chat, please feel free to ask anything in [my discord](https://jneen.ca/discord). Cheers!

data/lib/ramekin/cli.rb

@@ -44,6 +44,9 @@ module Ramekin
         '(compiles and installs spct - requires git,cmake,make)'
       end
       $stderr.puts "            #{default_text}"
+      $stderr.puts "        --package my-cool-folder/"
+      $stderr.puts "            create a package directory suitable for submission"
+      $stderr.puts "            to SMWC, complete with README and packaged samples."
       unless Ramekin.config.windows?
         $stderr.puts "        --wav filename.wav"
         $stderr.puts "        --wav filename.wav:N"
@@ -162,6 +165,7 @@ module Ramekin
       outer_chain = Processor.compose(
         MacroExpander,
         ScanForL,
+        LoopAllocator,
       )
 
       expanded = outer_chain.call(tokens)

data/lib/ramekin/errors.rb

@@ -15,7 +15,7 @@ module Ramekin
     def self.error!(e, nesting: 0)
       all << e
 
-      if ENV['RAMEKIN_DEBUG'] == '1'
+      if ENV['RAMEKIN_DEBUG'] == '1' && ENV['DISABLE_PRY'] != 'true'
         if nesting >= 0
           Pry.config.hooks.add_hook(:before_session, :ramekin) do |output, binding, pry|
             Pry.config.hooks.delete_hook(:before_session, :ramekin)
@@ -25,6 +25,8 @@ module Ramekin
 
         binding.pry
       end
+
+      nil
     end
 
     def initialize(start, fin, message)

data/lib/ramekin/legato.rb

@@ -1,6 +1,6 @@
 module Ramekin
   class LegatoStart < Element
-    def to_amk
+    def to_amk(*)
       '$f4$01'
     end
 
@@ -32,10 +32,10 @@ module Ramekin
       @note.ticks / 2
     end
 
-    def to_amk(current_octave=nil)
+    def to_amk(current_octave=nil, divisor=1)
       post_ticks = @note.ticks - ticks
       post_len = KNOWN_LENGTHS.fetch(post_ticks) { "=#{post_ticks}" }
-      "#{octave_amk(current_octave)}#{note_name}#{length_amk}$f4$01^#{post_len}"
+      "#{octave_amk(current_octave)}#{note_name}#{length_amk(divisor)}$f4$01^#{post_len}"
     end
 
     def inspect

data/lib/ramekin/loop_allocator.rb

@@ -0,0 +1,47 @@
+module Ramekin
+  class LoopAllocator < Processor
+    def call(&b)
+      tokens = @stream.to_a
+
+      loop_defs = tokens.select do |tok|
+        Token === tok && tok.type == :loop && tok.value && !tok.value.empty?
+      end
+
+      index = 0
+      indices = {}
+      used = Set.new
+
+      numbered, named = loop_defs.partition do |tok|
+        /\A\d+\z/.match?(tok.value)
+      end
+
+      numbered.each do |tok|
+        num = indices[tok.value] = tok.value.to_i
+        tok.meta[:number] = num
+        used << num
+      end
+
+      named.each do |tok|
+        if indices.key?(tok.value)
+          error! "multiple definitions of (#{tok.value})", el: tok
+          next
+        end
+
+        index += 1
+        index += 1 while used.include?(index)
+        indices[tok.value] = index
+        tok.meta[:number] = index
+      end
+
+      tokens.each do |token|
+        if Token === token && token.type == :loop_call
+          token.meta[:number] = indices.fetch(token.value) do
+            error! "no such loop", el: token
+          end
+        end
+
+        yield token
+      end
+    end
+  end
+end

data/lib/ramekin/meta.rb

@@ -48,6 +48,34 @@ module Ramekin
       )
     end
 
+    def t_value
+      t_with_divisor[0]
+    end
+
+    def divisor
+      t_with_divisor[1]
+    end
+
+    def t_with_divisor
+      return [50, 1] if @tempo.nil?
+
+      @t_with_divisor ||= begin
+        t = case @tempo.type
+        when :t then @tempo.value
+        when :bpm then (@tempo.value.to_f * 8192 / 20025.0)
+        end
+
+        t = t.to_f
+        divisor = 1
+        while t > 60
+          t /= 2
+          divisor *= 2
+        end
+
+        [t.round, divisor]
+      end
+    end
+
     def parse
       loop do
         break if @elements.empty?
@@ -58,7 +86,7 @@ module Ramekin
         when :amk then @amk = @current
         when :option then @options[@current.value] = true
         when :w then @volume = @current
-        when :t, :bpm then @tempo = @current
+        when :t, :bpm then @tempo = @current; @t_with_divisor = nil
         else
           error! 'invalid token in header'
         end
@@ -90,8 +118,6 @@ module Ramekin
         @instruments << Instrument.new(@current_pack, @current_directive, name, path, extensions)
       when 'default', 'optimized' then @sample_groups << @current
 
-      # TODO: real echo syntax
-      when 'echo' then @echo = expect_args(*([:hex] * 8))
       when 'echo/channels'
         channels = @current_directive.values[1]
         case channels

data/lib/ramekin/note_aggregator.rb

@@ -57,10 +57,16 @@ module Ramekin
       end
     end
 
-    def length_amk
+    def length_amk(div)
+      if ticks % div != 0
+        divisible = div == 2 ? 'even' : "divisible by #{div}"
+        error!("too fast! tick count must be #{divisible} at this tempo", el: self)
+      end
+
+      t = ticks / div
       # we use l16
-      return '' if ticks == 12
-      KNOWN_LENGTHS.fetch(ticks) { "=#{ticks}" }
+      return '' if t == 12
+      KNOWN_LENGTHS.fetch(t) { "=#{t}" }
     end
 
     def octave_amk(current_octave=nil)
@@ -80,8 +86,8 @@ module Ramekin
       end
     end
 
-    def to_amk(current_octave=nil)
-      return "#{octave_amk(current_octave)}#{note_name}#{length_amk}"
+    def to_amk(current_octave=nil, divisor=1)
+      return "#{octave_amk(current_octave)}#{note_name}#{length_amk(divisor)}"
     end
 
     def repr
@@ -94,7 +100,7 @@ module Ramekin
 
     def ticks
       if @extensions.empty? && default_length.nil?
-        error! "no length and no default specified with l", el: @note
+        return 192 / 16
       end
 
       exts = @extensions

data/lib/ramekin/renderer.rb

@@ -101,7 +101,7 @@ module Ramekin
         yield "}\n\n"
       end
 
-      yield "t#{tempo_of(m.tempo)} ; main tempo (0-60)\n" if m.tempo
+      yield "t#{m.t_value} ; main tempo (0-60)\n" if m.tempo
       yield "w#{m.volume.value} ; main volume (0-255)\n" if m.volume
       yield "l16\n\n"
 
@@ -143,12 +143,14 @@ module Ramekin
           if (old_tick-1) / 192 != (@tick-1) / 192
             yield "\n"
           end
-          yield el.to_amk(@octave)
+          divisor = @track.meta.divisor
+
+          yield el.to_amk(@octave, @track.meta.divisor)
           @octave = el.octave unless el.rest?
         when MacroDefinition
           # pass
         when LegatoStart, LegatoLastNote
-          yield el.to_amk
+          yield el.to_amk(@octave, @track.meta.divisor)
         when Instrument
           yield "@#{@instrument_index[el.name.value]}"
         when Token
@@ -241,14 +243,14 @@ module Ramekin
         yield " [[ "
       when :loop
         if token.value
-          yield " (#{token.value})[ "
+          yield " (#{token.meta[:number]})[ "
         else
           yield " [ "
         end
       when :loop_end
         yield " ]#{token.value} "
       when :loop_call
-        yield " (#{token.values[0]})#{token.values[1]} "
+        yield " (#{token.meta[:number]})#{token.values[1]} "
       when :star
         yield "*#{token.value}"
       when :superloop_end

data/lib/ramekin/tokenizer.rb

@@ -243,9 +243,9 @@ module Ramekin
       return [:superloop_end, m(1)] if match /\]\](\d*)/
 
       return [:remote_def, m(1)] if match /[(]!(\d+)[)]\[/
-      return [:loop, m(1)] if match /(?:[(](\d+)[)])?\[/
+      return [:loop, m(1)] if match /(?:[(]([\w-]+)[)])?\[/
       return [:loop_end, m(1)] if match /\](\d*)/
-      return [:loop_call, m(1), m(2)] if match /[(](\d+)[)](\d+)?/
+      return [:loop_call, m(1), m(2)] if match /[(]([\w-]+)[)](\d+)?/
 
       # this needs a reparse
       return remote(:remote_call, m(1)) if match /[(]!(\d*)/

data/lib/ramekin.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ramekin
 version: !ruby/object:Gem::Version
-  version: 0.0.10
+  version: 0.1.1
 platform: ruby
 authors:
 - jneen
 autorequire:
 bindir: gembin
 cert_chain: []
-date: 2025-02-20 00:00:00.000000000 Z
+date: 2025-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: strscan
@@ -85,6 +85,7 @@ files:
 - lib/ramekin/element.rb
 - lib/ramekin/errors.rb
 - lib/ramekin/legato.rb
+- lib/ramekin/loop_allocator.rb
 - lib/ramekin/macros.rb
 - lib/ramekin/meta.rb
 - lib/ramekin/note_aggregator.rb