One of our readers, Meir, once suggested a new feature for the frame on the GitHub forum.

He wanted an automatic filter on specific dates, like birthdays or anniversaries. On these special days, only a hand-made collection of images would be shown without manual interaction.

Never forget another wedding anniversary when you only see photos of your wedding in the morning. Talk about a gentle reminder!

My first thought was that this was going to be challenging. But it turns out that with some first principles thinking from Paddy, it's very easy to implement. Meir and Paddy devised a super simple solution, which they were kind enough to let me share here.

This article is written for picframe3, the frame software from my 2026 build guide.

Still running Pi3D PictureFrame? If your frame is a Pi 2, 3 or Zero 2 W on the Bookworm edition, skip to the original recipe at the end.

There are really two wishes hiding in this idea:

  1. "Show me this day in earlier years." Your wedding photos on your wedding anniversary, last year's birthday party on this year's birthday.
  2. "Show something special on a special day." Greeting cards, a personal message, a hand-picked set of photos.

On picframe3, the first one is a button. The second one needs a folder and a small script.

On this day: a button, nothing to set up

picframe3 has a set of date filters built in, and one of them is on this day: photos taken on today's calendar date, in any year.

You find it in the Filter bar at the top of the frame's web interface, and it arrives in Home Assistant as a button with no configuration at all, next to today, the last 7, 30 and 90 days, the last year, the last three years and all dates.

It is stored as a rule, not as a date. Switch it on once and tomorrow it shows tomorrow's photos from earlier years, without a crontab or a script.

The date comes from the photo itself, the moment it was taken, so this works best with photos straight from a camera or phone. A picture without a date of its own, like most scans, is dated by when its file was saved, and turns up on that day instead.

A folder for each special day

For greeting cards and hand-picked sets, you give each special day its own folder, and a small script switches the frame to that folder when the day comes.

Prepare your picture collection

Ask yourself the question:

A. Do you want to show photos on these special days that you wouldn't show normally? Think greeting cards, a personal message.

B. Or do you want to focus on a set of images from your normal collection, shown exclusively on a particular day?

A. Show special photos that you don't normally display

Create a new folder called main inside Pictures and put all the pictures you want to see every day in it. Don't leave any pictures directly in Pictures.

Then create a folder for each special date next to it, in the form MMDD: MM for the month and DD for the day, so 0510 for the tenth of May.

Pictures/
├── main/        ← your everyday pictures
├── 0510/        ← only on May 10
└── 1224/        ← only on December 24

Put the photos for each date in its folder. If you also want one of them in your normal slideshow, copy it into main as well.

Leave the frame's picture folder setting at Pictures, so it sees all of these folders. The script below makes sure that on ordinary days only main is shown.

B. Focus on a set of images exclusively

Here the special photos are part of your normal collection anyway. On their day, the frame shows only them.

Create the MMDD folders anywhere directly in Pictures and move the photos in there. They keep showing up in the normal slideshow on every other day.

Nothing to switch on

On the old frame, you had to enable the web server in the configuration file first. On picframe3, the web interface and its API are on by default, and the script talks to that API. If you ever switched the web interface off, set enabled: true under http: in ~/.config/picframe3/config.yaml and restart the frame.

Create the script

Log on to your frame and create the script:

nano ~/check_date.sh

Paste the content below.

#!/bin/sh
# Show today's MMDD folder if there is one, otherwise go back to normal.
DAY=$(date +%m%d)
URL=http://localhost:9000/api/filters

if [ -d "$HOME/Pictures/$DAY" ]; then
  BODY="{\"reset\":true,\"folder\":\"Pictures/$DAY\"}"
else
  BODY='{"folder":""}'
fi

curl -s -XPOST "$URL" -H 'content-type: application/json' -d "$BODY"
echo "$(date) - $BODY" >> "$HOME/check_date_log.txt"

If you went with option A, change the else line to

  BODY='{"folder":"Pictures/main"}'

Save and close, and make the script executable with

chmod +x ~/check_date.sh

Here is what it does:

  • On a special day it clears every other filter first (reset) and then shows only that day's folder. Otherwise a date filter you left on, say "last 30 days", would hide greeting cards you scanned years ago, and the frame would show nothing.
  • On an ordinary day it only resets the folder, back to everything (option B) or to main (option A). A tag or place filter you set yourself stays where it is.
  • It writes one line per run to check_date_log.txt in your home folder, so you can see what it sent.

It has to switch back on ordinary days because picframe3 remembers the folder filter, even across a reboot. Without that line, your frame would stay on May 10 for good.

Two more details:

  • picframe3 finds a folder by looking for its name anywhere in a picture's path, regardless of upper and lower case. 0510 on its own would also catch a folder called 20230510_Rome, and main would catch Mainz. That's why the script says Pictures/0510 and Pictures/main.
  • If you set a user name and password for the web interface, add -u user:password to the curl line. If your pictures are not in ~/Pictures, change the path in the if line and in the folder values.

Make the crontab settings

Now, all you need to do is instruct crontab. Type

crontab -e

and make the script run each day at one minute past midnight by adding these two lines:

@reboot sleep 60 && $HOME/check_date.sh
01 00 * * * $HOME/check_date.sh

If this is your first time using crontab, you will be asked which editor to choose. Answer "1" for Nano.

The reboot line makes sure the right folder is set after a power cut, and it lets you test with the current day. The sleep delay gives the frame time to start. If you use a slower Raspberry Pi, you may have to extend it.

You may even want to change the time to four o'clock in the morning, so if you have a birthday party in the evening, your frame will not kill the mood by changing back to your everyday pictures while everybody is still dancing. In that case, enter

00 04 * * * $HOME/check_date.sh

Why a script file rather than a single curl line in the crontab? The date check needs date +%m%d, and cron reads every % as a line break unless you escape it. That's the kind of mistake that fails silently at midnight.

Test it

Create a folder named after today's date (date +%m%d tells you which), put a picture in it and run

~/check_date.sh

The frame should switch to that picture right away, and check_date_log.txt shows the folder it asked for. Delete the test folder and run the script again to go back.

Alternative approach: tags

Instead of using folders, you could add a tag ("0510" for May 10) to your special occasion photos. picframe3 filters on tags too, from the filter bar, from Home Assistant, or with {"tags":"0510"} through the API.

The script above, though, can only tell whether today is special by looking for a folder. And I would assume that most people are unfamiliar with tagging, so Meir's folders are much easier to implement.

On Pi3D PictureFrame: the original recipe

This is the recipe as I wrote it in November 2024 for Pi3D PictureFrame. It has not been re-tested since. The folders are the same as above, with one difference for option A: instead of the script choosing main, you point the frame at it in configuration.yaml:

  pic_dir: "~/Pictures/main"                   # default="~/Pictures", root folder for images

(~ is your own home directory. Only write /home/pi/ if your user really is called pi. Raspberry Pi OS has not created that user by default since 2022.)

For option B, you don't have to change anything in configuration.yaml.

Switch on the web server. Open configuration.yaml and activate HTTP control in the http section:

http:
  use_http: True                         # default=False

Leave all other values unchanged (port 9000, no authentication). Save and close.

Create the Python script. Go to the picframe_data directory with

cd /home/pi/picframe_data

and create a new Python script with

nano check_date.py

Paste the below content in this file.

#!/usr/bin/python3

import datetime
import os
from urllib import request

ROOT_DIR = "/home/pi/Pictures"  # Root directory for picture subdirectories
URL = "http://localhost:9000"    # URL for sending requests

# Get current date and format it as MMDD
date_now = datetime.datetime.now()
subdirectory = f"{date_now.month:02}{date_now.day:02}"
full_url = f"{URL}?subdirectory="

# Check if the subdirectory exists within the root directory
if subdirectory in os.listdir(ROOT_DIR):  # No error handling here
    full_url += subdirectory  # Append the subdirectory to the URL
    request.urlopen(full_url)  # Send a request to the constructed URL

# Log the URL with date and time for debugging purposes
with open("/home/pi/picframe_data/check_date_log.txt", "a") as log_file:
    log_file.write(f"{datetime.datetime.now()} - directory:{full_url}\n")

Save, close and make it executable with

chmod +x /home/pi/picframe_data/check_date.py

Add the crontab lines with crontab -e:

@reboot sleep 60 && python3 /home/pi/picframe_data/check_date.py
01 00 * * * python3 /home/pi/picframe_data/check_date.py

The plain python3 is deliberate here: the script imports nothing but the standard library, so it does not need the venv_picframe interpreter that PictureFrame itself runs from. If you ever add a library to it, it will. The sleep delay is necessary because @reboot jobs sometimes run before all system services are up; 30 seconds seem to be fine on a Pi 5.

Conclusion

Thank you to Meir for coming up with such an exciting feature idea and to Paddy for helping him devise a simple solution.

Don't ever forget your wedding day again with this simple feature!