badline 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d667997df6e72a7efd6d8789896402ef09b757c49ac0e1890f9041a22d37d83b
-  data.tar.gz: ca5e42cebc1e7c1b4879062fab85bd97961242213f6701db86fa57717b270e8d
+  metadata.gz: feaedb95b99aa7efed205645c112426a2649ad7a08c975708d085bf69a7e9555
+  data.tar.gz: b284281a2e1256f0fe94abf5174990ac8dc8a98cd7035f1cd53aebd3ccbefbd6
 SHA512:
-  metadata.gz: 8965b452eb8836de285dc76e7d8220a3b302b81341ee277ab9738ea334e5d27f108b14e1b162b3fe28e88f7aa2fba1e1e30e4dd5fe2b4f7c579643c45e820070
-  data.tar.gz: 6603b0599428aef7a8bd0b1b5b99300281d02dbde1bd327895dc055a30ce16f2bdfc758b37661bca18eca256b0e98e5080926426dabbf0997c6a96762d7e3793
+  metadata.gz: 870ff9cb5c9a9d65c8e9dd8dee6cc87a45871c1a07c79c4b9dc69a692600c3167f92b1debca0f860ab96b783a81bb608276542322b17e305acb82e95c9fc560b
+  data.tar.gz: 7c12bf1fd073b2b0e58e41195d67316f0c518a0f5b8c013ded19f025b48456fea738e5ad3df26a796c84151638e8c0449b5bf14b7d013fcb876c61db5d2d9469

data/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## [0.8.0](https://github.com/elektronaut/badline/compare/v0.7.0...v0.8.0) (2026-10-03)
+
+
+### ⚠ BREAKING CHANGES
+
+* F9 opens the pause menu instead of swapping the joysticks, which the Ports page does now, and Tab no longer steps through the mouse and paddle modes.
+* --read-only is gone, and disks are write-protected by default. Pass --writable to let the machine write to a disk image.
+
+### Features
+
+* find the disks of a set by their names ([b2a4ba4](https://github.com/elektronaut/badline/commit/b2a4ba47bb4c9d4175130104c4dd2d3d2d5e570a))
+* pause the machine in a menu on F9 ([8b2568c](https://github.com/elektronaut/badline/commit/8b2568c8ebe894c3da56d404217189dc7b27db84))
+* put disks in write-protected unless --writable ([aed9fa1](https://github.com/elektronaut/badline/commit/aed9fa173007c85a5b9c19840e011d34f5b6b615))
+
+
+### Bug Fixes
+
+* stop printing that the window runs below real time ([86a57a6](https://github.com/elektronaut/badline/commit/86a57a635189a8e46e285773ce62ecbf1dd5adde))
+
+## [0.7.0](https://github.com/elektronaut/badline/compare/v0.6.1...v0.7.0) (2026-10-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* call a .sid tune's parts subtunes everywhere
+
+### Features
+
+* add a badline sid subcommand that plays tunes and directories ([7dfc21b](https://github.com/elektronaut/badline/commit/7dfc21b5e4ba47cd37a4593da61e95bb1d2329ab))
+* drop .sid files and folders on the SID player to queue them ([cc1f434](https://github.com/elektronaut/badline/commit/cc1f434b7404ded067ef43d1d3d5aa53d338de4c))
+* end a subtune with no known length when it falls silent ([46c4f10](https://github.com/elektronaut/badline/commit/46c4f1064f6382872ec22989253bc9c159f78dcf))
+* open a .sid tune, or no tune at all, in the SID player ([396c010](https://github.com/elektronaut/badline/commit/396c010ee626f95fbb71ced8bf3905909c470c8e))
+* play 2SID and 3SID tunes in stereo in the SID player ([7c72eef](https://github.com/elektronaut/badline/commit/7c72eeff7e5e7b1c56286f9bf6030ae3408f7176))
+* play a queue of tunes, with shuffle, loop and play-all subtunes ([d163106](https://github.com/elektronaut/badline/commit/d163106eea99d90f6ffe74fb91474a2aca4c64eb))
+* play sid tunes in a window that shows what the SID is doing ([60bfd3f](https://github.com/elektronaut/badline/commit/60bfd3f75fe82d928afa374d257d3d21e5ac29ad))
+* seek forward from where the subtune is, not from its start ([34059e8](https://github.com/elektronaut/badline/commit/34059e8f9b12cab44c94124e6455fef9c915d8eb))
+* seek within a subtune, and let the slow warning lapse ([b98ac6e](https://github.com/elektronaut/badline/commit/b98ac6eb6f9c0ce088545f55cc5f2445dd38dd2d))
+* show a tune's STIL entry in the SID player ([82d9dca](https://github.com/elektronaut/badline/commit/82d9dca26d7cefe853a6af41e50fc723a3e90170))
+* show each voice's live output in the SID view ([c61a128](https://github.com/elektronaut/badline/commit/c61a1289983887c0175fca3dc4c37b470e96de92))
+* show HVSC's STIL in the SID player ([bd55c0c](https://github.com/elektronaut/badline/commit/bd55c0c87695ba8cc84dbfd51ab2119a97eccded))
+* show where a seek is headed on the SID player's bar ([1a84b37](https://github.com/elektronaut/badline/commit/1a84b3746a960dba28dc9c789b3d2cd1520d2f94))
+* step subtunes and tunes on separate keys, add --all-subtunes ([eaef338](https://github.com/elektronaut/badline/commit/eaef3384e6205163e2a4b63f5aa8d9204fe5190f))
+* switch a SID between the 6581 and 8580 while it runs ([5920391](https://github.com/elektronaut/badline/commit/592039123d7936b8d22c8fd5f144a9bc9a8f383b))
+
+
+### Bug Fixes
+
+* build the native badline with a Spinel that keeps an array joined mid-expression alive ([d2c4eb2](https://github.com/elektronaut/badline/commit/d2c4eb20d6b80494fb2a20105c0532f3778b205c))
+* build the native badline with a Spinel that reports render progress ([58524ea](https://github.com/elektronaut/badline/commit/58524eaf4881661e7e0e9dd38c32071545bf1fae))
+* show non-ASCII text from a .sid header in the native badline ([959bb6f](https://github.com/elektronaut/badline/commit/959bb6f7d07de4c90ac50ae51ae63f3c66601a78))
+
+
+### Performance Improvements
+
+* draw the SID player's traces in one call each ([afcae15](https://github.com/elektronaut/badline/commit/afcae15ed273aa7a6dd49cb31e0f7180c56feb75))
+
 ## [0.6.1](https://github.com/elektronaut/badline/compare/v0.6.0...v0.6.1) (2026-09-30)
 
 

data/CLAUDE.md

@@ -164,7 +164,9 @@ the rows your change can't reach tell you nothing about it.
 - A pull request's CI is the verdict. It runs every suite on the Spinel
   build, compared row by row against
   `test/baselines/`, and every job is a required check. A row that moved
-  fails it. Re-record only those rows, in the same change:
+  fails it. A pull request that changes only docs, or only a release's
+  version bump, skips the specs and suites; pushes to main always run
+  them. Re-record only those rows, in the same change:
   `rake "regression:record:<suite>[filter,...]"` (quote it, because zsh
   globs the brackets). It runs only the matching tests on CRuby and
   splices their rows into the baseline, and every other row keeps its

data/README.md

@@ -56,46 +56,47 @@ badline game.prg       # Load and run a program
 badline game.d64       # Mount a disk image as device 8 and load it
 badline game.tap       # Insert a tape and load it
 badline game.crt       # Attach a cartridge
-badline tune.sid       # Play a SID tune
+badline tune.sid       # Play a SID tune in the SID player
 badline game.vsf       # Restore a snapshot, from badline or VICE
 badline ~/c64          # Mount a directory as device 8
 ```
 
-`badline-ruby` takes the same media and the same options, with the
-differences noted below.
-
 Programs, disk and tape images and SID tunes start automatically, and
 a cartridge starts itself. A mounted directory waits for you to `LOAD`
-from it. `--no-autostart` attaches the media and stops at `READY.`, so
-you can type the `LOAD` yourself. `--read-only` mounts a disk image
-write-protected, so the drive reports `26,WRITE PROTECT ON` for any
-write and the image file stays as it was. `--song N` picks a subtune of a
-`.sid` file, `--sid 8580` fits the newer SID and `--reu 512` plugs in a
-512K RAM Expansion Unit. `--ntsc` runs an NTSC C64, with the 6567R8
-VIC-II, instead of a PAL one. `badline-ruby` also
-takes `--disable-jit`, which runs without YJIT, otherwise switched on at
-startup. `--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.
-
-Both run the same window. `badline` plays the SID through the host's
-audio device, and `F10` mutes and unmutes it. `--no-sound` turns it
-off. The window is paced by the display's vsync; `--no-vsync` paces it
-by a timer, or by the sound while it plays.
-
-`--verbose` prints the display's refresh rate, the sound's sample rate
-and the game controllers found as the window opens, then the frame rate
-and the time each frame takes, once a second.
-
-For a scripted run, `--frames N` quits after N frames, `--unpaced` runs
-as fast as it can and `--at FRAME:EVENT` presses keys, types, swaps
-media and takes screenshots once that many frames have run. `--script
-FILE` takes one `FRAME:EVENT` a line:
+from it.
+
+`badline-ruby` takes the same media and the same options, with the
+differences noted in the table. `--help` lists the options for either.
+
+### Options
+
+| Option | Effect |
+| --- | --- |
+| `--no-autostart` | Attach the media and stop at `READY.`, so you can type the `LOAD` yourself |
+| `--writable` | Let the machine write to disk images. Without it, a disk goes in write-protected: the drive reports `26,WRITE PROTECT ON` for any write and the image file stays as it was |
+| `--true-drive` | Put an emulated 1541 on device 8 instead of the KERNAL traps. See [Media](#media) |
+| `-s`, `--subtune N` | Pick a subtune of a `.sid` file, counting from 1 |
+| `--sid 6581`, `--sid 8580` | Fit the older or newer SID. `--sid auto`, the default, takes a `.sid` tune's own |
+| `--reu SIZE` | Plug in a RAM Expansion Unit of `SIZE` K: 128, 256, 512 (a 1750) or up to 16384 |
+| `--ntsc` | Run an NTSC C64, with the 6567R8 VIC-II, instead of a PAL one |
+| `--no-sound` | Don't play the SID (`badline` only, where sound is on by default) |
+| `--sound` | Play the SID (`badline-ruby`, where sound is off by default) |
+| `--no-vsync` | Pace the window by a timer, or by the sound while it plays, instead of the display's vsync |
+| `--verbose` | Print the display's refresh rate, the sound's sample rate and the game controllers found as the window opens, then the frame rate and the time each frame takes, once a second |
+| `--disable-jit` | Run without YJIT, otherwise switched on at startup (`badline-ruby` only) |
+| `--version` | Show the version and what built it (`badline` only) |
+| `-h`, `--help` | List the options |
+
+### Scripted runs
+
+| Option | Effect |
+| --- | --- |
+| `--frames N` | Quit after N frames |
+| `--unpaced` | Run as fast as it can, without vsync or pacing |
+| `--at FRAME:EVENT` | Press keys, type, swap media or take a screenshot once `FRAME` frames have run |
+| `--script FILE` | Run the events in `FILE`, one `FRAME:EVENT` a line |
+| `--screenshot FILE` | Save the last frame as a `.bmp` |
+| `--save-snapshot FILE` | Save the machine as a `.vsf` snapshot after the last frame |
 
 ```sh
 badline --unpaced --frames 12000 --true-drive disk1.d64 \
@@ -106,161 +107,57 @@ badline --unpaced --frames 12000 --true-drive disk1.d64 \
 `--help` lists the events, and [native/README.md](native/README.md#running)
 describes them.
 
-In `badline-ruby` sound is off by default, and `--sound` turns it on.
-The machine runs below real time there, so the sound stutters: it plays
-in bursts with silent gaps between them, at the right pitch, and never
-slows the emulation down.
+Other KERNAL, BASIC or character ROMs, and using badline as a Ruby
+library, are covered in [doc/library.md](doc/library.md).
 
 ## Media
 
 | Format | Handling |
 |--------|----------|
 | `.prg`, `.p00` | Loaded into memory after boot. A program at the BASIC start (`$0801`) is `RUN`, anything else is left for you to `SYS` |
-| `.d64`, `.d71`, `.d81` | Mounted read-write as device 8, then `LOAD"*",8,1` and `RUN`. Writes go straight back to the image file. With `--read-only`, or an image the host can't write, it acts as a write-protected disk |
-| `.g64` | Put in a true 1541, which is plugged in as device 8 for it, then `LOAD"*",8,1` and `RUN`. The image holds the disk's raw GCR, half tracks and all, so copy protection and fast loaders that read it work. Tracks the drive writes go back to the image file. With `--read-only`, or an image the host can't write, it acts as a write-protected disk |
+| `.d64`, `.d71`, `.d81` | Mounted as device 8, then `LOAD"*",8,1` and `RUN`. Write-protected unless `--writable` |
+| `.g64` | Put in a true 1541, then `LOAD"*",8,1` and `RUN`. It holds the disk's raw GCR, so copy protection that reads it works. Write-protected unless `--writable` |
 | `.t64` | Mounted read-only as device 8 and loaded like a disk image. The files load by name, and no tape is involved |
 | `.tap` | Inserted in the datasette with PLAY pressed, then `LOAD` and `RUN`. It loads at the speed of a real tape |
 | `.crt` | The hardware types listed under [Cartridges](#whats-emulated). Other types are rejected |
 | `.sid` | PSID and RSID tunes, started through a small driver after boot |
 | `.vsf` | A snapshot of a running machine, badline's own or one VICE's x64sc saved. See [Snapshots](#snapshots) |
-| A directory | Mounted read-write as device 8. It serves the `.prg` and `.p00` files in it and the contents of any `.t64`, and `SAVE` writes a new `.prg` |
-
-Apart from a `.g64`, which only a true drive can read, there is no 1541
-unless `--true-drive` asks for one. Device 8 works by trapping the
-KERNAL's `LOAD` and `SAVE` routines and its serial bus primitives, so
-files open by name through `OPEN` and `CHRIN` as well. `LOAD"$",8` lists
-the directory of any medium mounted there, as a 1541 does. The command
-channel answers `I`, `B-P` and `U1` block reads, which covers loaders
-that read blocks directly. On a disk image it also takes `SAVE` (with
-`@0:` to replace a file), files opened for writing or appending, `S` to
-scratch, `U2` and `B-W` block writes, and `B-A` and `B-F`. Loaders that
-upload their own code to the drive with `M-W` and `M-E`, and copy
-protection that reads raw GCR, won't work there, but do on a true
-drive.
-
-`--true-drive` puts an emulated 1541 on device 8 instead, running its
-own DOS ROM on its own 6502 and talking to the machine over the serial
-bus. It reads `.d64` and `.g64` images, which it autostarts with the
-same `LOAD"*",8,1` and `RUN`, but not `.d71`, `.d81` or `.t64` images
-or directories. `--read-only` puts the disk in write-protected. Loading
-runs at the speed of a real 1541, and the drive's red LED lights in the
-bottom right corner of the border. Both executables take it.
-
-`Badline::Media.insert_disk(computer, path)` swaps the disk image or
-directory in device 8 while the machine runs, for software that asks for
-another disk. It takes `read_only: true`, and `Badline::Media.attach`
-takes `disk: { read_only: true }`, to mount a disk image write-protected,
-as the test harnesses under `bin/` do. A `.g64` goes in the true 1541,
-and takes out a disk mounted through the traps, so `LOAD` and `SAVE`
-reach the 1541 too. With the 1541 in device 8, a `.d64` goes in its
-drive as well.
+| A directory | Mounted as device 8. It serves the `.prg` and `.p00` files in it and the contents of any `.t64`, and `SAVE` writes a new `.prg` |
+
+Without `--true-drive`, device 8 is no drive at all but traps on the
+KERNAL's disk routines. Loading is instant, but fast loaders and copy
+protection that run code on the drive need `--true-drive`, which puts
+an emulated 1541 there, running its own DOS at a real 1541's speed. Its
+red LED lights in the bottom right corner of the border.
+[doc/media.md](doc/media.md) has the details, and how to attach media
+from Ruby.
 
 ## Snapshots
 
-In the window, `F11` saves the whole machine to a new
-`badline-<date>-<time>.vsf` in the working directory, and `F12` goes
-back to the snapshot last saved or opened, in a new machine built as the
-saved one was. Both executables do this, and both open a `.vsf` given as
-the media. A snapshot that fails to open leaves the machine running as
-it was. From Ruby, `computer.save_snapshot(path)` saves,
-`computer.restore_snapshot(path)` takes a machine back to a snapshot,
-and `Badline::Snapshot.load(path)` builds a new machine as the saved one
-was built and restores it. `computer.snapshot` and
-`computer.restore(state)` do the same in memory, without a file. A
-restore that fails leaves the machine as it was.
-
-A snapshot holds the machine as it was on the cycle it was saved: the
-chips down to the instruction step and the pixel pipeline, the RAM and
-any +60K or +256K expansion, the cartridge with its RAM and flash, a
-GEO-RAM, a true 1541 with its RAM, its VIAs and the disk under the head,
-a disk or directory mounted through the traps with its open channels,
-and the tape with its place on it. A restored machine runs on exactly
-as the saved one would have. A directory, a tape and a true drive's
-disk image open again from their paths when the snapshot is restored,
-the disk with its tracks as the drive last saw them. A disk image mounted through the traps comes back
-with its contents from the snapshot. What the host holds stays the host's: the keyboard, the
-joysticks, the mouse and paddles, sound, and blocks given to `on_init`
-that hadn't run yet, which a restore reports. A snapshot only restores
-in the badline version that wrote it, into a machine with the same
-chip models, RAM expansion and REU. `computer.snapshot` holds an REU's
-RAM, registers and transfer too, but a machine with an REU doesn't save
-to a file yet, as badline doesn't write VICE's REU module.
-
-Snapshots use VICE's `.vsf` format. badline writes VICE's modules for
-the CPU, RAM and CPU port, both CIAs, the SID and the VIC-II, plus the
-ones x64sc needs to open the file, with nothing attached to the
-cartridge, tape or user ports and no true drive. A `BADLINE` module,
-which VICE skips, holds the whole machine, and badline restores its own
-snapshots from it.
-
-x64sc 3.10 opens badline's snapshots, taken at the end of the
-instruction the CPU was in, as long as its VIC-II model matches
-(`-model c64` for the default machine). It keeps its own drives and
-leaves out the cartridge, the expansions and the tape. Snapshots x64sc
-saves open in badline through the same modules: the CPU at its
-instruction boundary, RAM, the CPU port, the CIAs' registers, timers and
-clocks, the SID's registers and reSID voice state, and the VIC-II's
-registers, beam position, counters and colour RAM. The VIC-II's pixel
-pipeline starts empty. badline reads the modules x64sc 3.7 to 3.10
-write, and VICE's development versions' `MAINC64CPU` and `VIC-IISC`. A module version
-it doesn't know is left out, or fails the restore for the CPU and RAM.
-It reports the modules it leaves out, such as the 1541 drives, the
-cartridge, the datasette and the keyboard, and carries on without them.
-An NTSC snapshot fails, as badline runs PAL only. Restored into a
-running machine, a VICE snapshot fails for a machine built another way,
-such as a C64C's snapshot in a C64, and otherwise takes the cartridge
-out and switches the machine off and on.
+`F11` saves the whole machine to a new `badline-<date>-<time>.vsf` in
+the working directory, and `F12` goes back to the snapshot last saved
+or opened. Snapshots use VICE's `.vsf` format: badline opens those
+x64sc saves, and x64sc opens badline's. See
+[doc/snapshots.md](doc/snapshots.md) for what they hold and how far the
+two agree.
 
 ## Playing and rendering SID tunes
 
-`badline-ruby --headless` plays a `.sid` tune on the host's audio
-device without opening the window, and `--audio-out` renders it to a
-16-bit PCM file instead. The file's extension picks the format, `.wav`
-or `.aiff`. The native `badline` has both modes too.
-
 ```sh
-badline-ruby --headless tune.sid                             # play, length from HVSC
-badline-ruby --headless -s 3 tune.sid                        # play the third subtune
-badline-ruby --seconds 180 tune.sid --audio-out out.aiff
-badline-ruby -s 3 --rate 48000 tune.sid --audio-out out.wav
-badline-ruby --headless --sid 8580 tune.sid
-badline-ruby --filter-chunk 1 tune.sid --audio-out out.wav   # exact filter, slower
+badline tune.sid                                     # play a tune in the SID player
+badline sid ~/C64Music/MUSICIANS/H/Hubbard_Rob       # play every tune below a directory
+badline sid --headless tune.sid other.sid            # play a queue in the terminal
+badline --seconds 180 tune.sid --audio-out out.wav   # render to a .wav or .aiff
 ```
 
-Both modes take the same options. The window's own, `--no-autostart`,
-`--read-only`, `--sound`, `--true-drive`, `--reu`, `--ntsc` and
-`--verbose`, don't apply to them. `--song` (or `-s`) picks the subtune, counting from 1 as HVSC
-does, and defaults to the tune's own start song. Playback asks the
-device for 44.1 kHz and takes whatever rate it offers, unless `--rate`
-says otherwise. Ctrl-C stops it.
-
-Played on a terminal, `--headless` shows the tune's name, author and
-release, the song number and the time played against the song's
-length. When a song reaches its length it goes on to the next, and it
-stops after the last. `n` or → skips to the next song, `p` or ← goes
-back one, space pauses and `q` quits. `--no-tui`, or output that isn't a
-terminal, gives plain progress output instead and plays just the one
-song, as `--audio-out` renders just the one.
-
-A `.sid` file doesn't store its length, so `badline-ruby` looks the
-tune up by MD5 in HVSC's `Songlengths.md5`. It finds the database
-through `--songlengths`, in a `DOCUMENTS` directory in any of the
-tune's parent directories (the layout of an HVSC collection), or under
-`$HVSC_BASE/DOCUMENTS`. Without a database or `--seconds` it runs for
-60 seconds.
-
-PSID tunes run on a CPU and RAM with only the SID clocked, at about
-twice real time, so they play smoothly. RSID tunes set up their own
-interrupts, so they boot a full C64 first and run at about half real
-time. They render fine but stutter when played, and `badline-ruby` says
-so when it falls behind. The filter steps four cycles at a time;
-`--filter-chunk 1` steps it every cycle, which is exact and takes about
-twice as long. `badline-ruby --help` lists the options.
-
-The native `badline` takes the same options and runs the same code, so
-it renders the same file sample for sample, and it plays RSID tunes
-without stuttering. See
-[native/README.md](native/README.md#without-the-window).
+The SID player plays a queue of tunes, looking up each subtune's length
+and STIL entry in an HVSC collection. Its window shows each voice's
+note and output, the SID's registers, envelopes and filter, and the
+tune's STIL entry, and is worked with the mouse. Tunes for 2 or 3 SIDs
+play in stereo. [doc/sid-player.md](doc/sid-player.md) covers the
+options, the keys and the window.
+
+![The SID player's visualizer playing Rob Hubbard's Delta](doc/images/sid-player.png)
 
 ## Input
 
@@ -283,109 +180,97 @@ types `"`. These keys have no same-named host key:
 | `+` / `*` | Keypad `+` / Keypad `*` |
 | `RESTORE` | `Page Up` |
 
-`Tab` steps through the input modes and `Shift-Tab` steps back. The
-window title shows the current mode:
+`Tab` switches the keys between the C64 keyboard and the joysticks. The
+window title shows where they go, and any device plugged into a control
+port:
 
-| Mode | What the host drives |
-|------|----------------------|
+| Title | What the host drives |
+|-------|----------------------|
 | (none) | The keyboard |
-| `[JOY 2]` / `[JOY 1]` | Arrows and Space (or Right Ctrl) are the joystick named, `WASD` and Left Shift the other. `F9` swaps them |
+| `[JOY 2]` / `[JOY 1]` | Arrows and Space (or Right Ctrl) are the joystick named, `WASD` and Left Shift the other. SWAP JOYSTICKS on the pause menu's Ports page swaps them |
 | `[MOUSE 1]` / `[MOUSE 2]` | A 1351 mouse in control port 1 or 2 |
 | `[PADDLE 1]` / `[PADDLE 2]` | A pair of paddles in control port 1 or 2 |
 
-The mouse and paddle modes capture the host mouse until you `Tab` out of
-them. Moving it moves the 1351 or turns the two paddle knobs, and the
-left and right buttons are the 1351's buttons, or the fire buttons of
-paddles A and B. Games differ in which port they read, which is why each
-device has a mode per port.
+A 1351 mouse or a pair of paddles plugs into either port on the pause
+menu's Ports page, and stays there whichever way `Tab` sends the keys.
+While one is plugged in it holds the host mouse, and opening the pause
+menu lets go. Moving it moves the 1351 or turns the two paddle knobs,
+and the left and right buttons are the 1351's buttons, or the fire
+buttons of paddles A and B. Games differ in which port they read.
 
 Game controllers work in every mode. The first one is joystick 2 and
 the second is joystick 1. The D-pad and left stick steer, the face and
 shoulder buttons fire, and controllers can be connected or removed while
 the emulator runs.
 
-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.
-
 `F10` mutes and unmutes the sound, and the window title shows `[MUTED]`
 while it's off.
 
+## The pause menu
+
+`F9` pauses the machine and opens a menu over the frozen picture, and
+`F9` or `Esc` closes it again. On a Mac, hold `Fn` for `F9`, unless the
+function keys are set to work as standard function keys. Up and Down move
+through the rows, Right goes into a page and Left back out, and Return or
+Space presses a row. A row with choices steps to the next. The mouse works
+too.
+
+| Page | What it holds |
+|------|---------------|
+| Drive 8 | The disk: insert, eject, the previous or next disk of its set, and whether it's writable |
+| Datasette | The tape: insert, eject, PLAY and REWIND |
+| Expansion port | The cartridge: insert, remove, and its freeze button if it has one |
+| Ports | The device in each control port, and where the keys go |
+| Sound | Mute, and the SID's model |
+| Power | Reset, power cycle and quit |
+
+INSERT opens a file browser. A disk's set comes from the names in its
+folder: `Disk 1`, `Side B`, `d2`, TOSEC's `(Disk 1 of 2)`, or a trailing
+`_1`, `_2` when the first of the set is there. WRITABLE starts as
+`--writable` sets it and stays as set for the next disk. Quick open starts
+a file in a new machine, as the command line does. It asks first, as
+inserting or removing a cartridge does, since each power cycles the
+machine.
+
+A disk or tape dropped on the window goes into its drive. A cartridge,
+program or `.sid` dropped on it opens the menu to ask first.
+
 ## What's emulated
 
 - **6510**: every opcode, documented and undocumented, with per-cycle
   bus behaviour checked against the
   [65x02 single step tests](https://github.com/SingleStepTests/65x02).
-  `JAM` opcodes halt the CPU until reset.
-- **Memory**: banking through the 6510 port, including the cartridge
-  `EXROM`/`GAME` lines and Ultimax mode. The +60K and +256K RAM
-  expansions fit with `Badline::Computer.new(ram_expansion: :plus60k)` or
-  `:plus256k`, banked through their register at `$D100`.
-- **VIC-II** (PAL 6569): the five standard graphics modes and the
-  invalid ones, sprites with multicolour, expansion, priority and
-  pixel-level collisions, raster interrupts, bad lines, sprite DMA, the
-  border, VIC banks and the light pen.
-  `Badline::Computer.new(vic_model: :mos8565)` fits the C64C's 8565
-  instead, with its grey dots on colour register writes and its own
-  timing for mode splits, sprite multicolour splits and the light pen.
-  `Badline::Computer.new(region: Badline::Region::NTSC)` builds an NTSC
-  machine instead: the 6567R8's 65 cycles by 263 lines at 1,022,727 Hz,
-  with its later sprite fetches and its X counter, and TOD clocks on
-  60 Hz mains. `Badline::Region::NTSC_OLD` is the first NTSC C64s'
-  6567R56A, 64 cycles by 262 lines. The stock KERNAL tells them from PAL
-  by the raster, so every region boots the same ROMs. `--ntsc` picks the
-  6567R8.
-- **CIA 1 and 2**: timers, time-of-day clocks with alarms, the serial
-  shift register, interrupts, the keyboard matrix with its ghost keys,
-  the control ports and the paddle multiplexer. The machine has the
-  original 6526s; `Badline::Computer.new(cia_model: :mos6526a)` fits the
-  C64C's 6526As instead, whose interrupt register timing differs.
-- **SID**: the 6581 and the 8580, with oscillators, ring modulation and
-  sync, the envelope generator including the ADSR delay bug, the filter,
-  and the RC network on the board that removes the DC offset from the
-  output. The machine has a 6581 unless a `.sid` tune asks for an 8580
-  in its header, and `--sid 6581` or `--sid 8580` overrides either.
-- **REU**: the 1700, 1764 and 1750 RAM Expansion Units, and the bigger
-  units up to 16M built on the same REC chip, with DMA timed against the
-  VIC's bad lines and sprites. `--reu SIZE` plugs one in, and
-  `Badline::Computer.new(reu: 512)` does the same from Ruby. An
-  REU beside a cartridge loses I/O 2 to the cartridge.
-- **Datasette**: `.tap` playback into CIA 1's FLAG line, with the motor
-  and sense lines on the 6510 port.
+- **Memory**: banking through the 6510 port, the cartridge lines and
+  Ultimax mode, and the +60K and +256K RAM expansions.
+- **VIC-II**: the PAL 6569, the C64C's 8565, and NTSC's 6567R8 (`--ntsc`)
+  and 6567R56A: every graphics mode, sprites, collisions, bad lines,
+  sprite DMA, the border and the light pen.
+- **CIA 1 and 2**: the 6526 and the C64C's 6526A, with timers,
+  time-of-day clocks, the serial shift register, the keyboard matrix
+  and the control ports.
+- **SID**: the 6581 and the 8580, filter and all.
+- **REU**: the 1700, 1764 and 1750 and bigger units up to 16M
+  (`--reu`), with DMA timed against the VIC's bad lines and sprites.
+- **Datasette**: `.tap` playback.
+- **1541**: an emulated drive running its own DOS (`--true-drive`).
 - **Cartridges**: standard 8K, 16K and Ultimax, Simons' BASIC, Ocean,
-  Fun Play / Power Play, Super Games, Epyx FastLoad, Westermann Learning,
-  Rex Utility, C64 Game System / System 3, Dinamic, Zaxxon / Super Zaxxon,
-  Magic Desk, Comal-80, EasyFlash, Mach 5, Pagefox, RGCD and GMod2, and
-  the freezers Action Replay (v4.2 to v6), Atomic Power / Nordic Power,
-  Retro Replay / Nordic Replay, Final Cartridge III / III+ and the KCS
-  Power Cartridge.
-  EasyFlash and GMod2 flash takes writes through the chip's command set
-  (program, sector and chip erase, autoselect), so games and EAPI can
-  save to it. An EasyFlash image's EAPI is swapped for a bundled copy of
-  the Am29F040 EAPI on attach, as VICE does. The writes stay in memory
-  and are lost when the emulator quits: the `.crt` file is never
-  overwritten. The Retro Replay's flash
-  works the same way in flash mode, which the flash jumper enables:
-  `Media.attach(computer, path, cartridge: { flash_jumper: true })`, with
-  `bank_jumper: true` to run from the second 64K of a 128K image. The
-  GMod2 EEPROM and the Retro Replay clock port aren't there.
-- **GEO-RAM**: 64K to 4M of RAM seen through the `$DE00` page, with the
-  `$DFFE`/`$DFFF` page and block registers. It takes the expansion port,
-  so it can't sit alongside a cartridge:
-  `computer.attach_cartridge(Badline::Cartridge::GeoRAM.new(size: 512))`.
-  Its contents are lost when the emulator quits.
+  Fun Play / Power Play, Super Games, Epyx FastLoad, Westermann
+  Learning, Rex Utility, C64 Game System / System 3, Dinamic, Zaxxon /
+  Super Zaxxon, Magic Desk, Comal-80, EasyFlash, Mach 5, Pagefox, RGCD,
+  GMod2 and GEO-RAM, and the freezers Action Replay (v4.2 to v6), Atomic
+  Power / Nordic Power, Retro Replay / Nordic Replay, Final Cartridge III
+  / III+ and the KCS Power Cartridge. Flash writes stay in memory.
+
+Machines other than the default, and the cartridges' jumpers, are
+built from Ruby: see [doc/library.md](doc/library.md).
 
 Known gaps:
 
-- `badline-ruby` runs below real time, so its live audio stutters.
-  `badline` plays smoothly, and so do PSID tunes under
-  `badline-ruby --headless`.
+- `badline-ruby` runs below real time, so its sound, which `--sound`
+  turns on, stutters: it plays in bursts with silent gaps between them.
 - Without `--true-drive`, fast loaders and anything else that runs code
-  on the drive won't work (see [Media](#media)). The command channel
-  doesn't rename, copy, format or validate disks.
+  on the drive won't work.
 - No PAL-N (Drean) machine.
-- The emulator window has no freeze button yet, so a freezer cartridge
-  runs its menu but can't freeze a program.
 
 ## Contributing
 

data/doc/library.md

@@ -0,0 +1,62 @@
+# Using badline from Ruby
+
+The gem is also a library, which runs a `Badline::Computer` from Ruby
+without a window.
+
+```ruby
+require "badline"
+
+computer = Badline::Computer.new
+Badline::Media.attach(computer, "game.d64")         # attaches and autostarts
+computer.on_init { computer.type_text("print 6*7\r") } # once the machine has booted
+3_500_000.times { computer.cycle! }
+computer.address_bus.peek(0x0400)                   # screen RAM starts at $0400
+```
+
+[media.md](media.md) covers attaching and swapping media, and
+[snapshots.md](snapshots.md) saving and restoring the machine.
+
+## Building a machine
+
+`Badline::Computer.new` builds the default machine: a PAL C64 with the
+6569 VIC-II, 6526 CIAs and a 6581 SID. Its keywords build others:
+
+- `vic_model: :mos8565` fits the C64C's 8565, with its grey dots on
+  colour register writes and its own timing for mode splits, sprite
+  multicolour splits and the light pen.
+- `region: Badline::Region::NTSC` builds an NTSC machine: the 6567R8's
+  65 cycles by 263 lines at 1,022,727 Hz, with its later sprite fetches
+  and its X counter, and TOD clocks on 60 Hz mains.
+  `Badline::Region::NTSC_OLD` is the first NTSC C64s' 6567R56A, 64 cycles
+  by 262 lines. The stock KERNAL tells them from PAL by the raster, so
+  every region boots the same ROMs.
+- `cia_model: :mos6526a` fits the C64C's 6526As, whose interrupt
+  register timing differs.
+- `sid_model: :mos8580` fits the 8580.
+- `ram_expansion: :plus60k` or `:plus256k` fits the +60K or +256K RAM
+  expansion, banked through its register at `$D100`.
+- `reu: 512` plugs in a RAM Expansion Unit of that many K.
+
+## Cartridges
+
+`Media.attach(computer, path, cartridge: { flash_jumper: true })` sets
+the Retro Replay's flash jumper, which makes its flash take writes, and
+`bank_jumper: true` runs it from the second 64K of a 128K image.
+EasyFlash and GMod2 flash take writes through the chip's command set
+(program, sector and chip erase, autoselect), so games and EAPI can save
+to it. An EasyFlash image's EAPI is swapped for a bundled copy of the
+Am29F040 EAPI on attach, as VICE does. Flash writes stay in memory and
+are lost when the emulator quits: the `.crt` file is never overwritten.
+
+A GEO-RAM takes the expansion port, so it can't sit alongside a
+cartridge: `computer.attach_cartridge(Badline::Cartridge::GeoRAM.new(size: 512))`.
+Its contents are lost when the emulator quits.
+
+## ROMs
+
+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.
+`Badline.rom_path = dir` does the same before a `Badline::Computer` is
+built, and `nil` restores the bundled set.