musegauge
Needs a GPU, about 28 GB free disk, Linux x86_64.
musegauge scores a folder of generated music with several existing metrics in one command:
Frechet Audio Distance (fadtk), Kernel Audio Distance (kadtk), a CLAP text-audio score
(laion-clap) and Audiobox Aesthetics. Each metric runs in its own Python environment, which the
tool builds by itself with uv, so tools that need different torch versions can be used together.
One run writes a results.json and a short report card for a paper appendix.
Version 0.1.2. Source: https://github.com/aroy1990-dev/musegauge. On PyPI. Container image:
ghcr.io/aroy1990-dev/musegauge.
Tested on Linux x86_64 only. Other systems are not tested.
Quick start
Docker (no install beyond Docker itself — Python, uv and musegauge are inside the image;
published image ghcr.io/aroy1990-dev/musegauge:0.1.2, built and tested 2026-10-06/07 on a
Linux x86_64 machine with Docker 27.3.1 — doctor, an offline --network none --no-fetch
run and GPU use all passed; the cache-volume bug the tests uncovered was fixed in 0.1.2; see
docker/README.md and docs/PROGRESS.md M7):
docker pull ghcr.io/aroy1990-dev/musegauge:0.1.2
docker run --rm --gpus all -v "$PWD/my_audio:/data/audio:ro" -v musegauge-cache:/cache \
-v "$PWD/out:/out" ghcr.io/aroy1990-dev/musegauge:0.1.2 \
run --generated /data/audio --out /out
pip (Python 3.10 or newer):
python3 -m venv .venv && source .venv/bin/activate
pip install musegauge
musegauge doctor
musegauge run --generated ./my_audio --prompts prompts.csv --out ./out
If python3 -m venv fails because ensurepip is missing (a Debian or Ubuntu system Python
without the python3-venv package), use another Python, or uv venv.
uvx (no install; needs uv):
uvx musegauge run --generated ./my_audio --out ./out
uvx --from . musegauge --version # from a clone
Docker, build it yourself from a clone (docker/README.md has the full commands and the
published-image alternative):
uv build && docker build -f docker/Dockerfile --target slim -t musegauge:slim .
docker run --rm --gpus all -v "$PWD/my_audio:/data/audio:ro" -v musegauge-cache:/cache \
-v "$PWD/out:/out" musegauge:slim run --generated /data/audio --out /out
The first run builds the plugin environments and downloads the model weights into the cache
folder (~/.cache/musegauge, or /cache in the container): about 24 GB of environments and
3.7 GB of weights for all four plugins. musegauge setup --all --fetch-weights does this ahead of
time. All install paths: docs/INSTALL.md.
Try it on synthetic audio
From a fresh clone, in a new shell:
git clone https://github.com/aroy1990-dev/musegauge.git && cd musegauge
python3 -m venv .venv && source .venv/bin/activate
pip install .
python tests/make_fixtures.py fixtures
musegauge run --generated fixtures/gen_small --metrics aesthetics.audiobox@1 --out out
cat out/report.md
tests/make_fixtures.py writes synthetic sine-and-noise clips (no real music). The first run
builds the Audiobox environment (about 5 GB) and downloads its weights (about 400 MB). Scores on
synthetic audio mean nothing about quality.
Input and output
- Input: a folder of
.wav,.flac,.oggor.mp3files (--generated DIR, with optional--prompts FILE), or a clips file in JSON lines (--manifest FILE). - Metrics: a suite (
--suite t2m-basic, the default, ort2m-full) or--metrics ID,ID.musegauge listshows them;musegauge info METRIC_IDshows a definition and its licences. - Reference:
--reference DIRor--reference bundled:fma_pop(FAD only). - Output folder:
results.json,report.md,per_clip/,logs/,requests/,responses/.
One example output, from docs/examples/report.md (synthetic audio; the numbers mean nothing):
| Metric | Score | Mean ± std | 95% CI | n | Status |
| --- | --- | --- | --- | --- | --- |
| fad.vggish@1 | fad | 25.369 | — | — | ok |
| fad.clap-laion-music@1 | fad | 1.274 | — | — | ok |
| clapscore.laion-music@1 | clap_cosine | 0.232 ± 0.059 | [0.200, 0.262] | 12 | ok |
| aesthetics.audiobox@1 | CE | 2.405 ± 0.557 | [2.115, 2.705] | 12 | ok |
| aesthetics.audiobox@1 | PQ | 6.228 ± 0.827 | [5.757, 6.655] | 12 | ok |
Things to know
- Offline use.
--no-fetchblocks downloads from libraries that honour the proxy settings, and sets the Hugging Face offline variables. It is best effort, not a guarantee; for a hard guarantee cut the network outside the tool (for example a container with no network). It was tested only with the proxy method, not with a truly blocked network. Runmusegauge setup --fetch-weightsfirst;run --no-fetchnever builds an environment. - Network without
--no-fetch. FAD and KAD with VGGish contact github.com on every run (torch.hub). An HTTP error there is reported asNETWORK_ERROR. - Licences. Every metric's
commercial_okisunknown, so every run warnsUNKNOWN_LICENCE.--commercialrefuses such metrics. Details:docs/LICENCES.md. - Comparability. Numbers are comparable only with the same metric ids, reference set, clip
length, device and thread setting.
fad_infis random from run to run. Seedocs/METRICS.md. - Shared machines.
--threads Nlimits CPU threads in each plugin (docs/INSTALL.md).
Documentation
docs/INSTALL.md: install paths, offline use, disk space, GPU driver, threadsdocs/METRICS.md: what each metric is and where numbers can differdocs/LICENCES.md: code, weights and data licence status per metricdocs/plugins/: one page per plugin (commands, files, downloads, differences from upstream)docs/PLUGIN_GUIDE.md: how to write a plugindocs/UPSTREAM_NOTES.md: problems found in the upstream toolsdocs/TESTING_REAL_PLUGINS.md: golden tests with the real toolsdocs/DECISIONS.md: choices made, and every change from the build specdocs/VERIFIED_FACTS.md,docs/PROGRESS.md,docs/BUILD_REPORT.md: checks and build record
Licence of this code
Apache License 2.0 (LICENSE; decision D2). The metric packages and model weights that the
plugins download have their own licences: docs/LICENCES.md.
Metadata
Release files for musegauge 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| musegauge-0.1.2.tar.gz | 15.8 MB | Without provenance | Details for musegauge-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| musegauge-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for musegauge-0.1.2-py3-none-any.whl |
Total release size: 16.1 MB
Release files / musegauge-0.1.2.tar.gz
| Download URL | musegauge-0.1.2.tar.gz |
|---|---|
| Size | 15.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a3910680ae5d0c752c0d31883554b31786c4250a8144e0bd9d9ffe80c368d267
|
|
BLAKE2b-256 checksum How to use checksums |
38f6cf88c2190a402297af39b7a9b1673d60edfc4c44771b25c5bc8c982a5560
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / musegauge-0.1.2-py3-none-any.whl
| Download URL | musegauge-0.1.2-py3-none-any.whl |
|---|---|
| Size | 335.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
838cecca65739d502b4012ae8e73b6da6e85489bc193bfdc16e1779002a3a397
|
|
BLAKE2b-256 checksum How to use checksums |
2898ce3f5d9cdbfee76aace1f2cb55e2a8053a68450c6627f28bbb70fd8074ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for musegauge 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.