ramekin 0.0.5b

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 42635a3432e6ba8fc0f53454dab984170902a215d2530834278b7c70e088b354
+  data.tar.gz: 265b13b18ce9a6840a5d550e675b2ed20d417d95edf01af57467a2b8cdd83c95
+SHA512:
+  metadata.gz: 5740cf99c3ba2ec568c2075d1ba40ee96a790c3617638e7c17f293051a0ad02803e4ebe7f20e8f76315050b2cfb55149918932eddad3675c3613795529b5f686
+  data.tar.gz: a42be3e89c445f84639fcbc963a199a9ebaf84b174dde945526914a49b881ca2b74ad8ee346527c2ffb460deb1a5a4ff3c331842d989a730807ca6dce61992a6

data/README.md

@@ -0,0 +1,277 @@
+# Ramekin
+
+Ramekin is a pre-processor for AddMusicK syntax that is in very early development.
+
+# Installation
+
+1. [Install Ruby](https://ruby-lang.org). Windows users can use [RubyInstaller](https://rubyinstaller.org/).
+2. [Download the script](https://codeberg.org/jneen/ramekin/releases).
+3. Install the scripts:
+    - For Windows users, put both `ramekin` and `ramekin.bat` in `%LOCALAPPDATA\Microsoft\WindowsApps\`.
+    - For MacOS and Linux users, ignore `ramekin.bat` - make the script executable with `chmod +x` and put it somewhere on your PATH.
+4. Run `ramekin setup` to set up dependencies and download sample packs. You will need about 90M of free space.
+
+# Usage
+
+```
+usage: ramekin [command] [flags]
+    (default command: compile)
+
+ramekin compile -i filename.rmk [flags]
+    flags:
+        -h --help
+            display this message
+        -i filename.rmk
+            set the input file
+        --txt filename.txt
+            output amk txt to this file
+        --spc filename.spc
+            attempt to invoke AddmusicK to output an SPC
+            requires ADDMUSICK_DIR and ASAR_COMMAND
+            to be set.
+        --play
+            play the generated SPC file. will automatically
+            set up an SPC player if none is detected.
+        --wav filename.wav
+        --wav filename.wav:N
+            (non-windows only)
+            render N seconds of the file to WAV.
+
+ramekin package [flags]
+    flags:
+        --update
+            download BRR packages from SMW Central.
+        --search [text]
+            search for BRR filenames.
+        --list [text]
+            list all samples in packages matching [text].
+
+ramekin setup [flags]
+    flags:
+        --amk
+            downloads and sets up AddMusicK and asar.
+            (requires cmake and make to be available)
+        --packages
+            downloads packages from SMW Central.
+            (equivalent to package --update)
+        --spc
+            downloads and sets up a default SPC player.
+        --all (default)
+            runs all of the above setup steps
+        --force
+            deletes and redownloads files instead of skipping.
+```
+
+# Configuration
+
+The first time ramekin runs, it will create a configuration file in `~/.ramekin/config.yml` (where `~` is your [home directory](https://en.wikipedia.org/wiki/Home_directory)). Edit this file with your favourite text editor, and be sure to remove the `#` from the start of lines you want to take effect. If you want Ramekin to keep its files in some other place, override the `RAMEKIN_HOME` environment variable.
+
+# If you already know AddmusicK
+
+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.
+* 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.
+* `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.
+```elisp
+; bends to c two octaves up for two 16th notes, then continues for a quarter note
+b8 #bend >>c16^16 ^^4
+```
+* Instruments are named rather than numbered. See `doc/smw-instruments.rmk` for a list.
+* Switching instruments always sets that instrument's default octave, by default `o4`. It does *not* reset transposition (you can use `_0` for that).
+* Samples are loaded directly from SMWCentral using `#pack` syntax:
+
+```elisp
+; references the BRR pack "Chrono Trigger" from SMW Central
+#pack "Chrono Trigger"
+
+; declares an instrument @kick with tuning parameters parsed from the BRR pack
+#instrument @kick "Kick"
+
+; parameters and default octave can be overridden
+#instrument @crash "Crash Cymbal" o4 #tuning:1FBC #adsr:0,0,7,1F
+```
+
+* 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.
+* `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!
+
+# Syntax
+
+Ramekin syntax is very similar to AddmusicK syntax. Comments begin with `;` and span to the end of the line, and most commands are either single characters, or directives marked with `#`.
+
+## Metadata / preamble
+
+The top of a Ramekin file, before the first channel is declared, is the *preamble*. Here, various commands can be used, starting with `#`.
+
+### Metadata commands
+
+These commands set important metadata headers for the SPC.
+
+```elisp
+#title "My cool songle"
+#game "title of the game, if any"
+#author "my name"
+#comment "usually something about who ported the track"
+```
+
+Additionally, you can specify additional `#readme` text to be included in the packaged song:
+
+```elisp
+#readme "
+Here is some very important information about running this track.
+"
+```
+
+Finally, some general options can be set:
+
+```elisp
+; causes the track not to speed up when the timer is low
+#option TempoImmunity
+
+; sets the global volume, 0-255.
+; Try to aim for -21 to -19 lufs to balance well with sound effects.
+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
+
+#### Default Instruments
+
+Ramekin can use the `#default` and `#optimized` native sample groups for SMW. One of these directives must be included for sound effects to work properly in the game. Using native SMW instruments is the easiest way to get started quickly.
+
+The `#default` sample group is implied if nothing else is specified, but you can use `#optimized` if you are running low on ARAM (more on that later).
+
+To see the full list of available native instruments, see `doc/smw-instruments.rmk`
+
+#### Sample Packs
+
+To get more diverse sounds on the SNES, it is often nice to use samples, either ripped from other games or converted to BRR (the SNES's native sample format).
+
+Ramekin allows you to extremely easily use BRR packs from SMW Central's repositories. These not only contain BRR samples, but also the tuning and ADSR data to make them sound great by default.
+
+To load a pack from SMW Central, use `#pack` with the pack's name on SMW Central. For example, let's say I wanted to use samples from Chrono Trigger. I can search that with:
+
+```console
+ramekin package --list chrono
+```
+
+This will show us a pack named "Chrono Trigger" along with a bunch of files with a `.brr` extension. To use the pack, add:
+
+```elisp
+#pack "Chrono Trigger"
+```
+
+Then, to load, say, the sitar from the pack, we use:
+
+```elisp
+#instrument @sitar "Sitar.brr"
+```
+
+This defines a new instrument called `@sitar` to point to `Sitar.brr` with the default settings. You can also leave off the ".brr" extension if you like. Later, you can use the command `@sitar` to switch to this instrument.
+
+After the instrument declaration, you can use several commands to change the default settings, such as `#adsr`, `#tuning` and `o`:
+
+```elisp
+#instrument @sitar #adsr:0,4,2,23 #tuning:1a2f o5
+```
+
+It is generally advised to stick with the default tuning. The `o5` declaration sets the *default octave* for the instrument to octave 5 (the default is 4). Whenever this instrument is selected, Ramekin will insert a switch to the specified octave.
+
+## Channel Commands
+
+With your metadata all set up, it's time to add some notes!
+
+SNES audio is organized into 8 channels, numbered 0-7. But in the context of a romhack, channels 6 and 7 are reserved for sound effects.
+
+**This is the biggest limitation of romhack music: You must generally arrange your music to fit on 6 channels.** Each channel can only play one note at a time - for chords, you must use multiple channels. However, channels can switch instruments extremely quickly - so things can be interleaved if you are clever with instrument switches.
+
+### Notes
+
+To start adding notes to a channel, use `#N`, where N is the channel number:
+
+```elisp
+#0
+; now we're in channel 0!
+```
+
+Next, switch to an instrument, and add some notes:
+
+```elisp
+#0
+@smwacousticbass
+o3
+c8d8e8f8
+```
+
+this plays 8th notes c, d, e, and f in octave 3 on the instrument `@smwacousticbass`.
+
+For sharps and flats, use `+` and `-`, and for rests, use the special note `r`:
+
+```elisp
+#0 @smwacousticbass o5
+d8 e-8 f+8 g8 r2
+```
+
+This plays d, e-flat, f-sharp, g in 8th notes, followed by a half-note rest. To convert this to an spc, save this to a file named `my-cool-song.rmk`, and run
+
+```
+ramekin my-cool-song.rmk --spc my-cool-song.spc
+```
+
+This will create a file called `my-cool-song.spc`, which you can open with an SPC player. Notice that it loops to the beginning by default! The default behaviour of the AddMusicK/smw music system is to loop as soon as the first defined channel runs out of notes.
+
+To set the loop point somewhere that is not the beginning, use the `/` command:
+
+```elisp
+; will return to the / when it hits the loop point
+#0 @smwacousticbass o5
+d8 e-8 / f+8 g8 r2
+```
+
+For more complex note lengths, **dots** and **ties** are available. For example, `b8.` plays a `b` for a dotted eigth note length. This is equivalent to `b8^16`, which plays for an 8th note tied to a 16th note.
+
+Because it is common to play a bunch of fast notes all the same length, the `l` command allows setting a default length to use when no note length is specified. So our example from before is equivalent to:
+
+```elisp
+#0 @smwacousticbass o5
+l8 de-f+g r2
+```
+
+Personally, I tend to use `l16` across the whole track for consistency.
+
+### Loops and loop calls
+
+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.
+* 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:
+
+```elisp
+#0 @smwacousticbass l16
+[ 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
+```
+
+### Expression and effects
+
+Volume can be set with `vXXX`, where `XXX` is a number between 0 and 255.

data/gembin/ramekin

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+# Editable default configs.
+# These can be edited by packagers or by you if you're feeling spicy.
+# You can also override these values with environment variables (of the same name),
+# or with a file `config.yml` in RAMEKIN_HOME.
+RAMEKIN_HOME = '~/.ramekin'
+RAMEKIN_AMK_DIR = './addmusick'
+RAMEKIN_ASAR_DIR = './asar'
+RAMEKIN_SPC_PLAYER = '__auto__'
+RAMEKIN_VERSION = Gem.loaded_specs['ramekin'].version.to_s
+
+require_relative '../lib/ramekin'
+require_relative '../lib/ramekin/cli'
+
+Ramekin::CLI.main(*ARGV)

data/lib/ramekin/amk_runner/sample_groups.rb

@@ -0,0 +1,65 @@
+SAMPLE_GROUPS = <<~'___'
+#default
+{
+	"default/00 SMW @0.brr"!
+	"default/01 SMW @1.brr"!
+	"default/02 SMW @2.brr"!
+	"default/03 SMW @3.brr"!
+	"default/04 SMW @4.brr"!
+	"default/05 SMW @8.brr"!
+	"default/06 SMW @22.brr"!
+	"default/07 SMW @5.brr"!
+	"default/08 SMW @6.brr"!
+	"default/09 SMW @7.brr"!
+	"default/0A SMW @9.brr"!
+	"default/0B SMW @10.brr"!
+	"default/0C SMW @13.brr"!
+	"default/0D SMW @14.brr"
+	"default/0E SMW @29.brr"!
+	"default/0F SMW @21.brr"
+	"default/10 SMW @12.brr"!
+	"default/11 SMW @17.brr"
+	"default/12 SMW @15.brr"!
+	"default/13 SMW Thunder.brr"!
+}
+
+#optimized
+{
+	"optimized/00 SMW @0.brr"!
+	"optimized/01 SMW @1.brr"!
+	"optimized/02 SMW @2.brr"!
+	"optimized/03 SMW @3.brr"!
+	"optimized/04 SMW @4.brr"!
+	"optimized/05 SMW @8.brr"!
+	"optimized/06 SMW @22.brr"!
+	"optimized/07 SMW @5.brr"!
+	"optimized/08 SMW @6.brr"!
+	"optimized/09 SMW @7.brr"!
+	"optimized/0A SMW @9.brr"!
+	"optimized/0B SMW @10.brr"!
+	"optimized/0C SMW @13.brr"!
+	"optimized/0D SMW @14.brr"
+	"optimized/0E SMW @29.brr"!
+	"optimized/0F SMW @21.brr"
+	"optimized/10 SMW @12.brr"!
+	"optimized/11 SMW @17.brr"
+	"optimized/12 SMW @15.brr"!
+	"optimized/13 SMW Thunder.brr"!
+}
+
+#AMM
+{
+	"EMPTY.brr"!
+	"EMPTY.brr"
+	"EMPTY.brr"
+	"EMPTY.brr"
+	"EMPTY.brr"
+	"EMPTY.brr"
+	"EMPTY.brr"
+	"EMPTY.brr"
+	"EMPTY.brr"
+	"EMPTY.brr"
+	"EMPTY.brr"
+	"EMPTY.brr"
+}
+___

data/lib/ramekin/amk_runner.rb

@@ -0,0 +1,123 @@
+require 'fileutils'
+require_relative 'amk_runner/sample_groups'
+
+module Ramekin
+  class AMKRunner
+    def initialize(filename, meta, txt)
+      @filename = File.expand_path(filename)
+      @amk_path = Ramekin.config.amk_dir
+      AMKSetup.setup! unless AMKSetup.setup_ok?
+      @meta = meta
+      @txt = txt
+      @workdir = Dir.mktmpdir
+    end
+
+    def basename
+      File.basename(@filename).chomp('.rmk')
+    end
+
+    def ln(src, dest)
+      # windows permissions don't allow linking from temp dirs
+      if Ramekin.config.windows?
+        FileUtils.cp_r(src, dest)
+      else
+        FileUtils.ln_s(src, dest)
+      end
+    end
+
+    def compile
+      FileUtils.mkdir_p("#@workdir/music/ramekin")
+      FileUtils.mkdir_p("#@workdir/SPCs")
+      FileUtils.mkdir_p("#@workdir/stats")
+
+      if Ramekin.config.windows?
+        ln("#@amk_path/AddmusicK.exe", "#@workdir/AddmusicK.exe")
+        ln("#@amk_path/asar.dll", "#@workdir/asar.dll")
+      else
+        ln("#@amk_path/AddmusicK", "#@workdir/AddmusicK")
+        ln(Ramekin.config.asar_lib, "#@workdir/libasar.#{Ramekin.config.lib_ext}")
+      end
+
+      ln("#@amk_path/asm", "#@workdir/asm")
+
+      FileUtils.mkdir_p("#@workdir/samples")
+      ln("#@amk_path/samples/default", "#@workdir/samples/default")
+      ln("#@amk_path/samples/optimized", "#@workdir/samples/optimized")
+      ln("#@amk_path/samples/EMPTY.brr", "#@workdir/samples/EMPTY.brr")
+      if @meta.instruments.any?
+        sample_dir = "#@workdir/samples/#{basename}"
+        FileUtils.mkdir_p(sample_dir)
+
+        @meta.instruments.each do |inst|
+          ln(inst.sample_path, "#{sample_dir}/#{inst.sample_name}")
+        end
+      end
+
+      File.write("#@workdir/music/ramekin/#{basename}.txt", @txt)
+      File.write("#@workdir/Addmusic_sample groups.txt", SAMPLE_GROUPS)
+      File.write("#@workdir/Addmusic_list.txt", <<~___)
+        Globals:
+        01  ramekin/#{basename}.txt
+      ___
+      File.write("#@workdir/Addmusic_sound effects.txt", '')
+
+      Dir.chdir(@workdir) do
+        system "./AddmusicK -norom ramekin/#{basename}.txt"
+        res = $?
+        binding.pry unless res.success?
+      end
+    end
+
+    def export(outdir)
+      Dir.chdir outdir do
+        FileUtils.cp(@filename, "./#{basename}.rmk")
+        FileUtils.cp(spc_file, "./#{basename}.spc")
+        FileUtils.cp(stats_file, "./#{basename}.stats.txt")
+        File.write("./#{basename}.txt", @txt)
+
+        FileUtils.mkdir_p("samples/#{basename}")
+        @meta.instruments.each do |inst|
+          FileUtils.cp(inst.sample_path, "./samples/#{basename}/#{inst.sample_name}")
+        end
+
+        packs = @meta.instruments.map(&:pack).uniq
+
+        pack_info = packs.map do |pack|
+          out = StringIO.new
+          out << "  #{pack.name}"
+          out << " (posted by #{pack.authors.join(', ')})" if pack.authors.any?
+          out << "\n"
+
+          out << "  - #{pack.url}"
+          out.string
+        end.join("\n\n")
+
+        readme = @meta.readme&.value || '(you should edit this space before publishing)'
+
+        File.write("./README.txt", <<~README)
+          #{readme}
+
+          --
+
+          #{basename}.txt was composed as #{basename}.rmk with Ramekin
+          https://codeberg.org/jneen/ramekin
+
+          Sample sources:
+          #{pack_info}
+        README
+      end
+    end
+
+    def spc_file
+      "#@workdir/SPCs/#{basename}.spc"
+    end
+
+    def stats_file
+      "#@workdir/stats/#{basename}.txt"
+    end
+
+    def spc
+      File.read(spc_file)
+    end
+  end
+end

data/lib/ramekin/amk_setup.rb

@@ -0,0 +1,116 @@
+require 'uri'
+require 'open-uri'
+require 'json'
+
+module Ramekin
+  module AMKSetup
+    def self.setup!(**opts)
+      Dir.chdir(HOME) do
+        if Ramekin.config.windows?
+          WindowsSetup.new(**opts).setup!
+        else
+          NormalSetup.new(**opts).setup!
+        end
+      end
+    end
+
+    def self.setup_ok?
+      if Ramekin.config.windows?
+        File.exist?("#{Ramekin.config.amk_dir}/AddmusicK.exe")
+      else
+        Ramekin.config.try_asar_lib && File.executable?("#{Ramekin.config.amk_dir}/Addmusick")
+      end
+    end
+
+    class Setup
+      include Util
+
+      def initialize(force: false)
+        @force = force
+      end
+
+      def error!(msg)
+        $stderr.puts(msg)
+        exit 1
+      end
+
+      def latest_tag(repo, host='github.com')
+        host = 'api.github.com' if host == 'github.com'
+        host = 'codeberg.org/api/v1' if host == 'codeberg.org'
+
+        tag_info = JSON.parse(URI.open("https://#{host}/repos/#{repo}/git/refs/tags").read)
+        tag_info.last['ref']
+      end
+
+      def unpack_repo_source!(repo, dir, host: 'github.com')
+        clear_dir(dir, force: @force) or return false
+
+        tag = latest_tag(repo, host)
+        tag = File.basename(tag) if host == 'codeberg.org'
+
+        source_url = "https://#{host}/#{repo}/archive/#{tag}.zip"
+
+        Dir.chdir(dir) do
+          zip = URI.open(source_url).read
+          $stderr.puts "extracting #{repo} from #{source_url}"
+          $stderr.puts "into #{dir}"
+          unpack_zip_here(zip) do |name|
+            $stderr.puts " -> #{name}"
+          end
+        end
+
+        true
+      end
+    end
+
+    class WindowsSetup < Setup
+      def setup!
+        clear_dir(Ramekin.config.amk_dir, force: @force) or return false
+
+        Dir.chdir Ramekin.config.amk_dir do
+          amk_zip = URI.open('https://dl.smwcentral.net/37906/AddmusicK%201.0.11.zip').read
+          unpack_zip_here(amk_zip)
+        end
+      end
+    end
+
+    class NormalSetup < Setup
+      def setup!
+        setup_asar!
+        setup_amk!
+      end
+
+      def setup_asar!
+        unpack_repo_source!('RPGHacker/asar', Ramekin.config.asar_dir) or return
+
+        Dir.chdir(Ramekin.config.asar_dir) do
+          system(cmake, 'src')
+          error! "failed to configure asar" unless $?.success?
+          system(make)
+          error! "failed to compile asar" unless $?.success?
+
+          lib_file = Dir.glob('asar/lib/*').find do |entry|
+            next false unless File.file?(entry)
+            next false if File.symlink?(entry)
+            entry.end_with?('.dylib') || entry.end_with?('.so') || entry.end_with?('.dll')
+          end
+
+          @asar_lib_file = File.expand_path(lib_file, Ramekin.config.asar_dir)
+        end
+      end
+
+      # Using AddMusicKFF as it is the only one that seems to compile cleanly
+      # outside of Windows.
+      def setup_amk!
+        unpack_repo_source!('KungFuFurby/AddMusicKFF', Ramekin.config.amk_dir) or return
+
+        Dir.chdir(Ramekin.config.amk_dir) do
+          system(make)
+
+          # link in the silly asar lib file
+          FileUtils.ln_s(@asar_lib_file, '.')
+        end
+      end
+    end
+  end
+end

data/lib/ramekin/channel_separator.rb

@@ -0,0 +1,40 @@
+module Ramekin
+  class ChannelSeparator
+    def self.parse(stream)
+      new.tap { |x| x.parse(stream) }
+    end
+
+    attr_reader :preamble, :channels, :meta
+    def initialize
+      @preamble = []
+      @channels = []
+
+      @current = @preamble
+    end
+
+    def preamble?
+      @current.equal?(@preamble)
+    end
+
+    def parse(stream)
+      stream.each do |el|
+        if Token === el && el.type == :channel
+          @meta = Meta.new(@preamble.dup).tap(&:parse) if preamble?
+          @meta.parse
+
+          @current = (@channels[el.value.to_i] ||= [])
+        end
+
+        next (@current << el) if preamble?
+
+        if el.type == :instrument && el.value !~ /\A\d+\z/
+          el.meta[:inst] = @meta.instruments.find do |inst|
+            inst.name.value == el.value
+          end
+        end
+
+        @current << el
+      end
+    end
+  end
+end