foley.sources.elevenlabs.adapter#

ElevenLabs Sound Effects generate adapter — hosted Text-to-SFX v2 over HTTP.

Turns a natural-language prompt into a GeneratedClip via the ElevenLabs POST /v1/sound-generation endpoint (report 02 §ElevenLabs). The response is raw audio bytes (default MP3 44.1 kHz), stored by-value (the generation flywheel) once the foley.sources.generate.generate() façade routes it through ingest_one().

Two ElevenLabs-specific quirks the adapter handles:

  • ``output_format`` is a URL query parameter, not a JSON body field; everything else (text / model_id / prompt_influence / loop / duration_seconds) is the JSON body.

  • No seed / negative-prompt / step control — generation is non-deterministic, so generation_seed stays None and those unified affordances warn-and-drop.

HTTP is dependency-injected (a Transport), so the adapter is fully testable with no network and import foley stays dol-only; the real requests lives only behind requests_transport() (the foley[elevenlabs] extra). The adapter performs NO storage/library access — it builds the audio + a generated LicenseRecord and returns; the façade converges it on the shared ingest pipeline.

Module Attributes

Adapter

Registry convention (arioso): the loader imports adapter.Adapter.

Classes

Adapter

Registry convention (arioso): the loader imports adapter.Adapter.

ElevenLabsAdapter([config, api_key, http, plan])

ElevenLabs Sound Effects generate adapter (a GenerateAdapter).
foley.sources.elevenlabs.adapter.Adapter#

Registry convention (arioso): the loader imports adapter.Adapter.

class foley.sources.elevenlabs.adapter.ElevenLabsAdapter(config=None, *, api_key=None, http=None, plan=None)[source]#

Bases: object

ElevenLabs Sound Effects generate adapter (a GenerateAdapter).

Parameters:

  • config (Optional[dict]) – The SOURCE_CONFIG (defaults to the module’s). Passed positionally by the registry’s lazy loader (the arioso Adapter(config) convention).

  • api_key (Optional[str]) – The ElevenLabs token. Defaults to $ELEVENLABS_API_KEY.

  • http (Optional[Transport]) – The injected Transport (defaults to requests_transport()); tests pass a fake.

  • plan (Optional[str]) – The ElevenLabs account plan ('elevenlabs-paid-plan' | 'elevenlabs-free-plan'), which decides the generated sound’s licence. Defaults to $FOLEY_ELEVENLABS_PLAN; with neither, generate refuses before calling the API (#56). When the key in use is a per-request one (bound, not passed as api_key=), the plan is the one bound with it (using_source_accounts()), never this or the env’s (#98).

account_id()[source]#

The account a call is made on, for the generations cache ('operator' or a fingerprint).

Return type:

str

property api_key: str#

The ElevenLabs token (constructor, else a bound key, else $ELEVENLABS_API_KEY).

generate(prompt, *, duration=None, prompt_influence=None, negative_prompt=None, steps=None, seed=None, loop=False, output_format='wav', **kw)[source]#

Generate a sound effect for prompt; return its bytes + provisional candidate.

Parameters:

  • prompt (str) – The natural-language sound description (required).

  • duration (Optional[float]) – Seconds (clamped to the native 0.5..30 range). None lets the model auto-determine the length from the prompt.

  • prompt_influence (Optional[float]) – 0..1 (identity map to the native field; higher = closer to the prompt, less variety). None (default) omits it, so the API applies its own default.

  • seed (Optional[int]) – No ElevenLabs SFX equivalent — a non-default value warns-and-drops (recorded in the clip notes); generation_seed stays None.

  • loop (bool) – Produce a seamless-loopable clip (native loop; v2 default).

  • output_format (str) – Coarse foley token (wav | opus | mp3) translated to the native enum; wav is the lossless pcm_48000 wrapped in a WAV header here, falling back to MP3 (with a note) if the account’s plan refuses PCM. Ingest re-archives to FLAC.

  • **kw – Extra/unknown affordances (warn-and-dropped).

Return type:

GeneratedClip

Returns:

A GeneratedClip (origin=generated, license_id = the account plan, is_ai_generated=True).

Raises:

RuntimeError – If the plan is unknown (before any API call).

property plan: str#

The account plan = the generated sound’s license_id (fail-closed when unknown).

It follows the key: a bound (per-request) key brings its own plan, and one bound without a plan is refused rather than labelled with the operator’s.

request_salt()[source]#

What besides the request decides the result: the plan (it decides the licence).

Return type:

str