# Film types and length rules

Markdown version of <https://sam-dumont.github.io/immich-memories/docs/reference/film-types/>.

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).

| Type | Covers | Target | Needs |
| - | - | - | - |
| `year_in_review` | one calendar year | 10 min | nothing extra |
| `monthly_highlights` | one month | 60 s | nothing extra |
| `season` | one season of one year | about 3 min 15 s | nothing extra |
| `person_spotlight` | a range, one person | 60 s a month, capped at 10 min | a named face in Immich |
| `multi_person` | a range, several people | 60 s a month, capped at 10 min | named faces in Immich |
| `on_this_day` | today's date in every earlier year | 45 s | a few years of library |
| `holiday` | one recurring date across several years | 60 s | a few years of library |
| `trip` | one trip found from GPS | 30 s + 10 s an active day | GPS on your pictures, and a home base |
| `album` | one Immich album | 30 s + 10 s an active day | an album |
| `special_days.detection` | one day the library says something happened on | as long as its distinct shots allow, up to 3 min | nothing, 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](https://sam-dumont.github.io/immich-memories/docs/reference/output-rendering.md#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](https://sam-dumont.github.io/immich-memories/docs/get-started/who-is-who.md).

## How long a film runs

**Diagram: A film is as long as its distinct shots can carry. It's never padded.** [(image)](https://sam-dumont.github.io/immich-memories/diagrams/decide-length.svg)

```text
┌─────────┐  ┌───────────┐  ┌─────────────┐  ┌───────────────────────────┐  ┌───────────────────────┐  ┌────────────────────────────────┐
│         │  │           │  │             │  │     15, 30, 60 or 90 s    │  │        shorter        │  │                                │
│How long?├─►│--duration?├─►│ that target │ ►│    portrait, unless you   │ ►│what the distinct shots│ ►│            no film             │
│         │  │           │  │             │ ││     pick another shape    │ ││   can hold, then on   │ ││      Nothing worth a film      │
└─────────┘  └─────┬─────┘  └─────────────┘ │└───────────────────────────┘ │└───────────────────────┘ │└────────────────────────────────┘
                   │                        │                              │                          │
                   │                        │                              │                          │
                   │               ┌────────┘              ┌───────────────┘            ┌─────────────┘
                   │               │                       │                            │
                   │               │                       │                            │
                   │        ┌──────┴──────┐  ┌─────────────┴─────────────┐  ┌───────────┴───────────┐  ┌────────────────────────────────┐
                   │        │             │  │                           │  │                       │  │                                │
                   │        │             │  │          Too few          │  │                       │  │            The film            │
                   └───────►│--short-form?├─►│      distinct shots?      ├─►│     Nothing worth     ├─►│auto target rounded down to 5 s;│
                            │             │  │month: 60 s; trip: 60–300 s│  │        a film?        │  │   ordinary titles: up to 20%   │
                            │             │  │   from photographed days  │  │                       │  │                                │
                            └─────────────┘  └───────────────────────────┘  └───────────────────────┘  └────────────────────────────────┘
```

Arrows:

- How long? → --duration?
- \--duration? → that target
- \--duration? → --short-form?
- \--short-form? → 15, 30, 60 or 90 s
- \--short-form? → Too few distinct shots?
- Too few distinct shots? → shorter
- Too few distinct shots? → Nothing worth a film?
- Nothing worth a film? → no film
- Nothing worth a film? → The film

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 it | When |
| - | - |
| `--duration` | you passed a number (or typed a length under **Length and pictures** in the [web UI](https://sam-dumont.github.io/immich-memories/docs/make/web-ui.md)) |
| `--short-form` | you picked a short-form preset and passed no `--duration` |
| the material | neither flag, and the period holds pictures |
| the preset floor | neither 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](https://sam-dumont.github.io/immich-memories/docs/how-it-chooses/length-and-filler.md).

## 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:

```bash
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.

```bash
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](https://sam-dumont.github.io/immich-memories/docs/how-it-chooses/overview.md)
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.

```bash
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:

```bash
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.

```bash
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").

```bash
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](https://sam-dumont.github.io/immich-memories/docs/reference/config-reference.md)). 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.

```bash
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.

```bash
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:

| Name | Falls on |
| - | - |
| `new_year` | 1 January |
| `valentines` | 14 February |
| `easter` | Western Easter Sunday, computed |
| `mothers_day` | second Sunday of May, or where your home country keeps it |
| `fathers_day` | third Sunday of June, or where your home country keeps it |
| `halloween` | 31 October |
| `thanksgiving` | where the country's public calendar has it (the US: fourth Thursday of November) |
| `christmas_eve` | 24 December |
| `christmas` | 25 December |
| `new_years_eve` | 31 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`](https://github.com/vacanza/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:

| Country | Mother's Day | Father's Day |
| - | - | - |
| `US`, and any country not listed | second Sunday of May | third Sunday of June |
| `BE`, `AT` | second Sunday of May | second Sunday of June |
| `DE` | second Sunday of May | Ascension Day |
| `IT` | second Sunday of May | 19 March |
| `ES`, `PT` | first Sunday of May | 19 March |
| `FR` | last Sunday of May, a week later on Pentecost | third Sunday of June |
| `GB`, `IE` | three weeks before Easter | third Sunday of June |
| `AU`, `NZ` | second Sunday of May | first Sunday of September |
| `MX` | 10 May | third 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.

**Video (44 s)** [trip-preview.mp4](https://sam-dumont.github.io/immich-memories/demo/trip-preview.mp4)\
![Poster frame](https://sam-dumont.github.io/immich-memories/img/trip-map-flyover.jpg)

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](https://sam-dumont.github.io/immich-memories/docs/run/privacy.md).

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.

```yaml
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.

```bash
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](https://sam-dumont.github.io/immich-memories/docs/reference/generation-contract.md#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 trip | Its name |
| - | - |
| A long weekend, nearly every picture in Las Vegas | `Las Vegas, United States` |
| Two weeks across Heraklion, Rethymno and Chania | `Crete, Greece` (French film: `Crète, Grèce`) |
| Palma and Pollença | `Mallorca, Spain` |
| A road trip, mostly Utah and Nevada | `Utah and Nevada, United States` |
| Four states, none of them most of it | `United 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.

```bash
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:

```bash
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](https://sam-dumont.github.io/immich-memories/docs/reference/selection-internals/picking-shots.md#what-a-frame-must-pass)).
`--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.

```bash
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`](https://sam-dumont.github.io/immich-memories/docs/reference/special-days.md#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](https://sam-dumont.github.io/immich-memories/docs/run/database.md); `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:

```text
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](https://sam-dumont.github.io/immich-memories/docs/how-it-chooses/what-a-model-adds.md) and
  [Make it better](https://sam-dumont.github.io/immich-memories/docs/better/overview.md).
