README.md

---
title: Theme Generator
emoji: 🎼
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false
short_description: Theme generators trained from the dict of musical themes
---

# Theme Generator

FastAPI web app for browsing the musical theme dictionary, playing catalog
themes, generating new themes with variable-order Markov or transformer engines,
and exporting MIDI, ABC, MusicXML, and Verovio-rendered SVG scores.

This Space is based on Harold Barlow and Sam Morgenstern's *A Dictionary of
Musical Themes* (Crown Publishers, New York, 1949), a printed reference catalog
of classical themes intended for identifying works from short melodic incipits.
The digitized working corpus lives in the GitHub repository
[`fpachet/musical_themes`](https://github.com/fpachet/musical_themes), including
the `midis/` directory used by the app.

The GitHub repository contains the code, corpus data, generation scripts, and
FastAPI app sources. This Hugging Face Space is the small public client for
exploring them: it displays the musical-theme dictionary, plays catalog and
generated samples, and lets users compare the variable-order Markov and small
transformer engines from the browser.

## Generation engines

The app offers two symbolic engines trained from the same normalized theme
corpus. Both generate `(relative pitch class, duration)` tokens and then realize
them as MIDI, ABC, MusicXML, and Verovio score previews.

- **Variable-order Markov**: backed by
  [`vo_regular_bp`](https://github.com/fpachet/vo-regular-bp), with finite-state
  constraints for length, rhythmic phase, duration vocabulary, triplet policy,
  and soft endpoint priors. The model is precomputed and loaded from
  `models/theme_lab_markov_cache/default.pkl`. This follows François Pachet,
  "Exact Regular-Constrained Variable-Order Markov Generation via Sparse
  Context-State Belief Propagation", arXiv:2605.07839
  ([arxiv.org/abs/2605.07839](https://arxiv.org/abs/2605.07839)).
- **Small transformer**: a vanilla PyTorch autoregressive transformer trained
  on the same token sequences. The deployed checkpoint has a 64-token context,
  84-symbol musical vocabulary, 48-wide embeddings, 4 attention heads, 2
  transformer layers, 96-wide feed-forward blocks, dropout 0.1, AdamW at
  `3e-4`, and was trained for 200 CPU steps. Sampling defaults are temperature
  `1.0` and top-k `16`.

The Docker image starts `apps.theme_lab.app` on port 7860.