speechfy

Speechify TTS

Multi-provider Text-to-Speech: Speechify API (primary, Cristiane voice) with automatic Edge TTS fallback (FranciscaNeural). Outputs .ogg (Opus) ready for voice messages.

⚡ Quick Start

# Basic usage
python3 scripts/speechfy-tts.py "Hello, world!" /tmp/hello.ogg

# With custom voice via env
SPEECHIFY_VOICE=bruno python3 scripts/speechfy-tts.py "Texto" /tmp/saida.ogg

Architecture

Text (CLI)
    │
    ├── Speechify API ──► .mp3 ──► ffmpeg ──► .ogg (Opus)
    │   (primary)
    │
    └── Edge TTS ──────► .ogg (Opus)
        (fallback)

Speechify fails when:

• No API key configured (env var or vault missing)
• Monthly quota exceeded (HTTP 402 — spend_cap_exceeded)
• Rate limited (HTTP 429)
• Network timeout

Prerequisites

Configuration

All via environment variables (no hardcoded config):

Resolution order: SPEECHIFY_API_KEY env var → vault-resolver → empty (skip).

Usage

CLI

# Simple text, default output
python3 scripts/speechfy-tts.py "Hello, how are you?"

# Custom output path
python3 scripts/speechfy-tts.py \
  "Important announcement" /tmp/alert.ogg

# SSML (Speech Synthesis Markup Language)
python3 scripts/speechfy-tts.py \
  'Excited'

Voice Messages (Telegram)

Include the .ogg path with MEDIA: prefix:

MEDIA:/tmp/speech-output.ogg

.ogg with Opus codec is the native voice bubble format on Telegram.

Programmatic (Python)

import subprocess

def generate_speech(text, output="/tmp/speech.ogg"):
    proc = subprocess.run(
        ["python3", "scripts/speechfy-tts.py", text, output],
        capture_output=True, text=True, timeout=60
    )
    if proc.returncode == 0:
        return output
    raise RuntimeError(f"TTS failed: {proc.stderr}")

Hermes Agent (skill integration)

import subprocess
output = "/tmp/response.ogg"
subprocess.run([
    "python3", "scripts/speechfy-tts.py",
    text, output
], check=True)

SSML Cheat Sheet

Speechify supports SSML via the input field. Pass XML as the text argument.

Emotions (``)

  Great news!
  
  Let's analyze calmly.

Prosody (pitch, rate, volume)

  Normal tone.
  5% higher pitch
  Lower and slower
  High and fast

Pitch: percentage (-83% to +100%) or levels (x-low to x-high) Rate: percentage or levels (x-slow to x-fast)

Pauses and Emphasis

  This is very important.
  
  And now this.

SSML Limitations

• ⚠️ Input limit: 2,000 chars on /v1/audio/speech (including SSML tags)
• ⚠️ For longer text: use streaming /v1/audio/stream (20,000 chars)
• ⚠️ Escape special chars: & → &, < → <, > → >

Plans and Limits

Edge TTS is free and unlimited — always works as fallback.

Multi-platform

Hermes Agent

Use via terminal() or execute_code():

import subprocess
result = terminal(
    f"python3 scripts/speechfy-tts.py {shlex.quote(text)} /tmp/out.ogg"
)

OpenClaw

# Direct invocation
python3 scripts/speechfy-tts.py "Hello" /tmp/out.ogg

# With mcporter (if configured for Speechify MCP)
mcporter call speechify.synthesize text="Hello"

Troubleshooting

"No API key found"

• Set SPEECHIFY_API_KEY env var, or
• Add item to Vaultwarden with name matching SPEECHIFY_VAULT_ITEM

"Speechify HTTP 402"

• Monthly quota exhausted (50K chars on free tier)
• Script automatically falls back to Edge TTS

"Speechify HTTP 429"

• Too many concurrent requests (free limit: 3 simultaneous)
• Wait a few seconds and retry

Edge TTS not working

pip install edge-tts
edge-tts --voice pt-BR-FranciscaNeural --text "test" --write-media /tmp/test.ogg

ffmpeg not found

# Debian/Ubuntu
sudo apt install ffmpeg

# Arch/Manjaro
sudo pacman -S ffmpeg

Related

• Speechify API Docs
• Edge TTS (GitHub)
• SSML W3C Spec
• references/voices.md — Available voices reference
• docs/diagrama.svg — Architecture diagram