audiowaveform 0.1.0

data/Cargo.toml

@@ -0,0 +1,28 @@
+[workspace]
+members = [
+    "crates/audiowaveform",
+    "crates/audiowaveform-cli",
+]
+exclude = ["bindings/ruby"]
+resolver = "2"
+
+[workspace.package]
+version = "1.10.3"
+edition = "2024"
+license = "GPL-3.0-or-later"
+repository = "https://github.com/Antti/audiowaveform"
+authors = ["Andrii Dmytrenko", "BBC Research and Development"]
+
+[workspace.dependencies]
+assert_cmd = "2.0"
+byteorder = "1.5"
+clap = { version = "4.5", features = ["derive"] }
+hound = "3.5"
+image = { version = "0.25", default-features = false, features = ["png"] }
+png = "0.17"
+predicates = "3.1"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+symphonia = { version = "0.5", default-features = false }
+tempfile = "3.14"
+thiserror = "2.0"

data/README.md

@@ -0,0 +1,255 @@
+# audiowaveform
+
+[![CI](https://github.com/Antti/audiowaveform/actions/workflows/rust.yml/badge.svg)](https://github.com/Antti/audiowaveform/actions/workflows/rust.yml)
+
+`audiowaveform` is a Rust library and CLI for generating waveform data from audio,
+serializing waveform files, rendering PNG waveform images, and transcoding audio
+to PCM16 WAV.
+
+This repository is the canonical home of the Rust rewrite:
+[github.com/Antti/audiowaveform](https://github.com/Antti/audiowaveform).
+
+It is a Rust rewrite of the original BBC `audiowaveform` project:
+[github.com/bbc/audiowaveform](https://github.com/bbc/audiowaveform).
+The original project was created by Chris Needham and contributors at BBC
+Research & Development.
+
+The repository's main workspace remains Rust-only:
+
+- `crates/audiowaveform`: reusable library crate
+- `crates/audiowaveform-cli`: thin `audiowaveform` command-line wrapper
+
+Ruby applications can use the native extension in `bindings/ruby` to generate
+waveforms in process through the same library crate.
+
+![Example Waveform](doc/example.png "Example Waveform")
+
+## Features
+
+- Decode AAC-LC, ALAC, MP1/MP2/MP3, WAV, FLAC, Ogg, AIFF, CAF, and audio in MP4/Matroska/WebM containers
+- Generate `.dat`, `.json`, and `.txt` waveform files
+- Render PNG waveform images in pure Rust
+- Transcode decoded audio or raw PCM input to PCM16 WAV
+- Use path-based, stream-based, or in-memory APIs from the library crate
+
+Opus and HE-AAC are unsupported by the current decoder. AAC-LC supports mono and
+stereo. Enabling a container such as WebM does not add unsupported codecs.
+AAC/MP4 decoding does not apply gapless trimming, so decoded audio and waveform
+duration can include encoder delay and padding.
+
+## Quick Start
+
+Build the workspace:
+
+```sh
+cargo build --workspace
+```
+
+Run the CLI:
+
+```sh
+cargo run -p audiowaveform-cli -- -i fixtures/test_file_stereo.wav -o output.dat
+```
+
+Install the CLI locally:
+
+```sh
+cargo install --path crates/audiowaveform-cli
+```
+
+Run the test suite:
+
+```sh
+cargo test --workspace
+```
+
+## Library Usage
+
+The Rust library has **no default features**. PCM/raw waveform generation,
+waveform serialization, and resampling are always available. Enable input formats
+and output capabilities explicitly:
+
+```toml
+[dependencies]
+audiowaveform = { version = "1.10.3", features = ["format-mp3", "format-m4a"] }
+```
+
+| Cargo feature | Capability |
+| --- | --- |
+| `format-aac` | AAC-LC in ADTS (`.aac`, `.adts`) |
+| `format-aiff` | PCM in AIFF/AIFF-C (`.aiff`, `.aif`, `.aifc`) |
+| `format-caf` | PCM and ALAC in CAF |
+| `format-flac` | FLAC |
+| `format-m4a` / `format-mp4` | AAC-LC, ALAC, MP3, and PCM in MP4/M4A/MOV containers |
+| `format-mkv` / `format-webm` | Supported audio codecs in Matroska/WebM (`.mkv`, `.mka`, `.webm`); no Opus |
+| `format-mp1`, `format-mp2`, `format-mp3` | MPEG audio layers I, II, and III respectively |
+| `format-ogg` | Vorbis and FLAC in Ogg (`.ogg`, `.oga`) |
+| `format-wav` | PCM and ADPCM in WAV/W64 |
+| `all-formats` | All input format bundles above |
+| `render` | PNG rendering |
+| `wav-output` | PCM16 WAV writing |
+
+`format-mp4` aliases `format-m4a`; `format-webm` aliases `format-mkv`.
+Format features enable the shared `decode` plumbing automatically. `decode`
+alone does not enable any codecs or containers. `all-formats` does not enable
+PNG rendering or WAV writing. Cargo features are additive: another dependency
+can enable additional features in a shared build.
+
+Generate waveform data from an audio file:
+
+```rust,no_run
+use audiowaveform::{GenerateOptions, WaveformFormat, generate_waveform_from_path};
+
+fn main() -> Result<(), audiowaveform::Error> {
+    let waveform = generate_waveform_from_path("input.mp3", &GenerateOptions::default())?;
+    waveform.save_to_path("output.dat", Some(WaveformFormat::Dat))?;
+    Ok(())
+}
+```
+
+Render a PNG from a stored waveform (requires `render`):
+
+```rust,no_run
+use std::fs::File;
+
+use audiowaveform::{RenderOptions, Waveform, write_waveform_png};
+
+fn main() -> Result<(), audiowaveform::Error> {
+    let waveform = Waveform::load_from_path("input.dat", None)?;
+    write_waveform_png(&waveform, &RenderOptions::default(), File::create("output.png")?)?;
+    Ok(())
+}
+```
+
+Generate waveform data from in-memory PCM:
+
+```rust
+use audiowaveform::{GenerateOptions, PcmAudio, generate_waveform_from_pcm};
+
+fn main() -> Result<(), audiowaveform::Error> {
+    let pcm = PcmAudio::new(48_000, 1, vec![0_i16; 48_000])?;
+    let waveform = generate_waveform_from_pcm(&pcm, &GenerateOptions::default())?;
+    assert!(!waveform.is_empty());
+    Ok(())
+}
+```
+
+Additional examples live in `crates/audiowaveform/examples`.
+
+## Ruby Usage
+
+Install the `audiowaveform` gem from RubyGems and generate waveform
+data without invoking the command-line program:
+
+```ruby
+gem "audiowaveform", "~> 0.1"
+```
+
+```ruby
+require "audiowaveform"
+
+waveform = AudioWaveform.generate("input.mp3", samples_per_pixel: 256)
+waveform.save("output.dat", bits: 8)
+```
+
+See [`bindings/ruby/README.md`](bindings/ruby/README.md) for the full Ruby API
+and development instructions.
+
+## CLI Usage
+
+The CLI defaults to `all-formats`, `render`, and `wav-output`. To build a smaller
+CLI, disable defaults and enable only the features you need:
+
+```sh
+cargo build -p audiowaveform-cli --no-default-features --features format-mp3,format-m4a
+```
+
+Add `render` or `wav-output` for those outputs. With no features, the CLI can
+still process raw PCM and convert/resample waveform data. Requests for omitted
+formats or outputs report the required Cargo feature.
+
+Generate `.dat` waveform data:
+
+```sh
+audiowaveform -i input.wav -o output.dat -z 128 -b 8
+```
+
+Render a PNG from waveform data:
+
+```sh
+audiowaveform -i input.dat -o output.png -w 1000 -h 200
+```
+
+Generate JSON waveform data from compressed audio:
+
+```sh
+audiowaveform -i input.flac -o output.json --pixels-per-second 50
+```
+
+Convert raw PCM to WAV:
+
+```sh
+audiowaveform -i input.raw -o output.wav --input-format raw --raw-samplerate 48000 --raw-channels 2 --raw-format s16le
+```
+
+See all options with:
+
+```sh
+audiowaveform --help
+```
+
+## Supported Formats
+
+Audio input:
+
+- `aac` and `adts` (AAC-LC)
+- `mp1`, `mp2`, and `mp3`
+- `mp4`, `m4a`, `m4b`, `m4r`, `m4v`, and `mov` (supported audio tracks only)
+- `mkv`, `mka`, and `webm` (supported audio tracks only; no Opus)
+- `aiff`, `aif`, and `aifc`
+- `caf`
+- `wav` and `w64`
+- `flac`
+- `ogg` and `oga`
+- `raw`
+
+Waveform input:
+
+- `dat`
+- `json`
+
+Waveform output:
+
+- `dat`
+- `json`
+- `txt`
+
+Image output:
+
+- `png`
+
+Audio output:
+
+- `wav`
+
+## Documentation
+
+- Waveform file formats: [doc/DataFormat.md](doc/DataFormat.md)
+- CLI man page: [doc/audiowaveform.1](doc/audiowaveform.1)
+- Waveform format man page: [doc/audiowaveform.5](doc/audiowaveform.5)
+- Project release history: [CHANGELOG.md](CHANGELOG.md)
+- Ruby gem release history: [bindings/ruby/CHANGELOG.md](bindings/ruby/CHANGELOG.md)
+
+Generate local API docs with:
+
+```sh
+cargo doc -p audiowaveform --all-features --no-deps
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow, documentation, and testing expectations.
+
+## License
+
+`audiowaveform` is released under the GPL-3.0-or-later license. See [COPYING](COPYING).

data/bindings/ruby/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Ruby Gem Version History
+
+## 0.1.0 - 2026-09-20
+
+### Added
+
+- Publish source and precompiled gems through RubyGems Trusted Publishing on
+  `ruby-vX.Y.Z` tag pushes. Manual workflow runs build and test without publishing.
+- Build native gems for CRuby 3.2–4.0 on Linux glibc/musl (x86-64 and ARM64),
+  macOS (Intel and Apple Silicon), and Windows UCRT (x86-64).
+- Load the extension matching the running Ruby version and verify installed
+  platform gems before publishing. Native gems have no build-time dependencies.
+- Enable all supported Rust input formats in source and precompiled builds,
+  including AAC-LC/M4A, ALAC, AIFF, CAF, MPEG layers I/II, Matroska/WebM audio,
+  Ogg FLAC, and WAV ADPCM. Opus and HE-AAC remain unsupported.
+
+- Generate waveform data directly from WAV, MP3, FLAC, and Ogg/Vorbis files.
+- Read waveform metadata and points, then serialize data as DAT, JSON, or text.
+- Install a source gem from GitHub releases or directly from the repository.
+
+### Changed
+
+- Release Ruby's global VM lock during generation, serialization, and file writes.
+- Point installation instructions and package metadata at `Antti/audiowaveform`.
+
+### Fixed
+
+- Build, install, and test the native extension across supported Linux, macOS,
+  and Windows environments.