# Config Reference

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

Every key with its built-in default. Set one in `~/.immich-memories/config.yaml`, as an environment
variable, or from the web UI's settings page (saved to the database). Environment beats the file,
the file beats the database, the database beats these defaults; `immich-memories config show` says
which one set each key ([where a setting comes from](https://sam-dumont.github.io/immich-memories/docs/run/config-file.md#where-a-setting-comes-from)).

> **Config tiers:** Tier 2 sections (`analysis`, `hardware`, `llm`, `musicgen`, `ace_step`, `server`, `auth`,
> `automation`, `notifications`, `triage`, `editorial`, `inference`, `free_text`, `speech`) go under an
> `advanced:` key in the file:
>
> ```yaml
> advanced:
>   analysis:
>     download_workers: 2
>   hardware:
>     encoder_preset: "quality"
> ```
>
> Both placements are read and merge key by key: a top-level value wins for the same key, while
> other keys under `advanced:` remain set. Everything else
> stays top level. Unknown keys inside a section are ignored; unknown top-level keys and invalid
> values fail validation at startup.

## Tier

One resolved tier controls both preparation and selection. Leave it automatic for normal use.

```yaml
tier: auto                         # auto | basic | gpu | full
```

| `tier` | Models | Reader | Needs |
| - | - | - | - |
| `basic` | eight shared-DINO CPU heads, no captions | rules | `models fetch` |
| `gpu` | heads, Marqo, Docling, captions and Laya | rules | a caption server, `models fetch` |
| `full` | everything in `gpu` | an LLM polishes the rules draft and writes the prose | enable `advanced.llm`; owned local model by default, or an explicit `base_url` and server model |

`auto` is the default. A healthy inference service reporting CUDA, or a local CUDA or MLX/Metal
runtime, selects `gpu`. An explicitly enabled LLM alongside that capability selects `full`. Without GPU
inference capability, selection stays on `basic` and reports what is missing. A renderer's GPU
does not establish inference capability. The runtime check loads no model weights and sends no
pictures; preflight and acquisition still check the actual producers.

`tier` is the only tier setting. The reader, the preparation mode, Laya and the detectors follow
from it; none of them is a key of its own. Save keeps automatic resolution automatic when the file
moves to another host.
An explicit `basic`, `gpu` or `full` pins a tier for a controlled comparison; it does not install or
start its services. `full` requires an enabled reader: the app-owned local model or a configured API.

Configured LLM titles and music mood work on every tier. A title from the LLM is for a special day,
or a trip with `--llm-title`; year, month, season, person, birthday, couple, holiday and "on this
day" films always take the app's own title. Basic and GPU still select with rules,
and sharing never asks the prose LLM. Captions use their own configured service; a text LLM is
not an automatic caption fallback. A missing Laya checkpoint or runtime is reported and uses
the conservative rules fallback; that is a degraded run, not a verified GPU/full comparison.

Env: `IMMICH_MEMORIES_TIER=auto`. A Compose, Kubernetes or Terraform install sets it with its
`TIER` (`IMMICH_MEMORIES_DEPLOYMENT_TIER`), which ranks with the environment: a `tier` in
config.yaml or Settings is ignored there, with a warning naming the variable. From a source checkout,
`uv run python scripts/tier_settings.py` prints what each tier runs with. That helper script is
not part of a pip/uv install; `immich-memories capabilities` reports the resolved setup there.

## Preset

One top-level switch that fills several knobs at once. `fast` is the CPU-only / NAS profile.
Anything you set yourself wins over the preset.

```yaml
preset: null                       # null | fast
```

`fast` sets, unless you set them yourself: `output.resolution: 1080p`, `output.codec: h264`,
`output.quality: fast`, `hardware.encoder_preset: fast` and
`title_screens.animated_background: false` (static title backgrounds and three-view maps). Music generation is already
off by default and stays wherever you put it.

Env: `IMMICH_MEMORIES_PRESET=fast`. One-off on the CLI: `immich-memories --preset fast generate …`
(root option, before the subcommand).

Settings saved in the UI or CLI go to the database. Environment variables and `config.yaml` still win; the app refuses to save a database value that they would override. Bootstrap keys never go to the database: `database.*` (read before the store opens), and `auth.*` and `server.*` (they decide who can reach the app). Set them in the environment or `config.yaml` and restart. A saved value cannot contain a `${VAR}` reference.

## Immich connection

Immich Memories supports **Immich v2 and v3**. Automatic runtime detection is the default:

```yaml
immich:
  url: "https://photos.example.com"
  api_key: "${IMMICH_API_KEY}"
  api_version: auto  # auto | v2 | v3
  public_url: ""     # the address your browser opens Immich at; blank = url
```

`url` is where the app reaches Immich, and every API call goes there. On Kubernetes
(`http://immich.immich.svc.cluster.local:2283`) or a shared Docker network (`http://immich-server:2283`)
that address does not open in your browser, so the links the app shows (**View in Immich** after an
upload, **Open in Immich** on the People page) would be dead. Set `public_url` to the address you
use yourself (`https://photos.example.org`) and those links use it. It is used for links only,
never for a request, and `preflight` prints it next to the server URL when it is set. Env:
`IMMICH_MEMORIES_IMMICH__PUBLIC_URL`. On Docker, add it under `environment:` only when you set it: an empty line pins the key and hides the one in `config.yaml`.

Keep `api_version` on `auto` for normal use. The client detects and caches the server major for
each runtime client; you do not choose it for each generation. Explicit `v2` or `v3` is a manual
troubleshooting escape hatch for a proxy or unusual deployment that prevents correct detection.
An override forces that API contract.

Run the read-only `immich-memories config test` to check credentials and see the resolved API
contract without generating or uploading a memory.

### Extra accounts

People can upload to separate Immich accounts. Put additional accounts under `accounts`, by name. The top-level `url` and `api_key` stay the primary account,
and the primary is the only account a film is ever uploaded to.

```yaml
immich:
  url: "https://photos.example.com"
  api_key: "${IMMICH_API_KEY}"
  native_sharing: false  # opt into verified native person identities on Immich 3.2 or 3.3
  accounts: {}  # name -> url, api_key, api_version (default: none)
  # accounts:
  #   partner:
  #     url: "https://photos.example.com"
  #     api_key: "${PARTNER_IMMICH_API_KEY}"
  #     api_version: auto
```

A name is lowercase letters and digits joined by single underscores (`partner`, `grandma_2`), and
`primary` is taken: it means the top-level account. The name is what a person alias bound to that
account records. Configuring an account adds nothing to your films: a run reads only the accounts it
selects, and every selected account has to answer `/users/me` with its key before anything is read.
`generate --accounts primary,partner` reads the named accounts into one film on the CLI, and
[`automation.accounts`](#automation) does the same for the daily scan. `config test` and
`preflight` check each one, one line per account, with no key printed:
[A second Immich account](https://sam-dumont.github.io/immich-memories/docs/run/multi-account.md).

The key is a secret like the primary one: redacted from logs and issue reports, and sealed with
`IMMICH_MEMORIES_SECRET_KEY` when saved to the database (the whole `immich.accounts` map is one
encrypted row). From the environment, name the account in the variable:
`IMMICH_MEMORIES_IMMICH__ACCOUNTS__PARTNER__API_KEY`.

## Render worker

The CLI and web UI can send an already selected film to a trusted render worker.
Blank `worker_base_url` renders on the app's machine.

```yaml
render:
  worker_base_url: ""
  worker_token: ""             # Or ${RENDER_WORKER_TOKEN}
  allow_insecure_http: false   # Explicitly accept a non-loopback cleartext HTTP worker
  timeout_seconds: 3600        # Least wait for rendering and download; longer films get more (more than 0, at most 86400 s)
  fallback_to_local: false     # Set true to allow local rendering after a worker failure
```

Use the same app version on both machines. The worker receives the selected assets,
exact cuts, Live source material, titles, locations, audio markers and the Immich API key
so it can download the sources directly. Configure a worker you trust, reachable over
your private network or HTTPS. The handoff request carries that Immich key, so a
non-loopback `http://` worker URL is refused until `allow_insecure_http: true` says you
meant it; loopback addresses and HTTPS need no opt-in. Preflight names the transport
before the first render request. Requests require the worker token and do not follow redirects.

The worker accepts H.264 or H.265 MP4. When a worker is configured, MOV and ProRes
render locally only with `fallback_to_local: true`; with `false`, the run fails.
Orientation only sets the canvas; it does not change the selection. Speech detection and cut
selection run before handoff. Music and Immich upload finish on the app after it checks the returned film.

See [worker deployment](https://github.com/sam-dumont/immich-memories/tree/main/services/render-worker)
for Docker Compose and Kubernetes examples.

## Video analysis

```yaml
advanced:
  analysis:
    # Media the camera roll did not shoot (see Configuration → Footage the
    # camera roll did not shoot). Setting the list replaces it; [] turns it off.
    exclude_filename_patterns:     # case-insensitive globs on the source filename
      - "RingVideo_*"
      - "RPReplay_Final*"
      - "Screen Recording *"
      - "Screenshot*"
      - "img-*-wa[0-9][0-9][0-9][0-9]*"
      - "vid-*-wa[0-9][0-9][0-9][0-9]*"
    exclude_stills_without_camera_exif: true   # a photo naming no camera was received, not shot
    max_source_video_seconds: 300  # Exclude longer source videos on Immich metadata, before download (0 disables)
    forwarded_copies_when_short: false  # Let forwarded copies fill gaps in the film's camera timeline

    # Downloads
    download_workers: 3            # Parallel Immich clients for downloads, previews and faces (1-8)
    source_prepare_workers: auto   # Sources prepared at once (1-4); auto: reserve 1 GiB, then 3 GiB per worker; 1-2, capped by available CPUs
    prepared_source_cache_max_size_gb: 10.0  # Disk for prepared sources a later render reuses (0-500 GB; 0 keeps none)

    # Live Photos (iPhone 3s video clips)
    include_live_photos: true      # Include Live Photo clips (ON by default)
```

The filename globs exclude matching source media before preparation. Replacing the list replaces
all defaults; `[]` disables that filter. `exclude_stills_without_camera_exif` excludes photos
whose EXIF names no camera; videos are exempt. Set it to `false` for exported originals that lost
camera metadata. These filters apply before selection, so a model cannot bring excluded media back.

`forwarded_copies_when_short` is off by default. Turn it on and a picture refused only as a
forwarded copy or saved image (a messaging export with no camera behind it) can fill a gap in the
film's camera timeline. The film reads its time the way it already cuts it: each occurrence (a
holiday's year, an earlier birthday), else each week of a film up to two months long, each month
of one up to two years, each year of a longer one. A stretch with no camera picture is a gap. A gap
gets about as many days of copies as a stretch with camera pictures has days of them, so a
lockdown year fills its empty months without the copies taking over the film. How short the film
is of its length no longer counts.

A copy that would fill a gap still has to pass every check a camera picture does, and is left out
when it's a collage (thin flat gutters between tiles, or a caption that says collage or
composite) or a copy of a picture your library already holds, found through Immich's own
duplicate groups and the duplicate review's preview hash. Screenshots and documents stay out
either way. Two copies of one scene received hours apart count as one moment.

The limit, and why this is opt-in: a copy is dated when it was received, not when it was taken.
A photo re-shared years later, with no original in your library, lands in the year it arrived.
The run names the copies that fill gaps, and the shot's reason says "a forwarded copy".

Any Live Photo cluster of two or more within the merge window is treated as a burst; the count is
not configurable. Where a clip is cut, and how long it runs, is the editor's decision per carrier.

A render keeps each source it prepares (the cut video segment, the animated photo, the merged
Live Photo) under `<cache.directory>/prepared-sources`. Rendering the same selection again, or
re-running after a crash, reuses them instead of downloading and preparing them again. A source is
reused only when nothing that shaped it has changed: the picture as Immich describes it (its
original, its edit, its Live Photo clips), whether it plays as a still, a stitched Live Photo or a
cut of a video, the cut window and how long a still stays on screen, the canvas, every setting that
reaches preparation (the tier, `output`, `hardware`, `photos`, `analysis` and the rest), this
machine's encoders, and the app version. Anything else prepares it again. An edited photo is
asked about its edit each render, since Immich changes nothing else on the asset when you replace
an edit; if Immich can't say, the photo is prepared again rather than reused. A source the run had to settle for less on (a Live Photo that played its
single video because the burst would not merge, a burst missing a part that failed to download, a
software encode after the hardware encoder failed) is never kept, so the next render tries again.
`prepared_source_cache_max_size_gb` caps the folder; the least recently
used sources go first, and `0` turns the reuse off. It also stays off with
`cache.video_cache_enabled: false`.

An album source reads up to 10,000 videos and 10,000 photos. Immich returns newest first, so a bigger album is truncated to its most
recent assets, with a warning naming it.

## Speech boundaries

```yaml
advanced:
  speech:
    enabled: true          # Move video cuts out of detected speech
```

The bundled FireRedVAD model runs locally with the `editorial` or `editorial-cuda` extra.
It measures retained videos and Live Photo companions, then maps speech onto the stitched
timeline. The editor fits the resulting intervals before rendering; an uninterrupted
utterance may cost more time or cause a clip to be left out. This detects voice activity,
not sentence meaning.

The same model also scores a clip's own sound for music or singing, which is how the soundtrack
knows to step aside instead of just ducking under it. Without the ONNX runtime, or with
`advanced.speech.enabled: false`, that detection never runs and the soundtrack never steps aside.

## Generation defaults

```yaml
defaults:
  scale_mode: "blur"             # blur | fit (black bars); used when --scale-mode is not given
  transition: "smart"            # cut, crossfade, smart, none (used when --transition is left on smart)
  transition_duration: 0.5       # 0-2 seconds
  sharing: "family"              # just-us | family | shareable; used when --sharing is not given
  add_date: true                 # caption each clip with its date; --no-add-date turns it off for one film
  add_place: true                # caption each clip with its place; --no-add-place turns it off for one film
```

`add_date` and `add_place` are the one rule for captions on every surface: the web render panel
starts from them, `generate` and `runs render` use them when neither `--add-date` nor
`--no-add-date` is given, and automation follows them. Set one to `false` to turn that caption off
everywhere, automation included. Privacy mode never shows a place, whatever `add_place` says.

`sharing` is who a film is for when the run doesn't say (`generate --sharing`, or **Who will watch
it** in the web brief). `just-us` is the household: a private moment a caption names, like a bath,
plays too. `family` keeps those out. `shareable` plays only what nothing held back. The rules:
[Sharing levels](https://sam-dumont.github.io/immich-memories/docs/reference/selection-internals/family-audience-duplicates.md#sharing-levels).

Target duration and orientation are per run (`--duration`, `--orientation`, or the UI), with the
memory type preset supplying the default duration; there is no config default for either. The
target covers the finished video, title and ending cards included, and the encoder lands near it
rather than exactly on it. There is no backfill: if the stories the editor funded do not fill the
budget, the run reports the shortfall.

## Output

```yaml
output:
  directory: "~/Videos/Memories"
  format: "mp4"                  # mp4 or mov
  resolution: "1080p"            # 720p, 1080p, 4k
  codec: h264                     # h264 (default), h265 (HDR-capable), prores
  codec_policy: prefer_hardware   # prefer_hardware (default) or strict
  hdr_mode: auto                  # auto, sdr, hdr
  quality: "balanced"            # high, balanced, fast (shorthand for CRF presets)
  crf: null                      # unset = derived from quality; 0-51 overrides (lower = better)
  min_free_space_gb: 5.0         # warn below this on the output/cache volumes; 0.5-1000
```

CRF is the image-quality authority. `quality` is only a shorthand used when `crf` is omitted; an
explicit `crf` wins. The number is on **libx265's CRF scale**, and every other encoder is
calibrated against it: each backend gets whatever setting reproduces the same picture, measured by
SSIM, rather than the same integer. Lower CRF means higher quality everywhere. The measured table
per encoder is on
[the hardware overview](https://sam-dumont.github.io/immich-memories/docs/run/hardware.md#quality-one-dial-calibrated-per-encoder).

The presets are points on that curve, measured on 1080p60 film:

| `quality` | reference CRF | SSIM | software bitrate | per minute |
| - | - | - | - | - |
| `high` | 18 | 0.99169 | 4.6 Mbps | \~35 MB |
| `balanced` (default) | 24 | 0.98451 | 1.6 Mbps | \~12 MB |
| `fast` | 24 | 0.98451 | 1.6 Mbps | \~12 MB, encoded as fast as the backend can |

There is no tier below `balanced`: around SSIM 0.980 gradients start to band. `fast` keeps the
balanced picture and buys its speed from the encoder effort preset instead, overriding
`hardware.encoder_preset`. Choose `balanced`, `high` or `fast` for a new configuration.

`codec_policy` decides what happens when the machine has no hardware encoder for the codec you
asked for but does have one for the other. `prefer_hardware` (the default) switches codec and says
so in the log and the run record, which on a chip like Intel Gemini Lake (H.264 encode entrypoint,
no HEVC one) is the difference between a film finishing and the CPU doing all of it. `strict`
always honours `output.codec` and accepts the CPU cost. The switch never applies to ProRes, and
never to an HDR output.

Containers and codecs pair up: `mp4` and `mov` with `h264`, `h265` or `prores`, and ProRes requires
MOV. `generate --format` accepts only `mp4`, `h265`, and `prores`: they select H.264/MP4,
H.265/MP4, and ProRes/MOV respectively. Internal and UI overrides also represent `h264_mov` and
`h265_mov`, but `h264_mov` and `h265_mov` are not CLI choices.

`hdr_mode: auto` preserves detected HLG or PQ sources when `codec: h265` is selected, converting
SDR clips, photos and title screens into the chosen HDR transfer before blending. H.264 is always
SDR: with `codec: h264`, `auto` tone-maps detected HDR sources and logs the reason. Use
`hdr_mode: sdr` when SDR is intentional, or `hdr_mode: hdr` with H.265 to force an HDR output from
SDR sources.

`min_free_space_gb` is a preflight, not a cap: it runs before a film starts rendering, on both
`output.directory` and `cache.directory`. Below the threshold the run logs a warning naming the
volume and its free space; below what the film itself needs (estimated from target duration and
`quality`) it stops before writing anything. A run that uploads to Immich has nothing else to do
here: its local film is removed once the upload is confirmed. A run that keeps files locally is
the one this protects. See [health, logs and caches](https://sam-dumont.github.io/immich-memories/docs/run/maintenance/health-logs-cache.md#caches).

## Photos

```yaml
photos:
  enabled: true                  # Include photos in memories
  duration: 4.0                  # Seconds per photo clip (1-10)
```

`duration` is how long the cut holds a still. With no model reader, an empty scene gets half a
second less and the film's first and last stills half a second more; a full film keeps fewer
stills rather than shaving them below that. `generate --photo-duration` sets it for one run.

The animation per photo (Ken Burns, face pan) is picked from the photo's content and is not
configurable. The bands around a photo that does not fill the canvas follow `defaults.scale_mode`,
as they do for video.

Burst de-duplication keeps only the best-scored frame of a run of near-identical photos (five
minutes apart at most), so fifteen shots of the same jump do not become fifteen clips.

## Hardware acceleration

```yaml
advanced:
  hardware:
    enabled: true                  # false = CPU encoding, no GPU probing at all
    backend: "auto"                # auto, none, nvidia, apple, vaapi, qsv
    encoder_preset: "balanced"     # fast, balanced, quality
    gpu_decode: true               # Hardware video decoding
```

`auto` detects the backend (NVIDIA NVENC → Apple VideoToolbox → Intel QSV → VAAPI, first hit wins).
`hardware.enabled: false` or `hardware.backend: none` forces software rendering. On multi-GPU Linux hosts pick the card with
`CUDA_VISIBLE_DEVICES` / `NVIDIA_VISIBLE_DEVICES`.

Naming a backend probes that one and nothing else, which is for measuring rather than for running.
A named backend that cannot encode here logs a warning and falls back to software. `backend` covers
the video render and Live Photo burst merge. Clip extraction detects its own backend and does
not use `hardware.backend`.

`encoder_preset` controls encoder speed and effort; it does not replace `output.crf`. On Apple,
`fast` enables VideoToolbox's speed-priority mode while `balanced` and `quality` leave it disabled.

## Audio and music

Background music uses a bundled track by default. Those tracks ship in Docker and the `music`
extra; a base pip/uv install needs that extra for the bundled fallback. Generated music needs `ace_step.enabled` or `musicgen.enabled`. With both on, ACE-Step generates
and MusicGen is the fallback generator and the stem separator used for ducking; with MusicGen off,
stems come from a local Demucs install if there is one. Per run, `--music PATH` uses your own file
and `--no-music` skips music. Music volume is per run too (`--music-volume`); the ducking and the
2 s / 3 s fades are fixed.

```yaml
audio:
  no_music: false                       # true: films render without music unless a run asks
  local_music_dir: "~/Music/Memories"   # Your own music, one folder per mood; films pick from it
advanced:
  musicgen:
    enabled: false                 # Use a MusicGen API server
    base_url: "http://localhost:8000"
    api_key: ""
    timeout_seconds: 10800         # 3 hours (60-18000)

  ace_step:
    enabled: false                 # Use ACE-Step (remote server or local library)
    mode: "api"                    # api (remote REST server) or lib (local, requires Python 3.12)
    api_url: "http://localhost:8000"
    api_key: ""                    # Bearer token for a protected ACE-Step server (api mode)
    model_variant: "auto"          # auto: XL on 64 GB+ Macs or 16 GB+ GPUs, else a bundled track; or xl-turbo, turbo, base
    lm_model_size: "1.7B"          # Default planner; use 4B with the XL production profile
    use_lm: false
    cpu_offload: true              # Local CUDA: move models back to CPU between phases
    timeout_seconds: 3600          # 60-18000

```

`advanced.ace_step.cpu_offload` defaults to `true` for local generation. CUDA moves models back
to CPU between phases to reduce VRAM use; `false` keeps them resident when enough VRAM is
available. The existing Apple Silicon runtime ignores this option, and API requests stay
unchanged. Host and container memory guards still apply. The environment override is
`IMMICH_MEMORIES_ACE_STEP__CPU_OFFLOAD=false`.

`audio.local_music_dir` is your own music, one subfolder per mood like the bundled library. Films
pick from it by mood in place of the bundled tracks; a mood it lacks plays the bundled ones, and a
configured generator still comes first. The `immich-memories music` commands read it too.
[Your own music folder](https://sam-dumont.github.io/immich-memories/docs/make/titles-maps-music.md#your-own-music-folder) has the layout.

`audio.no_music: true` renders every film without music: `generate`, `runs render`, automation and
the web render panel (which opens on **No music**). `--music FILE`, `--music auto` or a track picked
in the panel still gets music for that film; `--no-music` turns it off for one film.

Generated music is one take per film. The repetition check still scores it and writes the score to
the log, so a film that sounds mechanical can be diagnosed, but a high score never costs another
generation. `audio.max_regenerations` is ignored and warns when set; it stops being read in 2.0.

Seasonal music prompts read seasons in the home base's hemisphere (`trips.homebase_latitude`),
like the titles do; without a home base they read the northern one.

Generated music is planned from the assembled film's length. A film up to 90 seconds gets one
ACE-Step take. A longer one gets up to 3 takes of at most 90 seconds that share one caption, style, tempo and key, cut on bar lines and
joined with a 0.3 s crossfade, then repeated if the film is longer still. No setting chooses the
style: the app picks from the film's mood: solo piano, lo-fi, downtempo, neo-soul, post-rock, funk or city pop. Two takes never play over
each other for longer than that crossfade. MusicGen continues its own audio, so it gets the whole
film in one request, one scene per chapter.

## Text model and optional vision captions

One `llm` section serves the selection reader, titles, music mood, special-day scans and explicitly enabled LLM captions. Any OpenAI-compatible or Anthropic-compatible endpoint
works: mlx-vlm, oMLX, Ollama, vLLM, Groq, OpenAI, Claude, z.ai.

```yaml
advanced:
  llm:
    enabled: false                  # false: no LLM calls; true: local or API, chosen by base_url
    provider: "openai-compatible"   # openai-compatible | openai | zai | anthropic | ollama
    base_url: ""                     # blank: owned locally or hosted provider preset; URL: use that API
    model: "gemma-4-E4B-it-Q4_0"     # default local Gemma, another GGUF path, or API model name
    local_server: "llama-server"     # local executable on PATH or its full path
    local_mmproj: ""                 # custom GGUF vision projector; default Gemma has a pinned pair
    local_context: 32768             # bounded local context; affects memory use; at least 1024 tokens
    api_key: ""                      # optional, only for cloud APIs
    timeout_seconds: 300             # increase for slow local models (10-3600)
    send_image_detail: true          # off: APIs whose strict schema rejects image_url.detail
    always_reasons: false            # true: the endpoint thinks on every call, asked or not
    thinking: "disabled"             # disabled | low | high | max | auto
    reader_concurrency:              # independent reader jobs; unset reads it from base_url
    batch: "off"                     # off | auto: provider-supported batching of independent prompts
    batch_min_requests: 8            # fewest independent prompts in a stage worth queueing; 2-10000
    batch_max_wait_minutes: 60       # then ask whatever the batch has not answered in real time; 1-1440 minutes
    # thinking_params:               # what the switch looks like on your server
    #   chat_template_kwargs:        # (default: the Qwen dialect, vLLM/mlx)
    #     enable_thinking: true
    # no_thinking_params:            # how to say "don't reason" to that server
    #   chat_template_kwargs:        # (default: the Qwen dialect, vLLM/mlx)
    #     enable_thinking: false
```

The selection reader receives text: dates, people and place names, and descriptions. A hosted reader sends that text to its provider. Images are sent to the LLM only with explicit `editorial.preparation.caption_provider: llm`; otherwise captions use their separately configured service. See [Privacy](https://sam-dumont.github.io/immich-memories/docs/run/privacy.md).

`enabled: false` stops requests even when a model and URL remain configured. Set it to `true` to use a reader. The default model is Gemma.

An empty `base_url` with `enabled: true` and `openai-compatible` or `ollama` runs llama.cpp
on native Linux or macOS. The Docker and Kubernetes app images need an external server.
Set a URL to use your own API server. `openai`, `anthropic` and `zai` fill a blank URL with their vendor endpoint and select its adapter and reasoning dialect; under `zai` the URL also picks the adapter (a
`.../api/anthropic` base takes the Messages route). Which dialect goes where, what `thinking` does
on each host, how `thinking_params` and `no_thinking_params` differ, and what batching pays are all
in [Providers and dialects](https://sam-dumont.github.io/immich-memories/docs/reference/llm-providers.md#providers-and-dialects), with links to dated measurements.

`thinking` has five settings. `disabled` never asks for reasoning. `low`, `high` and `max` run the
model in reasoning mode for title generation. Bulk reader, music mood and special-day calls use the non-thinking settings. `auto` sends no reasoning field and takes the host's default, which is where to
start on a host whose dialect you do not know. `true` and `false` still parse, as `high` and
`disabled`. Reasoning is refused alongside images whatever this is set to: reasoning over several
pictures is a measured runaway. Measured on the live endpoint, a thinking call ran 30-134 s where
the same model answered in 4-7 s without it, and needs a 4000-token ceiling to finish.

The `openai` preset sends `reasoning_effort: none` for `gpt-5.6-luna`, `gpt-6-luna` and their dated snapshots
on non-thinking calls. Older GPT-5 models keep `minimal`. An explicit setting wins over the preset.
A provider that rejects a reasoning value reports that error; it does not silently remove the
control and fall back to default reasoning. Only rejection of the parameter itself permits that
fallback.

`always_reasons` covers a reasoning model that bills its private thinking inside `max_tokens`, so
the budget the reader asked for its answer is the budget the thinking spends first. Measured on one
hosted API with the same 17 KB monthly read: 245 thinking tokens on the lightest model, 4,126 and
6,256 on two others and 13,469 on the heaviest, all returning HTTP 200 and an empty answer at the
reader's 4,000-token ask. Such calls now ask for the cheapest reasoning the host sells and add
16,384 tokens of room on top of the caller's cap, so the cap keeps meaning what it says about the
answer. The room is a ceiling, not a bill. It is learned from the first reply that reports reasoning
tokens and remembered per server and model; set `always_reasons: true` to spare that first call,
which otherwise comes back empty.

`reader_concurrency` limits independent reader jobs in flight (1 to 16). Independent episode-evidence
packs, the period account's calendar-month pages, event inventories and worthiness blocks
can overlap. Pages within an event and later dependent picks remain sequential. Scheduling
preserves prompt text, judgment keys and source ordering; batch delivery is configured separately.

The owned reader always serializes requests. For external servers, unset concurrency is read
from `base_url`: 1 for loopback, a private IP or a bare service name, 4 for a dotted DNS name
or public IP. A dotted LAN name still gets the hosted policy; set `reader_concurrency: 1`
for a server that cannot handle overlap. See
[Reader concurrency](https://sam-dumont.github.io/immich-memories/docs/run/config-file.md#reader-concurrency). A provider that
answers 429 pauses every reader in the run, each waiting a slightly different span.

`send_image_detail` sends OpenAI's optional `image_url.detail` field. Set it to `false` for strict
vision schemas that reject anything beyond `image_url.url`; the `zai` preset already does.

A provider's dialect can be declared up front instead of negotiated:

```yaml
advanced:
  llm:
    max_tokens_param: max_completion_tokens  # example; the default is max_tokens
    drop_params: [temperature]               # example; the default is []
    extra_params: {}                         # fields merged into every call
```

`max_tokens_param` and `drop_params` are read only on the OpenAI dialect, where the query layer
otherwise learns them from the provider's 400s and remembers the answer per server and model.
`extra_params` also applies on Ollama, where anything under `options` (`num_ctx`, `num_predict`) is
merged into Ollama's own options block rather than replacing it, and a `num_predict` you set there
wins over the reasoning room the run would otherwise compute.

Two settings shape what a prose request asks for:

```yaml
advanced:
  llm:
    structured_output: null   # default: select the mode by request type
    repetition_penalty: 1.0   # default: sent to a server on your own machine or network, and to Ollama
```

`structured_output` sends the JSON shape the request's parser reads as `response_format`
`json_schema`, or as Ollama's `format`. Left unset, it selects the mode for each request:

- Free-text questions, titles and period accounts keep their schemas on both local and hosted
  endpoints.
- Episode readings on your machine or private network use the shape written in the prompt.
  oMLX's constrained decoder can stall on that nested schema after an empty array, spending the
  completion budget before reaching the next required key. Hosted episode readings keep the schema.

Both modes can run against the same endpoint in one process. Set `true` or `false` to override
this selection for an endpoint. A provider that refuses schema mode is retried in its compatible
mode, and the run remembers the refusal. Answer-cache identities include the policy and the
request's effective schema, so changing modes cannot reuse an answer from the old policy.

`repetition_penalty` is sent because local servers default to 1.1 (oMLX, Ollama), which penalises
the repeated keys every JSON answer needs. It is never sent to a public host; a server of your own
that refuses it is asked again without it. Set it to `null` to leave the server's default.

One `llm` section supplies all model calls: titles, the selection reader, music mood, special days and optional LLM captions. `enabled: true` is required; naming a model or URL does not enable it. Move any former separate title-model settings into `advanced.llm`; that block is removed without a compatibility fallback.

## Triage heads

```yaml
advanced:
  triage:
    encoder: ~/.immich-memories/models/triage/dinov2-small.onnx  # DINOv2-small ONNX export (88 MB)
    encoder_url: https://github.com/...    # where `models fetch` downloads that export from
    provider: auto                 # ONNX Runtime provider for the encoder: auto, cpu, cuda, coreml
```

`provider: auto` takes CUDA where that provider is present and CPU everywhere else. CoreML is opt-in. The provider is operational and does not enter the encoder key, so switching providers does not invalidate matching facts.

Editorial preparation uses `triage.encoder` with the public eight-head bundle from
`editorial.preparation.head_bundle`, and checks its digest on load. Missing required head facts
stop selection.

## Editorial planner

```yaml
advanced:
  editorial:
    thin_model_layer: true         # the model polishes a rules draft; false makes it plan the film
    strict_sharing: true           # anything a head or exposure flag marked stays out of shared films
    annotation_database: ""        # compatibility field; leave blank for the default cache directory
    # Apple silicon defaults below; elsewhere the ONNX archive and threshold 0.185 are used.
    laya_checkpoint: "~/.immich-memories/models/laya/laya-audience-a79ad9fa.tar"
    laya_checkpoint_url: "https://github.com/sam-dumont/immich-memories/releases/download/models-v2/laya-audience-a79ad9fa.tar"
    preparation:
      caption_provider: smolvlm    # llm explicitly opts into images sent to advanced.llm; higher cost
      caption_base_url: http://localhost:8092/v1
      caption_artifact_id: ""   # optional artifact/revision label; existing captions stay banked; at most 512 characters
      caption_api_key: ""          # bearer token for a caption server that requires one
      caption_timeout_seconds: 90   # positive seconds
      caption_concurrency: 1        # 1-16; raise it for a captioner on a GPU
      head_bundle: ""              # packaged public eight-head bundle
      detector_python: ""          # current Python interpreter
      detector_cache_dir: ""       # normal Hugging Face Hub cache
      marqo_onnx: ~/.immich-memories/models/detectors/nsfw-marqo-384.onnx  # digest-pinned sensitive-content export
      marqo_onnx_url: https://github.com/sam-dumont/immich-memories/releases/download/models-v1/nsfw-marqo-384-924658f1.onnx
      allow_model_downloads: false
```

In YAML, place this section under `advanced:`.

Close family from the people registry (partner, child, parent) reach the selection in two ways:
one seat for a close family member the draft left out, see
[the family seat](https://sam-dumont.github.io/immich-memories/docs/reference/selection-internals/family-audience-duplicates.md#the-family-seat), and the
weight of a story that is dense and mostly close family, see
[editing without a language model](https://sam-dumont.github.io/immich-memories/docs/reference/selection-internals/moments-and-stories.md#how-much-a-story-weighs).
Both use thresholds measured on real months; they are not settings.

Docling uses `det-v2`, because ONNX layout optimization mislabels documents on the Celeron J4125.
Saved `doc_docling: det-v1` settings upgrade on load, and the next run recomputes that head's facts
and refreshes dependent readings; other head facts stay reusable.

`nsfw_marqo` uses `det-v3`, which reads a video on up to eight frames across its length rather than
on the single early frame Immich serves as its preview, and keeps the strongest answer. A still is
read exactly as `det-v2` read it, so saved `det-v1` and `det-v2` settings upgrade on load, a still
keeps its banked `det-v2` answer as its `det-v3` one, and the next run recomputes that head for
videos only. Everything else it banked stays reusable.

`frame_kind`, `screen` and `uncovered_person` were distilled from a typed picture reader onto the
same encoder the other five heads run on, so a library prepared before they existed is owed only
their three rows and keeps everything else it banked. `public-v1-strict` says `screen` ships at one
strict band, baked into its coefficients because the bundle schema holds no threshold: at that band
it answered `yes` on 37 of 3,564 photographs and every one of them was a screen. Each of the three
only adds to a rule another producer already answered, and none of them can clear anything.

The top-level [`tier`](#tier) picks the reader: rules on `basic` and `gpu`, a model on `full`.
Rules cover the ten standard memory products, including albums and recurring dates,
from dates, places, favourites, people metadata and whatever preparation facts exist. They reuse
the normal allocation, spacing, audience and timing checks, write a one-line summary made only of
the film's story names, keep unsampled Live
Photos as stills, and write no semantic model banks. Saved plans identify the producer as
`rules-v1`. A custom `--start`/`--end` range is cut the same way as a month or a year.

### The thin model layer

`thin_model_layer` decides what a model install spends its calls on. On (the default), the cut is
built by the rules reader, with no model at all, and the model is then asked one closed question
over the finished film: which of these shots adds nothing to it? What the answer and the gates
leave open is refilled from the same stories, and nothing else moves.

It needs a period the library holds an account of, which cataloguing writes:
`immich-memories prepare --overviews` banks one per calendar month, and a cut of a whole month or
year that finds none writes its own from the readings it has just paid for. Any other single
window (a season, a trip) is its own period and writes its own account the same way. Films over several windows also use the rules draft and refinement by default. `false` makes the model plan
the whole film even when an account exists.

`strict_sharing` keeps any picture a detector head or an exposure flag marked out of a shareable
film. Only your own clearance on the picture can lift a detector or exposure hold.
It is also what lets Basic without captions cut a shareable film at all: with it on, a picture every
active head or detector read as clean and nothing flagged is `share`; with it off, Basic clears
nothing. Just-us
and family films are unchanged. Turning it off does not let a caption clear an exposure flag.

On `tier: gpu` and `tier: full`, a local Laya model answers the sharing question; and `immich-memories models fetch` downloads it.
Apple Silicon uses `laya-mlx`; Linux, Windows and Intel Macs use the portable ONNX checkpoint with the appropriate editorial runtime.

| Platform default | Checkpoint under `~/.immich-memories/models/laya/` | Hold threshold |
| - | - | - |
| Apple Silicon | `laya-audience-a79ad9fa.tar` | 0.186 |
| Other platforms (ONNX) | `laya-audience-onnx-90420ef3.tar.gz` | 0.185 |
| A missing checkpoint or runtime | | |
| is reported, and the run continues with the conservative rules fallback. | | |
| It reads the compact caption and adds holds; detector and rule holds still apply and | | |
| are never lifted. It works with the rules reader as well as the prose reader. A captioned shot | | |
| without a Laya answer stays held to the family. Sharing never calls an LLM, including exposure | | |
| checks and missing-answer fallbacks. The former `thin_batched_audience` option is removed. | | |
| See [Add a reader](https://sam-dumont.github.io/immich-memories/docs/reference/llm-providers.md#the-laya-audience-pre-screen). | | |

### Preparation tiers

Preparation follows the product tier. Basic acquires pixel facts and the eight shared-DINO heads.
GPU and Full add Marqo, Docling, captions and Laya. Every producer identity is kept, while the
active view filters out Marqo and Docling on Basic. Banked facts remain available when you switch back.
Saved review decisions and permanent holds persist across tier changes.

A film starts with a caption-free rules draft, retaining the resolved tier's detector policy, then
captions and checks only selected shots and actual
replacement candidates. `prepare` remains the explicit job for a larger scope. Changing tier
does not erase banked captions or other producer facts.

The sharing level decides what a caption reading refuses. A caption describing a shirtless baby or a parent holding a newborn in hospital does not, by itself, cause an activity-based hold. Other detector and selection rules still apply. Bath time,
breastfeeding, a nappy change and intimate hygiene play only in a just-us film. Graphic medical
procedures, sexual content, exposed adult changing and identifying records never play.

Preparation fills missing descriptions, public heads, detectors and pixel measurements in the
annotation database, and skips provider calls where the facts are complete. Missing previews or
providers stop selection with an explicit incomplete result. See
[Add captions](https://sam-dumont.github.io/immich-memories/docs/better/captions.md) for the caption endpoint requirements and
[Inference on a GPU box](https://sam-dumont.github.io/immich-memories/docs/better/inference.md) for the model artifacts.

## Inference service

```yaml
advanced:
  inference:
    facts_base_url: ""          # blank: the heads and detectors run in the app process
    timeout_seconds: 60         # one picture, one request; the service answers all producers at once; greater than 0, at most 300 seconds
    facts_concurrency: 8        # how many of those requests are in flight at once (1-32)
    producers: [heads, nsfw_marqo, doc_docling, obstruction]   # what the service answers for; the rest stay local
    fallback_to_local: true     # when the service cannot be reached, run the in-process producers
```

Point `facts_base_url` at a running [inference service](https://sam-dumont.github.io/immich-memories/docs/better/inference.md)
(`http://immich-memories-inference:8092` in the Compose profile;
`http://inference:8092` in Kubernetes) and `prepare` and `generate` send each picture's
preview there once and bank what comes back. The row is the same row the in-process producers
write: same head, version, label and encoder key, because the service runs the application's own
producers and the key is computed over the model artifact, never over where it ran. Change the
provider or the host and nothing is re-derived.

`producers` narrows what is offloaded. `[heads]` sends the DINOv2 encoder and the eight context heads
and keeps Marqo and Docling in the app when the tier enables them. Offloading does not
enable producers disabled by the tier. `obstruction` is the finger-over-the-lens check: it reads
the same encoder call as the heads, so the service answers both off one pass. Leave it out, or
run a service older than the app, and the app runs the encoder for it locally.

`facts_concurrency` is how many pictures are in the air at once. One at a time, measured on a
cluster against a T1000, costs 0.69 s a picture whatever the card is doing, because almost all of
it is the round trip: 3,709 pictures took 42.7 minutes, and a 13,552-picture year would have taken
2.6 hours. Answers are banked in the order the pictures were asked for, so raising this re-derives
nothing. Raise it until the service is the slow half; the ceiling is 32, and the service's own
`REQUEST_THREADS` decides how many it can answer at once.

When the service does not answer, the failure is recorded against the endpoint in the preparation
report, and with `fallback_to_local: true` the in-process producers take over for the pictures
still missing facts (which needs the model files from `models fetch` on the app box). With it off,
configuration loading fails with `Cannot verify the required inference service's compute` when
the service is unreachable. This can stop any command before it starts, including `preflight`;
restore the service or turn local fallback on.

## Free-text requests

```yaml
advanced:
  free_text:
    wordnet: ~/.immich-memories/models/wordnet/wordnet.zip   # WordNet 3.0 (11 MB)
    wordnet_url: https://raw.githubusercontent.com/...       # where `models fetch` gets it
```

A film asked for in a sentence (experimental, being built) looks the request's words up in
WordNet: is "cat" a thing, is "park" a place, is a town's name also an ordinary word. The corpus is
a model file like the others: `models fetch` downloads it from a fixed commit of `nltk_data` and
checks its SHA-256, and a run that finds it missing stops and says to run `models fetch`. Nothing
fetches it while a film is being made.

## Title screens

```yaml
title_screens:
  enabled: true                  # Opening title, month dividers and ending screen
  locale: "auto"                 # en fr nl de es it pt-BR pt-PT pl sv ru ja zh-Hans ko, or auto
  style_mode: "auto"             # auto (mood-based), random, or a named preset
  # Named presets: modern_warm, elegant_minimal, vintage_charm, playful_bright, soft_romantic
  fade_color: "white"            # white or black at the opening and closing
  animated_background: true      # Animated titles and smooth map flights
  show_month_dividers: true      # When the video spans several months (all-or-none)
  use_first_name_only: true      # "Riley" instead of "Riley Smith" in titles
  llm_titles: false              # Experimental: the reader names special days and writes the summary
```

`llm_titles` is experimental and off by default. With a [text reader](https://sam-dumont.github.io/immich-memories/docs/better/reader.md)
configured and this on, the reader names special days and writes the film's summary, the second
half of its Immich description. The results miss too often for now: the
[planned rework](https://github.com/sam-dumont/immich-memories/issues/2594) tracks it. Off, every film gets the app's own title, no summary,
and its Immich description is the title. `--llm-title` and `--no-llm-title` decide for one run.

`fade_color` chooses the opening and closing fade. `animated_background` controls movement;
the colour palette and custom fonts are not configurable today.
`animated_background: false` keeps the gradient still (no rotation, colour pulse or vignette pulse)
and uses three-view map journeys, which is what `preset: fast` selects. The
`immich-memories titles` command exposes more of the look as flags for previewing.

## Trip detection

```yaml
trips:
  homebase_latitude: 0.0
  homebase_longitude: 0.0
  min_distance_km: 50  # at least 1 km
  min_duration_days: 2  # at least 1 day
  max_gap_days: 2  # at least 1 day
```

## Outside calls

Every switch here is off. A run with both off reaches your Immich server, the endpoints you
wrote down yourself, and nothing else.

```yaml
network:
  geocoding: false        # nominatim.openstreetmap.org
  geocoding_url: ""       # a self-hosted Nominatim instead of the public one
  map_tiles: false        # server.arcgisonline.com (World Imagery)
```

| Key | What it sends | What you get |
| - | - | - |
| `geocoding` | each trip cluster's centroid, and the coordinates of the pictures in the film's window, rounded to about a kilometre, once per place (answers are kept in the store) | the city or village where Immich names a district or neighbouring town, on every name you read (story titles, captions, location cards, map stops, the report), trip names from the map instead of from EXIF, and place names in the film's language |
| `geocoding_url` | the same requests, to this host instead (`http://nominatim.lan:8080`); empty means `nominatim.openstreetmap.org`. Only read with `geocoding: true` | your own Nominatim, nothing sent outside |
| `map_tiles` | tile coordinates covering the trip area and your home base | the trip fly-over, the static trip map, and a satellite background behind location cards |

Fonts are not a switch: a render never downloads one, and `titles fonts --install` is the one
step that does ([Fonts](https://sam-dumont.github.io/immich-memories/docs/run/privacy.md#fonts)). `preflight` prints a row
for each switch you turn on, naming the host it will contact.

## Update check

Off by default. The button in Settings and `immich-memories version --check` need no setting:
they ask when you do.

```yaml
updates:
  check_daily: false      # api.github.com, at most once a day
```

| Key | What it sends | What you get |
| - | - | - |
| `check_daily` | one anonymous request for the public release list, at most once a day; no version, install id or setting goes with it | a dismissible banner in the web app and one line in the run log when a newer release is out |

Stable installs are offered stable releases. A release candidate is offered newer candidates and
stable releases. A nightly build is offered the next stable release. See
[Updates](https://sam-dumont.github.io/immich-memories/docs/run/reference/privacy-egress.md#update-check) for the request.

## Cache

```yaml
cache:
  directory: "~/.immich-memories/cache"
  database: "~/.immich-memories/cache.db"
  video_cache_enabled: true      # Cache downloaded videos locally
  video_cache_max_size_gb: 10.0  # Max disk usage for video cache (1-500 GB)
  video_cache_max_age_days: 7    # Auto-delete cached videos older than this (1-365)
  thumbnail_cache_max_size_mb: 30000.0 # Max disk for Immich previews (50 MB-100 GB)
  editorial_runs_max_size_gb: 5.0 # Max disk for past cut attempts in editorial-runs (0.5-500 GB)
```

Tight on disk: lower `video_cache_max_size_gb`, or turn it off with `video_cache_enabled: false`.

`editorial_runs_max_size_gb` caps `editorial-runs/`, where every cut keeps its plan, frames and
records. Each run start trims it, oldest first: failed, cancelled and replaced attempts go before
the ones a run in `runs list` points at, which `runs story`, `runs why` and `runs render` read.
A running cut, the newest attempt of each memory and anything from the last 24 hours always stay;
when those alone are over the budget, the run logs a warning naming this key.

### Size the thumbnail cache by your library

`thumbnail_cache_max_size_mb` is the one cache budget that scales with the library. Every candidate asset in a memory's scope gets an Immich preview fetched and read back several times. Measured on a real library, one preview is about **315 KB**, so:

```text
budget in MB ≈ 0.35 × (assets a memory's scope can reach)
```

A scope of ten thousand candidates wants about 3.4 GB; the `0.35` leaves a little headroom over the measured 0.315 MB. A year, a lifetime or a captioning pass can reach the whole library: two real installs held 16 GB for 50,600 previews and 19 GB for 57,116. The 30 GB default holds about 90,000 previews; past that, the run warns and names this key.

If the run's working set does not fit, nothing is lost mid-run: previews still in use are never deleted and the cache overflows the limit instead. The *next* run reclaims them, so the next overlapping memory re-downloads every preview. You get one `WARNING` per run saying how far over you are. Raise it rather than ignoring it.

The video cache is not library-sized: it holds the originals being assembled, tens of files per run however big your library is. An old config that still sets `preview_cache_max_size_mb` loads with a warning; it has no effect.

## Store database

Where the store lives: owner decisions, the people registry, model answers, run history, automation
state, the special-days catalogue and the settings you edit in the UI.
`cache.database` only names a pre-store `cache.db` for the one-time import, and the directory
the run lock files sit in.

```yaml
database:
  url: "sqlite:///~/.immich-memories/store.db"  # or postgresql://user:${PGPASSWORD}@host/db
  schema: "immich_memories"                     # PostgreSQL only: the schema holding every table; non-empty
  import_from: ""                               # where the one-time import of pre-store files looks;
                                                # blank = ~/.immich-memories
```

`IMMICH_MEMORIES_DATABASE_URL`, `IMMICH_MEMORIES_DATABASE_SCHEMA` and `IMMICH_MEMORIES_IMPORT_FROM`
beat the file. All three are read
before the store opens, so the UI can never change them. SQLite on local disk is the default and
fits a single-host install; point `url` at PostgreSQL 14+ (no extensions) to share a server,
including Immich's own, in a schema of its own. A SQLite file on NFS, SMB or CIFS is refused:
see [Environment variables](https://sam-dumont.github.io/immich-memories/docs/run/reference/environment.md#not-config-keys).

## Server (UI)

```yaml
advanced:
  server:
    host: "127.0.0.1"             # Explicit local bind; YAML 0.0.0.0 is ignored (see below)
    port: 8080                     # Listen port (1-65535)
    enable_demo_mode: false        # Offer the Demo mode (blur) switch in the web top bar
    secure_cookies: false          # Mark the session cookie Secure (turn on behind an HTTPS reverse proxy)
    trigger_token: ""              # Shared secret for POST /api/trigger. Empty, and with auth
                                   # off, the trigger API is not served at all
    allowed_hosts: []              # Hosts answered beyond localhost. Auth off: any other
                                   # Host gets 421. Auth on: empty answers any host, set
                                   # answers only these (and localhost, auth.public_url)
    music_upload_quota_mb: 1024    # Room for uploaded soundtracks; the oldest go past it
```

`allowed_hosts` is how an unauthenticated LAN install, or a caller that uses another name (a
Kubernetes Service, a NAS hostname), is let in. See
[Allowed hosts](https://sam-dumont.github.io/immich-memories/docs/run/network-security.md#allowed-hosts).

`host` and `port` also have CLI flags: `immich-memories ui --host 127.0.0.1 --port 9090`.
A YAML `server.host: 0.0.0.0` is ignored: older versions saved that value automatically.
Native installs bind to `127.0.0.1` unless you pass `--host` or set `server.host`. For LAN
access, keep sign-in on, or put the app behind your own proxy with
[header sign-in](https://sam-dumont.github.io/immich-memories/docs/run/authentication.md#trusted-header-reverse-proxy).
The Docker image already passes `--host 0.0.0.0`; its host port mapping controls reachability.
Unauthenticated LAN requests also need the hostname in `server.allowed_hosts`.
See [Network and security](https://sam-dumont.github.io/immich-memories/docs/run/network-security.md) before changing it.

`trigger_token` turns on the HTTP trigger: one POST that runs whatever `auto run` would have
decided, so an Immich workflow (or a cron, or a phone shortcut) can start a memory. See
[Trigger from Immich or anything else](https://sam-dumont.github.io/immich-memories/docs/make/automate.md#trigger-it-over-http).
Keep it out of `config.yaml` with `IMMICH_MEMORIES_SERVER__TRIGGER_TOKEN`: `server` does not expand
a `${VAR}` reference, so writing one here stores the six literal characters as your token. Either
way the value is redacted from `/health`, the config viewer and the logs, from config load onwards.

Saving settings does not write `config.yaml`. Set a LAN bind deliberately; otherwise the secure default is localhost.

## Upload to Immich

```yaml
upload:
  enabled: false
  album_name: null               # Created if missing, reused if exists
                                 # enabled and album_name cover manual and automatic films
  film_tags: false               # Tag each film with its type, years and stories
```

Each uploaded film gets a description in Immich: its title and subtitle, then its story summary.
With `film_tags: true` it is also tagged under `immich-memories/`: `type/` (Monthly highlights,
Trip, ...), `year/` for each year its pictures come from, and `story/` for each birthday, visit or
trip it shows, so you can find every trip film or every film of a year from Immich's tag list. A
birthday film that looks back five years but has no picture from two of them gets three year tags. The
`immich-memories/generated` tag is always set: it is how a later run recognises its own films.

An uploaded memory is filed on the day of its last picture, in the timezone most of its pictures
share, so it lands in your timeline where the memory ends instead of on the day it was rendered.
The render day is what you get when no picture in the cut carries a usable time.

## Automation

Controls what `immich-memories auto suggest` and `auto run` detect and generate. See [Automate it](https://sam-dumont.github.io/immich-memories/docs/make/automate.md) for the commands. In YAML, place this section under `advanced:`.

```yaml
advanced:
  automation:
    enabled: false                  # run the daily auto-run decision inside the web UI process (Docker)
    daily_at: "09:00"               # HH:MM, local time of that process (container TZ)
    cooldown_hours: 24              # min hours between auto-generated memories (1-168)
    max_delivery_attempts: 5        # give up on an Immich upload after this many failures (1-50)
    detect_monthly: true            # monthly highlights candidates
    detect_yearly: true             # year-in-review candidates
    detect_trips: true              # GPS trip detection (needs homebase coords)
    detect_person_spotlight: true   # per-person highlight candidates
    detect_activity_burst: true     # unusually active months
    special_days_per_year: 6        # days a year discover-days keeps without a model, strongest first; 1-100
    accounts: []                    # accounts automation reads, as generate --accounts does: list
                                    # primary too, e.g. ["primary", "partner"] (default: primary alone)
    detect_groups: true             # propose last year's film for each saved people group
                                    # (people group add) whose people have pictures
    detect_seasons: true            # the season that just ended (needs the home base for its hemisphere)
    detect_holidays: true           # a holiday film when the day stands out in your pictures
    detect_albums: true             # a new Immich album, or one that has grown
    detect_person_monthly: true     # last month's film of each person close to you
    backfill_months: true           # months of this year and last that never got a film, on quiet nights
    extra_holidays: []              # days of your own to film as holidays, each "MM-DD: name"
    include_shared_albums: false    # also propose albums other people shared with you
```

`accounts` and saved groups are the automation side of
[a second Immich account](https://sam-dumont.github.io/immich-memories/docs/run/multi-account.md): the daily scan reads the listed accounts the
same way a manual `--accounts` run does, one `/users/me` check per account, and a read that fails
on any of them fails that day's discovery instead of proposing a film from half a household. The
list is exactly what is read, so keep `primary` in it: `["partner"]` alone leaves the primary
library, and trips, out.

## Authentication

Protects the web UI. See the [Authentication guide](https://sam-dumont.github.io/immich-memories/docs/run/authentication.md) for provider-specific setup (OIDC examples, header proxy config, etc.).

```yaml
advanced:
  auth:
    enabled: false
    provider: basic                # basic, oidc, or header
    session_ttl_hours: 24          # 1-720
    public_url: ""                 # e.g. https://memories.example.com -- the URL users use to reach you
                                   # on. Pins the OIDC redirect_uri and enables callback-origin
                                   # validation; without it no origin check is performed

    # Basic auth
    username: ""
    password: ""                   # Supports ${ENV_VAR} expansion

    # OIDC / SSO
    issuer_url: ""                 # Auto-discovers via /.well-known/openid-configuration; supports ${ENV_VAR}
    client_id: ""                  # Supports ${ENV_VAR} expansion
    client_secret: ""              # Supports ${ENV_VAR} expansion; empty for public clients
    scope: "openid email profile"
    allowed_emails: []             # OIDC: addresses that may sign in. Empty = anyone the IdP
    allowed_domains: []            # authenticates. Domains match exactly: example.com does
                                   # not admit sub.example.com
    auto_launch: false             # Skip login page, redirect straight to IdP
    button_text: "Sign in with SSO"

    # Trusted header (reverse proxy)
    user_header: "Remote-User"
    email_header: "Remote-Email"
    trusted_proxies: []            # IPs/CIDRs of your proxy. Required for header provider;
                                   # for basic/oidc their X-Forwarded-* headers are trusted
```

Place under `advanced:` in your config file (like all Tier 2 sections).

## Notifications

Get notified when auto-generation or scheduled jobs complete. Uses [Apprise](https://github.com/caronc/apprise) (130+ services: ntfy, Discord, Telegram, Slack, email, webhooks). Apprise ships with the base package, no extra to install. In YAML, place this section under `advanced:`.

```yaml
advanced:
  notifications:
    enabled: false
    urls: []                        # No destinations by default; add your own Apprise URLs
    on_success: true                # notify on successful generation
    on_failure: true                # notify on failed generation
    attach_thumbnail: false         # opt in; attachments cost bandwidth/provider quota
    cooldown_hours: 24              # pause normal attempts after a delivery failure (1-168)
```

For example, set `advanced.notifications.urls: ["ntfy://your-ntfy-host/private-topic"]` and
`advanced.notifications.enabled: true`. Replace the host and topic with your own destination.

Delivery failures are stored as sanitized health state. Normal success and failure
notifications pause during the cooldown instead of hammering a quota-limited provider. The
pause ends up to three hours early (at most half the cooldown), so a one-day cooldown never
swallows the next day's notice. Each URL is tried on its own: one dead destination does not
pause the others, and a notice that reached at least one of them counts as delivered.
`auto test-notification` always bypasses the cooldown and a successful test clears it.
Provider URLs, credentials, and response bodies are never included in health output.

Test your config: `immich-memories auto test-notification`
