# foley

> Unified facade for sourcing, indexing, and searching sound effects to weave into narration


## Pages in this subsection

- [foley](foley.html.md): foley — a retrieval-first façade for sound effects.
- [foley.audio](foley.audio.html.md): Audio I/O and DSP primitives for foley.
- [foley.index](foley.index.html.md): foley INDEX stage — make every sound findable by keyword *and* meaning.
- [foley.index.taxonomy](foley.index.taxonomy.html.md): UCS + AudioSet taxonomy: the `tags -> UCS CatID` resolver for foley.
- [foley.index.taxonomy.audioset](foley.index.taxonomy.audioset.html.md): AudioSet-label -> UCS-CatID overlap map (report 04 §5.3, [11 §3.1]).
- [foley.index.taxonomy.model](foley.index.taxonomy.model.html.md): Data structures for the UCS/AudioSet taxonomy resolver (stdlib-only).
- [foley.index.taxonomy.resolver](foley.index.taxonomy.resolver.html.md): Resolve free tags/caption/labels to a UCS CatID (the EnvSound-UCS pipeline).
- [foley.index.taxonomy.seed](foley.index.taxonomy.seed.html.md): Seed taxonomy data — a representative in-code UCS subset + AudioSet overlap map.
- [foley.index.taxonomy.ucs](foley.index.taxonomy.ucs.html.md): UCS table loading + the UCS-filename CatID parse (report 04 §5.2, §6.4).
- [foley.index.embedders](foley.index.embedders.html.md): Embedders — the joint text<->audio space that powers retrieval.
- [foley.index.indexes](foley.index.indexes.html.md): Concrete vector + keyword index backends (the swappable retrieval engines).
- [foley.index.ingest](foley.index.ingest.html.md): The ingestion pipeline — turn any audio file into a searchable SoundRecord.
- [foley.index.library](foley.index.library.html.md): The `SoundLibrary` façade — one searchable, license-aware sound library.
- [foley.index.protocols](foley.index.protocols.html.md): Structural contracts for the foley index (the retrieval boundary).
- [foley.index.search](foley.index.search.html.md): Hybrid retrieval: reciprocal rank fusion over a vector list and a keyword list.
- [foley.index.taggers](foley.index.taggers.html.md): Taggers — auto-fill a sound’s semantic labels on ingest (report 03).
- [foley.obs](foley.obs.html.md): Observability & the reproducible run-artifact for foley (#11).
- [foley.obs.recorder](foley.obs.recorder.html.md): The run-recorder: owns the manifest, drives the OTel mirror, off by default (#11).
- [foley.obs.redact](foley.obs.redact.html.md): Redaction of sensitive narration / prompt / query text in telemetry (#11).
- [foley.obs.run_artifact](foley.obs.run_artifact.html.md): The reproducible run-artifact SSOT — `RunManifest` + `SpanRecord` (#11).
- [foley.obs.trace](foley.obs.trace.html.md): The OpenTelemetry MIRROR seam for foley’s observability (#11).
- [foley.agent](foley.agent.html.md): The SELECT stage — the search-agent that finds the right sound for a context (#7).
- [foley.agent.decompose](foley.agent.decompose.html.md): `decompose_context` — narrative passage → a sparse, salience-ranked event list.
- [foley.agent.llm](foley.agent.llm.html.md): Which LLM the SELECT rungs use — one explicit, spend-safe resolver (the `llm=` seam).
- [foley.agent.local_llm](foley.agent.local_llm.html.md): Offline / local-LLM SELECT rungs — OpenAI-compatible `Decomposer` / `Judge` / `Refiner`.
- [foley.agent.mcp](foley.agent.mcp.html.md): The MCP surface — foley’s façade as agent-callable tools (py2mcp, #12, report 05/10).
- [foley.agent.policy](foley.agent.policy.html.md): The SELECT policy: the fail-closed rights gate + the single generate-vs-retrieve branch.
- [foley.agent.preview](foley.agent.preview.html.md): Audition UX — preview a sound, find similar ones, and refine by relevance feedback (#12).
- [foley.agent.protocols](foley.agent.protocols.html.md): The structural DI seams of the SELECT stage — `Decomposer` / `Judge` / `Refiner`.
- [foley.agent.refine](foley.agent.refine.html.md): `refine_query` — one event query → 2–4 paraphrases for multi-query retrieval.
- [foley.agent.session](foley.agent.session.html.md): Session-scoped audition state — cached candidates, picks, and rejects (#12).
- [foley.agent.tools](foley.agent.tools.html.md): The SELECT orchestration: `find()` / `plan()` + the small pure tool wrappers.
- [foley.agent.verify](foley.agent.verify.html.md): `verify_match` — the retrieve→verify ladder (clap → listen → judge) + `Judge` impls.
- [foley.weave](foley.weave.html.md): Page content
- [foley.eval](foley.eval.html.md): Tier-1 retrieval evaluation — metrics, a frozen golden set, and the nDCG gate.
- [foley.eval.baseline](foley.eval.baseline.html.md): The committed nDCG baseline — the PR gate’s SSOT + staleness stamps.
- [foley.eval.embedder](foley.eval.embedder.html.md): A deterministic, numpy-only text embedder for the retrieval eval gate.
- [foley.eval.fidelity](foley.eval.fidelity.html.md): Set-level generation-fidelity — Fréchet Audio Distance (FAD) + Kernel Audio Distance (KAD).
- [foley.eval.fit](foley.eval.fit.html.md): Tier-2 fit evaluation — “does the accepted clip actually match the intent?” (report 08 §2/§5).
- [foley.eval.golden](foley.eval.golden.html.md): The frozen golden set + the deterministic Ring-0 retrieval harness.
- [foley.eval.reliability](foley.eval.reliability.html.md): Inter-rater reliability — Krippendorff’s α + the judge-vs-human calibration guardrail.
- [foley.eval.retrieval](foley.eval.retrieval.html.md): Tier-1 retrieval metrics + run assembly — pure stdlib, CI-safe, ranx-exact.
- [foley.provenance](foley.provenance.html.md): Provenance layer for foley — attribution/credits (and, later, disclosure).
- [foley.provenance.credits](foley.provenance.credits.html.md): TASL attribution / credits generator — the provenance render layer (#9a).
- [foley.provenance.disclosure](foley.provenance.disclosure.html.md): Disclosure, watermarking & safety for AI-generated audio (#9b).
- [foley.agent_kit](foley.agent_kit.html.md): Install foley’s shipped agent kit — the consumer skill + Claude slash command + subagent.
- [foley.base](foley.base.html.md): Canonical data models for foley — the single source of truth (SSOT) types.
- [foley.cli](foley.cli.html.md): The `foley` command-line interface (stdlib `argparse`, zero new deps).
- [foley.cost](foley.cost.html.md): Cost: what a call will cost before it is made, and a cumulative cap on a run (#57).
- [foley.licensing](foley.licensing.html.md): License policy for foley: the license_id -> flag-set SSOT, flag derivation
- [foley.qc](foley.qc.html.md): Tier-0 deterministic audio QC for foley (research report 08 §3).
- [foley.requirements](foley.requirements.html.md): Onboarding — check what foley needs, tell the user how to get it (accompy-style, #12).
- [foley.runtime](foley.runtime.html.md): Runtime posture — local-first / offline mode as one verifiable contract (#12, report 12).
- [foley.sources](foley.sources.html.md): Bulk-corpus source adapters for foley’s SOURCE stage.
- [foley.sources.base](foley.sources.base.html.md): The bulk-corpus source contract — a downloaded corpus as an ingestable stream.
- [foley.sources.bbc_remarc](foley.sources.bbc_remarc.html.md): BBC RemArc (Rewind Archive) — a Ring-2, quarantined corpus.
- [foley.sources.clotho](foley.sources.clotho.html.md): Clotho-eval — a captioned Ring-0 corpus that doubles as a retrieval fixture.
- [foley.sources.elevenlabs](foley.sources.elevenlabs.html.md): ElevenLabs Sound Effects generate source (hosted; #6).
- [foley.sources.elevenlabs.adapter](foley.sources.elevenlabs.adapter.html.md): ElevenLabs Sound Effects generate adapter — hosted Text-to-SFX v2 over HTTP.
- [foley.sources.elevenlabs.config](foley.sources.elevenlabs.config.html.md): `SOURCE_CONFIG` for the ElevenLabs Sound Effects generator (report 02 · 07 · 10 §4.1).
- [foley.sources.foleyset](foley.sources.foleyset.html.md): FoleySet — a CC-BY, Foley-native starter corpus (Ring 0).
- [foley.sources.freesound](foley.sources.freesound.html.md): Freesound APIv2 retrieve source — CC0 sounds, stored by-reference (`foley[freesound]`).
- [foley.sources.freesound.adapter](foley.sources.freesound.adapter.html.md): Freesound APIv2 retrieve adapter — CC0 sounds, stored strictly by-reference.
- [foley.sources.freesound.config](foley.sources.freesound.config.html.md): `SOURCE_CONFIG` for the Freesound APIv2 retrieve source (report 01 · 07 · 10 §4.1).
- [foley.sources.fsd50k](foley.sources.fsd50k.html.md): FSD50K — the labeled, commercial-safe backbone corpus (Ring 1).
- [foley.sources.http](foley.sources.http.html.md): Injectable HTTP transport for foley’s live source adapters.
- [foley.sources.pull](foley.sources.pull.html.md): `add_from` — the live-source pull façade (SOURCE → INDEX in one call).
- [foley.sources.registry](foley.sources.registry.html.md): Live-source adapter registry: auto-discovery + lazy loading (arioso’s registry, ported).
- [foley.sources.resilience](foley.sources.resilience.html.md): Graceful degradation for HTTP source adapters — throttle · backoff · circuit-break (#12).
- [foley.sources.sonniss](foley.sources.sonniss.html.md): Sonniss GameAudioGDC — a Ring-2, quarantined corpus.
- [foley.sources.stable_audio](foley.sources.stable_audio.html.md): Stable Audio Open 1.0 generate source (local default; #6).
- [foley.sources.stable_audio.adapter](foley.sources.stable_audio.adapter.html.md): Stable Audio Open 1.0 generate adapter — local `diffusers` inference.
- [foley.sources.stable_audio.config](foley.sources.stable_audio.config.html.md): `SOURCE_CONFIG` for the local Stable Audio Open 1.0 generator (report 02 · 07 · 10 §4.1).
- [foley.stores](foley.stores.html.md): dol-backed storage for foley: content-addressed bytes + a metadata store.
- [foley.weave.align](foley.weave.align.html.md): Forced-alignment adapters — the `Aligner` seam’s fake default + WhisperX real impl.
- [foley.weave.anchor](foley.weave.anchor.html.md): Symbolic-anchor → sample-onset heuristics — the SELECT→WEAVE timing bridge (report 06 §2.4).
- [foley.weave.master](foley.weave.master.html.md): Mastering — loudness-normalize + true-peak-limit the finished mix (report 06 §5).
- [foley.weave.mix](foley.weave.mix.html.md): Pure-numpy mixing DSP — making a clip sit under the voice (report 06 §3).
- [foley.weave.protocols](foley.weave.protocols.html.md): The structural DI seams of the WEAVE stage — `Aligner` / `ApplyStrategy`.
- [foley.weave.reaction](foley.weave.reaction.html.md): Audience-reaction timing — a crowd answers an event, it does not coincide with it.
- [foley.weave.requirements](foley.weave.requirements.html.md): System-dependency onboarding for WEAVE’s optional upgrade paths (accompy-style).
- [foley.weave.timeline](foley.weave.timeline.html.md): The sound-design timeline as an editable document — hydrate, edit, caption.

## Optional

- [Top-level llms.txt](../llms.txt): Complete documentation index.