Prerequisites
- Hermes Agent 0.21.5 or newer (Python 3.11+, macOS or Linux). Streaming voice replies and live dictation require Hermes Agent 0.21.6 or newer.
- A Fish Audio API key from fish.audio/app/api-keys.
Installation
Install and enable the latest release from GitHub:--yes-deps installs the plugin’s Python dependencies without prompting. Hermes 0.21.5 installs dependencies automatically and does not accept --yes-deps, so omit the flag on 0.21.5.
You can also install from the Hermes plugin catalog:
The catalog installs the release pinned in the Hermes catalog, which may lag
behind the latest GitHub release (check with
hermes plugins list). To switch
from a catalog install to the GitHub repository, remove it first with hermes plugins remove fish-audio, then run the GitHub install command above.Hermes Desktop
When Hermes Desktop runs on the same computer as your agent, it picks up the desktop interface automatically after a CLI install. Open Capabilities > Plugins > Fish Audio, switch on Desktop, and restart the gateway once. If Desktop is connected to an agent on another machine, install directly in Desktop:- Open Capabilities > Plugins > Install from Git and enter
https://github.com/fishaudio/fish-audio-hermes. - Select Review repository, then Install (with Enable after install checked; on Desktop older than 0.21.7, also switch on Desktop under Capabilities > Plugins > Fish Audio).
- Restart the agent’s gateway once so Hermes mounts the plugin’s desktop routes.
Configuration
Save your API key on the machine that runs Hermes:login validates the key against your Fish Audio account and saves it to the active Hermes profile. Where no speech or transcription provider is set, it selects Fish Audio. In an interactive terminal, it asks before replacing another provider; noninteractively, it preserves an existing provider unless you pass --yes. Pass --key-stdin to read the key from standard input.
You can also enter your key in Hermes Desktop (Voices > Enter API key, which opens Settings > Plugins > Fish Audio > Agent settings; on older Desktop builds, open the gear icon on the fish-audio row in Capabilities > Plugins) or with hermes tools > Text-to-Speech > Fish Audio. Never paste API keys into chat.
A key saved in Desktop’s Agent settings takes effect immediately. After hermes fish login or hermes tools, restart a running Hermes gateway or Desktop app to pick up the new key.
Verify your setup from any chat with the free checklist:
doctor runs one short billed synthesis to verify the full round trip. Pass --no-synth to check your key, wallet, providers, Hermes version, and STT registration without making a billed synthesis.
Voices and settings
Search the Fish Audio voice library, switch voices, and hear a short billed preview from any chat:/fish use, /fish preview, and hermes fish use accept a Fish voice ID, a saved name, or a unique title of one of your own voices (case-insensitive; use a single-word title with /fish preview).
In Hermes Desktop, open Voices to browse and preview the library with custom preview text, star favorites, click Use, edit or delete your own voices under My voices, clone or design voices under Create, and check credit under Account. On Desktop 0.21.6 or newer, Settings > Plugins > Fish Audio also lets you set the selected agent’s voice, speech model, reading speed (0.5×–2.0×), and saved voice names, with plugin options under Agent settings. The Desktop UI follows Hermes Desktop’s display language across nine languages.
All settings are per Hermes profile and can also be configured in config.yaml:
plugins.entries.fish-audio.settings options include base_url (an HTTPS URL, or HTTP on loopback, for a self-hosted Fish Audio endpoint) and operator_account: true (for operator-owned Fish accounts, hiding balances, billing links, and account-wide voices and dictionaries from end users).
Features
- Text-to-speech and streaming voice: Voice replies, read-aloud, and voice notes use Fish Audio. S2 models (
s2.1-pro,s2-pro,s2.1-pro-free) follow inline emotion and delivery cues in square brackets such as[excited]or[whispering], and support multi-speaker dialogue (<|speaker:N|>). On Hermes 0.21.6 or newer, CLI voice mode, the TUI, Desktop read-aloud, and gateway streaming stream 24 kHz PCM sentence by sentence (POST /v1/tts), retrying temporary rejections before audio starts; Hermes 0.21.5 synthesizes whole files before playback. (s1is deprecated and retires December 31, 2026.) - Drama 3: Switch to Drama 3 with
/fish model drama-3. Plain-language performance directions and sounds in square brackets work in every voice reply; agents send word-level tags such as<whisper>…</whisper>and multi-speaker markup throughfish_speak, which passes them to Fish Audio unchanged. - Speech-to-text and live dictation: Voice notes and recordings use
transcribe-1-pro(transcribe-1is deprecated and retires December 31, 2026). On Hermes 0.21.6 or newer, setstt.streaming: truefor live dictation in CLI voice mode, the TUI, and Desktop’s composer mic. By default, live dictation streams 16-bit PCM to Fish Audio’s native realtime speech-to-text endpoint (transcribe-stream-1, Preview) for word-by-word draft captions, billed per second of open session; failed or incomplete live sessions automatically fall back to file transcription. Setlive_transcription: compatto use the ElevenLabs-compatible endpoint with phrase captions billed per committed phrase. - Pronunciation dictionaries: Create, publish, and pin up to three reusable pronunciation dictionaries per profile with
fish_pronunciations, or pass per-callpronunciations(phonemes),spoken_as(plain-text alias replacements), ordictionariestofish_speak. - Agent tools (toolset
fish_audio):fish_speak: Expressive and multi-speaker speech withdelivery(voiceorfile), non-overwritingoutput_path,language,speed, pronunciations, andtimestamps: true(word timings, complete.alignment.jsonsidecar, and SRT/WebVTT subtitles).fish_voices: Search, list, inspect,audition(up to four voices reading a passage of up to 200 characters), clone, design, save, update, and delete voices.fish_transcribe: Transcribe recordings with speaker turns (diarize), timestamps, and SRT subtitles.fish_settings: Inspect or update the profile’s voice, model, reading speed (0.5–2.0), saved voice names, and setup status (free).fish_account: Check API credit and plan, list models with pricing and retirement dates, and run offline cost estimates before synthesis or transcription (free).fish_pronunciations: Manage reusable pronunciation dictionaries and profile defaults (free).
- Built-in skills: Includes six workflow skills covering guided setup (
fish-audio-setup), expressive speech (fish-audio-expressive-speech), voice casting and creation (fish-audio-voice-studio), long-form chapter narration with cost estimates and resumable manifests (fish-audio-long-form), multi-speaker clip translation and voice-over (fish-audio-translate-voice), and redacted bug reporting (fish-audio-report-problem).
Commands
Chat commands
Available in the CLI, messaging gateways, and Hermes Desktop:Terminal CLI
Run setup, diagnostics, and noninteractive scripting commands from your terminal:- Setup and diagnostics:
hermes fish login [--key-stdin] [--yes],hermes fish status,hermes fish doctor [--no-synth], andhermes fish use <voice> - Scripting (noninteractive; add
--jsonfor structured output with exit code0on success or1on failure):hermes fish speak,hermes fish transcribe,hermes fish voices, andhermes fish balance
plugins.isolation: host), the hermes fish terminal command is unavailable and voice replies use whole-file speech instead of streaming; /fish chat commands, tools, and speech/transcription providers continue to work.
Billing, approvals, and MCP
- Billing: Synthesis, transcription, voice cloning, and voice design are billed to your Fish Audio API credits (see Pricing & Rate Limits), except requests that run on the free
s2.1-pro-freemodel (free through November 30, 2026). Settingallow_free_model: falseresolvess2.1-pro-freerequests to paids2.1-pro.fish_settings,fish_account,fish_pronunciations,/fish setup,/fish status,/fish balance, andhermes fish doctor --no-synthdo not incur Fish Audio charges. - Approvals: Cloning or deleting voices and deleting pronunciation dictionaries or historical versions from chat go through Hermes’s approval gate. On the Desktop Voices page, you confirm speaker consent and deletions directly on the page.
- Plugin vs. MCP server: This plugin authenticates with a developer API key (billed to API credits) and registers Fish Audio as Hermes’s speech and transcription provider. For Story Studio projects, image generation, or video generation billed to web app plan credits over OAuth, connect the Fish Audio MCP server instead (
hermes mcp add fish-audio --url https://api.fish.audio/mcp --auth oauth --connect-timeout 180on Hermes 0.21.7 or newer).

