ankiazvox (azv)
ankiazvox is a professional-grade CLI tool that synchronizes Anki notes with high-quality Azure Neural TTS audio. By leveraging cloud-based Neural voices, it automates text extraction, sanitization, and card updates via AnkiConnect, transforming text-only decks into immersive audio-visual learning tools.
GitHub: github.com/ericxu131/ankiazvox · Marketing site: apps.pisikeji.com/ankiazvox (source in web/).
✨ New in v0.7.0
azv speak: Synthesize any text and play it aloud instantly through your Mac's speaker — no Anki required. Reads credentials from~/azv_config.yamlautomatically, making it easy to call from AI agents or shell scripts.
📌 v0.6.0 Highlights
- Concurrency / Performance: Parallel synthesis with
--workers/-wto speed up large sync jobs. - Overwrite & Debug:
--overwritereplaces existing audio;--debugprints extra diagnostics for troubleshooting.
📌 v0.5.0 Release Highlights
- azv init: An interactive onboarding setup that walks you through connecting your Azure account and setting your preferred default voice.
- Field Mapping: Efficiency-focused syncing that processes multiple fields simultaneously via the
--fieldsflag (e.g.,Word:Audio;Sent:SentAudio). - Prosody Control: Fine-tune the listening experience with
--rateand--pitchflags, allowing you to slow down complex phrases or adjust tone for clarity. - SSML Support: Enhanced processing that preserves natural phrasing by converting
<br>to pauses and providing full support for raw SSML input fields.
🚀 Installation
1. Prerequisites
- Anki Desktop: Must be running with the AnkiConnect add-on installed and configured.
- Azure Speech Service: An active subscription key and region from the Azure portal (Azure offers a generous free tier for speech services).
2. Setup & Configuration
Install the package and run the initializer to create your azv_config.yaml file:
pip install ankiazvox
azv init
🛠 Usage
1. Synchronize Audio (sync)
The sync command generates audio for notes that match a specific Anki search query. It handles the batch processing of voice synthesis and media management automatically.
Basic Single-Field Sync:
Sync text from "Front" and save audio tag to "Audio"
azv sync -q "deck:English::Vocabulary" -s "Front" -t "Audio"
Advanced Multi-Field Sync with Prosody:
Process Word and Sentence fields at 85% speed with a slight pitch increase
azv sync -q "deck:JP::Grammar" -f "Word:WordAud;Sent:SentAud" --rate 0.85 --pitch +5%
| Option | Short | Description |
|---|---|---|
--config |
Path to a config file (yaml or .env). The tool also auto-detects azv_config.yml or .env if present |
|
--query |
-q |
Anki search query (standard Anki search syntax) |
--fields |
-f |
Key-value mapping: source1:target1;source2:target2 |
--source |
-s |
Name of the field containing source text |
--target |
-t |
Name of the field to store the [sound:...] tag |
--rate |
Synthesis speed (1.0 is normal; 0.8 is 80% speed) | |
--pitch |
Pitch adjustment (e.g., +10% or -5%) |
|
--voice |
-v |
Override the default neural voice for this session |
--overwrite |
Replace existing audio in the target field if present | |
--ssml-source |
Treat the source field as raw SSML when it begins with <speak> |
|
--workers |
-w |
Number of concurrent synthesis workers (default: 1) |
--debug |
Enable debug logging for troubleshooting | |
--yes |
-y |
Skip the confirmation prompt and proceed immediately |
2. Speak Aloud (speak)
Synthesize text and play it immediately through your system speaker. Reads credentials from ~/azv_config.yaml by default — works from any directory.
azv speak "Hello, how are you today?"
azv speak "The word ephemeral means lasting a very short time." --voice en-US-AndrewNeural
azv speak "Good morning!" --rate 0.9 --pitch +5%
| Option | Short | Description |
|---|---|---|
--config |
Path to a config file (defaults to ~/azv_config.yaml) |
|
--voice |
-v |
Override the default voice |
--rate |
Speech rate (e.g., 0.8, 1.2) |
|
--pitch |
Pitch adjustment (e.g., +10%, -5%) |
|
--debug |
Enable debug logging |
3. Sample & List Voices
Before running a large sync, it is recommended to sample voices to find the best fit for your language material.
Preview a voice at a slower speed to check clarity
azv sample --voice en-US-AndrewNeural --text "The quick brown fox" --rate 0.8 --play
List all Japanese neural voices to find a specific dialect or tone
azv list-voices --locale ja-JP
📝 Formatting & SSML
- HTML Sanitization: The tool cleans up Anki's internal HTML (like
<div>and<span>) to ensure the TTS engine only reads the text. - Smart Pauses: It preserves line breaks by converting
<br>tags into 400ms SSML pauses, which helps in separating sentences or definitions. - Raw SSML: For advanced users, if a field's content starts with the
<speak>tag, ankiazvox treats it as raw SSML. This allows you to manually insert custom breaks, emphasis, or phoneme corrections directly into your Anki notes.
Additional notes:
- Language detection from voice names: When wrapping text into SSML the tool extracts the language code from typical voice names (e.g.,
en-US-AndrewNeural) so the TTS engine receives the correctxml:langattribute. - Cross-platform playback:
azv sample --playuses the system player (afplayon macOS,ffplayelsewhere) when available. - Temporary files cleaned: Temporary synthesis files are removed after sync to avoid cluttering your project folder.
🤝 Contributing
Contributions are welcome! Whether it's a bug fix, a new feature, or an improvement to the documentation, feel free to open an issue or submit a Pull Request on GitHub.
📄 License
This project is open-source and released under the MIT License.
Metadata
Release files for ankiazvox 0.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ankiazvox-0.7.0.tar.gz | 10.2 kB | Without provenance | Details for ankiazvox-0.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ankiazvox-0.7.0-py3-none-any.whl | Python 3 | none | any | Details for ankiazvox-0.7.0-py3-none-any.whl |
Total release size: 21.5 kB
Release files / ankiazvox-0.7.0.tar.gz
| Download URL | ankiazvox-0.7.0.tar.gz |
|---|---|
| Size | 10.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7e2a61379e604f17fbee0de73050ebaa52f2abf7d0bd93d0c9be4bb357b7ff63
|
|
BLAKE2b-256 checksum How to use checksums |
a7ee7f043f40b42d3213bf29563fba88d1685ca15f9b852ea0a6677d527cf7c9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.2.1 CPython/3.11.13 Darwin/25.5.0
|
Release files / ankiazvox-0.7.0-py3-none-any.whl
| Download URL | ankiazvox-0.7.0-py3-none-any.whl |
|---|---|
| Size | 11.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f37d4de8b1e843118c7253f98454c8ecea48c368f0710dd47a220fa3dd4ccff2
|
|
BLAKE2b-256 checksum How to use checksums |
1342b9ff1d99d73aab38999b80e559acf54b02ceae0672ae78d1a03dea498ed6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.2.1 CPython/3.11.13 Darwin/25.5.0
|
Security for ankiazvox 0.7.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.