Skip to main content

Film types and length rules

Ten types. Most are a date range with a filter on it; trip, album, holiday and special day aren't, and those are the ones worth reading about. Every type works on a plain NAS from Immich's metadata and the picture facts prepared locally (dates, places, faces, favourites and context heads).

TypeCoversTargetNeeds
year_in_reviewone calendar year10 minnothing extra
monthly_highlightsone month60 snothing extra
seasonone season of one yearabout 3 min 15 snothing extra
person_spotlighta range, one person60 s a month, capped at 10 mina named face in Immich
multi_persona range, several people60 s a month, capped at 10 minnamed faces in Immich
on_this_daytoday's date in every earlier year45 sa few years of library
holidayone recurring date across several years60 sa few years of library
tripone trip found from GPS30 s + 10 s an active dayGPS on your pictures, and a home base
albumone Immich album30 s + 10 s an active dayan album
special_days.detectionone day the library says something happened onas long as its distinct shots allow, up to 3 minnothing, or the discover-days catalogue

Every type except a trip, an album and a special day opens on a title the app writes from what the film is and when: "Kit · July 2025", "Christmas · 2019–2025", "October 14 · 2012–2025". See where the title came from.

Two setup steps make every type better: a home base, so the editor can tell a week away from a week at home, and who's who, so it knows which people come first. Set both in Home and people.

How long a film runs​

A film is as long as its distinct shots can carry. It's never padded.

The target is where the length starts. A film never runs longer than the distinct shots its days hold: a video counts once its window clears every one already kept, a photo or Live Photo counts once it's five real minutes from every frame already kept in its moment, and a pile of near-identical frames counts as one shot. A dense day supplies a lot, a thin day much less. The film goes short rather than padding. The run record says what set the length:

What set itWhen
--durationyou passed a number (or typed a length under Length and pictures in the web UI)
--short-formyou picked a short-form preset and passed no --duration
the materialneither flag, and the period holds pictures
the preset floorneither flag, and the period holds nothing to measure

A trip and an album count active days: 30 s plus 10 s a day, held between 60 s and 5 min. A special day runs as long as its distinct shots allow, up to 3 min, with at least 30 s of pictures on top of its title and ending. Twelve one-minute months don't make a twelve-minute year: the year has its own ten-minute target. How the editor spends those seconds is in Length, quiet weeks and filler.

Filtering by people​

Repeating --person means pictures holding every name. --person-match or makes it a union; the web UI's Pictures with select (all of them together or any of them) is the same switch. For anything else, --people-expression takes the condition directly:

immich-memories generate --memory-type multi_person --year 2025 \
--people-expression '"Riley" AND ("Casey" OR "Bob")'

AND binds tighter than OR, and AND means the same picture, not just the same afternoon: every named person must be recognised on that exact picture, strict per picture. The expression replaces --person and --person-match. The web UI has it under Grouped condition. Trips, albums, person spotlights and any --birthday run refuse it.

Year in review​

A whole calendar year, in capture order, with a title card wherever the month changes.

immich-memories generate --memory-type year_in_review --year 2025

The editor groups the year into stories (a trip, a birthday, a run of ordinary weeks), weighs them against each other and gives each the shots its weight earns. From library to film has the rules. A thin year won't reach 10 minutes, and the cut says how far short it landed.

Each month is checked afterwards: a month with worthy material that ends up silent makes the run's verdict coverage_incomplete. Nothing reserves a slot per month up front. If everything you have is one summer trip, a season or trip memory fits the material better.

Month dividers appear only when the range stays within one calendar year and spans four months or more. --no-photos takes stills out of the pool; they are in it by default.

Monthly, season, person, multi-person​

Same shape, different scope: pick a range, optionally filter by person, cut.

immich-memories generate --memory-type monthly_highlights --month 7 --year 2025
immich-memories generate --memory-type season --season summer --year 2025
immich-memories generate --memory-type person_spotlight --person "Riley" --year 2025
immich-memories generate --memory-type multi_person --person "Riley" --person "Bob" --year 2025

Season fits a curve through the date range: about 3 min 15 s for three months, the same from the web UI and the CLI. --duration overrides it. --hemisphere south maps summer onto December to February.

Person spotlight needs the person named in Immich's face recognition. What makes it a spotlight is the filter: the editor is the same one. Multi-person defaults to AND, so two people never in the same frame give an empty memory rather than two solo reels. Each window is read once for videos and once for photos, however many people are named. The title names everyone with "&" either way ("Kit & Pat · 2025"); the default filename says OR (multi_person_or), so the two runs never overwrite each other.

A people memory with no dates​

Leave the dates off a person or multi-person memory and it covers everything up to today, starting on the first day one of its pictures could exist:

immich-memories generate --memory-type multi_person \
--people-expression '("Riley" OR "Bob") AND "Sam"'

The start comes from the birth dates Immich holds, and from birth_date in the people registry where Immich has none. An AND waits for the youngest person it needs; an OR opens with the oldest it accepts, and bounds nothing when one of them has no birth date. Two grandparents AND a child born in 2024 covers 2024 onward, because no older picture can hold the child. runs why on an earlier picture says where the window came from. Dates you do give are never moved.

The title names everyone, then the span: "Riley, Bob & Sam · February 2024 to October 2026", the same for --person, --group and --people-expression. One person's reads "Riley · March 2019 to October 2026".

A spotlight over more than about 18 months is told as the person, one era per calendar year. Every year that holds a usable picture of them gets one moment before any story gets a second, so the dense recent years cannot take the whole film. Years with no picture of them take no part.

Birthdays​

--birthday turns a person spotlight into a yearly review of someone's life, from one birthday through the next, and nothing else. For a 21 July birthday and --year 2025 it runs 21 July 2024 to 21 July 2025, both parties included: last year's opens the film and this year's closes it. Target: 10 minutes. The opening title names the birthday being celebrated and its year ("Emma's birthday · 2025"). The app writes it; no model is asked. An explicit --title keeps your own wording.

immich-memories generate --person "Emma" --year 2025 --birthday

The birth date lives in Immich (People, pick the person, edit). Without one a birthday film refuses rather than guessing. --birthday 07-21 overrides it for one run, month first; slashed forms are rejected. Automatic birthday films are this same year.

Add --years-back and you get a different film: the birthdays themselves. The party and that many earlier birthdays, each ±1 day, and nothing from the days in between. It's the "look how small you were" film, about a minute long, titled with the years it shows ("Emma's birthday · 2021–2025").

immich-memories generate --person "Emma" --year 2025 --birthday --years-back 5

Most earlier birthdays hold nothing, so the run prints one line (history: 2 of 5 earlier windows hold material) rather than a warning per year. Only pictures a film can use count: a day holding nothing but forwarded copies or saved images holds no material, and the line says how many it set aside. With advanced.analysis.forwarded_copies_when_short on, those copies may stand in for a birthday that has no picture of its own (configuration reference). 29 February is celebrated on the 28th in other years.

In the web UI: Person Spotlight, then tick Birthday to birthday. The Birthday (MM-DD) field under it overrides Immich's birth date. Leave Only the birthdays, this many years back empty for the year; fill it in for the birthdays film. Cut a year the night before: a year of one person is a cold run the first time.

On this day​

Up to 30 earlier years by default, ±1 day around today, in one 45-second cut. --years-back changes that reach. It wants three or more years of library, and it is the obvious one to schedule.

immich-memories generate --memory-type on_this_day --years-back 3
immich-memories generate --memory-type on_this_day --day 2026-08-31 --years-back 20

--day names the anniversary to look back from, so a run can be repeated or compared.

Holiday​

A recurrence, not a period: one window per year, the holiday ±2 days, in every year back to 30 years, so twenty Christmases ask Immich for twenty windows and never for the months between.

immich-memories generate --memory-type holiday --holiday christmas

The film is about the day itself. Each year keeps the pictures of the holiday, plus the night that started on it (until 4:00 the next morning). The two days either side only join when the day holds fewer than 5 pictures, and a year with nothing on the day adds nothing. Every year that has a shot gets one before any year gets a second, and no year takes more than an even share of the film: a starred afternoon or two long videos from one year can't fill it.

--holiday is required. --years-back N narrows the film to the holiday of the year and the N before it; without it, every year is read. These names are recognised; availability depends on the country where the table says so:

NameFalls on
new_year1 January
valentines14 February
easterWestern Easter Sunday, computed
mothers_daysecond Sunday of May, or where your home country keeps it
fathers_daythird Sunday of June, or where your home country keeps it
halloween31 October
thanksgivingwhere the country's public calendar has it (the US: fourth Thursday of November)
christmas_eve24 December
christmas25 December
new_years_eve31 December

--holiday also takes any public holiday of your country by name (see below), and anything else is read as MM-DD, for a household's own occasion (--holiday 09-14, the day you moved in). Without --year, the starting year steps back when this year's occasion has not happened yet. The title is the holiday's name in the film's language, then the years the cut shows: "Assomption · 2004–2026", from the first year with footage to the last, whatever years between hold none. A public holiday takes the name its country's calendar gives it in that language, and a day from extra_holidays takes the name you wrote there. No text model writes a holiday's title.

The holidays follow the country your home base is in (trips.homebase_latitude and trips.homebase_longitude); Immich's own geodata says which country that is, so nothing leaves your server. Each country's public holidays come from the holidays library, and --holiday accepts their names too (--holiday "ascension day" in Belgium). Without a home base the US calendar applies. These defaults do not describe what every household celebrates.

Additional observances are added on top: Valentine's Day, Halloween, Christmas Eve, New Year's Eve, and Mother's and Father's Day, which move by country:

CountryMother's DayFather's Day
US, and any country not listedsecond Sunday of Maythird Sunday of June
BE, ATsecond Sunday of Maysecond Sunday of June
DEsecond Sunday of MayAscension Day
ITsecond Sunday of May19 March
ES, PTfirst Sunday of May19 March
FRlast Sunday of May, a week later on Pentecostthird Sunday of June
GB, IEthree weeks before Easterthird Sunday of June
AU, NZsecond Sunday of Mayfirst Sunday of September
MX10 Maythird Sunday of June

Only national holidays are read; regional calendars are not included. For an observance missing from the calendar, use its date as MM-DD with --year for a single year. A recurring MM-DD repeats the Gregorian date; it does not calculate lunar or other moving observances.

Something missing? A public holiday belongs in the holidays library upstream. A family day, or a country whose Mother's or Father's Day differs: open a pull request against memory_types/date_builders.py, one rule per line.

Trip​

Nothing declares a trip. The GPS on your pictures decides where one starts and ends, and each trip gets its own film.

That film is the real renderer over the demo library, asked for 40 seconds (tests/e2e/fixtures/library, credits in its CREDITS.md): a real road trip from Denmark to Nordkapp and back down the Norwegian coast, at the places and times its photographer took it. The satellite fly-over needs network.map_tiles: true, which is off by default because the tiles come from ArcGIS. With it off, the title sits on a flat panel. What that switch sends is on Privacy.

Detection is three steps:

  1. Away from home: a picture counts if its GPS is at least min_distance_km (50) from home. No GPS, no trip.
  2. Split on gaps: a new trip starts wherever more than max_gap_days (2) calendar days pass between two pictures, so a rest day does not split a trip. Saturday morning to Monday afternoon is a two-day gap, regardless of the capture times. A trip over New Year is one trip, not two.
  3. Drop the short ones: a trip must span min_duration_days (2) nights. 1 catches a weekend.
trips:
homebase_latitude: 48.8566 # required
homebase_longitude: 2.3522 # required
min_distance_km: 50
min_duration_days: 2
max_gap_days: 2

Home base is required. Get it wrong and your own neighbourhood becomes a trip, or real trips disappear. Drop min_distance_km to about 20 if weekend drives should count.

immich-memories generate --memory-type trip --year 2025 # list what it found
immich-memories generate --memory-type trip --year 2025 --trip-index 2
immich-memories generate --memory-type trip --year 2025 --all-trips
immich-memories generate --memory-type trip --year 2025 --near-date 2025-07-15

Both surfaces read photos and videos, and look a month either side of the year so a trip across New Year stays whole. --person narrows detection (whose pictures are scanned for GPS, useful when one phone carries it). Videos enter by date; photos also need GPS at least min_distance_km (50 km by default) from home. Photos without GPS or nearer home stay out even if their dates fit. Some cameras strip GPS, so a library shot on one can look full of holidays and find none.

--trip-index counts from 1 in the printed table. --month 7 selects the trip whose midpoint is closest to the 15th of that month; it does not crop a trip to July. Without --output, a trip starts with the filename trip_<place>_<start-date>.mp4, using a safe place slug and the selected container extension. The run adds its hash and directory as described under Output.

The name is the smallest place holding at least 85 % of the trip's located pictures, walking up from city to island, region, two regions, country. One step comes before the region: a town holding more than half of the pictures names the trip, so a seaside weekend with a walk to the next town is named after the town, not the province. It comes from the place Immich already stored on each picture, offline:

The tripIts name
A long weekend, nearly every picture in Las VegasLas Vegas, United States
Two weeks across Heraklion, Rethymno and ChaniaCrete, Greece (French film: Crète, Grèce)
Palma and PollençaMallorca, Spain
A road trip, mostly Utah and NevadaUtah and Nevada, United States
Four states, none of them most of itUnited States

network.geocoding: true lets Nominatim name a one-city or one-region trip in the film's language, and a trip to a village inside a merged municipality after the village. It is off by default: it sends coordinates to a third party.

Album​

One Immich album instead of a date range. The album is the selection: nothing outside it is considered, nothing inside it is dropped for its date. A shared album counts as your own.

immich-memories generate --from-album "Trip 2025"
immich-memories generate --from-album 59080965-22f0-46a4-be67-135692a9f584

--from-album makes it an album memory, and cannot be combined with --year, --start/--end, --period, --birthday, --season, --month, --person or another --memory-type. Albums and trips also reject --accounts; they read the primary account only. The film is titled after the album and named album_<slug>_<hash>.mp4 unless --output names the file. Two albums with one name stop the CLI with the candidates and their IDs; the web UI lists albums largest first and stores the choice by ID.

Smart albums like Recents can hold tens of thousands of assets. Album mode reads at most 10,000 per media type, newest first, and says so. Past that, you probably want a date range.

An album made for one subject​

An album you built around one thing (every loaf you baked, every car you drove) can say what that thing is:

immich-memories generate --from-album "Bread" --subject "bread making along the years"

With --subject, every picture in the album stands on that subject. An ordinary film drops a loaf on a counter with nobody in frame; this one keeps it. Every year the album holds gets at least one shot. Sharing, the family-viewing holds, duplicates and the length still apply, and the run record lists each shot that got in on the subject alone (Picking each shot). --subject needs --from-album and a model reader: the Basic reader refuses a written subject.

Special day​

The nine types above cover something you named. A special day is one you didn't: a day from your library that a scan flagged, wrote down and offers back when its anniversary comes round. --day is required. When the catalogue holds several events on that day, also pass --event-id with the event's ID from days-export. An ID that does not match an event on the chosen day is refused.

immich-memories discover-days # build the catalogue once; it resumes
immich-memories days-due # what falls within three days of today
immich-memories generate --memory-type special_day --day 2016-06-12

discover-days walks the library a month at a time. On Basic, a day is kept when one recorded fact stands out: it was spent away from home, it holds three or more favourites, it is mostly video, or it ran long (20 pictures over 6 hours or more) with close family in it. Each year keeps its strongest advanced.automation.special_days_per_year (6), away days first. The title comes from the day's own place.

The catalogue lives in the store; days-export writes it to a JSON file you can edit and days-import reads it back. A film covers the day's run, the stretch of pictures the occasion left, split at five hours of silence rather than at midnight, so a long night out is not cut at 00:00. It never reaches past its own first and last picture, and a run longer than 48 hours is not one occasion. window_origin in the run record says what bounded the film.

Three routes bring a day back: auto run offers anniversaries within 3 days (round ones first, a decade before a seventh), the Special day type on the Memory page offers the whole catalogue, and generate --day takes any day, catalogued or not. An uncatalogued day is scoped to itself and named by --title, else by a model from the day's facts when model titles are on (below), else after its place ("A day in Lisbon") with the date under it.

Catalogue titles name real people and places, so they never reach the command line: automation passes --day alone and generate re-reads the title. What automation prints is the evidence:

10 years ago today · 289 photos over 18 hours
via special-days catalogue

With a model​

A text model adds three things here, and changes nothing else about the types:

  • discover-days reads each month's days together, then checks each proposed occasion against that day's own picture descriptions. Both readings must agree it was an occasion; a title alone doesn't qualify it. No picture is sent. Confirmed occasions need enough varied material for a film, and the six-a-year cap doesn't apply. Unread days stay marked for a retry. discover-days --rescan rebuilds the catalogue; --replace redoes only the years between --since and --until.
  • With the experimental title_screens.llm_titles on (off by default) or --llm-title, a special day gets a title written from its facts, catalogued or not. The reader invents no event name the facts don't carry. Years, months, seasons, people, birthdays, holidays and "on this day" keep the app's own title ("Summer 2025", "Kit & Pat · 2025"); no model writes those.
  • A month or year gets a light polish on top of the Basic draft. What that polish does and costs is on What a model adds and Make it better.