wavify 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0573e324cb4eb544c7a82ed254dd7fcd473439747b5c675ab474457d5cad1fec
-  data.tar.gz: a8659118673abb114e917ce23c5c8e332338962f87fe42eec9bab562628b4af9
+  metadata.gz: faee1fe4af50cc79c060be1ff707954c8569d099bc29e6e9ca00a3769902de55
+  data.tar.gz: 8cbec03ebfb36f2a90adda64ac7866b8b6c32d26eb7239c5cfff958033a23d58
 SHA512:
-  metadata.gz: 197cda12919d9acb3a80b17cb6526a15e2fc5b2c8c442144f299d938d0306f0b0bc332ce57da8ec98ebe87a04b11b18b3b157d2ea2bcfbf570d3266b7dde855d
-  data.tar.gz: 96432c4aadea84b31a83a231678dde7faed327246e45fa7d34ca4a5cc16d0ab1da200faaef4ab7f0980ec6de33402bf1f5a82e628b7921c5447447c3793f5f41
+  metadata.gz: ebd9f41c36d264872830a83c60e90efbc55a245378b0be1ab4f2d238bbbb1d822b7120df0b29a742986baba56aacc5bfa4caec229378b9422534990b51fbc4e6
+  data.tar.gz: 0da527d00c870300883e3dee77da574df351d93f8714b48668b3291171a01ae88e790b955f7b3cedcd46f0c9b4479861063780332d87b0ca9a9990441820884b

data/CHANGELOG.md

@@ -6,6 +6,45 @@ The format is based on Keep a Changelog and this project adheres to Semantic Ver
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-16
+
+### Added
+
+- Added the `wavify` CLI with info, conversion, tone generation, processing, DSL rendering/timeline, format, and dependency-diagnostic commands.
+- Expanded `Audio` with timeline editing, repeat, channel/bit-depth/sample-rate conversion, dither, sample/frame mapping, stereo controls, configurable mixing, value semantics, and peak/RMS/LUFS/true-peak analysis.
+- Expanded streaming pipelines with named steps, duration windows, meters, progress, tees, materialization, dry runs, and reset/flush/latency handling for stateful processors.
+- Added public codec metadata and reversible codec registries, strict magic/extension checks, filename hints for IO, codec-specific options, and atomic no-overwrite output.
+- Added WAV LIST/INFO, cue, loop, BWF, RF64, valid-bit, and channel-layout metadata; AIFF-C, marker, and instrument-loop support; FLAC comments, stereo coding, LPC, and adaptive Rice encoding; and configurable raw PCM/float byte order and numeric domains.
+- Added `Automation`, `LFO`, BS.1770 `LoudnessMeter`, `Processor`, and headroom helpers, plus limiter, gate, expansion, modulation, stereo, EQ, bitcrusher, and mastering/podcast chain effects.
+- Expanded the sequencer and DSL with swing, velocity/probability/ratchet notation, note durations and ties, keys/scales, chord inversions and voicings, sample transforms, stems, repeatable tempo/meter sections, markers, explicit rests, timeline text/JSON, validation, and reproducible seeds.
+- Added format valid-bit/channel-layout metadata (including explicit unknown layouts), lazy sample-buffer views, optional packed storage, cached value hashing, and thread-safe value equality.
+- Added reversible effect registration and optional adapter discovery for external codec, MIDI, and analysis integrations.
+- Added namespace-split RBS signatures, public API parity checks, documentation guides, expanded examples, randomized/property tests, and branch/per-file coverage gates.
+
+### Changed
+
+- Made OGG Vorbis an optional dependency; chained/interleaved streams now decode incrementally where possible, resample to a common rate, and spool multi-stream input outside the Ruby heap.
+- Standardized codec read/write/stream/metadata contracts and processor `flush(format:)` behavior, including defined stream-source reuse semantics and isolated offline DSP runtimes.
+- Kept mixing, automation, effect chains, and sequencer buses in floating-point workspaces until their output boundary, with signal-aware headroom and linked master limiting.
+- Improved oscillator generation with polyBLEP waveforms and band-limited/interpolated wavetables, and improved FLAC compression with Levinson–Durbin LPC and adaptive Rice partition search.
+- Reduced allocations in audio analysis, format conversion, slicing, streaming codecs, OGG demultiplexing, and sequencer voice rendering while bounding eager allocations and parser resource use.
+- Moved general `InvalidParameterError` failures outside the DSP-specific error hierarchy.
+- Made gem packaging independent of Git metadata, tied release links to the version tag, strengthened release installation checks, and made the default Rake task run the local quality gate.
+- Expanded CI across supported Ruby/platform/dependency combinations, pinned actions/runners, strengthened lint and coverage checks, and added repeatable benchmark reports.
+
+### Removed
+
+- Removed the no-op OGG `decode_mode:` option; OGG reads now always perform full decoding.
+- Removed `Audio#loop`/`loop!`; use `repeat`/`repeat!` instead.
+
+### Fixed
+
+- Fixed PCM endpoint conversion, resampling, duration parsing, zero-duration fades, clipping detection, metadata coordinate projection, packed-buffer concurrency, and destructive writes to caller-owned IO.
+- Fixed WAV extensible/RF64/overflow handling, AIFF sample-width and bounded-read behavior, FLAC checksum validation, raw stream alignment, and OGG parser/tempfile cleanup and mixed-rate chaining.
+- Fixed stream duration limits, reusable and non-rewindable source handling, processor error propagation, and cross-platform atomic path output.
+- Fixed oscillator continuity/noise behavior, envelope release handling, filter stability, and state consistency across chunked DSP processing.
+- Fixed sequencer note/chord release and rest timing, duplicate-track validation, chord parsing, and clipping across voices and simultaneous tracks.
+
 ## [0.1.0] - 2026-03-04
 
-- Initial release
+- Initial release

data/README.md

@@ -1,12 +1,18 @@
-# Wavify
+# Wavify [![Gem Version](https://badge.fury.io/rb/wavify.svg)](https://badge.fury.io/rb/wavify) [![Ruby](https://github.com/ydah/wavify/actions/workflows/ci.yml/badge.svg)](https://github.com/ydah/wavify/actions/workflows/ci.yml)
 
 Wavify is a Ruby audio processing toolkit with immutable transforms, codec I/O, streaming pipelines, DSP effects, and a sequencing DSL.
 
+Use it to:
+
+- Read, inspect, transform, and write audio from Ruby scripts.
+- Process large files with streaming pipelines and stateful DSP effects.
+- Generate tones, small arrangements, and test fixtures without mandatory FFmpeg or SoX.
+
 ## Requirements
 
 - Ruby `>= 3.1`
 - Bundler
-- Native build environment for gems with C extensions (`ogg-ruby`, `vorbis`)
+- Optional native build environment for OGG Vorbis gems (`ogg-ruby`, `vorbis`)
 
 ## Installation
 
@@ -28,6 +34,8 @@ Or install directly:
 gem install wavify
 ```
 
+WAV, AIFF, FLAC, and raw PCM work without OGG dependencies. Add `ogg-ruby` and `vorbis` to your Gemfile only when you need `.ogg` / `.oga` support.
+
 ## Quick Start
 
 ```ruby
@@ -42,7 +50,16 @@ audio = Wavify::Audio.tone(
   format: format
 )
 
-audio.fade_in(0.02).fade_out(0.05).write("tone.wav")
+audio.fade_in(0.02, curve: :exp).fade_out(0.05, curve: :log).with_bit_depth(16, dither: true).write("tone.wav")
+```
+
+Codec-specific write options are forwarded with `codec_options:`:
+
+```ruby
+audio.write("master.flac", codec_options: { block_size: 2048 })
+audio.write("preview.ogg", codec_options: { quality: 0.5 })
+audio.write("tagged.wav", codec_options: { info: { title: "Tone", artist: "Wavify" } })
+audio.write("master.wav", overwrite: false)
 ```
 
 ## Core API
@@ -51,87 +68,195 @@ audio.fade_in(0.02).fade_out(0.05).write("tone.wav")
 
 Main constructors:
 
-- `Audio.read(path, format: nil, codec_options: {})`
-- `Audio.stream(path_or_io, chunk_size: 4096, format: nil, codec_options: {})`
+- `Audio.read(path_or_io, format: nil, codec_options: {}, strict: false, filename: nil)`
+- `Audio.metadata(path_or_io, format: nil, codec_options: {}, strict: false, filename: nil)`
+- `Audio.info(path_or_io, format: nil, codec_options: {}, strict: false, filename: nil)`
+- `Audio.stream(path_or_io, chunk_size: 4096, format: nil, codec_options: {}, strict: false, filename: nil)`
 - `Audio.tone(frequency:, duration:, waveform:, format:)`
 - `Audio.silence(duration_seconds, format:)`
-- `Audio.mix(*audios)`
+- `Audio.mix(*audios, strategy: :clip, gains: nil, align: :start, format: nil, work_format: nil, headroom_smoothing: 0.005)`
 
 Immutable transforms (each also has `!` in-place variants):
 
-- `gain`, `normalize`, `trim`, `fade_in`, `fade_out`, `pan`, `reverse`, `loop`, `apply`
+- `gain`, `normalize`, `trim`, `fade_in`, `fade_out`, `pan`, `reverse`, `repeat`, `apply`
+- `concat`, `append`, `prepend`, `overlay`, `crossfade`, `slice`, `crop`, `pad_start`, `pad_end`, `insert_silence`
+- `to_mono`, `to_stereo`, `resample`, `with_bit_depth`, `map_samples`, `map_frames`
 
 Utility methods:
 
-- `convert`, `split(at:)`, `peak_amplitude`, `rms_amplitude`, `duration`, `sample_frame_count`
+- `convert`, `split(at:)`, `duration`, `sample_frame_count`, `channels`, `sample_rate`, `bit_depth`, `frames`, `each_frame`
+- `peak_amplitude`, `rms_amplitude`, `peak_dbfs`, `rms_dbfs`, `lufs`, `stats`, `silent?`, `clipped?`, `dc_offset`, `zero_crossing_rate`
+
+Mix strategies are `:clip` (default), `:normalize`, `:headroom`, `:soft_limit`, and `:none`. The `:none` strategy leaves the float workspace unclipped, but a PCM output `format:` still clamps during final conversion; select a float output format to retain values outside -1.0..1.0 for downstream limiting. Headroom is intended for brief overlaps, while sustained over-full-scale mixes should use `Wavify::DSP::Limiter`. `gains:` accepts one dB value per source, and `align:` can be `:start`, `:center`, or `:end`.
+Normalize modes are `:peak`, `:rms`, and `:lufs`.
+Use `with_bit_depth(16, dither: true)` when reducing PCM bit depth and you want simple TPDF dither.
+For large immutable buffers that are not immediately transformed, pass `storage: :packed` to `SampleBuffer.new`; sequential enumeration stays packed until random sample access is requested.
+
+Duration helpers:
+
+```ruby
+Wavify.ms(250)
+Wavify.seconds(3)
+Wavify::Core::Duration.parse("1:23.456")
+```
 
 ### Streaming pipeline
 
 ```ruby
 Wavify::Audio.stream("input.wav", chunk_size: 4096)
-             .pipe(Wavify::Effects::Compressor.new(threshold: -18, ratio: 3.0))
-             .pipe(Wavify::Effects::Chorus.new(rate: 0.5, depth: 0.2, mix: 0.15))
+             .pipe(Wavify::Effects::Compressor.new(threshold: -18, ratio: 3.0), name: :comp)
+             .map_chunks(name: :trim_preview) { |chunk| Wavify::Audio.new(chunk).trim(threshold: 0.005).buffer }
+             .meter { |stats| puts stats[:peak_dbfs] }
+             .tee("preview.wav")
              .write_to("output.aiff", format: Wavify::Core::Format::CD_QUALITY)
 ```
 
 `pipe` accepts processors that respond to `call`, `process`, or `apply`.
+Stateful processors may implement `reset`, `flush(format:)`, and `tail_duration`. A processor that exposes `flush` must accept the `format:` keyword; Wavify invokes it exactly once at the end of a pass.
+Use `take_duration`, `drop_duration`, `to_audio`, `progress`, `meter`, `tee`, and `pipeline_steps` for common chunk workflows and inspection.
+Use `dry_run(format:)` to validate a stream pipeline without writing output.
+
+`write_to` also accepts codec-specific output options:
+
+```ruby
+stream.write_to("output.flac", codec_options: { block_size_strategy: :fixed, block_size: 2048 })
+```
 
 ## Format Support
 
 | Format | Read | Write | Stream Read | Stream Write | Notes |
 |--------|------|-------|-------------|--------------|-------|
-| WAV | ✅ | ✅ | ✅ | ✅ | PCM + float WAV, including extensible WAV |
-| AIFF | ✅ | ✅ | ✅ | ✅ | PCM only (AIFC unsupported) |
-| FLAC | ✅ | ✅ | ✅ | ✅ | Pure Ruby implementation |
-| OGG Vorbis | ✅ | ✅ | ✅ | ✅ | Backed by `ogg-ruby` + `vorbis` |
+| WAV | ✅ | ✅ | ✅ | ✅ | PCM + float WAV, extensible WAV, BWF metadata, RF64 read metadata |
+| AIFF | ✅ | ✅ | ✅ | ✅ | PCM AIFF plus uncompressed AIFF-C `NONE` / `sowt` |
+| FLAC | ✅ | ✅ | ✅ | ✅ | Pure Ruby implementation with comments, mid-side, and LPC write options |
+| OGG Vorbis | ✅ | ✅ | ✅ | ✅ | Optional `ogg-ruby` + `vorbis` gems |
 | Raw PCM/Float | ✅* | ✅ | ✅* | ✅ | `format:` is required for read/stream-read/metadata |
 
 Raw example:
 
 ```ruby
 raw_format = Wavify::Core::Format.new(channels: 2, sample_rate: 44_100, bit_depth: 16, sample_format: :pcm)
+raw_float_format = raw_format.with(bit_depth: 32, sample_format: :float)
 audio = Wavify::Audio.read("input.pcm", format: raw_format)
+big_endian = Wavify::Audio.read(
+  "input.pcm",
+  format: raw_format,
+  codec_options: { endianness: :big, signed: true }
+)
+ieee_float = Wavify::Audio.read(
+  "samples.raw",
+  format: raw_float_format,
+  codec_options: { float_domain: :ieee }
+)
 audio.write("output.wav")
 ```
 
+For IO objects without magic bytes, pass `filename:` as a codec hint:
+
+```ruby
+io = StringIO.new(raw_bytes)
+audio = Wavify::Audio.read(io, filename: "input.raw", format: raw_format)
+```
+
+Metadata example:
+
+```ruby
+metadata = Wavify::Audio.metadata("input.wav")
+metadata[:format].sample_rate
+metadata[:duration]
+```
+
+Codec registry helpers:
+
+```ruby
+Wavify::Codecs.supported_formats
+Wavify::Codecs.available_formats
+Wavify::Codecs.detect("input.wav")
+Wavify::Codecs.register(".custom", MyCodec)
+Wavify::Codecs.register(".custom", MyCodec, magic: "CSTM", priority: 10)
+Wavify::Codecs.unregister(".custom")
+Wavify::Adapters.known
+```
+
 ### OGG Vorbis notes
 
 - `read` / `stream_read` support sequential chained streams and interleaved multi-stream OGG.
+- Single-logical-stream `stream_read` incrementally processes pages, packets, native synthesis, and output chunks.
+- Chained/interleaved inputs demultiplex logical pages into bounded-memory temporary spools, then decode packets and emit mixed/resampled chunks incrementally.
 - Interleaved multi-stream decode is mixed into one output stream.
 - If interleaved streams have different sample rates, they are resampled to the first logical stream's sample rate before mix.
-- `decode_mode: :strict` and `decode_mode: :placeholder` are accepted for API compatibility.
+- OGG support is optional; `wavify doctor` reports whether the native gems are installed.
+- MP3, AAC, FFmpeg, MIDI, and spectrogram support are adapter-gem boundaries; use `Wavify::Adapters.load(:ffmpeg)` after installing a matching adapter gem.
+
+Native support matrix:
+
+| Platform | Core codecs | OGG Vorbis native CI | Support status |
+|----------|-------------|-----------------------|----------------|
+| Linux (Ubuntu 24.04) | Tested | Tested with `libogg-dev` / `libvorbis-dev` | Supported |
+| macOS 14 | Tested | Not run | Core supported; OGG native best-effort |
+| Windows Server 2022 | Tested | Not run | Core supported; OGG native best-effort |
 
 ## Sequencer DSL
 
 Use `Wavify.build` for one-shot rendering/writing, or `Wavify::DSL.build_definition` when you want timeline access.
 
 ```ruby
-song = Wavify::DSL.build_definition(format: Wavify::Core::Format::CD_QUALITY, tempo: 116, default_bars: 2) do
+song = Wavify::DSL.build_definition(format: Wavify::Core::Format::CD_QUALITY, tempo: 116, swing: 0.55, default_bars: 2) do
+  sample_folder "samples"
+  key :c, :minor
+
   track :kick do
     synth :sine
-    notes "C2 . . . C2 . . .", resolution: 16
+    notes "C2/8. . C2/8t .", resolution: 16
     envelope attack: 0.001, decay: 0.05, sustain: 0.0, release: 0.06
     gain(-4)
   end
 
+  track :pad do
+    chords ["Cmaj7/E@drop2"], voicing: :open
+  end
+
   arrange do
-    section :intro, bars: 1, tracks: %i[kick]
+    section :intro, bars: 1, tracks: %i[kick], markers: [:start]
+    section :bridge, bars: 1, tracks: %i[kick pad], tempo: 92, beats_per_bar: 3, markers: [:bridge]
   end
 end
 
 timeline = song.timeline
+song.timeline_json
+song.timeline_text
+stems = song.render(stems: true)
 mix = song.render
 mix.write("song.wav")
 ```
 
+Pattern steps support rests (`-`/`.`), normal triggers (`x`, velocity `0.8`), accents (`X`, velocity `1.0`), explicit velocity suffixes (`x0.5`), probability rolls (`x?50`), and ratchets (`x:3`). Pass `random_seed:` to the DSL entrypoint for reproducible probability rolls. Trigger patterns render audio on sample-backed DSL tracks; synth tracks use note or chord events.
+Note tokens support fixed durations (`C4/8`), dotted values (`C4/8.`), triplets (`C4/8t`), and ties (`D4~ D4`).
+Use `key :c, :minor` for simple scale quantization, slash chords for inversions, and `@drop2` / `@open` or `voicing:` for chord voicings.
+Arrangement sections can carry `tempo:`, `beats_per_bar:`, and `markers:`.
+Swing values start at `0.5` for straight timing; values such as `0.55` delay off-beat steps on even grids. Odd resolutions use straight timing because they do not form complete swing pairs.
+Notes, ties, envelope releases, and effect tails may continue beyond a bar or section boundary. They are rendered with the tempo at note-on and continue even if the track is inactive in the following section.
+Sample tracks can use `sample_folder`, per-sample `pitch:` semitones, `preset :lofi_drums`, and `Wavify::DSL.validate(deep: true)` for pre-render file/codec checks. Pass `safe_paths: true` to restrict sample paths to the configured sample folder.
+
 ## DSP
 
 Built-in modules:
 
-- Oscillator waveforms: `:sine`, `:square`, `:sawtooth`, `:triangle`, `:white_noise`, `:pink_noise`
-- Envelope (ADSR)
+- Oscillator waveforms: `:sine`, `:square`, `:sawtooth`, `:triangle`, `:pulse`, `:white_noise`, `:pink_noise`
+- Envelope (AHDSR with optional segment curves)
+- Automation and LFO modulation helpers
 - Biquad filters (lowpass/highpass/bandpass/notch/peaking/shelves)
-- Effects: `Delay`, `Reverb`, `Chorus`, `Distortion`, `Compressor`
+- Effects: `Delay`, `Reverb`, `Chorus`, `Vibrato`, `Flanger`, `Phaser`, `Distortion`, `Compressor`, `Limiter`, `SoftLimiter`, `NoiseGate`, `Expander`, `Tremolo`, `AutoPan`, `StereoWidener`, `Bitcrusher`, `EQ`
+- Preset chains: `MasteringChain`, `PodcastChain`
+
+Register custom processors for pipelines and DSL tracks:
+
+```ruby
+Wavify::Effects.register(:my_effect, MyEffect)
+Wavify::DSL.effect(:my_effect, MyEffect)
+```
+
+`Envelope` supports `hold:` and `curve: :linear | :exp | :log`. `Reverb` supports `pre_delay:` for delaying only the wet path and `width:` for stereo wet width.
 
 ## Examples
 
@@ -141,6 +266,7 @@ Scripts in `examples/`:
 - `examples/audio_processing.rb`
 - `examples/synth_pad.rb`
 - `examples/drum_machine.rb`
+- `examples/chill_vibes.rb`
 - `examples/hybrid_arrangement.rb`
 - `examples/streaming_master_chain.rb`
 - `examples/cinematic_transition.rb`
@@ -151,6 +277,50 @@ Run:
 ruby examples/synth_pad.rb
 ```
 
+See `examples/README.md` for the full list.
+
+## CLI
+
+The gem includes a small CLI for common scripting tasks:
+
+`wavify render` and `wavify timeline` evaluate song files as Ruby. Only run trusted song files; this is not a sandbox for untrusted input.
+
+```bash
+wavify info input.wav
+wavify convert input.wav output.flac
+wavify tone --freq 440 --duration 1 tone.wav
+wavify normalize input.wav output.wav --target -1
+wavify trim input.wav output.wav --threshold 0.01
+wavify chain input.wav output.wav --gain -3 --fade-in 0.02 --fade-out 0.05
+wavify render song.rb out.wav --tempo 120 --swing 0.55 --bars 4 --seed 123
+wavify timeline song.rb --tempo 120 --bars 4 --seed 123
+wavify formats
+wavify doctor
+```
+
+## Documentation
+
+- `docs/getting-started.md`
+- `docs/codecs.md`
+- `docs/dsp.md`
+- `docs/streaming.md`
+- `docs/sequencer.md`
+- `docs/limitations.md`
+- `docs/performance.md`
+- `ROADMAP.md`
+- YARD docs can be generated with `bundle exec rake docs:yard`.
+
+## Limitations
+
+- MP3, AAC, and M4A are not built into core.
+- FFmpeg and SoX are not mandatory runtime dependencies.
+- OGG Vorbis uses optional native gems (`ogg-ruby`, `vorbis`).
+- Raw PCM/float requires `format:` for read, stream read, and metadata.
+- Streaming writes for header-based formats require seekable output IO.
+- Non-rewindable IO stream sources are single-use; path and rewindable IO sources can be enumerated repeatedly.
+- Resampling defaults to linear interpolation; pass `resampler: :windowed_sinc` for higher-quality offline conversion.
+- LUFS measurement and normalization use BS.1770 K-weighting with absolute and relative gating. `Limiter` provides stereo-linked lookahead peak control.
+
 ## Development
 
 Install dependencies:
@@ -162,10 +332,16 @@ bundle install
 Run tests:
 
 ```bash
+bundle exec rake
 bundle exec rspec
-bundle exec rake spec:coverage COVERAGE_MINIMUM=90
+SIMPLECOV_BRANCH=1 COVERAGE_MINIMUM=90 COVERAGE_BRANCH_MINIMUM=70 \
+  COVERAGE_MINIMUM_PER_FILE=60 COVERAGE_BRANCH_MINIMUM_PER_FILE=40 \
+  bundle exec rake spec:coverage
+bundle exec rake types:validate
 ```
 
+The default `rake` task runs specs, lint, RBS/API parity validation, and the documentation gate.
+
 Generate/check docs:
 
 ```bash
@@ -175,6 +351,8 @@ YARD_MINIMUM=85 bundle exec rake docs:check
 bundle exec rake docs:all
 ```
 
+`docs:examples` syntax-checks every example and smoke-runs the shorter scripts. Set `EXAMPLES=all` to run all examples end to end. `docs:yard` generates YARD output under `doc/`. `docs:check` enforces the configured YARD documentation percentage.
+
 Benchmarks:
 
 ```bash
@@ -183,6 +361,8 @@ bundle exec rake bench:dsp
 bundle exec rake bench:flac
 bundle exec rake bench:stream
 bundle exec rake bench:all
+bundle exec rake bench:baseline
+bundle exec rake bench:compare
 ```
 
 Release checks:
@@ -191,6 +371,8 @@ Release checks:
 bundle exec rake release:check
 ```
 
+The release check builds the gem, installs it into an isolated `GEM_HOME`, then verifies `require "wavify"`, CLI help, and packaged public files.
+
 ## License
 
 Wavify is released under the MIT License.

data/exe/wavify

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "wavify"
+
+exit Wavify::CLI.run

data/lib/wavify/adapters.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Wavify
+  # Catalog and loader for optional adapter gems that live outside the core gem.
+  module Adapters
+    AdapterSpec = Struct.new(:name, :kind, :gem_name, :require_path, :formats, :summary, keyword_init: true)
+
+    KNOWN = [
+      AdapterSpec.new(
+        name: :ffmpeg,
+        kind: :codec,
+        gem_name: "wavify-ffmpeg",
+        require_path: "wavify/ffmpeg",
+        formats: %w[mp3 aac m4a wav flac ogg],
+        summary: "FFmpeg-backed codec adapter for formats that should not be mandatory core dependencies."
+      ),
+      AdapterSpec.new(
+        name: :mp3,
+        kind: :codec,
+        gem_name: "wavify-mp3",
+        require_path: "wavify/mp3",
+        formats: %w[mp3],
+        summary: "MP3 codec adapter."
+      ),
+      AdapterSpec.new(
+        name: :midi,
+        kind: :sequencer,
+        gem_name: "wavify-midi",
+        require_path: "wavify/midi",
+        formats: %w[mid midi],
+        summary: "MIDI import/export adapter for sequencer timelines."
+      ),
+      AdapterSpec.new(
+        name: :spectrogram,
+        kind: :analysis,
+        gem_name: "wavify-spectrogram",
+        require_path: "wavify/spectrogram",
+        formats: %w[png json],
+        summary: "Spectrogram and FFT analysis adapter."
+      )
+    ].freeze
+
+    class << self
+      # @return [Array<AdapterSpec>]
+      def known
+        KNOWN.dup
+      end
+
+      # @param name [String, Symbol]
+      # @return [AdapterSpec, nil]
+      def find(name)
+        normalized = normalize_name(name)
+        KNOWN.find { |adapter| adapter.name == normalized }
+      end
+
+      # Requires an optional adapter gem and lets it register itself.
+      #
+      # @param name [String, Symbol]
+      # @return [true]
+      def load(name)
+        adapter = find(name)
+        raise InvalidParameterError, "unknown adapter: #{name.inspect}" unless adapter
+
+        require adapter.require_path
+        true
+      rescue LoadError
+        raise UnsupportedFormatError,
+              "adapter #{adapter.name} is not installed; add gem #{adapter.gem_name.inspect} " \
+              "and require #{adapter.require_path.inspect}"
+      end
+
+      private
+
+      def normalize_name(name)
+        name.to_sym
+      rescue NoMethodError
+        raise InvalidParameterError, "adapter name must be String or Symbol"
+      end
+    end
+  end
+end