Encode job: target=fast|optimal directive with resource-estimation-driven format selection from an acceptable list (zencodec passthrough)
- Dominant language
- Rust
- Stars
- 4.4k
- Forks
- 144
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
Add a job-level encode directive — tentatively `target=fast` / `target=optimal` — that, given a list of **acceptable output formats**, lets imageflow **choose which format + effort to encode** based on **resource estimation**, and reports back **which format was chosen and whether the result is already optimal**. The selection and cost model should be backed by **zencodec (passthrough)**, not hardcoded in imageflow.
## Motivation
Imageflow Server is adding a background re-encode queue + opt-in format negotiation using a **FastFirstThenUpgrade** strategy:
- On a cold cache miss for a request that accepts modern formats (`&accept.avif/jxl/webp`), serve a **fast** encode immediately (with a short CDN TTL), then **upgrade to the optimal encode in the background** and serve that on subsequent requests.
- For some sizes/formats the **fast encode is already optimal** (e.g. tiny images, or where the cheap codec wins on both size and time), in which case the server should skip the background upgrade and serve with a long TTL.
Today the server would have to hardcode "fast = webp, optimal = avif" heuristics. imageflow — via zencodec — is the right place to make that decision, because it knows the relative encode costs and can estimate resources for a given (dimensions, format, effort).
## Requested API (job JSON)
1. **`target` directive** on the encode step (naming TBD): `fast` | `optimal` (possibly a `balanced` middle).
- `fast`: minimize encode cost while meeting a reasonable quality bar; may pick a cheaper codec/effort.
- `optimal`: minimize output size / best RD regardless of encode cost.
2. **Acceptable-format list**: the caller passes the set of allowed output formats; imageflow picks one from it. Must be intersected with the active `SecurityOptions`/killbits caps (an upgrade can't bypass policy).
3. **Resource estimation**: expose (or use internally) an estimate of encode cost (time / CPU / peak memory) per (dimensions, format, effort), sourced from zencodec. Useful both to drive `target` and to let the server budget background work.
4. **Result annotations** — the job result should report:
- the **chosen format + effort**,
- an **`is_optimal` / `would_not_improve` flag** so the caller knows whether a background upgrade is worthwhile,
- optionally the resource estimate used.
This should extend the existing codec-substitution annotation surface rather than add a parallel one.
5. **zencodec passthrough**: format selection, the effort ladder, the cost model, and the optimality determination live in zencodec; imageflow forwards the directive and surfaces the annotations.
## Notes / constraints
- Determinism: given the same inputs + cost-model version, the chosen format/effort must be stable — downstream cache keys depend on the resolved `format`, so non-determinism would fragment caches.
- The acceptable list intersect with `SecurityOptions` must happen before selection, and a fully-denied list should surface the existing killbits denial path.
## Consumer
Imageflow Server's background re-encode queue + format negotiation (`AddImageflowBackgroundReencoding` / `SetFormatNegotiation`). Companion .NET binding issue: imazen/imageflow-dotnet (linked below once filed).
Contributor guide
Assessment
This issue has not been assessed yet.