vinsynlib 0.3.0__tar.gz → 0.4.0__tar.gz

{vinsynlib-0.3.0/src/vinsynlib.egg-info → vinsynlib-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vinsynlib
-Version: 0.3.0
+Version: 0.4.0
 Summary: Shared base for ROMpler instrument browsers: settings, favourites, banks, dumps, CLI and key conventions
 License-Expression: GPL-2.0-or-later
 Project-URL: Homepage, https://github.com/lentferj/vinsynlib
@@ -34,15 +34,17 @@ SPDX-FileCopyrightText: Copyright (C) 2026  vinsynLib contributors
 The shared base of a family of terminal instrument browsers.
 
 Nine sibling programs browse nine instruments over MIDI from a terminal:
-[emorphed](https://github.com/lentferj/emorphed) (E-mu Morpheus),
-[ensqsqed](https://github.com/lentferj/ensqsqed) (Ensoniq SQ-R Plus),
-[eosed](https://github.com/lentferj/eosed) (E-mu E4XT),
-[kwsed](https://github.com/lentferj/kwsed) (Korg Wavestation SR),
-[nanosyned](https://github.com/lentferj/nanosyned) (Alesis NanoSynth),
-[p2ked](https://github.com/lentferj/p2ked) (E-mu Proteus 2000),
+emorphed (E-mu Morpheus), ensqsqed (Ensoniq SQ-R Plus),
+[eosed](https://github.com/lentferj/eosed) (E-mu E4XT), kwsed (Korg
+Wavestation SR), nanosyned (Alesis NanoSynth), p2ked (E-mu Proteus 2000),
 [rxved](https://github.com/lentferj/rxved) (Roland XV-2020),
-[s3ked](https://github.com/lentferj/s3ked) (Akai S1000/S3000) and
-[x5ded](https://github.com/lentferj/x5ded) (Korg X5D/X5DR).
+[s3ked](https://github.com/lentferj/s3ked) (Akai S1000/S3000) and x5ded
+(Korg X5D/X5DR). Several of these repositories are not public yet, which is
+why only some of the names above are links.
+
+A tenth project, [k2kremote](https://github.com/lentferj/k2kremote), is a
+remote for the Kurzweil K2000 rather than a browser, and depends on the same
+shared code.
 
 They grew separately, which is the right way to learn what an instrument
 does and the wrong way to arrive at nine copies of the same code. This
@@ -51,93 +53,6 @@ a change to one of them happens once instead of nine times.
 
 ---
 
-## Support this project
-
- is free software and always will be. Nothing is behind a paywall, no
-feature is withheld, and none of what follows changes that.
-
-But if it has been useful — if it saved you an evening of mapping zones
-by hand, or got a library onto a machine that had no way of reading it, or
-**best of all, if it has your vintage instrument switched on and in use more often
-than it was, and you are having more fun with it** — then please consider
-supporting the work.
-
-**Because here is what it has actually cost:**
-
-- **Real machines on a real bench.** Much of what these tools know about these
-  formats was measured on hardware rather than read anywhere, because for most
-  of it there is nowhere to read it. That needs the machines — the instruments
-  themselves — and it puts hours of wear on hardware that has been locked up and
-  recovered more than once in the course of it. Some of these instruments were
-  bought specifically to add and verify a format; the others were already here,
-  because the person doing this is a vintage instrument enthusiast first and the
-  projects exist because the instruments were in the room.
-- **Dozens — realistically hundreds — of hours of human time.** Format
-  reverse-engineering is slow: measure, be wrong, measure again. A single
-  parameter law in this README can represent an evening at the bench.
-- **AI assistance, which is a paid service**, used heavily throughout and not
-  cheap at this volume.
-
-**This is support, not a donation — and the distinction is a legal one, not a
-turn of phrase.** The maintainer is based in Germany, where payments like these
-are *not* `Spenden` in the tax sense: they count as **taxable income** for the
-recipient and are **not tax-deductible** for the giver. So this section is
-titled *Support*, deliberately, and no receipt for tax purposes can be issued.
-(That is a statement of how it is handled here, not tax advice.)
-
-If the project saved you the work, you can support it through
-**[GitHub Sponsors](https://github.com/sponsors/lentferj)** — the *Sponsor*
-button at the top of the repository. Payment is handled entirely by GitHub and
-Stripe, so bank and tax details are never handed to the person paying.
-
-**Support is not expected, and it is not the only currency.**
-
-- **Bug reports** — ideally with the bank, preset or disk image that produced
-  them. A tool's failures are usually specific to one file rather than
-  general, and without that file they are very hard to reproduce.
-- **Confirmations from hardware that is not on this bench**, which matters more
-  here than for a single-machine tool. These tools write for whole *families*
-  of instruments, and the bench holds only a subset. Whether a variant accepts
-  what we write is genuinely unknown, and several notes say "on this unit" for
-  that reason. A "loads fine here too", or a "no, mine refuses it", is worth a
-  great deal.
-- **Corrections to the reverse-engineering notes.** The wrong turns are
-  recorded next to the findings in `docs/RESOLUTION_NOTES.md` — retractions
-  included, because a finding that was withdrawn is as useful as one that
-  stood. If any of it is wrong in a way that is still costing someone time,
-  saying so improves the record.
-
----
-
-## AI assistance & human authorship
-
- was built by its human author together with AI assistance. The
-**ideas, the project vision, and every feature** came from the human author;
-AI assisted with **writing the code and analyzing the binary formats**.
-Crucially, the **reverse engineering rests on hands-on human work** — all testing
-and verification on real hardware, creating the reference images/banks on those
-instruments (disk saves, SysEx probes), and aural A/B comparison of presets —
-which is what makes the results correct.
-Full account in [DISCLAIMER.md](DISCLAIMER.md).
-
----
-
----
-
-## ⚠️ Use at your own risk — back up first
-
- is provided **as is, with absolutely no warranty and no liability**
-for data loss or **hardware damage**. You assume all risk. Full terms:
-[DISCLAIMER.md](DISCLAIMER.md).
-
-Before you use this software, **make good, current backups of all your files** —
-and of any existing banks on your instrument and storage media. These tools can
-write to hardware and storage media; a mistake, a bug, or untested output could
-overwrite or corrupt data, or be rejected by hardware. Always test on a spare
-unit or emulator **before** connecting irreplaceable equipment.
-
----
-
 ## What is in here, and what is not
 
 **In here:** how a preference is remembered, where a favourite lives, what
@@ -153,7 +68,7 @@ selects which bank is that instrument's business and stays put.
 
 ```
 vinsynlib/
-  config.py        the settings cache: port, channel, device ID
+  config.py        the settings cache: port, channel, device ID, UI state
   favorites.py     the favourites database: SQLite, slots, ratings, tags
   keys.py          the keymap and the legend
   cli.py           the command line every tool builds the same way
@@ -162,52 +77,31 @@ vinsynlib/
   midi.py          port listing, the shared error taxonomy, clean exit
   conformance.py   the checks a project runs against itself
   devchecks.py     checks that catch cross-project mistakes
+  backup.py        the backup envelope: a versioned JSON container
+  catalog.py       printed names, plus what has been read off the unit
+  livenames.py     names read off the unit, kept between runs
+  render.py        table and progress rendering, without Textual
+  undo.py          the undo log: inspectable records, no threads or locks
   ui/hints.py      the legend widget
+  ui/browser.py    BrowserApp, the AppProtocol implementation
+  ui/protocol.py   the App contract screens depend on
+  ui/work.py       worker infrastructure: busy gate, error set, idle-close
+  ui/confirm.py    a generic yes/no confirmation modal
+  ui/prompt.py     a one-line modal text prompt
+  ui/modals.py     the shared modal screens: picker, search, report, rating
 ```
 
-## Installing it, and who depends on it
-
-This is a library, not a program, and it is **not on PyPI yet**. The ten tools
-in the family depend on it, so it has to be a sibling checkout of whichever
-one you are building:
-
-```
-git-repos/
-  vinsynlib/     <- this one
-  x5ded/         <- and the ten tools beside it
-  emorphed/  ensqsqed/  eosed/  kwsed/  ...
-```
-
-```sh
-cd ../x5ded                     # or any sibling
-git clone https://github.com/lentferj/vinsynlib.git ../vinsynlib
-python3 -m venv .venv
-.venv/bin/pip install --no-deps -e ../vinsynlib   # --no-deps: its deps are theirs
-.venv/bin/pip install -e .
-```
-
-Each of the ten writes those steps out in its own README, because a reader
-starts from the tool and rarely from here. For projects that configure
-`[tool.uv.sources]` pointing to this library, `uv sync` takes the path
-from there, so the checkout only has to exist and neither `pip` line is needed.
-For projects that work from an index (like the published tools), the explicit
-`pip install -e ../vinsynlib` line remains necessary until the library is
-published.
-
-Publishing this to PyPI would replace all of it with an ordinary dependency
-line. Until then, the sibling checkout *is* the install.
-
 ## Why it exists
 
 Nine projects each grew a `config.py` (about 190 lines, 90-97% identical),
 a `favorites.py` (about 620 lines, 85-100% identical), a `KeyHints` widget
-and a `wrap_blocks` helper. Measured across the family: **8,101 lines of
-cloned code, roughly 6,300 of them duplicates that need not exist.**
+and a `wrap_blocks` helper. Measured across the family: **roughly 6,300
+lines of that were duplicates that need not exist.**
 
 Three of those copies had already drifted into bugs worth naming:
 
 * `emorphed`'s `LICENSE` file opened with the words "nanosyned — Terminal
-  browser for the Alesis NanoSynth".
+  browser for the E-mu Morpheus".
 * `emorphed`'s `mypy` and `deptry` configuration still named the `nano`
   module, and one function imported `nano.config` -- `nanosyned`'s package,
   which is not installed beside it. That function worked in the project it
@@ -220,6 +114,68 @@ Three of those copies had already drifted into bugs worth naming:
 None of these were visible in review. They were visible the moment there
 was a second copy to compare against, which is what this library is.
 
+---
+
+## ⚠️ Use at your own risk — back up first
+
+vinsynlib is provided **as is, with absolutely no warranty and no liability**
+for data loss or **hardware damage**. You assume all risk. Full terms:
+[DISCLAIMER.md](DISCLAIMER.md).
+
+Before you use this software, **make good, current backups of all your files** —
+and of any existing banks on your instrument and storage media. These tools can
+write to hardware and storage media; a mistake, a bug, or untested output could
+overwrite or corrupt data, or be rejected by hardware. Always test on a spare
+unit or emulator **before** connecting irreplaceable equipment.
+
+## Installing it, and who depends on it
+
+This is a library, not a program. It is published on PyPI — the current
+release is 0.4.0 — so the ordinary way to depend on it is a dependency
+line:
+
+```toml
+vinsynlib>=0.4.0
+```
+
+```sh
+python3 -m pip install vinsynlib
+```
+
+The library itself has no dependencies. The parts that need a terminal UI
+or a MIDI backend are behind the `ui` and `midi` extras:
+
+```sh
+python3 -m pip install "vinsynlib[ui,midi]"
+```
+
+Ten projects in the family depend on it: the nine browsers above and
+[k2kremote](https://github.com/lentferj/k2kremote). Each of them writes its
+own install steps out in its README, because a reader starts from the tool
+and rarely from here.
+
+**Working on the library itself.** To develop against a checkout rather
+than the published release, put it beside the project that uses it and
+install it editable:
+
+```
+git-repos/
+  vinsynlib/     <- this one
+  x5ded/         <- a sibling, and the other tools beside it
+```
+
+```sh
+cd ../x5ded                     # or any sibling
+git clone https://github.com/lentferj/vinsynlib.git ../vinsynlib
+python3 -m venv .venv
+.venv/bin/pip install --no-deps -e ../vinsynlib   # --no-deps: its deps are theirs
+.venv/bin/pip install -e .
+```
+
+For projects that configure `[tool.uv.sources]` pointing to this library,
+`uv sync` takes the path from there, so the checkout only has to exist and
+neither `pip` line is needed.
+
 ## Using it
 
 ```python
@@ -245,20 +201,6 @@ parser = cli.make_parser("x5cli", "Browse a Korg X5D's sounds.")
 cli.add_common_arguments(parser, port=True, scan=True, channel=True)
 ```
 
-## Development
-
-```console
-$ uv venv && uv pip install -e ".[ui,midi]" && uv pip install \
-      pytest pytest-cov mypy ruff vulture deptry detect-secrets pip-audit
-$ make check
-```
-
-`make check` runs the whole gate in order and stops at the first failure:
-ruff, mypy in strict mode, the test suite with coverage, then vulture,
-deptry and pip-audit.
-
-> **Legal:** [DISCLAIMER.md](DISCLAIMER.md) · [LICENSE](LICENSE)
-
 ## Where the rules are written down
 
 **[docs/UX-SPEC.md](docs/UX-SPEC.md)** is the contract: terminology, the
@@ -282,3 +224,89 @@ mistranslation is the difference between finding a sound and not.
 first lives in the working directory and is safe to delete. The second
 lives in the platform data directory, is keyed on the slot rather than the
 name, and is the one file here worth backing up.
+
+## Development
+
+```console
+$ uv venv && uv pip install -e ".[ui,midi]" && uv pip install \
+      pytest pytest-cov mypy ruff vulture deptry detect-secrets pip-audit
+$ make check
+```
+
+`make check` runs the whole gate in order and stops at the first failure:
+ruff, mypy in strict mode, the test suite with coverage, then vulture,
+deptry and pip-audit.
+
+---
+
+## Support this project
+
+vinsynlib is free software and always will be. Nothing is behind a paywall,
+no feature is withheld, and none of what follows changes that.
+
+But if it has been useful — if it saved you an evening of mapping zones
+by hand, or got a library onto a machine that had no way of reading it, or
+**best of all, if it has your vintage instrument switched on and in use more often
+than it was, and you are having more fun with it** — then please consider
+supporting the work.
+
+**Because here is what it has actually cost:**
+
+- **Real machines on a real bench.** Much of what these tools know about these
+  formats was measured on hardware rather than read anywhere, because for most
+  of it there is nowhere to read it. That needs the machines — the instruments
+  themselves — and it puts hours of wear on hardware that has been locked up and
+  recovered more than once in the course of it. Some of these instruments were
+  bought specifically to add and verify a format; the others were already here,
+  because the person doing this is a vintage instrument enthusiast first and the
+  projects exist because the instruments were in the room.
+- **Dozens — realistically hundreds — of hours of human time.** Format
+  reverse-engineering is slow: measure, be wrong, measure again. A single
+  parameter law in one of the projects can represent an evening at the bench.
+- **AI assistance, which is a paid service**, used heavily throughout and not
+  cheap at this volume.
+
+**This is support, not a donation — and the distinction is a legal one, not a
+turn of phrase.** The maintainer is based in Germany, where payments like these
+are *not* `Spenden` in the tax sense: they count as **taxable income** for the
+recipient and are **not tax-deductible** for the giver. So this section is
+titled *Support*, deliberately, and no receipt for tax purposes can be issued.
+(That is a statement of how it is handled here, not tax advice.)
+
+If the project saved you the work, you can support it through
+**[GitHub Sponsors](https://github.com/sponsors/lentferj)** — the *Sponsor*
+button at the top of the repository. Payment is handled entirely by GitHub and
+Stripe, so bank and tax details are never handed to the person paying.
+
+**Support is not expected, and it is not the only currency.**
+
+- **Bug reports** — ideally with the bank, preset or disk image that produced
+  them. A tool's failures are usually specific to one file rather than
+  general, and without that file they are very hard to reproduce.
+- **Confirmations from hardware that is not on this bench**, which matters more
+  here than for a single-machine tool. These tools write for whole *families*
+  of instruments, and the bench holds only a subset. Whether a variant accepts
+  what we write is genuinely unknown, and several notes say "on this unit" for
+  that reason. A "loads fine here too", or a "no, mine refuses it", is worth a
+  great deal.
+- **Corrections to the reverse-engineering notes.** The wrong turns are
+  recorded next to the findings — in this repository's `TODO.md`, and in each
+  project's own `docs/RESOLUTION_NOTES.md` — retractions included, because a
+  finding that was withdrawn is as useful as one that stood. If any of it is
+  wrong in a way that is still costing someone time, saying so improves the
+  record.
+
+## AI assistance & human authorship
+
+vinsynlib was built by its human author together with AI assistance. The
+**ideas, the project vision, and every feature** came from the human author;
+AI assisted with **writing the code and analyzing the binary formats**.
+Crucially, the **reverse engineering rests on hands-on human work** — all testing
+and verification on real hardware, creating the reference images/banks on those
+instruments (disk saves, SysEx probes), and aural A/B comparison of presets —
+which is what makes the results correct.
+Full account in [DISCLAIMER.md](DISCLAIMER.md).
+
+---
+
+> **Legal:** [DISCLAIMER.md](DISCLAIMER.md) · [LICENSE](LICENSE)