A Generative AI that composes MIDI music
The Jam Machine is an AI music composition tool that generates harmonious MIDI sequences. It's designed for musicians (beginners and professionals) looking for inspiration or backing tracks.
Key Features:
- Generate 8+ bars of multi-instrument MIDI music
- Control instruments, note density, and creativity level
- Download MIDI files to edit in your favorite DAW
- Runs locally or via web interface
┌─────────────────────────────────────────────────────────────────────────────┐
│ THE JAM MACHINE │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────┐
│ TRAINING (one-time, already done) │
│ │
│ 5000 MIDI Songs ──► Encoder ──► Text Tokens ──► Train GPT-2 Model │
│ │
│ Example text: "PIECE_START TRACK_START INST=DRUMS DENSITY=3 │
│ BAR_START NOTE_ON=36 TIME_DELTA=2 NOTE_OFF=36..." │
└──────────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ GENERATION (what happens when you use it) │
│ │
│ ┌─────────────────┐ │
│ Your Input ───► │ GPT-2 Model │ ───► Generated Text │
│ └─────────────────┘ │
│ │
│ • Instrument (Drums, Bass, Lead...) │
│ • Density (how many notes: 1-3) │
│ • Temperature (creativity: 0.1-1.0) │
└──────────────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ OUTPUT │
│ │
│ Generated Text ──► Decoder ──► MIDI File ──► Audio Preview │
│ │
│ Download the MIDI and import into GarageBand, Ableton, FL Studio... │
└──────────────────────────────────────────────────────────────────────────┘
The Jam Machine converts music into text, like a language:
| Musical Concept | Text Representation |
|---|---|
| Start of piece | PIECE_START |
| New instrument track | TRACK_START INST=DRUMS |
| Note density | DENSITY=3 |
| Play a note | NOTE_ON=60 (middle C) |
| Wait 1 beat | TIME_DELTA=4 |
| Release note | NOTE_OFF=60 |
| End of bar | BAR_END |
The GPT-2 model learns patterns from 5000 songs and generates new, coherent sequences.
Full documentation on GitHub Pages
| Page | Description |
|---|---|
| Encoding & Decoding Guide | Step-by-step walkthrough of the MIDI-to-text pipeline, token vocabulary, quantization, and a worked example using The Strokes' Reptilia |
| Embedding Explorer | Interactive visualizations of how the GPT-2 model represents MIDI tokens — embedding space, attention patterns, and head specialization |
- Python 3.11+
- FluidSynth (audio synthesis):
# macOS brew install fluidsynth # Ubuntu/Debian sudo apt install fluidsynth # Windows - see https://github.com/FluidSynth/fluidsynth/wiki/Download
# Clone the repository
git clone https://github.com/misnaej/the-jam-machine.git
cd the-jam-machine
# Option A: Use setup script (recommended)
./scripts/setup-env.sh
# Option B: Manual setup
pip install pipenv
pipenv install -e ".[ci]"
pipenv shellpipenv run python -m jammy.app.playgroundOpen the URL shown in your terminal (usually http://localhost:7860).
# Set up your HuggingFace token (optional, for faster downloads)
cp .env.example .env
# Edit .env with your token from https://huggingface.co/settings/tokens
docker compose upOpen http://localhost:7860. Generated output is available in ./output/ on the host.
The image uses CPU-only PyTorch (~2.5GB) and works on both amd64 and arm64.
- Choose an instrument for each track (Drums, Bass, Lead, etc.)
- Set creativity (temperature) - higher = more experimental
- Set density - how many notes per bar
- Click Generate - wait a few seconds
- Listen to the preview and view the piano roll
- Download the MIDI file
from jammy.load import load_model_and_tokenizer
from jammy.generating.config import GenerationConfig, TrackConfig
from jammy.generating.generate import GenerateMidiText
from jammy.embedding.decoder import TextDecoder
from jammy.utils import get_miditok
# Load model
model, tokenizer = load_model_and_tokenizer(
"JammyMachina/elec-gmusic-familized-model-13-12__17-35-53",
from_huggingface=True,
)
# Generate
tracks = [
TrackConfig(instrument="DRUMS", density=3, temperature=0.7),
TrackConfig(instrument="4", density=2, temperature=0.7), # Bass
TrackConfig(instrument="3", density=2, temperature=0.7), # Guitar
]
generator = GenerateMidiText(model, tokenizer, config=GenerationConfig(n_bars=8))
generator.generate_piece(tracks)
# Get the generated text and convert to MIDI
piece_text = generator.get_piece_text()
decoder = TextDecoder(get_miditok())
decoder.get_midi(piece_text, filename="my_song.mid")# Generate new music
pipenv run python examples/generate.py
# Encode/decode a MIDI file (roundtrip demo)
pipenv run python examples/encode_decode.pyOutput goes to output/examples/. See examples/README.md for details.
the-jam-machine/
├── src/jammy/ # Main package
│ ├── app/ # Gradio web interface
│ ├── analysis/ # Model visualization tools
│ ├── embedding/ # MIDI ↔ text conversion
│ ├── generating/ # Music generation (GPT-2)
│ ├── preprocessing/ # Data preprocessing
│ └── training/ # Model training
├── hf_space/ # HuggingFace Space deployment
├── examples/ # Runnable example scripts
├── test/ # Test suite (149 tests)
├── docs/ # GitHub Pages site
└── scripts/ # Build, test, deploy scripts
pipenv run pytest test/ -v# Lint
pipenv run ruff check src/ test/ app/ examples/
# Format
pipenv run ruff format src/ test/ app/ examples/
# Security audit
pipenv run pip-auditDevelopment of this repository is supported by Claude Code. The project includes custom skills and agents for a structured workflow:
| Skill | What it does |
|---|---|
/check |
Run tests + lint + format |
/lint |
Run ruff check + format |
/commit |
Lint, commit, and push to current branch |
/review |
Run design + docs review agents |
/pr |
Generate squash merge message |
Workflow:
- Create a feature branch from
main - Make changes, run
/checkto verify - Run
/committo lint, commit, and push - Create a PR, run
/prfor review and merge message - Squash and merge into
main
See CLAUDE.md for full development guidelines.
If you encounter errors with audio playback:
- Check this guide
- Ensure FluidSynth is in your PATH
- On macOS:
brew reinstall fluidsynth
The model (~500MB) downloads automatically on first run. If it fails:
- Check your internet connection
- Try:
huggingface-cli loginif you have rate limits
MIT License - feel free to use, modify, and distribute.