# Immich external library to albums

This script creates Immich albums from the directory names in an external
library and adds the corresponding assets to them. It does not move or modify
the original files.

For example, with:

```text
EXTERNAL_ROOT=/mnt/nextcloud-photos
ALBUM_MODE=root
```

the asset:

```text
/mnt/nextcloud-photos/Korea_2016_07_08/photo.jpg
```

is added to an album named `Korea_2016_07_08`. Files in nested directories
below `Korea_2016_07_08` are added to the same album.

## Configuration

Required environment variables:

- `IMMICH_URL`: Immich server URL, for example `http://immich-server:2283`
- `IMMICH_API_KEY`: API key with `asset.read`, `album.read`,
  `album.create`, and `albumAsset.create` permissions
- `IMMICH_LIBRARY_ID`: ID of the external Immich library

Optional environment variables:

- `EXTERNAL_ROOT`: Path stored in Immich's `originalPath`; defaults to
  `/mnt/nextcloud-photos`
- `ALBUM_MODE`: `root` (default), `leaf`, or `relative`
- `ALBUM_SEPARATOR`: Separator for `relative` mode; defaults to ` - `
- `PAGE_SIZE`: Immich search page size; defaults to `1000`
- `DRY_RUN`: Set to `true` to log planned work without changing albums
- `SYNC_INTERVAL_SECONDS`: Delay between runs; `0` runs once and exits.
  Docker Compose defaults to `1800` seconds (30 minutes)

Run the script after Immich has scanned the external library:

```bash
uv run python src/main.py
```

## Docker Compose

Copy the example configuration and insert your Immich API key and external
library ID:

```bash
cp .env.example .env
docker compose up --build
```

The example starts with `DRY_RUN=true`. Check the output, then set
`DRY_RUN=false` in `.env` and run `docker compose up` again.

When Immich publishes port `2283` on the same Docker host, use:

```text
IMMICH_URL=http://host.docker.internal:2283
```

For an Immich server on another machine, use its normal HTTP(S) URL instead.
The photo directory does not need to be mounted into this container:
`EXTERNAL_ROOT` is matched against the path recorded in Immich's
`originalPath` field.

The Compose service stays running and synchronizes every 30 minutes. Change
`SYNC_INTERVAL_SECONDS` in `.env` to use another interval. The delay starts
after a synchronization finishes. Temporary API errors are logged and retried
on the next scheduled run.

The script only adds missing assets. It never removes assets from albums and
never deletes albums.