https://github.com/osteele/add2anki
A CLI tool to add language learning cards to Anki, with automatic translation and audio generation
https://github.com/osteele/add2anki
anki anki-card-generation cli education language-learning mandarin-chinese
Last synced: 8 months ago
JSON representation
A CLI tool to add language learning cards to Anki, with automatic translation and audio generation
- Host: GitHub
- URL: https://github.com/osteele/add2anki
- Owner: osteele
- License: mit
- Created: 2025-03-15T17:21:10.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-17T03:22:35.000Z (about 1 year ago)
- Last Synced: 2025-06-22T00:14:57.978Z (about 1 year ago)
- Topics: anki, anki-card-generation, cli, education, language-learning, mandarin-chinese
- Language: Python
- Homepage: https://osteele.github.io/add2anki/
- Size: 259 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# add2anki — add language study cards to Anki
[](https://pypi.org/project/add2anki/)
[](https://pypi.org/project/add2anki/)
[](https://github.com/osteele/add2anki/blob/main/LICENSE)
[](https://github.com/astral-sh/ruff)
[](https://github.com/osteele/add2anki/actions/workflows/ci.yml)
A CLI tool to add language learning cards to Anki, with automatic translation and audio generation.
Currently supports English to Mandarin Chinese translation with audio generation using two providers:
- Google Translate TTS (default, no authentication required)
- ElevenLabs (requires API key)
For related language learning resources, visit [Oliver Steele's Language
Learning Resources](https://osteele.com/topics/language-learning/).
## Features
- 🔄 Translate English text to Mandarin Chinese using OpenAI's GPT models
- 🗣️ Support for different translation styles:
- `conversational` (default): Natural, everyday language
- `formal`: More polite expressions appropriate for business or formal situations
- `written`: Literary style suitable for written texts
- 🔊 Generate high-quality audio for Chinese text using one of two providers:
- Google Translate TTS (default, no authentication required)
- ElevenLabs (requires API key)
- 🃏 Add cards to Anki with translation and audio
- 🏷️ Add custom tags to notes or use the default "add2anki" tag
- 🧠 Context-aware language detection that automatically identifies languages
- 🔍 Automatic detection of suitable note types and field mappings
- 🔧 Support for custom note types with field name synonyms (Hanzi/Chinese, Pinyin/Pronunciation, English/Translation)
- 💾 Configuration saved between sessions
- 📚 Support for batch processing from text, CSV/TSV, or SRT subtitle files
- 🎬 Parse SRT files to create cards from Mandarin subtitles
- 🤔 Interactive mode for adding cards one by one
## Prerequisites
- Python 3.11 or higher
- [Anki](https://apps.ankiweb.net/) with the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) plugin installed
- OpenAI API key
- For audio generation (optional, as Google Translate is used by default):
- ElevenLabs API key (for ElevenLabs)
## Installation
You can install add2anki using either `uv`, or `pipx`, or `pip`:
### Using uv
1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/) if you don't have it already.
2. Install `add2anki`:
```bash
uv tool install add2anki
```
### Using pipx
1. [Install `pipx`](https://pipx.pypa.io/stable/installation/) if you don't have it already.
2. Install add2anki
```bash
pipx install add2anki
```
### Using pip (not recommended)
This method doesn't require a third-party tool, but it is not recommended as it will install add2anki in the current Python environment, which may cause conflicts with other packages.
```bash
pip install add2anki
```
## Environment Variables
Set the following environment variables:
```bash
# Required for translation
export OPENAI_API_KEY=your_openai_api_key
# Required only if using ElevenLabs
export ELEVENLABS_API_KEY=your_elevenlabs_api_key
```
## Quick Start
```bash
# Basic usage (uses Google Translate TTS by default)
add2anki "Hello, how are you?"
# Start interactive mode
add2anki
```
## Documentation
- [Command Line Reference](docs/command-line.md) - Detailed usage and options
- [Development Guide](DEVELOPMENT.md) - Information for contributors
## Note Type and Deck Selection
add2anki will automatically detect suitable note types in your Anki collection. A suitable note type must have fields that match:
- Hanzi/Chinese/Characters for the Chinese characters
- Pinyin/Pronunciation/Reading for the pronunciation
- English/Translation/Meaning for the English translation
If multiple suitable note types are found, you'll be prompted to select one.
Similarly, if no deck is specified via the `--deck` option and no previously selected deck is found in the configuration, add2anki will display a list of available decks and prompt you to select one.
Your selections for both note type and deck will be saved for future use.
## Configuration
add2anki saves your preferences (deck name, note type, field mappings) in a configuration file:
- On Windows: `%APPDATA%\add2anki\config.json`
- On macOS/Linux: `~/.config/add2anki/config.json`
## Acknowledgements
This project relies on several excellent libraries:
- [click](https://github.com/pallets/click) for building the command-line interface
- [rich](https://github.com/Textualize/rich) for beautiful text formatting
- [pydantic](https://github.com/samuelcolvin/pydantic) for robust data validation
- [requests](https://github.com/psf/requests) for making HTTP requests
Services:
- [openai](https://github.com/openai/openai-python) for transcription and translation
- [elevenlabs](https://github.com/elevenlabs/elevenlabs-python) for audio generation
## Related Projects
- [audio2anki](https://github.com/osteele/audio2anki) - Tool to extract foreign language vocabulary from audio transcriptions and add to Anki
- [contextual-langdetect](https://github.com/osteele/contextual-langdetect) - Context-aware language detection for multilingual text
## License
MIT
## Author
Oliver Steele (@osteele)