avianki 0.5.0

Build Anki flashcard decks for bird identification from allaboutbirds.org

AviAnki

Builds Anki flashcard decks for learning to identify birds by sight and sound. Cards are sourced from allaboutbirds.org and include photos, call/song audio, and species descriptions.

Each species generates two card types:

• Photo → Name — given two photos and audio, identify the bird
• Description → Name — given audio and a written description, identify the bird

Prerequisites

• uv — for running and installing
• ffmpeg — for trimming audio clips

Install ffmpeg:

# Windows
winget install ffmpeg

# macOS
brew install ffmpeg

Usage

From PyPI (recommended):

uvx avianki LOCATION [OPTIONS]

From a local clone:

git clone https://github.com/Ian-Costa18/avianki.git
cd avianki
uv run avianki LOCATION [OPTIONS]

Configuration

Copy .env.example to .env and fill in your key:

EBIRD_API_KEY=your_key_here

An eBird API key is only required if using an eBird region code as the location. Get one free at ebird.org/api/keygen.

Location formats

allaboutbirds.org browse URL (recommended — species sorted by local frequency):

1. Go to allaboutbirds.org/guide/browse
2. Under Birds Near Me, enter your city, ZIP code, or state/province
3. Set the time of year — Year-round is recommended for a complete deck
4. Click Browse, then copy the URL from your browser's address bar

uvx avianki "https://www.allaboutbirds.org/guide/browse/filter/loc/ChIJGzE9DS1l44kRoOhiASS_fHg/date/all/behavior/all/size/all/colors/all/sort/score/view/list-view"

Google Place ID (shorthand for the above):

uvx avianki ChIJGzE9DS1l44kRoOhiASS_fHg

Find a Place ID at developers.google.com/maps/documentation/javascript/examples/places-placeid-finder.

eBird region code (species in taxonomic order, requires API key):

uvx avianki US-MA
uvx avianki US-MA-017   # county level

Options

Flag	Description
--limit N	Cap the number of species included in the deck
--output FILE	Output .apkg path (default: auto-generated from location)
--deck-name NAME	Override the deck name shown in Anki
--no-audio	Skip downloading call and song audio
--no-images	Skip downloading photos
--delay SECONDS	Wait between requests in seconds (default: 0.5)
--media-dir DIR	Directory for cached media files (default: <tmp>/avianki/media/)
--clear-cache	Delete previously downloaded media before running
--no-cache	Skip cache lookup; delete downloaded media after packaging
--log-file FILE	Log file path (default: <tmp>/avianki/avianki.log)
--verbose	Show debug-level output in the console
--quiet	Only show warnings and errors in the console

Examples

# Build a deck for your area (recommended approach)
uvx avianki "https://www.allaboutbirds.org/guide/browse/..." --limit 50

# Re-download all media from scratch
uvx avianki US-MA --clear-cache

# Quick test with 5 species
uvx avianki US-MA --limit 5

# Custom output path and deck name
uvx avianki US-MA --output ~/Desktop/MyBirds.apkg --deck-name "My Birds"

# Images only, no audio
uvx avianki US-MA --no-audio

# Be polite to the server
uvx avianki US-MA --delay 1.5

Output

An .apkg file is written to the current directory (e.g. Birds_US-MA.apkg). Import it into Anki via File -> Import.

Downloaded images and audio are cached in the system temp directory (<tmp>/avianki/media/ by default, or the directory set by --media-dir) so re-runs skip already-fetched files. The log is written to <tmp>/avianki/avianki.log.

Notes

• Audio clips are trimmed to 10 seconds via ffmpeg to keep file sizes small.
• allaboutbirds.org browse URLs sort species by likelihood score for your location, which gives much better study order than eBird's taxonomic ordering.