README.md

---
title: MuQ-MuLan
emoji: 🎧
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.28.0
python_version: '3.12'
app_file: app.py
pinned: false
license: cc-by-nc-4.0
short_description: Rank music descriptions against an audio clip
---

# MuQ-MuLan Music-Text Similarity

A HARP-compatible deployment of MuQ-MuLan for comparing a music clip with
candidate text descriptions. It can support workflows such as tagging,
searching a sample library, or choosing the description that best matches a
piece of music.

The Space loads the official MuQ-MuLan-large checkpoint from Hugging Face.
Model files are downloaded at runtime and cached by the Space.

## Inputs

- One music audio clip between 10 and 60 seconds
- One to eight candidate descriptions, one per line

Audio is converted to mono and resampled to 24 kHz. MuQ-MuLan processes
10-second windows and averages their embeddings for longer clips. Candidate
descriptions should be written in English.

## Output

A JSON file containing the candidate descriptions in descending similarity
order. Scores are cosine similarities from -1 to 1, not calibrated
probabilities.

## Sources

See [SOURCES.md](SOURCES.md) for the model, source revision, license, and
associated paper.

## License

The upstream source code is MIT licensed. The MuQ-MuLan model weights are
released under CC BY-NC 4.0, so this deployment is intended for
non-commercial use.