Music Query DSL

Overview

The music query DSL allows agents and humans to search the Muse commit history for specific musical content without parsing MIDI bytes for every commit.

muse midi query "note.pitch_class == 'Eb' and bar == 12"
muse midi query "harmony.quality == 'dim' and bar == 8"
muse midi query "agent_id == 'counterpoint-bot'"
muse midi query "note.velocity > 80 and track == 'cello.mid'"

Grammar (EBNF)

query      = or_expr
or_expr    = and_expr ( 'or' and_expr )*
and_expr   = not_expr ( 'and' not_expr )*
not_expr   = 'not' not_expr | atom
atom       = '(' query ')' | comparison
comparison = FIELD OP VALUE
FIELD      = <see field table below>
OP         = '==' | '!=' | '>' | '<' | '>=' | '<='
VALUE      = QUOTED_STRING | INTEGER | FLOAT

Supported fields

Note fields match if any note in the bar satisfies the predicate — i.e. note.pitch > 60 is true for a bar if it contains at least one note with MIDI pitch > 60.

Examples

# All bars where Eb appears.
muse midi query "note.pitch_class == 'Eb'"

# Diminished chord in bar 8 specifically.
muse midi query "harmony.quality == 'dim' and bar == 8"

# High-velocity notes in the cello part authored by an agent.
muse midi query "note.velocity > 100 and track == 'cello.mid' and agent_id == 'melody-agent'"

# Notes outside a comfortable bass range.
muse midi query "note.pitch < 36 or note.pitch > 96" --track bass.mid

# Everything from a particular AI model.
muse midi query "model_id == 'claude-4'"

Architecture

The DSL is implemented in three layers in muse/plugins/midi/_music_query.py:

1. Tokenizer (_tokenize) — regex-based lexer producing Token objects.
2. Recursive descent parser (_Parser) — produces an AST of EqNode, AndNode, OrNode, NotNode.
3. Evaluator (evaluate_node) — walks the AST against a QueryContext that provides the bar's notes, chord, and commit provenance.

The top-level run_query() function walks the commit DAG from HEAD, loading each MIDI track from the object store, grouping notes by bar, and evaluating the predicate.

CLI flags

muse midi query QUERY
  --track  PATH     Restrict to one MIDI file
  --from   COMMIT   Start commit (default: HEAD)
  --to     COMMIT   Stop before this commit
  -n       N        Max results (default: 100)
  --json            Machine-readable JSON output

Related files