avianki 0.6.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

Card examples

Photo → Name — identify the bird from photos and audio:

Description → Name — identify the bird from audio and a redacted description:

Answer — reveals the name, scientific name, photos, audio, and full description:

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	Short	Description
--limit N	-n	Cap the number of species included in the deck
--output FILE	-o	Output .apkg path (default: auto-generated from location)
--deck-name NAME	-d	Override the deck name shown in Anki
--no-audio	-A	Skip downloading call and song audio
--no-images	-I	Skip downloading photos
--delay SECONDS	-D	Wait between requests in seconds (default: 0.5)
--work-dir DIR	-w	Directory for cached media and logs (default: <tmp>/avianki/)
--media-dir DIR	-m	Override media subdirectory (default: <work-dir>/media/)
--ephemeral	-e	Use a temporary work dir and delete everything after packaging
--no-cache	-X	Skip cache lookup; delete downloaded media after packaging
--log-file FILE	-l	Log file path (default: <work-dir>/avianki.log)
--verbose	-v	Show debug-level output in the console
--quiet	-q	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.