# audio_proxy v0.4.0 - Table of Contents

> On-the-fly audio transcoding proxy: renders variants (transcodes, trimmed previews, waveform peaks) from signed URLs, streams them while they encode, and caches them for range-capable serving.

## Pages

- [audio_proxy](readme.md)
- [Audio Proxy — API v1 (draft)](audio-proxy-api-v1.md)
- [Source resolution](sources.md)
- [S3-compatible providers](s3-providers.md)
- [Rendering](rendering.md)
- [How options become ffmpeg arguments](ffmpeg-arguments.md)
- [Running more than one node](scaling.md)
- [Capacity: sizing a container](capacity.md)
- [llms](llms.md)
- [llms-full](llms-full.md)
- [Pinned versions](versions.md)
- [LICENSE](license.md)

## Modules

- [AudioProxy](AudioProxy.md): An imgproxy-style on-the-fly audio transcoding proxy.
- [AudioProxy.Application](AudioProxy.Application.md): OTP application entry point.
- [AudioProxy.CacheKey](AudioProxy.CacheKey.md): Variant identity: the object key under which a rendered variant is cached.
- [AudioProxy.Config](AudioProxy.Config.md): Runtime configuration, read from `AP_`-prefixed environment variables.
- [AudioProxy.ErrorJSON](AudioProxy.ErrorJSON.md): The §5 error contract as one table: structured error in, response out.
- [AudioProxy.Ffmpeg.Command](AudioProxy.Ffmpeg.Command.md): Normalized options → ffmpeg argument vector (API doc §3).
- [AudioProxy.Ffmpeg.Render](AudioProxy.Ffmpeg.Render.md): One render: a subprocess spawned from an argv list, its stdout streamed to a
consumer as ordered chunks.
- [AudioProxy.Ffmpeg.RenderSupervisor](AudioProxy.Ffmpeg.RenderSupervisor.md): Supervises the running renders — one child per subprocess.
- [AudioProxy.Ffprobe](AudioProxy.Ffprobe.md): One probe: `ffprobe` run against a source, its JSON collected, and the §4
contract filtered out of it.
- [AudioProxy.LogHandler](AudioProxy.LogHandler.md): Turns telemetry into the log an operator reads: one line per request, plus
the render lifecycle behind it.
- [AudioProxy.Metrics](AudioProxy.Metrics.md): The four operator signals, aggregated from telemetry and exposed to a
scraper: saturation, latency, cache efficiency, errors.
- [AudioProxy.Metrics.Exposition](AudioProxy.Metrics.Exposition.md): The Prometheus text exposition format (version 0.0.4), as string assembly.
- [AudioProxy.Metrics.Router](AudioProxy.Metrics.Router.md): The scrape surface, and nothing else.
- [AudioProxy.OptionError](AudioProxy.OptionError.md): A rejected options segment, as data (API doc §3, §5).
- [AudioProxy.Options](AudioProxy.Options.md): The processing-options grammar (API doc §3): parse, validate, normalize.
- [AudioProxy.Peaks](AudioProxy.Peaks.md): Raw `s16le` PCM in, waveform peaks out (API doc §3.3).
- [AudioProxy.Peaks.Render](AudioProxy.Peaks.Render.md): A peaks render: probe, decode, reduce, serialize — behind
`AudioProxy.Ffmpeg.Render`'s contract.
- [AudioProxy.Plugs.Action](AudioProxy.Plugs.Action.md): Picks the action at the end of the signed chain: render, or info.
- [AudioProxy.Plugs.InfoAction](AudioProxy.Plugs.InfoAction.md): The info endpoint's action (API doc §2, §4): stat, probe, JSON.
- [AudioProxy.Plugs.ParseOptions](AudioProxy.Plugs.ParseOptions.md): Splits the verified rest-of-path into its options half and source half, and
parses the options (API doc §1, §3).
- [AudioProxy.Plugs.RenderAction](AudioProxy.Plugs.RenderAction.md): The render endpoint's action: everything between "every check passed" and
bytes on the socket.
- [AudioProxy.Plugs.RenderPipeline](AudioProxy.Plugs.RenderPipeline.md): The signed chain (API doc §2): verify, parse, resolve, act.
- [AudioProxy.Plugs.ResolveSource](AudioProxy.Plugs.ResolveSource.md): Parses the source half of the path into a typed source and authorizes it
(API doc §1, §5).
- [AudioProxy.Plugs.VerifySignature](AudioProxy.Plugs.VerifySignature.md): Gate for the signed URL space (API doc §1/§2).
- [AudioProxy.ProbeCoordinator](AudioProxy.ProbeCoordinator.md): One `ffprobe` per in-flight source, shared by everyone who asks about it.
- [AudioProxy.ProbeLimiter](AudioProxy.ProbeLimiter.md): The probe budget: at most `AP_MAX_PROBE_CONCURRENCY` `ffprobe` processes at
once, and no queue behind them.
- [AudioProxy.Readiness](AudioProxy.Readiness.md): Whether this node should be sent new work — the state behind `GET /ready`.
- [AudioProxy.RenderCoordinator](AudioProxy.RenderCoordinator.md): One render per in-flight cache key, shared by everyone who asks for it.
- [AudioProxy.Router](AudioProxy.Router.md): Top-level HTTP router.
- [AudioProxy.S3](AudioProxy.S3.md): The five S3 operations this proxy needs, over `ex_aws_s3`.
- [AudioProxy.S3.HttpClient](AudioProxy.S3.HttpClient.md): `ex_aws`'s HTTP client behaviour, over OTP's `:httpc`.
- [AudioProxy.Semaphore](AudioProxy.Semaphore.md): The render-slot budget: at most `AP_MAX_CONCURRENCY` renders at once, with at
most `AP_QUEUE_SIZE` waiting behind them.
- [AudioProxy.Signature](AudioProxy.Signature.md): URL signature generation and verification (API doc §1).
- [AudioProxy.Source](AudioProxy.Source.md): The source segment (API doc §1): encodings, decoding, dispatch, identity.
- [AudioProxy.Source.Allowlist](AudioProxy.Source.Allowlist.md): `AP_SOURCE_ALLOWLIST`: which buckets and hosts a remote source may name.
- [AudioProxy.Source.Https](AudioProxy.Source.Https.md): The `https://` source type: audio fetched from an origin over TLS.
- [AudioProxy.Source.Local](AudioProxy.Source.Local.md): The `local://` source type: files under one configured directory.
- [AudioProxy.Source.S3](AudioProxy.Source.S3.md): The `s3://` source type: an object in a bucket.
- [AudioProxy.Source.Type](AudioProxy.Source.Type.md): The contract a source type implements (API doc §1).
- [AudioProxy.Telemetry](AudioProxy.Telemetry.md): The render lifecycle as `:telemetry` events — the one instrumentation point
every consumer reads.
- [AudioProxy.VariantCache](AudioProxy.VariantCache.md): Serving a variant that is already in the store — everything a client can
observe about a cache HIT.
- [AudioProxy.VariantStore](AudioProxy.VariantStore.md): The contract a variant store backend implements, and the dispatch to the
configured one.
- [AudioProxy.VariantStore.Local](AudioProxy.VariantStore.Local.md): The `file://` variant store: a directory tree under the configured root.
- [AudioProxy.VariantStore.S3](AudioProxy.VariantStore.S3.md): The `s3://` variant store: one object per variant in a bucket.
- [AudioProxy.VariantStore.Tee](AudioProxy.VariantStore.Tee.md): The write-back: a coordinator subscriber that streams a render into the
variant store.

- Exceptions
  - [AudioProxy.Config.Error](AudioProxy.Config.Error.md): Raised when an `AP_`-prefixed variable holds an unusable value.
  - [AudioProxy.VariantStore.Tee.Abort](AudioProxy.VariantStore.Tee.Abort.md): Raised inside the tee's chunk stream when the render fails, is cancelled,
or goes silent — the signal `put_stream/3` turns into discard-and-return.
Never an error worth reporting: the render's own path already has.

