0
# Format Export
1

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

4
## Capabilities
5

6
### LilyPond Notation Export
7

8
Convert mingus musical structures to LilyPond notation language for high-quality music typesetting and rendering.
9

10
```python { .api }
11
def from_Note(note: Note, process_octaves: bool = True, standalone: bool = True) -> str:
12
    """
13
    Convert Note to LilyPond notation.
14
    
15
    Parameters:
16
    - note: Note object to convert
17
    - process_octaves: Include octave information
18
    - standalone: Create complete LilyPond document
19
    
20
    Returns:
21
    LilyPond notation string
22
    """
23

24
def from_NoteContainer(nc: NoteContainer, duration: int = None, standalone: bool = True) -> str:
25
    """
26
    Convert NoteContainer to LilyPond chord notation.
27
    
28
    Parameters:
29
    - nc: NoteContainer to convert
30
    - duration: Note duration for chord
31
    - standalone: Create complete LilyPond document
32
    
33
    Returns:
34
    LilyPond notation string
35
    """
36

37
def from_Bar(bar: Bar, showkey: bool = True, showtime: bool = True) -> str:
38
    """
39
    Convert Bar to LilyPond notation.
40
    
41
    Parameters:
42
    - bar: Bar object to convert
43
    - showkey: Include key signature
44
    - showtime: Include time signature
45
    
46
    Returns:
47
    LilyPond notation string
48
    """
49

50
def from_Track(track: Track) -> str:
51
    """
52
    Convert Track to LilyPond notation.
53
    
54
    Parameters:
55
    - track: Track object to convert
56
    
57
    Returns:
58
    LilyPond notation string
59
    """
60

61
def from_Composition(composition: Composition) -> str:
62
    """
63
    Convert Composition to LilyPond score.
64
    
65
    Parameters:
66
    - composition: Composition to convert
67
    
68
    Returns:
69
    Complete LilyPond score notation
70
    """
71

72
def from_Suite(suite: Suite) -> str:
73
    """
74
    Convert Suite to LilyPond book format.
75
    
76
    Parameters:
77
    - suite: Suite containing multiple compositions
78
    
79
    Returns:
80
    LilyPond book notation
81
    """
82

83
def to_png(ly_string: str, filename: str) -> None:
84
    """
85
    Render LilyPond notation to PNG image.
86
    
87
    Parameters:
88
    - ly_string: LilyPond notation string
89
    - filename: Output PNG filename (without extension)
90
    """
91

92
def to_pdf(ly_string: str, filename: str) -> None:
93
    """
94
    Render LilyPond notation to PDF.
95
    
96
    Parameters:
97
    - ly_string: LilyPond notation string
98
    - filename: Output PDF filename (without extension)
99
    """
100

101
def save_string_and_execute_LilyPond(ly_string: str, filename: str, command: str) -> None:
102
    """
103
    Save LilyPond string and execute custom command.
104
    
105
    Parameters:
106
    - ly_string: LilyPond notation string
107
    - filename: Output filename
108
    - command: LilyPond command to execute
109
    """
110
```
111

112
### MusicXML Export
113

114
Export mingus structures to MusicXML format for interchange with notation software and digital audio workstations.
115

116
```python { .api }
117
def from_Note(note: Note) -> str:
118
    """
119
    Convert Note to MusicXML.
120
    
121
    Parameters:
122
    - note: Note object to convert
123
    
124
    Returns:
125
    MusicXML note element as string
126
    """
127

128
def from_Bar(bar: Bar) -> str:
129
    """
130
    Convert Bar to MusicXML measure.
131
    
132
    Parameters:
133
    - bar: Bar object to convert
134
    
135
    Returns:
136
    MusicXML measure element
137
    """
138

139
def from_Track(track: Track) -> str:
140
    """
141
    Convert Track to MusicXML part.
142
    
143
    Parameters:
144
    - track: Track object to convert
145
    
146
    Returns:
147
    MusicXML part element
148
    """
149

150
def from_Composition(comp: Composition) -> str:
151
    """
152
    Convert Composition to complete MusicXML document.
153
    
154
    Parameters:
155
    - comp: Composition to convert
156
    
157
    Returns:
158
    Complete MusicXML document string
159
    """
160

161
def write_Composition(composition: Composition, filename: str, zip: bool = False) -> None:
162
    """
163
    Write Composition to MusicXML file.
164
    
165
    Parameters:
166
    - composition: Composition to export
167
    - filename: Output filename
168
    - zip: Create compressed MXL file if True
169
    """
170
```
171

172
### ASCII Tablature Generation
173

174
Generate ASCII tablature for string instruments with customizable formatting and tunings.
175

176
```python { .api }
177
def begin_track(tuning: StringTuning, padding: int = 2) -> str:
178
    """
179
    Begin ASCII tablature track.
180
    
181
    Parameters:
182
    - tuning: String tuning definition
183
    - padding: Character padding between notes
184
    
185
    Returns:
186
    Tablature header string
187
    """
188

189
def add_headers(title: str, subtitle: str, author: str, email: str, description: str, tuning: StringTuning) -> str:
190
    """
191
    Add headers to tablature.
192
    
193
    Parameters:
194
    - title: Song title
195
    - subtitle: Song subtitle
196
    - author: Author name
197
    - email: Author email
198
    - description: Song description
199
    - tuning: String tuning
200
    
201
    Returns:
202
    Formatted header string
203
    """
204

205
def from_Note(note: Note, width: int = 80, tuning: StringTuning = None) -> str:
206
    """
207
    Convert Note to tablature.
208
    
209
    Parameters:
210
    - note: Note to convert
211
    - width: Line width for tablature
212
    - tuning: String tuning (uses standard guitar if None)
213
    
214
    Returns:
215
    ASCII tablature string
216
    """
217

218
def from_NoteContainer(notes: NoteContainer, width: int = 80, tuning: StringTuning = None) -> str:
219
    """
220
    Convert NoteContainer to tablature chord.
221
    
222
    Parameters:
223
    - notes: Notes to convert
224
    - width: Line width
225
    - tuning: String tuning
226
    
227
    Returns:
228
    ASCII tablature string
229
    """
230

231
def from_Bar(bar: Bar, width: int = 40, tuning: StringTuning = None, collapse: bool = True) -> str:
232
    """
233
    Convert Bar to tablature.
234
    
235
    Parameters:
236
    - bar: Bar to convert
237
    - width: Line width
238
    - tuning: String tuning
239
    - collapse: Collapse repeated notes
240
    
241
    Returns:
242
    ASCII tablature string
243
    """
244

245
def from_Track(track: Track, maxwidth: int = 80, tuning: StringTuning = None) -> str:
246
    """
247
    Convert Track to tablature.
248
    
249
    Parameters:
250
    - track: Track to convert
251
    - maxwidth: Maximum line width
252
    - tuning: String tuning
253
    
254
    Returns:
255
    Complete ASCII tablature
256
    """
257

258
def from_Composition(composition: Composition, width: int = 80) -> str:
259
    """
260
    Convert Composition to tablature.
261
    
262
    Parameters:
263
    - composition: Composition to convert
264
    - width: Line width
265
    
266
    Returns:
267
    Complete tablature for all tracks
268
    """
269

270
def from_Suite(suite: Suite, maxwidth: int = 80) -> str:
271
    """
272
    Convert Suite to tablature collection.
273
    
274
    Parameters:
275
    - suite: Suite to convert
276
    - maxwidth: Maximum line width
277
    
278
    Returns:
279
    Tablature for entire suite
280
    """
281
```
282

283
### String Instrument Tunings
284

285
Comprehensive support for string instrument tunings and fingering analysis.
286

287
```python { .api }
288
class StringTuning:
289
    """String instrument tuning with fingering capabilities."""
290
    
291
    def __init__(self, instrument: str, description: str, tuning: List[str]):
292
        """
293
        Create string tuning.
294
        
295
        Parameters:
296
        - instrument: Instrument name
297
        - description: Tuning description
298
        - tuning: List of string notes (lowest to highest)
299
        """
300
    
301
    def count_strings(self) -> int:
302
        """
303
        Count number of strings.
304
        
305
        Returns:
306
        Number of strings in tuning
307
        """
308
    
309
    def count_courses(self) -> int:
310
        """
311
        Count number of courses (string groups).
312
        
313
        Returns:
314
        Number of courses
315
        """
316
    
317
    def find_frets(self, note: str, maxfret: int = 24) -> List[Tuple[int, int]]:
318
        """
319
        Find fret positions for note.
320
        
321
        Parameters:
322
        - note: Note to find
323
        - maxfret: Maximum fret to search
324
        
325
        Returns:
326
        List of (string, fret) tuples
327
        """
328
    
329
    def find_fingering(self, notes: List[str], max_distance: int = 4, not_strings: List[int] = None) -> List[int]:
330
        """
331
        Find fingering for notes.
332
        
333
        Parameters:
334
        - notes: List of notes to finger
335
        - max_distance: Maximum fret span
336
        - not_strings: Strings to avoid
337
        
338
        Returns:
339
        List of fret positions for each string
340
        """
341
    
342
    def find_chord_fingering(self, notes: List[str], max_distance: int = 4, not_strings: List[int] = None) -> List[int]:
343
        """
344
        Find chord fingering.
345
        
346
        Parameters:
347
        - notes: Chord notes
348
        - max_distance: Maximum fret span
349
        - not_strings: Strings to avoid
350
        
351
        Returns:
352
        Optimal fingering pattern
353
        """
354
    
355
    def frets_to_NoteContainer(self, fingering: List[int]) -> NoteContainer:
356
        """
357
        Convert fingering to NoteContainer.
358
        
359
        Parameters:
360
        - fingering: List of fret positions
361
        
362
        Returns:
363
        NoteContainer with fingered notes
364
        """
365
    
366
    def find_note_names(self, notelist: List[str], string: int = 0, maxfret: int = 24) -> List[Tuple[str, int]]:
367
        """
368
        Find note names on string.
369
        
370
        Parameters:
371
        - notelist: Notes to find
372
        - string: String number (0-based)
373
        - maxfret: Maximum fret
374
        
375
        Returns:
376
        List of (note, fret) tuples
377
        """
378
    
379
    def get_Note(self, string: int = 0, fret: int = 0, maxfret: int = 24) -> Note:
380
        """
381
        Get note at string and fret position.
382
        
383
        Parameters:
384
        - string: String number (0-based)
385
        - fret: Fret number
386
        - maxfret: Maximum allowed fret
387
        
388
        Returns:
389
        Note object at position
390
        """
391

392
# Tuning utility functions
393
def fingers_needed(fingering: List[int]) -> int:
394
    """
395
    Calculate number of fingers needed for fingering.
396
    
397
    Parameters:
398
    - fingering: List of fret positions
399
    
400
    Returns:
401
    Number of fingers required
402
    """
403

404
def add_tuning(instrument: str, description: str, tuning: List[str]) -> None:
405
    """
406
    Add tuning to tuning database.
407
    
408
    Parameters:
409
    - instrument: Instrument name
410
    - description: Tuning description
411
    - tuning: List of string notes
412
    """
413

414
def get_tuning(instrument: str, description: str, nr_of_strings: int = None, nr_of_courses: int = None) -> StringTuning:
415
    """
416
    Get tuning from database.
417
    
418
    Parameters:
419
    - instrument: Instrument name
420
    - description: Tuning description
421
    - nr_of_strings: Number of strings filter
422
    - nr_of_courses: Number of courses filter
423
    
424
    Returns:
425
    StringTuning object
426
    """
427

428
def get_tunings(instrument: str = None, nr_of_strings: int = None, nr_of_courses: int = None) -> List[StringTuning]:
429
    """
430
    Get all tunings matching criteria.
431
    
432
    Parameters:
433
    - instrument: Instrument name filter
434
    - nr_of_strings: Number of strings filter
435
    - nr_of_courses: Number of courses filter
436
    
437
    Returns:
438
    List of matching StringTuning objects
439
    """
440

441
def get_instruments() -> List[str]:
442
    """
443
    Get list of available instruments.
444
    
445
    Returns:
446
    List of instrument names
447
    """
448
```
449

450
### Audio Analysis via FFT
451

452
Analyze audio data using Fast Fourier Transform to extract musical information from recorded audio.
453

454
```python { .api }
455
def find_frequencies(data: List[float], freq: int = 44100, bits: int = 16) -> List[Tuple[float, float]]:
456
    """
457
    Find frequencies in audio data using FFT.
458
    
459
    Parameters:
460
    - data: Audio sample data
461
    - freq: Sample rate in Hz
462
    - bits: Bit depth
463
    
464
    Returns:
465
    List of (frequency, amplitude) tuples
466
    """
467

468
def find_notes(freqTable: List[Tuple[float, float]], maxNote: int = 100) -> List[str]:
469
    """
470
    Convert frequency table to note names.
471
    
472
    Parameters:
473
    - freqTable: List of (frequency, amplitude) tuples
474
    - maxNote: Maximum number of notes to return
475
    
476
    Returns:
477
    List of note names
478
    """
479

480
def data_from_file(file: str) -> List[float]:
481
    """
482
    Load audio file data.
483
    
484
    Parameters:
485
    - file: Audio filename to load
486
    
487
    Returns:
488
    Raw audio sample data
489
    """
490

491
def find_Note(data: List[float], freq: int, bits: int) -> str:
492
    """
493
    Find single dominant note in audio data.
494
    
495
    Parameters:
496
    - data: Audio sample data
497
    - freq: Sample rate
498
    - bits: Bit depth
499
    
500
    Returns:
501
    Dominant note name
502
    """
503

504
def analyze_chunks(data: List[float], freq: int, bits: int, chunksize: int = 512) -> List[List[str]]:
505
    """
506
    Analyze audio in chunks to extract note sequences.
507
    
508
    Parameters:
509
    - data: Audio sample data
510
    - freq: Sample rate
511
    - bits: Bit depth
512
    - chunksize: Size of analysis chunks
513
    
514
    Returns:
515
    List of note lists for each chunk
516
    """
517

518
def find_melody(file: str = "440_480_clean.wav", chunksize: int = 512) -> List[str]:
519
    """
520
    Extract melody from audio file.
521
    
522
    Parameters:
523
    - file: Audio filename
524
    - chunksize: Analysis chunk size
525
    
526
    Returns:
527
    List of notes representing melody
528
    """
529
```
530

531
## Usage Examples
532

533
### LilyPond Notation Export
534

535
```python
536
from mingus.extra import lilypond
537
from mingus.containers import Composition, Track, Bar
538

539
# Create musical content
540
composition = Composition()
541
composition.set_title("Example Piece")
542
composition.set_author("Composer Name")
543

544
track = Track()
545
bar = Bar()
546
bar.place_notes(["C", "E", "G"], 4)  # Quarter note chord
547
bar.place_notes("F", 2)              # Half note
548
track.add_bar(bar)
549
composition.add_track(track)
550

551
# Convert to LilyPond notation
552
ly_notation = lilypond.from_Composition(composition)
553
print(ly_notation)
554

555
# Render to PDF
556
lilypond.to_pdf(ly_notation, "example_piece")
557
```
558

559
### MusicXML Export
560

561
```python
562
from mingus.extra import musicxml
563
from mingus.containers import Composition, Track, Bar
564

565
# Create composition
566
composition = Composition()
567
composition.set_title("My Song")
568

569
# Add musical content
570
track = Track()
571
bar = Bar()
572
bar.place_notes("C", 4)
573
bar.place_notes("D", 4)
574
bar.place_notes("E", 2)
575
track.add_bar(bar)
576
composition.add_track(track)
577

578
# Export to MusicXML
579
musicxml.write_Composition(composition, "my_song.xml")
580
```
581

582
### ASCII Tablature Generation
583

584
```python
585
from mingus.extra import tablature
586
from mingus.extra.tunings import StringTuning
587
from mingus.containers import Track, Bar
588

589
# Create guitar tuning (standard tuning)
590
guitar_tuning = StringTuning("Guitar", "Standard", ["E", "A", "D", "G", "B", "E"])
591

592
# Create musical content
593
track = Track()
594
bar = Bar()
595
bar.place_notes("E", 4)  # Low E string open
596
bar.place_notes("A", 4)  # A string open
597
bar.place_notes("D", 4)  # D string open
598
track.add_bar(bar)
599

600
# Generate tablature
601
tab = tablature.from_Track(track, maxwidth=60, tuning=guitar_tuning)
602
print(tab)
603
```
604

605
### String Instrument Fingering
606

607
```python
608
from mingus.extra.tunings import StringTuning
609

610
# Create guitar tuning
611
guitar = StringTuning("Guitar", "Standard", ["E", "A", "D", "G", "B", "E"])
612

613
# Find fingering for C major chord
614
chord_notes = ["C", "E", "G"]
615
fingering = guitar.find_chord_fingering(chord_notes, max_distance=4)
616
print(f"C major fingering: {fingering}")
617

618
# Find all positions for a specific note
619
c_positions = guitar.find_frets("C", maxfret=12)
620
print(f"C note positions: {c_positions}")
621

622
# Convert fingering back to notes
623
notes = guitar.frets_to_NoteContainer(fingering)
624
print(f"Fingered notes: {notes.get_note_names()}")
625
```
626

627
### Audio Analysis
628

629
```python
630
from mingus.extra import fft
631

632
# Load and analyze audio file
633
audio_data = fft.data_from_file("recording.wav")
634

635
# Find frequencies in the audio
636
frequencies = fft.find_frequencies(audio_data, freq=44100, bits=16)
637

638
# Convert frequencies to note names
639
notes = fft.find_notes(frequencies, maxNote=10)
640
print(f"Detected notes: {notes}")
641

642
# Extract melody from audio file
643
melody = fft.find_melody("melody.wav", chunksize=1024)
644
print(f"Extracted melody: {melody}")
645

646
# Analyze audio in chunks for temporal analysis
647
chunks = fft.analyze_chunks(audio_data, 44100, 16, chunksize=512)
648
for i, chunk_notes in enumerate(chunks):
649
    print(f"Chunk {i}: {chunk_notes}")
650
```
651

652
### Custom Tuning Creation
653

654
```python
655
from mingus.extra.tunings import StringTuning
656

657
# Create custom banjo tuning
658
banjo_tuning = StringTuning("Banjo", "Open G", ["G", "D", "G", "B", "D"])
659

660
# Create mandolin tuning
661
mandolin_tuning = StringTuning("Mandolin", "Standard", ["G", "D", "A", "E"])
662

663
# Create bass tuning
664
bass_tuning = StringTuning("Bass", "Standard 4-string", ["E", "A", "D", "G"])
665

666
# Find chord fingerings for different instruments
667
g_major = ["G", "B", "D"]
668

669
banjo_fingering = banjo_tuning.find_chord_fingering(g_major)
670
mandolin_fingering = mandolin_tuning.find_chord_fingering(g_major)
671
bass_fingering = bass_tuning.find_chord_fingering(g_major)
672

673
print(f"G major on banjo: {banjo_fingering}")
674
print(f"G major on mandolin: {mandolin_fingering}")
675
print(f"G major on bass: {bass_fingering}")
676
```