Add README

README.md

@@ -0,0 +1,75 @@
+---
+license: apache-2.0
+language:
+- en
+tags:
+- music
+- MIDI
+- piano
+- representation-learning
+- jepa
+base_model: loubb/aria-medium
+---
+
+# MAJEPPA
+
+`MAJEPPA` is a self-supervised model for piano performance representation learning. It adapts a pre-trained MIDI autoregressive backbone with a Joint-Embedding Predictive Architecture (JEPA) objective, learning to predict abstract performance representations from score representations in a shared latent space.
+
+The model is designed for downstream tasks such as performance quality assessment, competition ranking, technique classification, mistake detection, and expressive-style analysis of solo piano MIDI.
+
+📖 Paper: *MAJEPPA: Morphing and Assessing in a Unified Piano Performance Space* (ISMIR 2026)  
+💻 Code, evaluation, and loading utilities: [github.com/anusfoil/majeppa](https://github.com/anusfoil/majeppa)  
+📊 Benchmark: [github.com/anusfoil/evpmr](https://github.com/anusfoil/evpmr)
+
+## Model Details
+
+- **Base model**: [`loubb/aria-medium`](https://huggingface.co/loubb/aria-medium) (660M-parameter LLaMA-style autoregressive transformer pre-trained on symbolic MIDI)
+- **Adaptation**: Low-Rank Adaptation (LoRA, rank 512) applied to attention projections; a linear projection head 1536 → 512; and additional learned tokens for conditioning and prediction (`[COND_perf]`, `[COND_rec]`, `[PRED]`).
+- **Context length**: 4096 tokens (via linear RoPE scaling).
+
+The published `model.safetensors` contains the full set of weights (base model, LoRA adapters, projection head, and added token embeddings) ready to be loaded together.
+
+## Quickstart
+
+Install dependencies:
+
+```bash
+pip install torch safetensors
+pip install git+https://github.com/EleutherAI/aria-utils.git
+```
+
+Load the model via the loader script in the [MAJEPPA repository](https://github.com/anusfoil/majeppa):
+
+```python
+from majeppa import load_model, load_tokenizer
+
+model = load_model("anusfoil/majeppa-embedding", device="cuda")
+tokenizer = load_tokenizer()
+
+# Encode a piano MIDI file to a global embedding
+tokens = tokenizer.encode_from_file("path/to/performance.mid", return_tensors="pt")
+embedding = model.encode(tokens.to("cuda"))
+print(embedding.shape)  # (1, 1536)
+```
+
+Token-level embeddings for finer-grained analysis:
+
+```python
+token_emb, timestamps = model.encode_tokens(tokens.to("cuda"))
+# token_emb: (T, 1536); timestamps: (T,) in seconds
+```
+
+## Intended Use
+
+This model is released for non-commercial research purposes. It is designed for MIDI-based downstream analysis and is not intended as a general-purpose generative model. Please refer to the paper for benchmark protocols and evaluation guidelines.
+
+## Citation
+
+```bibtex
+@inproceedings{zhou2026majeppa,
+  title  = {MAJEPPA: Morphing and Assessing in a Unified Piano Performance Space},
+  author = {Zhou, Jinwen and Zhang, Huan and Zhai, Weixi and Liang, Jinhua and Hogg, Aidan O. T. and Dixon, Simon},
+  booktitle = {Proc. International Society for Music Information Retrieval Conference (ISMIR)},
+  year   = {2026}
+}
+```