Anki Search Utility

A command-line utility to interact with Anki via the AnkiConnect add-on.

This script provides two main functionalities for interacting with your Anki collection from the command line:

• Advanced Card Search: Perform complex searches for cards and print the results directly to your console in either plain text or HTML format.

• Paragraph/Range Reading: Automatically detects and retrieves full paragraphs spanning multiple sequential Anki cards in a single operation, eliminating the need for sentence-by-sentence lookups.

• Deck Filtering: Limit search results to a specific deck or hierarchy (e.g., a specific book or chapter) using config.ini. This ensures results are relevant to your current study material and prevents checking the entire database.

• Direct Browser Integration: Instantly open the Anki Card Browser with a specific search query, either provided as an argument or taken directly from your system clipboard.

• GoldenDict Integration: Designed to work seamlessly with GoldenDict via an accompanying AutoHotkey script, allowing you to look up selected words in Anki with a single hotkey.

Table of Contents

• Anki Search Utility
  • Table of Contents
  • Usage
  • Prerequisites
  • Installation
  • Integration with GoldenDict (via AutoHotkey)
    • Configuration
    • How to Use
  • How It Works
  • Kardenwort Ecosystem
  • License

Usage

The script is controlled via command-line arguments.

Back to Top

Prerequisites

1. Anki: The script requires the Anki desktop application to be running.
2. AnkiConnect Add-on: You must have the AnkiConnect add-on installed in Anki.
3. Python 3: Python 3 must be installed on your system.

Installation

1. Clone this repository:

   git clone https://github.com/voothi/20240408222910-goldendict-anki-search.git

2. Navigate to the repository folder:

   cd 20240408222910-goldendict-anki-search

3. Install the required Python libraries:

   pip install requests pyperclip

4. Make sure Anki is running in the background with the AnkiConnect add-on enabled.
5. Run the script from your terminal to test it.

Example Commands:

# Search for the word "example" and print results as plain text
./anki-search.py --query "example"

# Search for "hello" filtering for English cards (expands to en-gb, en-us, etc.)
./anki-search.py --query "with" --languages en
./anki-search.py --query "mit" --languages de

# Performance-optimized searches
./anki-search.py --query "test" --only-ids
./anki-search.py --query "optimized" --optimized

# Search for a sentence and print results in HTML format
./anki-search.py --query "this is a test sentence" --search-type sentence --html

# Search for a whole paragraph (automatically detects range across cards)
./anki-search.py --query-file my_paragraph.txt --html

./anki-search.py --browse-query "deck:French is:due"

# Open the Anki browser with a query taken from the clipboard (used for integration)
./anki-search.py --browse-clipboard

Back to Top

Integration with GoldenDict (via AutoHotkey)

This script is most powerful when combined with the accompanying AutoHotkey (AHK) script to look up words from GoldenDict in Anki instantly.

Configuration

1. Download or clone the AutoHotkey script repository.
2. Open the open-in-anki.ahk file in a text editor.
3. You must update the paths at the top of the script to match your system's configuration:

   ; --- User Configuration ---
   ; You must update these paths to match your system's configuration.
   pythonPath := "C:\Path\To\Your\Python\python.exe"
   scriptPath := "C:\Path\To\Your\anki-search.py"

4. Save the open-in-anki.ahk file and run it by double-clicking. It will run in the background.

How to Use

Once the AHK script is configured and running, you have two ways to search from GoldenDict:

1. Hotkey Method:

   • In GoldenDict, select any word or phrase.
   • Press Ctrl+Alt+A.
   • The Anki Card Browser will open and execute a search for the selected text.

2. GoldenDict Program Method:

   • In GoldenDict, go to Edit -> Dictionaries -> Programs tab.
   • Click Add.
   • Set the Type to Audio.
   • In the Command Line field, enter the full path to the AHK script followed by the /trigger argument. Use %GDWORD% to pass the search term.

     "C:\Path\To\Your\open-in-anki.ahk" /trigger
     

   • Now, when you look up a word in GoldenDict, a new "play" icon will appear. Clicking it will trigger the search in Anki.

Back to Top

How It Works

• AnkiConnect API: The script communicates with a running Anki instance through the AnkiConnect add-on, which exposes an API at http://localhost:8765. All actions, like finding cards or opening the browser, are sent as JSON-RPC requests.
• Search Logic: When using the --query argument, the script constructs a specific search query tailored to find terms in WordSource, WordSourceInflectedForm, or SentenceSource fields. This logic is hardcoded in the search_word_in_decks function and can be modified to fit different note types.
• Multi-Sentence Logic: For long queries, the script extracts "Start" and "End" anchors. It identifies a range of cards in Anki, reconstructs the text, and verifies it against the original query using robust normalization (ignoring whitespace/case/punctuation).
• Clipboard Bridge: The --browse-clipboard argument acts as a bridge for other applications. The AutoHotkey script copies the selected text to the clipboard and then calls this Python script with that argument, which in turn tells Anki to search for the clipboard's content.
• Configuration (config.ini): Settings for anchor detection, boundary punctuation, and deck filtering can be customized in the local config.ini file.

Back 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

MIT

Back to Top