badline 0.6.1 → 0.8.0

data/lib/badline/options/help.rb

@@ -19,7 +19,7 @@ module Badline
     # What --help prints: the usage, then the options this build takes,
     # section by section, laid out as OptionParser did.
     def help
-      lines = [banner]
+      lines = [@sid_command ? sid_banner : banner]
       SECTIONS.each do |section|
         options = TABLE.select { |option| option.section == section && takes?(option) }
         next if options.empty?
@@ -40,6 +40,7 @@ module Badline
         Usage: #{@program} [options] [media]
                #{@program} --headless [options] tune.sid
                #{@program} [options] tune.sid --audio-out FILE
+               #{@program} sid [options] FILE|DIR...
 
         Media can be a .prg/.p00 program, a .d64/.d71/.d81 disk image, a
         .g64 disk image for the true 1541, a .t64 tape archive, a .tap
@@ -48,18 +49,23 @@ module Badline
         saves a snapshot and F12 restores it. Device 8 answers through
         traps on the KERNAL's disk routines, unless --true-drive puts an
         emulated 1541 there, which runs its own DOS and reads .d64 and .g64
-        images only.
+        images only. A .sid tune opens in the SID player, as `sid` plays it,
+        unless an option of the emulator's window asks for the machine.
 
         --headless plays a .sid tune on the host's audio device without the
         window, and --audio-out renders it to 16-bit PCM instead. The
         container follows the file's extension, .wav or .aiff. Played on a
-        terminal, n or → skips to the next song, p or ← to the previous one,
-        space pauses and q quits.
+        terminal, → and ← step between the tune's subtunes, n and p between
+        tunes, , and . seek, space pauses and q quits. s shuffles the tunes,
+        l loops them, and a, or --all-subtunes, plays on through each tune's
+        subtunes instead of just the one. `#{@program} sid` plays many tunes, and whole
+        directories of them, the same way.
 
         A .sid file carries no length of its own. Without --seconds the tune is
         looked up by MD5 in HVSC's Songlengths.md5, taken from --songlengths, from
         the DOCUMENTS directory of an HVSC collection above the tune, or from
-        $HVSC_BASE. Failing all of those it runs for #{FALLBACK_SECONDS.to_i} seconds.
+        $HVSC_BASE. Failing all of those it runs for #{FALLBACK_SECONDS.to_i} seconds, or
+        until it has been silent for #{SILENCE_SECONDS.to_i}.
 
         #{@native ? NATIVE_SPEED : RUBY_SPEED}
 
@@ -74,5 +80,28 @@ module Badline
         argument.
       BANNER
     end
+
+    def sid_banner
+      <<~BANNER
+        Usage: #{@program} sid [options] FILE|DIR...
+
+        Plays .sid tunes in the SID player's window, or in the terminal with
+        --headless, one after another in the order given. A directory adds
+        every .sid tune below it, in path order. → and ← step between a
+        tune's subtunes, n and p between tunes, , and . seek 10 seconds back
+        and forward, space pauses and q quits. s shuffles the tunes, l loops
+        them, and a, or --all-subtunes, plays on through each tune's subtunes
+        instead of just the one. The window has buttons for all of these,
+        and for switching the SID between the tune's own, the 6581 and the
+        8580. --subtune picks the first tune's subtune, and each tune after
+        it starts on its own. Without tunes, the window opens with an empty
+        queue, and .sid files or folders dropped on the window join it.
+
+        Each tune gets the SID its header names unless --sid says otherwise,
+        and its length from HVSC's Songlengths.md5 as #{@program} --help
+        describes. A tune written for 2 or 3 SIDs plays on the one badline
+        emulates, with a notice.
+      BANNER
+    end
   end
 end

data/lib/badline/options/option.rb

@@ -3,7 +3,7 @@
 module Badline
   class Options
     # One option of the table: its flags and value as the help shows them
-    # (`-s, --song N`), what it does, the help section it's listed in, the
+    # (`-s, --subtune N`), what it does, the help section it's listed in, the
     # mode it needs (:window, :headless or :either), and the build that
     # takes it (:native, :ruby or :both).
     class Option

data/lib/badline/options/table.rb

@@ -8,15 +8,15 @@ module Badline
 
     # Every option of both builds, in the order the help lists them.
     TABLE = [
-      Option.new("-s, --song N", "Subtune of a .sid, from 1 (default: the tune's own)", section: "Options"),
-      Option.new("--sid MODEL", "SID to fit: 6581 or 8580 (default: a .sid tune's own, else 6581)",
+      Option.new("-s, --subtune N", "Subtune of a .sid, from 1 (default: the tune's own)", section: "Options"),
+      Option.new("--sid MODEL", "SID to fit: auto, 6581 or 8580 (default: auto, a .sid tune's own, else 6581)",
                  section: "Options"),
       Option.new("--disable-jit", "Run without enabling YJIT", section: "Options", build: :ruby),
       Option.new("-h, --help", "Show this help", section: "Options"),
       Option.new("--version", "Show the version and what built it", section: "Options", build: :native),
       Option.new("--no-autostart", "Boot to READY. instead of running the program",
                  section: "Window options", needs: :window),
-      Option.new("--read-only", "Mount a disk image write-protected, leaving its file unchanged",
+      Option.new("--writable", "Let the machine write to disk images, changing their files",
                  section: "Window options", needs: :window),
       Option.new("--sound", "Play the SID through the host's audio device (F10 mutes)",
                  section: "Window options", needs: :window),
@@ -44,6 +44,8 @@ module Badline
       Option.new("--filter-chunk N", "Filter step in cycles, 1 is exact (default: 4)",
                  section: "Options without the window", needs: :headless),
       Option.new("--quiet", "Don't report progress", section: "Options without the window", needs: :headless),
+      Option.new("--all-subtunes", "Play on through each tune's subtunes, not just the one",
+                 section: "Options without the window", needs: :headless),
       Option.new("--no-tui", "Play without the interactive display, even on a terminal",
                  section: "Options without the window", needs: :headless),
       Option.new("--frames N", "Quit after N frames", section: "Testing options", needs: :window),

data/lib/badline/options/validation.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Badline
+  class Options
+    # The checks Options#parse makes once every argument has been read:
+    # the options fit the mode, the numbers are positive and the files
+    # exist.
+    module Validation
+      private
+
+      def validate
+        validate_mode
+        validate_numbers
+        validate_paths
+      end
+
+      def validate_mode
+        if headless?
+          raise Error, "#{@window_only.first} needs the window" unless @window_only.empty?
+          raise Error, "no tune given" if tune_paths.empty? && !player_window?
+
+          tune_paths.each { |path| validate_tune(path) }
+        elsif !@headless_only.empty?
+          raise Error, "#{@headless_only.first} needs --headless or --audio-out"
+        end
+      end
+
+      # `sid` takes directories as well as tunes.
+      def validate_tune(path)
+        return if !File.exist?(path) || File.extname(path).casecmp?(".sid")
+        return if @sid_command && File.directory?(path)
+
+        raise Error, "not a .sid tune: #{path}"
+      end
+
+      def validate_numbers
+        positive("--subtune", @subtune)
+        positive("--seconds", @seconds)
+        positive("--rate", @rate)
+        positive("--filter-chunk", @filter_chunk)
+      end
+
+      def positive(name, value)
+        raise Error, "invalid argument: #{name} #{value}" if !value.nil? && value <= 0
+      end
+
+      def validate_paths
+        missing = tune_paths.find { |path| !File.exist?(path) }
+        raise Error, "no such file or directory: #{missing}" unless missing.nil?
+        raise Error, "no such file or directory: #{@songlengths}" unless @songlengths.nil? || File.exist?(@songlengths)
+      end
+    end
+  end
+end

data/lib/badline/options.rb

@@ -4,33 +4,47 @@ require "badline/options/option"
 require "badline/options/event"
 require "badline/options/table"
 require "badline/options/help"
+require "badline/options/validation"
 
 module Badline
   # The command line of both builds, badline-ruby and the native badline.
   # Either opens the window for any media, or with --headless or
-  # --audio-out plays or renders a .sid tune without one. The native build
-  # adds --no-sound and --version, and badline-ruby adds --disable-jit.
+  # --audio-out plays or renders a .sid tune without one. `sid`, given
+  # first, plays .sid tunes and directories of them in the terminal. The
+  # native build adds --no-sound and --version, and badline-ruby adds
+  # --disable-jit.
   #
   # TABLE lists the options, and both the parser and the help read it. It
   # parses by hand, inside the subset of Ruby Spinel compiles. Values come
-  # as `--song 2` or `--song=2`, and `--` ends the options. It loads
+  # as `--subtune 2` or `--subtune=2`, and `--` ends the options. It loads
   # nothing else from badline, so badline-ruby can parse and reject its
   # arguments before paying for the emulator.
   class Options
+    include Validation
+
     class Error < StandardError; end
 
     FALLBACK_SECONDS = 60.0
 
+    # A tune on the fallback length ends sooner once it has been silent
+    # this long.
+    SILENCE_SECONDS = 5.0
+
     SID_MODELS = { "6581" => :mos6581, "8580" => :mos8580 }.freeze
 
+    # What `sid` leaves out besides the window's options.
+    NOT_FOR_SID = %w[--audio-out].freeze
+
     REU_SIZES = %w[128 256 512 1024 2048 4096 8192 16384].freeze
 
     # A Float as OptionParser took one: digits with an optional sign,
     # fraction and exponent.
     DECIMAL = /\A[-+]?(\d+(\.\d+)?|\.\d+)([eE][-+]?\d+)?\z/
 
-    attr_reader :program, :media_path, :song, :sid_model, :reu, :frames, :screenshot, :save_snapshot, :audio_out,
-                :seconds, :songlengths, :filter_chunk, :timeline
+    # tune_paths holds the media given, which `sid` takes more than one of:
+    # tunes and directories of tunes, in the order given.
+    attr_reader :program, :media_path, :tune_paths, :subtune, :sid_model, :reu, :frames, :screenshot, :save_snapshot,
+                :audio_out, :seconds, :songlengths, :filter_chunk, :timeline
 
     def self.parse(argv, native: false) = new(native:).parse(argv)
 
@@ -41,11 +55,13 @@ module Badline
       @native = native
       @program = native ? "badline" : "badline-ruby"
       @media_path = nil
-      @song = nil
+      @sid_command = false
+      @tune_paths = []
+      @subtune = nil
       @sid_model = nil
       @reu = nil
       @autostart = true
-      @read_only = false
+      @writable = false
       @sound = native
       @frames = 0
       @paced = true
@@ -67,13 +83,16 @@ module Badline
       @filter_chunk = nil
       @quiet = false
       @tui = true
+      @all_subtunes = false
       @window_only = []
       @headless_only = []
     end
 
     def parse(argv)
       args = argv.dup
+      sid_command(args) if args.first == "sid"
       argument(args.shift, args) until args.empty?
+      play_lone_tune
       validate unless help? || version?
       self
     end
@@ -82,7 +101,14 @@ module Badline
     def snapshot? = !@media_path.nil? && File.extname(@media_path).casecmp?(".vsf")
 
     # Plays or renders a .sid tune without the window.
-    def headless? = @headless || render?
+    def headless? = @headless || render? || @sid_command
+
+    # Whether `sid` came first, to play the tunes and directories given.
+    def sid_command? = @sid_command
+
+    # Whether `sid` plays in the SID player's window rather than the
+    # terminal.
+    def player_window? = @sid_command && !@headless
 
     def window? = !headless?
 
@@ -94,6 +120,9 @@ module Badline
     # How long to play a tune whose length nothing gives.
     def fallback_seconds = FALLBACK_SECONDS
 
+    # How long a tune playing for fallback_seconds may stay silent.
+    def silence_seconds = SILENCE_SECONDS
+
     def rate = @rate.nil? ? DEFAULT_RATE : @rate
 
     def rate_given? = !@rate.nil?
@@ -102,9 +131,11 @@ module Badline
 
     def tui? = @tui
 
+    def all_subtunes? = @all_subtunes
+
     def autostart? = @autostart
 
-    def read_only? = @read_only
+    def writable? = @writable
 
     def sound? = @sound
 
@@ -126,7 +157,24 @@ module Badline
 
     private
 
-    def takes?(option) = [:both, @native ? :native : :ruby].include?(option.build)
+    def takes?(option)
+      return false if @sid_command && (option.needs == :window || NOT_FOR_SID.include?(option.name))
+
+      [:both, @native ? :native : :ruby].include?(option.build)
+    end
+
+    def sid_command(args)
+      args.shift
+      @sid_command = true
+    end
+
+    # A .sid on its own plays in the SID player, as `sid` would, unless an
+    # option of the emulator's window asks for the machine.
+    def play_lone_tune
+      return if @sid_command || headless? || !@window_only.empty? || @media_path.nil?
+
+      @sid_command = File.extname(@media_path).casecmp?(".sid")
+    end
 
     def argument(arg, args)
       if arg == "--"
@@ -172,7 +220,7 @@ module Badline
 
     def valued_option(name, flag, value)
       case name
-      when "--song" then @song = number(flag, value)
+      when "--subtune" then @subtune = number(flag, value)
       when "--sid" then @sid_model = sid_model_for(value)
       when "--reu" then @reu = reu_size(value)
       when "--frames" then @frames = number(flag, value)
@@ -190,7 +238,7 @@ module Badline
     def switch(name)
       case name
       when "--no-autostart" then @autostart = false
-      when "--read-only" then @read_only = true
+      when "--writable" then @writable = true
       when "--sound" then @sound = true
       when "--no-sound" then @sound = false
       when "--no-vsync" then @vsync = false
@@ -203,11 +251,13 @@ module Badline
       when "--version" then @version = true
       when "--headless" then @headless = true
       when "--quiet" then @quiet = true
+      when "--all-subtunes" then @all_subtunes = true
       else @tui = false
       end
     end
 
     def sid_model_for(value)
+      return if value == "auto"
       raise Error, "invalid argument: --sid #{value}" unless SID_MODELS.key?(value)
 
       SID_MODELS[value]
@@ -232,41 +282,10 @@ module Badline
     end
 
     def media_argument(arg)
-      raise Error, "unexpected argument: #{arg}" unless @media_path.nil?
-
-      @media_path = arg
-    end
-
-    def validate
-      validate_mode
-      validate_numbers
-      validate_paths
-    end
-
-    def validate_mode
-      if headless?
-        raise Error, "#{@window_only.first} needs the window" unless @window_only.empty?
-        raise Error, "no tune given" if @media_path.nil?
-        raise Error, "not a .sid tune: #{@media_path}" unless File.extname(@media_path).casecmp?(".sid")
-      elsif !@headless_only.empty?
-        raise Error, "#{@headless_only.first} needs --headless or --audio-out"
-      end
-    end
-
-    def validate_numbers
-      positive("--song", @song)
-      positive("--seconds", @seconds)
-      positive("--rate", @rate)
-      positive("--filter-chunk", @filter_chunk)
-    end
-
-    def positive(name, value)
-      raise Error, "invalid argument: #{name} #{value}" if !value.nil? && value <= 0
-    end
+      raise Error, "unexpected argument: #{arg}" unless @sid_command || @media_path.nil?
 
-    def validate_paths
-      raise Error, "no such file or directory: #{@media_path}" unless @media_path.nil? || File.exist?(@media_path)
-      raise Error, "no such file or directory: #{@songlengths}" unless @songlengths.nil? || File.exist?(@songlengths)
+      @media_path = arg if @media_path.nil?
+      @tune_paths << arg
     end
   end
 end

data/lib/badline/sdl.rb

@@ -15,6 +15,7 @@ module Badline
     ffi_func :SDL_SetHint, %i[str str], :int
     ffi_func :SDL_CreateWindow, %i[str int int int int uint32], :ptr
     ffi_func :SDL_SetWindowTitle, %i[ptr str], :void
+    ffi_func :SDL_SetWindowSize, %i[ptr int int], :void
     ffi_func :SDL_DestroyWindow, [:ptr], :void
     ffi_func :SDL_CreateRenderer, %i[ptr int uint32], :ptr
     ffi_func :SDL_GetWindowDisplayMode, %i[ptr ptr], :int
@@ -26,6 +27,9 @@ module Badline
     ffi_func :SDL_RenderClear, [:ptr], :int
     ffi_func :SDL_SetRenderDrawColor, %i[ptr int int int int], :int
     ffi_func :SDL_RenderFillRect, %i[ptr ptr], :int
+    ffi_func :SDL_RenderDrawLines, %i[ptr int_array int], :int
+    ffi_func :SDL_SetTextureBlendMode, %i[ptr int], :int
+    ffi_func :SDL_SetTextureColorMod, %i[ptr int int int], :int
     ffi_func :SDL_RenderCopy, %i[ptr ptr ptr ptr], :int
     ffi_func :SDL_RenderPresent, [:ptr], :void
     ffi_func :SDL_PollEvent, [:ptr], :int
@@ -52,9 +56,6 @@ module Badline
     ffi_func :SDL_GameControllerGetButton, %i[ptr int], :uint8
     ffi_func :SDL_GameControllerGetAxis, %i[ptr int], :int16
     ffi_func :SDL_ClearQueuedAudio, [:uint32], :void
-    ffi_func :SDL_GetCurrentDisplayMode, %i[int ptr], :int
-    ffi_func :SDL_CreateRGBSurfaceFrom, %i[ptr int int int int uint32 uint32 uint32 uint32], :ptr
-    ffi_func :SDL_CreateTextureFromSurface, %i[ptr ptr], :ptr
     ffi_func :SDL_PushEvent, [:ptr], :int
     ffi_func :SDL_GetKeyName, [:int], :str
 
@@ -69,6 +70,11 @@ module Badline
     ffi_read_i32 :event_xrel, 28
     ffi_read_i32 :event_yrel, 32
     ffi_read_u8 :event_button, 16
+    # Where the pointer is, in a motion or button event.
+    ffi_read_i32 :event_x, 20
+    ffi_read_i32 :event_y, 24
+    # SDL_DropEvent's file, which the receiver frees.
+    ffi_read_ptr :event_file, 8
 
     ffi_buffer :rect, 16
     ffi_write_i32 :rect_x, 0
@@ -77,6 +83,8 @@ module Badline
     ffi_write_i32 :rect_h, 12
     # Where the drive LED goes.
     ffi_buffer :led_rect, 16
+    # A glyph's place in the SID player's font, drawn at SDL.rect.
+    ffi_buffer :glyph_rect, 16
 
     # SDL_DisplayMode: Uint32 format; int w, h, refresh_rate; then a pointer.
     ffi_buffer :display_mode, 24
@@ -104,6 +112,8 @@ module Badline
     ffi_const :RENDERER_ACCELERATED, 0x02
     ffi_const :RENDERER_PRESENTVSYNC, 0x04
     ffi_const :PIXELFORMAT_RGB888, 0x16161804
+    ffi_const :PIXELFORMAT_ARGB8888, 0x16362004
+    ffi_const :BLENDMODE_BLEND, 0x01
     ffi_const :TEXTUREACCESS_STREAMING, 1
     ffi_const :QUIT, 0x100
     ffi_const :KEYDOWN, 0x300
@@ -114,13 +124,10 @@ module Badline
     ffi_const :KMOD_SHIFT, 0x0003
     ffi_const :CONTROLLERDEVICEADDED, 0x653
     ffi_const :CONTROLLERDEVICEREMOVED, 0x654
-    ffi_const :CONTROLLERDEVICEREMAPPED, 0x655
     ffi_const :AUDIO_S16LSB, 0x8010
     ffi_const :ALLOW_FREQUENCY_CHANGE, 0x01
     ffi_const :KEY_TAB, 0x09
     ffi_const :KEY_F10, 0x4000_0043
-    ffi_const :KEY_F11, 0x4000_0044
-    ffi_const :KEY_F12, 0x4000_0045
   end
 
   # The few C library calls the native front end makes.
@@ -128,6 +135,9 @@ module Badline
     ffi_func :malloc, [:size_t], :ptr
     ffi_func :free, [:ptr], :void
     ffi_func :poll, %i[ptr size_t int], :int
+    # Called with an empty needle, it returns the C string it's given as a
+    # String.
+    ffi_func :strstr, %i[ptr str], :str
 
     ffi_const :POLLIN, 0x01
 

data/lib/badline/sid/catch_up.rb

@@ -96,7 +96,17 @@ module Badline
 
       def record_sample(span)
         sample = @decimator.push(current_sample, span)
-        @samples << sample if sample
+        return unless sample
+
+        @samples << sample
+        record_voices if @voice_samples
+      end
+
+      def record_voices
+        voice_samples = @voice_samples
+        voice_samples << (@voice1.output >> 7)
+        voice_samples << (@voice2.output >> 7)
+        voice_samples << (@voice3.output >> 7)
       end
 
       def current_sample

data/lib/badline/sid/filter.rb

@@ -122,6 +122,15 @@ module Badline
         reset
       end
 
+      # The integrators and the registers carry over; the cutoff maps
+      # through the new model's curve.
+      def model=(model)
+        @model = model
+        @w0_table = W0.fetch(model)
+        @mixer_dc = MIXER_DC.fetch(model)
+        @w0 = @w0_table[@cutoff]
+      end
+
       def reset
         @cutoff = 0x000
         @routing = 0x0

data/lib/badline/sid/voice.rb

@@ -33,6 +33,12 @@ module Badline
         @dc_offset = DC_OFFSET.fetch(model)
       end
 
+      def model=(model)
+        @waveform.model = model
+        @wave_zero = WAVE_ZERO.fetch(model)
+        @dc_offset = DC_OFFSET.fetch(model)
+      end
+
       def reset!
         @waveform.reset!
         @envelope = Envelope.new

data/lib/badline/sid/waveform.rb

@@ -54,17 +54,24 @@ module Badline
       attr_reader :accumulator, :shift_register, :frequency, :pulse_width, :pulse
 
       def initialize(model: :mos6581)
-        @topbit_feedback = model != :mos8580
+        use_model(model)
         @tri_saw_delay = model == :mos8580
-        @pulse_noise_read = PULSE_NOISE_READ.fetch(model)
-        @pulse_noise_write = PULSE_NOISE_WRITE.fetch(model)
-        @combined = Combined.tables(model)
-        @shift_register_reset_delay = SHIFT_REGISTER_RESET_DELAY.fetch(model)
         @accumulator = POWER_ON_ACCUMULATOR
         @sync_source = @sync_dest = self
         reset!
       end
 
+      # The running state carries over. A 6581 never delays its shapers, so
+      # the 8580's delayed triangle and sawtooth start from the current phase.
+      def model=(model)
+        use_model(model)
+        if model == :mos8580 && !@tri_saw_delay
+          @delayed_sawtooth = sawtooth
+          @delayed_triangle = triangle
+        end
+        @tri_saw_delay = model == :mos8580
+      end
+
       # The RES line clears the registers and reseeds the LFSR, but leaves
       # the accumulator alone (SID/oscinit).
       def reset!
@@ -190,6 +197,14 @@ module Badline
 
       private
 
+      def use_model(model)
+        @topbit_feedback = model != :mos8580
+        @pulse_noise_read = PULSE_NOISE_READ.fetch(model)
+        @pulse_noise_write = PULSE_NOISE_WRITE.fetch(model)
+        @combined = Combined.tables(model)
+        @shift_register_reset_delay = SHIFT_REGISTER_RESET_DELAY.fetch(model)
+      end
+
       def shape(selected, saw = sawtooth, tri = triangle(selected))
         case selected
         when 0x1 then tri

data/lib/badline/sid.rb

@@ -16,7 +16,9 @@ module Badline
   # $D41B-$D41C - Voice 3 oscillator/envelope - read only
   # $D41D-$D41F - Unconnected
   #
-  # The register file mirrors every 32 bytes up to $D7FF.
+  # The register file mirrors every 32 bytes up to $D7FF. A second or
+  # third SID, which only the SID player fits, is built `at` another
+  # address and decodes just the 32 bytes there.
   #
   # Reading a write-only or unconnected register returns the last byte the
   # SID saw on the data bus. That value fades to $00 as the capacitance
@@ -55,8 +57,8 @@ module Badline
     attr_accessor :pots
     attr_reader :model
 
-    def initialize(model: :mos6581, pots: nil, filter_chunk: FILTER_CHUNK)
-      addressable_at(0xd400, length: 2**10)
+    def initialize(model: :mos6581, pots: nil, filter_chunk: FILTER_CHUNK, at: 0xd400)
+      addressable_at(at, length: at == 0xd400 ? 2**10 : 2**5)
       @model = model
       @pots = pots
       @bus_ttl_reset = BUS_TTL.fetch(model)
@@ -67,6 +69,7 @@ module Badline
       @deferred_writes = []
       @decimator = nil
       @samples = []
+      @voice_samples = nil
       @filter_chunk = filter_chunk
       @voices = Voice.linked(VOICES, model:)
       @voice1, @voice2, @voice3 = @voices
@@ -74,6 +77,18 @@ module Badline
       reset!
     end
 
+    # Switches the chip, its filter and its voices to the other model's
+    # values. The cycles already passed run on the old model first, and the
+    # running state carries over.
+    def model=(model)
+      catch_up
+      @model = model
+      @bus_ttl_reset = BUS_TTL.fetch(model)
+      @filter.model = model
+      @voices.each { |voice| voice.model = model }
+      update_span_rules
+    end
+
     # The RES line clears the registers, the data bus, the filter and the
     # voices, all but their accumulators. Recording carries on across it.
     def reset!
@@ -112,6 +127,23 @@ module Badline
       @samples = []
     end
 
+    # Also keeps each voice's own output, before the filter and the volume,
+    # as each recorded sample closes, for #drain_voice_samples.
+    def record_voices!
+      @voice_samples = [] if @voice_samples.nil?
+    end
+
+    # The voices' outputs since the last drain, three to a sample, in voice
+    # order, or nothing unless #record_voices! asked for them.
+    def drain_voice_samples
+      return [] if @voice_samples.nil?
+
+      catch_up
+      samples = @voice_samples
+      @voice_samples = []
+      samples
+    end
+
     # The samples recorded since the last drain.
     def drain_samples
       catch_up

data/lib/badline/storage/hvsc.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Badline
+  module Storage
+    # The layout of an HVSC collection: tunes in directories under its root,
+    # and databases about them in `DOCUMENTS`. A tune's HVSC path is its path
+    # from the root, as `/MUSICIANS/H/Hubbard_Rob/Commando.sid`.
+    module HVSC
+      class << self
+        # The named file in the DOCUMENTS directory of a collection above the
+        # tune, or else of the one `$HVSC_BASE` points at.
+        def document(tune_path, name)
+          candidates(tune_path).map { |dir| File.join(dir, "DOCUMENTS", name) }
+                               .find { |path| File.file?(path) }
+        end
+
+        # The tune's HVSC path in the collection that holds the document, or
+        # nil when the tune lies outside it.
+        def path(tune_path, document)
+          root = File.dirname(File.expand_path(document), 2)
+          tune = File.expand_path(tune_path)
+          tune.start_with?("#{root}/") ? tune[root.length..] : nil
+        end
+
+        private
+
+        def candidates(tune_path)
+          dirs = []
+          dir = File.dirname(File.expand_path(tune_path))
+          until dirs.last == dir
+            dirs << dir
+            dir = File.dirname(dir)
+          end
+          base = ENV.fetch("HVSC_BASE", nil)
+          dirs << base if base
+          dirs
+        end
+      end
+    end
+  end
+end