audiowaveform 0.1.0-x86_64-linux-gnu

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.

data/bindings/ruby/README.md

@@ -0,0 +1,193 @@
+# audiowaveform for Ruby
+
+The `audiowaveform` gem provides native Ruby bindings for the Rust
+`audiowaveform` library. It generates waveform data in process without invoking
+the command-line program. Audio decoding runs without Ruby's global VM lock, so
+other Ruby threads can continue while a waveform is generated.
+
+## Installation
+
+Add the gem to your bundle:
+
+```ruby
+gem "audiowaveform", "~> 0.1"
+```
+
+Releases include precompiled gems for CRuby 3.2, 3.3, 3.4, and 4.0 on these platforms:
+
+| OS | Architectures | Gem platforms |
+| --- | --- | --- |
+| Linux (glibc) | x86-64, ARM64 | `x86_64-linux-gnu`, `aarch64-linux-gnu` |
+| Linux (musl/Alpine) | x86-64, ARM64 | `x86_64-linux-musl`, `aarch64-linux-musl` |
+| macOS | Intel, Apple Silicon | `x86_64-darwin`, `arm64-darwin` |
+| Windows (UCRT) | x86-64 | `x64-mingw-ucrt` |
+
+Precompiled gems do not require Rust, FFmpeg, or compilation during installation.
+They contain a separate extension for each supported Ruby minor version.
+Other Ruby versions and platforms fall back to the source gem, which needs Rust
+and Ruby development headers. Installing directly from GitHub also builds from
+source. JRuby and TruffleRuby are not supported.
+
+## Usage
+
+Generate waveform data from an audio file:
+
+```ruby
+require "audiowaveform"
+
+waveform = AudioWaveform.generate(
+  "recording.mp3",
+  samples_per_pixel: 256,
+  split_channels: false
+)
+
+waveform.sample_rate       # => 44_100
+waveform.samples_per_pixel # => 256
+waveform.channels          # => 1
+waveform.length            # => number of waveform points per channel
+waveform.data              # => interleaved [min, max, ...] samples
+```
+
+`AudioWaveform.generate` accepts these keyword arguments:
+
+| Keyword | Default | Description |
+| --- | --- | --- |
+| `samples_per_pixel` | `256` | Number of source samples represented by each waveform point. Must be at least 2. |
+| `pixels_per_second` | none | Time-based scale. Cannot be combined with `samples_per_pixel`. |
+| `split_channels` | `false` | Preserve separate audio channels instead of mixing them down. |
+| `amplitude_scale` | none | Non-negative numeric multiplier, or `:auto` to normalize automatically. |
+
+The returned `AudioWaveform::Waveform` exposes:
+
+| Method | Result |
+| --- | --- |
+| `sample_rate` | Source sample rate in hertz. |
+| `samples_per_pixel` | Source samples represented by each waveform point. |
+| `channels` | Number of waveform channels. |
+| `storage_bits` / `bits` | Internal sample resolution, either 8 or 16. |
+| `length` / `size` | Number of waveform points per channel. |
+| `empty?` | Whether the waveform contains no points. |
+| `duration` / `duration_seconds` | Approximate duration in seconds. |
+| `data` | Interleaved minimum and maximum sample values. |
+| `point(index, channel: 0)` | `[minimum, maximum]` pair for one point and channel. |
+
+Save the generated waveform as binary DAT, JSON, or text:
+
+```ruby
+waveform.save("recording.dat", bits: 8)
+waveform.save("recording.json", bits: 16)
+waveform.save("recording.waveform", format: :txt)
+
+json = waveform.to_json(bits: 8)
+binary = waveform.to_dat(bits: 16)
+text = waveform.to_txt(bits: 8)
+```
+
+`bits` must be 8 or 16. `save` infers the format from a `.dat`, `.json`, or
+`.txt` extension unless `format:` is provided explicitly. Invalid generation
+or serialization options raise `ArgumentError`; an out-of-range `point` raises
+`IndexError`; decoding and file I/O failures raise `AudioWaveform::Error`.
+
+Use `pixels_per_second` instead of `samples_per_pixel` when a time-based scale
+is more convenient:
+
+```ruby
+waveform = AudioWaveform.generate("recording.flac", pixels_per_second: 100)
+```
+
+Amplitude can be scaled with a numeric multiplier or normalized automatically:
+
+```ruby
+AudioWaveform.generate("quiet.wav", amplitude_scale: 1.5)
+AudioWaveform.generate("quiet.wav", amplitude_scale: :auto)
+```
+
+Both source and precompiled gems enable the Rust library's `all-formats` feature:
+AAC-LC/ADTS, AAC-LC and ALAC in M4A/MP4, MP1/MP2/MP3, WAV/W64 (PCM and ADPCM),
+FLAC, Ogg (Vorbis and FLAC), AIFF, CAF (PCM and ALAC), and supported audio tracks
+in Matroska/WebM. No FFmpeg installation is required for decoding.
+
+AAC-LC supports mono and stereo. HE-AAC and Opus remain unsupported, including
+Opus inside Ogg/WebM/MP4. Raw PCM input is not currently exposed by the gem.
+The filename extension identifies the container; an enabled container can still
+contain an unsupported codec. Such files raise `AudioWaveform::Error`.
+AAC/MP4 waveform duration can include encoder delay and padding; gapless
+trimming is not currently supported.
+
+## Development
+
+From the repository root:
+
+```sh
+bundle install
+bundle exec rake
+bundle exec rake build
+```
+
+Gem packages are written to the repository root's `pkg/` directory. To build a
+native gem for the current Ruby and platform, use `bundle exec rake native gem`.
+For the same multi-version build used in CI, install Docker and run:
+
+```sh
+bundle exec rb-sys-dock --platform x86_64-linux --ruby-versions 3.2,3.3,3.4,4.0 --build
+```
+
+The Linux build targets `x86_64-linux` and `aarch64-linux` produce explicitly
+tagged `-linux-gnu` gems, so RubyGems can distinguish glibc from musl.
+The rb_sys version pinned in the root Gemfile selects the cross-compilation image.
+
+## Releasing to RubyGems
+
+The gem has its own semantic version, independent of the Rust library. Releases
+use `ruby-vX.Y.Z` tags and [the Ruby Gem Release workflow](../../.github/workflows/ruby-release.yml).
+Each release runs the Ruby tests, builds a source gem and seven platform gems,
+installs and exercises every native gem on all four supported Ruby versions, and
+publishes the validated artifacts to RubyGems and a GitHub release.
+
+### One-time setup
+
+1. Create a GitHub environment named `release` in `Antti/audiowaveform`, allowing
+   deployments only from tags matching `ruby-v*`.
+2. Sign in to the RubyGems account that will own `audiowaveform`, with MFA enabled.
+   For the first release, create a **pending trusted publisher** from your profile.
+   For an existing gem you own, use its **Trusted publishers** page.
+3. Configure these exact values:
+
+   | Field | Value |
+   | --- | --- |
+   | Gem name (pending publisher) | `audiowaveform` |
+   | Repository owner | `Antti` |
+   | Repository name | `audiowaveform` |
+   | Workflow filename | `ruby-release.yml` |
+   | Environment | `release` |
+
+   Leave the optional reusable-workflow repository fields empty: publishing
+   happens directly in `ruby-release.yml`. No RubyGems API-key secret is needed.
+   Pending publishers expire after 12 hours, so create one shortly before the
+   first release; recreate it if it expires before the first successful push.
+   See the [RubyGems Trusted Publishing guide](https://guides.rubygems.org/trusted-publishing/).
+
+### Each release
+
+1. Update `bindings/ruby/lib/audiowaveform/version.rb` and the [Ruby changelog](CHANGELOG.md).
+   Refresh the local Bundler lockfile with `bundle install` after changing the version.
+2. Run `bundle exec rake` and `bundle exec rake build`, then commit and merge the
+   release preparation. The source gem is `pkg/audiowaveform-X.Y.Z.gem`.
+3. Optionally run **Ruby Gem Release** manually on that commit. Manual runs build
+   and test all packages without publishing, including when run against a tag.
+4. Tag the release commit and push the tag to the project repository:
+
+   ```sh
+   git tag -a ruby-vX.Y.Z -m "Release Ruby gem X.Y.Z"
+   git push antti ruby-vX.Y.Z
+   ```
+
+   Replace `X.Y.Z` with the gem version, and `antti` with your remote name if different.
+   The workflow rejects a tag that does not match the Ruby version file.
+5. Check that the release workflow succeeds and all eight artifacts are visible
+   on RubyGems and the GitHub release.
+
+If publishing fails partway through, rerun the failed job using the same artifacts.
+It skips previously uploaded gems only when their SHA-256 checksums match. A
+different artifact under the same version/platform is rejected; release a new
+version instead. Do not move an existing release tag.

data/bindings/ruby/lib/audiowaveform/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AudioWaveform
+  VERSION = "0.1.0"
+end

data/bindings/ruby/lib/audiowaveform.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "audiowaveform/version"
+require "rbconfig"
+
+# Platform gems contain one extension per Ruby minor version. Source builds put
+# the extension directly under audiowaveform/.
+native_extension = File.join(
+  __dir__, "audiowaveform", RUBY_VERSION[/\A\d+\.\d+/],
+  "audiowaveform_ruby.#{RbConfig::CONFIG.fetch('DLEXT')}"
+)
+if File.file?(native_extension)
+  require native_extension
+else
+  require "audiowaveform/audiowaveform_ruby"
+end
+
+module AudioWaveform
+  class << self
+    # Generates waveform data from an audio file.
+    def generate(
+      input,
+      samples_per_pixel: nil,
+      pixels_per_second: nil,
+      split_channels: false,
+      amplitude_scale: nil
+    )
+      scale_kind, scale_value = resolve_scale(samples_per_pixel, pixels_per_second)
+      amplitude_kind, amplitude_value = resolve_amplitude_scale(amplitude_scale)
+
+      Native.generate(
+        File.path(input),
+        scale_kind,
+        scale_value,
+        !!split_channels,
+        amplitude_kind,
+        amplitude_value
+      )
+    end
+
+    private
+
+    def resolve_scale(samples_per_pixel, pixels_per_second)
+      if samples_per_pixel && pixels_per_second
+        raise ArgumentError, "samples_per_pixel and pixels_per_second are mutually exclusive"
+      end
+
+      if pixels_per_second
+        ["pixels_per_second", positive_integer(pixels_per_second, :pixels_per_second)]
+      else
+        value = samples_per_pixel || 256
+        ["samples_per_pixel", positive_integer(value, :samples_per_pixel, minimum: 2)]
+      end
+    end
+
+    def resolve_amplitude_scale(value)
+      return ["none", 0.0] if value.nil?
+      return ["auto", 0.0] if value == :auto || value == "auto"
+
+      numeric = Float(value)
+      unless numeric.finite? && numeric >= 0.0
+        raise ArgumentError, "amplitude_scale must be a finite non-negative number or :auto"
+      end
+
+      ["fixed", numeric]
+    rescue TypeError, ArgumentError
+      raise ArgumentError, "amplitude_scale must be a finite non-negative number or :auto"
+    end
+
+    def positive_integer(value, name, minimum: 1)
+      unless value.is_a?(Integer) && value >= minimum
+        raise ArgumentError, "#{name} must be an integer greater than or equal to #{minimum}"
+      end
+
+      value
+    end
+  end
+
+  class Waveform
+    private_class_method :new
+
+    alias size length
+    alias bits storage_bits
+    alias duration_seconds duration
+
+    # Returns the [minimum, maximum] pair at +index+ for +channel+.
+    def point(index, channel: 0)
+      unless index.is_a?(Integer) && index.between?(0, length - 1) &&
+          channel.is_a?(Integer) && channel.between?(0, channels - 1)
+        raise IndexError, "waveform point is outside the available channel or index range"
+      end
+
+      value = __point(channel, index)
+      return value if value
+
+      raise IndexError, "waveform point is outside the available channel or index range"
+    end
+
+    # Writes waveform data to +path+ and returns self.
+    def save(path, format: nil, bits: storage_bits)
+      resolved_format = format || File.extname(File.path(path)).delete_prefix(".")
+      __save(File.path(path), resolved_format.to_s, validate_bits(bits))
+      self
+    end
+
+    # Returns binary DAT waveform data.
+    def to_dat(bits: storage_bits)
+      __serialize("dat", validate_bits(bits))
+    end
+
+    # Returns JSON waveform data.
+    def to_json(*, bits: storage_bits)
+      __serialize("json", validate_bits(bits)).force_encoding(Encoding::UTF_8)
+    end
+
+    # Returns plain-text waveform data.
+    def to_txt(bits: storage_bits)
+      __serialize("txt", validate_bits(bits)).force_encoding(Encoding::UTF_8)
+    end
+
+    private
+
+    def validate_bits(bits)
+      return bits if bits == 8 || bits == 16
+
+      raise ArgumentError, "bits must be either 8 or 16"
+    end
+  end
+
+  private_constant :Native
+end

data/sig/audiowaveform.rbs

@@ -0,0 +1,33 @@
+module AudioWaveform
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  def self.generate: (
+    path input,
+    ?samples_per_pixel: Integer?,
+    ?pixels_per_second: Integer?,
+    ?split_channels: bool,
+    ?amplitude_scale: (Numeric | :auto | String)?
+  ) -> Waveform
+
+  class Waveform
+    def sample_rate: () -> Integer
+    def samples_per_pixel: () -> Integer
+    def channels: () -> Integer
+    def storage_bits: () -> Integer
+    def bits: () -> Integer
+    def length: () -> Integer
+    def size: () -> Integer
+    def empty?: () -> bool
+    def duration: () -> Float
+    def duration_seconds: () -> Float
+    def data: () -> Array[Integer]
+    def point: (Integer index, ?channel: Integer) -> [Integer, Integer]
+    def save: (path path, ?format: (String | Symbol)?, ?bits: Integer) -> self
+    def to_dat: (?bits: Integer) -> String
+    def to_json: (*untyped arguments, ?bits: Integer) -> String
+    def to_txt: (?bits: Integer) -> String
+  end
+end