Identical audio is analyzed ONCE and served forever. This is the economic core
that makes cheap-analysis-at-scale viable, and it makes the live emotion
endpoint feel instant on repeats.
WHY: per the design, repeat calls must cost ~nothing — that's the margin story
vs cloud egress. A re-analyzed track shouldn't pay the CLAP compute twice.
WHAT:
- cache.py — content_id = sha256 of DECODED PCM (+ samplerate) so re-encodes /
re-uploads of the same sound dedupe; raw-bytes fallback for formats we can't
decode here. params_hash folds engine settings (model, bars…) so different
params cache separately. get/put (JSON inline or a result_ref path for big
artifacts), yt-id/url → content_id aliases (#29 will use them), and an
LRU/size-cap gc() that unlinks evicted artifact files (cache is transient on
the freebox — rebuildable).
- db.py — cache + aliases tables (WAL already on), LRU index on (kind, last_access).
- app.py — /v1/analyze/emotion now content-addresses the upload, serves cached
reads with X-Douanier-Cache: hit, computes+stores on miss. Engine call still
behind engines.ears (unchanged contract).
- douanier.py — cache stats / gc admin commands.
VALIDATION:
- 22/22 tests green (+7 cache: stable/decode-invariant content id, raw fallback,
miss→put→hit, params separate entries, hit counter, alias resolve, LRU gc
spares the recently-touched entry).
- Real-CLAP end-to-end: same clip twice → call 1 miss 10.6s, call 2 hit 0.002s
= 5663x speedup, identical V/A. The headline product benefit, measured.
