ramekin 0.0.11 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f9fce3c7ec61c39d7597621bf02fbd71788df731ee7a98cb89018549275eb44e
-  data.tar.gz: 0c123977b81c24d92f4f6b3514973ca4713aedf4c8292aa30d126f6b20d541ea
+  metadata.gz: f693295d87c86072d5d220f3a9cfed4b8a19aa5ae1bcfc468c4554eb89063945
+  data.tar.gz: 5d4890321e9f3d49ce4487e0539babe104bb03a1719ecf641040d22eadc7ba2a
 SHA512:
-  metadata.gz: 0d4484cc76d708e7b1d36929e2a4b95efe19b34ad5882f51e71d526bd08d1c500725de40054b17e5401922fd388854a2866fca0a2210a15589bdbd5e46bc85b4
-  data.tar.gz: cd54afeb74289aaf055344b45aca6b75679b494db546308c0d86d05866c0a4e4cc855921232f7c6507ac8cc6a2b8e6656247ba6ea579806c1589786470ce2f31
+  metadata.gz: 530beedb41422b51818f44445802ff95ba1b23c73f43e24b1d44c563bbe4479c46ac55c3a6c26ee722e1dd4e555ef61bd66f501380853085cd766734117b919b
+  data.tar.gz: 45a1589c63119cef6fc062feff81afe66445356974260953bbb8adb79a25e570329afecaf695b6b4781bbce9b067b25d4d85c5c7d9fc257262a44e4d9c77c86b

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.
@@ -47,25 +53,26 @@ ramekin compile -i filename.rmk [flags]
             output amk txt to this file.
             use a single dash (-) to print txt to stdout.
         --spc filename.spc
-            attempt to invoke AddmusicK to output an SPC
-            requires ADDMUSICK_DIR and ASAR_COMMAND
-            to be set.
+            attempt to invoke AddmusicK to output an SPC.
         --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)
             render N seconds of the file to WAV.
 
-ramekin package [flags]
+ramekin pack [flags]
     flags:
         --update
-            download BRR packages from SMW Central.
+            download BRR packs from SMW Central.
         --search [text]
             search for BRR filenames.
         --list [text]
-            list all samples in packages matching [text].
+            list all samples in packs matching [text].
 
 ramekin setup [flags]
     flags:
@@ -93,6 +100,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 +127,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 +171,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 +222,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 +305,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 +315,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/gembin/ramekin

@@ -10,6 +10,11 @@ RAMEKIN_ASAR_DIR = './asar'
 RAMEKIN_SPC_PLAYER = '__auto__'
 RAMEKIN_VERSION = Gem.loaded_specs['ramekin'].version.to_s
 
+if ENV['RAMEKIN_DEBUG'] == '1'
+  require 'pry'
+  require 'pry-stack_explorer'
+end
+
 require_relative '../lib/ramekin'
 require_relative '../lib/ramekin/cli'
 

data/lib/ramekin/cli.rb

@@ -32,9 +32,7 @@ module Ramekin
       $stderr.puts "            output amk txt to this file."
       $stderr.puts "            use a single dash (-) to print txt to stdout."
       $stderr.puts "        --spc filename.spc"
-      $stderr.puts "            attempt to invoke AddmusicK to output an SPC"
-      $stderr.puts "            requires ADDMUSICK_DIR and ASAR_COMMAND"
-      $stderr.puts "            to be set."
+      $stderr.puts "            attempt to invoke AddmusicK to output an SPC."
       $stderr.puts "        --play"
       $stderr.puts "            play the generated SPC file. will automatically"
       $stderr.puts "            set up an SPC player if none is detected."
@@ -44,6 +42,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"
@@ -51,13 +52,14 @@ module Ramekin
       end
       $stderr.puts ""
       $stderr.puts "ramekin package [flags]"
+      $stderr.puts "ramekin pack [flags]"
       $stderr.puts "    flags:"
       $stderr.puts "        --update"
-      $stderr.puts "            download BRR packages from SMW Central."
+      $stderr.puts "            download BRR packs from SMW Central."
       $stderr.puts "        --search [text]"
       $stderr.puts "            search for BRR filenames."
       $stderr.puts "        --list [text]"
-      $stderr.puts "            list all samples in packages matching [text]."
+      $stderr.puts "            list all samples in packs matching [text]."
       $stderr.puts ""
       $stderr.puts "ramekin setup [flags]"
       $stderr.puts "    flags:"
@@ -162,6 +164,7 @@ module Ramekin
       outer_chain = Processor.compose(
         MacroExpander,
         ScanForL,
+        LoopAllocator,
       )
 
       expanded = outer_chain.call(tokens)
@@ -172,7 +175,6 @@ module Ramekin
         NoteAggregator,
         RestAggregator,
         Legato,
-        LoopAllocator,
         Inspector,
       )
 
@@ -364,7 +366,7 @@ module Ramekin
       case argv[0]
       when 'compile'
         compile(*argv[1..])
-      when 'package'
+      when 'package', 'pack'
         package(*argv[1..])
       when 'setup'
         setup(*argv[1..])

data/lib/ramekin/legato.rb

@@ -1,6 +1,6 @@
 module Ramekin
   class LegatoStart < Element
-    def to_amk
+    def to_amk(*)
       '$f4$01'
     end
 

data/lib/ramekin/loop_allocator.rb

@@ -4,7 +4,7 @@ module Ramekin
       tokens = @stream.to_a
 
       loop_defs = tokens.select do |tok|
-        Token === tok && tok.type == :loop && !tok.value.empty?
+        Token === tok && tok.type == :loop && tok.value && !tok.value.empty?
       end
 
       index = 0

data/lib/ramekin/meta.rb

@@ -118,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/renderer.rb

@@ -239,6 +239,8 @@ module Ramekin
         else
           yield "p#{token.value} "
         end
+      when :n
+        yield "n#{token.value}"
       when :superloop
         yield " [[ "
       when :loop

data/lib/ramekin/sample_pack.rb

@@ -272,6 +272,7 @@ module Ramekin
         return
       end
 
+      $stderr.puts "downloading: #{name}:#{id}"
       download!
     end
 

data/lib/ramekin/tokenizer.rb

@@ -258,7 +258,7 @@ module Ramekin
       return [:l, m(1)] if match /l(\d+)/
       return [:amp] if match /[&]/
       return [:q, m(1)] if match /q(\d(?:,\h)?)/
-      return [:n, m(1)] if match /n(\h\h?)/
+      return [:n, m(1)] if match /n(\h\h)/
 
       error! "unknown token near: #{@scanner.peek(10)}", el: @last_token
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ramekin
 version: !ruby/object:Gem::Version
-  version: 0.0.11
+  version: 0.1.2
 platform: ruby
 authors:
 - jneen
 autorequire:
 bindir: gembin
 cert_chain: []
-date: 2025-02-27 00:00:00.000000000 Z
+date: 2025-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: strscan