groovebin 0.1.0__tar.gz

groovebin-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] — 2026-09-14
+
+First release.
+
+### Added
+- `groovebin remap`: translate a MIDI file's drum notes and polyphonic aftertouch keys from one note map to
+  another, scoped by `--track` and `--channel`; notes with no counterpart are kept or dropped (`--unmapped`).
+- `groovebin notes`: a file's tracks and notes with bar positions and stroke names.
+- `groovebin index`: a sqlite pattern library from a folder of `.mid` files, labelled from their paths, or
+  from a `MidiDb.csv`.
+- `groovebin search` and `groovebin show`: filter patterns by label, role, meter, tempo, swing and intensity;
+  draw one as drum lanes or a piano roll.
+- `groovebin generate`: a drum phrase picked bar by bar from library bars, with fills and a repeatable seed.
+- Note maps `gm` (General MIDI Level 1 percussion), `addictive-drums-2` and `drum-kit-designer` (GM Standard
+  input mapping).
+- Library: Standard MIDI File read and write (format 0 and 1) through paired notes and every other event,
+  tempo and meter maps, note transforms (transpose, velocity, shift, delete, quantize, merge), map
+  translation, and section planning (`library.compose`).

groovebin-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

groovebin-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE NOTICE README.md CHANGELOG.md
+# The suite reads docs/ and the repo's own markdown, so it runs from a repository checkout.
+prune tests
+global-exclude __pycache__ *.py[cod]

groovebin-0.1.0/NOTICE

@@ -0,0 +1,10 @@
+groovebin
+Copyright 2026 Mike Farr
+
+Built on pf-core (https://github.com/phierceweb/pf-core), Copyright 2026 Mike Farr,
+licensed under the MIT License, and mido (https://github.com/mido/mido), licensed under
+the MIT License.
+
+Addictive Drums 2 is a trademark of XLN Audio; Logic Pro and Drum Kit Designer are
+trademarks of Apple Inc. groovebin is not affiliated with either and ships no sounds,
+patterns or MIDI content from them — only note-number tables.

groovebin-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: groovebin
+Version: 0.1.0
+Summary: MIDI files, note maps and a pattern library in Python: translate drum maps, transform notes, index and search grooves — no DAW or plug-in needed
+Author: Mike Farr
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/phierceweb/groovebin
+Project-URL: Changelog, https://github.com/phierceweb/groovebin/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/phierceweb/groovebin/issues
+Keywords: midi,drums,drum-map,general-midi,groove,smf
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: pf-core~=0.22.0
+Requires-Dist: mido~=1.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# groovebin
+
+MIDI files, note maps and a pattern library in Python. It reads and writes Standard MIDI Files,
+translates notes between instrument maps — General MIDI drums, Addictive Drums 2, Logic's Drum Kit
+Designer — and indexes a folder of MIDI patterns so they can be searched, shown and recombined.
+Nothing needs a DAW or a plug-in installed or running.
+
+Status: alpha. Commands, the library API and the index format may change before 1.0.
+
+## Install
+
+    pip install groovebin
+    groovebin --version
+
+Needs Python 3.12 or newer.
+
+## Commands
+
+    groovebin remap IN.mid --from drum-kit-designer --to addictive-drums-2 -o OUT.mid
+    groovebin notes IN.mid --map gm
+    groovebin index ~/Grooves --map addictive-drums-2
+    groovebin search --role verse --meter 4/4 --tempo 90-110
+    groovebin generate --meter 4/4 --bars 16 --fills --role verse -o verse.mid
+
+Usage: [docs/usage.md](https://github.com/phierceweb/groovebin/blob/main/docs/usage.md).
+Changes: [CHANGELOG.md](https://github.com/phierceweb/groovebin/blob/main/CHANGELOG.md).
+
+## Develop
+
+From a checkout:
+
+    bin/run setup
+    bin/run pytest
+    bin/run lint        # ruff + the pf-core structural gate (300 soft / 500 hard lines)
+
+See [CONTRIBUTING.md](https://github.com/phierceweb/groovebin/blob/main/CONTRIBUTING.md).
+
+groovebin ships note-number tables only: no sounds, patterns or MIDI content from any vendor.

groovebin-0.1.0/README.md

@@ -0,0 +1,38 @@
+# groovebin
+
+MIDI files, note maps and a pattern library in Python. It reads and writes Standard MIDI Files,
+translates notes between instrument maps — General MIDI drums, Addictive Drums 2, Logic's Drum Kit
+Designer — and indexes a folder of MIDI patterns so they can be searched, shown and recombined.
+Nothing needs a DAW or a plug-in installed or running.
+
+Status: alpha. Commands, the library API and the index format may change before 1.0.
+
+## Install
+
+    pip install groovebin
+    groovebin --version
+
+Needs Python 3.12 or newer.
+
+## Commands
+
+    groovebin remap IN.mid --from drum-kit-designer --to addictive-drums-2 -o OUT.mid
+    groovebin notes IN.mid --map gm
+    groovebin index ~/Grooves --map addictive-drums-2
+    groovebin search --role verse --meter 4/4 --tempo 90-110
+    groovebin generate --meter 4/4 --bars 16 --fills --role verse -o verse.mid
+
+Usage: [docs/usage.md](https://github.com/phierceweb/groovebin/blob/main/docs/usage.md).
+Changes: [CHANGELOG.md](https://github.com/phierceweb/groovebin/blob/main/CHANGELOG.md).
+
+## Develop
+
+From a checkout:
+
+    bin/run setup
+    bin/run pytest
+    bin/run lint        # ruff + the pf-core structural gate (300 soft / 500 hard lines)
+
+See [CONTRIBUTING.md](https://github.com/phierceweb/groovebin/blob/main/CONTRIBUTING.md).
+
+groovebin ships note-number tables only: no sounds, patterns or MIDI content from any vendor.

groovebin-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "groovebin"
+version = "0.1.0"
+description = "MIDI files, note maps and a pattern library in Python: translate drum maps, transform notes, index and search grooves — no DAW or plug-in needed"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+authors = [{ name = "Mike Farr" }]
+keywords = ["midi", "drums", "drum-map", "general-midi", "groove", "smf"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: MIDI",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pf-core~=0.22.0",
+    "mido~=1.3",
+]
+
+[project.urls]
+Repository = "https://github.com/phierceweb/groovebin"
+Changelog = "https://github.com/phierceweb/groovebin/blob/main/CHANGELOG.md"
+Issues = "https://github.com/phierceweb/groovebin/issues"
+
+[project.scripts]
+groovebin = "groovebin.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+groovebin = ["py.typed", "data/maps/*.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# every skip is listed: a skip that fires on a fresh clone proves nothing
+addopts = "-rs"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "B", "UP035"]
+ignore = ["E501", "B008", "B904"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["B011"]

groovebin-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

groovebin-0.1.0/src/groovebin/__init__.py

@@ -0,0 +1,10 @@
+"""MIDI files, note maps and a pattern library, with no DAW or plug-in involved."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("groovebin")
+except PackageNotFoundError:  # a source tree without an install
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

groovebin-0.1.0/src/groovebin/_parsers.py

@@ -0,0 +1,97 @@
+"""argparse construction for the `groovebin` command line."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from pf_core.utils.env import resolve_str
+
+from . import __version__
+from .maps import NAMES
+
+
+def default_db() -> Path:
+    """The pattern library index when --db is not given: under the user's cache folder."""
+    return Path(resolve_str(None, "XDG_CACHE_HOME", default="~/.cache")).expanduser() / "groovebin" / "library.sqlite"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="groovebin",
+                                 description="MIDI files, note maps and a pattern library, with no DAW or plug-in involved.")
+    ap.add_argument("--version", action="version", version=f"groovebin {__version__}")
+    sub = ap.add_subparsers(dest="command")
+
+    remap = sub.add_parser("remap", help="translate a MIDI file's notes from one note map to another")
+    remap.add_argument("input", help="the .mid file to read")
+    remap.add_argument("--from", dest="src", required=True, choices=NAMES, help="the map the notes follow now")
+    remap.add_argument("--to", dest="dst", required=True, choices=NAMES, help="the map to translate them to")
+    remap.add_argument("-o", "--out", required=True, help="the .mid file to write")
+    remap.add_argument("--channel", type=int, action="append",
+                       help="remap only notes on this channel, 1-16 (repeatable)")
+    remap.add_argument("--track", type=int, action="append", help="remap only this track, from 1 (repeatable)")
+    remap.add_argument("--unmapped", choices=("keep", "drop"), default="keep",
+                       help="a note with no counterpart keeps its pitch (default) or is dropped")
+    remap.add_argument("--force", action="store_true", help="overwrite an existing --out file")
+
+    notes = sub.add_parser("notes", help="list a MIDI file's tracks and notes")
+    notes.add_argument("input", help="the .mid file to read")
+    notes.add_argument("--map", choices=NAMES, help="name each note's stroke from this map")
+    notes.add_argument("--track", type=int, action="append", help="list only this track, from 1 (repeatable)")
+
+    _library(sub)
+    return ap
+
+
+def _db(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--db", type=Path, help=f"the library index file (default {default_db()})")
+
+
+def _library(sub) -> None:
+    ix = sub.add_parser("index", help="build the pattern library index from a folder of .mid files or a MidiDb.csv")
+    ix.add_argument("folder", nargs="?", type=Path, help="a folder of .mid files, labelled from their paths")
+    ix.add_argument("--csv", type=Path, help="a MidiDb.csv instead of a folder: its columns label each pattern")
+    ix.add_argument("--map", choices=NAMES, help="the drum map the patterns follow (leave out for a library that is not drums)")
+    _db(ix)
+
+    se = sub.add_parser("search", help="patterns matching every filter given")
+    se.add_argument("--category", help="whole value, any case")
+    se.add_argument("--role", help="intro, verse, pre-chorus, chorus, bridge or outro")
+    se.add_argument("--meter", metavar="N/D", help="e.g. 4/4")
+    se.add_argument("--tempo", metavar="RANGE",
+                    help="100-130, <90, >=140 or 98, each bound to the digits written (98 is 97.5 up to 98.5)")
+    kind = se.add_mutually_exclusive_group()
+    kind.add_argument("--fill", action="store_true", help="fills only")
+    kind.add_argument("--beat", action="store_true", help="beats only")
+    se.add_argument("--swing", metavar="RANGE", help="0-1, as --tempo")
+    se.add_argument("--intensity", metavar="RANGE", help="0-1, as --tempo")
+    se.add_argument("--group", metavar="TEXT", help="a substring of the group")
+    se.add_argument("--variant", metavar="TEXT", help="a substring of the variant")
+    se.add_argument("--library", metavar="NAME", help="whole value, any case")
+    se.add_argument("--limit", type=int, default=50, metavar="N", help="at most N rows (default 50; 0 for all)")
+    se.add_argument("--json", action="store_true", help="the rows as JSON")
+    _db(se)
+
+    ge = sub.add_parser("generate", help="a drum phrase picked bar by bar from real library bars, as a MIDI file",
+                        description="Every bar is a real bar of a matching pattern: the first starts a pattern; each "
+                                    "next has the kick and snare onsets nearest those of the bar that followed the last "
+                                    "pick in its own pattern. Timing moves up to 5 ticks and velocity up to 6.")
+    ge.add_argument("--meter", required=True, metavar="N/D", help="e.g. 4/4; patterns with any bar in another meter are left out")
+    ge.add_argument("--bars", required=True, type=int, metavar="N", help="the phrase's length in bars")
+    ge.add_argument("-o", "--out", required=True, help="the .mid file to write")
+    ge.add_argument("--category", help="whole value, any case")
+    ge.add_argument("--role", help="intro, verse, pre-chorus, chorus, bridge or outro")
+    ge.add_argument("--tempo", metavar="RANGE", help="as `groovebin search` takes it")
+    ge.add_argument("--intensity", metavar="RANGE", help="as `groovebin search` takes it")
+    ge.add_argument("--fills", action="store_true", help="every fourth bar from a fill pattern")
+    ge.add_argument("--seed", type=int, metavar="N", help="0 or more; the same seed and index give the same phrase (default: a new one, printed)")
+    ge.add_argument("--map", choices=NAMES, help="write the notes in this drum map (default: the patterns' own)")
+    ge.add_argument("--unmapped", choices=("keep", "drop"), default="keep",
+                    help="with --map, a note with no counterpart keeps its pitch (default) or is dropped")
+    ge.add_argument("--force", action="store_true", help="overwrite an existing --out file")
+    _db(ge)
+
+    sh = sub.add_parser("show", help="one pattern as text: drum lanes, or a piano roll when it has no drum map")
+    sh.add_argument("id", help="the id search prints, or a unique prefix of it")
+    sh.add_argument("--map", choices=NAMES, help="name each lane's stroke from this map instead of the pattern's own")
+    _db(sh)

groovebin-0.1.0/src/groovebin/_views.py

@@ -0,0 +1,46 @@
+"""Terminal output for the `groovebin` commands."""
+
+from __future__ import annotations
+
+from collections import Counter
+
+from .maps import stroke
+from .song import Song, meter_map, tempo_map
+
+
+def joined(items: list[object]) -> str:
+    words = [str(i) for i in items]
+    return words[0] if len(words) == 1 else f"{', '.join(words[:-1])} and {words[-1]}"
+
+
+def remap_report(*, notes: int, unmapped: Counter, src: str, dst: str, nested: int, orphans: int,
+                 rule: str = "keep") -> list[str]:
+    line = f"{notes - sum(unmapped.values())} of {notes} note(s) remapped {src} -> {dst}"
+    if unmapped:
+        kept = ", ".join(f"{pitch} x{count}" for pitch, count in sorted(unmapped.items()))
+        line += f"; no {dst} counterpart, {'pitch kept' if rule == 'keep' else 'dropped'}: {kept}"
+    lines = [line]
+    if nested:
+        lines.append(f"{nested} same-pitch note(s) now start inside a longer one and end before it: "
+                     "a reader pairs note-offs first in, first out, so those lengths read back swapped")
+    if orphans:
+        lines.append(f"{orphans} note-off(s) with no note before them were dropped")
+    return lines
+
+
+def listing(name: str, song: Song, tracks: list[int], map_name: str | None) -> list[str]:
+    meters = meter_map(song)
+    num, den = meters.meter_at(0)
+    lines = [f"{name}: format {song.format}, PPQ {song.ppq}, {len(song.tracks)} track(s), "
+             f"{tempo_map(song).bpm(0):g} bpm, {num}/{den}"]
+    for i in tracks:
+        part = song.tracks[i]
+        label = f" {part.name!r}" if part.name else ""
+        lines.append(f"track {i + 1}{label}: {len(part.notes)} note(s), {len(part.events)} other event(s)")
+        for n in part.notes:
+            line = (f"  bar {meters.bar(n.tick):8.3f}  ch {n.channel:2d}  note {n.pitch:3d}  "
+                    f"vel {n.velocity:3d}  len {n.length:6d}")
+            if map_name:
+                line += f"  {stroke(map_name, n.pitch) or '-'}"
+            lines.append(line)
+    return lines

groovebin-0.1.0/src/groovebin/_views_library.py

@@ -0,0 +1,40 @@
+"""Terminal output for the pattern library commands."""
+
+from __future__ import annotations
+
+
+def _cell(value: object, width: int) -> str:
+    text = "" if value is None else f"{value:g}" if isinstance(value, float) else str(value)
+    return text[:width].ljust(width)
+
+
+def indexed(counts: dict) -> str:
+    return (f"  {counts['parsed']} pattern(s) indexed, {counts['failed']} not parsed, "
+            f"{counts['duplicates']} duplicate(s) skipped")
+
+
+def found(rows: list[dict], limit: int | None) -> list[str]:
+    lines = [f"{len(rows)} pattern(s){' (limit reached)' if limit and len(rows) == limit else ''}"]
+    for r in rows:
+        kind = "fill" if r["is_fill"] else "beat" if r["is_beat"] else ""
+        tempo = f"{r['tempo']:6.1f}" if r["tempo"] is not None else "     -"
+        lines.append(f"  {r['id']}  {_cell(r['meter'], 5)} {tempo}  {kind:4s}  {_cell(r['bars'], 3)} "
+                     f"{_cell(r['role'], 10)} {_cell(r['category'], 16)} {_cell(r['group_name'], 24)} "
+                     f"{_cell(r['variant'] or r['file'], 28)}")
+    return lines
+
+
+def picked(pool, ph) -> list[str]:
+    fills = f", {len(pool.fills)} fill bar(s)" if pool.fills else ""
+    left = f"; {pool.left_out} pattern(s) with a bar in another meter left out" if pool.left_out else ""
+    lines = [f"pool: {len(pool.bars)} beat bar(s) from {len(pool.patterns)} pattern(s){fills}{left}",
+             f"seed {ph.seed}: {len(ph.picks)} bar(s) of {ph.sig[0]}/{ph.sig[1]}, {len(ph.notes)} note(s) in {ph.map}"]
+    for k, p in enumerate(ph.picks, 1):
+        line = f"  bar {k:<3d} {'fill' if p.fill else 'beat'} {p.bar.id} bar {p.bar.index + 1} of {p.bar.count}"
+        if p.fill:
+            line += f", replaces {p.replaces.id} bar {p.replaces.index + 1}, {p.distance} onset step(s) from it"
+        lines.append(line)
+    if ph.unmapped:
+        kept = ", ".join(f"{pitch} x{n}" for pitch, n in ph.unmapped.items())
+        lines.append(f"  no {ph.map} counterpart, {'pitch kept' if ph.unmapped_rule == 'keep' else 'dropped'}: {kept}")
+    return lines