mp3peaks 0.1.0__tar.gz

mp3peaks-0.1.0/Cargo.lock

@@ -0,0 +1,243 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "bitflags"
+version = "2.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
+
+[[package]]
+name = "bytemuck"
+version = "1.25.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "lazy_static"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "20870f649af7073d53e38067b2a84312175d56ea15217e1b15bc83506ec50afb"
+
+[[package]]
+name = "libc"
+version = "0.2.191"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
+
+[[package]]
+name = "log"
+version = "0.4.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d15f86d12da44cd8d4ec3c73984537eb7f4cadcb9776a575a0a8a05ca11005c"
+
+[[package]]
+name = "mp3peaks"
+version = "0.1.0"
+dependencies = [
+ "pyo3",
+ "symphonia",
+]
+
+[[package]]
+name = "num-complex"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "229ca13b8a15bb0d1487b81ab975bfcd97513416499a8312011b6036e42e0de4"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "70130e2b6dd1ee589a8788026a429561ca5c40fa7a2fa7914c2282eddae24700"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e7ff73c555c286d212d4ce7e5fbda845a973c4f61bd5f160f5f2c3c2a04d1c4"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c46d2e5862c7bb8207e3b639f713dda3c499933444784154c11d013c5a691b60"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.30.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38b89f066f2ae72a2aef52d1537ca2fcd104440ebfadee06e97aa90738a25b9b"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "regex-lite"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cab834c73d247e67f4fae452806d17d3c7501756d98c8808d7c9c7aa7d18f973"
+
+[[package]]
+name = "smallvec"
+version = "1.16.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0d5d4b1981b8bbbb7aed204cae5726d683d5d6ac7e74ec54122ea28f315e7c8"
+
+[[package]]
+name = "symphonia"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7edef6a96b696d4e0cab5ee9ebb7ca155ed95f30a6b45bbb8b97d2727f02424"
+dependencies = [
+ "lazy_static",
+ "symphonia-bundle-mp3",
+ "symphonia-core",
+ "symphonia-metadata",
+]
+
+[[package]]
+name = "symphonia-bundle-mp3"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "98ea5ffc8716bff677dfb3b01b420c7b758de901a72b8c330bf2040ab74b4add"
+dependencies = [
+ "lazy_static",
+ "log",
+ "symphonia-core",
+]
+
+[[package]]
+name = "symphonia-core"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "01c412864d599d4750d0c3d684d7e093ec05e5309681ef5252cc1096a437f6e0"
+dependencies = [
+ "bitflags",
+ "bytemuck",
+ "lazy_static",
+ "log",
+ "num-complex",
+ "smallvec",
+]
+
+[[package]]
+name = "symphonia-metadata"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83713a97705d77bdef7cdbc0768fd6e5a54e4cd7e48d60a806ae85639e2c87c6"
+dependencies = [
+ "lazy_static",
+ "log",
+ "regex-lite",
+ "smallvec",
+ "symphonia-core",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"

mp3peaks-0.1.0/Cargo.toml

@@ -0,0 +1,41 @@
+[package]
+name = "mp3peaks"
+# The single source of the version: pyproject.toml reads it from here.
+version = "0.1.0"
+edition = "2024"
+rust-version = "1.99"
+description = "audiowaveform-compatible peak waveforms for MP3s, decoded in memory-safe Rust, for Python"
+license = "MIT"
+repository = "https://github.com/monty5811/mp3peaks"
+readme = "README.md"
+keywords = ["audio", "waveform", "mp3", "peaks", "python"]
+categories = ["multimedia::audio"]
+# Only the Python package is released. The crate is a cdylib with nothing to
+# offer Rust users yet, so it stays off crates.io.
+publish = false
+# What goes in the sdist (maturin uses cargo's package list). Leaves out the
+# tests, dev scripts and CI config.
+include = [
+    "/Cargo.toml",
+    "/Cargo.lock",
+    "/LICENSE",
+    "/README.md",
+    "/THIRD_PARTY_NOTICES.md",
+    "/pyproject.toml",
+    "/src/**",
+    "/mp3peaks.pyi",
+]
+
+[lib]
+name = "mp3peaks"
+crate-type = ["cdylib"]
+
+[profile.release]
+lto = true
+codegen-units = 1
+
+[dependencies]
+# extension-module is switched on by maturin (pyproject.toml) rather than here,
+# so `cargo test` can link a test binary.
+pyo3 = { version = "0.30.1", features = ["abi3-py311"] }
+symphonia = { version = "0.6.1", default-features = false, features = ["mp3"] }

mp3peaks-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The mp3peaks authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mp3peaks-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: mp3peaks
+Version: 0.1.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Typing :: Typed
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Summary: audiowaveform-compatible peak waveforms for MP3s, decoded in memory-safe Rust (symphonia)
+Keywords: audio,waveform,mp3,peaks,audiowaveform,peaks.js
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/monty5811/mp3peaks/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/monty5811/mp3peaks
+Project-URL: Issues, https://github.com/monty5811/mp3peaks/issues
+Project-URL: Source, https://github.com/monty5811/mp3peaks
+
+# mp3peaks
+
+[`audiowaveform`](https://github.com/bbc/audiowaveform)-compatible peak
+waveforms for MP3 files, from a `pip install`. The MP3 is decoded in
+memory-safe Rust by [symphonia](https://github.com/pdeljanov/Symphonia), and
+the result is the JSON that `audiowaveform --output-format json` writes, as
+read by [peaks.js](https://github.com/bbc/peaks.js) and
+[waveform-data.js](https://github.com/bbc/waveform-data.js).
+
+```python
+from mp3peaks import compute_waveform
+
+with open("talk.mp3", "rb") as f:
+    waveform = compute_waveform(f.read(), number_of_points=256, bits=8)
+
+# {"version": 2, "channels": 1, "sample_rate": 44100, "samples_per_pixel": 31556,
+#  "bits": 8, "length": 256, "data": [-3, 4, -41, 38, ...]}
+```
+
+```
+pip install mp3peaks
+```
+
+## Why
+
+- **No system packages.** Wheels are self-contained and have no Python
+  dependencies. There's no binary to install and no subprocess or temp files.
+- **Memory-safe decoding.** If you build waveforms from files people upload,
+  those bytes never reach a C decoder (libmad in `audiowaveform`, or FFmpeg).
+- **Fast.** On 50 real recordings it took a median of 1.83s per file, against
+  2.70s for `audiowaveform` (see below). The GIL is released while it decodes,
+  so threads run in parallel.
+
+It was built for [Yet Another Sermon Host](https://yetanothersermon.host) to
+replace calls to the `audiowaveform` binary, and is published in case it's
+useful to anyone else. It's an independent project, not affiliated with the
+BBC or the `audiowaveform` authors.
+
+## Scope
+
+It does one thing, deliberately:
+
+- **Input:** MP3 only, as bytes in memory.
+- **Output:** `audiowaveform` JSON, format version 2, as a Python dict. Always
+  one channel: stereo is mixed down to mono the way `audiowaveform` does it.
+- **Resolution:** 8 or 16 bits. You choose the number of points, not a zoom
+  level or samples per pixel.
+
+There's no binary `.dat` output, no image rendering, no other input formats and
+no multi-channel output. If you need any of those, use `audiowaveform`.
+
+## API
+
+```python
+compute_waveform(
+    data: bytes,
+    *,
+    number_of_points: int = 256,
+    bits: int = 8,               # 8 or 16
+    duration: float | None = None,
+) -> dict
+```
+
+- `number_of_points` is between 1 and 16,777,216 (2^24).
+- `duration` (in seconds) sizes the buckets:
+  `samples_per_pixel = ceil(sample_rate * duration / number_of_points)`,
+  rounded up so the buckets always cover the whole duration. Without it, the
+  stream's own duration is used. If given, it must be positive and finite.
+  Passing a known duration gives the exact number of points even when the
+  MP3's header is wrong.
+- Every decoded sample lands in a bucket, so a few points more than
+  `number_of_points` usually come back: the decoded audio runs past the
+  duration by the encoder delay and padding. If it runs past by much more
+  (a `duration` far too short), neighbouring buckets are merged in pairs,
+  doubling `samples_per_pixel`, so at most `2 * (number_of_points + 1)`
+  points come back.
+- Encoder delay and padding are decoded rather than trimmed, as
+  `audiowaveform` (libmad) does, so the peaks line up with its output.
+- A truncated file gives a waveform of the part that decodes. Corrupt frames
+  are skipped. A stream that changes channel count partway (mono to stereo,
+  say) decodes to the end. One that changes sample rate raises
+  `WaveformError`.
+- Raises `mp3peaks.WaveformError` if the bytes can't be decoded or hold
+  no audio, and `ValueError` for bad arguments.
+
+Type hints ship with the package.
+
+## Compared with audiowaveform
+
+The values follow `audiowaveform`'s rules (see `src/lib.rs`): each channel is
+rounded to 16 bits, channels are averaged with truncation, and 8-bit values
+are divided by 256 rounding toward zero.
+
+On 50 real speech recordings from 2008-2026, covering 7 channel and sample-rate
+combinations (41 of them stereo):
+
+| | Decoder | Median per file | vs audiowaveform 1.10.1 |
+|---|---|---|---|
+| audiowaveform 1.10.1 (C++) | libmad | 2.70s | - |
+| mp3peaks | symphonia | 1.83s | 45/50 within ±1 (median mean difference 0.002) |
+
+The other 5 files are MPEG-2 files that use intensity stereo. libmad decodes
+those about 20% too quietly. symphonia, FFmpeg and mpg123 all agree with each
+other on them, so this package's output is the correct one there.
+
+`scripts/compare_with_audiowaveform.py` runs that comparison. It isn't part of
+the package, and needs the `audiowaveform` binary and some MP3s of your own:
+
+    make compare AUDIOWAVEFORM=/path/to/audiowaveform ARGS="path/to/mp3s"
+
+## Platforms
+
+Wheels are built for CPython's stable ABI, so one wheel per platform covers
+Python 3.11 and later:
+
+- Linux x86_64 and aarch64 (`manylinux_2_17`, glibc 2.17+)
+- macOS arm64 and x86_64
+- Windows x86_64
+
+Anywhere else, pip builds it from the sdist, which needs a Rust toolchain
+(1.99+).
+
+## Support
+
+This is maintained for its original use. Bug reports are
+welcome, especially files it decodes differently from other decoders, but
+there's no roadmap and no promise of support. Requests for more formats or
+options will probably be declined to keep the scope small.
+
+## Development
+
+Needs cargo (Rust 1.99+) and [uv](https://docs.astral.sh/uv/).
+
+    make check     # rustfmt, clippy, cargo test, ruff, pytest, notices up to date
+    make develop   # rebuild into .venv after changing src/
+    make build     # a manylinux wheel for this machine, via zig
+    make sdist     # the source distribution
+    make notices   # regenerate THIRD_PARTY_NOTICES.md after changing dependencies
+
+`requirements-dev.txt` is only for the tests and scripts. PyAV is there to
+encode test MP3s and to read stream info in the comparison script, not to
+build waveforms.
+
+### Releasing
+
+1. Bump `version` in `Cargo.toml` (the only place it's set) and add a
+   `CHANGELOG.md` entry.
+2. Commit, then tag the commit `v<version>` (for example `v0.1.0`) and push
+   the tag.
+3. `.github/workflows/release.yml` checks the tag matches the version, builds
+   the wheels and sdist, smoke-tests each wheel, and publishes to PyPI with
+   trusted publishing. No API token is stored anywhere.
+
+## License
+
+MIT, see `LICENSE`. The wheels include symphonia, which is MPL-2.0, and PyO3
+and other crates under MIT or Apache-2.0. Their licenses are in
+`THIRD_PARTY_NOTICES.md`, which ships in every wheel and the sdist.
+

mp3peaks-0.1.0/README.md

@@ -0,0 +1,158 @@
+# mp3peaks
+
+[`audiowaveform`](https://github.com/bbc/audiowaveform)-compatible peak
+waveforms for MP3 files, from a `pip install`. The MP3 is decoded in
+memory-safe Rust by [symphonia](https://github.com/pdeljanov/Symphonia), and
+the result is the JSON that `audiowaveform --output-format json` writes, as
+read by [peaks.js](https://github.com/bbc/peaks.js) and
+[waveform-data.js](https://github.com/bbc/waveform-data.js).
+
+```python
+from mp3peaks import compute_waveform
+
+with open("talk.mp3", "rb") as f:
+    waveform = compute_waveform(f.read(), number_of_points=256, bits=8)
+
+# {"version": 2, "channels": 1, "sample_rate": 44100, "samples_per_pixel": 31556,
+#  "bits": 8, "length": 256, "data": [-3, 4, -41, 38, ...]}
+```
+
+```
+pip install mp3peaks
+```
+
+## Why
+
+- **No system packages.** Wheels are self-contained and have no Python
+  dependencies. There's no binary to install and no subprocess or temp files.
+- **Memory-safe decoding.** If you build waveforms from files people upload,
+  those bytes never reach a C decoder (libmad in `audiowaveform`, or FFmpeg).
+- **Fast.** On 50 real recordings it took a median of 1.83s per file, against
+  2.70s for `audiowaveform` (see below). The GIL is released while it decodes,
+  so threads run in parallel.
+
+It was built for [Yet Another Sermon Host](https://yetanothersermon.host) to
+replace calls to the `audiowaveform` binary, and is published in case it's
+useful to anyone else. It's an independent project, not affiliated with the
+BBC or the `audiowaveform` authors.
+
+## Scope
+
+It does one thing, deliberately:
+
+- **Input:** MP3 only, as bytes in memory.
+- **Output:** `audiowaveform` JSON, format version 2, as a Python dict. Always
+  one channel: stereo is mixed down to mono the way `audiowaveform` does it.
+- **Resolution:** 8 or 16 bits. You choose the number of points, not a zoom
+  level or samples per pixel.
+
+There's no binary `.dat` output, no image rendering, no other input formats and
+no multi-channel output. If you need any of those, use `audiowaveform`.
+
+## API
+
+```python
+compute_waveform(
+    data: bytes,
+    *,
+    number_of_points: int = 256,
+    bits: int = 8,               # 8 or 16
+    duration: float | None = None,
+) -> dict
+```
+
+- `number_of_points` is between 1 and 16,777,216 (2^24).
+- `duration` (in seconds) sizes the buckets:
+  `samples_per_pixel = ceil(sample_rate * duration / number_of_points)`,
+  rounded up so the buckets always cover the whole duration. Without it, the
+  stream's own duration is used. If given, it must be positive and finite.
+  Passing a known duration gives the exact number of points even when the
+  MP3's header is wrong.
+- Every decoded sample lands in a bucket, so a few points more than
+  `number_of_points` usually come back: the decoded audio runs past the
+  duration by the encoder delay and padding. If it runs past by much more
+  (a `duration` far too short), neighbouring buckets are merged in pairs,
+  doubling `samples_per_pixel`, so at most `2 * (number_of_points + 1)`
+  points come back.
+- Encoder delay and padding are decoded rather than trimmed, as
+  `audiowaveform` (libmad) does, so the peaks line up with its output.
+- A truncated file gives a waveform of the part that decodes. Corrupt frames
+  are skipped. A stream that changes channel count partway (mono to stereo,
+  say) decodes to the end. One that changes sample rate raises
+  `WaveformError`.
+- Raises `mp3peaks.WaveformError` if the bytes can't be decoded or hold
+  no audio, and `ValueError` for bad arguments.
+
+Type hints ship with the package.
+
+## Compared with audiowaveform
+
+The values follow `audiowaveform`'s rules (see `src/lib.rs`): each channel is
+rounded to 16 bits, channels are averaged with truncation, and 8-bit values
+are divided by 256 rounding toward zero.
+
+On 50 real speech recordings from 2008-2026, covering 7 channel and sample-rate
+combinations (41 of them stereo):
+
+| | Decoder | Median per file | vs audiowaveform 1.10.1 |
+|---|---|---|---|
+| audiowaveform 1.10.1 (C++) | libmad | 2.70s | - |
+| mp3peaks | symphonia | 1.83s | 45/50 within ±1 (median mean difference 0.002) |
+
+The other 5 files are MPEG-2 files that use intensity stereo. libmad decodes
+those about 20% too quietly. symphonia, FFmpeg and mpg123 all agree with each
+other on them, so this package's output is the correct one there.
+
+`scripts/compare_with_audiowaveform.py` runs that comparison. It isn't part of
+the package, and needs the `audiowaveform` binary and some MP3s of your own:
+
+    make compare AUDIOWAVEFORM=/path/to/audiowaveform ARGS="path/to/mp3s"
+
+## Platforms
+
+Wheels are built for CPython's stable ABI, so one wheel per platform covers
+Python 3.11 and later:
+
+- Linux x86_64 and aarch64 (`manylinux_2_17`, glibc 2.17+)
+- macOS arm64 and x86_64
+- Windows x86_64
+
+Anywhere else, pip builds it from the sdist, which needs a Rust toolchain
+(1.99+).
+
+## Support
+
+This is maintained for its original use. Bug reports are
+welcome, especially files it decodes differently from other decoders, but
+there's no roadmap and no promise of support. Requests for more formats or
+options will probably be declined to keep the scope small.
+
+## Development
+
+Needs cargo (Rust 1.99+) and [uv](https://docs.astral.sh/uv/).
+
+    make check     # rustfmt, clippy, cargo test, ruff, pytest, notices up to date
+    make develop   # rebuild into .venv after changing src/
+    make build     # a manylinux wheel for this machine, via zig
+    make sdist     # the source distribution
+    make notices   # regenerate THIRD_PARTY_NOTICES.md after changing dependencies
+
+`requirements-dev.txt` is only for the tests and scripts. PyAV is there to
+encode test MP3s and to read stream info in the comparison script, not to
+build waveforms.
+
+### Releasing
+
+1. Bump `version` in `Cargo.toml` (the only place it's set) and add a
+   `CHANGELOG.md` entry.
+2. Commit, then tag the commit `v<version>` (for example `v0.1.0`) and push
+   the tag.
+3. `.github/workflows/release.yml` checks the tag matches the version, builds
+   the wheels and sdist, smoke-tests each wheel, and publishes to PyPI with
+   trusted publishing. No API token is stored anywhere.
+
+## License
+
+MIT, see `LICENSE`. The wheels include symphonia, which is MPL-2.0, and PyO3
+and other crates under MIT or Apache-2.0. Their licenses are in
+`THIRD_PARTY_NOTICES.md`, which ships in every wheel and the sdist.