Metadata-Version: 2.3
Name: emg
Version: 0.1.8
Summary: Python library for generating melodies using the concept of Eulerian paths
Author: Chinmay Kakatkar
License: MIT License
         
         Copyright (c) 2025 Chinmay Kakatkar
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Requires-Dist: matplotlib>=3.10.5
Requires-Dist: midi2audio>=0.1.1
Requires-Dist: midiutil>=1.2.1
Requires-Dist: networkx>=3.5
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/ckstash/emg
Description-Content-Type: text/markdown

# Eulerian Melody Generator

**emg** is a Python library for generating algorithmic melodies using Eulerian paths with de Bruijn graphs. It can compose a melody from stochastically generated musical motifs by building a Eulerian path, visualize the related de Bruijn graph, and export the melody as an MP3 using a SoundFont file. MuseScore has a number of SoundFont files (e.g., *TimGM6mb.sf2*) that can be downloaded [here](https://musescore.org/en/handbook/3/soundfonts-and-sfz-files).

---

## ✨ Features

- Stochastically generate musical motifs (or k-mers) over a chosen musical scale
- Build and visualize a de Bruijn graph from the musical motifs
- Find Eulerian paths in the graph to create coherent melodic sequences
- Export melodies in MP3 format and de Bruijn graphs in PNG format
- Several configurable parameters: scale, tempo, k‑mer length, repeats, etc.

---

## 📦 Installation

```bash
pip install emg
```

Built for Python 3.12 or above.

**System Prerequisites:**

- [FFmpeg](https://ffmpeg.org/)
- [FluidSynth](https://www.fluidsynth.org/)

These tools can be installed using Homebrew on Mac OS:

```bash
brew install ffmpeg
brew install fluid-synth
```

---

## 🚀 Quick Start

```Python
from emg.generator import EulerianMelodyGenerator

# Path to your SoundFont file
sf2_path = "TimGM6mb.sf2"

# Create a generator instance
generator = EulerianMelodyGenerator(
    soundfont_path=sf2_path,
    scale="C-Major-Pentatonic",
    bpm=200,
    kmer_length=4,
    num_kmers=8,
    num_repeats=8,
    random_seed=2
)

# Run the full pipeline
generator.run_generation_pipeline(
    graph_png_path="graph.png",
    mp3_output_path="melody.mp3"
)
```

Use FFmpeg to convert the MP3 file to an MP4 file (taking the PNG export of the de Bruijn graph - or some other image - as cover art), for uploading to platforms such as YouTube:
```Bash
ffmpeg -loop 1 -i graph.png -i melody.mp3 \
  -c:v libx264 -tune stillimage -c:a aac -b:a 192k \
  -pix_fmt yuv420p -shortest melody.mp4
```

---

## 📚 API Reference

See [here](https://github.com/ckstash/emg/blob/main/API.md)
