avianki 0.1.1__tar.gz

avianki-0.1.1/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.3
+Name: avianki
+Version: 0.1.1
+Summary: Build Anki flashcard decks for bird identification from allaboutbirds.org
+Keywords: anki,birds,flashcards,ornithology
+Author: Ian Costa
+License: MIT
+Requires-Dist: genanki>=0.13.1
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/Ian-Costa18/avianki
+Project-URL: Issues, https://github.com/Ian-Costa18/avianki/issues
+Description-Content-Type: text/markdown
+
+# avianki
+
+Builds Anki flashcard decks for learning to identify birds by sight and sound. Cards are sourced from [allaboutbirds.org](https://www.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
+
+- **Python 3.10+**
+- **[uv](https://docs.astral.sh/uv/)** — for dependency management
+- **[ffmpeg](https://ffmpeg.org/)** — for trimming audio clips
+
+Install ffmpeg:
+
+```bash
+# Windows
+winget install ffmpeg
+
+# macOS
+brew install ffmpeg
+```
+
+## Installation
+
+```bash
+git clone https://github.com/Ian-Costa18/avianki.git
+cd avianki
+uv sync
+```
+
+## Configuration
+
+Copy `.env.example` to `.env` and fill in your key:
+
+```env
+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](https://ebird.org/api/keygen).
+
+## Usage
+
+```bash
+uv run avianki.py LOCATION [OPTIONS]
+```
+
+### Location formats
+
+**allaboutbirds.org browse URL** (recommended — species sorted by local frequency):
+
+1. Go to [allaboutbirds.org/guide/browse](https://www.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
+
+```bash
+uv run avianki.py "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):
+
+```bash
+uv run avianki.py ChIJGzE9DS1l44kRoOhiASS_fHg
+```
+
+Find a Place ID at [developers.google.com/maps/documentation/javascript/examples/places-placeid-finder](https://developers.google.com/maps/documentation/javascript/examples/places-placeid-finder).
+
+**eBird region code** (species in taxonomic order, requires API key):
+
+```bash
+uv run avianki.py US-MA
+uv run avianki.py US-MA-017   # county level
+```
+
+### Options
+
+| Flag                  | Description                                                    |
+| --------------------- | -------------------------------------------------------------- |
+| `--limit N`           | Cap the number of species (useful for testing)                 |
+| `--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`)              |
+| `--clear-cache`       | Delete previously downloaded media before running              |
+| `--log-file FILE`     | Log file path (default: `avianki.log`)                         |
+| `--verbose`           | Show debug-level output in the console                         |
+| `--quiet`             | Only show warnings and errors in the console                   |
+
+### Examples
+
+```bash
+# Build a deck for your area (recommended approach)
+uv run avianki.py "https://www.allaboutbirds.org/guide/browse/..." --limit 50
+
+# Re-download all media from scratch
+uv run avianki.py US-MA --clear-cache
+
+# Quick test with 5 species
+uv run avianki.py US-MA --limit 5
+
+# Custom output path and deck name
+uv run avianki.py US-MA --output ~/Desktop/MyBirds.apkg --deck-name "My Birds"
+
+# Images only, no audio
+uv run avianki.py US-MA --no-audio
+
+# Be polite to the server
+uv run avianki.py 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 `media/` so re-runs skip already-fetched files.
+
+## 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.

avianki-0.1.1/README.md

@@ -0,0 +1,124 @@
+# avianki
+
+Builds Anki flashcard decks for learning to identify birds by sight and sound. Cards are sourced from [allaboutbirds.org](https://www.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
+
+- **Python 3.10+**
+- **[uv](https://docs.astral.sh/uv/)** — for dependency management
+- **[ffmpeg](https://ffmpeg.org/)** — for trimming audio clips
+
+Install ffmpeg:
+
+```bash
+# Windows
+winget install ffmpeg
+
+# macOS
+brew install ffmpeg
+```
+
+## Installation
+
+```bash
+git clone https://github.com/Ian-Costa18/avianki.git
+cd avianki
+uv sync
+```
+
+## Configuration
+
+Copy `.env.example` to `.env` and fill in your key:
+
+```env
+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](https://ebird.org/api/keygen).
+
+## Usage
+
+```bash
+uv run avianki.py LOCATION [OPTIONS]
+```
+
+### Location formats
+
+**allaboutbirds.org browse URL** (recommended — species sorted by local frequency):
+
+1. Go to [allaboutbirds.org/guide/browse](https://www.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
+
+```bash
+uv run avianki.py "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):
+
+```bash
+uv run avianki.py ChIJGzE9DS1l44kRoOhiASS_fHg
+```
+
+Find a Place ID at [developers.google.com/maps/documentation/javascript/examples/places-placeid-finder](https://developers.google.com/maps/documentation/javascript/examples/places-placeid-finder).
+
+**eBird region code** (species in taxonomic order, requires API key):
+
+```bash
+uv run avianki.py US-MA
+uv run avianki.py US-MA-017   # county level
+```
+
+### Options
+
+| Flag                  | Description                                                    |
+| --------------------- | -------------------------------------------------------------- |
+| `--limit N`           | Cap the number of species (useful for testing)                 |
+| `--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`)              |
+| `--clear-cache`       | Delete previously downloaded media before running              |
+| `--log-file FILE`     | Log file path (default: `avianki.log`)                         |
+| `--verbose`           | Show debug-level output in the console                         |
+| `--quiet`             | Only show warnings and errors in the console                   |
+
+### Examples
+
+```bash
+# Build a deck for your area (recommended approach)
+uv run avianki.py "https://www.allaboutbirds.org/guide/browse/..." --limit 50
+
+# Re-download all media from scratch
+uv run avianki.py US-MA --clear-cache
+
+# Quick test with 5 species
+uv run avianki.py US-MA --limit 5
+
+# Custom output path and deck name
+uv run avianki.py US-MA --output ~/Desktop/MyBirds.apkg --deck-name "My Birds"
+
+# Images only, no audio
+uv run avianki.py US-MA --no-audio
+
+# Be polite to the server
+uv run avianki.py 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 `media/` so re-runs skip already-fetched files.
+
+## 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.

avianki-0.1.1/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "avianki"
+version = "0.1.1"
+description = "Build Anki flashcard decks for bird identification from allaboutbirds.org"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "Ian Costa" },
+]
+license = { text = "MIT" }
+keywords = ["anki", "birds", "flashcards", "ornithology"]
+dependencies = [
+    "genanki>=0.13.1",
+    "python-dotenv>=1.0.0",
+    "requests>=2.28.0",
+]
+
+[project.scripts]
+avianki = "avianki.cli:main"
+
+[project.urls]
+Repository = "https://github.com/Ian-Costa18/avianki"
+Issues = "https://github.com/Ian-Costa18/avianki/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.11",
+    "ty>=0.0.31",
+]

avianki-0.1.1/src/avianki/allaboutbirds.py

@@ -0,0 +1,143 @@
+"""Scrape species data from allaboutbirds.org.
+
+fetch_browse_species() accepts either a full browse URL or a Google Place ID:
+    https://www.allaboutbirds.org/guide/browse/filter/loc/{placeId}/
+        date/all/behavior/all/size/all/colors/all/sort/score/view/list-view
+"""
+
+import html
+import logging
+import re
+
+import requests
+
+log = logging.getLogger("bird_deck")
+
+AAB_BASE = "https://www.allaboutbirds.org/guide"
+HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"
+    ),
+    "Accept-Language": "en-US,en;q=0.9",
+}
+
+
+def fetch_browse_species(url_or_place_id: str, limit: int | None = None) -> list[str]:
+    """
+    Scrape an allaboutbirds.org browse page and return species slugs in
+    likelihood-score order (most commonly seen first).
+
+    Accepts either the full browse URL or just the Google Place ID.
+    """
+    if url_or_place_id.startswith("http"):
+        url = url_or_place_id
+    else:
+        place_id = url_or_place_id
+        url = (
+            f"{AAB_BASE}/browse/filter/loc/{place_id}"
+            "/date/all/behavior/all/size/all/colors/all/sort/score/view/list-view"
+        )
+
+    log.info("Fetching species list from allaboutbirds.org…")
+    log.debug("Browse URL: %s", url)
+    try:
+        resp = requests.get(url, headers=HEADERS, timeout=20)
+        resp.raise_for_status()
+        slugs = list(dict.fromkeys(
+            re.findall(r"/guide/([A-Za-z][A-Za-z_\-]+)/overview", resp.text)
+        ))
+        if limit:
+            slugs = slugs[:limit]
+        log.info("  %d species found (sorted by likelihood)", len(slugs))
+        return slugs
+    except Exception as e:
+        log.error("Browse fetch failed: %s", e)
+        return []
+
+
+def slug_to_names(slug: str) -> dict:
+    """
+    Return {comName, sciName} by scraping the overview page title/meta.
+    Used when building from an allaboutbirds URL (no eBird lookup needed).
+    """
+    try:
+        resp = requests.get(f"{AAB_BASE}/{slug}/overview", headers=HEADERS, timeout=15)
+        resp.raise_for_status()
+        html_text = resp.text
+        # <title>Black-capped Chickadee Overview, All About Birds…</title>
+        m_title = re.search(r"<title>([^<]+) Overview,", html_text)
+        com_name = m_title.group(1).strip() if m_title else slug.replace("_", " ")
+        # Scientific name appears in a consistent italics span
+        m_sci = re.search(r'<em class="sci-name">([^<]+)</em>', html_text)
+        if not m_sci:
+            m_sci = re.search(r'<i[^>]*itemprop="name"[^>]*>([^<]+)</i>', html_text)
+        sci_name = m_sci.group(1).strip() if m_sci else ""
+        return {"comName": com_name, "sciName": sci_name}
+    except Exception as e:
+        log.warning("slug_to_names failed (%s): %s", slug, e)
+        return {"comName": slug.replace("_", " "), "sciName": ""}
+
+
+def species_slug(com_name: str) -> str:
+    """'Black-capped Chickadee' → 'Black-capped_Chickadee'"""
+    return com_name.replace(" ", "_")
+
+
+def fetch_overview(slug: str) -> dict:
+    """
+    Scrape the overview page for a species.
+    Returns {desc, sciName, images} — images are up to 2 720px JPG URLs.
+    """
+    url = f"{AAB_BASE}/{slug}/overview"
+    log.debug("AAB overview: %s", url)
+    try:
+        resp = requests.get(url, headers=HEADERS, timeout=15)
+        resp.raise_for_status()
+        html_text = resp.text
+
+        m = re.search(r'<meta name="description" content="([^"]+)"', html_text)
+        desc = html.unescape(m.group(1)).strip() if m else ""
+        desc = re.sub(r"^<p>|</p>$", "", desc).strip()
+
+        m_sci = re.search(r'<em class="sci-name">([^<]+)</em>', html_text)
+        if not m_sci:
+            m_sci = re.search(r'<i[^>]*itemprop="name"[^>]*>([^<]+)</i>', html_text)
+        sci_name = m_sci.group(1).strip() if m_sci else ""
+
+        photo_ids = list(dict.fromkeys(
+            re.findall(r'/guide/assets/photo/(\d+)-\d+px\.jpg', html_text)
+        ))
+        images = [f"{AAB_BASE}/assets/photo/{pid}-720px.jpg" for pid in photo_ids[:2]]
+
+        return {"desc": desc, "sciName": sci_name, "images": images}
+    except Exception as e:
+        log.warning("AAB overview failed (%s): %s", slug, e)
+        return {"desc": "", "images": []}
+
+
+def fetch_sounds(slug: str) -> dict:
+    """
+    Scrape the sounds page for a species.
+    Returns {calls: [url, …], songs: [url, …]} — direct MP3 URLs from allaboutbirds.
+    """
+    url = f"{AAB_BASE}/{slug}/sounds"
+    log.debug("AAB sounds: %s", url)
+    try:
+        resp = requests.get(url, headers=HEADERS, timeout=15)
+        resp.raise_for_status()
+        html_text = resp.text
+
+        # Each entry: jp-jplayer name="URL" ... jp-flat-audio aria-label="Song|Calls|..."
+        entries = re.findall(
+            r'name="(https://www\.allaboutbirds\.org/guide/assets/sound/\d+\.mp3)"'
+            r'.*?aria-label="([^"]+)"',
+            html_text,
+            re.DOTALL,
+        )
+        calls = [u for u, label in entries if "Call" in label]
+        songs = [u for u, label in entries if "Song" in label]
+        return {"calls": calls, "songs": songs}
+    except Exception as e:
+        log.warning("AAB sounds failed (%s): %s", slug, e)
+        return {"calls": [], "songs": []}

avianki-0.1.1/src/avianki/anki_model.py

@@ -0,0 +1,105 @@
+"""Anki model definition for bird ID cards."""
+
+import hashlib
+
+import genanki
+
+CSS = """
+.card {
+  font-family: Georgia, serif;
+  font-size: 16px;
+  color: #1a1a1a;
+  background-color: #fafaf7;
+  max-width: 600px;
+  margin: 0 auto;
+  padding: 16px;
+  line-height: 1.5;
+}
+.bird-name { font-size: 1.6em; font-weight: bold; color: #2c5f2e; margin: 12px 0 4px 0; }
+.sci-name  { font-style: italic; color: #666; font-size: 0.9em; margin-bottom: 14px; }
+.card img  {
+  max-width: 48%;
+  max-height: 200px;
+  object-fit: contain;
+  display: inline-block;
+  margin: 4px 1%;
+  border-radius: 8px;
+  vertical-align: top;
+}
+.desc-box {
+  background: #f0f4f0;
+  border-left: 4px solid #2c5f2e;
+  padding: 10px 14px;
+  border-radius: 0 6px 6px 0;
+  margin: 10px 0;
+  font-size: 0.95em;
+}
+.prompt-label {
+  font-size: 0.85em; font-weight: bold; color: #888;
+  text-transform: uppercase; letter-spacing: 0.08em; margin-bottom: 4px;
+}
+.divider { border-top: 1px solid #ddd; margin: 14px 0; }
+audio { width: 100%; margin: 4px 0; }
+"""
+
+# Fields shared by both card templates
+FIELDS = [
+    {"name": "BirdName"},
+    {"name": "SciName"},
+    {"name": "Image1"},    # <img src="..."> or ""
+    {"name": "Image2"},    # <img src="..."> or ""
+    {"name": "Call"},      # [sound:...] or ""
+    {"name": "Song"},      # [sound:...] or ""
+    {"name": "Description"},
+]
+
+# Shared answer side: name + both images + audio + description
+_BACK = """
+<div class="card">
+  <div class="bird-name">{{BirdName}}</div>
+  <div class="sci-name">{{SciName}}</div>
+  {{Image1}}{{Image2}}
+  {{#Song}}<div class="prompt-label">🎵 Song</div>{{Song}}{{/Song}}
+  {{#Call}}<div class="prompt-label">🔊 Call</div>{{Call}}{{/Call}}
+  <div class="divider"></div>
+  <div class="desc-box">{{Description}}</div>
+</div>"""
+
+TEMPLATES = [
+    {
+        "name": "Picture → Name",
+        "qfmt": """
+<div class="card">
+  <div class="prompt-label">🖼 What bird is this?</div>
+  {{Image1}}{{Image2}}
+  {{#Song}}<div class="prompt-label">🎵 Song</div>{{Song}}{{/Song}}
+  {{#Call}}<div class="prompt-label">🔊 Call</div>{{Call}}{{/Call}}
+</div>""",
+        "afmt": _BACK,
+    },
+    {
+        "name": "Description → Name",
+        "qfmt": """
+<div class="card">
+  <div class="prompt-label">🔊 What bird is this?</div>
+  {{#Song}}<div class="prompt-label">Song</div>{{Song}}{{/Song}}
+  {{#Call}}<div class="prompt-label">Call</div>{{Call}}{{/Call}}
+  <div class="divider"></div>
+  <div class="desc-box">{{Description}}</div>
+</div>""",
+        "afmt": _BACK,
+    },
+]
+
+
+def _stable_id(seed: str) -> int:
+    return int(hashlib.md5(seed.encode()).hexdigest()[:8], 16)
+
+
+MODEL = genanki.Model(
+    _stable_id("BirdDeck_Model_v2"),
+    "Bird ID",
+    fields=FIELDS,
+    templates=TEMPLATES,
+    css=CSS,
+)

avianki-0.1.1/src/avianki/cli.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+"""
+avianki.py — CLI entry point.
+
+Scrapes images, audio, and descriptions from allaboutbirds.org and packages
+everything into an Anki .apkg deck. Accepts three location formats:
+
+Usage:
+    avianki "https://www.allaboutbirds.org/guide/browse/..."
+    avianki ChIJGzE9DS1l44kRoOhiASS_fHg   # Google Place ID
+    avianki US-MA                           # eBird region code
+    avianki US-MA --limit 40
+
+Output:
+    Birds_<location>.apkg — import into Anki via File > Import
+"""
+
+import argparse
+import hashlib
+import logging
+import os
+import re
+import shutil
+import sys
+import time
+
+import genanki
+from dotenv import load_dotenv
+
+from . import allaboutbirds
+from . import anki_model
+from . import ebird
+from . import media
+
+load_dotenv()
+
+# ─── Logging ──────────────────────────────────────────────────────────────────
+_fmt = logging.Formatter("%(asctime)s %(levelname)-7s %(message)s", datefmt="%H:%M:%S")
+log = logging.getLogger("bird_deck")
+log.handlers.clear()  # avoid duplicate handlers if rerun in same Python session
+log.setLevel(logging.DEBUG)
+log.propagate = False
+
+_sh = logging.StreamHandler(sys.stdout)
+_sh.setFormatter(_fmt)
+_sh.setLevel(logging.INFO)
+log.addHandler(_sh)
+
+
+def _setup_logging(log_file: str, verbose: bool, quiet: bool) -> logging.FileHandler:
+    fh = logging.FileHandler(log_file, encoding="utf-8", mode="w")
+    fh.setFormatter(_fmt)
+    fh.setLevel(logging.DEBUG)
+    log.addHandler(fh)
+    if verbose:
+        _sh.setLevel(logging.DEBUG)
+    elif quiet:
+        _sh.setLevel(logging.WARNING)
+    return fh
+
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+
+
+def _safe_name(com_name: str) -> str:
+    """Filesystem-safe version of a common name for use in filenames."""
+    return re.sub(r"[^A-Za-z0-9_]", "_", com_name)
+
+
+def _get_audio(
+    sounds: dict, kind: str, safe: str, media_dir: str
+) -> tuple[str, list[str]]:
+    """
+    Download, trim, and cache one audio clip (call or song).
+    Returns ([sound:file] field value, [absolute path]) tuple.
+    """
+    base = f"bird_{safe}_{kind}"
+    cached = media.find_cached_audio(media_dir, base)
+    if cached:
+        log.info("  ✓ %s (cached)", kind)
+        return f"[sound:{cached}]", [os.path.join(media_dir, cached)]
+
+    urls = sounds.get(kind + "s", [])  # "calls" or "songs"
+    if not urls:
+        log.warning("  no %s audio found", kind)
+        return "", []
+
+    raw_path = os.path.join(media_dir, f"{base}_raw.mp3")
+    out_file = f"{base}.mp3"
+    out_path = os.path.join(media_dir, out_file)
+
+    if media.download_file(urls[0], raw_path) and media.trim_to_mp3(raw_path, out_path):
+        os.remove(raw_path)
+        log.info("  ✓ %s  %.1f KB", kind, os.path.getsize(out_path) / 1024)
+        return f"[sound:{out_file}]", [out_path]
+
+    log.warning("  %s download/trim failed", kind)
+    return "", []
+
+
+def _get_images(
+    img_urls: list[str], safe: str, media_dir: str
+) -> tuple[list[str], list[str]]:
+    """
+    Download and cache up to 2 images.
+    Returns (img_fields, media_paths) where img_fields are '<img src="...">' strings.
+    """
+    img_fields = []
+    media_paths = []
+
+    for idx, img_url in enumerate(img_urls, 1):
+        ext = os.path.splitext(img_url.split("?")[0])[1].lower() or ".jpg"
+        img_base = f"bird_{safe}_img{idx}"
+        cached = media.find_cached_image(media_dir, img_base)
+        if cached:
+            log.info("  ✓ image %d (cached)", idx)
+            img_fields.append(f'<img src="{cached}">')
+            media_paths.append(os.path.join(media_dir, cached))
+        else:
+            img_file = img_base + ext
+            img_path = os.path.join(media_dir, img_file)
+            if media.download_file(img_url, img_path):
+                log.info("  ✓ image %d  %.1f KB", idx, os.path.getsize(img_path) / 1024)
+                img_fields.append(f'<img src="{img_file}">')
+                media_paths.append(img_path)
+            time.sleep(0.5)
+
+    while len(img_fields) < 2:
+        img_fields.append("")
+
+    return img_fields, media_paths
+
+
+# ─── Main ─────────────────────────────────────────────────────────────────────
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Build an Anki bird ID deck from allaboutbirds.org",
+        epilog=(
+            "LOCATION can be:\n"
+            "  - An allaboutbirds.org browse URL  (copy from your browser)\n"
+            "  - A Google Place ID                (e.g. ChIJGzE9DS1l44kRoOhiASS_fHg)\n"
+            "  - An eBird region code             (e.g. US-MA or US-MA-017)\n"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "location", help="allaboutbirds.org URL, Google Place ID, or eBird region code"
+    )
+    parser.add_argument(
+        "--limit", type=int, default=None, help="Max number of species to include"
+    )
+    parser.add_argument(
+        "--output", default=None, help="Output .apkg filename (default: auto-generated)"
+    )
+    parser.add_argument(
+        "--deck-name", default=None, help="Override the deck name shown in Anki"
+    )
+    parser.add_argument(
+        "--no-audio", action="store_true", help="Skip downloading audio clips"
+    )
+    parser.add_argument(
+        "--no-images", action="store_true", help="Skip downloading images"
+    )
+    parser.add_argument(
+        "--delay", type=float, default=0.5, help="Seconds to wait between requests (default: 0.5)"
+    )
+    parser.add_argument(
+        "--clear-cache", action="store_true", help="Delete cached media before running"
+    )
+    parser.add_argument(
+        "--log-file", default="avianki.log", help="Log file path (default: avianki.log)"
+    )
+    verbosity = parser.add_mutually_exclusive_group()
+    verbosity.add_argument("--verbose", action="store_true", help="Show debug output")
+    verbosity.add_argument("--quiet", action="store_true", help="Only show warnings and errors")
+    args = parser.parse_args()
+
+    fh = _setup_logging(args.log_file, args.verbose, args.quiet)
+
+    location = args.location
+    media_dir = "media"
+    os.makedirs(media_dir, exist_ok=True)
+
+    if args.clear_cache:
+        shutil.rmtree(media_dir)
+        os.makedirs(media_dir)
+        log.info("Media cache cleared.")
+
+    # Determine species source: allaboutbirds URL/place ID, or eBird region code
+    use_ebird = re.match(r"^[A-Z]{2}(-[A-Z]{2}(-\d+)?)?$", location.upper())
+    if use_ebird:
+        region = location.upper()
+        if not os.getenv("EBIRD_API_KEY"):
+            log.error("EBIRD_API_KEY not set — add it to .env")
+            sys.exit(1)
+        raw = ebird.fetch_species(region, limit=args.limit)
+        slugs = [allaboutbirds.species_slug(b["comName"]) for b in raw]
+        names = {allaboutbirds.species_slug(b["comName"]): b for b in raw}
+        deck_name = args.deck_name or f"Birds – {region}"
+        deck_seed = region
+    else:
+        slugs = allaboutbirds.fetch_browse_species(location, limit=args.limit)
+        names = {}  # resolved lazily from each overview page
+        deck_name = args.deck_name or "Birds – Local"
+        deck_seed = location
+
+    if not slugs:
+        log.error("No species found for: %s", location)
+        sys.exit(1)
+
+    deck_id = int(hashlib.md5(deck_seed.encode()).hexdigest()[:8], 16)
+    deck = genanki.Deck(deck_id, deck_name)
+    all_media = []
+    skipped = 0
+
+    for slug in slugs:
+        # Resolve common + scientific name
+        if slug in names:
+            name = names[slug]["comName"]
+            sci = names[slug]["sciName"]
+        else:
+            resolved = allaboutbirds.slug_to_names(slug)
+            name = resolved["comName"]
+            sci = resolved["sciName"]
+
+        safe = _safe_name(name)
+        log.info("── %s ──", name)
+
+        overview = allaboutbirds.fetch_overview(slug)
+        if not overview["desc"] and not overview["images"]:
+            log.warning("  no allaboutbirds page found — skipping")
+            skipped += 1
+            time.sleep(args.delay)
+            continue
+
+        if not sci:
+            sci = overview.get("sciName", "")
+
+        if not args.no_images:
+            img_fields, img_paths = _get_images(overview["images"], safe, media_dir)
+            all_media.extend(img_paths)
+        else:
+            img_fields = ["", ""]
+
+        time.sleep(args.delay)
+
+        if not args.no_audio:
+            sounds = allaboutbirds.fetch_sounds(slug)
+            call_field, call_paths = _get_audio(sounds, "call", safe, media_dir)
+            all_media.extend(call_paths)
+            time.sleep(args.delay)
+            song_field, song_paths = _get_audio(sounds, "song", safe, media_dir)
+            all_media.extend(song_paths)
+            time.sleep(args.delay)
+        else:
+            call_field, song_field = "", ""
+
+        note = genanki.Note(
+            model=anki_model.MODEL,
+            fields=[
+                name,
+                sci,
+                img_fields[0],
+                img_fields[1],
+                call_field,
+                song_field,
+                overview["desc"],
+            ],
+            guid=genanki.guid_for(deck_seed, name, "v1"),
+        )
+        deck.add_note(note)
+
+    pkg = genanki.Package(deck)
+    pkg.media_files = all_media
+    output = args.output or f"Birds_{re.sub(r'[^A-Za-z0-9]', '_', deck_seed[:30])}.apkg"
+    pkg.write_to_file(output)
+
+    log.info("✅  Saved → %s", output)
+    log.info(
+        "    %d species, %d skipped, %d notes, %d media files",
+        len(slugs),
+        skipped,
+        len(deck.notes),
+        len(all_media),
+    )
+    log.info("    File > Import > %s", output)
+
+    fh.close()
+    log.removeHandler(fh)
+
+
+if __name__ == "__main__":
+    main()

avianki-0.1.1/src/avianki/ebird.py

@@ -0,0 +1,52 @@
+"""eBird API helpers."""
+
+import logging
+import os
+
+import requests
+
+log = logging.getLogger("bird_deck")
+
+
+def _headers() -> dict:
+    return {"X-eBirdApiToken": os.getenv("EBIRD_API_KEY", "")}
+
+
+def fetch_species(region_code: str, limit: int | None = None) -> list[dict]:
+    """
+    Return [{speciesCode, comName, sciName}] for every species recorded in a region.
+    Results are in eBird taxonomic order.
+    """
+    log.info("Fetching eBird species list for %s…", region_code)
+    r = requests.get(
+        f"https://api.ebird.org/v2/product/spplist/{region_code}",
+        headers=_headers(),
+        timeout=15,
+    )
+    r.raise_for_status()
+    codes: list[str] = r.json()
+    log.info("  %d species recorded in %s", len(codes), region_code)
+
+    if limit:
+        codes = codes[:limit]
+
+    # Resolve codes → full names in batches (safe URL length)
+    species: list[dict] = []
+    for i in range(0, len(codes), 200):
+        batch = codes[i : i + 200]
+        r2 = requests.get(
+            "https://api.ebird.org/v2/ref/taxonomy/ebird",
+            params={"species": ",".join(batch), "fmt": "json"},
+            headers=_headers(),
+            timeout=30,
+        )
+        r2.raise_for_status()
+        for t in r2.json():
+            species.append({
+                "speciesCode": t["speciesCode"],
+                "comName": t["comName"],
+                "sciName": t["sciName"],
+            })
+
+    log.info("  Resolved %d species names", len(species))
+    return species

avianki-0.1.1/src/avianki/media.py

@@ -0,0 +1,63 @@
+"""Media download, caching, and ffmpeg trimming."""
+
+import logging
+import os
+import subprocess
+
+import requests
+
+log = logging.getLogger("bird_deck")
+
+AUDIO_MAX_SECONDS = 10
+HEADERS = {
+    "User-Agent": (
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"
+    ),
+}
+
+
+def find_cached(media_dir: str, base: str, exts: list[str]) -> str | None:
+    """Return 'base.ext' if a file with any of the given extensions exists, else None."""
+    for ext in exts:
+        if os.path.exists(os.path.join(media_dir, base + ext)):
+            return base + ext
+    return None
+
+
+def find_cached_image(media_dir: str, base: str) -> str | None:
+    return find_cached(media_dir, base, [".jpg", ".jpeg", ".png", ".webp"])
+
+
+def find_cached_audio(media_dir: str, base: str) -> str | None:
+    return find_cached(media_dir, base, [".mp3", ".wav", ".ogg"])
+
+
+def download_file(url: str, path: str) -> bool:
+    """Download a URL to a local path. Returns True on success."""
+    try:
+        resp = requests.get(url, headers=HEADERS, timeout=30)
+        resp.raise_for_status()
+        with open(path, "wb") as f:
+            f.write(resp.content)
+        return True
+    except Exception as e:
+        log.warning("Download failed (%s): %s", url, e)
+        return False
+
+
+def trim_to_mp3(src: str, dst: str, seconds: int = AUDIO_MAX_SECONDS) -> bool:
+    """Trim audio to `seconds` and re-encode as MP3 via ffmpeg. Returns True on success."""
+    try:
+        result = subprocess.run(
+            ["ffmpeg", "-y", "-i", src,
+             "-t", str(seconds),
+             "-acodec", "libmp3lame", "-q:a", "4",
+             dst],
+            capture_output=True,
+            timeout=30,
+        )
+        return result.returncode == 0
+    except Exception as e:
+        log.warning("ffmpeg trim failed (%s): %s", src, e)
+        return False