tessl/pypi-mingus

Python music theory and MIDI processing library for programmers, musicians, composers, and researchers.

—

Pending

Overview

Eval results

Files

Music Theory Core

Name: tessl/pypi-mingus
Author: tessl

Essential music theory functions for working with notes, intervals, chords, scales, keys, progressions, and rhythmic values. These modules provide the theoretical foundation for all musical operations in mingus.

Capabilities

Note Operations

Basic note operations for converting between different note representations, validating note names, and performing note transformations.

def int_to_note(note_int: int, accidentals: str = "#") -> str:
    """
    Convert integers (0-11) to note names.
    
    Parameters:
    - note_int: Integer from 0-11 representing chromatic pitch class
    - accidentals: Use "#" for sharps or "b" for flats
    
    Returns:
    Note name as string (e.g., "C", "F#", "Bb")
    """

def note_to_int(note: str) -> int:
    """
    Convert note names to integers (0-11).
    
    Parameters:
    - note: Note name (e.g., "C", "F#", "Bb")
    
    Returns:
    Integer from 0-11 representing chromatic pitch class
    """

def is_valid_note(note: str) -> bool:
    """
    Return True if note is in recognized format.
    
    Parameters:
    - note: Note name to validate
    
    Returns:
    True if note is valid, False otherwise
    """

def augment(note: str) -> str:
    """
    Augment a note (add sharp or remove flat).
    
    Parameters:
    - note: Note name to augment
    
    Returns:
    Augmented note name
    """

def diminish(note: str) -> str:
    """
    Diminish a note (add flat or remove sharp).
    
    Parameters:
    - note: Note name to diminish
    
    Returns:
    Diminished note name
    """

def is_enharmonic(note1: str, note2: str) -> bool:
    """
    Test if two notes are enharmonically equivalent.
    
    Parameters:
    - note1, note2: Note names to compare
    
    Returns:
    True if notes are enharmonically equivalent
    """

def reduce_accidentals(note: str) -> str:
    """
    Reduce extra accidentals to proper notes.
    
    Parameters:
    - note: Note with possible redundant accidentals
    
    Returns:
    Note with reduced accidentals
    """

def remove_redundant_accidentals(note: str) -> str:
    """
    Remove redundant sharps/flats from note.
    
    Parameters:
    - note: Note name to clean
    
    Returns:
    Note name with redundant accidentals removed
    """

# Constants
fifths: List[str] = ["F", "C", "G", "D", "A", "E", "B"]
"""Circle of fifths progression."""

Key Signatures and Keys

Functions for working with musical keys, key signatures, and key relationships.

def is_valid_key(key: str) -> bool:
    """
    Return True if key is recognized.
    
    Parameters:
    - key: Key name (e.g., "C", "Am", "F#", "Bbm")
    
    Returns:
    True if key is valid
    """

def get_key_signature(key: str = "C") -> int:
    """
    Return key signature as integer (number of sharps/flats).
    
    Parameters:
    - key: Key name
    
    Returns:
    Integer representing key signature (positive for sharps, negative for flats)
    """

def get_notes(key: str = "C") -> List[str]:
    """
    Return ordered list of notes in key.
    
    Parameters:
    - key: Key name
    
    Returns:
    List of note names in the key
    """

def relative_major(key: str) -> str:
    """
    Return relative major of minor key.
    
    Parameters:
    - key: Minor key name
    
    Returns:
    Relative major key name
    """

def relative_minor(key: str) -> str:
    """
    Return relative minor of major key.
    
    Parameters:
    - key: Major key name
    
    Returns:
    Relative minor key name
    """

class Key:
    """Key object with properties for key analysis."""
    
    def __init__(self, key: str = "C"):
        """
        Create Key object.
        
        Parameters:
        - key: Key name (e.g., "C", "Am", "F#")
        """
    
    @property
    def key(self) -> str:
        """Key name."""
    
    @property
    def mode(self) -> str:
        """Mode (major or minor)."""
    
    @property
    def signature(self) -> int:
        """Key signature as integer."""

Interval Analysis

Functions for creating and analyzing musical intervals between notes.

def measure(note1: str, note2: str) -> int:
    """
    Return half steps between notes.
    
    Parameters:
    - note1, note2: Note names
    
    Returns:
    Number of half steps between notes
    """

def determine(note1: str, note2: str, shorthand: bool = False) -> str:
    """
    Name interval between notes.
    
    Parameters:
    - note1, note2: Note names
    - shorthand: Return shorthand notation if True
    
    Returns:
    Interval name (e.g., "major third", "perfect fifth")
    """

def from_shorthand(note: str, interval: str, up: bool = True) -> str:
    """
    Return note at shorthand interval.
    
    Parameters:
    - note: Starting note
    - interval: Interval shorthand (e.g., "3", "5", "b7", "M7")
    - up: Direction (True for up, False for down)
    
    Returns:
    Resulting note name
    """

def invert(interval: str) -> str:
    """
    Invert interval.
    
    Parameters:
    - interval: Interval name
    
    Returns:
    Inverted interval name
    """

# Chromatic interval functions
def minor_second(note: str) -> str:
    """Return minor second above note."""

def major_second(note: str) -> str:
    """Return major second above note."""

def minor_third(note: str) -> str:
    """Return minor third above note."""

def major_third(note: str) -> str:
    """Return major third above note."""

def perfect_fourth(note: str) -> str:
    """Return perfect fourth above note."""

def perfect_fifth(note: str) -> str:
    """Return perfect fifth above note."""

def minor_sixth(note: str) -> str:
    """Return minor sixth above note."""

def major_sixth(note: str) -> str:
    """Return major sixth above note."""

def minor_seventh(note: str) -> str:
    """Return minor seventh above note."""

def major_seventh(note: str) -> str:
    """Return major seventh above note."""

def is_consonant(note1: str, note2: str, include_fourths: bool = True) -> bool:
    """
    Test consonance between two notes.
    
    Parameters:
    - note1, note2: Note names
    - include_fourths: Include perfect fourths as consonant
    
    Returns:
    True if interval is consonant
    """

def is_dissonant(note1: str, note2: str, include_fourths: bool = False) -> bool:
    """
    Test dissonance between two notes.
    
    Parameters:
    - note1, note2: Note names  
    - include_fourths: Include perfect fourths as dissonant
    
    Returns:
    True if interval is dissonant
    """

Chord Construction and Analysis

Comprehensive chord construction including triads, seventh chords, extended chords, and chord analysis functions.

# Triad construction
def major_triad(note: str) -> List[str]:
    """
    Return major triad.
    
    Parameters:
    - note: Root note
    
    Returns:
    List of notes in major triad
    """

def minor_triad(note: str) -> List[str]:
    """Return minor triad."""

def diminished_triad(note: str) -> List[str]:
    """Return diminished triad."""

def augmented_triad(note: str) -> List[str]:
    """Return augmented triad."""

def suspended_fourth_triad(note: str) -> List[str]:
    """Return sus4 triad."""

def suspended_second_triad(note: str) -> List[str]:
    """Return sus2 triad."""

# Seventh chord construction  
def major_seventh(note: str) -> List[str]:
    """Return major seventh chord."""

def minor_seventh(note: str) -> List[str]:
    """Return minor seventh chord."""

def dominant_seventh(note: str) -> List[str]:
    """Return dominant seventh chord."""

def half_diminished_seventh(note: str) -> List[str]:
    """Return half-diminished seventh chord."""

def diminished_seventh(note: str) -> List[str]:
    """Return diminished seventh chord."""

def minor_major_seventh(note: str) -> List[str]:
    """Return minor-major seventh chord."""

# Extended chords
def major_sixth(note: str) -> List[str]:
    """Return major sixth chord."""

def minor_sixth(note: str) -> List[str]:
    """Return minor sixth chord."""

def major_ninth(note: str) -> List[str]:
    """Return major ninth chord."""

def minor_ninth(note: str) -> List[str]:
    """Return minor ninth chord."""

def dominant_ninth(note: str) -> List[str]:
    """Return dominant ninth chord."""

def dominant_flat_ninth(note: str) -> List[str]:
    """Return dominant flat ninth chord."""

def dominant_sharp_ninth(note: str) -> List[str]:
    """Return dominant sharp ninth chord."""

def eleventh(note: str) -> List[str]:
    """Return eleventh chord."""

def minor_eleventh(note: str) -> List[str]:
    """Return minor eleventh chord."""

def major_thirteenth(note: str) -> List[str]:
    """Return major thirteenth chord."""

def minor_thirteenth(note: str) -> List[str]:
    """Return minor thirteenth chord."""

def dominant_thirteenth(note: str) -> List[str]:
    """Return dominant thirteenth chord."""

def hendrix_chord(note: str) -> List[str]:
    """Return Hendrix chord (7#9)."""

def sixth_ninth(note: str) -> List[str]:
    """Return sixth/ninth chord."""

# Augmented chords
def augmented_major_seventh(note: str) -> List[str]:
    """Return augmented major seventh chord."""

def augmented_minor_seventh(note: str) -> List[str]:
    """Return augmented minor seventh chord."""

# Suspended chords
def suspended_triad(note: str) -> List[str]:
    """Return suspended triad (alias for sus4)."""

def suspended_second_triad(note: str) -> List[str]:
    """Return suspended second triad."""

def suspended_seventh(note: str) -> List[str]:
    """Return suspended seventh chord."""

def suspended_fourth_ninth(note: str) -> List[str]:
    """Return suspended fourth flat ninth chord."""

# Altered chords
def dominant_flat_five(note: str) -> List[str]:
    """Return dominant flat five chord."""

def lydian_dominant_seventh(note: str) -> List[str]:
    """Return lydian dominant seventh chord."""

# Chord analysis and manipulation
def determine(chord: List[str], shorthand: bool = False, no_inversions: bool = False, no_polychords: bool = False) -> str:
    """
    Analyze chord and return name.
    
    Parameters:
    - chord: List of note names
    - shorthand: Return shorthand notation
    - no_inversions: Don't consider inversions
    - no_polychords: Don't consider polychords
    
    Returns:
    Chord name or description
    """

def from_shorthand(shorthand_string: str, slash: str = None) -> List[str]:
    """
    Create chord from shorthand notation.
    
    Parameters:
    - shorthand_string: Chord shorthand (e.g., "CM7", "Am", "F#dim7")
    - slash: Slash chord bass note
    
    Returns:
    List of notes in chord
    """

def invert(chord: List[str]) -> List[str]:
    """
    Invert chord.
    
    Parameters:
    - chord: List of note names
    
    Returns:
    Inverted chord
    """

def first_inversion(chord: List[str]) -> List[str]:
    """Return first inversion of chord."""

def second_inversion(chord: List[str]) -> List[str]:
    """Return second inversion of chord."""

def third_inversion(chord: List[str]) -> List[str]:
    """Return third inversion of chord."""

# Functional harmony (named functions)
def tonic(key: str) -> List[str]:
    """Return tonic chord in key."""

def tonic7(key: str) -> List[str]:
    """Return tonic seventh chord in key."""

def supertonic(key: str) -> List[str]:
    """Return supertonic chord in key."""

def supertonic7(key: str) -> List[str]:
    """Return supertonic seventh chord in key."""

def mediant(key: str) -> List[str]:
    """Return mediant chord in key."""

def mediant7(key: str) -> List[str]:
    """Return mediant seventh chord in key."""

def subdominant(key: str) -> List[str]:
    """Return subdominant chord in key."""

def subdominant7(key: str) -> List[str]:
    """Return subdominant seventh chord in key."""

def dominant(key: str) -> List[str]:
    """Return dominant chord in key."""

def dominant7(key: str) -> List[str]:
    """Return dominant seventh chord in key."""

def submediant(key: str) -> List[str]:
    """Return submediant chord in key."""

def submediant7(key: str) -> List[str]:
    """Return submediant seventh chord in key."""

def subtonic(key: str) -> List[str]:
    """Return subtonic chord in key."""

def subtonic7(key: str) -> List[str]:
    """Return subtonic seventh chord in key."""

# Roman numeral analysis (aliases)
def I(key: str) -> List[str]:
    """Return tonic chord in key."""

def I7(key: str) -> List[str]:
    """Return tonic seventh chord in key."""

def ii(key: str) -> List[str]:
    """Return supertonic chord in key."""

def II(key: str) -> List[str]:
    """Return supertonic chord in key."""

def ii7(key: str) -> List[str]:
    """Return supertonic seventh chord in key."""

def II7(key: str) -> List[str]:
    """Return supertonic seventh chord in key."""

def iii(key: str) -> List[str]:
    """Return mediant chord in key."""

def III(key: str) -> List[str]:
    """Return mediant chord in key."""

def iii7(key: str) -> List[str]:
    """Return mediant seventh chord in key."""

def III7(key: str) -> List[str]:
    """Return mediant seventh chord in key."""

def IV(key: str) -> List[str]:
    """Return subdominant chord in key."""

def IV7(key: str) -> List[str]:
    """Return subdominant seventh chord in key."""

def V(key: str) -> List[str]:
    """Return dominant chord in key."""

def V7(key: str) -> List[str]:
    """Return dominant seventh chord in key."""

def vi(key: str) -> List[str]:
    """Return submediant chord in key."""

def VI(key: str) -> List[str]:
    """Return submediant chord in key."""

def vi7(key: str) -> List[str]:
    """Return submediant seventh chord in key."""

def VI7(key: str) -> List[str]:
    """Return submediant seventh chord in key."""

def vii(key: str) -> List[str]:
    """Return subtonic chord in key."""

def VII(key: str) -> List[str]:
    """Return subtonic chord in key."""

def vii7(key: str) -> List[str]:
    """Return subtonic seventh chord in key."""

def VII7(key: str) -> List[str]:
    """Return subtonic seventh chord in key."""

Scale Construction

Scale classes for constructing and analyzing various musical scales and modes.

class Diatonic:
    """Generic diatonic scale."""
    
    def __init__(self, note: str, semitones: List[int], octaves: int = 1):
        """
        Create diatonic scale.
        
        Parameters:
        - note: Root note
        - semitones: List of semitone intervals
        - octaves: Number of octaves
        """
    
    def ascending(self) -> List[str]:
        """Return ascending notes."""
    
    def descending(self) -> List[str]:
        """Return descending notes."""
    
    def degree(self, degree_number: int, direction: str = "a") -> str:
        """
        Return scale degree.
        
        Parameters:
        - degree_number: Scale degree (1-8)
        - direction: "a" for ascending, "d" for descending
        
        Returns:
        Note at scale degree
        """
    
    @property
    def name(self) -> str:
        """Scale name."""
    
    @property
    def tonic(self) -> str:
        """Tonic note."""

class Major(Diatonic):
    """Major scale (Ionian mode)."""
    
    def __init__(self, note: str, octaves: int = 1):
        """Create major scale."""

class NaturalMinor(Diatonic):
    """Natural minor scale (Aeolian mode)."""
    
    def __init__(self, note: str, octaves: int = 1):
        """Create natural minor scale."""

class HarmonicMinor(Diatonic):
    """Harmonic minor scale."""
    
    def __init__(self, note: str, octaves: int = 1):
        """Create harmonic minor scale."""

class MelodicMinor(Diatonic):
    """Melodic minor scale."""
    
    def __init__(self, note: str, octaves: int = 1):
        """Create melodic minor scale."""

class HarmonicMajor(Diatonic):
    """Harmonic major scale."""
    
    def __init__(self, note: str, octaves: int = 1):
        """Create harmonic major scale."""

class Bachian(Diatonic):
    """Bachian scale."""
    
    def __init__(self, note: str, octaves: int = 1):
        """Create Bachian scale."""

class MinorNeapolitan(Diatonic):
    """Minor Neapolitan scale."""
    
    def __init__(self, note: str, octaves: int = 1):
        """Create minor Neapolitan scale."""

# Modal scales
class Dorian(Diatonic):
    """Dorian mode."""
    
    def __init__(self, note: str, octaves: int = 1):
        """Create Dorian scale."""

class Phrygian(Diatonic):
    """Phrygian mode."""
    
    def __init__(self, note: str, octaves: int = 1):
        """Create Phrygian scale."""

class Lydian(Diatonic):
    """Lydian mode."""
    
    def __init__(self, note: str, octaves: int = 1):
        """Create Lydian scale."""

class Mixolydian(Diatonic):
    """Mixolydian mode."""
    
    def __init__(self, note: str, octaves: int = 1):
        """Create Mixolydian scale."""

class Locrian(Diatonic):
    """Locrian mode."""
    
    def __init__(self, note: str, octaves: int = 1):
        """Create Locrian scale."""

# Other scales
class Chromatic(Diatonic):
    """Chromatic scale."""
    
    def __init__(self, key: str, octaves: int = 1):
        """Create chromatic scale."""

class WholeTone(Diatonic):
    """Whole tone scale."""
    
    def __init__(self, note: str, octaves: int = 1):
        """Create whole tone scale."""

class Octatonic(Diatonic):
    """Octatonic (diminished) scale."""
    
    def __init__(self, note: str, octaves: int = 1):
        """Create octatonic scale."""

def determine(notes: List[str]) -> List[str]:
    """
    Determine scales containing given notes.
    
    Parameters:
    - notes: List of note names
    
    Returns:
    List of possible scale names
    """

Chord Progressions

Functions for working with chord progressions and harmonic analysis.

def to_chords(progression: List[str], key: str = "C") -> List[List[str]]:
    """
    Convert progression to chords.
    
    Parameters:
    - progression: List of Roman numerals or chord functions
    - key: Key for progression
    
    Returns:
    List of chord note lists
    """

def determine(chord: List[str], key: str, shorthand: bool = False) -> str:
    """
    Determine chord function in key.
    
    Parameters:
    - chord: List of note names
    - key: Key for analysis
    - shorthand: Return shorthand notation
    
    Returns:
    Chord function (e.g., "I", "V7", "vi")
    """

def substitute(progression: List[str], substitute_index: int, depth: int = 0) -> List[str]:
    """
    Generate chord substitutions for progression.
    
    Parameters:
    - progression: List of chord functions
    - substitute_index: Index to substitute
    - depth: Substitution depth
    
    Returns:
    List of possible substitution progressions
    """

def substitute_harmonic(progression: List[str], substitute_index: int, ignore_suffix: bool = False) -> List[str]:
    """
    Perform simple harmonic substitutions.
    
    Parameters:
    - progression: List of chord functions
    - substitute_index: Index to substitute
    - ignore_suffix: Ignore chord suffixes if True
    
    Returns:
    List of possible harmonic substitutions
    """

def substitute_minor_for_major(progression: List[str], substitute_index: int, ignore_suffix: bool = False) -> List[str]:
    """
    Substitute minor chords for major equivalents.
    
    Parameters:
    - progression: List of chord functions
    - substitute_index: Index to substitute
    - ignore_suffix: Ignore chord suffixes if True
    
    Returns:
    List of minor chord substitutions
    """

def substitute_major_for_minor(progression: List[str], substitute_index: int, ignore_suffix: bool = False) -> List[str]:
    """
    Substitute major chords for minor equivalents.
    
    Parameters:
    - progression: List of chord functions
    - substitute_index: Index to substitute
    - ignore_suffix: Ignore chord suffixes if True
    
    Returns:
    List of major chord substitutions
    """

def substitute_diminished_for_diminished(progression: List[str], substitute_index: int, ignore_suffix: bool = False) -> List[str]:
    """
    Substitute diminished chord for another diminished chord.
    
    Parameters:
    - progression: List of chord functions
    - substitute_index: Index to substitute
    - ignore_suffix: Ignore chord suffixes if True
    
    Returns:
    List of diminished chord substitutions
    """

def substitute_diminished_for_dominant(progression: List[str], substitute_index: int, ignore_suffix: bool = False) -> List[str]:
    """
    Substitute diminished chords for dominant seventh chords.
    
    Parameters:
    - progression: List of chord functions
    - substitute_index: Index to substitute
    - ignore_suffix: Ignore chord suffixes if True
    
    Returns:
    List of diminished-to-dominant substitutions
    """

def parse_string(progression: str) -> Tuple[str, int, str]:
    """
    Parse progression string into components.
    
    Parameters:
    - progression: Roman numeral progression string
    
    Returns:
    Tuple of (roman numeral, accidentals, suffix)
    """

def tuple_to_string(prog_tuple: Tuple[str, int, str]) -> str:
    """
    Convert parsed tuple back to string.
    
    Parameters:
    - prog_tuple: Tuple from parse_string
    
    Returns:
    Reconstructed progression string
    """

def interval_diff(progression1: str, progression2: str, interval: int) -> int:
    """
    Calculate interval difference between progressions.
    
    Parameters:
    - progression1: First roman numeral
    - progression2: Second roman numeral
    - interval: Target interval in semitones
    
    Returns:
    Number of accidentals needed for adjustment
    """

def skip(roman_numeral: str, skip_count: int = 1) -> str:
    """
    Skip to next roman numeral.
    
    Parameters:
    - roman_numeral: Starting roman numeral
    - skip_count: Number of steps to skip
    
    Returns:
    Next roman numeral in sequence
    """

# Constants
numerals: List[str] = ["I", "II", "III", "IV", "V", "VI", "VII"]
"""Roman numeral progression sequence."""

numeral_intervals: List[int] = [0, 2, 4, 5, 7, 9, 11]
"""Half-step intervals for each roman numeral."""

Rhythmic Values

Constants and functions for working with note values and durations.

# Note value constants
whole: int = 1
half: int = 2
quarter: int = 4
eighth: int = 8
sixteenth: int = 16
thirty_second: int = 32
sixty_fourth: int = 64

def add(value1: int, value2: int) -> int:
    """
    Add note values.
    
    Parameters:
    - value1, value2: Note values to add
    
    Returns:
    Combined note value
    """

def subtract(value1: int, value2: int) -> int:
    """
    Subtract note values.
    
    Parameters:
    - value1, value2: Note values
    
    Returns:
    Difference in note values
    """

def dots(value: int, nr: int = 1) -> float:
    """
    Add dots to note value.
    
    Parameters:
    - value: Base note value
    - nr: Number of dots
    
    Returns:
    Dotted note value
    """

def triplet(value: int) -> float:
    """
    Create triplet value.
    
    Parameters:
    - value: Base note value
    
    Returns:
    Triplet note value
    """

def determine(value: float) -> str:
    """
    Analyze note value.
    
    Parameters:
    - value: Note value to analyze
    
    Returns:
    Description of note value
    """

Time Signatures

Functions for working with time signatures and meters.

def is_valid(meter: Tuple[int, int]) -> bool:
    """
    Test if meter tuple is valid.
    
    Parameters:
    - meter: Time signature tuple (numerator, denominator)
    
    Returns:
    True if meter is valid
    """

def is_compound(meter: Tuple[int, int]) -> bool:
    """
    Test if meter is compound.
    
    Parameters:
    - meter: Time signature tuple
    
    Returns:
    True if meter is compound
    """

def is_simple(meter: Tuple[int, int]) -> bool:
    """
    Test if meter is simple.
    
    Parameters:
    - meter: Time signature tuple
    
    Returns:
    True if meter is simple
    """

# Common time signatures
common_time: Tuple[int, int] = (4, 4)
cut_time: Tuple[int, int] = (2, 2)

Install with Tessl CLI