Melodic Skeletal Diagram Generator

A Python command-line tool that analyzes MIDI files and generates skeletal diagrams based on Minao Shibata's skeletal figure theory. The system performs melodic analysis using fourth-interval relationships and generates visual diagrams showing core notes and ornamental notes.

Features

• MIDI Input Processing: Reads MIDI files and extracts primary melodic lines
• Key Detection: Automatic key signature detection with manual override option
• Relative Pitch Conversion: Converts MIDI notes to solfege notation (Do, Re, Mi, etc.)
• Skeletal Analysis: Identifies fourth-interval core note pairs following Shibata's theory
• Ornamental Classification: Classifies decorative notes based on interval distance from core notes
• Visual Diagrams: Generates high-quality skeletal diagrams with precise positioning
• Multiple Segmentation: Supports measure, phrase, section, and automatic segmentation modes

Installation

1. Clone this repository:

git clone <repository-url>
cd skeletal_diagram

2. Install dependencies:

pip install -r requirements.txt

3. Install the package:

pip install -e .

Usage

Basic Analysis

skeletal-gen analyze input.mid

This will create diagrams in the ./diagrams/ directory by default.

Advanced Options

# Specify custom output directory and segmentation mode
skeletal-gen analyze input.mid --output ./my_analysis --unit phrase

# Manual key specification
skeletal-gen analyze input.mid --key "C major"

# Generate overview grid
skeletal-gen analyze input.mid --overview

# Verbose output for debugging
skeletal-gen analyze input.mid --verbose

Output Directory Structure

By default, generated diagrams are saved to ./diagrams/ to keep your workspace organized. You can specify a different directory using the --output option.

MIDI File Information

skeletal-gen info input.mid

Core Concepts

Shibata's Skeletal Theory

The analysis is based on Minao Shibata's skeletal figure theory, which identifies structurally important notes (core notes) typically in fourth-interval relationships, with other notes classified as ornamental based on their interval distance from core notes.

Ornamental Note Positioning

• Semitone intervals: Positioned inside core note circles
• Whole tone intervals: Positioned on circle boundaries
• Larger intervals: Positioned outside circles

Analysis Units

• Measure: Fixed 1-2 measure segments
• Phrase: Natural phrase boundaries detected by rests
• Section: Larger 8-measure structural units
• Auto: Intelligent selection based on melody length

Output Files

The tool generates:

• Individual skeletal diagrams for each analysis unit (PNG format)
• Optional overview grid showing all units together
• Analysis summary with confidence scores and statistics

Example Output

Generated diagrams show:

• Core notes as labeled circles connected by lines
• Ornamental notes positioned by interval distance
• Analysis metadata (confidence scores, unit information)
• Clear solfege notation labels

Requirements

• Python 3.8+
• music21 (MIDI processing)
• matplotlib (diagram generation)
• numpy (numerical computations)
• click (CLI framework)

Project Structure

src/skeletal_gen/
├── cli.py                    # Command-line interface
├── input/                    # MIDI processing modules
├── analysis/                 # Core detection & classification
├── visualization/            # Diagram generation
└── models/                   # Data classes

Testing

Test with the provided sample MIDI files:

python create_test_midi.py  # Generate test files
skeletal-gen analyze tests/fixtures/test_melody.mid --overview

License

MIT License