# Titles, maps and music

Markdown version of <https://sam-dumont.github.io/immich-memories/docs/make/titles-maps-music/>.

These are render choices. You can change them after reviewing the cut, without asking the app to choose the shots again.

## Titles and language

Under **Render**, type a **Title** and **Subtitle**, or leave them empty for the app's own. The
app titles a film by what it is and when, in the film's language. No model writes these:

| Film | Title |
| - | - |
| A year, month or season | its period: "2025", "July 2025", "Summer 2025" |
| One person | first name and year: "Kit · 2025"; with no dates, the first and last year their pictures show: "Kit · 2003–2026" |
| Several people | every first name, whether you picked them by name, group or expression: "Kit, Pat & Lou · 2025", with the same span of years when you gave no dates |
| A birthday | whose it is and the year being celebrated: "Kit's birthday · 2026" |
| A holiday | its own name and the years the cut shows: "Assomption · 2015–2026" |
| On this day | the day and its span of years: "October 15 · 2012–2025" |
| A special day the scan never catalogued | its place: "A day in Lisbon" |

Nothing goes under the title unless you type a subtitle. With `title_screens.llm_titles: true`
(experimental, off by default) an optional [text reader](https://sam-dumont.github.io/immich-memories/docs/better/reader.md) names special days
instead, from their stories, people and places. A reader title keeps the year the template title
would show; one that drops it falls back to the template. A reader subtitle may only carry dates,
places, people and words the film's facts use: a mood line the facts don't back ("salt air and
golden light") is dropped and the title stands.

The film's language is separate from the interface language. Save **Settings > Title screens > locale**
(including in Docker), or set it in your configuration. A special day found by the automatic
scan is catalogued with an English name, but its opening title is always written in this
configured language, not in English.

```yaml
title_screens:
  locale: fr
```

The default, `auto`, follows the host's language: `LC_ALL`, `LC_MESSAGES`, `LANG` and `LANGUAGE` are checked
in that order, and on a Mac with none of those set, the macOS language setting is used instead. A Docker
container usually starts with none of them set, so it renders English titles until you set
`title_screens.locale` or the container's `LANG`.

A trip is named at one scale (a town, a region, a country, whichever fits how far its pictures
spread) and every part of that name is shown in this same configured language, in the opening
title, the trip picker in the web UI, and the discovery table a `generate --memory-type trip`
run prints before cutting one. A French film never shows a region translated next to its
country in English, or the other way round.

## Opening and closing fades

Choose **Opening and closing fade** under **Render**: white, black, or **As configured**. This changes the fade at both ends of the title sequence for this film. Title screens must be enabled.

Set the default in **Settings → title screens → fade\_color**, or in your configuration:

```yaml
title_screens:
  fade_color: black  # white is the default
```

For one CLI render, add `--fade-color black` to `generate` or `runs render`. The override leaves your saved default alone.

## Styles

Choose **Title style** under **Render** for one film. **As configured** keeps the saved default. The choices are **Auto (match the mood)**, **Random**, **Modern warm**, **Elegant minimal**, **Vintage charm**, **Playful bright** and **Soft romantic**. For a lasting default:

```yaml
title_screens:
  style_mode: elegant_minimal
```

`auto` and `random` are also valid defaults. For a saved CLI cut, use `runs render RUN_ID --title-style elegant_minimal`. Preview a card before rendering the whole film:

```bash
immich-memories titles test --year 2025 --style elegant_minimal
```

In Docker, write the preview to the mounted output folder:

```bash
docker compose exec immich-memories immich-memories titles test --year 2025 --style elegant_minimal -o /app/output/title-test.mp4
```

The host file is `./output/title-test.mp4`.

The [style and font reference](https://sam-dumont.github.io/immich-memories/docs/reference/output-rendering.md#styles) lists the palettes and supported alphabets. Docker includes the fonts; native installs may need `immich-memories titles fonts --install`.

On a CPU or NAS, title cards keep the font, layout and palette. FFmpeg slides, scales and fades
the text over a still background; the text is drawn once. Moving backgrounds, bokeh, animated
deblur and separate title/subtitle timing still need a rendering GPU.

## Date and place captions

In **Render**, untick **Add date overlay** or **Caption clips with their place** if you want a cleaner frame. Frequently visited places are not labelled over and over. The lasting defaults are `defaults.add_date` and `defaults.add_place`.

Place captions show the city when it changes. The home country stays hidden. Abroad, the
country appears when you enter it, unless the opening title already named it; the next city
doesn't repeat it. Crossing another border shows the new country.

With `network.geocoding: true`, Nominatim resolves rounded coordinates at zoom 16 in your
chosen title/caption language. If a translation is missing, it tries the base language
(for example, Portuguese for Brazilian Portuguese), then falls back to the place's own
native name rather than English. A Greek village with no French name stays in Greek
script in a French film, not translated or anglicised. A town keeps its name even when
no translation exists. Administrative words come off: "Limassol District" reads Limassol, "Pärnu linn"
reads Pärnu. A Latvian, Lithuanian or Finnish municipality name
comes in the genitive ("Helsingin kaupunki"), so the caption uses the city Immich stored for the
picture instead ("Helsinki"). Some places write their name in several alphabets at once, as
many Moroccan ones do ("Medina ⵎⴷⵉⵏⴰ المدينة"). The caption keeps one: the part in your film's
alphabet ("Medina" in a Spanish film), or the first part when none matches. A long place name
shrinks to fit the frame, portrait included, and only gets cut short with "…" when it still
doesn't fit at the smaller size.

Near the configured home base, captions can name the district, such as Montmartre in Paris; further
out, a district needs most of a stay's pictures behind it to keep its name, and excursions keep
their own labels. Visits spread across districts use their shared locality, and towns separated
by more than `trips.max_gap_days` do not rename one another. Streets and points of interest stay
out of captions. A country disagreement keeps the source label; failed lookups are retried on a
later run. A few distant excursions do not turn a local stay into a regional trip, and a town
already named by its own pictures is not replaced by a broader label from the trip's centre
point. The [output reference](https://sam-dumont.github.io/immich-memories/docs/reference/output-rendering.md) has the exact distances and
shares.

## The map fly-over

Trip maps are off by default. Enable them when you want an animated route and are comfortable requesting satellite tiles from an outside provider:

In Docker, save **Settings > Network > map\_tiles**, or use YAML:

```yaml
network:
  map_tiles: true
```

With maps off, a trip uses ordinary title and location cards. Smooth maps fly between stops; the fast preset uses three views joined by short fades. Maps add time to the finished film beyond the picture budget. [Map rendering](https://sam-dumont.github.io/immich-memories/docs/reference/output-rendering.md#the-map-fly-over) covers providers, route grouping and timing.

## Music

In **Render**, choose **Automatic**, **No music**, or upload your own MP3, M4A or WAV. **Music volume** changes the mix; the music drops under the clips' own sound. When a clip's own sound is music or singing, the soundtrack steps aside for its whole window instead of competing with it.

Untick **Keep original audio** to remove all sound recorded in videos and Live Photos, including speech. The film keeps its motion and plays only the soundtrack. With **No music** selected too, it is silent. Original audio stays on by default.

For the same choice on the CLI, add `--no-original-audio` to `generate` or `runs render`:

```bash
immich-memories runs render RUN_ID --no-original-audio --music ~/Music/track.mp3
```

Automatic uses a bundled track by default: 76 generated tracks, each about 90 seconds, in five moods (calm, tender, nostalgic, happy, energetic) and styles from piano and lo-fi to downtempo, neo-soul, post-rock, funk and city pop. The Docker image has them built in; on a pip install, `immich-memories models fetch` downloads them once (118 MB, checked against a pinned SHA-256), and a film never downloads music. Without them a film plays the smaller set of 28 shorter tracks that ships with the `music` extra. `models fetch` skips the download when `audio.no_music` is on. A configured [music generator](https://sam-dumont.github.io/immich-memories/docs/better/music.md) running the XL model makes an original track instead and enables **Preview a track** so you can listen first. A generator that fails, or can't run XL, falls back to a bundled track and leaves a warning.

### Your own music folder

Put your own tracks in `audio.local_music_dir` (`~/Music/Memories` unless you change it), one subfolder per mood, the way the bundled tracks are laid out:

```text
~/Music/Memories/
  calm/       slow-piano.mp3, rain-guitar.flac
  happy/      ukulele-morning.m4a
  tender/     lullaby.opus
```

Automatic then picks from your folder instead of the bundled tracks, by the film's mood, the same way: a beat that fits the photo cadence first, and one track per film, looped onto itself when the film is longer. Folder names are moods: calm, peaceful, tender, nostalgic, playful, happy, exciting, energetic, and the rarer ones (sad, romantic, dramatic, mysterious, inspiring, melancholic, uplifting). A playful film without a `playful` folder takes `happy`; peaceful takes `calm`, exciting `energetic` and romantic `tender`, as the bundled music does.

A mood your folder lacks plays the bundled tracks for it. A mood neither has (a year in review starts as `inspiring`) picks from all of your folder. An empty or missing folder leaves the bundled music in charge, and the log says so without printing the path. A configured generator still comes first; your folder replaces the bundled fallback, not the generator. In Docker, mount the folder and point `audio.local_music_dir` at the mount.

### No music by default

```yaml
audio:
  no_music: true
```

Films then render without music on every surface: `generate`, `runs render`, the daily timer and triggered runs, and the web **Render** panel, which opens on **No music**. A run can still ask for music: `--music FILE`, `--music auto`, or picking **Automatic** or a track in the panel. `--no-music` turns it off for one film when the config leaves it on.

Temporary files used to loop and master bundled tracks are removed after mixing, including
when the mix fails.

On the CLI:

```bash
immich-memories generate --year 2025 --music ~/Music/track.mp3 --music-volume 0.4
```

## When a model names the film

Model-written titles and summaries are experimental and off by default: they miss too often. Turn them on with `title_screens.llm_titles: true`, or for one run with `--llm-title`. Then a text reader names special days (and trips, with `--llm-title`) and writes the film's summary. A reader still chooses the music mood on the Basic tier, whatever this setting says. Those calls use text, not pictures. Years, months, seasons, people, birthdays, holidays and "on this day" films keep the app's own title whatever the reader could say. Your typed title wins over all of it. [Title provenance](https://sam-dumont.github.io/immich-memories/docs/reference/output-rendering.md#where-the-title-came-from) explains the source shown on a run.

A model title can use a first name, a place, an occasion name or a relationship word your family record actually states between the people it names, such as "her grandmother". It never calls someone family, or states a relationship, that your record doesn't back, and it never names a year that isn't true for the span. It also never narrates a parent or grandparent from a child's point of view ("maman", "papy", "mum", "oma") even when your record backs the relation; standard words such as "abuela" or "mormor", which have no separate child's-eye form in their own language, are unaffected. A title that breaks a rule falls back to the plain template instead.

## Generated music

[Set up generated music](https://sam-dumont.github.io/immich-memories/docs/better/music.md) when you want it. The [output reference](https://sam-dumont.github.io/immich-memories/docs/reference/output-rendering.md) has language catalogues, typography, map timing and audio mixing details.
