How julian-b-smith/tonality works
Tonality is a local-first, deterministic music-theory engine for software and AI callers. The principal workflow is to submit musical material through Python or the MCP tool surface, derive ranked, evidence-bearing analysis, and return structured results. MIDI and temporal analysis extend that workflow with key, meter, rhythm, and modulation stages; separate branches cover rulesets and style modeling, generation, search, and render-agnostic representations. Edges follow the excerpts, SOURCE INDEX references, or README claims; unsampled internals are represented at subsystem level, and their unverified connections are omitted.
Main entry points: tools.py MCP tools · sequence.py Musical sequence · bitmask.py Pitch and set primitives · midi.py MIDI ingestion
Components 24
Theory primitives
- Pitch and set primitives
mts/core/bitmask.py - Pitch model
mts/core/pitch.py - Registered realization
mts/core/realization.py - Scale model
mts/core/scale.py - Derived functions
mts/theory/functions.py
Harmonic analysis
- Naming and context
mts/analysis/naming.py - Key induction
mts/analysis/key_induction.py - Ranked results
mts/analysis/results.py
Temporal analysis
- Musical sequence
mts/temporal/sequence.py - Key tracking
mts/temporal/key_tracking.py - Chromatic events
mts/temporal/chromatic.py
Rules and style
- Rules and evaluation
mts/rules/schema.py - Rule induction
mts/rules/induction.py - Style transitions
mts/rules/transition.py
Access and outputs
- MCP tools
mts/mcp/tools.py - MCP server
mts/mcp/server.py - Data loaders
mts/io/loaders.py - MIDI ingestion
mts/io/midi.py - Analysis pipelines
mts/dataset/pipelines.py - Dataset builders
mts/dataset/builders.py - Visual descriptions
mts/representation/keyboard.py - Music generation
mts/generate/modal.py - Voicing search
mts/search/voicings.py
Other components
- Music software / agent
Connections 28
- Music software / agent → MCP tools: queries tools
README.md - MCP server → MCP tools: registers tools
mts/mcp/server.py - MCP tools → Naming and context: calls analysis
mts/mcp/tools.py - MCP tools → Key induction: calls analysis
mts/mcp/tools.py - MCP tools → Voicing search: calls search
mts/mcp/tools.py - MCP tools → Visual descriptions: calls views
mts/mcp/tools.py - MCP tools → Rules and evaluation: calls rules
mts/mcp/tools.py - MCP tools → Music generation: calls transforms
mts/mcp/tools.py - MCP tools → Analysis pipelines: calls pipelines
mts/dataset/pipelines.py - Pitch model → Pitch and set primitives: uses pitch classes
mts/core/pitch.py - Scale model → Pitch and set primitives: builds masks
mts/core/scale.py - Registered realization → Pitch and set primitives: reduces to mask
mts/core/realization.py - Derived functions → Pitch and set primitives: derives from masks
mts/theory/functions.py - Data loaders → Key induction: loads priors
mts/analysis/key_induction.py - MIDI ingestion → Pitch model: creates pitches
mts/io/midi.py - MIDI ingestion → Musical sequence: creates sequences
mts/io/midi.py - Musical sequence → Registered realization: reads sounding pitches
mts/temporal/sequence.py - Musical sequence → Key tracking: tracks key regions
mts/temporal/key_tracking.py - Chromatic events → Naming and context: names chords
mts/temporal/chromatic.py - Chromatic events → Musical sequence: segments sequence
mts/temporal/chromatic.py - Key induction → Ranked results: returns candidates
mts/analysis/key_induction.py - Analysis pipelines → Dataset builders: builds dataset
mts/dataset/pipelines.py - Rule induction → Rules and evaluation: evaluates rules
mts/rules/induction.py - Music software / agent → MIDI ingestion: supplies MIDI
README.md - Music software / agent → Rules and evaluation: defines constraints
README.md - Music software / agent → Style transitions: uses style model
README.md - Music software / agent → Visual descriptions: consumes descriptors
README.md - Music software / agent → Music generation: requests generation
README.md