f5-tts

Files (2)

• SKILL.md
• api.md · references/

SKILL.md (first lines)

# f5-tts

Use this skill when the task is specifically about the user's local F5 TTS server or when you need to choose a voice profile directly instead of relying on Hermes' default `text_to_speech` configuration.

## Core workflow

1. Check the service first with `GET /health`.
2. Read the base URL from `tts.f5.base_url` in `~/.hermes/config.yaml` when available. Default to `http://localhost:8081`.
3. Use the already-loaded environment variable `F5TTS_SECRET_KEY` when you need to authenticate directly.
4. Generate a short-lived HS256 bearer token from that env value.
5. Call `GET /api/v1/voices/list` to discover valid `voice_profile` names instead of guessing.
6. Call `POST /api/v1/tts/synthesize` with exact user text plus the selected `voice_profile`.
7. Save the returned WAV bytes to disk and return the file path or `MEDIA:` tag as needed.

## Preferred behavior

- Prefer the built-in Hermes `text_to_speech` tool when the user simply wants speech output and the configured default voice is fine.
- Prefer direct F5 API use when the user wants to inspect voices, pick a specific cloned voice, debug the local TTS service, or bypass Hermes' default provider selection.
- Preserve the user's text exactly unless they asked for rewriting.
- For long text, keep the FastAPI request body within the service limit by chunking and stitching rather than relaxing validation.
- Do not ask the user for the secret key if `F5TTS_SECRET_KEY` is already present in the environment.

## Long text

- The local F5 FastAPI endpoint accepts `text` up to 1000 characters per request.
- For text longer than that, split on sentence boundaries when possible.
- If a sentence still exceeds the limit, split on whitespace, then hard-split only as a last resort.
- Synthesize each chunk separately and concatenate the WAV files in order.
- For Telegram voice bubbles, convert the final WAV to OGG Opus after stitching.

## Failure handling

- If `/health` fails, report that the local F5 container is unavailable before trying anything else.
- If auth fails, first check whether `F5TTS_SECRET_KEY` is already present in the environment and use it before asking the user for anything.
- If auth still fails after using the env var, verify `F5TTS_SECRET_KEY` matches the FastAPI container `SECRET_KEY`.
- If a requested voice is missing, list available voices from `/api/v1/voices/list`.
- If synthesis fails on long text, retry with shorter chunks instead of sending a larger single request.

## Reference file

- Load `references/api.md` when you need exact endpoint shapes, token generation snippets, or direct request examples.

From helix4u/hermes-agent-private, MIT.

More from helix4u/hermes-agent-private