{"id":26358778,"url":"https://github.com/osteele/add2anki","last_synced_at":"2025-10-27T00:17:39.369Z","repository":{"id":282631321,"uuid":"949102023","full_name":"osteele/add2anki","owner":"osteele","description":"A CLI tool to add language learning cards to Anki, with automatic translation and audio generation","archived":false,"fork":false,"pushed_at":"2025-04-17T03:22:35.000Z","size":265,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-22T00:14:57.978Z","etag":null,"topics":["anki","anki-card-generation","cli","education","language-learning","mandarin-chinese"],"latest_commit_sha":null,"homepage":"https://osteele.github.io/add2anki/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/osteele.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-15T17:21:10.000Z","updated_at":"2025-05-18T20:47:42.000Z","dependencies_parsed_at":"2025-03-15T22:56:17.689Z","dependency_job_id":"da28f364-790c-4818-8e55-6d8ebabb4a11","html_url":"https://github.com/osteele/add2anki","commit_stats":null,"previous_names":["osteele/add2anki"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/osteele/add2anki","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fadd2anki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fadd2anki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fadd2anki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fadd2anki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osteele","download_url":"https://codeload.github.com/osteele/add2anki/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osteele%2Fadd2anki/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261380141,"owners_count":23149930,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anki","anki-card-generation","cli","education","language-learning","mandarin-chinese"],"created_at":"2025-03-16T15:28:00.481Z","updated_at":"2025-10-27T00:17:39.365Z","avatar_url":"https://github.com/osteele.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# add2anki — add language study cards to Anki\n\n[![PyPI version](https://img.shields.io/pypi/v/add2anki.svg)](https://pypi.org/project/add2anki/)\n[![Python Version](https://img.shields.io/pypi/pyversions/add2anki.svg)](https://pypi.org/project/add2anki/)\n[![License](https://img.shields.io/github/license/osteele/add2anki.svg)](https://github.com/osteele/add2anki/blob/main/LICENSE)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![CI](https://github.com/osteele/add2anki/actions/workflows/ci.yml/badge.svg)](https://github.com/osteele/add2anki/actions/workflows/ci.yml)\n\nA CLI tool to add language learning cards to Anki, with automatic translation and audio generation.\n\nCurrently supports English to Mandarin Chinese translation with audio generation using two providers:\n- Google Translate TTS (default, no authentication required)\n- ElevenLabs (requires API key)\n\nFor related language learning resources, visit [Oliver Steele's Language\nLearning Resources](https://osteele.com/topics/language-learning/).\n\n## Features\n\n- 🔄 Translate English text to Mandarin Chinese using OpenAI's GPT models\n- 🗣️ Support for different translation styles:\n  - `conversational` (default): Natural, everyday language\n  - `formal`: More polite expressions appropriate for business or formal situations\n  - `written`: Literary style suitable for written texts\n- 🔊 Generate high-quality audio for Chinese text using one of two providers:\n  - Google Translate TTS (default, no authentication required)\n  - ElevenLabs (requires API key)\n- 🃏 Add cards to Anki with translation and audio\n- 🏷️ Add custom tags to notes or use the default \"add2anki\" tag\n- 🧠 Context-aware language detection that automatically identifies languages\n- 🔍 Automatic detection of suitable note types and field mappings\n- 🔧 Support for custom note types with field name synonyms (Hanzi/Chinese, Pinyin/Pronunciation, English/Translation)\n- 💾 Configuration saved between sessions\n- 📚 Support for batch processing from text, CSV/TSV, or SRT subtitle files\n- 🎬 Parse SRT files to create cards from Mandarin subtitles\n- 🤔 Interactive mode for adding cards one by one\n\n## Prerequisites\n\n- Python 3.11 or higher\n- [Anki](https://apps.ankiweb.net/) with the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) plugin installed\n- OpenAI API key\n- For audio generation (optional, as Google Translate is used by default):\n  - ElevenLabs API key (for ElevenLabs)\n\n## Installation\n\nYou can install add2anki using either `uv`, or `pipx`, or `pip`:\n\n### Using uv\n\n1. [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/) if you don't have it already.\n\n2. Install `add2anki`:\n  ```bash\n  uv tool install add2anki\n  ```\n\n### Using pipx\n\n1. [Install `pipx`](https://pipx.pypa.io/stable/installation/) if you don't have it already.\n\n2. Install add2anki\n  ```bash\n  pipx install add2anki\n  ```\n\n### Using pip (not recommended)\n\nThis 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.\n\n```bash\npip install add2anki\n```\n\n## Environment Variables\n\nSet the following environment variables:\n\n```bash\n# Required for translation\nexport OPENAI_API_KEY=your_openai_api_key\n\n# Required only if using ElevenLabs\nexport ELEVENLABS_API_KEY=your_elevenlabs_api_key\n```\n\n## Quick Start\n\n```bash\n# Basic usage (uses Google Translate TTS by default)\nadd2anki \"Hello, how are you?\"\n\n# Start interactive mode\nadd2anki\n```\n\n## Documentation\n\n- [Command Line Reference](docs/command-line.md) - Detailed usage and options\n- [Development Guide](DEVELOPMENT.md) - Information for contributors\n\n## Note Type and Deck Selection\n\nadd2anki will automatically detect suitable note types in your Anki collection. A suitable note type must have fields that match:\n\n- Hanzi/Chinese/Characters for the Chinese characters\n- Pinyin/Pronunciation/Reading for the pronunciation\n- English/Translation/Meaning for the English translation\n\nIf multiple suitable note types are found, you'll be prompted to select one.\n\nSimilarly, 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.\n\nYour selections for both note type and deck will be saved for future use.\n\n## Configuration\n\nadd2anki saves your preferences (deck name, note type, field mappings) in a configuration file:\n\n- On Windows: `%APPDATA%\\add2anki\\config.json`\n- On macOS/Linux: `~/.config/add2anki/config.json`\n\n## Acknowledgements\n\nThis project relies on several excellent libraries:\n\n- [click](https://github.com/pallets/click) for building the command-line interface\n- [rich](https://github.com/Textualize/rich) for beautiful text formatting\n- [pydantic](https://github.com/samuelcolvin/pydantic) for robust data validation\n- [requests](https://github.com/psf/requests) for making HTTP requests\n\nServices:\n\n- [openai](https://github.com/openai/openai-python) for transcription and translation\n- [elevenlabs](https://github.com/elevenlabs/elevenlabs-python) for audio generation\n\n## Related Projects\n\n- [audio2anki](https://github.com/osteele/audio2anki) - Tool to extract foreign language vocabulary from audio transcriptions and add to Anki\n- [contextual-langdetect](https://github.com/osteele/contextual-langdetect) - Context-aware language detection for multilingual text\n\n## License\n\nMIT\n\n## Author\n\nOliver Steele (@osteele)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosteele%2Fadd2anki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosteele%2Fadd2anki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosteele%2Fadd2anki/lists"}