# audio_proxy

> An on-the-fly audio transcoding proxy. A signed URL names a source and the variant you want from it — format, bitrate, trim, fades, loudness, waveform peaks — and the proxy renders it with ffmpeg, streams it while it encodes, and caches it for later requests. URLs are the entire API: no request bodies, no server-side state, and the normalized options string is the cache key.

This is the complete reference. Everything needed to construct a correct URL and interpret every response is below; no follow-up fetch is required.

## Endpoints

```
GET /{signature}/{options}/{source}    a rendered audio variant, or waveform peaks
GET /{signature}/info/{source}         the source's own metadata, as JSON
GET /health                            liveness, unsigned
GET /ready                             readiness, unsigned
GET /metrics                           Prometheus scrape — on a separate, bind-restricted listener
```

`/metrics` is deliberately not on the main listener: it is bound to `AP_METRICS_BIND:AP_METRICS_PORT` (default `127.0.0.1:9568`), and a request for `/metrics` on the main port answers `404`.

Only `GET` and `HEAD` are served. Any other method is a `404` everywhere — a `405` would confirm a route's shape without telling a client anything useful. The single exception is `OPTIONS` when `AP_ALLOW_ORIGIN` is set, which answers the CORS preflight with `204`, `Access-Control-Allow-Methods: GET, HEAD`, an echo of `Access-Control-Request-Headers` and `Access-Control-Max-Age: 86400`.

CORS is off by default: no `Access-Control-*` header is sent anywhere, which is all an `<audio src>` needs. Set `AP_ALLOW_ORIGIN` and every response — success and error alike — carries `Access-Control-Allow-Origin`, `Access-Control-Expose-Headers: x-audio-proxy, retry-after, accept-ranges, etag`, and, for a named origin rather than `*`, `Vary: Origin`. A page that `fetch()`es peaks or `/info` cross-origin needs this, as does one that wants to read `Retry-After` off a `429` — that header is not CORS-safelisted, so without the expose list the page sees the `429` but not how long to wait.

## Signing a URL

The first path segment is the signature:

```
base64url(HMAC-SHA256(key, salt ‖ rest-of-path))
```

- `key` and `salt` are the **hex-decoded** values of the `AP_KEY` and `AP_SALT` environment variables.
- `rest-of-path` is the exact byte sequence after the signature segment, **leading `/` included**, taken from the raw — still percent-encoded — request path.
- Output is unpadded base64url. Verification also accepts the canonical single-`=` padded form. Nothing else: over-padding and the variant final characters that decode to the same bytes are rejected, so a signature has exactly two accepted spellings.

Sign the path in the spelling you will request. Re-encoding anything breaks the signature: a key containing a space must appear as `a%20track.wav` in both the signed bytes and the request. The `enc/` source form exists to sidestep this entirely.

### Worked example

Verify your implementation against these exact values before doing anything else.

<!-- signing-example:start -->
```
AP_KEY  (hex)   00112233445566778899AABBCCDDEEFF00112233445566778899AABBCCDDEEFF
AP_SALT (hex)   FFEEDDCCBBAA99887766554433221100
rest-of-path    /f:opus/br:96/plain/s3://masters/2026/piece-final.wav
signature       zfLTfPPhQ8kdeYYJOdagqPfog2nFk7KzDFUjtRAf_Ns
```
<!-- signing-example:end -->

The request is `/{signature}{rest-of-path}`:

```
/zfLTfPPhQ8kdeYYJOdagqPfog2nFk7KzDFUjtRAf_Ns/f:opus/br:96/plain/s3://masters/2026/piece-final.wav
```

In Ruby:

```ruby
require "openssl"
require "base64"

sig = Base64.urlsafe_encode64(
  OpenSSL::HMAC.digest("SHA256", [key_hex].pack("H*"), [salt_hex].pack("H*") + rest),
  padding: false
)
```

**That key is a published test vector.** Never use it as a real key; generate one with `openssl rand -hex 32`. `AP_KEY` must decode to at least 32 bytes or the proxy refuses to boot.

A deployment with `AP_ALLOW_INSECURE=true` accepts the literal segment `insecure` in place of a signature (`/insecure/f:mp3/plain/local://track.wav`). It is a development switch: while it is on, anyone who can reach the port can render anything.

## Sources

The last portion of the path names what to render, in one of two forms:

```
plain/{source}              percent-escaped, unescaped exactly once
enc/{base64url(source)}     the source as written, base64url-encoded
```

Both name the same thing and produce the same cache key. A source that already carries escapes must be escaped again in the `plain/` form, so a URL ending `a%20b.wav` is written `plain/https://h/a%2520b.wav`; `enc/` avoids the question.

Three schemes:

- `local://{path}` — a path relative to `AP_LOCAL_ROOT`. The root does not appear in the cache key, so the same relative path is the same variant however a deployment mounted it. Unset root means local sources are refused outright. Paths are confined to the root after decoding and after symlink resolution, and bounded at 64 components and 1024 bytes.
- `s3://{bucket}/{key}` — an object. Both halves required. Bounded at 63 bytes of bucket and 1024 of key.
- `https://{host}/{path}` — a URL at an origin. Bounded at 2048 bytes of URL and 253 of host. `http://` and embedded credentials (`https://user:pass@…`) are refused at the grammar.

`AP_SOURCE_ALLOWLIST` gates the two remote schemes. Entries are an exact name, a trailing-`*` prefix glob for buckets, a leading-`*.` label-anchored suffix glob for hosts, or a bare `*`. Buckets match case-sensitively, hosts fold case. **Unset accepts every bucket and refuses every host** — bucket credentials are already a gate, an outbound fetch has none.

Every source-side refusal — not allowlisted, missing, unreadable, unparseable, unknown scheme — is the same byte-identical `404`. There is no `403`, deliberately: a distinguishable response would make the source policy an existence oracle.

### The source must be audio

A source carrying a video stream is refused with `415` (`video_source`), whatever variant was asked for, on both the render path and `/info`. The audio track is not extracted. Embedded cover art is not video and renders normally.

The check costs a probe, so it does not run on a cache hit (immutable bytes that already passed it) or on `HEAD` (which spawns no subprocess). Both are ways a `200` can answer a URL whose `GET` on a miss is a `415`.

## Processing options

Options are `/`-separated `key:value` segments between the signature and the source. Order does not matter — it is normalized before hashing — but every key may appear at most once. Unknown keys, repeated keys, empty segments and valueless segments are all `422`; there is no last-write-wins and no silent ignoring, because either would let two URLs mean one variant.

<!-- options-table:start -->

| Key | Value | Meaning |
|---|---|---|
| `f` | `mp3` `opus` `ogg` `aac` `m4a` `flac` `wav` `peaks` | Output format. Default `mp3`. `aac` is an ADTS stream, `m4a` a fragmented MP4, `peaks` waveform data rather than audio |
| `br` | integer kbps, 1–10000 | CBR/ABR bitrate. Lossy formats only; excludes `q` |
| `q` | number | VBR quality on the codec's own scale. Excludes `br`; needs a format whose encoder has a scale |
| `sr` | integer Hz, 1–384000 | Resample. Default is the source's own probed rate, for every format — `norm` resamples back to it rather than overriding it. An explicit value above 48000 is refused for lossy formats, which bounds what may be *asked* for and not what a source may be: `f:aac` on a 96 kHz source returns 96 kHz |
| `ch` | `1` \| `2` | Channel count. Default follows the source — except under `f:peaks`, where it is `1` |
| `bd` | `16` \| `24` \| `32f` | Bit depth. Lossless formats only; `32f` needs `f:wav`. Default is the source's own probed depth, falling back to 16 where it cannot be read |
| `t` | `start[:duration]` seconds | Trim. `t:30` runs to the end, `t:30:15` is 15 s from 30 s. Duration must be positive |
| `fade` | `in[:out]` seconds | Fades inside the trimmed region. An omitted out-fade is `0`, not a mirror of the in |
| `gain` | signed number dB, \|value\| ≤ 100 | Static gain |
| `norm` | `ebu[:I[:TP[:LRA]]]` | EBU R128 loudness normalization. Targets default to `-16:-1.5:11`; ranges are I −70–−5, TP −9–0, LRA 1–50. Emits a resample back to the source's rate, because single-pass `loudnorm` outputs 192 kHz; the rate of the variant is therefore unchanged. Single-pass: good for previews, not for masters |
| `enhance` | `voice` | Enhancement preset: high-pass, denoise, de-ess, compress, limit — applied ahead of every other filter, and peak-limited so the preset cannot clip a source that did not. Independent of `norm`, and the two combine. A preset value is pinned to its chain forever — see *Presets are pinned* |
| `pts` | integer, 1–100000 | Peaks only: number of min/max pairs. Default `800` |
| `pk_fmt` | `json` \| `dat` | Peaks only: serialization. Default `json` |
| `dl` | filename | Sets `Content-Disposition: attachment`. Opaque, kept percent-encoded, control bytes refused |
| `cb` | opaque string | Cache-buster; participates in the cache key. Control bytes refused |
| `exp` | integer Unix seconds, 1–253402300799 | Expires the URL: a `410` from this second on. The one key excluded from the cache key — see *Expiring URLs* |

<!-- options-table:end -->

Decimals are accepted to three places (millisecond precision) and **rejected beyond that rather than rounded**, so float formatting can never destabilize a cache key. Exponent notation is rejected. `-0` is collapsed to `0` at parse time.

Codec quality scales for `q`: mp3 0–9, ogg −1–10, aac/m4a 0.1–2, opus 0–10, flac 0–12. Out of range is a `422` — `f:flac/q:13` is refused by ffmpeg itself, so refusing it here turns a `500` into a `422`.

### Cross-key rules

Each is a `422` naming the offending segment:

- `br` and `q` are mutually exclusive.
- `br` requires a lossy format (`mp3`, `opus`, `ogg`, `aac`, `m4a`).
- `q` requires a format whose encoder has a quality scale, and a value inside that codec's range.
- `bd` requires a lossless format (`flac`, `wav`); `bd:32f` requires `f:wav`.
- `pts` and `pk_fmt` require `f:peaks`.
- `f:peaks` refuses `br`, `q`, `bd` and `sr` — peaks are computed from the decoded source, so an option that cannot change the picture would hand identical bytes two cache keys. `br`, `q` and `bd` are encoder settings and peaks are never encoded; `sr` cannot move a pixel either, because bucket boundaries are a fraction of the total sample count rather than a duration. Everything that *does* change the samples applies: `t`, `ch`, `fade`, `enhance`, `gain` and `norm`, so a waveform matches the audio playing under it.
- `enhance` takes a name from a closed vocabulary (`voice` today). Anything else — including a name a future release might mint, like `voice2` — is refused rather than passed through.
- `sr` above 48000 is refused for lossy formats.
- A fade must fit inside a bounded trim, and a fade-out requires the trim to be bounded at all: its start is `duration - out`, and without a duration there is nothing to count back from. A fade-in needs no trim.

### Presets are pinned

`enhance` names a chain rather than describing one, and the name is a promise about bytes: `enhance:voice` maps to one exact filter chain, permanently.

It has to be. A variant is addressed by a key derived from the options string and served `Cache-Control: immutable`, so a chain that changed under an existing name would hand two different renders the same key — a warm CDN keeps serving the old bytes, a cold cache produces the new ones, and nothing in the URL tells them apart.

So an improved chain ships as a **new value**, `voice2`, and `enhance:voice` goes on rendering what it always rendered. Two consequences for anything generating these URLs:

- A preset name you have used before will not change what it does under you.
- A name that is not in the vocabulary yet is a `422`, not a forward-compatible no-op. Adding a preset is additive; asking for one before it exists is an error.

`enhance` runs first in the filter chain, ahead of `norm`, `gain`, the resample and the fades: it conditions the source, and every later stage is a statement about what comes out of it. That is also why it is orthogonal to `norm` rather than a substitute for it — the preset shapes dynamics, `norm` hits a loudness target, and asking for both means both.

### Expiring URLs

Options come in two classes. **Variant options** — every key above except `exp` — normalize into the canonical options string, which is the cache key, and become ffmpeg arguments. **Request options** — `exp` — are parsed, validated and signed like any other path bytes, and excluded from the canonical string, the cache key and the ffmpeg arguments.

So two URLs differing only in `exp` are one variant: identical cache key, identical arguments, coalesced into one render. That is the point of the class. A per-recipient timestamp inside the cache key would mint one render per recipient for byte-identical audio, which is what makes `exp` an option rather than a query parameter.

`exp:<unix-seconds>` refuses the request with `410 expired` from that second onwards, checked after signature verification and before any source access, so an expired URL touches no storage and starts no subprocess. It is tamper-proof for free: it is in the path, so it is in the HMAC.

Four rules to build against:

- **No clock-skew leeway.** Pad your own timestamps if you want a margin. The boundary is exclusive — a request arriving in the second `exp` names is still served.
- **A past timestamp is valid grammar.** `exp:1` signs and parses; the answer is `410`, not `422`. That is what makes the `410` a permanent, cacheable verdict rather than a parse error.
- **Both lifetimes are clamped** to at most `exp - now`: a successful response's `max-age`, and the presigned URL a `302` cache hit redirects to.
- **`/info` cannot carry `exp`** — that endpoint has no options segment.

### Waveform peaks

`f:peaks` returns [audiowaveform](https://github.com/bbc/audiowaveform)-compatible data, so it drops straight into peaks.js. `pk_fmt:json` is `application/json`:

```json
{
  "version": 2,
  "channels": 1,
  "sample_rate": 44100,
  "samples_per_pixel": 5513,
  "bits": 16,
  "length": 800,
  "data": [-31904, 31810, "…1598 more"]
}
```

`data` holds `length × 2 × channels` signed 16-bit integers: a minimum and a maximum per pixel per channel, interleaved. `bits` is always 16 and `length` always exactly `pts`. `pk_fmt:dat` is the same numbers as `application/octet-stream` — audiowaveform's binary layout, a little-endian header of version, flags, sample rate, samples-per-pixel, length and channel count, then the values as `int16`. It is roughly a fifth the size.

Peaks respect `t`, `ch` and `fade` and ignore everything about encoding. Pick `pts` to match the pixel width you will draw at.

## Cache keys

```
lowercase-hex(SHA-256(normalized-options ‖ "\n" ‖ canonical-source))
```

Normalization is what makes this deterministic: keys are sorted lexicographically, applicable defaults are materialized (`f` always; the `norm` targets when `norm` is present; `ch`, `pts` and `pk_fmt` under `f:peaks`), and every number is rendered minimally (`30`, never `30.0`). So `f:opus/br:96` and `br:96/f:opus` are one variant with one key, while any genuine difference — `cb` included — yields a different one. `exp` is the one exception, and a deliberate one: it never enters the normalized string, so two URLs differing only in their expiry are one variant.

Normalization is syntactic, not semantic: `t:0`, `fade:0:0` and `gain:0` are identity renders that keep their own keys, and therefore cost duplicate cache objects.

The response's `ETag` is this digest, quoted: the header reads `etag: "6f1c…"`, so strip the quotes before comparing it with a cache key you derived yourself.

## Responses

A request for a variant that is not stored renders it (`X-Audio-Proxy: MISS`), or attaches to a render already running for it (`COALESCED`). A request for one that is stored renders nothing (`HIT`). The three answer in different shapes:

| | `MISS` / `COALESCED` | `HIT` |
|---|---|---|
| Status | `200` | `200`, or `302` in redirect mode |
| Framing | `transfer-encoding: chunked` | `content-length` |
| `accept-ranges` | absent | `bytes` |
| A `Range` request | ignored, answered in full | `206` with the slice |

**The same URL can answer in either shape**, because which one you get depends on whether the variant happens to be cached at that moment. A client that assumes a length, or assumes a range will be honored, will be wrong on a cold cache. `content-type`, `cache-control` and `etag` are the same either way, and so are the bytes.

Bytes start arriving before the render finishes. There is no way to signal a failure that happens *after* the response has begun, so treat a chunked response that ends without its terminating chunk as a failed download.

A `Range` this proxy does not implement — several ranges at once, a unit other than `bytes` — is ignored and answers the whole variant. A range no byte of a cached variant can satisfy is a `416`.

`If-None-Match` matching the `ETag` answers `304` before anything is rendered or fetched. The signature still gates: an unsigned conditional request is a `401`.

`HEAD` on a signed URL runs signature, options, source authorization and a stat, with no body and no render. It neither decodes nor probes, so it cannot report a source ffmpeg would reject or one that turns out to be video, and it does not consult the variant cache.

### Cache-Control

| Response | `Cache-Control` |
|---|---|
| `200` media or peaks | `public, max-age=31536000, immutable, no-transform` |
| `200` from `/info` | `public, max-age=3600` |
| `404`, `413`, `415` | `max-age=10` |
| `401`, `422` | `max-age=60` |
| `410` | `public, max-age=31536000, immutable` |
| `302` cache hit, `416`, `429`, `5xx` | `no-store` |
| `/health`, `/ready`, `/metrics` | `no-store` |

A rendered variant is genuinely immutable: the URL encodes it completely. `/info` is not, because it describes a file somebody may re-upload. The `410` is the other permanent one, and for a different reason: the timestamp it is judged against is inside the signature, so no later request can make that URL valid.

Under `exp` the `max-age` of a successful response is clamped to at most `exp - now`, and the presigned URL of a `302` cache hit to the same bound. The `Cache-Control` *stored* with the variant is never clamped, because those bytes are shared by every `exp`.

## `/info`

`info` sits where the options go and answers with the source's own metadata, so a client can size a request to the file before making it:

```
GET /{signature}/info/{source}
```

```json
{"format":"wav","duration":184.32,"sample_rate":48000,"channels":2,
 "bit_depth":16,"bitrate":1536000,"size":35389532,
 "tags":{"title":"Sea Change","artist":"…"}}
```

- `format` is the `f:` token this source would be, not the container's internal name: an MP4 is `m4a`, Ogg is `opus` or `ogg` depending on contents. A container the proxy cannot itself produce is named plainly (`matroska`).
- `duration` is seconds as a float; `size` is bytes from storage; `bitrate` is bits per second.
- **A field the source cannot answer is left out, never `null`.** A lossy source has no `bit_depth`; an untagged file has no `tags`. Test for the key, not for a value.

`info` takes no processing options — `/info/br:128/…` is a `422`. `AP_MAX_SRC_BYTES` does not apply, since a probe reads headers only, and probes have their own shorter `AP_PROBE_TIMEOUT` and their own concurrency ceiling.

## Errors

Failures before the response begins are JSON, one shape everywhere:

```json
{"error": "…", "message": "…"}
```

<!-- errors-table:start -->

| Status | `error` | When |
|---|---|---|
| `401` | `invalid_signature` | Missing, malformed or wrong signature. A pure function of the URL: it will not become valid |
| `404` | `not_found` | The source is missing, unreadable, unparseable, or not one this proxy may serve. Deliberately indistinguishable — this status tells you nothing about what exists |
| `413` | `source_too_large` | The source exceeds `AP_MAX_SRC_BYTES`. Renders only; `/info` describes a source of any size |
| `415` | `undecodable_source` | The source format is not decodable, or on `/info` carries no audio at all |
| `415` | `video_source` | The source contains a video stream, and this proxy serves audio only. Cover art is not video |
| `410` | `expired` | The URL carried an `exp` that has passed. The signature verified; only the clock refused it. Permanent, and cacheable as such |
| `416` | `range_not_satisfiable` | A `Range` no byte of a cached variant can satisfy. Carries `Content-Range: bytes */size`. Unreachable on an uncached variant, where ranges are ignored |
| `422` | `invalid_options` | Invalid or conflicting options. The message names the offending segment |
| `429` | `queue_full` | A pool is full: the render queue, a wait for a render slot that ran out of budget, or the probe ceiling. Carries `Retry-After`; the causes are deliberately indistinguishable |
| `500` | `render_failed` | The render failed for a reason that is not yours. Worth retrying |
| `500` | `probe_failed` | A probe failed for a reason that is not yours. Worth retrying |
| `500` | `not_configured` | The storage backend is misconfigured — no credentials, or the wrong region or endpoint. An operator has to fix it; retrying will not |
| `502` | `upstream_unavailable` | The storage backend could not be reached. Says nothing about whether your object exists. Worth retrying |
| `504` | `render_timeout` | A render started and then exceeded `AP_RENDER_TIMEOUT`. Time spent waiting for a slot is a `429`, not this |
| `504` | `probe_timeout` | A probe exceeded `AP_PROBE_TIMEOUT`. On a render URL, the audio-only check ran out of time before encoding started |

<!-- errors-table:end -->

`/ready`'s `503` is not in this table and does not use this envelope: it is a verdict, with a body of `{"status", "queued", "threshold"}` and no `Retry-After`.

## Configuration

All configuration is `AP_`-prefixed environment variables, read and validated once at boot; a malformed value aborts startup naming the variable. Booleans accept `1`/`true`/`yes`/`on` and their negatives.

<!-- config-table:start -->
| Variable | Default | Purpose |
|---|---|---|
| `AP_PORT` | `4000` | Port the proxy listens on; `PORT` is read when it is unset |
| `AP_KEY` | unset | HMAC key for signatures, hex, ≥ 32 bytes decoded |
| `AP_SALT` | unset | HMAC salt, hex |
| `AP_ALLOW_INSECURE` | `false` | Accept the literal `insecure` in place of a signature. Development only |
| `AP_SOURCE_ALLOWLIST` | empty | Permitted buckets and hosts. Empty accepts every bucket, refuses every host |
| `AP_LOCAL_ROOT` | unset | Root for `local://` sources; unset disables them |
| `AP_VARIANT_STORE` | unset | Where completed renders are kept (`file:///path` or `s3://bucket`); unset means every request renders |
| `AP_SERVE_MODE` | `redirect` | Serve cache hits by `302` to a presigned URL, or proxied. `redirect` needs an `s3://` store |
| `AP_PRESIGN_TTL` | `300` | Seconds a hit's presigned URL stays valid |
| `AP_MAX_CONCURRENCY` | schedulers online | Simultaneous ffmpeg processes. Coalesced requests share a slot, so this counts encodes |
| `AP_MAX_PROBE_CONCURRENCY` | `4 ×` the above | Simultaneous ffprobe processes, so a probe never queues behind a render |
| `AP_QUEUE_SIZE` | `32` | Requests that may wait for a render slot before the next is `429`ed |
| `AP_READY_QUEUE_THRESHOLD` | half `AP_QUEUE_SIZE`, rounded down, minimum 1 — and `0` when `AP_QUEUE_SIZE` is `0` | Queue depth at which `/ready` answers `503`, recovering at half the threshold, rounded down. `0` disables the check |
| `AP_MAX_SRC_BYTES` | `2000000000` | Sources above this are `413`. Does not apply to `/info` |
| `AP_MAX_VARIANT_BYTES` | `AP_MAX_SRC_BYTES` | Bytes one render may hold in memory before it is killed |
| `AP_RENDER_TIMEOUT` | `300` | Seconds a render may take before it is killed and answered `504` |
| `AP_PROBE_TIMEOUT` | `10` | Seconds a probe may take before it is killed and answered `504` |
| `AP_LOG_LEVEL` | `info` | Lowest level written to stdout |
| `AP_METRICS_BIND` | `127.0.0.1` | Interface the `/metrics` listener binds. An address literal; a hostname is refused |
| `AP_METRICS_PORT` | `9568` | Port for the `/metrics` listener |
| `AP_ALLOW_ORIGIN` | unset | `*` or one origin (`https://app.example.com`). Unset sends no CORS header anywhere. An origin and nothing else, spelled as a browser spells it — a path, query, fragment, trailing slash, uppercase scheme or host, trailing dot, or explicit default port is refused at boot, with the canonical spelling in the error |
| `AP_S3_ENDPOINT` | unset | An S3-compatible store instead of AWS. Origin only |
| `AP_S3_ADDRESSING` | `virtual`, or `path` with an endpoint | Whether a request names its bucket in the host or the path |
| `AP_S3_CA_BUNDLE` | unset | PEM bundle replacing the system trust store, for a store behind a private CA |
| `AP_VARIANT_S3_ENDPOINT` | `AP_S3_ENDPOINT` | Variant store only; see the override group below |
| `AP_VARIANT_S3_ADDRESSING` | derived from `AP_VARIANT_S3_ENDPOINT` when it is set, otherwise the effective `AP_S3_ADDRESSING` | Variant store only |
| `AP_VARIANT_S3_CA_BUNDLE` | `AP_S3_CA_BUNDLE` | Variant store only |
| `AP_VARIANT_S3_ACCESS_KEY_ID` | `AWS_ACCESS_KEY_ID` | Variant store only; all-or-nothing with the secret and region below |
| `AP_VARIANT_S3_SECRET_ACCESS_KEY` | `AWS_SECRET_ACCESS_KEY` | Variant store only |
| `AP_VARIANT_S3_REGION` | `AWS_REGION` | Variant store only |
| `AP_VARIANT_S3_SESSION_TOKEN` | `AWS_SESSION_TOKEN` while the identity is inherited; unset once the store has its own | Variant store only |
<!-- config-table:end -->

S3 credentials are the standard `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_REGION` — or `AWS_DEFAULT_REGION`, which is read when `AWS_REGION` is unset — plus an optional `AWS_SESSION_TOKEN`. They are validated as a group at boot — all three or none. They come from the environment only: there is no IMDS or STS lookup, so an instance role does not work.

The variables above configure both jobs the proxy does with S3 — reading sources and keeping variants. The `AP_VARIANT_S3_*` group overrides the variant store's side alone, for cross-provider caching (sources on one provider, variants on another) or split principals (a read-only source credential, a writing store one). Every variable in it falls back to its shared counterpart, so setting none of them is exactly the single-profile behaviour above. The credential triple is all-or-nothing: setting a strict subset aborts boot naming what is missing. The session token follows the identity rather than the variable — inherited with the rest when no variant credential is set, read from `AP_VARIANT_S3_SESSION_TOKEN` alone once one is. Store operations — the boot writability probe, HEAD lookups, write-back and the presigned URL a `302` carries — all run under the store's own configuration.

## Worked requests

```bash
BASE=localhost:4000
SRC='plain/local://piece.wav'

# 30-second Opus preview at 96 kbps, starting 12.5 s in, with fades.
curl "$BASE/$SIG/f:opus/br:96/t:12.5:30/fade:0.5:1/$SRC"

# Mono 16 kHz WAV, the shape a speech-to-text pipeline wants.
curl "$BASE/$SIG/f:wav/ch:1/sr:16000/$SRC"

# Normalised to −16 LUFS for podcast delivery.
curl "$BASE/$SIG/f:mp3/br:128/norm:ebu/$SRC"

# 800 min/max pairs as JSON, to draw a waveform.
curl "$BASE/$SIG/f:peaks/pts:800/$SRC"

# Two minutes of 24-bit FLAC, offered to the browser as a download.
curl -OJ "$BASE/$SIG/f:flac/bd:24/t:60:120/dl:excerpt.flac/$SRC"

# What is this file?
curl "$BASE/$SIG/info/$SRC"
```

Each `$SIG` differs: it signs the rest of that particular path.

## Version

`0.x` means the URL contract can still change. It settles at `1.0`, after which a change to what an existing URL means, or to how cache keys are derived, is a major version.

The source of truth for this contract is [docs/audio-proxy-api-v1.md](https://github.com/audioproxy/audioproxy/blob/main/docs/audio-proxy-api-v1.md).

<!--
  Editing this file: four regions above are machine-checked, and this note
  lives at the bottom because the convention wants the H1 first.

  `test/llms_docs_test.exs` parses the three marked tables and compares
  them, as sets, against the implementation: option keys against
  `AudioProxy.Options.keys/0`, error rows against
  `AudioProxy.ErrorJSON.rows/0`, configuration variables against
  `AudioProxy.Config.variables/0`. The signing example is recomputed with
  `AudioProxy.Signature.sign/3`.

  So the tables have a fixed shape. Inside a marked region, every line that
  starts with `|` and whose first cell is a single backticked token is read as
  a row; the header and its `|---|` separator are skipped. One row per option
  key, error row and variable — do not merge, split, or annotate the first
  cell. Prose outside the markers is yours; prose inside the first cell is not.

  Variable *names* are checked, not defaults: several defaults are derived
  rather than literal, and this file and the documentation site word them
  differently for different readers. A default that moves is on you.
-->