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/).
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.
- Concurrency / Performance: Parallel synthesis with
--workers/-wto speed up large sync jobs. - Overwrite & Debug:
--overwritereplaces existing audio;--debugprints extra diagnostics for troubleshooting.
- 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.
- 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).
Install the package and run the initializer to create your azv_config.yaml file:
pip install ankiazvox
azv init
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 |
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 |
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
- 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.
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.
This project is open-source and released under the MIT License.