Anki add-on: Audio Dictionary and TTS Player with Fallback and Smart Caching for Anki

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 Kardenwort Anki Templates project. Kardenwort Anki Templates This project provides extensive examples of how to structure cards and tag fields for various languages within a production-ready environment. Return to Top Related Projects Piper TTS Command-Line Utility : The local TTS engine that this add-on depends on for its offline functionality. No TTS Player for Anki : A companion add-on to temporarily or permanently silence all TTS fields ( {{tts...}} ) without needing to edit card templates. Return to Top Kardenwort Ecosystem This project is part of the Kardenwort environment, designed to create a focused and efficient learning ecosystem. Return to Top License GNU AGPL v3 Return to Top

GitHub repository: voothi/20250421115831-anki-gtts-player
Repository description: 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
Languages: Python, Shell
Topics: 20231001193911-tts, 20241206010110-piper-tts, 20250421115831-anki-gtts-player, anki, anki-addon, anki-addons, anki-audio, audio-dictionary, caching, gtts, gtts-api, kardenwort, language-learning, offline, offline-tts, piper-tts, python, text-to-speech, tts