Linux TTS Player for Anki (Edge Neural & Azure Speech)

Ultra-realistic Microsoft Azure / Edge Neural Text-to-Speech for Anki on Linux. Works seamlessly with native {{tts}} tags without requiring any API keys or paid subscriptions.

The Problem

• macOS has the native say command built into Anki.
• Windows has native SAPI / Windows Media Speech built into Anki.
• Linux has NO native TTS player in Anki.

When you download shared decks or sync decks created on iOS, macOS, or Android, they frequently include tags like:

{{tts it_IT voices=Apple_Federica_(Premium),com.google.android.tts-it-it-x-itb-local:ItalianWord}}
{{tts fr_FR voices=Apple_Audrey_(Premium),Microsoft_Vivienne:FrenchWord}}

On Linux, these tags either fail completely into silence, or fall back to robotic, metallic voices. Heavy add-ons often require setting up cloud API keys, monthly subscriptions, or complicated menus.

The Solution

Linux TTS Player bridges this gap:

1. Pristine Neural Voices: Uses Microsoft's state-of-the-art Azure Speech / Edge Neural engines.
2. Zero Setup & Zero Keys: Works out-of-the-box with no Microsoft account, credit card, or API key needed.
3. Universal Language & Tag Normalization: Handles it, it-IT, it_IT, ita (ISO 639-1, 639-2/3, BCP 47).
4. Transparent Voice Aliasing: Automatically maps Apple (Apple_*), Android (com.google.android.tts-*), and Microsoft voices to their corresponding Azure Neural voices.
5. Dynamic On-The-Fly Synthesis: Whenever you review a brand-new card, audio is synthesized in ~500 ms and cached locally. Subsequent reviews play instantly (<1 ms).
6. Multi-Tier Resilience: If you are ever offline without internet, it automatically falls back to standard Google Translate TTS or offline espeak-ng.
7. Optimized for Modern Linux Audio: Direct, low-latency playback via mpv integrated with PipeWire and PulseAudio, including volume compensation.

Supported Languages & Voices

Includes 322 Microsoft Azure / Edge Neural voices across 142 locales (all bundled offline in voices.json).

All standard languages supported by gTTS and espeak-ng are also supported as automatic fallbacks.

Installation

System Prerequisites

Make sure mpv is installed on your Linux distribution:

• Arch Linux / Omarchy: sudo pacman -S mpv
• Ubuntu / Debian: sudo apt install mpv
• Fedora: sudo dnf install mpv

(Optional) For offline fallback: sudo pacman -S espeak-ng or sudo apt install espeak-ng.

Option A: Install via .ankiaddon File (Recommended)

1. Download the latest linux_tts_player.ankiaddon from the Releases page.
2. In Anki, go to Tools → Add-ons → Install from file...
3. Select linux_tts_player.ankiaddon and restart Anki.

Option B: Install via Git / Manual Clone

1. Open a terminal and navigate to your Anki add-ons directory:

   cd ~/.local/share/Anki2/addons21/
   

2. Clone this repository directly into linux_tts_player:

   git clone https://github.com/argrig666/anki-linux-tts-player.git linux_tts_player
   

3. Restart Anki.

Configuration

In Anki, navigate to Tools → Add-ons → select Linux TTS Player (Edge Neural & Azure Speech) → click Config.

{
  "default_voices": {
    "it_IT": "it-IT-ElsaNeural",
    "fr_FR": "fr-FR-DeniseNeural",
    "en_US": "en-US-JennyNeural"
  },
  "volume": 140,
  "audio_output": "pipewire,pulse",
  "debug_log": false
}

• default_voices: Choose your preferred voice for any language when a card template uses general tags like {{tts it_IT:Word}}. Prefer dedicated monolingual voices (e.g. fr-FR-DeniseNeural) over *MultilingualNeural voices for language-learning decks.
• volume: Adjust software playback gain (default: 140%).
• audio_output: Set mpv audio driver (default: "pipewire,pulse").
• debug_log: Set to true to log synthesis events to user_files/debug.log.

Architecture & How It Works

flowchart TD
    A["Card Review ({{tts it_IT voices=...:Field}})"] --> B["LinuxTTSPlayer Voice Resolver"]
    B --> C{"Check Local Cache"}
    C -- "Hit (< 1 ms)" --> F["Direct mpv Subprocess Playback (PipeWire)"]
    C -- "Miss (New Card)" --> D["edge-tts Neural Synthesis (~500 ms)"]
    D -- "Success" --> E["Save MP3 to Edge Cache Slot"]
    D -- "Network / 403 Error" --> G["gTTS / espeak-ng Fallback"]
    G --> H["Save to Separate Fallback Cache Slot"]
    E --> F
    H --> F

Cache keys include the synthesis engine (edge / gtts / espeak) so a temporary fallback cannot overwrite a neural cache entry.

Troubleshooting

If neural voices suddenly sound lower quality, or debug logs show 403 Invalid response status, see SUPPORT.md. Short version for the October 2026 Edge TTS outage:

1. Use add-on v1.1.0+ (edge-tts>=7.3.0).
2. Clear user_files/cache/ and restart Anki.
3. Re-review affected cards so audio regenerates.

License

GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE for details. Includes dependencies under vendor/ according to their respective open-source licenses.