elevenlabs-sound-effects

ElevenLabs Sound Effects for Hermes Agent

Part of the Hermes Official Plugins, Nous Research's official plugins for Hermes Agent.

Official Hermes Agent plugin for the
ElevenLabs Sound Effects API. It gives the
agent one tool:

Ask for "the sound of a heavy wooden door creaking open in a stone hall", "a short retro coin pickup
blip" or "90s hip-hop drum loop, 90 BPM, loopable" and Hermes generates it and saves it. The tool hands
the agent a MEDIA: line for the file; when the agent puts it in its reply, the file is sent as an
attachment on Telegram, Discord, Slack and the other messaging platforms. MP3 (the default format)
plays inline on most chat apps; Ogg Opus and WAV can arrive as plain files (Telegram shows them that
way). On Discord, Hermes releases after v0.22.5 send MP3 and WAV as normal attachments that play
inline (v0.22.5 and earlier sent them as voice messages). In Hermes Desktop the
same line becomes an inline sound card (below). In the terminal you get the file path.

The plugin also ships:

Install

hermes plugins install elevenlabs-sound-effects

Or straight from this repo: hermes plugins install NousResearch/hermes-official-plugins#elevenlabs-sound-effects.

The installer asks for your ElevenLabs API key if ELEVENLABS_API_KEY is not set yet (create one
under Profile → API keys at https://elevenlabs.io/app/settings/api-keys). It is the same key
Hermes's ElevenLabs text-to-speech voice uses, so if you already have that set up there is nothing
to enter. A restricted key needs the Sound Effects permission enabled (separate from Text to Speech). The tool only appears to the agent once the key is set. Plugins are installed per profile:
use hermes -p <profile> plugins install elevenlabs-sound-effects for another profile.

The only Python dependency is httpx, which Hermes already ships.

Settings

In Hermes Desktop: Capabilities → Plugins, then the gear icon on the plugin (the settings page is
titled with the package name, elevenlabs-sound-effects). Everywhere else, with hermes config set:

The agent chooses the per-sound parameters itself: the description (at most 450 characters; longer
prompts are refused before anything is sent), the length (duration_seconds, 0.5 to 30; omit it and
ElevenLabs picks one), loop, and prompt_influence (0 to 1; higher follows the prompt more
literally, lower varies more).

The tool also takes an optional model per call (eleven_text_to_sound_v2 or
eleven_text_to_sound_v3); without it the sound_model setting applies.

Where files go

Each sound is saved to <HERMES_HOME>/cache/generated/audio/sfx_<description>_<timestamp>_<id>.<ext>
and never overwrites an earlier one. The Desktop card and library serve a file only while it has a single
link: after a backup tool hard-links your Hermes folder (rsnapshot, cp -al), those sounds play in
Desktop's built-in player instead of the card, and the library can't play or download them until the
extra links are removed (the files themselves are untouched). Ask the agent to copy it into your project if you want it
somewhere else.

Each generation also appends one line to <HERMES_HOME>/plugin-data/<plugin namespace>/sounds.jsonl
(the plugin's own data folder, per profile): the sound id, prompt, requested length, the length of
the audio ElevenLabs returned, loop, prompt influence, model, format, file name, size, the credits
ElevenLabs billed, and the chat it came from.
The Desktop library reads it. Nothing in it leaves your machine.

Hermes Desktop

The Desktop half is opt-in, also after hermes plugins install from the CLI (which turns on only the
agent half): open Capabilities → Plugins, switch to the list view, and turn on
Desktop: ElevenLabs Sound Effects on the plugin's row. Without it Desktop still plays every sound,
in its built-in audio player.

Sound card. The tool always hands the agent a plain MEDIA: line, the one every surface plays.
Hermes Desktop works out which tool produced that file and, when it was elevenlabs_sound_effect and
the Desktop half is on, lets this plugin draw it as a sound card instead of the built-in audio player.
That needs a Hermes Desktop with tool-media renderers (on main since commit 567569267a; first in the
next release after v0.22.5). On older Desktops, or with the Desktop half off, the same line plays in
Desktop's built-in player. The card also hands the sound back to the built-in player whenever it can't
play it itself: a sound made in another profile, a removed record, or a file the plugin won't serve
(see Where files go). Nothing depends on which surface a chat was started on, and the
agent never writes a card line.

The card shows the prompt, length, loop, model, format and credits billed, a waveform you can click
to seek, Play/Pause, a Loop toggle that repeats the sound gaplessly so you can hear the seam,
Download (the original, or MP3 / WAV / OGG converted by ffmpeg on the machine Hermes runs on;
saved through Desktop's Save dialog on your computer), and Reveal in your file manager. Next
offers 3 variations, shorter, longer, make it loop and try the other model. Each row shows its cost
worked out from what ElevenLabs billed for this sound (an automatic-length sound is billed a flat
amount per generation, so its per-second price isn't known, and the row says so), and sends a chat message to the agent naming the tool and its
arguments. Nothing is billed until the agent runs the tool. On Desktop builds that tell plugins which
chat shows a card, the message goes to that chat, and nowhere else: if that chat is not on screen,
Desktop shows a notice instead. Older builds send it to the chat you last typed in.

Sound library. ⌘K → ElevenLabs: open sound library opens a tab listing every sound the tool
made in the active profile, MP3, Ogg Opus and WAV alike, with per-format counts and sizes, a format
filter and a prompt search. Each row plays, downloads, reveals, Reuse prompt (into the composer)
and Open chat (the conversation that made it). It reloads when a sound is generated, when you
switch profile or connection, and when you save the plugin's settings; it never polls.

Remote Hermes. The Desktop half runs in the Desktop app, so install the plugin on the Hermes
machine (agent half) and into the Desktop you use: Capabilities → Plugins → Install from Git with
NousResearch/hermes-official-plugins/elevenlabs-sound-effects and Desktop UI checked, then turn
on the Desktop switch. Without that, Desktop lists the half as unavailable for the remote backend and
sounds play in its built-in player. The files stay on the Hermes machine. Playback and downloads stream through Hermes, so they work the same. On a registered remote
connection Reveal is replaced by a note saying which host holds the file; where Desktop can't tell
(a per-profile remote override) the library names the host the backend reports and Reveal explains
when the file is not on this computer. Format conversion needs ffmpeg on that host; without it only
the original format is offered and the menu says why.

Cost and privacy

Every call is a paid ElevenLabs generation billed to your account: ElevenLabs charges per second of
audio when a duration is set (about 10 credits per second, as billed to us) and a flat amount per
generation otherwise (about 50 credits, for 2 s and 3 s automatic clips alike; see their
pricing). Loops can come back longer than requested (we measured
1 s → 1.5 s and 2 s → 2.25 s, billed 10 and 20 credits): the tool reports the real length as
length_seconds beside requested_duration_seconds, and the card shows both. The tool reports the character-cost header
ElevenLabs returns as billed_characters. Desktop format conversions and the processing script run
locally and cost nothing. What leaves your machine: the sound description and the
parameters above, sent to api_base_url with your API key. Nothing else from the conversation is
sent.

Local processing script

The bundled skill runs skills/elevenlabs-sound-design/scripts/sfx_tool.py (Python standard library
plus ffmpeg/ffprobe on PATH) when a sound needs processing (python instead of python3 where
only that exists, as on Windows):

python3 sfx_tool.py process in.wav --out out.ogg --trim --loudness -16 --fade-ms 10   # one-shot: trim + normalise + fade + convert
python3 sfx_tool.py process loop.mp3 --out loop.ogg                                   # plain conversion keeps a loop's edges
python3 sfx_tool.py loopfix loop.wav --out fixed.wav                                  # crossfade the seam (+ crossfade_level_db)
python3 sfx_tool.py loopcheck fixed.wav                                               # seamless | click | silent, worst channel (+ a note when the seam dips)
python3 sfx_tool.py pack a.mp3 b.mp3 --name "UI pack" --out-dir . --format ogg # folder + manifest.json + zip
python3 sfx_tool.py process take1.mp3 --out t1.wav --trim --loudness -18 --mono      # a positional game one-shot: mono, levelled
python3 sfx_tool.py pack t1.wav t2.wav t3.wav --name "Footstep Gravel" --out-dir . --variations  # footstep_gravel_01..03 + loudness_spread_lu

Every run prints one JSON line ({"ok": true, ...} or {"ok": false, "code": ..., "error": ...}),
including when ffmpeg is missing, an input is not audio or an output can't be written. Codes:
ffmpeg_missing, bad_input, bad_args, ffmpeg_failed, interrupted, internal. process
reports the loudness it measured on the output (output.integrated_lufs, output.true_peak_dbtp):
--loudness aims at the target under a -1.5 dBTP ceiling, so a peaky clip can land below it.

Development

cd elevenlabs-sound-effects
HERMES_AGENT_REPO=../../hermes-agent PYTHONPATH=../../hermes-agent python -m pytest -q
hermes plugins validate .
npm ci && npm test && npm run typecheck && npm run build   # Desktop half: src/*.tsx → desktop/plugin.js

The tests load the plugin through Hermes's real plugin discovery and dispatch the tool through the
real registry against a local stand-in for POST /v1/sound-generation that checks requests against
ElevenLabs' published OpenAPI schema; they never call ElevenLabs. tests/test_library.py reads the
provenance records back through dashboard/plugin_api.py; tests/test_sfx_tool_script.py runs the
script (its ffmpeg cases skip where ffmpeg is absent); tests/sound.test.mjs covers the card's Next
actions and helpers, and tests/plugin.test.mjs registers the real Desktop half against a stub SDK with
and without Desktop's tool-media renderer area.

The Desktop half is TypeScript in src/, bundled with esbuild into desktop/plugin.js, which is
committed (Hermes Desktop loads it as is). It imports only @hermes/plugin-sdk and react;
sdk.d.ts declares the SDK names it uses, and newer SDK calls are feature-detected. Rebuild and
commit desktop/plugin.js after any change under src/.

License

MIT, see LICENSE.

README from the reviewed commit e7a218f; it updates when the author re-pins.