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:
  1. Local Audio Dictionary: Plays high-quality, pre-recorded audio from your local collection (e.g., Forvo packs) for the most authentic pronunciation.
  2. gTTS (Online): If no local file is found, it uses Google's high-quality online TTS service.
  3. 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:

1. 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.

2. 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).

3. 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

1. Anki: The Anki desktop application.
2. Python 3: A separate Python 3 installation is required to run the Piper TTS script.
3. 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)

1. Open Anki.
2. Go to Tools > Add-ons > Get Add-ons...
3. Enter code: 42281744
4. Click OK.

Option B: Manual Installation (Advanced)

1. Clone this repository or download the ZIP.
2. 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:

1. Download the Piper TTS Command-Line Utility.
2. Crucial: Follow the setup instructions in that repository (downloading voice models, configuring config.ini, etc.).
3. Note: If this utility is not configured correctly, Piper TTS will not work.

Part 3: Finalize

1. Configure: Go to Tools -> Add-ons, select this add-on, and click Config to set up your paths and preferences.
2. 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

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