badline 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7150f883c604da9d4f9bd4712412a020f9352dbbdba08a5051fee95e7f8bce30
-  data.tar.gz: cac44823e8c8afcc4637ad40383da5c624f51d29a60a45084b2ba6b81d6ae68e
+  metadata.gz: 9348bef9831893e0aefa4d6965e1ea99a7252fb9f8f71e311f6b93b849ee1faa
+  data.tar.gz: '01029a95df00b30c92120e7f91c2e6dc9af247a927c41e64296a6285abdb9267'
 SHA512:
-  metadata.gz: d09600dbf17cfa3df1d32e6ca5b8b25cd6f3cb012fd54c0cc0f7a4f700d98aaa45e9b0ba6cde95fa6c37e7310368f692e75c0f332f55fad84c5181a07df5da61
-  data.tar.gz: e3b2796713ab7701ab0a536276b6e845bb1751586c7706bdbe19a918129bb978927aef395062c98331c493af515a8ef77455446ca21289e434360753bf1aa89a
+  metadata.gz: 8944a5873ed411c9ab156a5cedf537f8d7db1b0a06625c567a24b2b33f05c8ac6b20b45edbbaf7049b91a72da7bc1a5fc35b0c3f24e7029fda86a671315bfef5
+  data.tar.gz: bb10fd47802aadab93ed86916ce8de6a2d17e4163ecf723a0a6d4b45085eefadd2905e2eabbfbba39530f7d0e7d3be18f0e059a17bc6c71fb69aa592ea7204a3

data/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## [0.3.0](https://github.com/elektronaut/badline/compare/v0.2.1...v0.3.0) (2026-09-24)
+
+Sound is the headline: `badline --sound` plays the SID in the emulator window and paces emulation to the audio device. It is off by default, because the emulator still runs below real time on CRuby and the sound stutters there. This release also brings the virtual drive closer to a real 1541 (buffer channels in drive RAM, DOS command parsing, the BAM in buffer 4, `LOAD"*"`), cartridge banking fixes, and `Badline::Checkpoint` with `bin/machine_diff` for checking that a change leaves emulation alone.
+
+
+
+### Features
+
+* add Badline::Checkpoint, a per-component digest of machine state ([183e164](https://github.com/elektronaut/badline/commit/183e16438b4b1bfae5c16b10f29f2b08d0a6b297))
+* add bin/machine_diff, a differential run harness ([58f695a](https://github.com/elektronaut/badline/commit/58f695a32096fe61d7395fcec9a76d8d84b5e440))
+* load ROMs from a configurable Badline.rom_path ([4fa12c8](https://github.com/elektronaut/badline/commit/4fa12c8e55004eebe0b1a14e80f03713306e3acf))
+* pace the window to the audio device while sound plays ([031b001](https://github.com/elektronaut/badline/commit/031b00196ee9a881740047c726231ffc0400d03d))
+* play the SID in the emulator window with --sound ([4cbd211](https://github.com/elektronaut/badline/commit/4cbd211ca986834e3d8fcbafdabc5586c87ec950))
+
+
+### Bug Fixes
+
+* answer a buffer channel's first read with its buffer number ([851e0d2](https://github.com/elektronaut/badline/commit/851e0d2bb71db51cc36607da90b4f7891b32bced))
+* bank BASIC out for PSID routines whose image reaches under it ([9c5bf57](https://github.com/elektronaut/badline/commit/9c5bf57646ca8de8687679accdca26ac4dd68931))
+* bank sparse and odd-sized cartridge images like the hardware ([1560f63](https://github.com/elektronaut/badline/commit/1560f63678a254bfa53e8915c35851dab00dc27b))
+* drop the carriage return that ends a file name, as the 1541 does ([3ca3d51](https://github.com/elektronaut/badline/commit/3ca3d518808cf87ab0e14a3b312e972883fc4699))
+* fail a block write at the block it names ([4b9664c](https://github.com/elektronaut/badline/commit/4b9664ca02bd0026334ffee01d4f6a5cfc354f73))
+* fail an append open on a write-protected disk ([b5c7baf](https://github.com/elektronaut/badline/commit/b5c7bafed7f189c3e7a0074d27f0b76e8ffb3b56))
+* fail an unreadable host file with a READ ERROR ([8b3d8f4](https://github.com/elektronaut/badline/commit/8b3d8f4eeae28a4ef61ef72e76dcfc02cefb738f))
+* fill a buffer channel with the bytes written to it ([36c3660](https://github.com/elektronaut/badline/commit/36c3660e1c170ea058b80d3a0b10ec019aa84058))
+* give single-bank mappers erased ROM when the image has no chip ([07e5bf3](https://github.com/elektronaut/badline/commit/07e5bf39b26e022f814c99b0d9226cecf3114400))
+* ignore whatever follows a star in a DOS file name ([b2f8831](https://github.com/elektronaut/badline/commit/b2f8831b193e496d19c03388fe0613b9f9c9abb3))
+* keep the drive's buffer channels in its RAM ([9efefe4](https://github.com/elektronaut/badline/commit/9efefe44520067db27496ea2af85468228c6579f))
+* keep the drive's RAM when the disk changes ([2c07d0e](https://github.com/elektronaut/badline/commit/2c07d0eb73120dfe1eda69a5fc8ad43a31d83ef2))
+* leave secondary address $60 in $B9 after a trapped LOAD ([d7366a8](https://github.com/elektronaut/badline/commit/d7366a8aaf0fe13d239035178751fc8f783d7a30))
+* mask Ocean and Magic Desk bank selection to the ROM size ([e6d36a0](https://github.com/elektronaut/badline/commit/e6d36a004583d18e225e4bb5cfccdd69380d523e))
+* play NTSC PSID tunes on an NTSC clock on the bare rig ([006e04b](https://github.com/elektronaut/badline/commit/006e04b03985ef5d2fe57bab6c862bbe97d65f50))
+* read DOS command parameters the way the 1541 does ([db5b4fc](https://github.com/elektronaut/badline/commit/db5b4fc06b82f5423453ee988d30f407a8565ed1))
+* read open bus from a cartridge's empty ROM socket ([fee013d](https://github.com/elektronaut/badline/commit/fee013dcff2a062b75713b268422171e79a50375))
+* read the BAM into buffer 4 when the drive initializes a disk ([c1320a5](https://github.com/elektronaut/badline/commit/c1320a5d2f7d9fcd24e800fcacaf07ba8b07b889))
+* reopen the last loaded file on a LOAD of "*" ([64b3991](https://github.com/elektronaut/badline/commit/64b3991b9e1c91190e9b47e44238b93e0ea74850))
+* report host SAVE and read failures on the drive's error channel ([039b6da](https://github.com/elektronaut/badline/commit/039b6da1779397e56ebf6cc25effe656ca85c1f6))
+* reset the drive with the machine, as the serial bus's RESET line does ([4044db6](https://github.com/elektronaut/badline/commit/4044db6ae1bd241381c2d7651cf2a44b1ae8a61a))
+* RUN BASIC RSID tunes instead of calling their first byte ([d9a51c2](https://github.com/elektronaut/badline/commit/d9a51c2eebd5092e97da576c438a647079458e78))
+* show a BMM falling out of multicolour bitmap or ECM+BMM at pixel 5 ([988a0c6](https://github.com/elektronaut/badline/commit/988a0c60e40c720e8e1cd7acf0506107902a1ccb))
+* **vic:** power on with every register zero, as VICE does ([d5bf757](https://github.com/elektronaut/badline/commit/d5bf75756d2edfdf3b6bf40214615262b79958a6))
+* wrap a buffer channel's reads back to its second byte, as the DOS does ([9c9f0ed](https://github.com/elektronaut/badline/commit/9c9f0edb7b92b580bb2cb71668e5fa07fa8e3bd9))
+
+
+### Performance Improvements
+
+* cut the SID's per-span catch-up overhead ([f50ede8](https://github.com/elektronaut/badline/commit/f50ede8472389c28c1dde70909794ef69ae77238))
+* type the hot core for Spinel with RBS seeds ([90d31b0](https://github.com/elektronaut/badline/commit/90d31b02331982e216284f2ac533f5a6aa934bf9))
+
 ## [0.2.1](https://github.com/elektronaut/badline/compare/v0.2.0...v0.2.1) (2026-09-23)
 
 

data/CLAUDE.md

@@ -52,6 +52,12 @@ timer test takes about 25 minutes.
 where that time goes. `test/baselines/README.md`
 documents the baseline format, the suites and how rows are compared.
 
+`bin/machine_diff <scenario|media> --against <rev>` checks that a change
+leaves emulation alone. It runs the scenario on this tree and on `<rev>`'s
+`lib/` side by side, digests the CPU, RAM, VIC, CIAs and SID every million
+cycles, and names the first component that differs. Use it for refactors
+and speed work.
+
 ## Driving the emulator headlessly
 
 `exe/badline <media>` opens the SDL window, which is no use for checking

data/README.md

@@ -10,9 +10,9 @@ are modelled at the cycle level.
 
 It runs programs, disk and tape images, cartridges and SID tunes, and
 the SDL2 front end supports the keyboard, joysticks, game controllers,
-paddles and a 1351 mouse. There is no live sound yet, and emulation runs
-slower than a real C64. See [What's emulated](#whats-emulated) for the
-details.
+paddles and a 1351 mouse. Emulation runs slower than a real C64, so
+live sound, which is off by default, stutters. See
+[What's emulated](#whats-emulated) for the details.
 
 ## Requirements
 
@@ -54,6 +54,21 @@ you can type the `LOAD` yourself. `--song N` picks a subtune of a
 without YJIT, which is otherwise switched on at startup.
 `badline --help` lists the options.
 
+The KERNAL, BASIC and character ROMs come with the gem. To run other
+images, such as a patched KERNAL, point `BADLINE_ROM_PATH` at a
+directory that holds `kernal.rom`, `basic.rom` and `character.rom`,
+plus `eapi/eapi-am29f040-14` if you attach EasyFlash cartridges. From
+Ruby, `Badline.rom_path = dir` does the same before a
+`Badline::Computer` is built, and `nil` restores the bundled set.
+
+`--sound` plays the SID through the host's audio device, and `F10`
+mutes and unmutes it. Sound is off by default. While it plays, the
+audio device sets the pace instead of the display, so the machine never
+runs ahead of the sound or drifts behind it. The whole machine runs
+below real time, though, so the sound stutters: it plays in bursts with
+silent gaps between them, at the right pitch, and never slows the
+emulation down.
+
 ## Media
 
 | Format | Handling |
@@ -160,6 +175,9 @@ Control port 1's fire line is also the VIC-II's light pen input, so
 joystick 1's fire button and the 1351's left button in port 1 latch the
 light pen registers.
 
+With `--sound`, `F10` mutes and unmutes the sound, and the window
+title shows `[MUTED]` while it's off.
+
 ## What's emulated
 
 - **6510**: every opcode, documented and undocumented, with per-cycle
@@ -202,9 +220,9 @@ light pen registers.
 
 Known gaps:
 
-- No live audio in the emulator window. The SID is emulated, but the
-  whole machine runs below real time. `badline-sid` plays `.sid` tunes
-  on their own.
+- Live audio in the emulator window stutters, because the whole machine
+  runs below real time. `badline-sid` plays PSID tunes smoothly on
+  their own.
 - No drive emulation, so fast loaders and anything else that runs code
   on the drive won't work (see [Media](#media)). Disk images are
   read-only.

data/doc/pinned-behaviour.md

@@ -650,12 +650,24 @@ VICE x64sc's `vicii_fetch_graphics` and `draw_graphics8` for the 6569.
   - Pinned by `modesplit` (48 → 1222 px painting whole groups, 428 with
     MCM read at pixel 4), the `videomode` rows and `vicii_reg_timing`
     (pass → 274).
-  - `videomode2` and `videomode-y` disagree on where a falling BMM shows:
-    pixel 6 in `videomode2`, pixel 5 in `videomode-y` and in `modesplit`'s
-    ECM+BMM → ECM split. The readme says these delays vary with the chip
-    and its temperature. badline keeps VICE's pixel 6, which passes
-    `videomode2` and leaves `videomode-y` 1 px off and all 48 px left in
-    `modesplit`, one pixel on each of its first-section lines.
+  - A falling BMM shows at pixel 5 instead of 6 unless it leaves hi-res
+    bitmap: out of multicolour bitmap, and out of the invalid ECM+BMM
+    modes, whether ECM falls with it or stays.
+    - Pinned by `modesplit` (48 px → pass), whose first section drops BMM
+      out of ECM+BMM, by the E+B row of `vicii_reg_timing-a5` and `-ff`
+      (7 px each → pass), which drops ECM and BMM together, and by
+      `videomode-y` (1 px → pass), which drops it out of multicolour
+      bitmap. The hi-res exception is pinned by `videomode2` and the BMM
+      row of `vicii_reg_timing` (pass → 1 and 7 px without it).
+    - Two references disagree, and both are marked unsafe in the
+      testlist: `videomode-v` drops BMM out of multicolour bitmap and
+      `videomode-w` out of ECM+BMM, and both want pixel 6 (+1 px each).
+      The readme says these delays vary with the chip and its
+      temperature.
+    - Spec guard: *takes a BMM falling out of hi-res bitmap at pixel 6*,
+      *out of ECM+BMM at pixel 5* and *out of multicolour bitmap at
+      pixel 5* in
+      [`vic/graphics_shifter_spec.rb`](../spec/badline/vic/graphics_shifter_spec.rb).
   - An MCM that falls out of the invalid ECM+MCM text mode is a pixel
     later on both counts. The lookup stays black through pixel 4 and
     changes at pixel 5, and the pairs are read through pixel 7, with

data/exe/badline

@@ -6,7 +6,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 require "optparse"
 
-options = { autostart: true, jit: true }
+options = { autostart: true, jit: true, sound: false }
 
 parser = OptionParser.new do |opts|
   opts.banner = <<~BANNER
@@ -32,6 +32,8 @@ parser = OptionParser.new do |opts|
     options[:sid_model] = model
   end
 
+  opts.on("--sound", "Play the SID through the host's audio device (F10 mutes)") { options[:sound] = true }
+
   opts.on("--disable-jit", "Run without enabling YJIT") do
     options[:jit] = false
   end
@@ -64,7 +66,8 @@ require "badline/gui"
 
 begin
   application = Badline::GUI::Application.new(media_path:, autostart: options[:autostart],
-                                              song: options[:song], sid_model: options[:sid_model])
+                                              song: options[:song], sid_model: options[:sid_model],
+                                              sound: options[:sound])
 rescue Badline::Storage::SIDFile::FormatError, Badline::Storage::T64::FormatError,
        Badline::Storage::TAP::FormatError, Badline::Storage::CRTFile::FormatError,
        Badline::Cartridge::UnsupportedTypeError => e

data/lib/badline/address_bus.rb

@@ -180,10 +180,12 @@ module Badline
       end
     end
 
+    # EXROM and GAME select the cartridge whether or not it has a chip
+    # there, and an empty socket leaves the bus floating.
     def map_rom_overlays
-      @read_pages.fill(@cartridge.roml, 0x80, 0x20) if roml?
+      @read_pages.fill(@cartridge.roml || @open_bus, 0x80, 0x20) if roml?
       if romh?
-        @read_pages.fill(@cartridge.romh, 0xa0, 0x20)
+        @read_pages.fill(@cartridge.romh || @open_bus, 0xa0, 0x20)
       elsif basic?
         @read_pages.fill(basic_rom, 0xa0, 0x20)
       end
@@ -254,11 +256,11 @@ module Badline
     end
 
     def roml?
-      @cartridge&.roml && @cartridge.exrom.zero? && io_port.kernal? && io_port.basic?
+      @cartridge&.exrom&.zero? && io_port.kernal? && io_port.basic?
     end
 
     def romh?
-      @cartridge&.romh && @cartridge.exrom.zero? && @cartridge.game.zero? && io_port.kernal?
+      @cartridge&.exrom&.zero? && @cartridge.game.zero? && io_port.kernal?
     end
 
     # In 16K mode LORAM alone leaves $d000 as RAM, where it still maps I/O.

data/lib/badline/addressable.rb

@@ -51,7 +51,7 @@ module Badline
 
     private
 
-    def index(addr)
+    def offset_of(addr)
       i = addr - @start
       raise OutOfBoundsError, "#{addr.inspect} (#{range})" unless i >= 0 && i < @length
 

data/lib/badline/audio/bare_player.rb

@@ -8,6 +8,10 @@ module Badline
     # which is what makes this path about three times faster than the whole
     # machine.
     #
+    # Nothing on the rig ties it to PAL, so an NTSC tune gets an NTSC
+    # machine: 60 Hz frames, the NTSC KERNAL's timer and `$02a6`, and a
+    # clock of 1022727 Hz for the SID's output.
+    #
     # Calls go through a six-byte stub whose JSR operand the dispatch trap
     # rewrites:
     #
@@ -23,6 +27,11 @@ module Badline
       # 312 raster lines of 63 cycles.
       FRAME_CYCLES = 19_656
 
+      # 263 raster lines of 65 cycles.
+      NTSC_FRAME_CYCLES = 17_095
+
+      NTSC_CLOCK_HZ = 1_022_727
+
       # A tune's init routine is free to unpack itself, but not forever.
       INIT_LIMIT = 10_000_000
 
@@ -30,6 +39,11 @@ module Badline
       # second.
       KERNAL_TIMER = 0x4025
 
+      NTSC_KERNAL_TIMER = 0x4295
+
+      # The KERNAL's PAL/NTSC flag, 1 for PAL.
+      VIDEO_STANDARD = 0x02a6
+
       attr_reader :sid
 
       def initialize(tune, song: nil, sid_model: tune.sid_model)
@@ -39,7 +53,8 @@ module Badline
         # The CPU port as the KERNAL leaves it, which a PSID tune expects.
         @bus.poke(0x00, 0x2f)
         @bus.poke(0x01, 0x37)
-        @bus.cia1.timer_a_latch = KERNAL_TIMER
+        @bus.poke(VIDEO_STANDARD, tune.ntsc? ? 0 : 1)
+        @bus.cia1.timer_a_latch = tune.ntsc? ? NTSC_KERNAL_TIMER : KERNAL_TIMER
         @cpu = CPU.new(@bus)
         @sid = @bus.sid
         @idle = false
@@ -67,12 +82,14 @@ module Badline
         cycles
       end
 
+      def clock_hz = @tune.ntsc? ? NTSC_CLOCK_HZ : TimeOfDay::CLOCK_HZ
+
       private
 
-      # A PAL frame, or for a CIA-timed song one period of CIA 1 timer A,
+      # A video frame, or for a CIA-timed song one period of CIA 1 timer A,
       # which init and play are both free to reprogram.
       def period
-        return FRAME_CYCLES unless @tune.cia_timed?(@song + 1)
+        return (@tune.ntsc? ? NTSC_FRAME_CYCLES : FRAME_CYCLES) unless @tune.cia_timed?(@song + 1)
 
         @bus.cia1.timer_a_latch + 1
       end

data/lib/badline/audio/machine_player.rb

@@ -4,8 +4,8 @@ module Badline
   module Audio
     # Runs a tune on the whole machine, for the RSID tunes that install their
     # own interrupts and expect a booted C64 underneath. The tune goes in
-    # through the same stub `Media` uses and BASIC SYSes it; rendering starts
-    # when the CPU reaches that stub.
+    # the way `Media` puts it in: BASIC SYSes the driver stub, or RUNs a
+    # BASIC tune. Rendering starts when the CPU gets there.
     class MachinePlayer
       FRAME_CYCLES = BarePlayer::FRAME_CYCLES
 
@@ -22,12 +22,15 @@ module Badline
 
       def start
         @computer.on_init { inject }
-        @computer.cpu.install_trap(@tune.driver_address) { begin_playing }
+        @computer.cpu.install_trap(@tune.entry_address) { begin_playing }
         @computer.cycle! until @started || @computer.cycles > START_LIMIT
       end
 
       def sid = @computer.sid
 
+      # The machine is PAL whatever the tune asks for.
+      def clock_hz = TimeOfDay::CLOCK_HZ
+
       # Advances one PAL frame, or `budget` cycles if that is shorter, then
       # yields whatever the SID recorded over it. Returns the cycles advanced.
       def frame(budget, &)
@@ -41,13 +44,13 @@ module Badline
 
       def inject
         @computer.ram.write(@tune.load_address, @tune.data)
-        @computer.ram.write(@tune.driver_address, @tune.driver(song: @song))
-        @computer.type_text("sys#{@tune.driver_address}\r")
+        @tune.boot_memory(song: @song).each { |address, bytes| @computer.ram.write(address, bytes) }
+        @computer.type_text(@tune.boot_command)
         @injected = true
       end
 
       def begin_playing
-        return unless @injected
+        return if @started || !@injected
 
         @computer.sid.synthesize!
         @started = true

data/lib/badline/audio/renderer.rb

@@ -60,7 +60,7 @@ module Badline
       # The cycles it takes to close exactly `total_samples` windows; the SID
       # records floor(cycles * rate / clock) of them.
       def total_cycles
-        ((total_samples * TimeOfDay::CLOCK_HZ) + @rate - 1) / @rate
+        ((total_samples * player.clock_hz) + @rate - 1) / @rate
       end
 
       def container_for(path)
@@ -71,13 +71,13 @@ module Badline
       end
 
       def each_frame
-        player.sid.record(rate: @rate, filter_chunk: @filter_chunk)
+        player.sid.record(rate: @rate, filter_chunk: @filter_chunk, clock_hz: player.clock_hz)
         total = total_cycles
         remaining = total
         while remaining.positive?
           samples = []
           remaining -= player.frame(remaining) { |sample| samples << sample }
-          yield samples, (total - remaining).fdiv(TimeOfDay::CLOCK_HZ)
+          yield samples, (total - remaining).fdiv(player.clock_hz)
         end
       end
     end

data/lib/badline/audio/stream.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Badline
+  module Audio
+    # Plays a running machine's SID through a sink, for the window: #feed
+    # queues whatever the SID recorded since the last call, once a frame,
+    # and #pace holds the machine to the device's clock.
+    #
+    # The device starts once the queue holds `ahead` seconds. Below real time
+    # the queue runs dry, and the device then stops until it holds `ahead`
+    # again, so the sound stutters with silent gaps rather than slowing
+    # down; `on_underrun` hears about the first time. A frame that would
+    # take the queue past `limit` seconds, as an unpaced machine above real
+    # time makes, is dropped whole.
+    class Stream
+      AHEAD = 0.08
+      LIMIT = 0.25
+
+      attr_reader :underruns, :dropped
+
+      # What #pace reads the time from and sleeps on: #now and #sleep.
+      attr_writer :clock
+
+      def initialize(sink, sid, ahead: AHEAD, limit: LIMIT, on_underrun: nil)
+        @sink = sink
+        @sid = sid
+        @ahead = ahead
+        @limit = limit
+        @on_underrun = on_underrun
+        @clock = Clock.new
+        @next_frame = nil
+        @started = false
+        @muted = false
+        @underruns = 0
+        @dropped = 0
+        sid.record(rate: sink.rate)
+      end
+
+      def rate = @sink.rate
+
+      def muted? = @muted
+
+      def playing? = @started
+
+      # Muting drops the queue; unmuting fills it to `ahead` again before
+      # the device restarts.
+      def toggle_mute
+        @muted = !@muted
+        return unless @muted
+
+        halt
+        @sink.clear
+      end
+
+      def feed
+        samples = @sid.drain_samples
+        return if @muted || samples.empty?
+
+        queued = @sink.queued_seconds
+        return @dropped += samples.size if queued + samples.size.fdiv(rate) > @limit
+
+        underrun! if @started && queued.zero?
+        @sink.queue(samples)
+        start if @sink.queued_seconds >= @ahead
+      end
+
+      # Waits out the frame just run. While the device plays, that is until
+      # it has played the queue down to `ahead`, so the machine runs at the
+      # device's rate and the queue neither drifts dry nor grows. Muted or
+      # filling up, the clock paces frames `seconds` apart instead.
+      def pace(seconds)
+        return wait_for_device if playing?
+
+        now = @clock.now
+        @next_frame = now if @next_frame.nil? || @next_frame < now
+        @clock.sleep(@next_frame - now)
+        @next_frame += seconds
+      end
+
+      def close = @sink.close
+
+      private
+
+      def start
+        return if @started
+
+        @started = true
+        @sink.start
+      end
+
+      def wait_for_device
+        @next_frame = nil
+        while (excess = @sink.queued_seconds - @ahead).positive?
+          @clock.sleep([excess, 0.001].max)
+        end
+      end
+
+      def halt
+        @started = false
+        @sink.pause
+      end
+
+      def underrun!
+        @underruns += 1
+        @on_underrun&.call if @underruns == 1
+        halt
+      end
+
+      # The host's monotonic clock.
+      class Clock
+        def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        def sleep(seconds) = Kernel.sleep(seconds)
+      end
+    end
+  end
+end

data/lib/badline/audio.rb

@@ -9,6 +9,7 @@ require "badline/audio/machine_player"
 require "badline/audio/renderer"
 require "badline/audio/sdl_sink"
 require "badline/audio/playback"
+require "badline/audio/stream"
 require "badline/audio/console"
 require "badline/audio/jukebox"
 require "badline/audio/cli"

data/lib/badline/cartridge/easy_flash.rb

@@ -18,7 +18,10 @@ module Badline
     class EasyFlash < Cartridge
       BANKS = 64
       EAPI_OFFSET = 0x1800
-      EAPI = File.binread(File.expand_path("../roms/eapi/eapi-am29f040-14", __dir__)).bytes.drop(2).freeze
+
+      def self.eapi
+        @eapi ||= ROM.read("eapi/eapi-am29f040-14").drop(2).freeze
+      end
 
       attr_reader :low_flash, :high_flash
 
@@ -110,7 +113,8 @@ module Badline
       def install_eapi(high)
         return unless high[EAPI_OFFSET, 4] == "eapi".bytes
 
-        high[EAPI_OFFSET, EAPI.length] = EAPI
+        eapi = EasyFlash.eapi
+        high[EAPI_OFFSET, eapi.length] = eapi
       end
 
       def place(flash_data, offset, bytes)

data/lib/badline/cartridge/epyx_fastload.rb

@@ -61,7 +61,7 @@ module Badline
       end
 
       def install_chips(chips)
-        @rom = banks_from(chips).first.compact.first
+        @rom = banks_from(chips).first.compact.first || EMPTY_BANK
         @roml = Window.new(self, @rom)
         @discharged_at = 0
         self.mode = :rom8k

data/lib/badline/cartridge/mach5.rb

@@ -26,7 +26,7 @@ module Badline
       private
 
       def install_chips(chips)
-        @roml = banks_from(chips).first.compact.first
+        @roml = banks_from(chips).first.compact.first || EMPTY_BANK
         reset
       end
     end

data/lib/badline/cartridge/magic_desk.rb

@@ -2,12 +2,15 @@
 
 module Badline
   class Cartridge
+    # Magic Desk: up to 128 8K banks. A write to I/O 1 selects the bank from
+    # bits 0-6, masked to the size of the ROM and at least four banks, and
+    # switches the ROM out with bit 7.
     class MagicDesk < Cartridge
       def poke(addr, value)
         return if addr > 0xdeff
 
         @exrom = value.anybits?(0x80) ? 1 : 0
-        @roml = @banks[(value & 0x3f) % @banks.length]
+        @roml = bank(@banks, value & @bank_mask)
         changed!
       end
 
@@ -19,6 +22,7 @@ module Badline
 
       def install_chips(chips)
         @banks = banks_from(chips).first
+        @bank_mask = (bank_mask(@banks) | 0x03) & 0x7f
         reset
       end
     end

data/lib/badline/cartridge/ocean.rb

@@ -2,11 +2,13 @@
 
 module Badline
   class Cartridge
+    # Ocean: up to 64 8K banks. A write to I/O 1 selects the bank from bits
+    # 0-5, masked to the size of the ROM.
     class Ocean < Cartridge
       def poke(addr, value)
         return if addr > 0xdeff
 
-        select_bank((value & 0x3f) % @banks.length)
+        select_bank(value & @bank_mask)
         changed!
       end
 
@@ -19,12 +21,13 @@ module Badline
 
       # In 16K mode the selected bank shows through ROMH as well.
       def select_bank(number)
-        @roml = @banks[number]
+        @roml = bank(@banks, number)
         @romh = @roml if game.zero?
       end
 
       def install_chips(chips)
         @banks = banks_from(chips).first
+        @bank_mask = bank_mask(@banks) & 0x3f
         reset
       end
     end

data/lib/badline/cartridge/rex_utility.rb

@@ -25,7 +25,7 @@ module Badline
       private
 
       def install_chips(chips)
-        @roml = banks_from(chips).first.compact.first
+        @roml = banks_from(chips).first.compact.first || EMPTY_BANK
         reset
       end
     end

data/lib/badline/cartridge/rgcd.rb

@@ -40,7 +40,7 @@ module Badline
 
       def install_chips(chips)
         @banks = banks_from(chips).first
-        @bank_mask = @hucky ? @banks.length - 1 : 0x07
+        @bank_mask = @hucky ? bank_mask(@banks) : 0x07
         reset
       end
     end

data/lib/badline/cartridge/simons_basic.rb

@@ -31,8 +31,8 @@ module Badline
 
       def install_chips(chips)
         roml, romh = banks_from(chips)
-        @roml = roml.first
-        @romh = romh.first
+        @roml = bank(roml, 0)
+        @romh = bank(romh, 0)
         reset
       end
     end

data/lib/badline/cartridge/westermann.rb

@@ -25,8 +25,8 @@ module Badline
 
       def install_chips(chips)
         roml, romh = banks_from(chips)
-        @roml = roml.first
-        @romh = romh.first
+        @roml = bank(roml, 0)
+        @romh = bank(romh, 0)
         reset
       end
     end