or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

format-export.mdindex.mdmidi-operations.mdmusic-theory-core.mdmusical-containers.md
tile.json

tessl/pypi-mingus

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/mingus@0.6.x

To install, run

npx @tessl/cli install tessl/pypi-mingus@0.6.0

index.mddocs/

Mingus

A comprehensive Python music theory and MIDI processing library designed for programmers, musicians, composers, and researchers. Mingus provides a robust foundation of music theory components including intervals, chords, scales, and progressions with rigorous testing and convenient shorthand notation. The library extends beyond theory to support classical notation, MIDI sequencing and file I/O, MusicXML processing, ASCII tablature generation, and integration with external tools like LilyPond and FluidSynth.

Package Information

  • Package Name: mingus
  • Language: Python
  • Installation: pip install mingus

Core Imports

import mingus

Common for working with specific modules:

# Music theory fundamentals
from mingus.core import notes, chords, scales, intervals, progressions
from mingus.core.keys import Key

# Musical data structures  
from mingus.containers import Note, NoteContainer, Bar, Track, Composition
from mingus.containers import Piano, Guitar, MidiInstrument

# MIDI functionality
from mingus.midi import Sequencer, fluidsynth
from mingus.midi import midi_file_out, midi_file_in

# Additional utilities
from mingus.extra import lilypond, musicxml, tablature
from mingus.extra.tunings import StringTuning

Basic Usage

from mingus.core import chords, scales
from mingus.containers import Note, NoteContainer, Bar, Track
from mingus.midi import fluidsynth

# Create and analyze chords
chord = chords.major_triad("C")  # Returns ['C', 'E', 'G']
chord_name = chords.determine(['C', 'E', 'G'])  # Returns 'C major triad'

# Work with scales
c_major = scales.Major("C")
scale_notes = c_major.ascending()  # Returns ['C', 'D', 'E', 'F', 'G', 'A', 'B']

# Build musical structures
note = Note("C", 4)  # C in octave 4
chord_container = NoteContainer(['C', 'E', 'G'])

# Create a simple melody
bar = Bar()
bar.place_notes("C", 4)  # Quarter note C
bar.place_notes("E", 4)  # Quarter note E  
bar.place_notes("G", 2)  # Half note G

# Work with tracks and compositions
track = Track()
track.add_bar(bar)

# MIDI playback (requires FluidSynth)
fluidsynth.init("soundfont.sf2")
fluidsynth.play_Track(track)

Architecture

Mingus is organized into four main packages that work together to provide comprehensive music capabilities:

  • mingus.core: Music theory fundamentals including note operations, intervals, chords, scales, keys, progressions, and rhythmic values. These modules provide the theoretical foundation for all musical operations.

  • mingus.containers: Musical data structures representing notes, chords, bars, tracks, compositions, and instruments. These classes store and manipulate musical information at different hierarchical levels.

  • mingus.midi: MIDI functionality including sequencing, file I/O, and integration with FluidSynth. Enables real-time playback and MIDI file processing of musical structures.

  • mingus.extra: Additional utilities for exporting to various formats including LilyPond notation, MusicXML, ASCII tablature, and audio analysis via FFT.

This modular design allows developers to use components independently or combine them for sophisticated music analysis, generation, and manipulation applications.

Capabilities

Music Theory Core

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

# Note operations
def int_to_note(note_int: int, accidentals: str = "#") -> str: ...
def note_to_int(note: str) -> int: ...
def is_valid_note(note: str) -> bool: ...

# Chord construction and analysis  
def major_triad(note: str) -> List[str]: ...
def minor_seventh(note: str) -> List[str]: ...
def determine(chord: List[str], shorthand: bool = False) -> str: ...
def from_shorthand(shorthand_string: str) -> List[str]: ...

# Scale construction
class Major:
    def __init__(self, note: str, octaves: int = 1): ...
    def ascending(self) -> List[str]: ...
    def descending(self) -> List[str]: ...

Music Theory Core

Musical Containers

Data structures for representing and manipulating musical information at different hierarchical levels - from individual notes to complete compositions.

class Note:
    def __init__(self, name: str = "C", octave: int = 4, dynamics: Any = None, velocity: int = None, channel: int = None): ...
    def transpose(self, interval: str, up: bool = True) -> None: ...
    def to_hertz(self, standard_pitch: float = 440) -> float: ...

class NoteContainer:
    def __init__(self, notes: List[str] = None): ...
    def add_note(self, note: str, octave: int = None) -> bool: ...
    def from_chord(self, shorthand: str) -> bool: ...
    def determine(self, shorthand: bool = False) -> str: ...

class Bar:
    def __init__(self, key: str = "C", meter: Tuple[int, int] = (4, 4)): ...
    def place_notes(self, notes: Union[str, List[str]], duration: int) -> bool: ...
    def is_full(self) -> bool: ...

class Track:
    def __init__(self, instrument: Any = None): ...
    def add_bar(self, bar: Bar) -> None: ...
    def transpose(self, interval: str, up: bool = True) -> None: ...

class Composition:
    def __init__(self): ...
    def add_track(self, track: Track) -> None: ...
    def set_title(self, title: str = "Untitled", subtitle: str = "") -> None: ...

Musical Containers

MIDI Operations

MIDI sequencing, playback, file I/O, and FluidSynth integration for real-time audio synthesis and MIDI file processing.

class Sequencer:
    def __init__(self): ...
    def play_Note(self, note: Note, channel: int = 1, velocity: int = 100) -> None: ...
    def play_Bar(self, bar: Bar, channel: int = 1, bpm: int = 120) -> None: ...
    def play_Composition(self, composition: Composition, channels: List[int] = None, bpm: int = 120) -> None: ...
    def set_instrument(self, channel: int, instr: int, bank: int = 0) -> None: ...

# MIDI file operations
def write_Composition(file: str, composition: Composition, bpm: int = 120, repeat: int = 0, verbose: bool = False) -> None: ...
def MIDI_to_Composition(file: str) -> Composition: ...

# FluidSynth integration
def init(sf2: str, driver: str = None, file: str = None) -> bool: ...
def play_Track(track: Track, channel: int = 1, bpm: int = 120) -> None: ...
def set_instrument(channel: int, midi_instr: int, bank: int = 0) -> None: ...

MIDI Operations

Format Export

Export musical structures to various formats including LilyPond notation, MusicXML, ASCII tablature, and audio analysis capabilities.

# LilyPond notation export
def from_Composition(composition: Composition) -> str: ...
def from_Track(track: Track) -> str: ...
def to_png(ly_string: str, filename: str) -> None: ...
def to_pdf(ly_string: str, filename: str) -> None: ...

# MusicXML export
def write_Composition(composition: Composition, filename: str, zip: bool = False) -> None: ...

# ASCII tablature generation
def from_Track(track: Track, maxwidth: int = 80, tuning: StringTuning = None) -> str: ...

# String instrument tunings
class StringTuning:
    def __init__(self, instrument: str, description: str, tuning: List[str]): ...
    def find_frets(self, note: str, maxfret: int = 24) -> List[Tuple[int, int]]: ...
    def find_chord_fingering(self, notes: List[str], max_distance: int = 4) -> List[int]: ...

# Audio analysis via FFT
def find_frequencies(data: List[float], freq: int = 44100, bits: int = 16) -> List[Tuple[float, float]]: ...
def find_melody(file: str = "440_480_clean.wav", chunksize: int = 512) -> List[str]: ...

Format Export

Types

# Type aliases used throughout the library
from typing import List, Tuple, Union, Optional, Any

# Common type patterns
NoteType = str  # Note names like "C", "F#", "Bb"
ChordType = List[str]  # List of note names
MeterType = Tuple[int, int]  # Time signature (numerator, denominator)
IntervalType = str  # Interval names like "3", "5", "b7", "M7"