Metadata-Version: 2.4
Name: foley
Version: 0.0.17
Summary: Unified facade for sourcing, indexing, and searching sound effects to weave into narration
Project-URL: Homepage, https://github.com/thorwhalen/foley
Project-URL: Repository, https://github.com/thorwhalen/foley
Project-URL: Documentation, https://thorwhalen.github.io/foley
Author: Thor Whalen
License: mit
License-File: LICENSE
Keywords: audio,audio-retrieval,clap,foley,narration,sfx,sound-design,sound-effects,text-to-audio
Requires-Python: >=3.10
Requires-Dist: dol
Provides-Extra: agent
Requires-Dist: anthropic; extra == 'agent'
Provides-Extra: align
Requires-Dist: torch; extra == 'align'
Requires-Dist: whisperx; extra == 'align'
Provides-Extra: audio
Requires-Dist: librosa; extra == 'audio'
Requires-Dist: numpy; extra == 'audio'
Requires-Dist: pyloudnorm; extra == 'audio'
Requires-Dist: soundfile; extra == 'audio'
Requires-Dist: soxr; extra == 'audio'
Provides-Extra: c2pa
Requires-Dist: c2pa-python; extra == 'c2pa'
Provides-Extra: caption
Requires-Dist: torch; extra == 'caption'
Requires-Dist: torchaudio; extra == 'caption'
Requires-Dist: transformers>=4.40; extra == 'caption'
Provides-Extra: clap
Requires-Dist: torch; extra == 'clap'
Requires-Dist: transformers>=4.40; extra == 'clap'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
Requires-Dist: sphinx>=6.0; extra == 'docs'
Provides-Extra: elevenlabs
Requires-Dist: requests; extra == 'elevenlabs'
Provides-Extra: eval
Requires-Dist: ranx>=0.3; extra == 'eval'
Provides-Extra: fit
Requires-Dist: torch; extra == 'fit'
Requires-Dist: torchaudio; extra == 'fit'
Requires-Dist: transformers>=4.40; extra == 'fit'
Provides-Extra: freesound
Requires-Dist: requests; extra == 'freesound'
Provides-Extra: index
Requires-Dist: lancedb>=0.13; extra == 'index'
Provides-Extra: index-sqlite
Requires-Dist: sqlite-vec>=0.1.0; extra == 'index-sqlite'
Provides-Extra: mcp
Requires-Dist: py2mcp; extra == 'mcp'
Provides-Extra: obs
Requires-Dist: opentelemetry-sdk>=1.37; extra == 'obs'
Provides-Extra: provenance
Requires-Dist: audioseal; extra == 'provenance'
Requires-Dist: numpy; extra == 'provenance'
Requires-Dist: soundfile; extra == 'provenance'
Requires-Dist: torch; extra == 'provenance'
Requires-Dist: torchaudio; extra == 'provenance'
Provides-Extra: stable-audio
Requires-Dist: accelerate; extra == 'stable-audio'
Requires-Dist: diffusers>=0.27; extra == 'stable-audio'
Requires-Dist: soundfile; extra == 'stable-audio'
Requires-Dist: torch; extra == 'stable-audio'
Requires-Dist: transformers>=4.40; extra == 'stable-audio'
Provides-Extra: tag
Requires-Dist: panns-inference; extra == 'tag'
Provides-Extra: test
Requires-Dist: numpy; extra == 'test'
Requires-Dist: pyloudnorm; extra == 'test'
Requires-Dist: pytest-cov>=4.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Requires-Dist: soundfile; extra == 'test'
Requires-Dist: soxr; extra == 'test'
Provides-Extra: weave
Requires-Dist: opentimelineio; extra == 'weave'
Description-Content-Type: text/markdown

# foley

Find (or generate) the **right sound effect for a moment of narration** — and weave it in.

foley is a **retrieval-first façade for sound effects**: one simple surface over many
sound *sources* (your own library, service APIs, and generative-AI models), a searchable
*index* of every sound (by keyword **and** meaning), an *agent* that picks the right
sound for a narrative context, and a *compositor* that places it under the voice.

It's the SFX sibling of [`arioso`](https://github.com/thorwhalen/arioso) (a unified
façade over AI music-generation backends): same discipline — one entry function,
config-driven plugin adapters, a unified vocabulary translated per-backend, zero
required core deps with lazy optional-deps — but centered on **search** rather than
generation, with generation as just one of several sources.

> **Status: v1.** All four stages — source, index, select, weave — plus the MCP server
> and the licensing/provenance, evaluation, and observability layers are implemented
> (Epic #13 complete). The API below is live; see the [roadmap](misc/docs/roadmap.md)
> for what's next. Follow along in [`misc/docs/`](misc/docs/).

## The idea

```python
import foley

# The headline — right sounds for a narrative context:
# decompose the passage into salient sound events → search → verify → decide
candidates = foley.find("She pushed open the heavy oak door; rain hammered outside.")

# Direct hybrid search of your library (text query or a reference clip)
hits = foley.search("distant thunder rumble", k=10, commercial_ok=True)

# Generate a sound when nothing fits (arioso-style; pluggable backends)
clip = foley.generate("a single wooden door creak", backend="stable_audio", duration=3)

# Grow the library — ingest auto-tags, captions, and embeds every file
foley.ingest("~/my_sounds/")
foley.add_from("freesound", query="ocean waves", license="cc0")

# Compose: place the sounds under the narration (find → plan → weave)
timeline = foley.plan(candidates)  # the editable sound-design plan
result = foley.weave("narration.wav", timeline)  # mastered mix + SDH captions + credits
```

## How it works — four stages

| Stage | What it does | Built on |
|-------|--------------|----------|
| **Source** | your own files · Freesound (CC0) · generate (Stable Audio Open / ElevenLabs) | config-driven adapters, per-sound license tracking |
| **Index** | probe → tag → caption → embed every sound; hybrid keyword+semantic search | PANNs · CLAP · EnCLAP · LanceDB (local→cloud via `dol`) |
| **Select** | decompose a narrative context → search → verify → generate-or-retrieve | CLAP retrieval + LLM decomposition + a verification ladder |
| **Weave** | align to the voice, duck, place, master → mastered mix + editable timeline + captions + credits | forced-alignment · LUFS/EBU-R128 |

The selection tools publish as an **MCP server** (via `py2mcp`) so the same capabilities
drive the agent, a CLI, and external hosts.

## Design & research

foley's design is grounded in five research reports (unified, cited):

- [Design](misc/docs/design.md) · [Roadmap](misc/docs/roadmap.md)
- [Research reports](misc/docs/research/) — sound sources, SFX generation, recognition/
  tagging, embeddings/indexing, and the context-retrieval agent
- [Deep-research prompt library](misc/docs/research/deep-research-prompts.md) — 12
  ready-to-run prompts covering every dimension of the project

## Install

```
pip install foley
```

(Optional per-capability extras — `foley[freesound]`, `foley[clap]`, `foley[stable-audio]`,
`foley[index]`, … — are added as each subsystem lands.)

## License

MIT
