0
# Mingus
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: mingus
7
- **Language**: Python  
8
- **Installation**: `pip install mingus`
9

10
## Core Imports
11

12
```python
13
import mingus
14
```
15

16
Common for working with specific modules:
17

18
```python
19
# Music theory fundamentals
20
from mingus.core import notes, chords, scales, intervals, progressions
21
from mingus.core.keys import Key
22

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

27
# MIDI functionality
28
from mingus.midi import Sequencer, fluidsynth
29
from mingus.midi import midi_file_out, midi_file_in
30

31
# Additional utilities
32
from mingus.extra import lilypond, musicxml, tablature
33
from mingus.extra.tunings import StringTuning
34
```
35

36
## Basic Usage
37

38
```python
39
from mingus.core import chords, scales
40
from mingus.containers import Note, NoteContainer, Bar, Track
41
from mingus.midi import fluidsynth
42

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

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

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

55
# Create a simple melody
56
bar = Bar()
57
bar.place_notes("C", 4)  # Quarter note C
58
bar.place_notes("E", 4)  # Quarter note E  
59
bar.place_notes("G", 2)  # Half note G
60

61
# Work with tracks and compositions
62
track = Track()
63
track.add_bar(bar)
64

65
# MIDI playback (requires FluidSynth)
66
fluidsynth.init("soundfont.sf2")
67
fluidsynth.play_Track(track)
68
```
69

70
## Architecture
71

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

74
- **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.
75

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

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

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

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

84
## Capabilities
85

86
### Music Theory Core
87

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

90
```python { .api }
91
# Note operations
92
def int_to_note(note_int: int, accidentals: str = "#") -> str: ...
93
def note_to_int(note: str) -> int: ...
94
def is_valid_note(note: str) -> bool: ...
95

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

102
# Scale construction
103
class Major:
104
    def __init__(self, note: str, octaves: int = 1): ...
105
    def ascending(self) -> List[str]: ...
106
    def descending(self) -> List[str]: ...
107
```
108

109
[Music Theory Core](./music-theory-core.md)
110

111
### Musical Containers
112

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

115
```python { .api }
116
class Note:
117
    def __init__(self, name: str = "C", octave: int = 4, dynamics: Any = None, velocity: int = None, channel: int = None): ...
118
    def transpose(self, interval: str, up: bool = True) -> None: ...
119
    def to_hertz(self, standard_pitch: float = 440) -> float: ...
120

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

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

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

137
class Composition:
138
    def __init__(self): ...
139
    def add_track(self, track: Track) -> None: ...
140
    def set_title(self, title: str = "Untitled", subtitle: str = "") -> None: ...
141
```
142

143
[Musical Containers](./musical-containers.md)
144

145
### MIDI Operations
146

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

149
```python { .api }
150
class Sequencer:
151
    def __init__(self): ...
152
    def play_Note(self, note: Note, channel: int = 1, velocity: int = 100) -> None: ...
153
    def play_Bar(self, bar: Bar, channel: int = 1, bpm: int = 120) -> None: ...
154
    def play_Composition(self, composition: Composition, channels: List[int] = None, bpm: int = 120) -> None: ...
155
    def set_instrument(self, channel: int, instr: int, bank: int = 0) -> None: ...
156

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

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

167
[MIDI Operations](./midi-operations.md)
168

169
### Format Export
170

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

173
```python { .api }
174
# LilyPond notation export
175
def from_Composition(composition: Composition) -> str: ...
176
def from_Track(track: Track) -> str: ...
177
def to_png(ly_string: str, filename: str) -> None: ...
178
def to_pdf(ly_string: str, filename: str) -> None: ...
179

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

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

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

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

197
[Format Export](./format-export.md)
198

199
## Types
200

201
```python { .api }
202
# Type aliases used throughout the library
203
from typing import List, Tuple, Union, Optional, Any
204

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