Cyber-Yichen
hermes-xiaomi-mimo-tts
Xiaomi MiMo V2.5 TTS provider for Hermes Agent with native Feishu/Lark OGG/Opus voice-message delivery.
Repository last updated Jun 30, 2026
Overview
This plugin integrates Xiaomi MiMo V2.5 TTS into Hermes Agent, enabling high-quality voice responses that can be delivered as native voice messages in Feishu and Lark. It solves three key challenges: MiMo uses a Chat Completions API rather than the standard /v1/audio/speech endpoint; MiMo natively outputs WAV, MP3, or PCM while Feishu requires OGG/Opus; and older command-based providers often produce pseudo-transcoded files that are MP3 despite having a .ogg extension.
The plugin implements Hermes' native TTSProvider interface, so no modifications to Hermes source code are needed. It calls MiMo's /v1/chat/completions using only Python standard library modules, decodes the Base64 audio from the response, and uses ffmpeg to transcode the audio to OGG/Opus. If ffmpeg is unavailable, it gracefully falls back to sending a genuine MP3 audio attachment.
This plugin is intended for developers and users running Hermes Agent on Windows who want to leverage Xiaomi MiMo TTS for voice interactions within Feishu or Lark. It supports both standard MiMo API keys and Token Plan credentials, with automatic priority handling.
Highlights
- Converts MiMo TTS to OGG/Opus for Feishu voice messages
- Supports standard API and Token Plan credentials
- Automatic ffmpeg fallback to MP3 audio attachments
- Uses only Python standard library, no external SDKs
- Preserves existing Hermes config and plugins during install
Features
Native TTSProvider Integration
Registers as <code>xiaomi-mimo</code> provider using Hermes' built-in TTSProvider API, no source code changes required.
Feishu/Lark Voice Message Delivery
Transcodes MiMo audio output to OGG/Opus format, enabling native voice message playback in Feishu and Lark.
Automatic ffmpeg Fallback
If ffmpeg with libopus is not available, the plugin falls back to sending a genuine MP3 audio attachment instead of a broken OGG file.
Credential Priority System
Supports <code>MIMO_TTS_API_KEY</code>, <code>XIAOMI_TOKEN_PLAN_API_KEY</code>, and <code>XIAOMI_API_KEY</code> with automatic priority selection.
Built-in Voice Directory
Includes a curated list of Chinese and English voices (e.g., Chloe, Milo, 茉莉) that can be selected via config.
Safe Installation Script
PowerShell installer backs up existing Hermes config and plugins before copying files and restarting the Gateway.
Requirements
- Windows 10 or 11
- Hermes Agent 0.15.0 or newer
- Hermes with tts toolset enabled
- Xiaomi MiMo API Key or Token Plan API Key
- ffmpeg with libopus encoder (optional, for voice messages)
How it's built
The plugin is written in Python 3.11+ and uses only the standard library (urllib, json, base64, subprocess, pathlib) to call the MiMo Chat Completions API. Audio is extracted from choices[0].message.audio.data as Base64, then decoded and piped to ffmpeg for transcoding to OGG/Opus. The resulting file is returned to Hermes via a MEDIA tag, which the Feishu Adapter then uploads and sends as a voice message.
The repository layout follows Hermes plugin conventions: the plugin code lives in plugin/__init__.py with metadata in plugin/plugin.yaml. Tests are in tests/test_provider.py and run with Hermes' bundled Python. The installer install.ps1 handles Windows deployment, including backup, file copy, config updates, and Gateway restart.
No external dependencies like OpenAI SDK, requests, Node.js, or Docker are required. API keys are read exclusively from environment variables or HERMES_HOME/.env and are never logged or committed.
Source
This summary was written for Neura Market from the project's own repository. Install commands, identifiers and licence details are reproduced unchanged. The Cyber-Yichen/hermes-xiaomi-mimo-tts repository is the authoritative source and the place to file issues or contribute.
Category: Content Creation · Licensed under MIT