midi_query.py
python
| 1 | """``muse midi-query`` — MIDI DSL query over commit history. |
| 2 | |
| 3 | Evaluates a predicate expression against the note content of all MIDI tracks |
| 4 | across the commit history and returns matching bars with chord annotations, |
| 5 | agent provenance, and note tables. |
| 6 | |
| 7 | Usage:: |
| 8 | |
| 9 | muse midi-query "note.pitch_class == 'Eb' and bar == 12" |
| 10 | muse midi-query "note.velocity > 100" --track piano.mid |
| 11 | muse midi-query "agent_id == 'counterpoint-bot'" --from HEAD~10 |
| 12 | muse midi-query "harmony.quality == 'dim'" --json |
| 13 | |
| 14 | Grammar:: |
| 15 | |
| 16 | query = or_expr |
| 17 | or_expr = and_expr ( 'or' and_expr )* |
| 18 | and_expr = not_expr ( 'and' not_expr )* |
| 19 | not_expr = 'not' not_expr | atom |
| 20 | atom = '(' query ')' | FIELD OP VALUE |
| 21 | FIELD = note.pitch | note.pitch_class | note.velocity | |
| 22 | note.channel | note.duration | bar | track | |
| 23 | harmony.chord | harmony.quality | |
| 24 | author | agent_id | model_id | toolchain_id |
| 25 | OP = == | != | > | < | >= | <= |
| 26 | |
| 27 | See ``muse/plugins/midi/_midi_query.py`` for the full grammar reference. |
| 28 | """ |
| 29 | |
| 30 | import json |
| 31 | import logging |
| 32 | import pathlib |
| 33 | import sys |
| 34 | |
| 35 | import typer |
| 36 | |
| 37 | from muse.core.repo import require_repo |
| 38 | from muse.core.store import get_head_commit_id, read_commit |
| 39 | from muse.plugins.midi._midi_query import run_query |
| 40 | |
| 41 | logger = logging.getLogger(__name__) |
| 42 | |
| 43 | app = typer.Typer(no_args_is_help=True) |
| 44 | |
| 45 | |
| 46 | def _read_branch(root: pathlib.Path) -> str: |
| 47 | head_ref = (root / ".muse" / "HEAD").read_text().strip() |
| 48 | return head_ref.removeprefix("refs/heads/").strip() |
| 49 | |
| 50 | |
| 51 | def _resolve_head(root: pathlib.Path, alias: str | None = None) -> str | None: |
| 52 | """Resolve ``None``, ``HEAD``, or ``HEAD~N`` to a concrete commit ID.""" |
| 53 | branch = _read_branch(root) |
| 54 | commit_id = get_head_commit_id(root, branch) |
| 55 | if commit_id is None: |
| 56 | return None |
| 57 | if alias is None or alias == "HEAD": |
| 58 | return commit_id |
| 59 | |
| 60 | # Handle HEAD~N. |
| 61 | parts = alias.split("~") |
| 62 | if len(parts) != 2: |
| 63 | return alias |
| 64 | try: |
| 65 | steps = int(parts[1]) |
| 66 | except ValueError: |
| 67 | return alias |
| 68 | |
| 69 | current: str | None = commit_id |
| 70 | for _ in range(steps): |
| 71 | if current is None: |
| 72 | break |
| 73 | commit = read_commit(root, current) |
| 74 | if commit is None: |
| 75 | break |
| 76 | current = commit.parent_commit_id |
| 77 | |
| 78 | return current or alias |
| 79 | |
| 80 | |
| 81 | @app.command(name="midi-query") |
| 82 | def midi_query_cmd( |
| 83 | query_expr: str = typer.Argument( |
| 84 | ..., |
| 85 | metavar="QUERY", |
| 86 | help=( |
| 87 | "Music query DSL expression. Examples: " |
| 88 | "\"note.pitch_class == 'Eb'\", " |
| 89 | "\"harmony.quality == 'dim' and bar == 8\", " |
| 90 | "\"agent_id == 'my-bot' and note.velocity > 80\"" |
| 91 | ), |
| 92 | ), |
| 93 | track: str | None = typer.Option( |
| 94 | None, |
| 95 | "--track", |
| 96 | "-t", |
| 97 | metavar="PATH", |
| 98 | help="Restrict search to a single MIDI file path.", |
| 99 | ), |
| 100 | start: str | None = typer.Option( |
| 101 | None, |
| 102 | "--from", |
| 103 | "-f", |
| 104 | metavar="COMMIT", |
| 105 | help="Start commit (default: HEAD).", |
| 106 | ), |
| 107 | stop: str | None = typer.Option( |
| 108 | None, |
| 109 | "--to", |
| 110 | metavar="COMMIT", |
| 111 | help="Stop before this commit (exclusive).", |
| 112 | ), |
| 113 | max_results: int = typer.Option( |
| 114 | 100, |
| 115 | "--max-results", |
| 116 | "-n", |
| 117 | metavar="N", |
| 118 | help="Maximum number of matches to return.", |
| 119 | ), |
| 120 | as_json: bool = typer.Option( |
| 121 | False, |
| 122 | "--json", |
| 123 | help="Output machine-readable JSON instead of formatted text.", |
| 124 | ), |
| 125 | ) -> None: |
| 126 | """Query the MIDI note history using a MIDI DSL predicate.""" |
| 127 | root = require_repo() |
| 128 | |
| 129 | start_id = _resolve_head(root, start) |
| 130 | if start_id is None: |
| 131 | typer.echo("❌ No commits in this repository.", err=True) |
| 132 | raise typer.Exit(1) |
| 133 | |
| 134 | try: |
| 135 | matches = run_query( |
| 136 | query_expr, |
| 137 | root, |
| 138 | start_id, |
| 139 | track_filter=track, |
| 140 | from_commit_id=stop, |
| 141 | max_results=max_results, |
| 142 | ) |
| 143 | except ValueError as exc: |
| 144 | typer.echo(f"❌ Query parse error: {exc}", err=True) |
| 145 | raise typer.Exit(1) |
| 146 | |
| 147 | if not matches: |
| 148 | typer.echo("No matches found.") |
| 149 | return |
| 150 | |
| 151 | if as_json: |
| 152 | sys.stdout.write(json.dumps(matches, indent=2) + "\n") |
| 153 | return |
| 154 | |
| 155 | for m in matches: |
| 156 | typer.echo( |
| 157 | f"commit {m['commit_short']} {m['committed_at'][:19]} " |
| 158 | f"author={m['author']} agent={m['agent_id'] or '—'}" |
| 159 | ) |
| 160 | typer.echo(f" track={m['track']} bar={m['bar']} chord={m['chord'] or '—'}") |
| 161 | for n in m["notes"]: |
| 162 | typer.echo( |
| 163 | f" {n['pitch_class']:3} (MIDI {n['pitch']:3}) " |
| 164 | f"vel={n['velocity']:3} ch={n['channel']} " |
| 165 | f"beat={n['beat']:.2f} dur={n['duration_beats']:.2f}" |
| 166 | ) |
| 167 | typer.echo("") |
| 168 | |
| 169 | typer.echo(f"— {len(matches)} match{'es' if len(matches) != 1 else ''} —") |