pianistprogrammer/abc2vec-model

ABC2Vec: Self-Supervised Representation Learning for Irish Folk Music

This is the official pre-trained ABC2Vec model from the paper:

"ABC2Vec: Self-Supervised Representation Learning for Irish Folk Music"

Model Description

ABC2Vec is a self-supervised Transformer encoder that learns dense, semantically meaningful embeddings from ABC notation (symbolic music format). It is specifically designed for Irish traditional folk music and trained on 211,524 tunes.

Key Features

• 🎵 Purpose-built for folk music - Addresses transposition equivalence, modal tonality, and variant detection
• 🔄 Transposition Invariance - Novel TI objective for pitch-invariant representations
• 📊 Bar-level Patchification - 16× sequence length reduction for efficiency
• 🎯 Self-supervised - No text annotations or audio required
• ⚡ Efficient - Trained in 18 hours on Apple M4 Mac

Model Architecture

• Layers: 6
• Hidden Size (d_model): 256
• Attention Heads: 8
• FFN Size (d_ff): 1024
• Embedding Size: 128
• Vocabulary Size: 98
• Max Bars: 64
• Max Bar Length: 64
• Parameters: ~5M

Training Details

• Dataset: 211,524 Irish traditional tunes (IrishMAN corpus)
• Training Objectives:
  • Masked Music Modeling (MMM)
  • Transposition Invariance (TI) contrastive learning
• Training Steps: 40,000 steps (40 epochs)
• Final Validation Loss: 2.36
• Hardware: Apple M4 Mac (48GB unified memory)
• Training Time: ~18 hours

Performance

Task	Accuracy	Notes
Tune Type Classification	78.4% ± 1.2%	6 classes (jig, reel, polka, etc.)
Mode Classification	78.8% ± 1.6%	4 classes (major, minor, dorian, mixolydian)
Key Root (Linear Probe)	62.3% ± 0.9%	8 most common keys
Tune Length (Linear Probe)	89.5% ± 0.7%	3 classes (short, medium, long)

Usage

import torch
import json
from pathlib import Path

# Load model configuration
config_path = "model_config.json"
with open(config_path) as f:
    config_dict = json.load(f)

# Initialize model (you'll need the ABC2Vec model code)
from abc2vec.core.model import ABC2VecModel
from abc2vec.core.model.encoder import ABC2VecConfig

config = ABC2VecConfig(**config_dict)
model = ABC2VecModel(config)

# Load pre-trained weights
checkpoint = torch.load("best_model.pt", map_location="cpu")
model.load_state_dict(checkpoint["model_state_dict"])
model.eval()

# Load vocabulary for tokenization
with open("vocab.json") as f:
    vocab_data = json.load(f)

# Extract embeddings for a tune
from abc2vec.core.tokenizer import ABCVocabulary, BarPatchifier

vocab = ABCVocabulary.load("vocab.json")
patchifier = BarPatchifier(
    vocab=vocab,
    max_bars=config.max_bars,
    max_bar_length=config.max_bar_length
)

# Example ABC tune
abc_tune = "M:6/8\nK:D\n|:A2A ABc|ded cBA|A2A ABc|ded cAG|"
patches = patchifier.patchify(abc_tune)

# Get embedding
with torch.no_grad():
    bar_indices = patches["bar_indices"].unsqueeze(0)
    char_mask = patches["char_mask"].unsqueeze(0)
    bar_mask = patches["bar_mask"].unsqueeze(0)

    embedding = model.get_embedding(bar_indices, char_mask, bar_mask)
    # embedding shape: (1, 128)

Code Repository

Full training code, evaluation scripts, and usage examples:

• GitHub: https://github.com/pianistprogrammer/ABC2VEC

Dataset

The processed dataset with train/validation/test splits:

• HuggingFace: https://huggingface.co/datasets/pianistprogrammer/abc2vec-irish-folk-dataset

Citation

If you use this model, please cite:

@article{abc2vec2025,
  title={ABC2Vec: Self-Supervised Representation Learning for Irish Folk Music},
  author={[Your Name]},
  journal={[Journal Name]},
  year={2025},
  note={Model: https://huggingface.co/pianistprogrammer/abc2vec-model}
}

License

MIT License

Acknowledgements

We thank The Session community for curating and maintaining the Irish traditional music archive that made this work possible.

Model Card Authors

[Your Name]

Contact

For questions or issues:

• GitHub: https://github.com/pianistprogrammer/ABC2VEC
• HuggingFace: https://huggingface.co/pianistprogrammer