totalrecall

README

totalrecall - Bulgarian Anki Flashcard Generator

totalrecall is a versatile tool for generating Anki flashcard materials from Bulgarian words. It offers both a command-line interface (CLI) and a graphical user interface (GUI) for creating audio pronunciation files and AI-generated images.

It has mainly been vibe coded using Claude Code CLI.

⚠️ Important: TotalRecall now uses Google Gemini APIs by default for audio, image generation, translation, and phonetic lookup. Optional OpenAI paths are still available when explicitly selected. See Quick Start for setup instructions.

🔊 Computer / Компютър audio example (Download raw file, and then play locally)

Features

• Audio generation using Google Gemini TTS by default
  • Uses a random Gemini voice by default unless you select a specific one
  • Option to generate in all available voices
  • Defaults to mp3 output and auto-converts Gemini audio with ffmpeg to save space
• Phoenetic pronunciation:
  • Fetches IPA (International Phonetic Alphabet) for each word
  • Uses Gemini by default
• Automatic Bulgarian to English translation
  • Saves translations to separate text files
  • Uses Gemini by default
• Image generation:
  • Google Gemini Nano Banana: Default image path for GUI, CLI, and batch runs
  • OpenAI DALL-E: Optional explicit CLI image generation path
  • Config-driven selection: Set image.provider to openai or nanobanana
  • Scene generation creates memorable contexts for each word
• Batch processing of multiple words
• Anki-compatible export
• Random voice variants and speech speed

Installation

Prerequisites

1. For Gemini defaults (audio, images, translation, phonetics):

   • Create a Google AI Studio API key
   • Set it with export GOOGLE_API_KEY="..."
   • Install ffmpeg if you want the default space-saving mp3 audio output

2. For optional OpenAI paths:

   • Create an account at https://platform.openai.com
   • Generate an API key at https://platform.openai.com/api-keys
   • Set it with export OPENAI_API_KEY="sk-..."

Building from Source

git clone https://github.com/snonux/totalrecall.git
cd totalrecall
go build -o totalrecall ./cmd/totalrecall

Installing to Go Bin Directory

Using Task (recommended):

cd totalrecall
task install

Or using go install directly:

cd totalrecall
go install ./cmd/totalrecall

Or install from remote repository:

go install github.com/snonux/totalrecall/cmd/totalrecall@latest

This will install the binary to ~/go/bin/totalrecall, which should be in your PATH.

Desktop Icon Installation (GNOME/Fedora)

TotalRecall includes a desktop icon for GNOME integration. To install:

For current user only:

cd totalrecall
./assets/install-icon.sh

System-wide installation:

cd totalrecall
sudo ./assets/install-icon.sh

After installation, you may need to log out and log back in for the icon to appear in GNOME's application menu. The icon will show up as "TotalRecall" in the Education category.

Quick Start

Note: By default, totalrecall uses Gemini TTS for audio, Nano Banana for images, and Gemini-backed translation/phonetic lookup. If you want the optional OpenAI paths, set your OpenAI API key too:

export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."

GUI Mode

Launch the interactive graphical interface:

totalrecall                 # GUI mode is now the default

The GUI is best navigated using keyboard shortcuts for efficient workflow. Press h at any time to display a complete list of all available keyboard shortcuts.

Key features:

• Fast keyboard-driven interface
• Real-time audio playback
• Batch processing support
• Visual feedback for all operations

CLI Mode

1. Generate materials for a single word. Explicit CLI image generation uses Nano Banana by default, and you can switch to OpenAI with --image-api openai:

   totalrecall ябълка
   

2. Generate with specific DALL-E model:

   totalrecall ябълка --openai-image-model dall-e-3
   

3. Process multiple words from a file:

   totalrecall --batch words.txt
   

   Example words.txt with translations:

   книга = book
   стол = table
   компютър
   молив = pencil
   

   Have a look further below for more info about the batch file format!

4. Generate with Anki package:

   totalrecall ябълка --anki                                   # Creates APKG file (recommended)
   totalrecall ябълка --anki --anki-csv                        # Creates CSV file (legacy and untested)
   totalrecall ябълка --anki --deck-name "My Bulgarian Words"  # Custom deck name
   

5. Archive existing cards directory:

   totalrecall --archive                        # Archives cards to ~/.local/state/totalrecall/archive/cards-TIMESTAMP
   

Batch file format

Create a text file with Bulgarian words, optionally with English translations or Bulgarian definitions. The tool supports five flexible formats:

Format 1: Bulgarian words only (will be translated to English)

ябълка
котка
куче
хляб
вода

Format 2: Bulgarian words with English translations (single equals =)

книга = book
стол = table
прозорец = window
компютър = computer
молив = pencil

Creates English→Bulgarian flashcards (front: English, back: Bulgarian).

Format 3: English words only (will be translated to Bulgarian)

= apple
= cat
= dog
= bread
= water

Format 4: Bulgarian-Bulgarian (monolingual - double equals ==)

ябълка == плод
котка == домашно животно
куче == млекопитающо

Creates Bulgarian→Bulgarian flashcards (front: Bulgarian word, back: Bulgarian definition). Useful for monolingual learning where both sides are in Bulgarian. Uses double equals (==) to distinguish from the English format.

Format 5: Mixed format (all four types can be combined)

книга = book
котка == домашно животно
= table
куче = dog
вода == течност
молив

When translations are provided, they are used directly without calling the translation API, saving time and API quota. When only English is provided (format starting with =), the tool will automatically translate it to Bulgarian. Spaces around the words and translations are automatically trimmed.

Bulgarian-Bulgarian cards generate two separate audio files (front and back pronunciation).

Configuration

Create an optional ~/config/totalrecall/config.yaml file. You can copy the example file provided:

cp assets/config.yaml.example ~/.config/totalrecall/config.yaml

Output Files

By default, all files are saved to ~/.local/state/totalrecall/. You can override this with the -o flag or the output.directory config option.

For each word, the tool generates:

• word.mp3 - Audio pronunciation (random voice)
• word_translation.txt - English translation
• word_1.jpg, word_2.jpg, etc. - Generated images
• bulgarian_vocabulary.apkg - Anki package file (when using --anki flag)
• anki_import.csv - Anki import file (when using --anki --anki-csv flags)

With --all-voices flag:

• word_alloy.mp3, word_nova.mp3, etc. - Audio in all 11 voices

Anki Import

Method 1: APKG Format (Recommended)

1. Generate materials with the --anki flag
2. In Anki, go to File → Import
3. Select the generated .apkg file
4. All media files are included automatically
5. Cards are ready to use with custom styling

Method 2: CSV Format (Legacy - and untested)

1. Generate materials with --anki --anki-csv flags
2. In Anki, go to File → Import
3. Select the generated anki_import.csv
4. Copy all media files to your Anki media folder
5. Map fields appropriately during import

GUI Export

The GUI mode offers an export dialog where you can:

• Choose between APKG and CSV formats
• Set a custom deck name
• Export all generated cards at once