Everything That Changes the Sound

"The cache key is a promise: identical key means identical sound. Break the promise and the cache lies."

The Key Is the Whole Game

A content-addressed cache is only as good as its key. The rule is exact: the key must include the normalized text and every input that could change the resulting audio — the resolved binding, the model, the voice settings, the language, the pronunciation dictionary version, the seed, and any surrounding context. Get the list complete and the cache is a guarantee. Get it wrong and the cache becomes a confident liar.

Two Ways to Be Wrong

Leave something out — say the model version — and two genuinely different requests hash to the same key. The second one gets the first one's audio, subtly wrong and served with total confidence. That's an under-specified key, and it's the dangerous failure. The opposite mistake is an over-specified key: fold in something that doesn't affect the audio, like a timestamp, and identical requests never collide — so you pay every single time and the cache never earns its keep.

Normalize First, Then Hash

Notice that the key hashes the normalized text, not the raw text. Two inputs that differ only in ways normalization erases should produce the same audio, so they must produce the same key. That's why normalization (Track 7) runs before identity: the cache is keyed on what will actually be spoken, not on incidental differences in what was typed.

Code

The synthesis identity, field by field·python

import hashlib, json

def synthesis_identity(norm_text: str, binding: VoiceBinding, s: Settings) -> str:
    # EVERYTHING that can change the audio goes in. Miss one -> silent collision.
    material = {
        "text":         norm_text,           # NORMALIZED, not raw
        "voice_id":     binding.voice_id,    # the resolved binding
        "model":        s.model,
        "stability":    s.stability,
        "style":        s.style,
        "language":     s.language,
        "dict_version": s.dictionary_version,
        "seed":         s.seed,
        "context":      s.context,           # e.g. surrounding chunk text
    }
    blob = json.dumps(material, sort_keys=True, ensure_ascii=False).encode()
    return hashlib.sha256(blob).hexdigest()

# Add a field the day it starts affecting the audio. Never add one that doesn't.

Exercise

Pick an expensive operation you'd want to cache — an image render, a compiled asset, an LLM completion. List every input that changes its output. Then find the one people usually forget (a version, a locale, a config flag). Decide what breaks if you leave it out of the key, and what it costs if you add an input that doesn't actually matter.

Hint

Walk the operation and ask of each input: 'if only this changed, would the output change?' Yes means it belongs in the key. No means it must stay out. The forgotten input is almost always a version or a setting that lives far from the call site.