Skip to content

README.md

Latest commit

 

History

History
187 lines (125 loc) · 7.95 KB

README.md

File metadata and controls

187 lines (125 loc) · 7.95 KB

MEDIOCRE-MUSIC

An AI tool for generating unique, cutting-edge musical compositions via hybridization.

npm version MIT License Node.js Version

Listen to what it makes →

Haydn crossed with Merzbow. Messiaen crossed with Burial. Babbitt crossed with Muslimgauze.

mediocre-music runs a coordinated pipeline of AI agents — composer, QA critic, orchestrator, drum arranger, soundfont selector, ornament specialist — that iteratively generate and refine compositions in ABC notation, then render them to MIDI and WAV. You control how long it runs and how weird it gets.

It's built as a training data generator for audio ML, but the output is genuinely interesting on its own.

Hear It

Stochastic Voltage — Xenakis × Lightning Bolt

stochastic-voltage-1767426307965.webm

Ionisation Infinitum: Noise Architecture for Orchestral Machines — Varèse × Merzbow

ionisation-infinitum-noise-architecture-for-orches-1771959392556.webm

Viennese Glitch Waltz — Strauss × Oneohtrix Point Never

viennese-glitch-waltz-1768854783329.webm

Ride of the Hypercore Valkyries — Wagner × Speedcore

ride-of-the-hypercore-valkyries-1767583620798.webm

Partchcore Genesis — Harry Partch × Happy Hardcore

partchcore-genesis-1767859136656.webm

Full gallery with PDF scores and analysis →

Try It

npm install -g mediocre-music
export ANTHROPIC_API_KEY=your_key_here

mediocre generate \
  -C "Messiaen,Varese,Spectralism" \
  -M "Merzbow,Burial,Oneohtrix Point Never" \
  -s "Excessively Experimental" \
  --sequential --max-iterations 8 --stream-text

That's it. Walk away. Come back to rendered audio.

What It Does

  • Genre fusion at scale — give it any classical composers and modern artists, it figures out how to merge them
  • Multi-agent pipeline — 10+ specialized agents (composer, QA critic, orchestrator, drum arranger, soundfont selector, ornamentation, MIDI expression, title guard, genre researcher) run in coordination
  • Iterative refinement — the orchestrator scores each iteration and directs targeted improvements until the piece passes QA or hits your iteration limit
  • Human-in-the-loop — --interactive mode lets you approve, reject, redirect, listen, or branch at every iteration
  • Full render pipeline — ABC → MIDI → WAV → WebM, with PDF scores and structured JSON analysis for every piece
  • Soundfont-aware — custom TiMidity configs per composition, soundfont selected per genre
  • Structured output — composition agent uses Zod schemas to build valid ABC deterministically, not by hoping the LLM gets the syntax right
  • Dataset-ready — everything outputs to structured JSON alongside the audio for ML training

Install

npm install -g mediocre-music

Requires: Node.js 18+, ANTHROPIC_API_KEY, and these system tools:

# Ubuntu/Debian
apt install abcmidi abcm2ps ghostscript timidity fluidsynth sox ffmpeg

# macOS
brew install abcmidi abcm2ps ghostscript timidity fluidsynth sox ffmpeg

# NixOS
nix-shell -p abcmidi abcm2ps ghostscript timidity fluidsynth sox ffmpeg

Key Flags

Flag What it does
-C Classical composers/genres to fuse from
-M Modern artists/genres to fuse from
-s Style description
--sequential Enable multi-agent orchestration loop
--max-iterations N How many refinement cycles (default: 5)
--interactive Pause at each iteration for human control
--stream-text Watch the composition being written in real time
-c N Generate N compositions
--model <id> Use a different model (works with --proxy-url + --api-key for any provider)
--llama-server <url> Use a local LLM via OpenAI-compatible API instead of Anthropic (e.g. http://localhost:8001/v1)
--abc2midi <path> Path to a custom abc2midi binary (see abc2midi-llm fork below)
--instruments <list> Comma-separated instruments for template composition (e.g. "sitar,tabla,fretless bass")

Local Model Support

mediocre-music works with any OpenAI-compatible local inference server (llama.cpp, vLLM, etc.):

mediocre generate \
  -g "bartok_x_venetian_snares" \
  --llama-server http://localhost:8001/v1 \
  --abc2midi ~/.local/bin/abc2midi \
  --sequential --stream-text

No API key needed. The --llama-server flag switches all LLM calls from Anthropic to your local endpoint. Works with generate, compose, and all agent-based commands.

Template Pipeline

Generate structured compositions by first creating a formal template, then filling it with LLM-generated content:

# Create a 192-bar ritual form template
mediocre template --form ritual --key Ddor --meter 7/8 --bars 192 \
  --instruments "shakuhachi,koto,erhu,fretless bass" \
  --pneuma organic

# Fill the template with LLM content
mediocre compose template-ritual.abc \
  --llama-server http://localhost:8001/v1 \
  --abc2midi ~/.local/bin/abc2midi

Available forms: ritual, stack-overflow, source-transfer, accumulative. Each generates a scaffold with pre-written structural voices (drums, drones), content slots for the LLM to fill, and temporal humanization directives.

abc2midi-llm Fork

For the best results, use our abc2midi-llm fork which adds seven directives designed for LLM-generated music:

Directive What it does
%%PNEUMA Biological timing — note onset jitter, sinusoidal breathing tempo, cumulative drift, free time, rubato
%%ENSEMBLE Inter-voice micro-timing offsets so independently generated voices sound like musicians playing together
%%BREATH Automatic rest insertion at phrase boundaries — the piece breathes
%%GRAVITY Phrase-level weight — heavier openings, lighter middles, stretched endings
%%ARTICULATE Context-aware note length — repeated notes shortened, leaps lengthened, phrase endings sustained
%%SPATIAL Millisecond-scale delays between voice groups simulating physical distance
%%TRANSFORM Cross-voice algorithmic transformation — retrograde, inversion, fragmentation, pitch shift, time scale

Point mediocre-music at the fork with --abc2midi:

mediocre generate -g "messiaen_x_burial" \
  --system-prompt prompts/pneuma-system-prompt.txt \
  --abc2midi /path/to/abc2midi-llm/abc2midi

The template pipeline automatically includes these directives via --pneuma presets (subtle, organic, drunk, ritual, mechanical).

More

Full CLI reference, architecture docs, advanced usage, and troubleshooting in DOCS.md.