audioproxy-rails 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2c006e53f916a943195a3887a184f3fa141e086227ecc03919199a335f32df7
-  data.tar.gz: 110cc6e5eb81d7fb34d3688b2c56953d822792157a27e9669d1f25c17b86d1e1
+  metadata.gz: 4de1340b2094f8154a8c5f02b45c5409fc7b0468967cbe9bf0bda9d836264f4d
+  data.tar.gz: 6a69838fa47da950bdd6a80880b31e2f2a75dad76991cfa52599dc01ea92925a
 SHA512:
-  metadata.gz: 8c506590e9344488d0cc4222aec06ae92315628e685526fd8a7b2c1ab7692997dadba3b84294d7bcf1f1c4d653c5b6b8320e695c88ce86d571a83d0e5561ab4b
-  data.tar.gz: a1a54ccb83749af4b65339ba42d29c11ae76d1cc914376461388dcf70707febf0771159df327b54b26ad00692371b5980829e8b7031f1077235ab31546168dff
+  metadata.gz: 0c86091fd6f663dab0785223d5cc9a19d4396d04243363aa8d2ec9ddb94d631eb6c626319c8cd7ca40f0927c14abfdf436e498a9eeecaf5fb00e63e79b424a07
+  data.tar.gz: 966e160dfe9a51c1e3e47c0c6bcad259a7a4a829242917fbe2428d9f7f1c03f00132c5f753a1b1bceac06e1933689d3a9934f4e7cebdf4e4a7689fe9ebffc777

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.3.0
+
+* Probe metadata URLs. `Audioproxy.info_url(source)` and the `audioproxy_info_url` view helper
+  build the proxy's `/info` URL, which returns duration, sample rate, channels and tags as JSON. The
+  proxy's `/info` has no options segment, so `info_url` raises for any option or `raw:`, and ignores
+  `config.default_options` and `config.expires_in`. Info URLs therefore never expire, even when
+  every other URL your app builds does.
+
+* Waveform peaks URLs. `Audioproxy.peaks_url(source, **options)` and the `audioproxy_peaks_url`
+  view helper build a variant URL with `f:peaks` fixed. They accept only the options that change a
+  waveform (`pts`, `pk_fmt`, `pk_bits`, `ch`, `t`, `fade`, `gain`, `norm`, `dl`, `cb`) and raise on
+  the rest, since the proxy refuses encoding options on peaks. Of the configured defaults, only
+  `t`, `fade`, `gain`, `norm` and `cb` carry over, so the waveform follows normalized audio while an
+  audio default such as `br: 96` or `ch: 2` never reaches a peaks request.
+
+* `pk_bits` option, aliased as `peak_bits`: the width of each peaks value, 8 or 16. peaks.js reads
+  only 8-bit data, so a peaks.js client asks for `pk_bits: 8`. Requires audioproxy 0.8.0 or newer;
+  older proxies answer `pk_bits:` with a `422`.
+
+* `url_for` output is unchanged, byte for byte.
+
 ## 0.2.0
 
 * Expiring URLs. `url_for` and every view helper accept `expires_in:` (a duration or Integer

data/README.md

@@ -10,9 +10,9 @@ Full Rails is a development dependency only. `require "audioproxy"` works in a p
 
 ## Status
 
-Core signing and typed options work, in both the proxy's short spellings and their aliases, as do the Railtie's credentials/ENV wiring, the view helpers — URL, `<audio>` tag and preload hint — and ActiveStorage resolution for the S3 and Disk services. Blobs on any other service raise; see [ActiveStorage](#activestorage) for what to do about that.
+Core signing and typed options work, in both the proxy's short spellings and their aliases, as do [`info` and peaks URLs](#metadata-and-waveforms), the Railtie's credentials/ENV wiring, the view helpers — URL, `<audio>` tag and preload hint — and ActiveStorage resolution for the S3 and Disk services. Blobs on any other service raise; see [ActiveStorage](#activestorage) for what to do about that.
 
-[Expiring URLs](#expiring-urls) work too, against [audioproxy 0.6.0 or newer](#minimum-proxy-version). One caveat worth knowing either way: everything in this gem is verified against the proxy's published signature vectors and its source, but no test here has yet asked a running proxy whether a generated URL is accepted. That round-trip is the next change.
+[Expiring URLs](#expiring-urls) work too, against [audioproxy 0.6.0 or newer](#minimum-proxy-version), and `pk_bits` needs 0.8.0. Everything here is verified against the proxy's published signature vectors and its source, and CI also asks a running proxy to accept signed, unsigned, typed-option and expiring URLs. `info` and peaks URLs are not in that round-trip yet.
 
 ## Installation
 
@@ -92,6 +92,24 @@ Audioproxy.url_for("s3://masters/2026/piece-final.wav", raw: "f:opus/br:96")
 
 The result is `{endpoint}/{signature}/{options}/{source}`. The source is always emitted in `enc/` form (unpadded base64url), so spaces, nested URLs, and already-escaped bytes need no special handling.
 
+### Metadata and waveforms
+
+The proxy answers two more things a player needs around playback, and each has its own entry point:
+
+```ruby
+Audioproxy.info_url("s3://masters/piece.wav")
+# => "https://audio.example.com/…/info/enc/czM6Ly9tYXN0ZXJz…"
+
+Audioproxy.peaks_url("s3://masters/piece.wav", pts: 800, pk_bits: 8)
+# => "https://audio.example.com/…/f:peaks/pts:800/pk_bits:8/enc/czM6Ly9tYXN0ZXJz…"
+```
+
+`info_url` builds the proxy's probe-metadata URL: duration, sample rate, channels and tags as JSON, which is how a player learns the duration it needs before it can write a sensible `t:`. It takes **no options**, because the proxy answers any options segment alongside `info` with a `422`. So it raises for a typed key or `raw:`, and it ignores `config.default_options`, the one entry point that does. It also ignores `config.expires_in` and raises for a per-call `expires_in:` or `expires_at:`, since `/info` has nowhere to carry `exp`: **info URLs never expire, even when every other URL your app builds does.** The proxy treats them as operator-facing rather than something handed to listeners, so keep them that way. Info responses are cached for an hour and are deliberately not `immutable`, because a re-upload changes the answer; do not memoize a response forever.
+
+`peaks_url` is a variant URL with the format fixed to `f:peaks`. It accepts only the options that change a waveform: `pts`, `pk_fmt`, `pk_bits`, `ch`, `t`, `fade`, `gain`, `norm`, `dl` and `cb`, in either spelling. Anything else raises, naming that list. The proxy refuses `br`, `q`, `sr` and `bd` on a peaks request, and an option it merely ignored would still enter its cache key and buy a second render of identical peaks. `raw:` is refused too, because a pre-rendered string cannot be checked; `url_for(source, raw: "f:peaks/…")` stays the escape hatch.
+
+Only some configured defaults carry over to peaks: `t`, `fade`, `gain` and `norm`, which change the samples, so the waveform matches the audio drawn above it, and the cache buster `cb`. The rest are skipped. `f:opus` or `br:96` would render into a `422`, and `ch` and `dl` mean something else as audio defaults: `ch: 2` is stereo output for audio but per-channel pairs for peaks, and an audio filename is the wrong name for peaks JSON. Pass either per call when you want it on the peaks. A `raw:` default is skipped entirely. Expiry works exactly as it does for `url_for`. The gem does not add `ch:1` for you even though peaks default to mono; the proxy fills in its own defaults.
+
 ## Options
 
 Describe the variant with the proxy's option keys as Ruby keyword arguments, either in the proxy's own short spelling or in the spelled-out alias next to it:
@@ -115,9 +133,12 @@ Audioproxy.url_for("s3://masters/piece.wav", f: :opus, br: 96, t: [12.5, 30])
 | `norm` | `normalize` | `norm: [:ebu, -16, -1.5, 11]` | loudness normalization: mode, then I, TP, LRA |
 | `pts` | `peak_count` | `pts: 800` | peak points, for waveform output |
 | `pk_fmt` | `peak_format` | `pk_fmt: :json` | peaks format |
+| `pk_bits` | `peak_bits` | `pk_bits: 8` | peaks value width, 8 or 16 |
 | `dl` | `download` | `dl: "piece.mp3"` | download filename |
 | `cb` | `cache_buster` | `cb: "v2"` | cache buster |
 
+If the peaks are for [peaks.js](https://github.com/bbc/peaks.js), ask for `pk_bits: 8`: peaks.js only loads 8-bit waveform data, and the proxy's default width is 16. The alias is `peak_bits` rather than `bit_depth`, because `bit_depth` already means `bd`, the sample format of encoded audio.
+
 Segments render in the order you write the keywords. The gem does not sort them and does not materialize defaults; that is the proxy's normalization, and a half-normalization here would only invent a third spelling. If you want URLs to stay stable across a codebase, keep the argument order stable.
 
 `t`, `fade` and `norm` take colon-separated parts, so they take arrays: `t: [12.5, 30]` renders `t:12.5:30`. A single part can be written as a scalar: `t: 12.5` renders `t:12.5`. Symbols and strings render alike, so `f: :opus` and `f: "opus"` are the same URL.
@@ -274,7 +295,11 @@ An expiry composes with `raw:` rather than replacing it, since `exp` is not a va
 
 ### Minimum proxy version
 
-Expiring URLs need **audioproxy 0.6.0 or newer**, the release that added the `exp` option. `0.5.0` and earlier answer `exp:` with a `422 invalid option`. That failure is loud and server-side, so pointing this gem at an older proxy breaks visibly rather than silently ignoring the expiry, and every other feature here works against `0.5.0` unchanged. This gem does not version-sniff.
+Expiring URLs need **audioproxy 0.6.0 or newer**, the release that added the `exp` option. `0.5.0` and earlier answer `exp:` with a `422 invalid option`. That failure is loud and server-side, so pointing this gem at an older proxy breaks visibly rather than silently ignoring the expiry.
+
+`pk_bits` needs **audioproxy 0.8.0 or newer**, the release that added it. Older proxies answer `pk_bits:` with a `422` for an unknown key.
+
+Every other feature here works against `0.5.0` unchanged. This gem does not version-sniff.
 
 ## Rails
 
@@ -351,6 +376,8 @@ Nothing is validated at boot. An app with no credentials and no ENV boots fine
 
 The `html:` bucket is not ceremony. Without it, proxy option names and HTML attribute names would share one namespace, and the gem would have to guess which one you meant for any key it did not recognize — so a mistyped `bitrat: 96` would land silently on the `<audio>` element as an attribute and quietly ship the default format instead. With the bucket, the two never mix in either direction: an unknown proxy option raises, and an `html:` entry never reaches the proxy. Proxy options never appear as tag attributes.
 
+`audioproxy_info_url` and `audioproxy_peaks_url` are [`info_url` and `peaks_url`](#metadata-and-waveforms) under view names, as `audioproxy_url` is `url_for`. There are no tag helpers for either: both return JSON (or peaks' binary `.dat`) for a script to fetch, and there is no HTML element to hand them to.
+
 #### Preloading a variant
 
 `audioproxy_preload_link_tag` emits a resource hint for a variant you are about to play. Because the first request for a variant is a render, the hint overlaps that render with page load rather than leaving someone waiting for it after a click:
@@ -447,6 +474,63 @@ It boots the dummy Rails app in `test/dummy` for the integration tests. Style ch
 bin/rubocop
 ```
 
+### Round-trip tests against a real proxy
+
+`bin/test` checks the bytes this gem produces. It cannot check that a real proxy *accepts* them, and
+some things are not expressible as a byte comparison at all: whether an expired URL is refused with
+`410`, and whether the second `exp` names is still served, are questions only a running proxy
+answers.
+
+Those tests live in `test/server/`, and they are skipped unless you tell them where a proxy is. The
+gem does not start one for you — start it yourself:
+
+```bash
+mkdir -p /tmp/audioproxy-fixtures
+
+docker run --rm -d --name audioproxy-test \
+  --platform linux/amd64 \
+  -p 4000:4000 \
+  -e AP_KEY=00112233445566778899AABBCCDDEEFF00112233445566778899AABBCCDDEEFF \
+  -e AP_SALT=FFEEDDCCBBAA99887766554433221100 \
+  -e AP_ALLOW_INSECURE=true \
+  -e AP_LOCAL_ROOT=/srv/audio \
+  -v /tmp/audioproxy-fixtures:/srv/audio \
+  ghcr.io/audioproxy/audioproxy:0.6.0
+```
+
+Then point the suite at it:
+
+```bash
+AUDIOPROXY_PROXY_URL=http://127.0.0.1:4000 bin/test test/server
+```
+
+Drop the path to run everything, unit tests included. Stop it with
+`docker rm -f audioproxy-test` when you are done.
+
+The key and salt above are the published known-answer test vectors — not secrets, and the same ones
+in `test/fixtures/signature_vectors.rb`, so the round-trips exercise the bytes those vectors pin.
+The suite writes a generated WAV into `/tmp/audioproxy-fixtures` (override with
+`AUDIOPROXY_FIXTURE_ROOT`), so there is nothing to fetch and you need no ffmpeg on your side.
+`--platform linux/amd64` is there because the published image is amd64-only; on Apple Silicon it
+runs under emulation, and on an amd64 host the flag does nothing.
+
+A few things worth knowing:
+
+- **`AUDIOPROXY_PROXY_URL` unset means skip; set means fail if nothing answers.** Setting it is a
+  claim that a proxy is there, so an unreachable one is an error rather than a quiet pass. That
+  keeps `bin/test` a fast, Docker-free unit run for anyone who cannot pull an image, without
+  letting a broken round-trip environment look like a green one.
+- **The proxy version is checked, not assumed.** The suite asks `/health` what it is talking to and
+  refuses to run against anything but the pinned release, so a mismatch is a named failure rather
+  than a confusing one.
+- **The pin is advanced by hand, as part of the proxy's release checklist.** A pinned tag nobody
+  advances stops testing anything interesting, and it fails silently — by passing. When the proxy
+  releases, bump `PROXY_VERSION` in `test/support/server_roundtrip.rb` and the image in
+  `.github/workflows/ci.yml`. Forgetting one of the two is caught by the version check above.
+- **In CI the proxy is a service container**, and the round-trip job is **visible but not required**:
+  it goes red on failure, but putting it in branch protection would make every merge depend on ghcr
+  being up, and the unit suite is the real safety net.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/audioproxy/options.rb

@@ -11,8 +11,8 @@ module Audioproxy
   # carrying a separator — because a mangled segment is a valid-looking URL for
   # the wrong variant, and it fails at request time, far from here.
   module Options
-    # The proxy's fifteen option keys, canonical short spellings.
-    KEYS = %i[bd br cb ch dl exp f fade gain norm pk_fmt pts q sr t].freeze
+    # The proxy's sixteen option keys, canonical short spellings.
+    KEYS = %i[bd br cb ch dl exp f fade gain norm pk_bits pk_fmt pts q sr t].freeze
 
     # The one *request* option in the grammar: signed as path bytes, but
     # excluded from the proxy's canonical options string, its cache key and its
@@ -26,8 +26,9 @@ module Audioproxy
     # rather read than decode. Total over KEYS, so "does this key have an alias"
     # never has two answers: +fade+ and +gain+ are already words and alias to
     # themselves. The names are the proxy's own where it has one — its Options
-    # struct calls pts +peak_count+ and pk_fmt +peak_format+ — so this is one
-    # vocabulary spelled twice, not a second vocabulary (D2).
+    # struct calls pts +peak_count+, pk_fmt +peak_format+ and pk_bits
+    # +peak_bits+ — so this is one vocabulary spelled twice, not a second
+    # vocabulary (D2). peak_bits is deliberately not bit_depth, which bd owns.
     ALIASES = {
       f: :format,
       br: :bitrate,
@@ -41,6 +42,7 @@ module Audioproxy
       norm: :normalize,
       pts: :peak_count,
       pk_fmt: :peak_format,
+      pk_bits: :peak_bits,
       dl: :download,
       cb: :cache_buster,
       exp: :expires_at
@@ -53,6 +55,22 @@ module Audioproxy
       .merge(KEYS.to_h { |key| [ key, key ] })
       .freeze
 
+    # The keys that reach the proxy's peaks renderer (API v1 §3.3): the peaks
+    # keys themselves, and the ones peaks follow so a waveform matches the
+    # audio drawn under it. A positive list on purpose (D4): an ignored option
+    # still enters the proxy's cache key, so one that slips through buys a
+    # second render of byte-identical peaks, and a key added to the proxy later
+    # is refused here until someone checks it belongs.
+    PEAKS_KEYS = %i[pts pk_fmt pk_bits ch t fade gain norm dl cb].freeze
+
+    # The configured defaults that carry over to peaks (D10): the ones that
+    # change the samples, so a waveform matches the audio drawn above it, and
+    # the cache buster. Narrower than PEAKS_KEYS because a default was written
+    # for audio: ch:2 there means stereo output, but on peaks it means
+    # per-channel pairs instead of the mono downmix, and a dl: filename for the
+    # audio is never the right name for peaks JSON.
+    PEAKS_DEFAULT_KEYS = %i[t fade gain norm cb].freeze
+
     # Keys whose grammar takes colon-separated parts: +t:START[:DURATION]+,
     # +fade:IN[:OUT]+, +norm:ebu[:I[:TP[:LRA]]]+.
     MULTI_PART_KEYS = %i[t fade norm].freeze

data/lib/audioproxy/rails/helpers.rb

@@ -11,6 +11,18 @@ module Audioproxy
         Audioproxy.url_for(source, **options)
       end
 
+      # URL helpers only, with no tag counterparts on purpose (D7): info is
+      # JSON and peaks are JSON or a binary .dat, both fetched by a script, so
+      # there is no element to hand them to. A <div data-peaks-url> convention
+      # would make this gem the keeper of some JavaScript library's markup.
+      def audioproxy_info_url(source, **options)
+        Audioproxy.info_url(source, **options)
+      end
+
+      def audioproxy_peaks_url(source, **options)
+        Audioproxy.peaks_url(source, **options)
+      end
+
       # The html: bucket is the seam between proxy options and tag attributes
       # (D4). Without it, proxy option keys and HTML attribute names share one
       # namespace, and a typoed option lands silently on the <audio> element

data/lib/audioproxy/url_builder.rb

@@ -19,6 +19,11 @@ module Audioproxy
     # always-valid options string is its default format spelled out.
     FALLBACK_OPTIONS = "f:mp3".freeze
 
+    INFO_SEGMENT = "info".freeze
+
+    # Builder keywords that carry an expiry, which /info cannot hold (D9).
+    EXPIRY_KEYWORDS = %i[expires_in expires_at].freeze
+
     attr_reader :config
 
     def initialize(config = Audioproxy.config)
@@ -36,20 +41,32 @@ module Audioproxy
     # overriding +config.expires_in+; either given as nil opts out of it (D6).
     def url_for(source, raw: nil, endpoint: nil, unsigned: nil,
                 expires_in: Expiry::UNSET, expires_at: Expiry::UNSET, **typed)
-      base = endpoint.nil? ? config.endpoint : Config.new.tap { |c| c.endpoint = endpoint }.endpoint
-      raise ConfigurationError, "Audioproxy has no endpoint configured" if base.nil?
+      assemble(source, endpoint: endpoint, unsigned: unsigned) do
+        expiry = expiry_for(expires_in, expires_at)
+        with_expiry(variant_segment(raw, typed), expiry)
+      end
+    end
 
-      # Once per URL, so the window arithmetic and the past-check cannot
-      # straddle a second boundary (D4).
-      expiry = Expiry.timestamp(
-        expires_in: expires_in, expires_at: expires_at,
-        default_expires_in: config.expires_in, now: Time.now.to_i
-      )
+    # The proxy's probe-metadata endpoint, +/{sig}/info/{source}+. API v1 §4:
+    # any options segment alongside +info+ is a 422, and the grammar therefore
+    # cannot carry +exp+ either. So neither +config.default_options+ (D2) nor
+    # +config.expires_in+ (D9) is consulted here — the one entry point that
+    # ignores them, because honouring them would break every info request.
+    def info_url(source, endpoint: nil, unsigned: nil, **options)
+      reject_info_options!(options)
 
-      rest_of_path = "/#{options_segment(raw, typed, expiry)}/#{source_segment(source)}"
-      insecure = unsigned.nil? ? config.unsigned : unsigned
+      assemble(source, endpoint: endpoint, unsigned: unsigned) { INFO_SEGMENT }
+    end
 
-      "#{base}/#{insecure ? INSECURE_SEGMENT : sign(rest_of_path)}#{rest_of_path}"
+    # A variant URL with the format fixed to +f:peaks+. Peaks are a format, not
+    # an endpoint, so this is url_for's grammar with a screened vocabulary: only
+    # Options::PEAKS_KEYS pass, per call and from the defaults (D4, D10).
+    def peaks_url(source, raw: nil, endpoint: nil, unsigned: nil,
+                  expires_in: Expiry::UNSET, expires_at: Expiry::UNSET, **typed)
+      assemble(source, endpoint: endpoint, unsigned: unsigned) do
+        expiry = expiry_for(expires_in, expires_at)
+        with_expiry(peaks_segment(raw, typed), expiry)
+      end
     end
 
     # Signs via Audioproxy::Signer. Whether the config *can* sign is this
@@ -64,14 +81,31 @@ module Audioproxy
     end
 
     private
+      # The block yields the segment between signature and source, and runs
+      # after the endpoint check, so a missing endpoint is reported first.
+      def assemble(source, endpoint:, unsigned:)
+        base = endpoint.nil? ? config.endpoint : Config.new.tap { |c| c.endpoint = endpoint }.endpoint
+        raise ConfigurationError, "Audioproxy has no endpoint configured" if base.nil?
+
+        rest_of_path = "/#{yield}/#{source_segment(source)}"
+        insecure = unsigned.nil? ? config.unsigned : unsigned
+
+        "#{base}/#{insecure ? INSECURE_SEGMENT : sign(rest_of_path)}#{rest_of_path}"
+      end
+
+      # Once per URL, so the window arithmetic and the past-check cannot
+      # straddle a second boundary (D4).
+      def expiry_for(expires_in, expires_at)
+        Expiry.timestamp(
+          expires_in: expires_in, expires_at: expires_at,
+          default_expires_in: config.expires_in, now: Time.now.to_i
+        )
+      end
+
       # Precedence, per D4: an explicit per-call source of options replaces the
       # configured defaults entirely; typed per-call keys merge over typed
       # defaults key-by-key, keeping the defaults' position and appending the
       # rest in caller order.
-      def options_segment(raw, typed, expiry)
-        with_expiry(variant_segment(raw, typed), expiry)
-      end
-
       def variant_segment(raw, typed)
         unless raw.nil? || typed.empty?
           raise ArgumentError,
@@ -98,6 +132,62 @@ module Audioproxy
         FALLBACK_OPTIONS
       end
 
+      # Screened on the keys as written, so an error echoes the spelling the
+      # caller typed rather than a canonical key they never saw.
+      def peaks_segment(raw, typed)
+        unless raw.nil?
+          raise ArgumentError,
+            "Audioproxy peaks_url does not take raw:, because a pre-rendered string cannot be checked " \
+            "against the options peaks accept; use url_for(source, raw: \"f:peaks/…\") to write it whole"
+        end
+
+        written = typed.keys
+        typed = Options.resolve(typed)
+        reject_expiry_option!(typed, "peaks_url")
+
+        if typed.key?(:f)
+          format = typed.delete(:f)
+          unless format == :peaks || format == "peaks"
+            key = written.find { |spelling| Options::CANONICAL[spelling.to_sym] == :f }
+            raise ArgumentError,
+              "Audioproxy peaks_url fixes the format to peaks, but was also given #{key}: #{format.inspect}; " \
+              "use url_for for any other format"
+          end
+        end
+
+        refused = written.reject { |key| [ :f, *Options::PEAKS_KEYS ].include?(Options::CANONICAL[key.to_sym]) }
+        unless refused.empty?
+          raise ArgumentError,
+            "Audioproxy peaks_url does not take #{refused.join(", ")}; peaks accept only " \
+            "#{Options::PEAKS_KEYS.join(", ")}, each also accepted spelled out. Any other option still " \
+            "enters the proxy's cache key, so it would buy a second render of identical peaks, or a 422"
+        end
+
+        # Defaults were written for audio variants, so only the ones that mean
+        # the same thing for peaks carry over; f:opus or br:96 beside f:peaks is
+        # a 422 (D10). f:peaks leads regardless, so a redundant format: cannot
+        # move it (D3). select, not slice: slice reorders by its arguments, and
+        # defaults keep the order they were written in, as they do for url_for.
+        defaults = config.default_options.select { |key, _| Options::PEAKS_DEFAULT_KEYS.include?(key) }
+        Options.render({ f: :peaks }.merge(defaults).merge(typed))
+      end
+
+      def reject_info_options!(options)
+        expiry = options.slice(*EXPIRY_KEYWORDS).compact
+        unless expiry.empty?
+          raise ArgumentError,
+            "Audioproxy info_url cannot carry an expiry (got #{expiry.keys.join(" and ")}:): the proxy's " \
+            "/info has no options segment, so there is nowhere to put exp. Info URLs do not expire"
+        end
+
+        rest = options.except(*EXPIRY_KEYWORDS)
+        return if rest.empty?
+
+        raise ArgumentError,
+          "Audioproxy info_url takes no proxy options (got #{rest.keys.join(", ")}): the proxy answers " \
+          "any options segment alongside /info with a 422. Use url_for or peaks_url to describe a variant"
+      end
+
       # exp is a *request* option: signed as path bytes, but excluded from the
       # proxy's cache key, so it is orthogonal to the variant options that
       # raw: and the typed keys describe and composes with either (D3). It goes
@@ -123,11 +213,11 @@ module Audioproxy
       # exp: written as an ordinary option skips every check in Expiry, and the
       # two mistakes it invites — a timestamp already past, a millisecond
       # timestamp — both render a URL that looks right and never works (D1).
-      def reject_expiry_option!(typed)
+      def reject_expiry_option!(typed, entry = "url_for")
         return unless typed.key?(:exp)
 
         raise ArgumentError,
-          "Audioproxy url_for does not take exp: as an option key; " \
+          "Audioproxy #{entry} does not take exp: as an option key; " \
           "pass expires_in: (a duration from now) or expires_at: (the instant), " \
           "which validate the value and do the arithmetic"
       end

data/lib/audioproxy/version.rb

@@ -1,3 +1,3 @@
 module Audioproxy
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/audioproxy.rb

@@ -19,12 +19,23 @@ module Audioproxy
       config
     end
 
-    # Single public entry point: usable from jobs, mailers and serializers of
-    # any Ruby program, Rails or not.
+    # Usable from jobs, mailers and serializers of any Ruby program, Rails or
+    # not, as are the two below.
     def url_for(source, **options)
       UrlBuilder.new(config).url_for(source, **options)
     end
 
+    # Probe metadata as JSON. Takes no proxy options and ignores the configured
+    # defaults and expiry, because /info can carry neither.
+    def info_url(source, **options)
+      UrlBuilder.new(config).info_url(source, **options)
+    end
+
+    # Waveform peaks: f:peaks fixed, and only the options peaks read.
+    def peaks_url(source, **options)
+      UrlBuilder.new(config).peaks_url(source, **options)
+    end
+
     # Anything that is not already a source String is handed to this resolver.
     # The Rails layer registers one for ActiveStorage objects; the core stays
     # ignorant of what a blob is, which is what keeps +url_for+ usable with no

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: audioproxy-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Julian Rubisch
 bindir: bin
 cert_chain: []
-date: 2026-08-13 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64