tessl/pypi-mingus
Python music theory and MIDI processing library for programmers, musicians, composers, and researchers.
—
Pending
format-export.mddocs/
Format Export
Export musical structures to various formats including LilyPond notation, MusicXML, ASCII tablature, and audio analysis capabilities. These modules enable mingus to generate publication-quality notation, industry-standard music files, and custom visualizations.
Capabilities
LilyPond Notation Export
Convert mingus musical structures to LilyPond notation language for high-quality music typesetting and rendering.
def from_Note(note: Note, process_octaves: bool = True, standalone: bool = True) -> str:
"""
Convert Note to LilyPond notation.
Parameters:
- note: Note object to convert
- process_octaves: Include octave information
- standalone: Create complete LilyPond document
Returns:
LilyPond notation string
"""
def from_NoteContainer(nc: NoteContainer, duration: int = None, standalone: bool = True) -> str:
"""
Convert NoteContainer to LilyPond chord notation.
Parameters:
- nc: NoteContainer to convert
- duration: Note duration for chord
- standalone: Create complete LilyPond document
Returns:
LilyPond notation string
"""
def from_Bar(bar: Bar, showkey: bool = True, showtime: bool = True) -> str:
"""
Convert Bar to LilyPond notation.
Parameters:
- bar: Bar object to convert
- showkey: Include key signature
- showtime: Include time signature
Returns:
LilyPond notation string
"""
def from_Track(track: Track) -> str:
"""
Convert Track to LilyPond notation.
Parameters:
- track: Track object to convert
Returns:
LilyPond notation string
"""
def from_Composition(composition: Composition) -> str:
"""
Convert Composition to LilyPond score.
Parameters:
- composition: Composition to convert
Returns:
Complete LilyPond score notation
"""
def from_Suite(suite: Suite) -> str:
"""
Convert Suite to LilyPond book format.
Parameters:
- suite: Suite containing multiple compositions
Returns:
LilyPond book notation
"""
def to_png(ly_string: str, filename: str) -> None:
"""
Render LilyPond notation to PNG image.
Parameters:
- ly_string: LilyPond notation string
- filename: Output PNG filename (without extension)
"""
def to_pdf(ly_string: str, filename: str) -> None:
"""
Render LilyPond notation to PDF.
Parameters:
- ly_string: LilyPond notation string
- filename: Output PDF filename (without extension)
"""
def save_string_and_execute_LilyPond(ly_string: str, filename: str, command: str) -> None:
"""
Save LilyPond string and execute custom command.
Parameters:
- ly_string: LilyPond notation string
- filename: Output filename
- command: LilyPond command to execute
"""MusicXML Export
Export mingus structures to MusicXML format for interchange with notation software and digital audio workstations.
def from_Note(note: Note) -> str:
"""
Convert Note to MusicXML.
Parameters:
- note: Note object to convert
Returns:
MusicXML note element as string
"""
def from_Bar(bar: Bar) -> str:
"""
Convert Bar to MusicXML measure.
Parameters:
- bar: Bar object to convert
Returns:
MusicXML measure element
"""
def from_Track(track: Track) -> str:
"""
Convert Track to MusicXML part.
Parameters:
- track: Track object to convert
Returns:
MusicXML part element
"""
def from_Composition(comp: Composition) -> str:
"""
Convert Composition to complete MusicXML document.
Parameters:
- comp: Composition to convert
Returns:
Complete MusicXML document string
"""
def write_Composition(composition: Composition, filename: str, zip: bool = False) -> None:
"""
Write Composition to MusicXML file.
Parameters:
- composition: Composition to export
- filename: Output filename
- zip: Create compressed MXL file if True
"""ASCII Tablature Generation
Generate ASCII tablature for string instruments with customizable formatting and tunings.
def begin_track(tuning: StringTuning, padding: int = 2) -> str:
"""
Begin ASCII tablature track.
Parameters:
- tuning: String tuning definition
- padding: Character padding between notes
Returns:
Tablature header string
"""
def add_headers(title: str, subtitle: str, author: str, email: str, description: str, tuning: StringTuning) -> str:
"""
Add headers to tablature.
Parameters:
- title: Song title
- subtitle: Song subtitle
- author: Author name
- email: Author email
- description: Song description
- tuning: String tuning
Returns:
Formatted header string
"""
def from_Note(note: Note, width: int = 80, tuning: StringTuning = None) -> str:
"""
Convert Note to tablature.
Parameters:
- note: Note to convert
- width: Line width for tablature
- tuning: String tuning (uses standard guitar if None)
Returns:
ASCII tablature string
"""
def from_NoteContainer(notes: NoteContainer, width: int = 80, tuning: StringTuning = None) -> str:
"""
Convert NoteContainer to tablature chord.
Parameters:
- notes: Notes to convert
- width: Line width
- tuning: String tuning
Returns:
ASCII tablature string
"""
def from_Bar(bar: Bar, width: int = 40, tuning: StringTuning = None, collapse: bool = True) -> str:
"""
Convert Bar to tablature.
Parameters:
- bar: Bar to convert
- width: Line width
- tuning: String tuning
- collapse: Collapse repeated notes
Returns:
ASCII tablature string
"""
def from_Track(track: Track, maxwidth: int = 80, tuning: StringTuning = None) -> str:
"""
Convert Track to tablature.
Parameters:
- track: Track to convert
- maxwidth: Maximum line width
- tuning: String tuning
Returns:
Complete ASCII tablature
"""
def from_Composition(composition: Composition, width: int = 80) -> str:
"""
Convert Composition to tablature.
Parameters:
- composition: Composition to convert
- width: Line width
Returns:
Complete tablature for all tracks
"""
def from_Suite(suite: Suite, maxwidth: int = 80) -> str:
"""
Convert Suite to tablature collection.
Parameters:
- suite: Suite to convert
- maxwidth: Maximum line width
Returns:
Tablature for entire suite
"""String Instrument Tunings
Comprehensive support for string instrument tunings and fingering analysis.
class StringTuning:
"""String instrument tuning with fingering capabilities."""
def __init__(self, instrument: str, description: str, tuning: List[str]):
"""
Create string tuning.
Parameters:
- instrument: Instrument name
- description: Tuning description
- tuning: List of string notes (lowest to highest)
"""
def count_strings(self) -> int:
"""
Count number of strings.
Returns:
Number of strings in tuning
"""
def count_courses(self) -> int:
"""
Count number of courses (string groups).
Returns:
Number of courses
"""
def find_frets(self, note: str, maxfret: int = 24) -> List[Tuple[int, int]]:
"""
Find fret positions for note.
Parameters:
- note: Note to find
- maxfret: Maximum fret to search
Returns:
List of (string, fret) tuples
"""
def find_fingering(self, notes: List[str], max_distance: int = 4, not_strings: List[int] = None) -> List[int]:
"""
Find fingering for notes.
Parameters:
- notes: List of notes to finger
- max_distance: Maximum fret span
- not_strings: Strings to avoid
Returns:
List of fret positions for each string
"""
def find_chord_fingering(self, notes: List[str], max_distance: int = 4, not_strings: List[int] = None) -> List[int]:
"""
Find chord fingering.
Parameters:
- notes: Chord notes
- max_distance: Maximum fret span
- not_strings: Strings to avoid
Returns:
Optimal fingering pattern
"""
def frets_to_NoteContainer(self, fingering: List[int]) -> NoteContainer:
"""
Convert fingering to NoteContainer.
Parameters:
- fingering: List of fret positions
Returns:
NoteContainer with fingered notes
"""
def find_note_names(self, notelist: List[str], string: int = 0, maxfret: int = 24) -> List[Tuple[str, int]]:
"""
Find note names on string.
Parameters:
- notelist: Notes to find
- string: String number (0-based)
- maxfret: Maximum fret
Returns:
List of (note, fret) tuples
"""
def get_Note(self, string: int = 0, fret: int = 0, maxfret: int = 24) -> Note:
"""
Get note at string and fret position.
Parameters:
- string: String number (0-based)
- fret: Fret number
- maxfret: Maximum allowed fret
Returns:
Note object at position
"""
# Tuning utility functions
def fingers_needed(fingering: List[int]) -> int:
"""
Calculate number of fingers needed for fingering.
Parameters:
- fingering: List of fret positions
Returns:
Number of fingers required
"""
def add_tuning(instrument: str, description: str, tuning: List[str]) -> None:
"""
Add tuning to tuning database.
Parameters:
- instrument: Instrument name
- description: Tuning description
- tuning: List of string notes
"""
def get_tuning(instrument: str, description: str, nr_of_strings: int = None, nr_of_courses: int = None) -> StringTuning:
"""
Get tuning from database.
Parameters:
- instrument: Instrument name
- description: Tuning description
- nr_of_strings: Number of strings filter
- nr_of_courses: Number of courses filter
Returns:
StringTuning object
"""
def get_tunings(instrument: str = None, nr_of_strings: int = None, nr_of_courses: int = None) -> List[StringTuning]:
"""
Get all tunings matching criteria.
Parameters:
- instrument: Instrument name filter
- nr_of_strings: Number of strings filter
- nr_of_courses: Number of courses filter
Returns:
List of matching StringTuning objects
"""
def get_instruments() -> List[str]:
"""
Get list of available instruments.
Returns:
List of instrument names
"""Audio Analysis via FFT
Analyze audio data using Fast Fourier Transform to extract musical information from recorded audio.
def find_frequencies(data: List[float], freq: int = 44100, bits: int = 16) -> List[Tuple[float, float]]:
"""
Find frequencies in audio data using FFT.
Parameters:
- data: Audio sample data
- freq: Sample rate in Hz
- bits: Bit depth
Returns:
List of (frequency, amplitude) tuples
"""
def find_notes(freqTable: List[Tuple[float, float]], maxNote: int = 100) -> List[str]:
"""
Convert frequency table to note names.
Parameters:
- freqTable: List of (frequency, amplitude) tuples
- maxNote: Maximum number of notes to return
Returns:
List of note names
"""
def data_from_file(file: str) -> List[float]:
"""
Load audio file data.
Parameters:
- file: Audio filename to load
Returns:
Raw audio sample data
"""
def find_Note(data: List[float], freq: int, bits: int) -> str:
"""
Find single dominant note in audio data.
Parameters:
- data: Audio sample data
- freq: Sample rate
- bits: Bit depth
Returns:
Dominant note name
"""
def analyze_chunks(data: List[float], freq: int, bits: int, chunksize: int = 512) -> List[List[str]]:
"""
Analyze audio in chunks to extract note sequences.
Parameters:
- data: Audio sample data
- freq: Sample rate
- bits: Bit depth
- chunksize: Size of analysis chunks
Returns:
List of note lists for each chunk
"""
def find_melody(file: str = "440_480_clean.wav", chunksize: int = 512) -> List[str]:
"""
Extract melody from audio file.
Parameters:
- file: Audio filename
- chunksize: Analysis chunk size
Returns:
List of notes representing melody
"""Usage Examples
LilyPond Notation Export
from mingus.extra import lilypond
from mingus.containers import Composition, Track, Bar
# Create musical content
composition = Composition()
composition.set_title("Example Piece")
composition.set_author("Composer Name")
track = Track()
bar = Bar()
bar.place_notes(["C", "E", "G"], 4) # Quarter note chord
bar.place_notes("F", 2) # Half note
track.add_bar(bar)
composition.add_track(track)
# Convert to LilyPond notation
ly_notation = lilypond.from_Composition(composition)
print(ly_notation)
# Render to PDF
lilypond.to_pdf(ly_notation, "example_piece")MusicXML Export
from mingus.extra import musicxml
from mingus.containers import Composition, Track, Bar
# Create composition
composition = Composition()
composition.set_title("My Song")
# Add musical content
track = Track()
bar = Bar()
bar.place_notes("C", 4)
bar.place_notes("D", 4)
bar.place_notes("E", 2)
track.add_bar(bar)
composition.add_track(track)
# Export to MusicXML
musicxml.write_Composition(composition, "my_song.xml")ASCII Tablature Generation
from mingus.extra import tablature
from mingus.extra.tunings import StringTuning
from mingus.containers import Track, Bar
# Create guitar tuning (standard tuning)
guitar_tuning = StringTuning("Guitar", "Standard", ["E", "A", "D", "G", "B", "E"])
# Create musical content
track = Track()
bar = Bar()
bar.place_notes("E", 4) # Low E string open
bar.place_notes("A", 4) # A string open
bar.place_notes("D", 4) # D string open
track.add_bar(bar)
# Generate tablature
tab = tablature.from_Track(track, maxwidth=60, tuning=guitar_tuning)
print(tab)String Instrument Fingering
from mingus.extra.tunings import StringTuning
# Create guitar tuning
guitar = StringTuning("Guitar", "Standard", ["E", "A", "D", "G", "B", "E"])
# Find fingering for C major chord
chord_notes = ["C", "E", "G"]
fingering = guitar.find_chord_fingering(chord_notes, max_distance=4)
print(f"C major fingering: {fingering}")
# Find all positions for a specific note
c_positions = guitar.find_frets("C", maxfret=12)
print(f"C note positions: {c_positions}")
# Convert fingering back to notes
notes = guitar.frets_to_NoteContainer(fingering)
print(f"Fingered notes: {notes.get_note_names()}")Audio Analysis
from mingus.extra import fft
# Load and analyze audio file
audio_data = fft.data_from_file("recording.wav")
# Find frequencies in the audio
frequencies = fft.find_frequencies(audio_data, freq=44100, bits=16)
# Convert frequencies to note names
notes = fft.find_notes(frequencies, maxNote=10)
print(f"Detected notes: {notes}")
# Extract melody from audio file
melody = fft.find_melody("melody.wav", chunksize=1024)
print(f"Extracted melody: {melody}")
# Analyze audio in chunks for temporal analysis
chunks = fft.analyze_chunks(audio_data, 44100, 16, chunksize=512)
for i, chunk_notes in enumerate(chunks):
print(f"Chunk {i}: {chunk_notes}")Custom Tuning Creation
from mingus.extra.tunings import StringTuning
# Create custom banjo tuning
banjo_tuning = StringTuning("Banjo", "Open G", ["G", "D", "G", "B", "D"])
# Create mandolin tuning
mandolin_tuning = StringTuning("Mandolin", "Standard", ["G", "D", "A", "E"])
# Create bass tuning
bass_tuning = StringTuning("Bass", "Standard 4-string", ["E", "A", "D", "G"])
# Find chord fingerings for different instruments
g_major = ["G", "B", "D"]
banjo_fingering = banjo_tuning.find_chord_fingering(g_major)
mandolin_fingering = mandolin_tuning.find_chord_fingering(g_major)
bass_fingering = bass_tuning.find_chord_fingering(g_major)
print(f"G major on banjo: {banjo_fingering}")
print(f"G major on mandolin: {mandolin_fingering}")
print(f"G major on bass: {bass_fingering}")Install with Tessl CLI
npx tessl i tessl/pypi-mingus