Skip to main content

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.yaml automatically, making it easy to call from AI agents or shell scripts.

📌 v0.6.0 Highlights

  • Concurrency / Performance: Parallel synthesis with --workers/-w to speed up large sync jobs.
  • Overwrite & Debug: --overwrite replaces existing audio; --debug prints 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 --fields flag (e.g., Word:Audio;Sent:SentAudio).
  • Prosody Control: Fine-tune the listening experience with --rate and --pitch flags, 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 correct xml:lang attribute.
  • Cross-platform playback: azv sample --play uses the system player (afplay on macOS, ffplay elsewhere) 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)

Source distribution for ankiazvox 0.7.0
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)

Table of built distributions (wheels) for ankiazvox 0.7.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page