🐦 MMM-BirdOfTheDay

This is a personal hobby project I build for my own use and publish in case it's useful to someone else. I work on it in my spare time, so issues and PRs are welcome but replies may be slow. Use at your own risk.

• Screenshots
• Features
• Prerequisites
• Installation
• Configuration
• Layout Options
• Customization
• Changelog
• Credits
• License

Text Below (Default)	Text on Left	Text on Right

• 🖼️ Displays a random bird with a high-quality image — and picks a random photo when a bird has several
• 🔄 Calendar-aligned rotation — Hourly (top of the hour), Daily (midnight), or Weekly (Monday at midnight)
• 💾 Remembers the current bird and history across restarts — the mirror rebooting no longer changes today's bird
• 📋 Optional details: common name, scientific name, region, and conservation status
• 📐 Flexible layout: text below, left, or right of the image
• 🎨 Fully customizable image size and font size via CSS
• 🧠 Smart history tracking to avoid showing the same bird twice
• 🏷️ Module title follows the rotation interval, in your mirror's language (English and Swedish included)
• 🔁 Retries automatically (and tells you on the mirror) if the bird database is unreachable at startup
• 🔐 API calls run server-side in a node helper, so your API key stays out of browser traffic

• MagicMirror² installed and running
• A free API key from the Nuthatch API

1. Navigate to your MagicMirror's modules directory:

cd ~/MagicMirror/modules

2. Clone this repository:

git clone https://github.com/cgillinger/MMM-BirdOfTheDay

Step 1 — Get your free API key:

Visit the Nuthatch API key generation page and follow the instructions.

Step 2 — Add the module to your config.js:

{
    module: "MMM-BirdOfTheDay",
    position: "top_center",     // Choose your preferred position
    config: {
        apiKey: "YOUR_API_KEY_HERE",   // Required
        rotation: "Daily",             // "Hourly" | "Daily" | "Weekly"
        imageWidth: "400px",           // CSS width value
        fontSize: "medium",            // "small" | "medium" | "large"
        textPosition: "below",         // "below" | "left" | "right"
        showTitleLine: true,
        maxHistory: 50,
        showName: true,
        showSciName: true,
        showRegion: true,
        showStatus: true,
    },
},

Control where the text appears relative to the image using the textPosition option:

config: {
    textPosition: "below",
}

config: {
    textPosition: "left",
}

config: {
    textPosition: "right",
}

You can further tweak the appearance by editing MMM-BirdOfTheDay.css in the module folder. Adjust colors, fonts, spacing, and more to match your mirror's theme.

Good to know: the module stores its state (current bird and history) in .botd-state.json inside the module folder so your Bird of the Day survives restarts. Delete that file if you ever want to reset the rotation. And keep your config.js out of version control — it contains your API key.

Bird data and images are provided by the Nuthatch API by Last Elm Software — a big thanks for making this free resource available! All rights for bird data and images belong to their respective contributors.

This project is licensed under the MIT License — see the LICENSE file for details.