Audio Dictionary & TTS Player with Fallback & Smart Caching for Anki
A powerful Anki audio add-on with a 3-tier playback system: prioritizes your local audio dictionary, falls back to online gTTS, and finally to offline Piper TTS.
Attribution & Source
This add-on is a modified fork of the official gTTS Player developed by Ankitects Pty Ltd.
Original Project: Source Code | AnkiWeb (391644525) This Enhanced Version: Source Code | AnkiWeb (42281744)
Licensed under the GNU AGPL, version 3 or later.
This enhanced version uses a 3-tier system for audio playback: a local high-fidelity audio dictionary, Google’s online TTS service, and a local Piper TTS engine for a complete offline fallback.
Table of Contents Audio Dictionary & TTS Player with Fallback & Smart Caching for Anki Table of Contents Project Philosophy Features How It Works Prerequisites Installation Part 1: Install the Add-on Part 2: Set up the Piper TTS Backend (Optional but Recommended) Part 3: Finalize Configuration Configuration Keys Usage in Templates Basic Syntax Language Examples Real-World Examples Related Projects Kardenwort Ecosystem License Project Philosophy
The primary goal of this enhancement is to create a self-sufficient study environment. Whether you are on the go with limited mobile data or wish to disconnect completely for a focused study session, this add-on ensures your audio cards work flawlessly. By leveraging a local TTS engine, it saves bandwidth, works entirely offline, and removes dependency on an active internet connection.
Return to Top
Features 3-Tier Audio Source Priority: Local Audio Dictionary: Plays high-quality, pre-recorded audio from your local collection (e.g., Forvo packs) for the most authentic pronunciation. gTTS (Online): If no local file is found, it uses Google’s high-quality online TTS service. Piper TTS (Offline): If gTTS fails or is disabled, it falls back to a high-quality, local, and fully offline Piper TTS engine. Playback Cycling: On repeated clicks, cycle through different voices: Hear various pronunciations from different authors in your Audio Dictionary. Alternate between gTTS and Piper to compare synthesized voices. Smart Caching & Persistent Storage: Caches all generated audio to avoid repeated network requests (gTTS) or CPU usage (Piper). Files can be stored permanently across Anki sessions. Flexible Configuration: Fine-tune every aspect, from enabling/disabling sources to mapping custom language folders and excluding specific speakers. On-the-Fly Engine Switching: Instantly switch between gTTS and Piper as the primary TTS engine via the Anki Tools menu. Atomic Writes: Prevents corrupted or zero-byte audio files if generation is interrupted.
Return to Top
How It Works
The add-on intercepts Anki’s default TTS requests and processes them with the following priority:
Check Audio Dictionary:
It first searches for a matching .mp3 file in your configured local audio dictionary path. If found, it plays immediately. On subsequent clicks, it can cycle through other available recordings for the same word.
Attempt Primary TTS (or Cycle):
If no local audio is found, it proceeds to TTS. If tts_cycle_enabled is true, it alternates between gTTS and Piper on each click. Otherwise, it uses the default engine set in the config (gTTS or Piper).
Cross-Engine Failover:
If the selected TTS engine fails (e.g., gTTS timeout, Piper script error), it automatically attempts the other engine as a final fallback. Sound will only fail if both your local dictionary is empty for a term and both TTS engines are disabled or failing.
Return to Top
Prerequisites Anki: The Anki desktop application. Python 3: A separate Python 3 installation is required to run the Piper TTS script. Piper TTS Utility: You must have the Piper TTS Command-Line Utility project downloaded and configured. Installation Part 1: Install the Add-on
Choose one of the following methods:
Option A: Install via AnkiWeb (Recommended)
Open Anki. Go to Tools > Add-ons > Get Add-ons… Enter code: 42281744 Click OK.
Option B: Manual Installation (Advanced)
Clone this repository or download the ZIP. Move the extracted folder into your Anki addons21 directory. Part 2: Set up the Piper TTS Backend (Optional but Recommended)
For offline functionality, you must set up the external TTS engine:
Download the Piper TTS Command-Line Utility. Crucial: Follow the setup instructions in that repository (downloading voice models, configuring config.ini, etc.). Note: If this utility is not configured correctly, Piper TTS will not work. Part 3: Finalize Configure: Go to Tools -> Add-ons, select this add-on, and click Config to set up your paths and preferences. Restart: Restart Anki to ensure all modules are loaded correctly. Configuration
Important: Please configure this add-on via the Anki interface: Tools -> Add-ons -> Select this add-on -> Config.
Anki manages user preferences using a separate meta.json file. Manually editing config.json in the file system is not recommended, as your changes may be ignored or overwritten by Anki’s internal settings management.
Immediate Effect: All configuration changes (including paths, timeouts, and cache settings) apply immediately after clicking “OK” in the configuration window. You do not need to restart Anki for these changes to take effect, as the add-on re-reads the configuration before playing each audio file.
The default configuration (in config.json) looks like this:
{ “tts_engine”: “gTTS”, “persistent_cache_enabled”: true, “persistent_cache_path”: "", “audio_dictionary_enabled”: true, “audio_dictionary_path”: “D:/AudioDictionaries”, “audio_dictionary_lang_map”: { “de_DE”: “German”, “en_US”: “English”, “en_GB”: “English” }, “audio_dictionary_exclusions”: [ “BadSpeakerName” ], “audio_dictionary_cycle_enabled”: true, “audio_dictionary_cycle_limit”: 3, “tts_cycle_enabled”: true, “gtts_enabled”: true, “gtts_timeout_sec”: 5, “gtts_cache_enabled”: true, “piper_enabled”: true, “piper_python_path”: “C:/Python/Python312/python.exe”, “piper_script_path”: “D:/apps/piper-tts/piper_tts.py”, “piper_cache_enabled”: true }
Configuration Keys
| Key | Type | Description | | :--- | :--- | :--- | | General Settings | | | | tts_engine | String | The default TTS engine: “gTTS” or “Piper”. Can also be toggled via the Tools menu. | | persistent_cache_enabled| Boolean | (Optional, Default: true) If true, saves TTS files to a permanent folder. If false, uses Anki’s temp folder (deleted on exit). | | persistent_cache_path | String | (Optional, Default: "") A custom path for the cache. If empty, defaults to user_cache inside the add-on folder. | | tts_cycle_enabled | Boolean | (Optional, Default: false) If true, repeated clicks on a TTS field will alternate between gTTS and Piper. | | Audio Dictionary Settings | | | | audio_dictionary_enabled| Boolean | (Optional, Default: false) Master switch to enable or disable the local audio dictionary feature. | | audio_dictionary_path | String | (Optional, Default: "") Required if enabled. Absolute path to the root folder of your audio dictionary (e.g., D:/Forvo). | | audio_dictionary_lang_map| Object | (Optional, Default: {}) Maps Anki language codes to your custom folder names (e.g., “de_DE”: “German”). If omitted, it defaults to two-letter codes (e.g., de, en). | | audio_dictionary_exclusions| Array | (Optional, Default: []) A list of strings. If any string appears in an audio file’s path, it will be skipped. Useful for blacklisting speakers. | | audio_dictionary_cycle_enabled| Boolean | (Optional, Default: false) If true, repeated clicks will cycle through different recordings of the same word. | | audio_dictionary_cycle_limit| Integer | (Optional, Default: 2) The maximum number of recordings to cycle through for a single word. | | gTTS Engine Settings | | | | gtts_enabled | Boolean | (Optional, Default: true) Master switch to enable or disable the gTTS engine entirely. | | gtts_timeout_sec | Integer | (Optional, Default: 5) Seconds to wait for Google’s API before failing over to Piper. | | gtts_cache_enabled | Boolean | (Optional, Default: true) If false, forces a fresh download every time. ⚠️ Warning: Disabling this may lead to a temporary IP ban from Google. | | Piper TTS Engine Settings | | | | piper_enabled | Boolean | (Optional, Default: true) Master switch to enable or disable the Piper TTS engine entirely. | | piper_python_path | String | (Optional, Default: "") Required if enabled. Full path to your Python executable (e.g., C:/Python/python.exe). | | piper_script_path | String | (Optional, Default: "") Required if enabled. Full path to the piper_tts.py script. | | piper_cache_enabled | Boolean | (Optional, Default: true) If false, regenerates audio every time (high CPU usage). |
Return to Top
Usage in Templates
To enable audio on your cards, you need to add the standard Anki TTS tag to your Card Templates (Front or Back).
Basic Syntax
Insert the following code into your template where you want the audio to play:
{{tts en_GB voices=gTTS:Front}}
en_GB: The language code. Change this to match your target language (e.g., en_US, de_DE, ru_RU, uk_UA). voices=gTTS: Important: Do not change this parameter. This add-on specifically intercepts requests made to gTTS to enable the caching and offline fallback features. Front: The name of the field you want to be read aloud. Language Examples
Below are examples of how to configure the tag for different languages, based on common usage patterns:
English (UK): {{tts en_GB voices=gTTS:EnglishWord}} English (US): {{tts en_US voices=gTTS:EnglishWord}} German: {{tts de_DE voices=gTTS:GermanWord}} Russian: {{tts ru_RU voices=gTTS:RussianhWord}} Ukrainian: {{tts uk_UA voices=gTTS:UkrainianhWord}} Real-World Examples
For a comprehensive collection of real-world templates demonstrating proper integration, please refer to the Karden
Screenshots
