musicxml-to-png 0.5.0

Convert MusicXML files into clean, analyzable PNG visualizations

musicxml-to-png

Visualize and analyze MusicXML scores for humans, classrooms, and AI collaborations/workflows

MusicXML is rich and expressive for human-facing notation software, but challenging to scan at a glance or share with AI systems. This tool converts MusicXML into clear visual timelines and pitch maps for score study, arrangement review, education, and pipeline integration—while still making it easy for humans and AI to explore music side by side.

Quick Start

Requirements: Python 3.12 or higher

# Install from PyPI
pip install musicxml-to-png

# Convert a MusicXML file
musicxml-to-png your-score.mxl

# With options
musicxml-to-png your-score.mxl --ensemble bigband --minimal -o output.png

See Installation for development setup.

Features

Convert MusicXML files into clean, analyzable PNG visualizations showing temporal flow (horizontal axis = time), pitch range (vertical axis = low to high), note duration (length of visual bars), and instrument identities (color-coded per instrument by default or by ensemble family when requested).

Use cases: Human-AI collaboration on musical analysis, visual comparison of arrangements, AI pipeline integration for score processing, and educational visualization of orchestration principles.

• Parse MusicXML files (.xml, .musicxml, .mxl)
• Extract note events (pitch, duration, start time, instrument)
• High-resolution 2D visualization (time × pitch) with grid/labels toggles
• Multiple ensemble types:
  • Ungrouped (default): every part gets its own color, even if multiple of the same instrument appear
  • Orchestra: strings, winds, brass, percussion
  • Bigband: trumpets, trombones, saxophones, rhythm section
  • (More ensemble types coming - jazzcombo, chamber, etc.)
• Color-coded instruments or families (per-instrument by default, ensemble palettes when requested)
• Customizable visualization:
  • Grid lines (enabled by default, disable with --no-grid)
  • Minimal mode (remove all labels, legend, title, borders, --minimal)
  • Custom titles (-t "Custom Title")
  • Width controls: --time-stretch or --fig-width
  • Staccato shortening (default 40%); override with --staccato-factor (0.1–0.9)
  • Timeline slicing by bars/measures or beats using --slice-range start-end (unit from --timeline-unit, default bar/measure)
    • Slice ranges are 1-based and end-exclusive (e.g., 2-4 yields bars 2–3; 2-3 beats yields only beat 2)
  • Timeline units for x-axis: bars/measures (default) or beats (--timeline-unit measure or --timeline-unit beat), labels are 1-indexed
  • Output DPI control: --dpi (default 150)
  • No-output mode for smoke tests: --no-output
  • Verbose mode for debugging (-v/--verbose)
  • Same-pitch stacking is split by default so only overlapping segments thicken; opt out with --no-overlap-splitting for the legacy whole-note look
• Export as high-resolution PNG with user-settable DPI, defaulting to 150 (--dpi 72)

Getting Your Music into MusicXML

Most modern notation software can export to MusicXML format. Here are some popular options:

Desktop Software:

• Dorico - File → Export → MusicXML (or use compressed .mxl format)
• Finale - File → Export → MusicXML
• LilyPond - Can export via lilypond --formats=xml
• MuseScore (Free, open source) - File → Export → MusicXML
• Notion - File → Export → MusicXML
• Overture - File → Export → MusicXML
• Sibelius - File → Export → MusicXML

Web-Based:

• Flat.io - File → Export → MusicXML
• Noteflight - File → Export → MusicXML

For detailed export instructions, please refer to your notation software's documentation. Most software supports both uncompressed .mxl and compressed .xml formats - this tool handles both!

Installation

For End Users

Simply install from PyPI:

pip install musicxml-to-png

Note: Requires Python 3.12 or higher. If you don't have Python 3.12, pip will show an error with installation instructions.

For Developers

If you want to contribute or develop locally:

1. Python Version: This project requires Python 3.12. The .python-version file will automatically set this if you use pyenv, asdf, or similar version managers.

   Using pyenv:

   pyenv install 3.12  # If not already installed
   python --version    # Verify it shows Python 3.12.x
   

2. Clone the repository:

   git clone <repository-url>
   cd musicxml-to-png
   

3. Set up Python environment:

   # Create and activate virtual environment
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   
   # Install dependencies
   pip install -r requirements.txt
   
   # Install package in development mode
   pip install -e .
   

Note: Activate the virtual environment (source venv/bin/activate) each time you work on the project. You'll see (venv) in your prompt when active.

Usage

Command Line Interface

Convert a MusicXML file to PNG:

musicxml-to-png input.xml

This creates input.png in the same directory. Supports both .xml and .mxl (compressed) MusicXML files.

Basic Options:

# Specify custom output file
musicxml-to-png input.xml -o output.png

# Add custom title
musicxml-to-png input.xml --title "My Composition"

# Disable grid lines
musicxml-to-png input.xml --no-grid

# Minimal mode (no labels, legend, title, or borders)
musicxml-to-png input.xml --minimal

# Show music21 warnings and diagnostics
musicxml-to-png input.xml --verbose
# or
musicxml-to-png input.xml -v

Ensemble Types:

Select the instrument categorization scheme:

# Ungrouped (default) - every instrument gets its own color
musicxml-to-png input.xml

# Group by orchestra families
musicxml-to-png input.xml --ensemble orchestra

# Group by bigband families
musicxml-to-png input.xml --ensemble bigband

Combining Options:

musicxml-to-png input.xml --ensemble bigband --minimal --no-grid -o output.png

Python Library

Use as a library in your Python code:

from musicxml_to_png import convert_musicxml_to_png
from pathlib import Path

# Basic conversion
output_path = convert_musicxml_to_png(
    input_path=Path("input.xml"),
    output_path=Path("output.png"),  # Optional
    title="My Composition"  # Optional
)

# With all options
output_path = convert_musicxml_to_png(
    input_path=Path("input.xml"),
    output_path=Path("output.png"),
    title="My Composition",
    show_grid=False,           # Disable grid lines
    minimal=True,              # Remove all labels/borders
    ensemble="bigband"         # Use bigband categorization
)

Contributing

See Roadmap for planned features.

This project emerged from human-AI collaborative exploration of musical structure. Contributions, ideas, and feedback are welcome!

Philosophy: This tool exists to enable human-AI collaboration, not to replace human musical intuition. The goal is to create shared visual language that helps both humans and AI systems understand musical architecture more deeply.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built through collaborative iteration between human musical expertise and AI technical assistance. Created to bridge the gap between MusicXML (machine-readable but visually dense) and visual analysis (human-friendly and AI-parseable).

Special thanks to: The music21 project for their excellent MusicXML parsing library.