music: extreme-fidelity synthesis of musical elements

Extreme-fidelity synthesis of musical elements, based on the MASS framework.

pip install -U music

📖 Tutorial · API reference · Full changelog

This is the first release with a test suite, type checking, linting and rendered API documentation behind it — and, consequently, the release in which most of the package was found to be broken and fixed.

What was wrong

Roughly thirty routines returned a wrong answer or raised on their own documented defaults. The ones worth naming:

• localize_linear() was never implemented — it raised NotImplementedError. It now computes the position sample by sample and, from it, the interaural time and intensity differences, with fractional delays interpolated rather than rounded.
• trill() and stretches() raised unconditionally, on an import cycle and on abandoned scratch code respectively.
• fir() applied the response it was given. It convolved with the magnitudes rather than their inverse transform, so a flat response — "pass everything unchanged" — was a boxcar moving average instead of the identity.
• Sixteen sites detected an argument with type(x) in (np.ndarray, list), so a tuple or an ndarray subclass was silently discarded and the caller got a default-duration envelope back instead of their own audio. No error, just the wrong sound.
• write_wav_* was broken at 8- and 64-bit depth, and WAV round trips were off by one LSB on every file the package had ever written: the writer scaled by 2**(b-1) - 1 while the reader divided by 2**(b-1).
• normalize_mono/stereo returned NaN for any constant signal, and the stereo path silently corrupted a mono vector by reading its first two samples as the two channels.
• PlainChanges(n) returned a fraction of the peal above five bells — 120 rows of 720 at six, 224 of 40320 at eight.
• The waveform tables were three drifted copies of the same four definitions, disagreeing at the triangle's peak sample; the triangle, which is the default table for every note, never reached full amplitude.

Four fixes change rendered output

All are corrections — the previous behaviour was wrong in each case — but a render from this version will not be byte-identical to one from 1.0.1. The complete peal, the exact waveform tables, unity-gain WAV round trips, and fir(). See the changelog's Note for anyone upgrading for the details and for how to ask for the old shorter peal.

What is around it now

• 481 tests at 100% coverage, enforced in CI
• mypy clean on Python 3.10 through 3.13, with check_untyped_defs on — it had been off, which made type checking vacuous over 83% of the code
• ruff clean at PEP 8's 79 columns
• Every docstring converted to numpydoc, and the API reference published at ttm.github.io/music, built with warnings as errors
• A tutorial, whose every code block is executed by the test suite
• A Sequencer, for scheduling notes onto a timeline
• 3 Dependabot alerts cleared

Citing

If you use this package, please cite the article it implements:

Fabbri, R., Vieira da Silva Junior, V., Pessotti, A. C. S., Corrêa, D. C., & Oliveira Jr., O. N. Musical elements in the discrete-time representation of sound. arXiv:1412.6853 (2017).

CITATION.cff in the repository gives GitHub's "Cite this repository" button the same thing in machine-readable form.