foley.agent.preview#

Audition UX — preview a sound, find similar ones, and refine by relevance feedback (#12).

The interactive/agentic layer over the existing retrieval engine, all thin over foley.index.SoundLibrary:

  • preview() — synthesize a short audition clip for a sound and reference it by a store key (never raw bytes over the wire); degrades to preview_uri=None when the audio codec extra is absent.

  • similar_to() — “more like this”: sound_id / Candidate → by-id neighbours (SoundLibrary.similar), or a raw clip → audio-to-audio search (SoundLibrary.search_clip). A NEW clip/candidate-in entrypoint, distinct from the existing by-id SoundLibrary.similar.

  • refine() — TRUE relevance feedback (distinct from the query-paraphrase foley.refine_query()): expand the query for recall, pull neighbours of the

    session’s picks, drop its rejects, and re-rank.

Dol-only core (numpy/soundfile only inside preview()’s encode path).

Module Attributes

PREVIEW_SECONDS

Default audition length (seconds).

Functions

preview(candidate_or_id, *[, seconds, ...])

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

refine([session, query, picked_ids, ...])

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

similar_to(clip_or_candidate, *[, k, library])

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

Classes

RefineResult(queries, results)

The output of refine(): the expanded queries and the re-ranked candidates.
foley.agent.preview.PREVIEW_SECONDS: int = 6#

Default audition length (seconds).

class foley.agent.preview.RefineResult(queries, results)[source]#

Bases: object

The output of refine(): the expanded queries and the re-ranked candidates.

foley.agent.preview.preview(candidate_or_id, *, seconds=6, library=None, byte_store=None, session=None)[source]#

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 (int) – 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[SessionStore]) – Optional session (unused here; accepted for a uniform signature).

Return type:

Candidate

Returns:

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

foley.agent.preview.refine(session=None, *, query=None, picked_ids=(), rejected_ids=(), hint=None, n=3, k=10, library=None, refiner=None)[source]#

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 (Optional[SessionStore]) – The audition session (source of picks/rejects when not passed explicitly).

  • query (Optional[str]) – The base text query to expand (optional).

  • rejected_ids (tuple[str, ...]) – Explicit feedback (override the session’s).

  • hint (Optional[str]) – A steer for the query expansion.

  • n (int) – Paraphrases to request.

  • k (int) – Result depth.

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

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

Return type:

RefineResult

Returns:

A RefineResult.

foley.agent.preview.similar_to(clip_or_candidate, *, k=10, library=None)[source]#

“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:
Return type:

list[Candidate]

Returns:

A list of Candidate.