Skip to main content

musegauge

PyPI Licence Python

Score a folder of generated music with several existing metrics in one command.

Needs: a GPU, about 28 GB of free disk, Linux x86_64. Tested on Linux x86_64 only. Other systems are not tested.

musegauge runs these existing metrics:

Metric Tool
Frechet Audio Distance fadtk
Kernel Audio Distance kadtk
CLAP text-audio score laion-clap
Audiobox Aesthetics Audiobox Aesthetics

Each metric runs in its own Python environment. The tool builds these by itself with uv, so metrics 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.4. On PyPI. Source: https://github.com/AMAAI-Lab/musegauge. Container image: ghcr.io/aroy1990-dev/musegauge.

Authors

musegauge was created and is maintained by Abhinaba Roy (@aroy1990-dev), AMAAI Lab, Singapore University of Technology and Design (SUTD). Contact: abhinabaroy1990@gmail.com

Quick start

Docker (published image)

No install is needed beyond Docker. Python, uv and musegauge are inside the image.

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

The image 0.1.2 was built and tested on 2026-10-06 and 2026-10-07 on a Linux x86_64 machine with Docker 27.3.1. doctor, an offline run (--network none --no-fetch) and GPU use all passed. The tests found a cache-volume bug, which is fixed in 0.1.2. See docker/README.md and docs/PROGRESS.md (M7).

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

First run

The first run builds the plugin environments and downloads the model weights into the cache folder (~/.cache/musegauge, or /cache in the container). For all four plugins this is about 24 GB of environments and 3.7 GB of weights. musegauge setup --all --fetch-weights does this ahead of time. All install paths are in docs/INSTALL.md.

Try it on synthetic audio

From a fresh clone, in a new shell:

git clone https://github.com/AMAAI-Lab/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, .ogg or .mp3 files (--generated DIR, with optional --prompts FILE), or a clips file in JSON lines (--manifest FILE).
  • Metrics: a suite (--suite t2m-basic, the default, or t2m-full) or --metrics ID,ID. musegauge list shows them. musegauge info METRIC_ID shows a definition and its licences.
  • Reference: --reference DIR or --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, so 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-fetch blocks 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. Run musegauge setup --fetch-weights first. run --no-fetch never 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 as NETWORK_ERROR.
  • Licences of the metrics. Every metric's commercial_ok is unknown, so every run warns UNKNOWN_LICENCE. --commercial refuses such metrics. Details: docs/LICENCES.md.
  • Comparing numbers. Numbers are comparable only with the same metric ids, reference set, clip length, device and thread setting. fad_inf is random from run to run. See docs/METRICS.md.
  • Shared machines. --threads N limits CPU threads in each plugin (docs/INSTALL.md).

Documentation

File Contents
docs/INSTALL.md Install paths, offline use, disk space, GPU driver, threads
docs/METRICS.md What each metric is and where numbers can differ
docs/LICENCES.md Code, weights and data licence status per metric
docs/plugins/ One page per plugin: commands, files, downloads, differences from upstream
docs/PLUGIN_GUIDE.md How to write a plugin
docs/UPSTREAM_NOTES.md Problems found in the upstream tools
docs/TESTING_REAL_PLUGINS.md Golden tests with the real tools
docs/DECISIONS.md Choices made, and every change from the build spec
docs/VERIFIED_FACTS.md, docs/PROGRESS.md, docs/BUILD_REPORT.md Checks and build record

Citation

If you use musegauge in your work, please cite it:

@software{musegauge,
  author  = {Roy, Abhinaba},
  title   = {musegauge: scoring generated music with existing metrics in one command},
  year    = {2026},
  version = {0.1.4},
  url     = {https://github.com/AMAAI-Lab/musegauge}
}

Licence

Copyright 2026 Abhinaba Roy.

Licensed under the Apache License, Version 2.0. See LICENSE for the full text and NOTICE for the attribution notice. You may use, change and share this code under those terms, but you must keep the copyright and NOTICE text.

The metric packages and model weights that the plugins download have their own licences. See docs/LICENCES.md.

Metadata

Release files for musegauge 0.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for musegauge 0.1.4
File Size Uploaded Provenance Actions
musegauge-0.1.4.tar.gz 520.3 kB Without provenance Details for musegauge-0.1.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for musegauge 0.1.4
File Interpreter ABI Platform Actions
musegauge-0.1.4-py3-none-any.whl Python 3 none any Details for musegauge-0.1.4-py3-none-any.whl

Total release size: 856.7 kB

Release files / musegauge-0.1.4.tar.gz

Download URL musegauge-0.1.4.tar.gz
Size 520.3 kB
Tags Source
SHA-256 checksum
How to use checksums
be4d3f73d8c8bff1f7905d8ec379714c93f534579e54e154db8d8b246d5baf64
BLAKE2b-256 checksum
How to use checksums
63a48c28c13ced3f0922ed937c2206f713066a6b6b1cc1625698fca901bec3f4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.4

Release files / musegauge-0.1.4-py3-none-any.whl

Download URL musegauge-0.1.4-py3-none-any.whl
Size 336.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2c93115ca248524ebe91372e2617c9ef5a40ab37ec5df862ed6cd0585d793497
BLAKE2b-256 checksum
How to use checksums
e9f037aa872f8f2e1ec196604c6f8952eb6d299423e04463a91d2bad17d01f4d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.9.4

Security for musegauge 0.1.4

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page