foley

foley — a retrieval-first façade for sound effects.

foley finds (or generates) the right sound effect for a moment of narration and weaves it in. It is the SFX sibling of arioso (a unified façade over AI music-generation backends): one simple surface over many sound sources (a bring-your-own library, service APIs like Freesound, and generative-AI models), a searchable index of every sound (by keyword and meaning, via CLAP embeddings + hybrid search), an agent that selects the right sound for a narrative context, and a compositor that places it under the voice.

Four stages:

SOURCE  ->  INDEX  ->  SELECT  ->  WEAVE
(get)      (find)      (choose)    (compose)

The façade (v1 — Epic #13 complete; the surface below is live — see misc/docs/design.md / misc/docs/roadmap.md for the roadmap):

import foley

foley.find("She pushed open the heavy oak door; rain hammered outside.")
foley.search("distant thunder rumble", k=10)
foley.generate("a single wooden door creak", backend="stable_audio")
foley.ingest("~/my_sounds/")

The design is grounded in the research reports under misc/docs/research/.

The whole four-stage surface (source → index → select → weave) plus the MCP server and the licensing/provenance, evaluation, and observability layers is implemented and re-exported here (see __all__ and the find / search / generate / ingest / weave façade functions below). The retrieval-agnostic foundation every later stage stands on:

• Data models (foley.base) — the SSOT dataclasses/enums shared across layers (SoundRecord, LicenseRecord, Candidate, SoundEvent, Verdict, IntendedUse), the two affordance registries, and generic dict/JSON (de)serialization.

• License policy (foley.licensing) — the license_id -> flag-set SSOT (LICENSE_FLAGS), flag derivation, and the fail-closed keep() gate.

• Storage (foley.stores) — content-addressed byte store + metadata store built from dol, and store_sound() (the by-value vs by-reference gate driven by LicenseRecord.cache_bytes_ok).

• QC (foley.qc) — Tier-0 deterministic audio checks (run_qc() -> QCReport, thresholds in QCThresholds).

• Audio (foley.audio) — I/O + DSP primitives. Exposed as a submodule (foley.audio) with the key functions also re-exported here.

Import cost: import foley pulls only dol (a light core dependency used by foley.stores); numpy/soundfile/soxr/librosa/pyloudnorm are lazy-imported inside the audio/QC functions that need them (install via the foley[audio] extra), so a bare install imports cleanly.

class foley.AcquisitionMethod(value)

How a sound entered foley (retrieval channel or origin).

class foley.Affordance(name: str, type: type, description: str, default: Any = None, stage: str = 'query')

Descriptor for a unified parameter affordance (arioso analog).

name

Canonical parameter name used at the façade level.

Type:

str

type

Expected Python type.

Type:

type

description

Human-readable description.

Type:

str

default

Default value (None = no default / required).

Type:

Any

stage

'query' (search/find/filter) or 'generate'.

Type:

str

class foley.Anchor(value)

How a WEAVE Placement binds its symbolic time to the narration (report 06 §2.4).

absolute is a fixed offset; the rest resolve against the forced-aligned word_timeline — word to a trigger word’s onset, sentence across a sentence span, scene/paragraph to a boundary’s first spoken word.

class foley.Budget(max_refine_loops: int = 1, max_generations: int = 1, allow_generate: bool = True, _refines: int = 0, _gens: int = 0)

Bounded-cost accounting for the per-event refine/generate loops.

Prevents unbounded cost on a hard event. The loop calls refine_ok() / gen_ok() to test, then spend_refine() / spend_gen() to charge.

gen_ok() → bool

Whether a generation fallback is allowed and within budget.

refine_ok() → bool

Whether another refine→re-retrieve pass is within budget.

reset() → None

Zero the spend counters so the caps apply per event, not per passage.

The find loop calls this at the top of each event so one hard event’s refine/generate spend never starves later events (the documented per-event semantics).

spend_gen() → None

Charge one generation.

spend_refine() → None

Charge one refine loop.

class foley.Candidate(sound: SoundRecord, origin: CandidateOrigin = CandidateOrigin.retrieved, event: SoundEvent | None = None, clap_score: float | None = None, bm25_score: float | None = None, rrf_score: float | None = None, rerank_score: float | None = None, verdict: Verdict | None = None, license_ok: bool | None = None, preview_uri: str | None = None)

A ranked, license-checked, (optionally) verified sound for one SoundEvent.

Retrieval and generation return the SAME shape; only origin differs. Nested sound / event / verdict dataclasses are decoded generically by _decode() — no per-field code needed.

class foley.CandidateOrigin(value)

Whether a candidate was retrieved from the index or freshly generated.

class foley.Captioner(*args, **kwargs)

Produce one natural-language sentence describing a clip (report 03).

The caption feeds the BM25 keyword index and human display. Default is a dedicated AAC model (EnCLAP); Qwen2-Audio is a richer promptable upgrade. Both are foley[caption] adapters plugged in behind this protocol.

caption(wav: ndarray, sr: int) → str

Return a one-sentence caption for the clip.

class foley.CatIdResolution(catid: str | None = None, category: str | None = None, subcategory: str | None = None, source: str | None = None, confidence: float = 0.0, matched_terms: list[str] = <factory>)

The result of resolving free tags/caption/labels to a UCS CatID.

catid feeds ucs_category and subcategory feeds ucs_subcategory on ingest, and ucs_catid on the query side.

class foley.ClapEmbedder(model_id: str = 'laion/larger_clap_general', *, device=None)

LAION-CLAP text<->audio embedder (the default retrieval engine).

Returns L2-normalized float32 embeddings so a plain inner product is cosine similarity. embed_text always returns a 2-D (n, dim) array; embed_audio returns a 1-D (dim,) array for one clip.

model_id

The HF checkpoint id.

dim

The embedding dimensionality.

property device: str

The resolved torch device string ('cuda'/'cpu').

property dim: int

The embedding dimensionality (512 for the default; resolved for others).

For a non-default checkpoint this fetches only the model’s config.json (via AutoConfig) — never the ~1.7 GB weights — so building an index for it does not force a model download. Falls back to the loaded model’s config if the standalone config lacks projection_dim.

embed_audio(wav: ndarray, sr: int) → ndarray

Embed one audio clip -> (dim,) L2-normalized.

The clip is down-mixed to mono and resampled to 48 kHz (what CLAP expects) via foley.audio before embedding.

Parameters:

• wav – A working-array clip (float32; mono or multichannel).

• sr – The clip’s sample rate in Hz.

embed_text(text: str | list[str]) → ndarray

Embed one or more query strings -> (n_texts, dim) L2-normalized.

class foley.ClapZeroShotTagger(*, embedder=None, labels: Sequence[str] | None = None, prompt: str = 'this is a sound of {label}', threshold: float = 0.0)

Zero-shot tagger: score a clip against a label set via CLAP cosine.

Reuses a ClapEmbedder (the same model the Index uses), so the audio is embedded in the same joint space as the label prompts and no extra weights load. The default label set is the UCS subcategory names (foley’s own vocabulary), so tags land in-taxonomy.

property embedder

The CLAP embedder (injected or the process-wide default).

property labels: list[str]

natural UCS category subcategory phrases).

Natural multi-word phrases ("weather rain", "glass break") are far better CLAP prompts — and better BM25 tags / taxonomy-resolver input — than bare abstract subcategory words ("Break", "Buzz"), which are a known zero-shot artifact (anomalously close to everything). Absolute tag-quality calibration (thresholds, label curation) is an eval-harness concern (#10).

Type:

The label vocabulary (default

tag(wav: ndarray, sr: int, *, taxonomy: str = 'custom', top_k: int = 10) → list[tuple[str, float]]

Return the top-k (label, cosine) tags for the clip, best first.

tag_vector(audio_vec: ndarray, *, top_k: int = 10) → list[tuple[str, float]]

Score a precomputed (L2-normalized) audio vector against the labels.

The efficiency seam (report 03 Part 2): the Index already embeds every sound with this model, so on ingest the retrieval vector is reused here — no second CLAP forward pass.

class foley.CreditEntry(sound_id: str, title: str | None = None, author: str | None = None, author_url: str | None = None, source: str | None = None, source_url: str | None = None, license_id: str = 'unknown', license_name: str | None = None, license_url: str | None = None, modified: bool = False, requires_attribution: bool = False, attribution_text: str | None = None, notice_text_required: str | None = None, is_ai_generated: bool = False, generator_model: str | None = None, disclosure_recommended: bool = False, watermark: dict | None = None, c2pa_manifest_ref: str | None = None)

One rendered TASL credit for a single sound (a flat, serializable row).

Built by credit_entry() from a record’s rights fields; rendered to a single attribution line by attribution_line(). Carries the AI-disclosure + watermark / C2PA fields as pass-throughs so the JSON manifest becomes the content-credentials carrier once #6/#9b populate them (None today).

class foley.Credits(entries: tuple[CreditEntry, ...] = (), title: str = 'Credits', schema_version: int = 1)

A deduplicated, ordered collection of CreditEntry for one run.

Iterable and sized; renders to CREDITS.md via markdown and to a JSON manifest via manifest (== to_dict()). Both are deterministic (no timestamps) and diffable.

property manifest: dict

The machine-readable JSON manifest (a plain dict).

property markdown: str

The rendered CREDITS.md document.

class foley.Decision(action: DecideAction, candidate: Candidate | None = None, reason: str = '')

The tiny result of decide(); reason feeds the refine hint + the audit Step.

class foley.Embedder(*args, **kwargs)

A joint text<->audio embedding space (CLAP by default).

One space serves both text->audio search (embed_text a query) and audio<->audio similarity (embed_audio a clip). Implementations MUST return L2-normalized float32 arrays so a plain inner product is cosine similarity, and MUST stamp model_id/dim so mixed-model libraries stay coherent (each SoundRecord records the embedding_model/embedding_dim it was indexed under).

model_id

The checkpoint id (e.g. 'laion/larger_clap_general').

Type:

str

dim

The embedding dimensionality (e.g. 512).

Type:

int

embed_audio(wav: ndarray, sr: int) → ndarray

Embed one audio clip.

Parameters:

• wav – A working-array clip (float32, mono preferred). CLAP expects 48 kHz; implementations resample as needed.

• sr – The clip’s sample rate in Hz.

Returns:

A 1-D (dim,) L2-normalized float32 array.

embed_text(text: str | list[str]) → ndarray

Embed one or more query strings.

Parameters:

text – A single string or a list of strings.

Returns:

A 2-D (n_texts, dim) L2-normalized float32 array (n_texts is 1 for a single string) — always 2-D so callers can index [0] for the single-query case.

class foley.FusedHit(id: str, rrf_score: float | None = None, clap_score: float | None = None, bm25_score: float | None = None)

One fused retrieval hit: an id plus the scores that produced it.

The raw component scores are carried through (not just the fused rank score) so the façade can stamp them onto a Candidate (clap_score / bm25_score / rrf_score) for display and debugging.

id

The sound id.

Type:

str

rrf_score

The fused RRF score (None for a pure-vector search).

Type:

float | None

clap_score

Cosine similarity from the vector ranker (None if the id appeared only in the keyword list).

Type:

float | None

bm25_score

BM25 score from the keyword ranker (None if the id appeared only in the vector list).

Type:

float | None

exception foley.GenerationError(message: str, *, report: IngestReport, status: str | None)

Raised by foley.generate() when a backend yields no stored sound.

Carries the full IngestReport and the terminal status so a caller can react distinctly to quarantined (QC-rejected — e.g. regenerate), rights_blocked, or error. The lower-level generate() workhorse never raises this — it always returns an inspectable report; only the public foley.generate() promise raises.

report

The IngestReport from the run.

status

The terminal IngestResult status ('quarantined' | 'rights_blocked' | 'error' | …).

class foley.IngestReport(root: str, results: list[IngestResult] = <factory>)

The rolled-up outcome of a folder ingest (JSON-serializable).

error(path, exc: Exception) → None

Record a per-file error without aborting the run.

property errored: list[IngestResult]

Results that raised during ingest.

property ingested: list[IngestResult]

Results that were added to the library (pass or warn).

property quarantined: list[IngestResult]

Results rejected by the QC gate.

record(result: IngestResult) → None

Append one IngestResult.

property rights_blocked: list[IngestResult]

Results refused by the fail-closed AI-training/license rights gate.

property skipped: list[IngestResult]

Results skipped as content-addressed duplicates.

summary() → dict

A counts dict for a console/CLI summary.

class foley.IngestResult(id: str, status: str, record: SoundRecord | None = None, qc: dict | None = None, notes: list = <factory>, error: str | None = None)

The outcome of ingesting one clip.

status: 'pass'/'warn' (ingested), 'quarantined' (QC-rejected, not added), 'skipped_dup' (content already in the library), 'rights_blocked' (license forbids AI training / embedding, refused before embed — see ingest_one()), 'skipped_license' (dropped by a bootstrap commercial-use / fail-closed license filter), or 'error'. record is present only when the clip was ingested.

class foley.IntendedUse(commercial: bool = True, publish: bool = True, redistribute_standalone: bool = False, will_train: bool = False, can_attribute: bool = True, revenue_usd: int = 0, allow_voice_or_trademark: bool = False)

What the caller intends to do with a sound; consumed by keep().

class foley.Judge(*args, **kwargs)

One rung of the verify ladder: does this candidate match this event? (report 10 §4.2).

level selects the rung — clap (cheap score gate), listen (audio-LM), judge (LLM arbitration + scene consistency). The returned Verdict carries level == the rung that produced it. Only the judge rung’s real impl calls the LLM.

class foley.KeywordIndex(*args, **kwargs)

BM25 / full-text index over each sound’s tags + caption.

The default is LanceDB’s Tantivy FTS (report 04 §3.4); SQLite FTS5 is the single-file fallback. Same where push-down contract as VectorIndex.

bm25(query: str, k: int, *, where: dict | None = None) → list[tuple[str, float]]

Return the top-k BM25 matches for query, best first.

Parameters:

• query – A natural-language / keyword query.

• k – Number of matches to return.

• where – Optional metadata predicates for push-down filtering.

Returns:

[(id, bm25_score), ...] in descending-score order.

index(id: str, text: str, meta: dict) → None

Insert or replace the searchable text (and light metadata) for id.

class foley.LanceIndex(*, uri, dim: int, table_name: str = 'sounds')

LanceDB-backed index: one table with a vector column + a native FTS index.

Writes are staged per id and flushed on the next read (or explicit commit()), so a sound’s vector (upsert()) and text (index()) — which arrive as two separate protocol calls — are merged into one row and written as an efficient batch. Vector search is exact cosine (no ANN index is built at this tier; adding one is a scale-time optimization). Fusion is done by foley.index.search, not by LanceDB’s native hybrid reranker, so ranking matches every other backend.

One-table constraint: the vector column is mandatory, so every indexed row needs a vector. SoundLibrary.add enforces this (it raises without an embedding source), so the façade path is safe; a bare index() with no matching upsert() stages a text-only row that stays unflushed (never keyword-searchable). For a keyword-only library with no embeddings, use MemoryIndex or SqliteVecIndex (independent vector/text tables).

bm25(query: str, k: int, *, where: dict | None = None) → list[tuple[str, float]]

Native full-text (BM25) search; returns [(id, score), ...].

commit() → None

Flush all staged writes to the LanceDB table.

property db

The lazily-connected LanceDB database handle.

get_vector(id: str) → ndarray | None

Return the stored vector for id (staged or persisted), else None.

index(id: str, text: str, meta: dict) → None

Stage the searchable text for id (flushed on the next read/commit).

knn(vector: ndarray, k: int, *, where: dict | None = None) → list[tuple[str, float]]

Exact cosine KNN; returns [(id, cosine_similarity), ...].

property table

The lazily-opened (or created-empty) LanceDB table.

upsert(id: str, vector: ndarray, meta: dict) → None

Stage the vector for id (flushed on the next read/commit).

class foley.Layer(value)

Mix layer (shared by SoundEvent now and TimelineItem later).

class foley.LicenseFlags(commercial_ok: bool = False, embed_in_derivative_ok: bool = False, redistribute_standalone_ok: bool = False, cache_bytes_ok: bool = False, modification_ok: bool = False, ai_training_ok: bool = False, requires_attribution: bool = False, revenue_cap_usd: int | None = None)

The eight derivable flags for one license_id (the table row type).

class foley.LicenseMeta(display_name: str, url: str | None = None)

Human-facing display metadata for one license_id (name + canonical URL).

The presentation sibling of LicenseFlags: where LicenseFlags holds the permission row consulted by keep(), LicenseMeta holds the display row consulted by the credits/attribution layer (foley.provenance.credits). Kept here so licensing stays the single license authority; a record’s own license_name / license_url (when a source populated them) take precedence over this default.

class foley.LicenseRecord(source: str, source_id: str | None = None, source_url: str | None = None, acquisition_method: AcquisitionMethod = AcquisitionMethod.user, retrieved_at: str | None = None, adapter_version: str | None = None, content_sha256: str | None = None, license_id: str = 'unknown', license_name: str | None = None, license_version: str | None = None, license_url: str | None = None, rights_holder: str | None = None, creator_name: str | None = None, creator_url: str | None = None, commercial_ok: bool = False, embed_in_derivative_ok: bool = True, redistribute_standalone_ok: bool = False, cache_bytes_ok: bool = False, modification_ok: bool = False, ai_training_ok: bool = False, revenue_cap_usd: int | None = None, requires_attribution: bool = False, attribution_text: str | None = None, notice_text_required: str | None = None, transformations: list = <factory>, is_ai_generated: bool = False, generator_model: str | None = None, generator_version: str | None = None, generation_prompt: str | None = None, generation_seed: int | None = None, generation_params: dict = <factory>, watermark: dict | None = None, c2pa_manifest_ref: str | None = None, contains_recognizable_voice: bool = False, potential_trademark: bool = False, disclosure_recommended: bool = False, rights_verified: bool = False, verified_at: str | None = None, schema_version: int = 1)

Per-sound rights + provenance. SSOT for BOTH keep() and storage mode.

The derived permission flags default fail-closed here (the bare-record baseline) — with one deliberate exception: embed_in_derivative_ok defaults True (the normal case for a licensed sound). That is not a live bypass: keep() checks rights_verified first, so an unverified record is rejected regardless. Populate the flags from the license_id via foley.licensing.apply_license_flags (source overrides win). Never hand-set the derived flags — always route through the policy layer.

class foley.MasterProfile(target_lufs: float = -16.0, true_peak_db: float = -1.0, lra: float = 11.0)

Loudness master target — the delivery spec as data, not code (report 06 §5.2).

class foley.MemoryIndex(*, dim: int | None = None)

In-memory vector + keyword index (numpy cosine + compact BM25).

Not persistent — everything lives in dicts, lost on process exit. It exists so the full hybrid + façade path is testable and usable with only numpy (no LanceDB, no torch), and as a genuine zero-config tier for small or ephemeral libraries. The vector and text stores are independent dicts, so upsert() and index() never contend.

bm25(query: str, k: int, *, where: dict | None = None) → list[tuple[str, float]]

Return the top-k BM25 matches for query (best first).

A compact Okapi BM25 (k1=1.5, b=0.75) recomputed per query — O(N) in the corpus size, which is fine for the in-memory tier’s scale.

commit() → None

No-op (writes are immediate); present for interface symmetry.

get_vector(id: str) → ndarray | None

Return the stored vector for id (or None).

index(id: str, text: str, meta: dict) → None

Insert or replace the searchable text (and light metadata) for id.

knn(vector: ndarray, k: int, *, where: dict | None = None) → list[tuple[str, float]]

Return the k cosine-nearest ids to vector (most-similar first).

upsert(id: str, vector: ndarray, meta: dict) → None

Insert or replace the vector (and light metadata) for id.

class foley.PannsTagger(*, device: str = 'cpu', threshold: float = 0.1)

PANNs CNN14 supervised tagger over the 527 AudioSet classes (foley[tag]).

The checkpoint auto-downloads to ~/panns_data (~327 MB) on the first tag(). PANNs expects 32 kHz mono; the clip is resampled via foley.audio.to_working().

tag(wav: ndarray, sr: int, *, taxonomy: str = 'audioset', top_k: int = 10) → list[tuple[str, float]]

Return the top-k (AudioSet label, score) tags, best first.

class foley.Placement(anchor: Anchor = Anchor.absolute, ref: str | None = None, onset: float = 0.0, pre_roll: float = 0.0, duration: float | None = None, loop: bool = False)

WHERE/WHEN a clip sits — a symbolic anchor plus its resolved time (report 06 §6.3).

Filled by WEAVE’s aligner+anchor pass. onset is the resolved start in seconds (distinct from the sparse TimelineItem.onset symbolic string); pre_roll shifts the clip earlier so its salient transient — not its file start — lands on the anchor (report 06 §2.4).

class foley.Processing(gain_db: float = 0.0, pan: float = 0.0, distance: float = 0.0, reverb_send: float = 0.0, fade_in: float = 0.008, fade_out: float = 0.012, duck_bed: bool = False)

HOW a clip sounds — all optional with identity defaults (report 06 §3, §6.3).

Every field is a no-op at its default, so a sparse item (no processing) renders untouched; the mixer departs from dry/centered/full-level only when a field is set.

class foley.QCReport(duration_s: float, sample_rate: int, channels: int, clipped_ratio: float, clipped_max_run: int, dc_offset: float, rms_dbfs: float | None, is_silent: bool, needs_edge_fade: bool, has_nan_inf: bool, true_peak_dbtp: float | None = None, snr_db: float | None = None, loudness_lufs: float | None = None, status: QCStatus = QCStatus.pass_, notes: list = <factory>)

Per-clip Tier-0 QC result.

Mirrors the fields the SoundRecord schema already carries (duration_s, sample_rate, channels, loudness_lufs) plus the deterministic check outputs, an overall status, and human-readable notes for every firing condition. Serialize with to_dict() into SoundRecord.qc.

to_dict() → dict

Return a plain, JSON-safe dict (status as its string value).

Non-finite floats are swept to None at this boundary too (belt-and- suspenders over the construction-time _json_safe() guard) so no Infinity/NaN can ever reach json.dumps regardless of who set a field.

class foley.QCStatus(value)

Overall verdict for a clip (subclasses str so it is JSON-safe).

class foley.QCThresholds(clip_full_scale: float = 0.999, clip_min_run: int = 3, clip_reject_ratio: float = 0.0001, clip_reject_run: int = 10, true_peak_max_dbtp: float = -1.0, true_peak_oversample: int = 4, dc_offset_fail: float = 0.01, dc_offset_warn: float = 0.001, silence_rms_dbfs: float = -60.0, snr_clean_db: float = 20.0, snr_quiet_percentile: float = 10.0, snr_frame_s: float = 0.025, snr_hop_s: float = 0.01, edge_rel_peak_dbfs: float = -40.0, edge_fade_s: float = 0.01, lufs_gate_floor: float = -70.0, lufs_outlier_lu: float = 6.0, duration_min_s: float = 0.1, deliver_min_sample_rate: int = 44100)

All Tier-0 QC defaults (report 08 §3 table), each an explicit field.

Grouped by check. Pass a customized instance to run_qc() (or the per-check keyword arguments) to override any threshold without editing code.

exception foley.RecognizableVoiceRefusal(message: str, *, hits: list[str], report: IngestReport)

A SafetyRefusal for a prompt requesting a recognizable / cloned voice (report 07 §7.1).

class foley.RunManifest(run_id: str, op: str, created_at: str | None = None, foley_version: str | None = None, inputs: dict = <factory>, params: dict = <factory>, spans: list[SpanRecord] = <factory>, steps: list[Step] = <factory>, ingest_report: dict | None = None, result_ids: list = <factory>, candidate_scores: list = <factory>, credits_ref: dict | None = None, disclosure_refs: dict = <factory>, seeds: dict = <factory>, plan_ref: dict | None = None, trace_ref: str | None = None, status: str = 'ok', error: str | None = None, schema_version: int = 1)

The reproducible run-artifact for one foley operation (trace ⊕ plan ⊕ provenance).

Persisted by emit_run_manifest() into a run store keyed by run_id. Sensitive prompt/query text lives redacted (see foley.obs.redact); chosen clips are held by reference (SoundRecord id) so the manifest stays light and a trace can be replayed against a fresh index.

class foley.RuntimeConfig(offline: bool = False, data_egress_allow: frozenset[str] = <factory>, telemetry: bool = True, redaction_mode: str = 'hash', http_resilience: bool = True)

A frozen runtime posture — the local-first / offline contract as data.

Parameters:

• offline – Whether this posture is offline/local-first.

• data_egress_allow – The egress classes a source may use to be available ({'local'} offline; {'local','external'} online).

• telemetry – Whether the obs run-artifact export is on.

• redaction_mode – 'hash' (default, salted), 'off' (drop), or 'full' (raw — local-debug only).

• http_resilience – Whether HTTP source adapters are wrapped with the throttle/backoff/circuit-breaker (foley.sources.resilience).

allows(data_egress: str | None) → bool

Whether a source declaring data_egress is available under this posture.

An unknown/absent declaration is rejected (fail-closed): a source that does not say where its data goes is never used offline.

classmethod default() → RuntimeConfig

The online default: all egress allowed, telemetry on, hashed redaction.

classmethod from_env() → RuntimeConfig

Build from the environment: FOLEY_OFFLINE in {1,true,yes} → offline-local.

classmethod offline_local() → RuntimeConfig

The local-first offline posture: local-only egress, telemetry off, hashed redaction.

exception foley.SafetyRefusal(message: str, *, hits: list[str], report: IngestReport)

Raised (fail-closed) when a generation prompt trips a #9b safety gate.

A pre-synthesis hard stop: nothing is generated or stored. Distinct from a resilience error result (a backend/ingest failure the workhorse records without raising) — a safety refusal is a deliberate refusal of an unsafe request. Its report is an empty pre-generation report and status is 'refused'. Carries hits (the matched marks/patterns). Subclass of GenerationError so the public foley.generate() Raises clause already covers it. See foley.provenance.disclosure.scan_prompt().

class foley.Salience(value)

How prominent a sound event is within a passage.

class foley.ScoreResult(timeline: SoundDesignTimeline, events: list[ScoredEvent], weave: WeaveResult | None = None)

The output of score() — the editable plan + per-event rationale (+ mix when woven).

property n_sounds: int

How many sounds were placed (the restraint check — fewer than one-per-sentence).

property rationale: str

A short, agent/human-readable summary of what was chosen and why.

class foley.ScoredEvent(segment: int, query: str, sound_id: str, origin: str | None, confidence: float | None, reason: str)

One chosen sound placed for a narration event (a JSON-friendly rationale row).

to_dict() → dict

Plain-dict form (for the MCP projection / a caller’s log).

class foley.SerializableMixin

Adds to_dict/to_json/from_dict/from_json to a dataclass.

Stdlib-only, DRY, no-magic (de)serialization. Every SSOT dataclass below inherits this instead of hand-rolling per-class encoders/decoders.

classmethod from_dict(d: dict) → SerializableMixin

Reconstruct an instance from a plain dict.

Enum fields and nested dataclasses are coerced via _decode(). Unknown keys are ignored (forward-compatible); missing keys fall back to field defaults.

Parameters:

d – A plain dict (typically from to_dict() or json.loads).

classmethod from_json(s: str) → SerializableMixin

Reconstruct an instance from a JSON string.

Parameters:

s – A JSON string (typically from to_json()).

to_dict() → dict

Return the recursive plain-dict form.

Enum members are preserved (and remain JSON-safe because every enum subclasses str); nested dataclasses are recursed via dataclasses.asdict.

to_json(*, indent: int | None = None) → str

Return a JSON string (str-enums serialize to their .value).

Parameters:

indent – Optional pretty-print indent passed to json.dumps.

class foley.SessionStore(session_id: str = 'default', candidates: dict | None = None, picks: dict | None = None, rejects: dict | None = None)

Three namespaced stores for one audition session (candidates / picks / rejects).

Each store defaults to a foley.stores.make_session_store() JSON store; tests inject plain dicts. All values are JSON-safe dicts.

Parameters:

• session_id – The session namespace.

• rejects (candidates / picks /) – Optional injected MutableMapping stores.

add_pick(sound_id: str, *, layer: str | None = None, onset: float | None = None) → int

Persist an accepted pick (+ optional layer/onset); return the pick count.

add_reject(sound_id: str, *, reason: str | None = None) → int

Record a rejected sound (feeds refine relevance feedback); return the count.

cache_candidates(candidates: list[Candidate]) → int

Cache each candidate’s full to_dict() keyed by sound id; return the count cached.

drop_pick(sound_id: str) → int

Remove a pick (idempotent); return the remaining pick count.

list_picks() → list[dict]

All persisted picks.

list_rejects() → list[dict]

All recorded rejects.

picked_ids() → list[str]

The picked sound ids.

rehydrate(ids: list[str]) → list[Candidate]

Rebuild Candidate objects for ids from the cache.

Missing ids are skipped. Uses Candidate.from_dict (rebuilds the nested SoundRecord / LicenseRecord / Verdict).

rejected_ids() → list[str]

The rejected sound ids.

class foley.SoundDesignTimeline(items: list[TimelineItem] = <factory>, run_manifest_ref: str | None = None, transcript_ref: str | None = None, schema_version: int = 1, narration_ref: str | None = None, word_timeline: list = <factory>, master: MasterProfile = <factory>)

The editable, re-renderable sound-design plan — the SELECT→WEAVE bridge and render SSOT.

SELECT (#7) emits the SPARSE form (just items + the run/transcript joins) via foley.agent.plan(). WEAVE (#8) grows it additively: narration_ref binds the voice audio, word_timeline caches the forced alignment (the reproducible seed), master carries the loudness target, and each item gains its resolved Placement/Processing. render(timeline, library) is then a PURE function of this data + the library, so editing any field and re-rendering reproduces exactly that change. run_manifest_ref == foley.obs.RunManifest.run_id (the reserved #8 plan_ref join).

class foley.SoundEvent(query: str, layer: Layer = Layer.sfx_fg, diegetic: bool = True, salience: Salience = Salience.medium, onset: str | None = None, loop: bool = False, ucs_catid: str | None = None, audioset: list = <factory>, era_place: str | None = None)

One salient, physically-audible event decomposed from a passage.

class foley.SoundLibrary(*, sounds=None, meta=None, vindex=None, kindex=None, embedder=None, data_dir=None, candidate_k: int = 50, rrf_k: int = 60)

A searchable, license-aware library of sounds (the foley INDEX façade).

Read it as a Mapping of SoundRecord`s; search it with :meth:`search (text) / search_clip() (a reference clip) / similar() (audio<->audio by id); browse it with filter(); grow it with add().

add(record: SoundRecord, *, data: bytes | None = None, vector: ndarray | None = None) → SoundRecord

Store a sound and index it (the ingest write path).

Persists bytes via store_sound() (honouring the by-value/by-reference license gate), upserts the CLAP vector into the vector index, and indexes caption``+``tags into the keyword index.

A sound is retrieval-first, so it MUST carry an embedding: supply either data (bytes to embed — note a by-reference sound is embedded from its transient bytes even though they are not cached) or a precomputed vector. Adding with neither raises, rather than silently indexing a vectorless row (which the single-table LanceIndex cannot persist, producing backend-dependent search results).

Parameters:

• record – The record to add (mutated by store_sound with resolved storage fields, and stamped with the embedding model/dim).

• data – The archive bytes (required for by-value storage; also the source for computing vector when it is not supplied).

• vector – A precomputed CLAP embedding; when omitted and data is given, it is computed via the library’s embedder.

Returns:

The same (persisted, indexed) record.

Raises:

ValueError – If neither data nor vector is provided (no way to obtain an embedding).

array(sound_id: str, *, sr: int | None = None, mono: bool = True) → ndarray

Decode a sound to a working array (float32).

Parameters:

• sound_id – The record id.

• sr – Target sample rate (default: the working rate, 48 kHz).

• mono – Down-mix to mono (default True).

Returns:

The decoded working array.

audio(sound_id: str) → bytes

Return a sound’s archive bytes (by-value from the store, or from a local by-reference path).

Parameters:

sound_id – The record id.

Returns:

The raw archive bytes.

Raises:

LookupError – If the bytes are neither cached (by-value) nor readable from a local uri — a remote by-reference sound needs its source adapter (subtask #5) to fetch.

property data_dir: Path

The data root for default stores/index.

property embedder

The text<->audio embedder (CLAP by default).

filter(**facets) → list[SoundRecord]

Browse the library by metadata facets (no ranking).

Accepts the same facet keywords as search()’s filters (commercial_ok, ucs_category, min_snr, duration_range) plus any record_attr=value equality predicate.

property kindex

The keyword index.

property meta

The metadata store (id -> SoundRecord).

search(query: str, *, k: int = 10, filters: dict | None = None, commercial_ok: bool | None = None, ucs_category: str | None = None, min_snr: float | None = None, duration_range: tuple[float, float] | None = None, rerank: bool = False) → list[Candidate]

Hybrid (CLAP vector ⊕ BM25) search for a text query.

Parameters:

• query – The natural-language query.

• k – Number of results to return.

• filters – Extra {record_attr: value} equality predicates.

• commercial_ok – If True, keep only commercially-usable sounds.

• ucs_category – Keep only sounds with this UCS CatID.

• min_snr – Keep only sounds whose QC snr_db is at least this.

• duration_range – Keep only sounds whose duration_s is in (min, max).

• rerank – Re-order the shortlist by direct query<->audio cosine (fills the CLAP score for keyword-only hits).

Returns:

Up to k :class:`~foley.base.Candidate`s, best first.

search_clip(clip: AudioSource, *, sr: int | None = None, k: int = 10) → list[Candidate]

Search by a reference audio clip (audio<->audio via CLAP).

Parameters:

• clip – A working array, or a path/bytes/file decodable by foley.audio.load().

• sr – Sample rate when clip is already a working array.

• k – Number of results.

Returns:

Up to k :class:`~foley.base.Candidate`s, most-similar first.

similar(sound_id: str, *, k: int = 10) → list[Candidate]

Return the k sounds most similar to sound_id (audio<->audio).

Uses the stored vector (no re-decoding); the query sound itself is excluded from the results.

property sounds

The content-addressed byte store.

property vindex

The vector index.

class foley.SoundRecord(id: str, content_sha256: str | None = None, hash_algo: str = 'sha256', uri: str | None = None, storage_mode: StorageMode = StorageMode.by_reference, archive_format: str | None = None, source_sample_rate: int | None = None, source_bit_depth: int | None = None, license: LicenseRecord = <factory>, caption: str | None = None, tags: list = <factory>, ucs_category: str | None = None, ucs_subcategory: str | None = None, audioset_labels: list = <factory>, duration_s: float | None = None, sample_rate: int | None = None, channels: int | None = None, loudness_lufs: float | None = None, format: str | None = None, qc: dict | None = None, embedding_model: str | None = None, embedding_dim: int | None = None, embedding_ref: str | None = None, named_cue: str | None = None, schema_version: int = 1)

Canonical SSOT per sound.

Audio bytes + CLAP vector live in SEPARATE stores keyed by the same id; this record holds a content-hash uri, never raw bytes.

class foley.SpanRecord(name: str, span_id: str, parent_id: str | None = None, kind: str | None = None, start_ms: float | None = None, duration_ms: float | None = None, status: str = 'ok', attributes: dict = <factory>, events: list = <factory>, error: str | None = None)

One node of the run’s span tree (the trace half of the artifact).

Built by the recorder from its own clock + id-factory, independent of any tracer, so the tree is complete even when the OTel mirror is a total no-op.

class foley.SqliteVecIndex(*, path, dim: int)

Single-file index: sqlite-vec vec0 KNN + stdlib FTS5 keyword search.

The whole index is one SQLite file behind two virtual tables (independent, so upsert() and index() never contend). Requires an interpreter whose ``sqlite3`` permits loadable extensions — probe with sqlite_vec_loadable() before constructing; the constructor raises a clear error otherwise.

bm25(query: str, k: int, *, where: dict | None = None) → list[tuple[str, float]]

FTS5 BM25 search; returns [(id, score), ...] best-first.

FTS5’s rank is more-negative-is-better; it is negated so the returned score is larger-is-better (consistent with the other backends).

close() → None

Close the underlying SQLite connection.

commit() → None

Commit any pending SQLite transaction (writes auto-commit already).

get_vector(id: str) → ndarray | None

Return the stored vector for id (or None).

index(id: str, text: str, meta: dict) → None

Insert or replace the searchable text for id in the FTS5 table.

knn(vector: ndarray, k: int, *, where: dict | None = None) → list[tuple[str, float]]

KNN over vec0 (cosine); returns [(id, cosine_similarity), ...].

upsert(id: str, vector: ndarray, meta: dict) → None

Insert or replace the vector for id in the vec0 table.

class foley.StorageMode(value)

How a sound’s bytes are held (DERIVED from license.cache_bytes_ok).

class foley.Tagger(*args, **kwargs)

Map a clip to (label, score) pairs against a label vocabulary.

Used on ingest to auto-fill SoundRecord.audioset_labels (supervised) and tags (zero-shot). The default supervised tagger is PANNs CNN14 over AudioSet; the default zero-shot tagger scores a clip against a custom/UCS label set via CLAP (report 03). BEATs/AST are drop-in upgrades. Consumes the working array (float32, any sr — the impl resamples to its model’s rate).

tag(wav: ndarray, sr: int, *, taxonomy: str = 'audioset', top_k: int = 10) → list[tuple[str, float]]

Return the top-k (label, score) tags for the clip, best first.

class foley.TimelineItem(clip_ref: str, onset: str | None = None, gain: float = 0.0, layer: Layer = Layer.sfx_fg, loop: bool = False, id: str | None = None, placement: Placement | None = None, processing: Processing | None = None, event: dict | None = None, enabled: bool = True)

One placed sound on the sound-design timeline — sparse seed + resolved render fields.

SELECT (#7) sets only the sparse flat fields (clip_ref·onset·gain·layer·loop); WEAVE (#8) additively fills id / placement / processing (and may carry the originating event for provenance). enabled is a non-destructive mute. The sparse flat fields are never removed — they stay SELECT’s SSOT input; the render reads the resolved placement/processing (falling back to the flat fields when those are absent).

exception foley.TrademarkRefusal(message: str, *, hits: list[str], report: IngestReport)

A SafetyRefusal for a prompt naming a trademarked audio logo (report 07 §7.2).

class foley.VectorIndex(*args, **kwargs)

Approximate-nearest-neighbour store over embedding vectors.

The default is LanceDB (report 04 §2); Qdrant/pgvector/sqlite-vec bind the same protocol behind the scenes. where is an optional metadata push-down the façade may pass; a backend that cannot push filters down MAY ignore it (the façade over-fetches and post-filters to stay correct either way).

get_vector(id: str) → ndarray | None

Return the stored vector for id (or None if absent).

Needed by SoundLibrary.similar (fetch a sound’s own vector, then run knn()) and by the optional CLAP rerank (score keyword-only hits).

knn(vector: ndarray, k: int, *, where: dict | None = None) → list[tuple[str, float]]

Return the k nearest ids to vector, most-similar first.

Parameters:

• vector – A (dim,) query vector (already L2-normalized).

• k – Number of neighbours to return.

• where – Optional metadata predicates for push-down filtering.

Returns:

[(id, cosine_similarity), ...] in descending-similarity order.

upsert(id: str, vector: ndarray, meta: dict) → None

Insert or replace the vector (and light metadata) for id.

class foley.Verdict(match: bool, confidence: float, reason: str = '', level: VerifyLevel = VerifyLevel.clap)

The result of one verification rung for a candidate.

class foley.VerifyLevel(value)

Which rung of the verification ladder produced a Verdict.

class foley.WeaveResult(audio: ndarray, sr: int, timeline: SoundDesignTimeline, credits: Credits, captions_vtt: str, captions_srt: str, master_report: dict, run_manifest_ref: str | None = None, content_credential: dict | None = None, watermark: dict | None = None)

The output of weave() — the v1 Definition-of-Done deliverable.

A mastered mix + an editable, re-renderable timeline + credits + SDH captions + a reproducible run-artifact join, plus the fail-safe provenance re-assertion.

foley.add_from(source: str, *, query: str, license: str | None = 'cc0', limit: int = 50, library=None, intended_use: IntendedUse | None = None, adapter=None, **affordances) → IngestReport

Search a live source and ingest its license-clean hits into library.

Progressive disclosure: add_from("freesound", query="ocean waves") works out of the box (CC0-only, into the process-wide default library); every other knob is an optional keyword. Each hit is license-gated BEFORE any bytes are fetched (fail-closed), then routed through ingest_one(), which applies the by-reference storage gate from the sound’s own license.

Parameters:

• source – A registered live-source name (e.g. 'freesound').

• query – The natural-language search query.

• license – License constraint pushed into the source query (default 'cc0'). The per-item fail-closed guard enforces the source’s accepted-license allowlist regardless.

• limit – Max candidates to request from the source.

• library – Target SoundLibrary (default: the process-wide default library).

• intended_use – The rights intent each candidate is gated against (default: DEFAULT_INTENDED_USE).

• adapter – An optional pre-built adapter to use instead of the registry’s (the dependency-injection seam — a test passes a fake-transport adapter; production omits it and the registry lazily builds one).

• **affordances – Extra unified affordances forwarded to the adapter’s search (e.g. duration_range, sort).

Returns:

An IngestReport — inspect .ingested for the stored records (each storage_mode == by_reference for Freesound) and .summary() for counts, exactly like foley.ingest().

foley.apply_license_flags(record: LicenseRecord, *, overrides: dict | None = None) → LicenseRecord

Populate record’s eight derived flags from its license_id (+ overrides), in place, and return it.

Does NOT touch rights_verified — verification is a separate concern.

Parameters:

• record – The LicenseRecord to populate.

• overrides – Optional per-source flag overrides (see derive_license_flags()).

Returns:

The same (mutated) record.

foley.attribution_line(source: CreditEntry | SoundRecord | Candidate | LicenseRecord, *, fmt: str = 'markdown') → str

Render one sound’s TASL attribution line.

A source-supplied attribution_text (if non-empty) is returned verbatim; otherwise the line is synthesized from Title/Author/Source/License, with a (modified) notice and an AI-disclosure segment appended as applicable.

Parameters:

• source – A CreditEntry, or any credit input (coerced first).

• fmt – 'markdown' (hyperlinked list-item body) or 'plain' (text with URLs in parentheses).

Returns:

The attribution line (no leading bullet / trailing newline).

foley.bootstrap(*, rings: tuple[int, ...] = (0, 1), corpora: list[str] | None = None, data_dir: str | None = None, library=None, roots: dict[str, str] | None = None, accept_ai_restricted: bool = False, commercial_only: bool | None = None, **ingest_one_kw) → dict[str, IngestReport]

Seed library from the selected bulk corpora, returning per-corpus reports.

Parameters:

• rings – Which rings to include (default (0, 1) — Ring 2 is never default; it is opt-in via corpora=[...] + accept_ai_restricted).

• corpora – Explicit corpus-name allowlist; overrides rings when given.

• data_dir – Root under which each corpus lives at data_dir/<name> (default: the library’s data dir / $FOLEY_DATA_DIR).

• library – Target SoundLibrary (default: the process-wide default library).

• roots – Optional per-corpus root overrides ({name: path}) — for corpora downloaded somewhere other than data_dir/<name>.

• accept_ai_restricted – Consent gate for Ring-2 / ai_training_ok=False corpora. False (default) refuses them; True records explicit operator consent and admits them.

• commercial_only – Force the per-clip commercial filter on/off. None (default) derives it from the ring (Ring 1 → on, else off).

• **ingest_one_kw – Forwarded to foley.index.ingest.ingest_one() (do_supervised, do_zeroshot, min_status, thresholds …).

Returns:

{corpus_name: IngestReport} — inspect each .summary().

foley.build_mcp_server(*, library=None, session: str = 'default', runtime=None, byte_store=None, include: list[str] | None = None, name: str = 'foley')

Build the foley MCP server (lazy py2mcp); registers the JSON-safe tool surface.

Validates that every source declares a data_egress (fail-closed), binds the injectable library / runtime / byte-store, and hands the resolved tool functions to py2mcp.mk_mcp_server. Never starts a server or touches the network.

Parameters:

• library – The foley.index.SoundLibrary (default: the shared one).

• session – The default session id.

• runtime – A foley.runtime.RuntimeConfig (default: the active one).

• byte_store – A MutableMapping[str, bytes] for previews / rendered mixes.

• include – Optional subset of tool names to expose.

• name – The MCP server name.

Returns:

A fastmcp.FastMCP server.

foley.candidate_of(result: IngestResult) → Candidate

Wrap a stored IngestResult as a generated candidate.

The report-10 §4.2 shape: retrieval and generation return the same Candidate, differing only in origin. Use on a pass / warn result (its record is the canonical, stored SoundRecord).

Parameters:

result – A stored ingest result (result.record is not None).

Returns:

A Candidate with origin=CandidateOrigin.generated.

foley.capability_report(*, runtime=None) → dict

A JSON-safe capability + posture snapshot for the CLI, docs, and the MCP tool.

Groups requirements into keys (env), extras (importable), system (binary), adds the current offline posture and the available source list, and lists degraded_tools — capabilities whose requirement is unmet.

Parameters:

runtime – A foley.runtime.RuntimeConfig (default: the active one).

Returns:

{keys, extras, system, offline, sources, degraded_tools} — all JSON-safe.

foley.check_requirements(*, names: tuple[str, ...] | None = None, verbose: bool = False) → dict[str, bool]

Report which optional foley capabilities are available ({name: is_available}).

Parameters:

• names – Which requirements to check (default: the full assembled set).

• verbose – If True, print an actionable hint for each missing requirement.

Returns:

{requirement_name: available}. Everything-absent is fine — foley degrades (deterministic fakes, offline mode, in-process DSP); the report just shows what each capability would unlock.

foley.content_key(data: bytes, *, algo: str = 'sha256') → str

Return the content-address key for data — its hex digest.

Using the hash as the key gives free deduplication (identical bytes map to the same key) and immutability (a key always names the exact same bytes).

Parameters:

• data – The raw bytes to address (e.g. a FLAC archive blob).

• algo – A hashlib algorithm name (defaults to HASH_ALGO).

Returns:

The lowercase hex digest of data under algo.

foley.credit_entry(record: SoundRecord | Candidate | LicenseRecord, *, title: str | None = None) → CreditEntry

Build a CreditEntry from a record (title override optional).

Every field is read straight off the LicenseRecord (flags never re-derived); modified reflects a non-empty transformations list.

Parameters:

• record – A SoundRecord, Candidate, or LicenseRecord.

• title – Explicit title override (else resolved from caption/tags/…).

foley.credits(sounds, *, title: str = 'Credits', only_required: bool = False, write_to=None)

Build the TASL attribution Credits for sounds.

Works standalone today (given any iterable of sounds), and is what the WEAVE stage will call at render time. Inspect .markdown (a CREDITS.md document) / .manifest (a JSON-serializable dict) on the result.

Parameters:

• sounds – An iterable of SoundRecord / Candidate / LicenseRecord (e.g. the result of search(), or the sounds placed in a timeline).

• title – The credits heading.

• only_required – Keep only legally-required attributions (drops CC0 / user-owned courtesy credits). Default credits everything.

• write_to – Optional directory; when given, writes CREDITS.md and credits.json into it (created if missing).

Returns:

A Credits.

foley.credits_for(sounds: Iterable[SoundRecord | Candidate | LicenseRecord], *, title: str = 'Credits', only_required: bool = False, sort: str = 'appearance') → Credits

Build the deduplicated Credits for the sounds used in a run.

Parameters:

• sounds – An iterable of records / candidates / license records.

• title – The credits heading (also carried in the manifest).

• only_required – Keep only entries whose license requires attribution (drops CC0 / user-owned courtesy credits). Default False credits everything (never-discard-provenance).

• sort – 'appearance' (default: first-seen order), 'author', or 'title' (case-insensitive alpha).

Returns:

A Credits; identical sounds (same id) are credited once (first-writer-wins).

foley.dc_offset(samples: np.ndarray) → float

Largest per-channel absolute DC offset, max_c |mean_n x[n, c]|.

foley.decide(event: SoundEvent, kept: list[Candidate], verified: list[Candidate], *, tau_retrieve: float, budget: Budget, loop: int) → Decision

The single generate-vs-retrieve branch — a PURE function (report 05 §4).

Chooses among DecideAction from the already-gated (kept) and already-verified (verified) sets. It performs no I/O and never calls keep/search/generate — the foley.agent.tools loop acts on the returned Decision.

Policy (report 05 §4):

• a verified clip clearing tau_retrieve → USE (the best one);

• verified-but-low-confidence with refine budget → REFINE (feed the reason back);

• a non-diegetic cue, or a diegetic gap with no verified match, with generate budget → GENERATE;

• otherwise → DROP (silence), unless a lower-confidence verified clip exists and generation is off, in which case fall back to that best-effort pick.

Parameters:

• event – The event being resolved.

• kept – The license-clean candidates (each license_ok is True).

• verified – The subset of kept whose verdict matched.

• tau_retrieve – The confidence threshold for auto-accepting a retrieved clip.

• budget – The per-event cost budget.

• loop – The current refine-loop index (for the audit reason).

Returns:

A Decision.

foley.decompose_context(context: str, *, max_events: int = 6, seconds: float | None = None, decomposer: Decomposer | None = None, _span=None) → list[SoundEvent]

Decompose a passage into <= max_events sparse SoundEvents.

The pure SELECT tool (Python-API == agent == future-MCP surface): resolves the default decomposer when decomposer is None, calls it, and records the GenAI span on the real path (the fake’s last_response is None → no-op).

Parameters:

• context – The narrative passage.

• max_events – The sparse density cap.

• seconds – Optional passage duration (density-window hint; forwarded, else ignored).

• decomposer – An injected Decomposer (the DI seam); defaults to _default_decomposer().

• _span – Internal — the obs span handle find() opens for GenAI recording.

foley.default_embedder() → ClapEmbedder

Return a process-wide default ClapEmbedder (loaded once, reused).

Cached so repeated foley.search() calls share a single loaded model.

foley.default_index(*, data_dir, dim: int)

Build the best available persistent index for a library.

Degradation ladder: LanceDB (foley[index]) → sqlite-vec (foley[index-sqlite], if loadable) → an informative error. The non-persistent MemoryIndex is never chosen automatically (a library must survive restarts); inject it explicitly for tests/ephemeral use.

Parameters:

• data_dir – The library data root (a pathlib.Path-like).

• dim – The embedding dimensionality from the active embedder.

Returns:

A ready index object (both VectorIndex and KeywordIndex).

Raises:

RuntimeError – If no persistent backend is installed/usable.

foley.default_library() → SoundLibrary

The process-wide default library (local stores + CLAP + best index).

foley.default_tagger() → PannsTagger

The default supervised tagger (PANNs CNN14; foley[tag]).

foley.default_zeroshot_tagger(embedder=None) → ClapZeroShotTagger

The default zero-shot tagger (CLAP vs UCS subcategories; foley[clap]).

Cached per embedder so the tagger is bound to the SAME embedder that produced the audio vector it scores — otherwise (report seam) the cosine would cross two unrelated embedding spaces. embedder=None uses the process-wide default embedder.

foley.demo(*, library=None, query: str = 'rain on a window', k: int = 3) → dict

Ingest the bundled Ring-0 fixture and run one search — the smoke test.

Needs no corpus download (the fixture ships in the wheel), but does need the runtime extras: foley[audio] to decode and, unless a library is injected, foley[clap] for the default embedder (its model downloads on first use). Uses an ephemeral in-memory library (so it never mutates $FOLEY_DATA_DIR) unless one is injected. The fixture’s per-clip captions + tags (from its manifest.json) flow into the keyword index so a plain-text query resolves.

Parameters:

• library – Optional target library (tests inject a FakeEmbedder one; the default builds a memory library with the real CLAP embedder).

• query – The demo search query.

• k – How many hits to request.

Returns:

{"ingested": <summary dict>, "top_hit": <id or None>, "caption": <str>}.

foley.derive_license_flags(license_id: str, *, overrides: dict | None = None) → LicenseFlags

Look up the flag set for a license_id (fail-closed fallback), then apply per-source overrides.

Parameters:

• license_id – The normalized license id (SPDX or foley-specific token).

• overrides – Optional per-source flag overrides — e.g. Freesound forces cache_bytes_ok=False on CC0. Keys must be LicenseFlags fields.

Returns:

The resolved LicenseFlags (fallback = all-False UNKNOWN_LICENSE_FLAGS for unrecognized ids).

Raises:

ValueError – If overrides contains a key that is not a LicenseFlags field.

foley.detect_clipping(samples: np.ndarray, *, full_scale: float = 0.999, min_run: int = 3) → tuple[float, int]

Detect hard (flat-topped) clipping.

A frame is “hot” when any channel reaches |x| >= full_scale. Only maximal hot runs of length >= min_run count as clip events.

Parameters:

• samples – Waveform in [-1, 1].

• full_scale – Absolute level at/above which a sample is full-scale.

• min_run – Minimum consecutive full-scale frames to count as clipping.

Returns:

(clipped_ratio, max_run_length) — the fraction of frames inside counting runs, and the longest counting run ((0.0, 0) if none).

foley.duration_s(samples: np.ndarray, sample_rate: int) → float

Clip duration in seconds: frames / sample_rate.

foley.encode(samples: ndarray, sample_rate: int, *, fmt: str = 'flac', subtype: str = 'PCM_24') → bytes

Encode samples fully in memory and return the container bytes.

This is the producer for the content-addressed byte store: default output is the FLAC archive form.

Parameters:

• samples – The working array to encode.

• sample_rate – Sample rate in Hz.

• fmt – Container/codec name (case-insensitive).

• subtype – Sample subtype (e.g. PCM_24).

Returns:

The encoded audio as bytes.

Lazy dependency: soundfile.

foley.ensure_channels(samples: ndarray, *, channels: int) → ndarray

Coerce samples to exactly channels channels.

Mappings: mono -> N by duplication; N -> mono by mean; N -> M (N != M, both > 1) by collapsing to mono then tiling up to M.

Parameters:

• samples – Mono or multichannel working array.

• channels – Target channel count (must be >= 1).

Returns:

A (frames,) array when channels == 1, else a (frames, channels) array.

Raises:

ValueError – If channels < 1.

Lazy dependency: numpy (only for the up-mix / tile path).

foley.estimate_snr(samples: np.ndarray, sample_rate: int, *, quiet_percentile: float = 10.0, frame_s: float = 0.025, hop_s: float = 0.01) → float

Estimate SNR in dB (advisory — a busy-street SFX legitimately scores low).

The noise floor is the mean short-time RMS of the quietest quiet_percentile percent of frames; the signal level is the whole-clip RMS. A near-noise-free clip (quiet frames -> ~0) yields a very high value; an exactly-zero floor returns inf and a silent clip returns -inf.

Parameters:

• samples – Waveform in [-1, 1] (down-mixed to mono internally).

• sample_rate – Sample rate in Hz (sizes the frames).

• quiet_percentile – Percent of quietest frames forming the noise floor.

• frame_s – Short-time frame length in seconds.

• hop_s – Hop between frames in seconds.

Returns:

SNR in dB.

foley.evaluate(*, golden=None, k: int = 10)

Run the Tier-1 retrieval eval over the golden set (nDCG@10 / recall / mAP / MRR).

Scores every golden query through the real SoundLibrary.search() path against a deterministic, CLAP-free Ring-0 library — the same computation the PR gate asserts on. See foley.eval.

Parameters:

• golden – Optional path to a golden-set JSON (default: the frozen seed).

• k – Retrieval cutoff and metric @k.

Returns:

A foley.eval.RetrievalReport.

foley.evaluate_fit(*, golden=None, sample=None, level=VerifyLevel.judge, fit_judge=None, embedder=None, seed: int = 0, k: int = 10)

Run the Tier-2 fit eval over the golden set — “does the accepted clip fit?” (#10b).

The judge-based sibling of evaluate(): over a seeded stratified sample it runs the SELECT pipeline and audits each license-clean candidate with the authoritative fit-judge, returning a foley.eval.FitReport (fit-precision / recall / F1 + fit-score + auto-accept-rate + per-stratum breakdown). Works out of the box on the Ring-0 fixture with the deterministic fake judge — no network, key, or heavy deps. Nightly / pre-release and cost-gated: report-only — gating is the caller’s job via FitReport.gate(). It never touches the retrieval ranking (the Tier-1 nDCG gate).

Parameters:

• golden – Optional golden-set JSON path (default: the frozen Ring-0 seed).

• sample – Optional stratified sample cap (default: the whole set — the cost gate).

• level – The verify rung the fit-judge audits at — 'listen' or 'judge' (default VerifyLevel.judge); 'clap' is rejected.

• fit_judge – An injected authoritative judge (default: the auto-resolved fit-judge — the LLM arbiter AnthropicJudge when a key is configured, else the hermetic StringOverlapJudge fake; the audio-LM AudioLMJudge is injection-only in this slice).

• embedder – The Ring-0 embedder (default: the CLAP-free HashingBowEmbedder).

• seed – The sampling RNG seed.

• k – Retrieval shortlist depth per event.

Returns:

A foley.eval.FitReport.

foley.fade(samples: ndarray, sample_rate: int, *, fade_in_s: float = 0.01, fade_out_s: float = 0.01, kind: str = 'linear') → ndarray

Apply in/out gain ramps to samples (a short declick by default).

Ramp lengths are clamped to at most len(samples) // 2 so the in- and out-ramps never overlap on tiny inputs.

Parameters:

• samples – Working array (mono or multichannel).

• sample_rate – Sample rate in Hz (converts the fade durations to samples).

• fade_in_s – Fade-in duration in seconds.

• fade_out_s – Fade-out duration in seconds.

• kind – 'linear' or 'equal_power' ramp shape.

Returns:

A new array with the fade envelope applied (input is not mutated).

Lazy dependency: numpy.

foley.find(context: str, *, max_events: int = 6, seconds: float | None = None, intended_use: IntendedUse | None = None, backend: str = 'auto', verify: str | VerifyLevel = 'listen', stream: bool = False, k: int = 10, tau_retrieve: float = 0.5, tau_clap: float = 0.35, max_refine_loops: int = 1, budget: Budget | None = None, library=None, decomposer=None, judge=None, refiner=None) → list[Candidate] | Iterator[Candidate]

The headline: a narrative context → verified, license-clean sound candidates.

decompose → (per event) refine/search → verify_match ladder → decide (with the fail-closed license gate FIRST) → place (report 05 §5). Works out of the box — foley.find("She pushed open the heavy oak door; rain hammered outside.") — with deterministic defaults; every model / threshold / seam is an optional keyword.

Parameters:

• context – The narrative passage.

• max_events – The sparse density cap on decomposed events.

• seconds – Optional passage duration (density-window hint; forwarded).

• intended_use – The caller’s rights intent (default: a conservative IntendedUse — allow_voice_or_trademark stays False).

• backend – Generation backend for the fallback ('auto' → foley.generate’s default).

• verify – The max verify rung — 'clap' | 'listen' | 'judge'.

• stream – If True, return a generator yielding one Candidate per resolved event; else return the collected list.

• k – Retrieval shortlist depth per query.

• tau_retrieve – Confidence threshold to auto-accept a retrieved clip.

• tau_clap – The clap-rung gate threshold.

• max_refine_loops – Max refine→re-retrieve passes per event (also the default Budget).

• budget – An explicit Budget (overrides max_refine_loops).

• library – Target SoundLibrary (default: the process-wide default).

• refiner (decomposer / judge /) – Injected DI seams (Decomposer / Judge / Refiner); each defaults to the hermetic fake when foley[agent] is absent.

Returns:

list[Candidate] (stream=False) or an Iterator[Candidate] (stream=True) — one verified, license-clean candidate per resolved event.

foley.fuse_hits(vector_hits: list[tuple[str, float]], keyword_hits: list[tuple[str, float]], *, k: int, rrf_k: int = 60) → list[FusedHit]

RRF-fuse a vector ranker’s hits with a keyword ranker’s hits.

Parameters:

• vector_hits – [(id, cosine_similarity), ...] best-first (from knn()).

• keyword_hits – [(id, bm25_score), ...] best-first (from bm25()).

• k – Number of fused hits to return.

• rrf_k – The RRF damping constant.

Returns:

The top-k :class:`FusedHit`s, each carrying its raw component scores.

foley.generate(prompt: str, *, backend: str = 'stable_audio', library=None, store: bool = True, adapter=None, watermark=None, on_flagged: str = 'refuse', watermarker=None, provenance_store=None, **affordances)

Generate a sound effect for prompt and add it to the library (by-value).

Progressive disclosure: foley.generate("a single wooden door creak") works out of the box (the local Stable Audio Open backend, into the process-wide default library). The generated audio is stored by-value with a content-hash id, so it becomes a first-class, re-searchable library entry — every generation is a future free retrieval (the generation flywheel). It flows through the SAME ingest_one() pipeline as every other source, with operator consent for the generator license’s AI-training restriction (the record keeps ai_training_ok=False, so keep() still refuses it for training uses).

Parameters:

• prompt – The natural-language sound description.

• backend – A registered generate source — "stable_audio" (default, local; needs foley[stable-audio]) or "elevenlabs" (hosted; foley[elevenlabs] + $ELEVENLABS_API_KEY).

• library – Target library (default: the process-wide default library).

• store – If False, synthesize + enrich a preview without adding it.

• adapter – Optional pre-built adapter (the DI seam; production omits it and the registry lazily builds one).

• watermark – True require an AudioSeal watermark, False never, None (default, auto) watermark iff foley[provenance] is installed (#9b).

• on_flagged – 'refuse' (default, fail-closed) or 'warn' for a prompt that trips the trademarked-audio / recognizable-voice safety gate (#9b).

• watermarker – An injected watermarker (the DI seam; tests pass a fake).

• provenance_store – A MutableMapping for content-credential sidecars (default: foley.stores.make_provenance_store()).

• **affordances – Unified generation affordances (duration, prompt_influence, negative_prompt, steps, seed, loop, output_format — see GENERATION_AFFORDANCES); a backend warns-and-drops the ones it does not support.

Returns:

The stored Candidate (origin=generated) — its sound is the canonical, by-value SoundRecord (a content-hash id).

Raises:

• SafetyRefusal – If the prompt trips a safety gate and on_flagged='refuse' (a GenerationError subclass — TrademarkRefusal / RecognizableVoiceRefusal).

• GenerationError – If the backend yields no stored sound (QC-quarantined, rights-blocked, or a synthesis/ingest error). The exception carries the full report and terminal status so callers can react distinctly.

foley.has_nan_inf(samples: np.ndarray) → bool

Return True if any sample is NaN or Inf (corrupt-clip guard).

foley.hybrid_search(query: str, *, embedder: Embedder, vindex: VectorIndex, kindex: KeywordIndex, k: int = 10, candidate_k: int = 50, rrf_k: int = 60, where: dict | None = None) → list[FusedHit]

Embed query, run the vector + keyword rankers, and RRF-fuse them.

Parameters:

• query – The natural-language query.

• embedder – Text<->audio embedder (its embed_text produces the query vector).

• vindex – The vector index (CLAP KNN).

• kindex – The keyword index (BM25).

• k – Number of fused results to return.

• candidate_k – Shortlist depth pulled from each ranker before fusion.

• rrf_k – The RRF damping constant.

• where – Optional metadata push-down passed to both rankers.

Returns:

The top-k fused :class:`FusedHit`s.

foley.ingest(path, *, library=None, backend: str = 'local', qc: bool = True, recursive: bool = True, **kw)

Ingest a folder (or single file) of sounds into the default library.

probe -> QC -> tag -> zero-shot -> caption -> embed -> SoundRecord for each file, returning an IngestReport. See foley.index.ingest_folder() / ingest_one() for the per-file options (license, taggers, min_status, …).

Parameters:

• path – A folder (walked) or a single audio file.

• library – Target library (default: the process-wide default library).

• backend – "local" ingests filesystem audio; other backends (a source adapter pull) route through add_from (subtask #5) — kept in the signature for forward-compat.

• qc – Run the Tier-0 QC gate (quarantines failing clips).

• recursive – Recurse into sub-folders.

• **kw – Forwarded to foley.index.ingest_one().

foley.ingest_folder(path, *, library=None, recursive: bool = True, exts: tuple[str, ...] = ('.wav', '.flac', '.aiff', '.aif', '.ogg', '.mp3', '.opus', '.m4a'), on_error: str = 'collect', **ingest_one_kw) → IngestReport

Ingest every audio file under path and return an IngestReport.

Parameters:

• path – A folder (walked) or a single audio file.

• library – Target library (default: the process-wide default).

• recursive – Recurse into sub-folders.

• exts – Audio extensions to ingest.

• on_error – 'collect' records per-file errors and continues; 'raise' re-raises the first error.

• **ingest_one_kw – Forwarded to ingest_one() (license, taggers, QC flags, …).

Returns:

An IngestReport (with .summary() counts and per-file results).

foley.ingest_one(src: AudioSource, *, library=None, sound_id: str | None = None, source_uri: str | None = None, license: LicenseRecord | None = None, tagger=None, zeroshot_tagger=None, captioner=None, do_qc: bool = True, min_status: QCStatus = QCStatus.warn, do_supervised: bool = True, do_zeroshot: bool = True, do_caption: bool = True, thresholds: QCThresholds = QCThresholds(clip_full_scale=0.999, clip_min_run=3, clip_reject_ratio=0.0001, clip_reject_run=10, true_peak_max_dbtp=-1.0, true_peak_oversample=4, dc_offset_fail=0.01, dc_offset_warn=0.001, silence_rms_dbfs=-60.0, snr_clean_db=20.0, snr_quiet_percentile=10.0, snr_frame_s=0.025, snr_hop_s=0.01, edge_rel_peak_dbfs=-40.0, edge_fade_s=0.01, lufs_gate_floor=-70.0, lufs_outlier_lu=6.0, duration_min_s=0.1, deliver_min_sample_rate=44100), store: bool = True, allow_ai_training_forbidden: bool = False, seed_tags: list | None = None) → IngestResult

Ingest one clip into library and return an IngestResult.

Pipeline: probe + decode-once -> content-address dedup -> QC gate -> embed (once) -> supervised + zero-shot tags -> caption -> resolve UCS -> assemble SoundRecord -> SoundLibrary.add().

Parameters:

• src – A path, bytes, or file-like audio source.

• library – Target SoundLibrary (default: the process-wide default library).

• sound_id – Optional canonical id override. Defaults to None → the content-hash of the decoded PCM (the local-ingest identity, used as the record id and dedup key). A live source adapter passes a short, case-stable, source-native id (e.g. 'freesound:12345') so dedup keys on the stable id rather than on re-fetched (lossy, byte-varying) preview bytes; when it does, the PCM hash is computed only for the (skipped) default and is not persisted. Separately, content_sha256 records the hash of the stored FLAC archive bytes (set by store_sound), which is a different byte source from this PCM hash.

• source_uri – Optional by-reference fetchable URI override. Defaults to None → the resolved local path when src is path-like. A live adapter passes the stable source page URL (e.g. 'https://freesound.org/s/12345/') that foley.stores.store_sound() requires for a by-reference sound.

• license – Rights record (default: a user-owned, cacheable license).

• tagger – Supervised Tagger (default: PANNs via default_tagger()).

• zeroshot_tagger – Zero-shot tagger (default: CLAP via default_zeroshot_tagger()).

• captioner – Optional Captioner (default: none — the caption stage is off unless one is injected).

• do_qc – Run the Tier-0 QC gate.

• min_status – Admission floor — a QC status worse than this is quarantined (default warn: only fail clips are rejected).

• do_caption (do_supervised / do_zeroshot /) – Toggle each enrichment stage.

• thresholds – QC thresholds.

• store – If False, assemble the record but do not add it to the library (probe/QC/enrich only).

• seed_tags – Optional caller-supplied tags (e.g. a corpus’s folder-path taxonomy) unioned into the record’s tags alongside the supervised/zero-shot tags — so they feed the BM25 keyword index.

• allow_ai_training_forbidden – The universal fail-closed rights gate. A sound whose license has ai_training_ok=False (e.g. Sonniss, BBC RemArc) is refused with status 'rights_blocked' before it is embedded or stored — CLAP-embedding-and-persisting is itself a form of AI training on the corpus. Pass True to record explicit operator consent and admit it anyway (see foley.bootstrap.bootstrap()’s accept_ai_restricted). Protects every ingest path, not just bootstrap.

Returns:

An IngestResult; its record is None when quarantined, a duplicate, or rights-blocked.

foley.install_agent_kit(dest='./.claude', *, overwrite: bool = False) → list[str]

Copy the shipped skill + slash command + subagent into dest (a .claude dir).

Installs:

• dest/skills/foley-sound-design/ — the consumer skill (the sound-design playbook),

• dest/commands/foley-score.md — the /foley-score slash command,

• dest/agents/sound-designer.md — the sound-designer subagent.

Parameters:

• dest – The target agent-config dir (default ./.claude in the cwd; pass ~/.claude to install globally for every project).

• overwrite – Replace existing files/dirs (default: skip what already exists).

Returns:

The list of installed paths (as strings) — empty entries that already existed are skipped.

foley.is_offline() → bool

Whether an offline runtime scope is currently active.

foley.is_silent(samples: np.ndarray, *, rms_floor_dbfs: float = -60.0) → bool

Return True when whole-clip RMS falls below rms_floor_dbfs.

A zero (exactly silent) clip has RMS 0 -> -inf dBFS -> True.

foley.keep(record: LicenseRecord, intended_use: IntendedUse) → bool

Fail-closed candidate license gate (report 07 §8.2).

Run BEFORE ranking/verification in the agent’s decide(). Unknown or unverified rights => reject. Any single unmet requirement => reject.

Parameters:

• record – The candidate’s rights record.

• intended_use – The caller’s declared intent.

Returns:

True only if every requirement in intended_use is satisfied by record; False otherwise (including unverified rights).

foley.keep_sound(sound_record, intended_use: IntendedUse) → bool

Convenience: apply keep() to a SoundRecord’s nested license.

Parameters:

• sound_record – A SoundRecord (its .license is the SSOT consulted).

• intended_use – The caller’s declared intent.

Returns:

The result of keep(sound_record.license, intended_use).

foley.lancedb_available() → bool

True if lancedb is importable (the foley[index] extra is present).

foley.license_id_from_cc_url(url: str | None) → tuple[str, bool]

Map a Creative-Commons license URL or label to (license_id, verified).

The single SSOT for turning an external source’s license string into a foley license_id (used by the FSD50K bulk adapter and the Freesound API adapter). Recognized CC families map to their foley license_id with rights_verified=True; anything unknown/missing fails closed to ('unknown', False) so keep() drops it while its provenance is still recorded.

Both representations Freesound uses are handled: the CC URL form (http://creativecommons.org/publicdomain/zero/1.0/) and the plain label the search API returns ("Creative Commons 0", "Attribution", "Attribution NonCommercial").

Fail-closed for NoDerivatives / ShareAlike. Any -nd / -sa variant — including the by-nc-nd and by-nc-sa compounds — has NO foley LICENSE_FLAGS row: its extra restrictions (no derivatives / share-alike) are not expressible by any row we have, so it maps to ('unknown', False) and is rejected everywhere. This check runs first, so by-nc-nd / by-nc-sa are NOT mis-mapped to plain CC-BY-NC-4.0 (which would fail-open by granting the modification / derivative / standalone-redistribution rights those licenses forbid). Only after it are by-nc / sampling tested before the bare by.

Parameters:

url – A CC license URL, a CC label string, or None.

Returns:

(license_id, rights_verified) — ('unknown', False) when unrecognized, missing, or a fail-closed ND/SA variant.

foley.license_meta(license_id: str) → LicenseMeta

Return the display LicenseMeta for license_id (fail-closed fallback).

Parameters:

license_id – The normalized license id.

Returns:

The mapped LicenseMeta, or UNKNOWN_LICENSE_META for an unrecognized / Proprietary-* id.

foley.list_sources(*, egress_allow: frozenset | None = None) → list[str]

Return the names of registered live sources (runs discovery first).

Parameters:

egress_allow – If given, keep only sources whose declared config['data_egress'] is in this set (the local-first / offline filter — see foley.runtime.RuntimeConfig). A source that does not declare data_egress is excluded (fail-closed).

foley.load(src: AudioSource, *, target_sr: int | None = None, mono: bool = False, dtype: str = 'float32') → tuple['ndarray', int]

Decode audio into a float working array.

src may be a filesystem path, raw encoded bytes (wrapped in a BytesIO so nothing touches disk), or any binary file-like object.

Parameters:

• src – Path, raw bytes, or file-like object to decode.

• target_sr – If given, resample the decoded audio to this rate (via resample()); otherwise the native rate is returned.

• mono – If True, down-mix multichannel audio to mono.

• dtype – NumPy dtype string for the returned array (default float32).

Returns:

A (samples, sample_rate) tuple. samples has shape (frames,) (mono) or (frames, channels); sample_rate reflects any resample.

Lazy dependencies: soundfile (and soxr when target_sr differs).

foley.loudness_normalize(samples: ndarray, sample_rate: int, *, target_lufs: float = -16.0, peak_ceiling_dbfs: float = -1.0, min_block_s: float = 0.4) → tuple['ndarray', float]

Loudness-normalize to target_lufs, then keep it peak-safe.

Integrated loudness is measured (ITU-R BS.1770-4 / EBU R128), the signal is scaled to target_lufs, and finally attenuated so its sample peak sits at or below peak_ceiling_dbfs. Two inputs are returned unchanged (flag them, don’t amplify): near-silent input (measured loudness at or below LUFS_GATE_FLOOR), and a clip shorter than one BS.1770 gating block (min_block_s) — which pyloudnorm cannot measure and would otherwise raise ValueError on (routine for one-shots: clicks, blips, gunshots).

Parameters:

• samples – Working array (mono or multichannel, time on axis 0 — the layout pyloudnorm expects).

• sample_rate – Sample rate in Hz.

• target_lufs – Desired integrated loudness (default = foley’s podcast target).

• peak_ceiling_dbfs – Sample-peak ceiling (dBFS) applied after loudness normalization. Note this is a sample-peak limit, not an inter-sample true-peak (dBTP) limit — see foley.qc.true_peak_dbtp() for the oversampled measurement.

• min_block_s – Minimum clip length (seconds) that can be loudness-measured; shorter clips are returned unchanged with measured = -inf.

Returns:

(normalized, measured_input_lufs). When the input is near-silent or too short to measure, normalized is the unchanged input and measured_input_lufs is at or below LUFS_GATE_FLOOR (-inf for the too-short case).

Lazy dependencies: pyloudnorm (+ numpy).

foley.make_byte_store(rootdir: str | PathLike[str] = PosixPath('/home/runner/.local/share/foley/audio')) → MutableMapping[str, bytes]

Build the content-addressable blob store: Mapping[content_key -> bytes].

The local default is dol.Files (bytes values on disk). For cloud storage, build the equivalent store from any dol Mapping (e.g. an S3 store) and pass it directly to store_sound() instead of calling this factory — the store_sound gate treats sounds as an opaque MutableMapping.

Parameters:

rootdir – Directory that holds the blobs (created if missing).

Returns:

A MutableMapping[str, bytes] keyed by content_key().

foley.make_http_app(*, auth: dict, path: str = '/mcp', json_response: bool = False, library=None, runtime=None, byte_store=None, include: list[str] | None = None, name: str = 'foley')

Build a bearer-auth-gated ASGI app serving the foley MCP tools over streamable HTTP.

HTTP exposes the tool surface to the network, so auth is required and fail-closed: pass auth={'bearer_tokens': [...]} (a non-empty iterable of accepted tokens) — a request without a matching Authorization: Bearer <token> header gets a 401. The returned app (a Starlette/ASGI callable) mounts in any ASGI host (uvicorn, gunicorn, a parent FastAPI). py2mcp / fastmcp are imported lazily inside build_mcp_server(), so import foley stays dol-only.

Parameters:

• auth – {'bearer_tokens': [...]} — required; empty/missing raises (fail-closed).

• path – The MCP HTTP mount path.

• json_response – Return a single JSON response instead of an SSE stream (simple clients).

• name (library / runtime / byte_store / include /) – As build_mcp_server().

Returns:

An ASGI application (the bearer-gated MCP HTTP app).

Raises:

ValueError – If auth carries no bearer tokens (no anonymous HTTP access).

foley.make_meta_store(rootdir: str | PathLike[str] = PosixPath('/home/runner/.local/share/foley/meta')) → MutableMapping[str, SoundRecord]

Build the metadata store: Mapping[sound_id -> SoundRecord] (JSON files).

SoundRecord values are (de)serialized transparently via the SerializableMixin (to_dict / from_dict); each record is written as a percent-encoded {sound_id}.json file while the store’s keys stay the bare sound_id (invariant #3 — the id is escaped at this boundary so an externally-derived id can never escape rootdir or collide via //..).

Parameters:

rootdir – Directory that holds the metadata JSON files (created if missing).

Returns:

A MutableMapping[str, SoundRecord] keyed by sound_id.

foley.make_run_store(rootdir: str | PathLike[str] = PosixPath('/home/runner/.local/share/foley/runs')) → MutableMapping[str, dict]

Build the run-artifact store: Mapping[run_id -> RunManifest dict] (JSON files).

The by-value carrier for #11’s reproducible run-manifests (one per instrumented find() / generate() / … ). An exact sibling of make_provenance_store(): escapes the run_id to a safe {enc}.json filename (invariant #3) while exposing bare run_id keys; values are plain dicts ((de)serialized by dol.JsonFiles). Local by default; swap in any dol Mapping for the cloud.

Parameters:

rootdir – Directory that holds the run JSON files (created if missing).

Returns:

A MutableMapping[str, dict] keyed by run_id.

foley.make_session_store(session_id: str = 'default', name: str = 'picks', *, rootdir: str | PathLike[str] | None = None) → MutableMapping[str, dict]

Build a per-session JSON store: Mapping[key -> dict] under sessions/{id}/{name}/.

The by-value carrier for #12’s audition state — one store per namespace (candidates / picks / rejects). A sibling of make_run_store(): percent-encodes each key to a safe {enc}.json filename (invariant #3) while exposing bare keys; values are plain dicts. Local by default; swap in any dol Mapping for the cloud.

Parameters:

• session_id – The session namespace (default 'default').

• name – The store namespace within the session (candidates / picks / rejects).

• rootdir – Root sessions directory (default: DEFAULT_SESSION_DIR).

Returns:

A MutableMapping[str, dict] keyed by the bare key.

foley.mcp_server(*, library=None, session: str = 'default', runtime=None, byte_store=None, include: list[str] | None = None, name: str = 'foley')

Build the foley MCP server (lazy py2mcp); registers the JSON-safe tool surface.

Validates that every source declares a data_egress (fail-closed), binds the injectable library / runtime / byte-store, and hands the resolved tool functions to py2mcp.mk_mcp_server. Never starts a server or touches the network.

Parameters:

• library – The foley.index.SoundLibrary (default: the shared one).

• session – The default session id.

• runtime – A foley.runtime.RuntimeConfig (default: the active one).

• byte_store – A MutableMapping[str, bytes] for previews / rendered mixes.

• include – Optional subset of tool names to expose.

• name – The MCP server name.

Returns:

A fastmcp.FastMCP server.

foley.measure_lufs(samples: np.ndarray, sample_rate: int, *, gate_floor_lufs: float = -70.0, min_block_s: float = 0.4) → float | None

Integrated loudness (LUFS, ITU-R BS.1770-4) via pyloudnorm (lazy).

Returns None when pyloudnorm is unavailable, the clip is shorter than one gating block (min_block_s), the samples are non-finite, or the measured loudness is at/below the gate floor (near-silent / unstable — do not amplify, just flag).

foley.needs_edge_fade(samples: np.ndarray, *, rel_peak_dbfs: float = -40.0) → bool

Return True when the first or last sample sits above rel_peak_dbfs relative to the clip peak — i.e. a nonzero boundary that clicks under narration and needs a short fade.

foley.offline(config: RuntimeConfig | None = None)

Alias of offline_scope() — with foley.offline(): ... for local-first runs.

foley.parse_ucs_filename(filename, *, table: UcsTable | None = None) → tuple[str | None, str | None]

Parse a UCS-conformant filename to (ucs_category, ucs_subcategory).

Fail-quiet: returns (None, None) when the name is not UCS-conformant or its CatID token is unknown (so a wrong subcategory is never emitted).

Parameters:

• filename – A path or filename (only the basename’s token 0 is used).

• table – The UCS table to resolve against (defaults to default_ucs_table()).

foley.plan(candidates: list[Candidate], *, transcript: str | None = None) → SoundDesignTimeline

Fold verified candidates into the SPARSE SoundDesignTimeline (the SELECT→WEAVE bridge).

One TimelineItem per candidate (onset·gain·layer·loop only, from its SoundEvent), joined to the run-artifact via run_manifest_ref — the reserved #8 plan_ref slot is filled when called inside an active foley.obs run scope (None-safe otherwise).

Parameters:

• candidates – The candidates returned by find().

• transcript – Optional narration transcript (WEAVE resolves the reference).

foley.preview(candidate_or_id, *, seconds: int = 6, library=None, byte_store=None, session: SessionStore | None = None) → Candidate

Produce a short audition of a sound; set its preview_uri to a store key.

Writes the first seconds of the clip (FLAC) into byte_store under its content key and points Candidate.preview_uri at that key — referencing the audio, never returning bytes. Fail-safe: if the audio codec extra (foley[audio]) or the clip is unavailable, preview_uri is None (the sound id + duration still let a client fetch it).

Parameters:

• candidate_or_id – A Candidate or a sound id.

• seconds – Audition length.

• library – The foley.index.SoundLibrary (default: the shared one).

• byte_store – A MutableMapping[str, bytes] to hold the preview (default: none — then preview_uri stays None).

• session – Optional session (unused here; accepted for a uniform signature).

Returns:

The candidate with preview_uri set (or None on graceful degradation).

foley.reciprocal_rank_fusion(ranked_id_lists: list[list[str]], *, k: int = 60) → list[tuple[str, float]]

Fuse several ranked id lists into one, by reciprocal rank.

Parameters:

• ranked_id_lists – Each element is a list of ids in descending-relevance order (best first). Lists may overlap and may differ in length.

• k – The RRF damping constant (default RRF_K = 60).

Returns:

[(id, fused_score), ...] sorted by fused score descending, ties broken by id ascending (so the fusion is fully deterministic).

foley.refine(session: SessionStore | None = None, *, query: str | None = None, picked_ids: tuple[str, ...] = (), rejected_ids: tuple[str, ...] = (), hint: str | None = None, n: int = 3, k: int = 10, library=None, refiner=None) → RefineResult

Relevance-feedback refinement: expand for recall, boost picks, drop rejects, re-rank.

Distinct from foley.refine_query() (which only paraphrases a query): this reads the session’s picks/rejects (or the explicit picked_ids / rejected_ids), expands the query into paraphrases for recall, gathers neighbours of every pick, drops the rejects, and re-ranks by score.

Parameters:

• session – The audition session (source of picks/rejects when not passed explicitly).

• query – The base text query to expand (optional).

• rejected_ids (picked_ids /) – Explicit feedback (override the session’s).

• hint – A steer for the query expansion.

• n – Paraphrases to request.

• k – Result depth.

• library – The foley.index.SoundLibrary (default: the shared one).

• refiner – The query-expansion seam (default: the deterministic fake).

Returns:

A RefineResult.

foley.refine_query(query: str, *, n: int = 3, hint: str | None = None, refiner: Refiner | None = None, _span=None) → list[str]

Expand query into up to n paraphrases for multi-query retrieval.

Parameters:

• query – The event query to expand.

• n – Number of paraphrases.

• hint – Optional verify-failure reason to steer re-retrieval.

• refiner – An injected Refiner (the DI seam); defaults to _default_refiner().

• _span – Internal — the obs span handle for GenAI recording.

foley.register_source(name: str, config: dict, adapter=None) → None

Register a live source directly (out-of-tree plugin or a test double).

Overwrites any existing entry for name — the seam a test uses to inject a fake-transport-backed adapter. If adapter is None it is lazily built from config on first get_source() (the source must then be an importable foley.sources.<name> package).

Parameters:

• name – The source name (the add_from() / get_source() key).

• config – The SOURCE_CONFIG declaration.

• adapter – An optional pre-instantiated adapter (bypasses lazy loading).

foley.resample(samples: ndarray, sample_rate: int, *, target_sr: int = 48000, quality: str = 'HQ') → ndarray

Resample samples to target_sr (a no-op when already there).

Parameters:

• samples – Working array (mono (frames,) or (frames, channels)).

• sample_rate – The array’s current rate in Hz.

• target_sr – Desired output rate in Hz (default = the working rate).

• quality – soxr quality preset (QQ/LQ/MQ/HQ/VHQ).

Returns:

The resampled array (the input unchanged when sample_rate == target_sr). dtype is preserved by soxr.

Lazy dependency: soxr.

foley.resolve_catid(*, tags: Sequence[str] = (), caption: str | None = None, audioset_labels: Sequence[str] = (), filename: str | None = None, table: UcsTable | None = None, audioset_map: AudioSetUcsMap | None = None) → CatIdResolution

Resolve inputs to a best UCS CatID by the staged precedence.

Parameters:

• tags – Free tags on the sound.

• caption – Free-text caption/description.

• audioset_labels – AudioSet MIDs or names (e.g. from PANNs).

• filename – Optional UCS-style filename/path (its token-0 CatID wins if recognized).

• table – UCS table (defaults to default_ucs_table()).

• audioset_map – AudioSet->UCS map (defaults to default_audioset_ucs_map()).

Returns:

A CatIdResolution (falsy when nothing resolved).

foley.resolve_master(master: str | MasterProfile | None) → MasterProfile

Resolve a master spec (profile name, explicit profile, or None) to a MasterProfile.

Parameters:

master – A MASTER_PROFILES key (e.g. 'podcast'), an explicit MasterProfile, or None (-> the podcast default).

Returns:

The resolved MasterProfile.

Raises:

ValueError – If master is an unknown profile name.

foley.run_qc(samples: np.ndarray, sample_rate: int, *, thresholds: QCThresholds = QCThresholds(clip_full_scale=0.999, clip_min_run=3, clip_reject_ratio=0.0001, clip_reject_run=10, true_peak_max_dbtp=-1.0, true_peak_oversample=4, dc_offset_fail=0.01, dc_offset_warn=0.001, silence_rms_dbfs=-60.0, snr_clean_db=20.0, snr_quiet_percentile=10.0, snr_frame_s=0.025, snr_hop_s=0.01, edge_rel_peak_dbfs=-40.0, edge_fade_s=0.01, lufs_gate_floor=-70.0, lufs_outlier_lu=6.0, duration_min_s=0.1, deliver_min_sample_rate=44100)) → QCReport

Run every Tier-0 check and fold the results into a QCReport.

Status rules (evaluated in order):

FAIL if has_nan_inf OR is_silent OR clipped_max_run >= clip_reject_run OR clipped_ratio > clip_reject_ratio OR duration_s < duration_min_s. WARN if dc_offset > dc_offset_fail OR needs_edge_fade OR (snr_db is a finite value < snr_clean_db) OR (true_peak_dbtp is a finite value > true_peak_max_dbtp). Otherwise PASS.

Each firing condition appends a human-readable string to notes. Two thresholds are intentionally NOT evaluated on a single source clip here because they belong to later stages: the library-median loudness-outlier check (+/- lufs_outlier_lu, a library-level concern) and the delivery sample-rate target (deliver_min_sample_rate, enforced at the weave/master stage).

Parameters:

• samples – Waveform in [-1, 1] (mono or (frames, channels)).

• sample_rate – Sample rate in Hz.

• thresholds – Overridable QC thresholds (defaults to shipped values).

Returns:

A populated QCReport.

foley.save(samples: ndarray, sample_rate: int, dst: str | os.PathLike | BinaryIO, *, fmt: str = 'flac', subtype: str = 'PCM_24') → None

Write samples to dst as fmt/subtype (default = FLAC archive).

Parameters:

• samples – The working array to write (shape (frames,) or (frames, channels)).

• sample_rate – Sample rate in Hz.

• dst – Destination path or writable binary file-like object.

• fmt – Container/codec name (case-insensitive; passed to libsndfile).

• subtype – Sample subtype (e.g. PCM_24, PCM_16, FLOAT).

Lazy dependency: soundfile.

foley.score(segments, *, audio=None, transcript: str | None = None, library=None, intended_use=None, commercial_ok: bool = False, max_events: int = 6, verify: str = 'listen', master: str = 'podcast', weave: bool | None = None, **weave_kwargs) → ScoreResult

Choose sounds for narration text and (optionally) weave them into the narration audio.

Progressive disclosure — the AI-first headline:

foley.score("She pushed open the heavy oak door; rain hammered outside.")  # plan only
foley.score(segments, audio="narration.wav")  # + mastered mix, captions, credits

For each segment it runs the SELECT loop (decompose → search → verify → decide) with the fail-closed license gate and tasteful restraint, folds the chosen sounds into ONE editable SoundDesignTimeline, and — when audio is given (or weave=True) — aligns + weaves into a mastered mix. Returns a ScoreResult.

Parameters:

• segments – The narration text — a single string, or a list of segment strings.

• audio – The narration voice audio (path / bytes / ndarray / a library ref). When given, the result is woven into a mastered mix (set weave=False to skip).

• transcript – The full narration transcript for alignment (default: the segments joined).

• library – The foley.index.SoundLibrary (default: the process-wide default).

• intended_use – The rights intent (default: a conservative publishing IntendedUse from commercial_ok).

• commercial_ok – Shorthand for a commercial-publishing intent (the license filter).

• max_events – The sparse density cap per segment (restraint).

• verify – The max verify rung — 'clap' | 'listen' | 'judge'.

• master – The delivery MASTER_PROFILES target ('podcast' default).

• weave – Force weaving on/off; default auto (True iff audio is given).

• **weave_kwargs – Forwarded to foley.weave() (e.g. sign_cert, watermark).

Returns:

A ScoreResult (timeline + events rationale; weave when woven).

foley.search(query: str, *, k: int = 10, filters=None, commercial_ok=None, ucs_category=None, min_snr=None, duration_range=None, rerank: bool = False)

Hybrid (CLAP vector ⊕ BM25) search of the default library.

Convenience wrapper over foley.library.search(...) — see foley.index.SoundLibrary.search(). Constructs the process-wide default library (local stores + CLAP + best available index) on first use.

foley.serve_http(*, host: str = '127.0.0.1', port: int = 8000, auth: dict, path: str = '/mcp', **kwargs) → None

Build and serve the foley MCP tools over authenticated streamable HTTP (blocks).

Wraps make_http_app() and runs it with uvicorn. auth is required (fail-closed).

foley.similar(sound_id: str, *, k: int = 10)

Find sounds similar to a stored sound (audio<->audio) in the default library.

See foley.index.SoundLibrary.similar().

foley.similar_to(clip_or_candidate, *, k: int = 10, library=None) → list[Candidate]

“More like this” — neighbours of a sound id / candidate, or of a raw clip.

A str id or a Candidate uses by-id neighbours (SoundLibrary.similar, self excluded); a raw working-array / bytes clip uses audio-to-audio search (SoundLibrary.search_clip).

Parameters:

• clip_or_candidate – A sound id, a Candidate, or a clip.

• k – How many neighbours to return.

• library – The foley.index.SoundLibrary (default: the shared one).

Returns:

A list of Candidate.

foley.sqlite_vec_loadable() → bool

True if sqlite_vec is installed AND this interpreter can load it.

The macOS system / pyenv CPython builds frequently ship a sqlite3 without loadable-extension support (no enable_load_extension); on those, sqlite-vec cannot be used even when ``pip install``ed. This probes both.

foley.store_sound(record: SoundRecord, data: bytes | None = None, *, sounds: MutableMapping[str, bytes], meta: MutableMapping[str, SoundRecord], cache_bytes_ok: bool | None = None) → SoundRecord

Persist a sound, choosing by-value vs by-reference from cache_bytes_ok.

The choice is driven by the sound’s own license (invariant #1): unless cache_bytes_ok is passed explicitly, it is read from record.license.cache_bytes_ok. A sound whose bytes may NOT be cached (e.g. Freesound CC0, whose TOS forbids caching even though the file is legally redistributable — invariant #2) is stored by reference: no bytes are written, only its fetchable uri plus provenance.

Parameters:

• record – The SoundRecord to persist; its nested license is the SSOT for the storage mode. Mutated in place with the resolved storage_mode / uri / content_sha256 and written into meta.

• data – The canonical archive bytes (FLAC). Required for by-value storage; for by-reference it is optional — if given, its hash is recorded in content_sha256 for provenance but the bytes are NOT stored.

• sounds – The content-addressed byte store (see make_byte_store()).

• meta – The metadata store (see make_meta_store()).

• cache_bytes_ok – Optional override. None (the default) means “use record.license.cache_bytes_ok”.

Returns:

The same (mutated) record, after it has been written into meta.

Raises:

ValueError – If record.id is empty/non-str (checked first, so a bad id never leaves an orphan blob), or if the sound resolves to by-reference storage but record.uri is empty (a by-reference sound must name a fetchable source URL).

Note

The blob is written BEFORE the record so a crash can never leave a metadata reference dangling against a missing blob.

foley.to_mono(samples: ndarray) → ndarray

Down-mix to mono by averaging channels; 1-D input passes through.

Parameters:

samples – Mono (frames,) or multichannel (frames, channels) array.

Returns:

A 1-D mono array (dtype preserved).

foley.to_working(samples: ndarray, sample_rate: int, *, mono: bool = True, target_sr: int = 48000, dtype: str = 'float32') → ndarray

Produce the canonical CLAP/QC working array from an arbitrary clip.

Down-mixes (when mono), resamples to target_sr, and casts to dtype — the float32 @ 48 kHz mono array every embedder/tagger/QC check consumes.

Parameters:

• samples – Decoded working array (mono or multichannel).

• sample_rate – The array’s current rate in Hz.

• mono – If True, down-mix to mono.

• target_sr – Working sample rate in Hz.

• dtype – Output NumPy dtype string.

Returns:

The canonical working array.

Lazy dependency: soxr (only when sample_rate != target_sr).

foley.trim_silence(samples: ndarray, sample_rate: int, *, top_db: float = 30.0) → tuple['ndarray', tuple[int, int]]

Strip leading/trailing silence, returning the clip and its kept span.

Silence detection runs on a transient mono down-mix (so librosa’s time-last convention never clashes with foley’s time-first (frames, channels) layout); the returned sample indices then slice the original array along axis 0, preserving its channel layout.

Parameters:

• samples – Working array (mono or multichannel).

• sample_rate – Sample rate in Hz (kept in the signature for API symmetry; trimming is index-based).

• top_db – A frame is silent when it sits at least this many dB below the reference (peak) level.

Returns:

(trimmed, (start_sample, end_sample)). On all-silent (or otherwise degenerate) input the original array is returned unchanged with a full-length span (0, len(samples)).

Lazy dependency: librosa.

foley.true_peak_dbtp(samples: np.ndarray, sample_rate: int, *, oversample: int = 4) → float

Inter-sample true-peak level in dBTP.

Each channel is band-limited-upsampled oversample``x (numpy FFT), the peak magnitude is taken across all channels, and converted to dBTP. Returns ``-inf for a fully silent clip. sample_rate is accepted for interface symmetry (FFT interpolation is rate-independent).

foley.vector_search(qvec: ndarray, *, vindex: VectorIndex, k: int = 10, where: dict | None = None) → list[FusedHit]

Pure audio<->audio (or clip->library) vector search — no keyword leg.

Used by SoundLibrary.similar and by searching with a reference clip. Hits keep their cosine similarity in clap_score and preserve the index’s own descending-similarity order (rrf_score is left None — there is no fusion).

Parameters:

• qvec – An already-L2-normalized (dim,) query vector.

• vindex – The vector index.

• k – Number of neighbours to return.

• where – Optional metadata push-down.

Returns:

Up to k :class:`FusedHit`s in descending-similarity order.

foley.verify_and_setup(*, names: tuple[str, ...] | None = None) → dict[str, dict]

Return a per-requirement status + guidance report (never runs an installer).

Returns:

{name: {'available', 'purpose', 'install', 'url', 'probe'}}.

foley.verify_match(event: SoundEvent, candidate: Candidate, *, level: str | VerifyLevel = VerifyLevel.clap, judge: Judge | None = None, tau_clap: float = 0.35, _span=None) → Verdict

Verify candidate against event up to rung level (AND-confirming ladder).

Runs the clap gate always; if level is higher and the clap gate passed, escalates to the injected/​default judge for that rung and returns its verdict (Verdict.level == the producing rung).

Parameters:

• event – The wanted SoundEvent.

• candidate – A license-clean Candidate — this MUST run after the gate_candidates() gate (asserted).

• level – The max rung to climb (clap | listen | judge).

• judge – An injected Judge for the higher rungs (the DI seam; defaults per _default_judge()).

• tau_clap – The clap-gate threshold.

• _span – Internal — the obs span handle for GenAI recording on the LLM rung.

Raises:

AssertionError – If candidate.license_ok is not True (verify-before-gate is a bug — the license gate is the fail-closed first pass).